[behruznassre]

What

Adds docs/adr/5812-worktree-residue-removal-guards.md (status Proposed) and regenerates docs/adr/README.md with node scripts/gen-adr-index.cjs --write. Docs only; no code changes.

Closes #5812. Sub-issue of #4941, which stays open. The implementation PR is #5233, which cites this ADR.

Why

The maintainer made this ADR a prerequisite for #5233 (comment 6485710283). worktree.reap-orphans in #5233 deletes directories under .claude/worktrees that git no longer tracks. Until now, no ADR said what evidence allows that deletion. The guards were settled one review at a time, and review 5691418415 found that the sweep's own prune order defeated one of them.

What the ADR decides

One decision per item in the issue:

1. Positive evidence, all of it required: location, shape, not registered, harness name and branch, plus the reserved .gsd-reap-* exception.
2. No work git lacks. The directory matches a harness branch tip in a throwaway index, the standard git worktree remove applies without --force. A registration is explicitly not the protection.
3. Disqualifiers, each with its skip reason.
4. The maintainer's ruling on the open question (chore(#4941): ADR — residue-removal guard standard for worktree.reap-orphans #5812, 2026-10-31). An ignored secret or user-data file the harness did not create keeps the directory. The ADR spells out how the code applies the ruling:
   • the patterns are .env*, .secrets and .planning/;
   • "the harness created it" means the file has the same bytes as the file at the same path in the main checkout, which is what Claude Code's .worktreeinclude copy produces.
5. The removal protocol.
6. The reporting contract.
7. Accepted limits.

It also covers the alternatives considered and the consequences.

On the issue's done-when list:

• The CONTEXT.md pointer lands with fix(#4941): reap-orphans names .claude/worktrees residue git has forgotten, and reports what it scanned #5233. That PR already rewrites the Worktree Safety Policy Module entry, and a second edit to the same line here would conflict.
• Every guard in fix(#4941): reap-orphans names .claude/worktrees residue git has forgotten, and reports what it scanned #5233 maps to a decision in the ADR. Every decision maps to code in src/worktree-safety.cts or is named as an accepted limit. A cross-check was run against fix(#4941): reap-orphans names .claude/worktrees residue git has forgotten, and reports what it scanned #5233's head.

Testing

• node scripts/gen-adr-index.cjs --check: up to date, 102 ADRs.
• All tests/adr-*.test.cjs files pass, including adr-index-gate (95/95) and adr-parser*.
• npm run lint:changeset and lint:docs pass. The change is docs only, so no changeset fragment is needed.

🤖 Generated with Claude Code

[trek-e]

Summary

Docs-only PR: adds docs/adr/5812-worktree-residue-removal-guards.md (status Proposed) and one line in docs/adr/README.md. No code changes. Reviewed head 9a8457d0b111d0bf8d72fb6e619bd1318e658379.

Classification & gate compliance

• Linked issue #5812 (Closes #5812 in body), OPEN, labels approved-enhancement, type: chore. Feature track by label. Diff is confined to docs/, so the orthogonal code-review passes (/code-review, /security-review) have no code to read and are not required by CLAUDE.md.
• Author behruznassre is not an owner login.
• Changed files (gh pr diff --name-only): docs/adr/5812-worktree-residue-removal-guards.md, docs/adr/README.md. Both checked against the armed diff reference.

Functional checklist

• ADR read in full (101 lines). Cross-links resolve: docs/adr/0004-worktree-workstream-seam-module.md, docs/adr/4630-dispatch-identity-and-isolation-decision-seam.md exist.
• Head CI (check-runs, latest run per name): all checks success or skipped except Reviewed or maintainer, which is the review-wait check. No runs in action_required for this head. docs-lint, Required tests, Changeset Required, Pull request template format all green.
• Not run locally: node scripts/gen-adr-index.cjs --check. The local run was denied by the auto-mode classifier because it executes PR-branch code. Equivalent evidence: the docs-lint check on this head is green.

Blast radius (from get_impact)

cmdWorktreeReapOrphans (src/worktree-safety.cts:2764, next): 0 callers, 1 callee (reapOrphanWorktrees, :2507), process Worktree-safetyCmdWorktreeReapOrphans, total_affected: 0, risk: UNKNOWN (observed_static_dependencies). The ADR governs code that lands with #5233, not code on next. Risk tier from §1.11b: not intersected with a central or bridge symbol (docs-only).

Co-change completeness

N/A: no code changed. The ADR names CONTEXT.md as updated by #5233; that is stated in the ADR itself, not a gap in this PR.

Memtrace Evidence

• recall_decision: UNAVAILABLE. Two attempts, both returned unavailable: true (MemCortex IPC deadline elapsed, then circuit open). The recorded-decision gate did NOT run for this review. No decision was checked against the ADR.
• get_symbol_context (cmdWorktreeReapOrphans): 0 callers, 1 callee, community ReasonWorktreePath, process Worktree-safetyCmdWorktreeReapOrphans. Confirms the ADR's scope (findUnregisteredResidue) is not yet on next.
• get_impact (cmdWorktreeReapOrphans, upstream, depth 3): total_affected: 0, risk: UNKNOWN, graph_incomplete: false.
• find_code_review_issues (ADR diff via @pr-block): 0 issues, _graph_state: disabled (no repo_id passed), _raw_count: 0. Markdown only, so no detector applies.

Findings

• Blocker: none
• Major: none
• Minor: none
• Nit: none

Verdict

Approve. No findings. The recorded-decision check is unavailable as stated above; this approval does not claim it passed.