# Fail closed for unknown Cursor plugin IDs

## Traceability

- Spec ID: U-01
- Story: roadmap.md TODO U-01
- Status: Implemented

## Intent

Prevent Cursor installed-plugin records with unknown numeric or opaque IDs from
being assigned to unrelated cached plugins. Installed status must come only from
direct plugin-manifest IDs or workspace-bound project MCP evidence, so cache
enumeration and display-name order cannot change which plugin is reported as
installed.

## Acceptance Scenarios

- **U01-AC-1 (unknown IDs fail closed):** Given one or more installed-plugin
  records whose IDs match neither a cached plugin's `cursorPluginId` nor a
  project MCP hint, the inventory reports no cached plugin as installed and
  lists every unknown record ID in `unmatchedInstalledPluginIds`.
- **U01-AC-2 (order invariance):** Reordering cache candidates without reliable
  IDs does not change the installed-plugin inventory or attach an unknown
  record's sources, scope, or install metadata to any candidate.
- **U01-AC-3 (direct ID evidence):** A record that directly equals a cached
  plugin's `cursorPluginId` remains installed with `installMatch: "id"` and
  preserves install-record order.
- **U01-AC-4 (project MCP evidence):** A record mapped by a workspace-bound MCP
  tool snapshot remains installed with `installMatch: "project-mcp"`.
- **U01-AC-5 (diagnostic compatibility):** Existing diagnostic field names
  remain available. `installedPluginFallbackCount` remains numeric and is zero
  because cache fallback assignment is no longer allowed; the matching summary
  clearly distinguishes fully matched records from records left unknown.

## Non-goals

- Change Cursor capability declarations, session evidence, checkup behavior, or
  report routing.
- Infer plugin identity from cache order, display name, cache path position, or
  numeric-ID shape.
- Add new Cursor data sources or decode undocumented state.
- Change roadmap items other than U-01 or broaden another Cursor capability
  claim.

## Plan and Tasks

1. Add focused provider regressions for unknown IDs and cache-order invariance,
   while retaining direct-ID and project-MCP positive coverage.
2. Run the focused regression against the pre-fix provider and record that the
   cache fallback behavior fails the new assertions.
3. Remove cache-order fallback assignment from
   `scripts/agent-customize/providers/cursor.mjs`; preserve existing diagnostic
   keys and report unmatched records explicitly.
4. Update the Unreleased changelog entry because installed-plugin inventory is
   observable provider behavior.
5. Mark roadmap U-01 complete and align its Cursor inventory description with
   the implemented evidence boundary.
6. Run focused provider tests, documentation link integrity, full tests,
   package verification, and whitespace checks. Record any environment-specific
   limitation without weakening the acceptance criteria.

## Test and Review Evidence

- **U01-AC-1/U01-AC-2:** focused assertions in
  `test/agent-customize.test.mjs` use plugins without manifest IDs and compare
  inventories across reversed cache names/order. Before implementation these
  must fail by exposing `cache-fallback` assignments.
- **U01-AC-3:** the existing direct-ID install-order test must continue to pass.
- **U01-AC-4:** the existing project MCP numeric-ID hint test must continue to
  pass.
- **U01-AC-5:** focused assertions verify a zero fallback count, preserved
  unmatched IDs, and diagnostic text that says unknown records remained
  unmatched.
- Provider gate: `node --test test/agent-customize.test.mjs`.
- Documentation gate: regenerate the routing graph with
  `node scripts/doc-link-graph/cli.mjs skills/better-harness`, then run
  `node --test test/doc-link-graph.test.mjs`.
- Regression gates: `npm test`, `npm run pack:verify`, and `git diff --check`.
- Primary risk: downstream consumers may have treated heuristic plugin entries
  as installed. The safe compatibility boundary keeps diagnostic keys and
  direct/hinted matches intact while deliberately removing unproven entries.
- Review readiness must confirm the diff is limited to the Cursor provider,
  focused tests, this spec, U-01 roadmap declarations, generated documentation
  routing if changed, and the changelog.

### Observed Evidence (2026-07-30)

- Pre-fix regression: the two new focused tests failed 0/2. The old provider
  assigned ID `9001` to `Future Tool` and assigned two unknown records to cache
  candidates including `Alpha Without Id` and `Hex`.
- Provider plus architecture gate:
  `node --test test/agent-customize.test.mjs
  test/agent-customize-architecture.test.mjs` passed 33/33 after rebasing
  onto `origin/main` at `686e1aa`, including direct-ID, project-MCP,
  unknown-ID, and cache-order cases.
- Documentation gate: the graph generator reported 34 files and 50 links; the
  generated graph had no semantic diff because this spec is not in the
  `skills/better-harness` routing chain. The doc-link suite passed 6/6.
- Full regression: `npm test` ran 980 tests: 973 passed, 4 failed, and 3 were
  skipped. The four failures are environment-specific Windows `EPERM`
  failures while creating symlinks in
  `test/core-change-watch-scope.test.mjs`,
  `test/harness-report-render-cli.test.mjs`, and
  `test/workspace-topology.test.mjs`; a focused rerun reproduced the same four
  failures without any Cursor provider failure.
- Package gate: `npm --cache .npm-cache run pack:verify` passed with 333 npm
  entries and 356 runtime ZIP entries. The temporary cache was removed
  afterward.
- Environment limitation: Node `v22.17.0` and npm `10.9.2` are below the
  repository minimums of Node `22.20.0` and npm `10.9.3`.
- `git diff --check` passed before this evidence update and is rerun during the
  final readiness check.