fix(watch): honor scope when storing and looking up watch state #10

Summary

add --watch/--watch-only accepts --scope user, but the watch ledger remains tied to the current project directory. Watch listing likewise accepts --scope but reads the same project-local ledger.

The behavior is confirmed, but current documentation explicitly describes watch state as project-local. This issue requests a scope-consistent contract rather than claiming a regression from a documented user-scope implementation.

Code evidence at b742a99:

• Sources/CLI/AddCommand.swift:9,48 accepts and passes scope.
• Sources/Core/RuntimeService.swift:228–231 resolves explicit watch sources without passing scope, using SourceResolver's project default.
• Sources/Core/RuntimeService.swift:284–291 upserts watches without scope.
• Sources/Core/WatchLedger.swift:237–269 always loads/saves projectDirectory/.agent/skills-state.json.
• Sources/CLI/ListCommand.swift:69–80 reads that ledger without using scope.
• Sources/Core/RuntimeService.swift:792–796 also fixes watch-install cache placement under the project.
• Documentation/Architecture/Package.md:214–215 explicitly states the project-local design.

Impact: a purported user watch is visible only from its original working directory. Project and user watch operations in one directory share identities, paths, and review state.

Reproduction

Proposed steps; not executed for this report.

1. Create a fresh temporary root containing project-a, project-b, and source/skills/demo.

2. Create source/skills/demo/SKILL.md with valid name: demo and nonempty description frontmatter.

3. From project-a:

   skill add <absolute-temporary-source-path> \
     --watch-only --scope user --agent codex --skill demo
   skill list --watch --scope user --json
   skill list --watch --scope project --json

4. Inspect project-a/.agent/skills-state.json.

5. From project-b, run:

   skill list --watch --scope user --json

The watch-only local-source case does not install skills into the real user skill directory.

Expected Behavior

Proposed behavior: user-scoped watches use user-scoped state and remain visible across project directories; project-scoped watches remain isolated.

The repository maintainer must decide the exact user-state path and migration policy. Existing project-local records do not contain a reliable scope distinction and should not be blindly moved.

If watch state is intentionally project-only, reject or clearly define --scope user on watch operations rather than silently presenting it as a watch-storage selector.

Completion checks after the contract is chosen:

• Verify visibility from two project directories.
• Verify separation between project and user watches.
• Cover list, status, diff, review, remove, and watched installs consistently.
• Match cache placement to the accepted scope model.
• Preserve existing review history during any migration.
• Run swift test.

Actual Behavior

The record is stored in project-a/.agent/skills-state.json. Both scope values list the same watch from project-a. The user-scoped listing from project-b cannot see it.

The current implementation and project-local documentation agree with each other; the inconsistency is between the accepted CLI scope surface and the requested user-watch behavior.

No duplicate issue or fixing PR was found. Issue #4 is unrelated.

Environment

• skill version: 0.2.1.
• Source inspected: b742a99.
• Swift version: not obtained in the read-only sandbox.
• OS: macOS 27.0.1 (26A434).
• Architecture: arm64.
• Validation: static inspection only; reproduction not executed.

Decision needed

Choose the watch scope contract: support real user-scope watches, which needs a storage location and a migration plan, or keep watches project-local and reject or explain scope arguments that do not apply.