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

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Bug
• [x] Lineage — Standalone, discovered during palinks session
• [x] Repo — ldraney/claude-custom
• [x] What Broke — detailed, includes 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-pal-e-agency, reflog evidence

Traceability

• [x] story:agent-reliability label — present on board item
• [ ] story note MISSING — [SCOPE] story:agent-reliability does not exist in project-pal-e-agency user-stories section. Available stories: superuser-manage, superuser-onboard, pm-scope, dev-execute, qa-review, validation-execute, dottie-docs. Create user story entry or reassign to an existing story (e.g. story:superuser-manage).
• [x] arch:claude-hooks label — present on board item
• [ ] arch note MISSING — [SCOPE] arch-claude-hooks note does not exist in pal-e-docs (404). Create architecture note arch-claude-hooks for the hooks subsystem. Note: issue #236 tracks creating missing arch notes but does not specifically cover arch-claude-hooks.
• [x] Forgejo issue — ldraney/claude-custom#296, open

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 does NOT check which branch the user is on before running update-ref (no symbolic-ref or branch detection)
• [x] Confirmed: hook does NOT source forgejo-helper.sh and does NOT call _sync_working_tree

Repo Placement

Dependencies

• Issue #294 — "SOP: Enforce worktree-first — never develop on main" (complementary prevention, not a dependency)
• Issue #248 — "Add hook to block destructive git commands" (tangentially related)

Acceptance Criteria

• AC1: When on main, use git merge --ff-only — testable by checking out main, creating upstream commits, and verifying behavior
• AC2: When on feature branch, keep update-ref — testable by checking out a branch and verifying code path
• AC3: No phantom staged changes — testable via git status after hook runs
• AC4: Fail-open on errors — testable by simulating network/merge failures

Blast Radius

• post-mcp-merge-rebase.sh (line 68) — uses identical update-ref pattern but is ALREADY PATCHED: it calls _sync_working_tree() from forgejo-helper.sh (line 74) to reset the working tree after update-ref.
• forgejo-helper.sh (lines 472-494) — already has a _sync_working_tree() helper that detects if user is on the default branch and does git reset --hard HEAD if no uncommitted changes. This is an alternative fix approach the implementing agent should be aware of.
• The issue proposes merge --ff-only (which updates HEAD + index + working tree atomically) rather than update-ref + reset --hard. Both approaches solve the problem; merge --ff-only is arguably cleaner as it avoids the destructive reset --hard.

Decomposition Assessment

Recommendations

• [SCOPE] Create user story entry story:agent-reliability on project-pal-e-agency user-stories section, or reassign to existing story:superuser-manage.
• [SCOPE] Create architecture note arch-claude-hooks for the hooks subsystem in pal-e-docs.
• [BODY] Add note in Related section referencing forgejo-helper.sh:_sync_working_tree() as existing art for the implementing agent's awareness.