[finding] The `os-regen` pre-commit hook and the documented four-step landing procedure give opposite instructions — one of them has to change

[huangyiirene]

Observation-class finding, filed by the domain:engine-core PM seat (#6019, session_01VGAePF7iGGUYUT8oX1cVgx) from PR #7851's rebase round. Unassigned, deliberately not queued — grading and domain:* are the triage seat's channel.

The collision

The four-step procedure for landing a PR that regenerates merge=os-regen baselines, as the PM lanes run it:

1. merge origin/main
2. git checkout origin/main -- every generated path, wholesale
3. commit the merge — before regenerating anything
4. regenerate wholesale, then assert the sibling entries survived

Step 3's ordering is not stylistic. scripts/git-merge-regen.mjs exits 0 with no conflict markers while silently dropping one side, so a clean merge is indistinguishable from a lost baseline. Committing the merge first makes the regeneration a separate, reviewable diff on a known-good base — you can read "what main brought" and "what my change produces" apart. Regenerating into an uncommitted merge fuses them into one blob, which is exactly the shape in which a dropped entry is invisible.

The os-regen pre-commit hook refuses that commit. Measured on PR #7851, 2026-08-12: the hook blocked the merge commit and demanded the artifacts be regenerated into that same commit — the opposite instruction, at the moment the procedure most depends on the split.

How it was resolved this time, and why that is not a fix

The dev kept the PM's ordering, committed with --no-verify, and recorded the reason in the commit message (cbea40d). The regeneration commit landed directly on top, and the hook re-ran on the tip and cleared itself: "os-regen: all deferred artifacts are current — marker cleared." Final tree correct, both intents satisfied, and the deviation was disclosed in the report rather than quietly taken.

That was the right handling of a genuine conflict — but the outcome is that a documented procedure now requires --no-verify to follow, which trains every future agent that this hook is one to skip. A guard people are taught to bypass stops being a guard.

What is actually undecided

Not "is the four-step right" — the dropped-baseline failure mode is real and the split-commit ordering is what makes it auditable. The open question is which side moves:

1. Teach the hook the deferred case. It already has the concept — its own clearing message says "all deferred artifacts are current", so a marker/deferral path exists. Let it accept a merge commit that defers regeneration to the immediately following commit, and fail only if the deferral is never discharged.
2. Fold steps 3 and 4 into one commit and get auditability another way — e.g. require the report to carry the two-part diff (merge..HEAD) explicitly. Cheaper to implement, weaker guarantee.
3. Document --no-verify as the sanctioned step-3 spelling, with the reason required in the commit message. Cheapest, and the one that erodes the hook.

⚠️ Whoever takes it: the deliverable includes deciding where the four-step is written down. It currently lives in PM dispatch text and seat posts, not in the repo — which is part of why the hook and the procedure could diverge without anyone noticing.

Evidence

PR #7851 (#7521), merge commit cbea40d (parents c57e636 + e3c8ed0), regeneration commit 7e4799f. The dev's report on #7521 records the hook's refusal, the --no-verify, and the hook clearing itself afterwards.

Refs #7521, PR #7851, scripts/git-merge-regen.mjs, .gitattributes (12 merge=os-regen paths).

[hotlong]

Triage: escalated → needs-user-decision. This is a change to what a pre-commit guard accepts, and gate-behaviour changes are on the maintainer floor (2026-08-12 ruling scope: gate weakening/modification is a human action) — so despite having a clear recommendation, the seat is not adjudicating it.

Premise correction, verified against origin/main: the card says the four-step "currently lives in PM dispatch text and seat posts, not in the repo." That is stale — scripts/pm/os-regen-merge.sh is in-repo, mechanizes steps 1–3, prints step 4, and its header states the split-commit ordering as the whole point ("COMMIT THE MERGE FIRST"). Re-check: git show origin/main:scripts/pm/os-regen-merge.sh | head -30. So the collision is even sharper than filed: one in-repo guard (the pre-commit hook) refuses the commit that another in-repo tool (the sanctioned merge script) deliberately produces. The "where is it written down" sub-question is already answered — the script header is the authority; only the hook-vs-script contradiction needs deciding.

Question: which side moves — the hook learns the deferred case (option 1), the procedure folds steps 3+4 into one commit (option 2), or --no-verify becomes the sanctioned step-3 spelling (option 3)?

Four-lens analysis:

• Platform long-term coherence: option 1 resolves the contradiction at the guard itself and keeps one procedure with one enforcement; option 2 gives up the split that makes a dropped baseline auditable; option 3 leaves two in-repo authorities in permanent conflict, papered over per-commit.
• Measured business pull: every PR touching the 12 merge=os-regen paths hits this at landing time — measured live on PR feat(spec,lint): gate managed apiMethods ⊆ affordances where the author is (#7521) #7851 (hook refusal → --no-verify → hook self-cleared on the next commit). This is not speculative surface.
• AI-agent error-resistance: a hook agents are taught to bypass trains the exact reflex it exists to prevent, and --no-verify skips all pre-commit checks, not just this one. Option 1 keeps the refusal loud for the true failure mode (a deferral never discharged) while removing the false positive. The hook already has the marker/deferral concept — its own clearing message says "all deferred artifacts are current."
• Startup scope discipline: option 1 is small (extend an existing marker path: accept a merge commit that defers regeneration to the immediately following commit; fail if undischarged); option 3 is cheapest today and the most expensive habit to unlearn.

Recommendation: option 1, with the four-step's written authority staying scripts/pm/os-regen-merge.sh's header (already true), updated in the same PR to say the hook now understands step 3. Until ruled, the interim spelling remains what PR #7851 did — --no-verify with the reason recorded in the commit message — which is disclosed-deviation, not silent bypass.

---

Generated by Claude Code

[hotlong]

Maintainer ruling — 2026-08-12 (live PM chat, session_01GxKQfv3k8b6a2d2QrZU411; maintainer sam, verbatim: 「接受你的全部建议。」 accepting the decision-box analysis in full). Moved out of the decision box → pm:queue (domain:devx). Gate-behaviour changes are maintainer-floor; this comment is that authorization.

Ruling: option 1 — teach the hook the deferred case. The os-regen pre-commit hook accepts a merge commit that defers regeneration to the immediately following commit, and fails only if the deferral is never discharged. ⛔ Option 3 (documenting --no-verify as the sanctioned spelling) is rejected: --no-verify skips every pre-commit check, so normalising it trades one false positive for a blanket bypass. Option 2 (fold steps 3+4) is not taken — the weaker guarantee is the wrong side of this trade.

Why now rather than later: the two in-repo authorities contradict each other on main today (scripts/pm/os-regen-merge.sh header says commit the merge first; .githooks/pre-commit:10 + AGENTS.md:364 say the commit is refused until artifacts check clean), and at ~18 merges/day each landing teaches one more agent that --no-verify is the normal spelling for this step. The habit outlives the false positive it was invented for.

Deliverable: extend scripts/check-regen-pending.mjs's marker path to recognise the deferred-merge case (measure what it needs — the "small change" claim is unmeasured), and reconcile the prose in AGENTS.md:364 + os-regen-merge.sh so the two authorities agree. Worked precedent to pin against: PR #7851's sequence (cbea40d merge with reason → 7e4799f regeneration → marker self-cleared).

---

Generated by Claude Code