Engine-only install (3) prune dangling repo-owned symlinks and dead hook entries

[EdbertChan]

Summary

Make every ./install.sh run (both modes) remove dangling symlinks that
point into this repo (typically left behind by deleted worktrees) from the
harness hook and skill directories, and remove ~/.claude/settings.json hook
entries whose script file under ~/.claude/hooks/ no longer exists. Depends on
the --engine-only installer slice having merged.

Goal: A machine stops erroring on every Bash call because of a hook whose
worktree was deleted, and nobody has to hand-edit settings.json.
Motivation: Today ~/.claude/hooks holds three links into deleted
.worktrees/ paths and settings.json still calls
~/.claude/hooks/narrow-the-scope/claude_posttooluse.py, which prints an error
on every command.
Safety invariant: Symlinks are removed only when they are dangling and their
raw readlink target starts with "$REPO_DIR/"; settings.json entries are
removed only when the command references a path under $HOME/.claude/hooks/
that does not exist; every other key, matcher, and command is preserved.
Effectiveness measurement: On the maintainer's machine ~/.claude/hooks goes
from 3 dangling repo links to 0 and settings.json from 1 dead hook entry to
0 after one install run.

Test Plan

Test Plan

• python3 -m unittest tests.test_prune_dead_hook_entries tests.test_install -v && python3 scripts/check_ecosystem_boundaries.py — Review claim: The prune unit tests and the install end-to-end tests pass against a fake home, and the boundary check still passes.
  Review lane: proof
  Safety invariant: Verification runs only against a temporary fake $HOME and synthetic settings dictionaries.
  Effectiveness measurement: The new test cases assert the dangling repo link and dead entry are gone while the outside-repo link and unrelated key remain.
  Slice rationale: One focused proof for the deletion rules before review.
  Architectural effect: None; verification only.
  Goal: Prove the deletion rules delete exactly the dead state and nothing else.
  Motivation: Deletion code is only trustworthy when its negative cases are exercised.
  Alternative considerations: Running against the real home was rejected as non-reproducible.
  Implementation details: Run the two unittest modules and the boundary check.
  Non-goals: No mutations outside the fake home.
  Layer: app_regression
  Feature state: active
  Acceptance criteria:

• Exits 0 only when all checks pass.

• bash scripts/scrub-handoff-artifacts.sh — Review claim: No ephemeral inter-task handoff files remain in the worktree before the merge gate.
  Review lane: cleanup
  Safety invariant: The scrub script only removes known handoff artifact names and never touches source, tests, or other repository files.
  Effectiveness measurement: The script exits non-zero if any handoff artifact remains.
  Slice rationale: Required terminal scrub for every implementation workflow.
  Architectural effect: None; hygiene only.
  Goal: Leave the branch free of handoff artifacts.
  Motivation: Handoff files must not reach the PR.
  Alternative considerations: Manual cleanup was rejected as non-deterministic.
  Implementation details: Run scripts/scrub-handoff-artifacts.sh.
  Non-goals: No product edits.
  Layer: app_regression
  Feature state: active
  Acceptance criteria:

• bash scripts/scrub-handoff-artifacts.sh exits 0.

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha>
• Post-revert steps: None
• Data migration? No

---

Note

Medium Risk
Install mutates user hook symlinks and rewrites ~/.claude/settings.json, but only for dangling repo-owned links and hook commands whose script paths are missing.

Overview
./install.sh now self-heals stale hook state on every run (full and --engine-only): it deletes dangling symlinks in ~/.claude|cursor|codex hook and skill dirs when readlink points under $REPO_DIR, and runs new scripts/prune_dead_hook_entries.py to strip ~/.claude/settings.json hook commands that reference missing files under ~/.claude/hooks/, dropping empty matcher groups while leaving other settings intact.

Coverage adds tests/test_prune_dead_hook_entries.py and TestStaleStatePrune in tests/test_install.py for the negative cases (outside-repo links, unrelated settings keys).

^{Reviewed by Cursor Bugbot for commit 4a6bab2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_3b36e3d4-9556-43c2-993e-a5833654238b)