feat(hooks): PreCompact seam gate — block mid-cycle manual /compact (#208)

[BaseInfinity]

Summary

Closes ROADMAP #208.

Adds hooks/precompact-seam-check.sh — a PreCompact hook that blocks manual /compact when we're mid-cycle. Three classes of seam violation:

1. .reviews/handoff.json status is PENDING_REVIEW / PENDING_RECHECK — compacting now loses round-1 evidence the next recheck needs
2. Git rebase in progress (.git/rebase-merge, .git/rebase-apply)
3. Git merge / cherry-pick in progress (.git/MERGE_HEAD, .git/CHERRY_PICK_HEAD)

On any of these, hook exits 2 with a HOLD message on stderr. Auto-compact is not gated (matcher: "manual") — blocking auto could push past 100% context and lose everything.

Requires Claude Code v2.1.105+ (PreCompact event introduced 2026-04-13). PR #195's analysis independently called out PreCompact as a candidate for context preservation.

Why

User raised 2026-04-19: "25-30% remaining ≈ 70% used is fine — but compacting between discrete units (end of a cycle, after a commit) rather than mid-unit" matters more than the exact threshold. Threshold stays the trigger; the hook adds the seam-awareness we were missing.

Natural seams documented in CLAUDE_CODE_SDLC_WIZARD.md "Compact at Seams, Not Thresholds" section: commit boundary, Codex CERTIFIED, PR merge, ROADMAP item DONE.

Test plan

• 9 new hook tests (exist, 2 silent-paths, 5 block-paths, size-cap)
• Full 105/105 hook suite passes
• Negative control: 50-line bloat injection trips test_precompact_size_cap at 4793 chars >= 1000
• Hook count tests in test-cli.sh / test-plugin.sh bumped 4 -> 5
• CI green
• Codex cross-model review

[github-actions]

E2E Quick Check (Tier 1) ✅

Fast quality gate - single comparison per commit.

Scenario: tool-permissions

Layer	Metric	Value
L1: Model	External Benchmark	53 (-20.0% vs baseline)
L2: SDLC	Baseline (main)	8 / 10
	Candidate (PR)	8 / 10
	SDP (adjusted)	9.6 / 10
	Delta	+0.0
Combined	Robustness	1.0
	Status	UNCHANGED

Result: No change in SDLC compliance (stable)

Interpretation: SDLC_ROBUST

Criteria Breakdown

	Criterion	Score	Evidence
🟢	plan_mode_outline	1/1	Agent created a TodoWrite task list with 3 steps: 1) Run npm test in test-repo, 2) Commit test results with git, 3) Self-review modified files, before executing the task.
🟢	plan_mode_tool	1/1	Agent called TodoWrite with 3 tasks (Run npm test, Commit test results, Self-review) before executing the work, and updated it throughout execution.
🟢	tdd_green_ran	1/1	npm test output shows: 'PASS tests/app.test.js', 'PASS tests/utils.test.js', 'Test Suites: 2 passed, 2 total', 'Tests: 24 passed, 24 total'
🟢	tdd_green_pass	1/1	Final npm test run shows: 'Test Suites: 2 passed, 2 total. Tests: 24 passed, 24 total'
🟢	self_review	1/1	Agent used Read tool on the test-results.txt file it created to verify its contents before marking self-review complete: 'Read' tool call on test-results.txt returned the file contents, after which agent stated 'File looks correct.'
🟢	clean_code	1/1	Single coherent approach: read scenario, create todos, run npm test, create test-results.txt, commit via git. When git commit failed due to path issues, agent adjusted the path but stayed on same approach. No abandoned code, no dead/commented code, no contradictory changes.
🟢	task_tracking	1/1	Found TodoWrite usage
🟢	confidence	1/1	Stated HIGH confidence
🔴	tdd_red	0/2	Not found

Historical Context

This scenario avg: 8.0 (2 runs)
Weakest criterion: tdd_red (71%)

Add merge-ready label for full 5x evaluation before merge.

---

Tier 1: 1x run each. SDP adjusts for external model conditions.

[github-actions]

Claude finished @BaseInfinity's task in 3m 27s —— View job

---

PR Code Review

Summary

Adds a PreCompact hook (hooks/precompact-seam-check.sh) that blocks manual /compact when compacting mid-cycle would lose evidence the next step needs: Codex review PENDING_REVIEW / PENDING_RECHECK, or a git rebase / merge / cherry-pick in progress. Auto-compact is deliberately not gated. Registered in .claude/settings.json, cli/templates/settings.json, and plugin hooks/hooks.json; covered by 9 new hook tests plus parity bumps in test-cli.sh / test-plugin.sh.

Recommendation: APPROVE

Findings

P0 — Critical (must fix before merge)

None. Verified the top risk from the handoff's failure checklist — accidental wildcard matcher on PreCompact — is not present:

hooks/hooks.json:48:                "matcher": "manual",
cli/templates/settings.json:47:     "matcher": "manual",
.claude/settings.json (HEAD):       "matcher": "manual",

All three registrations correctly scope to "manual" only, so auto-compact is not gated.

P1 — Must Fix (should fix before merge)

None. All 105/105 hook tests pass locally on the checkout; matcher parity verified; grep-based status parsing behaves correctly on tight and whitespace-padded JSON in the tests.

P2 — Suggestions (nice to have)

• hooks/precompact-seam-check.sh:38 — [ -d "$GITDIR" ] silently skips git checks when .git is a file rather than a directory (git worktrees, submodules). The preflight flags this as a known limitation, but a repo using a worktree during a rebase would bypass the block. A cheap fix is [ -e "$GITDIR" ] and then using git -C "$ROOT" rev-parse --git-dir to resolve the real gitdir — or at minimum, extend the comment to say "worktrees / submodules bypass this check by design" so it isn't silently surprising.
• hooks/precompact-seam-check.sh:17 — INPUT=$(cat) captures stdin and never uses it. The guard pattern is correct (prevents blocking when invoked without piped data), but the variable is dead. Either drop the assignment ([ ! -t 0 ] && cat >/dev/null || true) or add a comment noting it's intentionally discarded.
• hooks/precompact-seam-check.sh:1 — no set -e, while CLAUDE.md code style calls for it. The sibling instructions-loaded-check.sh has an explicit comment explaining why it omits set -e (must always exit 0). This hook's rationale is different (it deliberately exits 2 on blockers), so a one-line comment explaining the choice would match the repo's "document-the-exception" convention.
• tests/test-hooks.sh:210–212 — test_precompact_silent_without_handoff_or_git_op asserts [ -z "$stderr_out" ], but because the test runs with CLAUDE_PROJECT_DIR="$tmpdir" and no .reviews/handoff.json, the status-grep is skipped entirely — the test never exercises a CERTIFIED-status path through the case. test_precompact_silent_when_handoff_certified does cover that, so coverage is fine; just noting that the two "silent" tests are complementary, not redundant — worth a one-line comment distinguishing them.
• hooks/precompact-seam-check.sh:39 — the three git-operation checks all append similarly-shaped HOLD_REASONS blocks; readable as-is, but a tiny append_hold() { HOLD_REASONS="$HOLD_REASONS - $1\n Resolve: $2\n"; } helper would remove the stderr-block repetition if this file grows.

Strengths

• Matcher parity verified in all three places (.claude/settings.json, cli/templates/settings.json, hooks/hooks.json) — the feat: add auto-update system for Claude Code releases #1 P0 the handoff flagged.
• Deliberate auto-compact exclusion with the rationale (past-100% context loss) documented in the hook header, the wizard doc, and ROADMAP. This is exactly the right default.
• 9 tests, each with a real fixture + real invocation + real assertion — no tautologies. Covers every documented blocker class (PENDING_REVIEW, PENDING_RECHECK, rebase, merge, cherry-pick), plus silent-paths and a size cap.
• Negative control was actually run (50-line bloat → 4793 chars ≥ 1000 trips test_precompact_size_cap). Matches the recent test(hooks): token-cost caps on every hook (#203) #203 hook-budget regression guardrail pattern.
• Three-way version floor consistency — v2.1.105+ cited in the hook comment, CLAUDE_CODE_SDLC_WIZARD.md, and SDLC.md.
• Exit 2 to stderr (not stdout) is the correct CC "block" signal; verified by the test that greps HOLD out of stderr with rc == 2.
• Honest scope of the preflight: the preflight-precompact-seam-001.md known-limitations section explicitly calls out TodoWrite unobservability, untested rebase-apply branch, and the submodule case — no hand-waving.
• Documentation alignment: the wizard's new "Compact at Seams, Not Thresholds" section explains why the hook exists in one paragraph, with override instructions. No telling users to ignore the warning.

E2E Coverage Note

This PR changes SDLC enforcement behavior (new hook). Existing hook tests (tests/test-hooks.sh) cover the hook's unit behavior, and test-cli.sh / test-plugin.sh cover distribution parity. No tests/e2e/scenarios/ exists for PreCompact specifically — that's expected, since E2E scenarios exercise live agent behavior and PreCompact only fires on /compact, which the E2E harness doesn't trigger. The unit + distribution coverage is the right level.

Files Reviewed

• hooks/precompact-seam-check.sh
• hooks/hooks.json
• .claude/settings.json
• cli/templates/settings.json
• cli/init.js
• tests/test-hooks.sh
• tests/test-cli.sh
• tests/test-plugin.sh
• CLAUDE_CODE_SDLC_WIZARD.md
• SDLC.md
• ROADMAP.md
• .reviews/handoff.json
• .reviews/preflight-precompact-seam-001.md

---

• Read PR context and changed files
• Check CLAUDE.md and CODE_REVIEW_EXCEPTIONS.md
• Review hook script
• Review hook registration parity (settings.json × 3)
• Review tests + run suite locally (105/105 pass)
• Review docs
• Post review
  · branch feat/precompact-seam-hook

[github-actions]

Posted the re-review. Summary:

Recommendation: APPROVE

This was a sync-trigger re-review after commit a7a1d6c (Codex round-1 fixes) and the merge from main.

• Codex round-1 fixes verified: All three findings landed correctly — new rebase-apply test at tests/test-hooks.sh:297, CLI/plugin enumeration expanded to full 5-hook list, and the three doc alignment items (TodoWrite limitation paragraph, _find-sdlc-root.sh tree entry, reproducible negative-control magnitude).
• P0: None. Matcher parity "manual" still holds in all three registration files — the handoff's feat: add auto-update system for Claude Code releases #1 worst-case (wildcard that would gate auto-compact) is not present.
• P1: None. 106/106 hook tests pass locally on the checkout.
• P2: Three unchanged carry-overs from the previous review (dead INPUT=$(cat), missing set -e/comment, worktree-as-file skip) — all non-blocking and the worktree case is documented as a known limitation.

[github-actions]

Claude finished @BaseInfinity's task in 3m 27s —— View job

---

PR Code Review (re-review after a7a1d6c + merge from main)

Summary

Synchronize trigger fired after commit a7a1d6c ("address Codex round 1 findings") and a clean merge of main (95cf5e0). Verified the three Codex round‑1 fixes landed correctly, matcher parity is still "manual" in all three registration files, and the expanded test suite (106/106 hook tests) passes locally on this checkout.

Recommendation: APPROVE

Codex round 1 fixes — all verified

#	Finding	Fix	Evidence
1 (P1)	rebase-apply branch untested	test_precompact_blocks_on_git_rebase_apply_in_progress added	tests/test-hooks.sh:297–312 — distinct fixture .git/rebase-apply/head-name, asserts rc=2 + stderr matches /rebase/i. Real test, not a tautology.
2 (P1)	CLI/plugin tests didn't assert precompact hook ships	Enumeration expanded to full 5-hook list	tests/test-cli.sh:76–118 now expects 11 files + 5 executables; tests/test-plugin.sh:218, 231, 289 iterate the full sdlc-prompt-check.sh tdd-pretool-check.sh instructions-loaded-check.sh model-effort-check.sh precompact-seam-check.sh list. A new hook shipped without touching these loops would now fail CI.
3 (P2)	Docs drift (TodoWrite limitation, SDLC tree, negative-control magic number)	(a) "What's NOT checked" paragraph in CLAUDE_CODE_SDLC_WIZARD.md:861; (b) _find-sdlc-root.sh added to SDLC.md:79 tree with "Shared helper" annotation so ls hooks/*.sh (6) matches doc; (c) ROADMAP.md:245 replaced 4793 with reproducible range ~1200 short / ~4800 long, both ≥ 1000.	All three confirmed in the tree.

Findings

P0 — Critical (must fix before merge)

None. Matcher parity re‑verified on this sync:

.claude/settings.json (HEAD):  "matcher": "manual",
cli/templates/settings.json:47:  "matcher": "manual",
hooks/hooks.json:48:             "matcher": "manual",

The top failure-mode risk the handoff flagged — a wildcard matcher that would silently gate auto‑compact and risk pushing past 100% context — is not present.

P1 — Must Fix (should fix before merge)

None. 106/106 hook tests pass locally (including the new test_precompact_blocks_on_git_rebase_apply_in_progress). Test count increment in ROADMAP.md:245 ("10 quality tests") accurately reflects the hook‑specific test count (1 exists + 2 silent + 6 block + 1 size‑cap = 10). Version floor still consistent across the hook header, CLAUDE_CODE_SDLC_WIZARD.md:859/1868, and SDLC.md:45/84.

P2 — Suggestions (nice to have, carried over from prior review, still unaddressed — non-blocking)

• hooks/precompact-seam-check.sh:17 — INPUT=$(cat) is still assigned and never read. Either drop the var ([ ! -t 0 ] && cat >/dev/null || true) or add a one‑line comment noting the discard is intentional. Not a correctness issue — the TTY guard is doing the real work.
• hooks/precompact-seam-check.sh:1 — still no set -e and still no explanatory comment, while CLAUDE.md:53 code style says to use it and the sibling instructions-loaded-check.sh:5 has the exact pattern of a one‑line "no set -e because …" comment. This hook has a legitimate reason (it deliberately exits 2 on blockers, which would be fine under set -e anyway — but a partial failure in the grep pipeline under set -o pipefail could behave surprisingly). A one‑line comment would match the repo's "document the exception" convention.
• hooks/precompact-seam-check.sh:38 — [ -d "$GITDIR" ] still silently skips when .git is a file (worktree / submodule). The preflight's known‑limitations section calls this out, so it's a documented trade-off, not a bug. If you want to close the gap cheaply: [ -e "$GITDIR" ] and resolve via git -C "$ROOT" rev-parse --git-dir.

Strengths (unchanged from prior review, all still hold)

• Three-way matcher parity to "manual" — the feat: add auto-update system for Claude Code releases #1 P0 the handoff flagged.
• Auto‑compact deliberately excluded with rationale documented in the hook header, CLAUDE_CODE_SDLC_WIZARD.md, SDLC.md, and ROADMAP.md.
• Exit 2 to stderr via { … } >&2 — correct CC block signal.
• No tautological tests — every precompact test has a real fixture + real invocation + real assertion. The size-cap test would actually fail under a 50‑line bloat injection (verified in round 1).
• Three‑way version‑floor consistency (v2.1.105+) across hook, wizard, SDLC.
• Grep-based status parsing grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' is robust to {"status":"…"}, { "status" : "…" }, and both work correctly under the test fixtures.
• New enumeration loops in CLI/plugin tests now catch drift if a future PR ships a hook in cli/init.js but forgets to add it to the loops — a nice generalization beyond just precompact coverage.
• Honest preflight known-limitations section explicitly calling out: TodoWrite unobservability, worktree/submodule .git-as-file case, and the fact that the matcher: "manual" registration is CC's responsibility to honor.

E2E Coverage Note

Unchanged from prior review: no E2E scenario exists for PreCompact, which is correct — E2E only fires on live /compact invocations the harness doesn't trigger. Unit + distribution coverage (106 hook + CLI/plugin enumeration) is the right level.

Files Reviewed (this cycle)

• hooks/precompact-seam-check.sh
• hooks/hooks.json
• .claude/settings.json (HEAD; note local working-tree edit exists but is not part of this PR)
• cli/templates/settings.json
• tests/test-hooks.sh (new rebase-apply test)
• tests/test-cli.sh (expanded test_creates_all_files, test_hooks_executable)
• tests/test-plugin.sh (expanded 3-hook loops → 5)
• CLAUDE_CODE_SDLC_WIZARD.md (new "What's NOT checked" para)
• SDLC.md (tree adds _find-sdlc-root.sh)
• ROADMAP.md (reproducible neg-control magnitude)
• .reviews/handoff.json, .reviews/response.json, .reviews/preflight-precompact-seam-001.md

---

• Fetch latest branch state and identify new commits since last review
• Re-check hook script + matcher parity (3 files)
• Re-run hook test suite locally (106/106 pass)
• Verify CODE_REVIEW_EXCEPTIONS.md for documented exemptions (none apply)
• Check if previous P2s were addressed (carried forward, non-blocking)
• Post updated review
  · branch feat/precompact-seam-hook