Review: Bug: pre-spawn-freshness hook corrupts git index when on main

Verdict: APPROVED

Template Completeness

• [x] Type — Bug
• [x] Lineage — Standalone, discovered during palinks session
• [x] Repo — ldraney/claude-custom
• [x] What Broke — detailed root cause: update-ref moves ref without updating index/working tree
• [x] Repro Steps — 5 clear steps
• [x] Expected Behavior — clear
• [x] Environment — Linux + macOS, specific hook and line number
• [x] Acceptance Criteria — 4 criteria
• [x] Related — project, reflog evidence, forgejo-helper.sh reference, arch component

Traceability

• [x] story:superuser-manage label — present on board item
• [x] story note verified — found in project-pal-e-agency user-stories section (Superuser role, row 1)
• [x] arch:claude-custom label — present on board item
• [~] arch note pending — arch-claude-custom note does not yet exist (404), but creation is tracked in Forgejo issue ldraney/claude-custom#236. Label correctly identifies the component. Not a scope defect in this ticket.
• [x] Forgejo issue — ldraney/claude-custom#296, open

Prior Review Resolution

• [x] [SCOPE] story:agent-reliability → Reassigned to story:superuser-manage. Verified: exists in project-pal-e-agency user-stories table.
• [x] [SCOPE] arch:claude-hooks missing → Changed to arch:claude-custom. Note creation tracked in #236. Correct component label.
• [x] [BODY] forgejo-helper.sh reference → Added to Related section: forgejo-helper.sh:_sync_working_tree() with context about post-mcp-merge-rebase.sh usage.

File Targets

• [x] hooks/pre-spawn-freshness.sh line 64 — verified: contains git -C "$CWD" update-ref refs/heads/main "$REMOTE_SHA" "$LOCAL_SHA" 2>/dev/null || exit 0
• [x] Confirmed: hook has no branch detection (no symbolic-ref or current-branch check before update-ref)
• [x] Confirmed: hook does NOT source forgejo-helper.sh and does NOT call _sync_working_tree
• [x] hooks/forgejo-helper.sh line 476 — verified: _sync_working_tree() helper exists, uses symbolic-ref to detect branch + reset --hard HEAD

Repo Placement

Dependencies

• Issue #236 — "Create arch-landing-site and arch-claude-custom architecture notes" (open, tracks arch note creation)
• Issue #294 — "SOP: Enforce worktree-first" (complementary prevention)
• Board items #822, #784 — same arch:claude-custom label, both in backlog, no ordering dependency

Acceptance Criteria

• AC1: When on main, use git merge --ff-only — testable by inspecting code path
• AC2: When on feature branch, keep update-ref — testable by inspecting code path
• AC3: No phantom staged changes — testable via git status after hook runs on main
• AC4: Fail-open on errors — testable by verifying || exit 0 pattern preserved

Blast Radius

• post-mcp-merge-rebase.sh (line 68) — uses identical update-ref pattern but ALREADY PATCHED: calls _sync_working_tree() from forgejo-helper.sh at line 74.
• forgejo-helper.sh (lines 472-494) — _sync_working_tree() helper already handles the desync. Issue body now references this as existing art, giving the implementing agent both fix approaches.
• pre-spawn-freshness.sh is the only remaining unpatched instance of bare update-ref on main.

Decomposition Assessment

Recommendations