Review: Pre-spawn freshness hook

Verdict: READY

Template Completeness

• [x] Type — Feature
• [x] Lineage — Standalone, references spec and plan docs
• [x] Repo — forgejo_admin/claude-custom
• [x] User Story — "As a session operator..."
• [x] Context — References 2026-03-06 incident, quantifies waste (40K+ tokens)
• [x] File Targets — Create list, modify list, and do-not-touch list all present
• [x] Acceptance Criteria — 7 criteria, all testable
• [x] Test Expectations — Manual test commands with concrete JSON payloads
• [x] Constraints — 4 constraints covering safety, patterns, and error handling
• [x] Checklist — Standard PR/test/no-unrelated checklist
• [x] Related — References project and SOP

Traceability

• [x] story:pm-scope label — present on board item #507
• [x] arch:worktree label — present on board item #507
• [x] Forgejo issue — forgejo_admin/claude-custom#193, open

File Targets

• [x] hooks/pre-spawn-freshness.sh — NEW file. Confirmed does not yet exist in /home/ldraney/claude-custom/hooks/. Correct location alongside 38 other hooks.
• [x] settings.json — EXISTS at /home/ldraney/claude-custom/settings.json. Confirmed PreToolUse Task matcher at lines 112-119 currently contains only check-agent-spawn.sh. New hook should be added to this matcher's hooks array.
• [x] hooks/check-agent-spawn.sh — DO NOT TOUCH. Confirmed exists. Issue correctly marks this as hands-off.

Repo Placement

Dependencies

• No blocking dependencies found. Board item #507 is in todo column.
• Related work: #508 (Post-merge worktree cleanup) and #509 (Fix cleanup-worktrees.sh repo list) are also in todo — same worktree lifecycle enforcement batch. These are siblings, not dependencies.
• #241 (Worktree auto-rebase) is in todo and conceptually downstream (rebase after freshness). No blocking relationship.
• #485 (Worktree isolation enforcement gaps, claude-custom#184) is in backlog — broader scope item. This ticket is a subset of that work. No conflict.

Acceptance Criteria

• AC1 (PreToolUse Task matcher) — verifiable by reading settings.json after modification
• AC2 (detect remote) — verifiable by testing with repos that have different remote names
• AC3 (fetch + fast-forward via update-ref) — verifiable by manual test with provided JSON payload
• AC4 (never blocks, exit 0) — verifiable by confirming no deny output and exit 0
• AC5 (log on advance) — verifiable by checking stderr output
• AC6 (silent when fresh) — verifiable by running when main is current
• AC7 (ignores non-spawn) — verifiable by piping JSON without prompt field

Blast Radius

• Existing pattern confirmed: post-merge-rebase.sh (lines 51-61) already uses the exact git fetch + git update-ref pattern. The new hook reuses this proven approach.
• Remote detection note: The issue says "detect forgejo remote first, else origin." Existing post-merge-rebase.sh hardcodes origin. The forgejo-helper.sh library has a forgejo-first detection pattern. The new hook's approach is more correct for the platform (some repos use forgejo remote). No conflict — this is an improvement, and does not change existing hooks.
• No downstream consumers affected: This is a new PreToolUse hook that runs alongside check-agent-spawn.sh. It always exits 0, so it cannot break the existing spawn gate.

Decomposition

• File targets: 1 new file + 1 minor edit = 2 files, 1 repo
• Acceptance criteria: 7 (above threshold), but all are behavioral checks of the same ~30-line script
• Estimated time: well under 5 minutes — the script is ~30 lines following an established pattern

Recommendation