feat: legacy-install migration + S9 agent-discipline fixes (v5.4.0 prep)

[lwalden]

Summary

Five parts, one per commit — legacy-install migration plus the agent-discipline fixes from the dungeon-game S9 retrospective.

Origin story

dungeon-game (initialized at AAM v4.5.0, pre-plugin) ran sprints S6–S9 on the plugin while stale file copies sat in .claude/agents/ + .claude/scripts/ and duplicate hook registrations in project settings fired twice per event. S9's retro also surfaced two process gaps that belonged at the distributed layer, not in per-sprint prompt instances: (a) per-item reviewFindings metrics read 0 despite real judge findings — nothing ever set the field; (b) GUI-subsystem executables (Unity.exe on Windows) return immediately from naive shell invocation, so backgrounded test runs died when executor turns ended (3h28m lost on one S-sized item).

1. bin/sprint-metrics.sh — review-findings subcommand (bcfcb38)

Set-not-increment semantics (idempotent on judge re-runs); validates a non-negative integer; unknown item ids leave the file untouched. 6 new tests.

2. agents/sprint-master.md — wire the metric + docs-only precedent (dd323b2)

TEST state now records the ACCEPTED finding count (critical+high+medium+low from the judge's JSON summary) via sprint-metrics.sh review-findings after every judge pass, including clean passes. Docs-only diffs skip code lenses and route straight to quality-reviewer for a claim-accuracy judge pass (the S7-001/S9-004 field precedent), recorded the same way. Condensed the duplicated PLAN/SPEC checkpoint procedure to stay under the 200-line orchestrator cap (now 199).

3. Long-Running Operations sections — item-executor + pr-pipeliner (7f318d0)

Stack-agnostic: mandatory use of the project's canonical .claude/scripts/run-*-tests.* runner seam when one ships; never background a long-running test/build run or end a turn with one in flight (poll in the SAME turn); foreground CI watching (gh run watch --exit-status, bounded timeout); push at every durable boundary. pr-pipeliner additionally: "ci-pending: {run_id, head_sha}" output contract with sprint-master picking up the gate, and one immediate retry on transient gh 401s.

4. Legacy migration — strip-retired-hooks.sh migrate → bin/legacy-migrate.sh (a8bbd08)

• Manifest-driven: only filenames AAM has ever shipped (historical pre-5.0 names + current payload, enumerated live from the plugin's agents/ + bin/) are candidates. Everything else under .claude/agents/ / .claude/scripts/ is user property — never touched (verified against the real dungeon-game layout, incl. its user-owned run-editmode-tests.ps1).
• Customization-safe: matches (or whitespace/CRLF-only diffs) retire; divergent candidates skip by default, --force-divergent overrides.
• Dry-run by default; --apply to act. Retirement MOVES files to .claude/legacy-retired-<UTC>/ — never deletes; files are git-tracked too, so doubly recoverable.
• Hook de-dup: removes project entries whose command basename matches a hook the plugin registers (read live from hooks/hooks.json, built-in fallback), plus retired hooks, via the existing surgical jq transform. statusLine stays project-level by design, but a legacy .claude/scripts/context-monitor.sh statusLine is repointed at the plugin copy so the file can retire. Scripts still referenced by surviving settings are kept.
• Investigated mechanism: plugin-namespaced agents invoke bare sprint-update.sh etc. because Claude Code puts the plugin's bin/ on the Bash tool's PATH while the plugin is enabled (README:96, customization-guide). No project shim needed post-migration; the guide's verify step checks command -v sprint-update.sh.
• Also fixes: correction-capture-hook.sh (retired v4.6) was missing from the retired strip pattern — real field installs still had it registered. The original <settings-file> mode is unchanged; aam-bootstrap.sh keeps using it. Decomposed into legacy-migrate.sh (244 lines) + slimmed strip-retired-hooks.sh (103 lines, sourceable lib) to respect the 300-line guidance. 14 new tests.

5. docs/migration-guide.md + release prep (de5b574)

Concise guide: identify (.claude/aiagentminder-version < 5.0) → update plugin → /aiagentminder:setup → dry-run → review → --apply → verify (hooks fire once; scripts resolve via PATH). Customization guide's raw shell-delete migration advice replaced with the safe script. CHANGELOG [5.4.0] section; all four version points bumped to 5.4.0 (minor — new functionality, backwards compatible).

Test plan

• npm test: 389 tests, 380 pass locally — the 9 failures are pre-existing Windows-local environment artifacts (exec-bit layout checks, git-diff secret-scan, sed fallback) identical to the pre-change baseline; ubuntu CI is the gate.
• npm run validate: versions 5.4.0 × 4, zero plugin-manifest errors; exec bits set in the git index (100755) for both touched bin scripts.
• New coverage: 6 review-findings tests, 14 migrate-mode/legacy tests, content assertions for all three agent edits.

Remaining owner steps (per docs/RELEASING.md — cannot be done from this PR)

1. Merge this PR.
2. git checkout main && git pull, then tag: git tag v5.4.0 && git push origin v5.4.0 (release workflow re-validates and drafts the GitHub Release).
3. Publish the drafted release (title v5.4.0 — legacy migration + agent long-run discipline).
4. Re-run /aiagentminder:setup + bash strip-retired-hooks.sh migrate in legacy target repos (dungeon-game first).

🤖 Generated with Claude Code