Review: Bug: post-merge hook false alarm on squash merge

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Bug
• [x] Lineage -- Standalone, discovered during pal-e-api PR #226 merge
• [x] Repo -- forgejo_admin/claude-custom
• [x] What Broke -- Clear description of false negative on merged:true response
• [x] Repro Steps -- 4-step repro
• [x] Expected Behavior -- Correct
• [x] Environment -- Hook names identified (with caveats, see below)
• [x] Acceptance Criteria -- 3 criteria
• [x] Related -- project + triggering PR

Traceability

• [x] story:pm-scope label -- present on board item #505
• [x] arch:hooks label -- present on board item #505
• [x] Forgejo issue -- forgejo_admin/claude-custom#189, open

File Targets

• [x] hooks/remind-update-docs.sh (lines 21-24) -- verified: contains two-stage jq parsing for .tool_response.merged / .tool_response.result. This is the hook that emits the false "Merge was not successful" message (line 28-34).
• [x] hooks/post-mcp-merge-rebase.sh (lines 13-16) -- verified: identical two-stage jq parsing. Silently skips fast-forward on false negative.
• [x] hooks/board-item-on-merge.sh (lines 37-40) -- verified: identical two-stage jq parsing. Silently skips auto-move to done.
• [ ] hooks/board-item-on-merge.sh -- ISSUE: not mentioned in the issue body at all. This hook is equally affected.

Repo Placement

Dependencies

• Regression from #173 (board item #426, done) -- Issue #173 reported the identical symptom ("Merge was not successful" on successful squash merge). It was fixed in PR #177 (commit a742d5f) and validated. The two-stage jq parsing now in the hooks IS the fix from #173. This means either: (a) the actual PostToolUse hook input JSON shape differs from what the fix assumed, or (b) the Claude hook infrastructure changed its response wrapping since the fix was validated.
• Also related to #134 (board item #230, done) -- earlier bug "Post-merge hook fires on failed merges" (the inverse problem).
• No blocking dependencies on other in-progress items.

Acceptance Criteria

• "Successful squash merge triggers /update-docs reminder" -- testable via MCP merge + hook output inspection
• "Failed merge still shows error message" -- testable via intentional failure
• "No regression for rebase or regular merge methods" -- testable but adds scope; rebase and regular merge may have the same bug

Blast Radius

• 3 hooks affected, not 1 -- identical jq parsing pattern in remind-update-docs.sh, post-mcp-merge-rebase.sh, and board-item-on-merge.sh. The issue only names 2 of the 3.
• DRY violation -- the merged-detection logic is copy-pasted across 3 hooks. The fix from #173 was applied to all 3, but the shared logic should be extracted to forgejo-helper.sh to prevent future regressions. However, this is enhancement scope, not bug scope.
• Regression investigation needed -- the fix for #173 was validated on 2026-03-27 (same day). If the same symptom reappeared hours later during pal-e-api PR #226, the agent must capture the actual stdin JSON that the hook receives (e.g., via tee /tmp/hook-debug.json) before attempting a blind fix. Without knowing the actual JSON shape, any fix is a guess.

Decomposition

Recommendation

• [BODY] Add board-item-on-merge.sh to the Environment section as a third affected hook.
• [BODY] Add explicit file targets section listing all 3 hooks with line numbers: remind-update-docs.sh:21-24, post-mcp-merge-rebase.sh:13-16, board-item-on-merge.sh:37-40.
• [BODY] Add note in Lineage: "Recurrence of #173 (fixed in PR #177, validated same day). Fix is present in code but symptom returned -- likely response shape mismatch."
• [BODY] Add acceptance criterion: "All 3 merge hooks (remind-update-docs, post-mcp-merge-rebase, board-item-on-merge) correctly detect merged:true."
• [BODY] Add acceptance criterion: "Debug: capture actual PostToolUse stdin JSON to /tmp/hook-debug.json before fixing, to confirm the actual response shape."