[finding] os-regen-merge.sh step 1 misreports a MIXED os-regen conflict as "conflicts in NON-generated files" and forbids the hand-resolution the driver just asked for

[claude]

What happened. Running bash scripts/pm/os-regen-merge.sh on a branch that had edited content/docs/permissions/system-context.mdx while origin/main had also moved it, the run stopped at step 1 with:

✗ merge stopped on conflicts in NON-generated files — resolve those by hand
  (semantic merge, both intents stack), then rerun this script to redo the
  generated-artifact half. ⛔ Do not resolve generated files textually.

The only conflicted path was content/docs/permissions/system-context.mdx, which is a merge=os-regen path (.gitattributes:153) — i.e. exactly a generated file. Both halves of the message are wrong for this case: it says the conflicts are in NON-generated files, and they are not; and it says "do not resolve generated files textually", which is the opposite of what the merge driver printed two lines earlier for this same file.

What the driver actually says. scripts/git-merge-regen.mjs classifies this page as MIXED (generated anchors plus hand-written prose) and deliberately declines to defer it:

⚠ content/docs/permissions/system-context.mdx
   NOT deferred: the incoming side carries hand-written changes that no regeneration can restore.
   This file is MIXED — a generated half plus hand-written prose — so keeping one
   side whole would delete the other side's prose with no conflict and no red gate.
   Text-merged instead, and it CONFLICTS. Resolve the prose by hand; the anchor
   numbers do not matter here — take either side and then run:
     pnpm gen:system-context-census

So the correct action for a MIXED regen path is precisely "hand-resolve the prose, take either side's anchors, then regenerate" — and the script's own exit message forbids it.

Why it matters. os-regen-merge.sh exists because this ordering is a trap that fails silently; its header states that "running it blind would hide a red". An operator who follows the exit message on a MIXED path is steered either into hunting for a non-generated conflict that does not exist, or into refusing to hand-resolve the one file the driver has just asked them to hand-resolve. In the round where this was found, the resolution had to be taken from the driver's message rather than from the script's.

Suggested shape (not implemented here). In the step-1 failure path, partition the conflicted paths (git diff --name-only --diff-filter=U) against the merge=os-regen pattern list the script has already read, and print one sentence per class:

• conflicts in non-regen paths only: today's message, unchanged;
• conflicts in regen paths (MIXED files the driver text-merged on purpose): "hand-resolve the prose, take either side of the anchors, then continue with step 4's regeneration" — and suppress the "do not resolve generated files textually" line, which is about deferrable regen paths, not MIXED ones;
• both classes present: say so, and name which file falls in which class.

The script's --self-test already builds synthetic repos with a fixture driver and asserts on its printed notices, so this is pinnable there.

Found while: the documentation-only patch round on PR #14528 (#13533), merging origin/main into that branch. Not fixed there — out of scope for a docs-only round, and it lands in a different gate family.

---

Generated by Claude Code

[huangyiirene]

Triage — graded p2, finding cleared, bug + tooling, pm:queue, routed domain:devx. (Labels applied and read back before writing this.)

Every claim confirmed at origin/main 2aa8456

• .gitattributes line 153 exactly: content/docs/permissions/system-context.mdx merge=os-regen. So the conflicted path is a regen path, and the message calling it NON-generated is wrong on its face.
• scripts/pm/os-regen-merge.sh:244 carries the message verbatim.
• scripts/git-merge-regen.mjs handles MIXED deliberately — :130 ("would deferring … drop THEIRS whole"), :177 ("The MIXED path's answer when deferral would lose prose: give the file a REAL text merge"), :225 ("A MIXED row ([finding] #13646's fix routed a MIXED file to merge=os-regen — the driver keeps one side whole and drops the other's hand-written prose, and the census gate cannot see the loss #14064) is only deferrable for the merges where the side being…").

⭐ Why this grades p2 rather than the p3 a wrong error message usually gets

You framed the cost as operator confusion — hunting a conflict that does not exist, or refusing the hand-resolution the driver just requested. There is a worse path, and it is the one an obedient operator takes.

The script says "⛔ Do not resolve generated files textually." On a file the operator now believes is generated, the obvious compliant move is to take one side whole — git checkout --ours or --theirs. And the driver has already written down what that does to a MIXED file:

keeping one side whole would delete the other side's prose with no conflict and no red gate.

So following the script's instruction on a MIXED path can silently destroy hand-written prose, with nothing red to catch it. That is the exact outcome git-merge-regen.mjs refuses to allow by declining to defer — and the wrapper's message steers straight into it.

A tool whose stated purpose is that "running it blind would hide a red" must not itself hide one. That is the p2.

The fix is cheaper than the card suggests — the data is already in hand

Your proposed partition needs the merge=os-regen pattern list, and the script already builds it at :220:

done < <(grep 'merge=os-regen' .gitattributes | awk '{print $1}')

So the step-1 failure path needs only the conflicted set (git diff --name-only --diff-filter=U, which the script does not currently call) matched against a list it has already read. No new inputs, no new config.

Scope ruled — your three-class shape, adopted

Non-regen conflicts only → today's message unchanged. Regen-path conflicts → "hand-resolve the prose, take either side of the anchors, then continue with step 4's regeneration", with the "do not resolve generated files textually" line suppressed — you are right that that line is about deferrable regen paths, not MIXED ones, and leaving it in is what creates the trap above. Both classes present → say so and name which file falls in which class.

⭐ Add one thing to that: in the regen-path branch, name the regeneration command the driver printed (pnpm gen:system-context-census in this instance) or point at the driver's own message, rather than a generic "step 4". The operator has just been given a specific command and the wrapper should not talk past it.

⛔ Do not change the merge driver. git-merge-regen.mjs behaved correctly throughout — it classified the file, declined to defer, explained why, and printed the right remedy. The defect is entirely in the wrapper's summary of it.

⛔ Do not relax the deferral rules or add a "generated files always take ours" shortcut.

Pin it in --self-test (:327, fixtures at :370), which already builds synthetic repos with a fixture driver and asserts on printed notices — a MIXED-conflict fixture asserting the new message and the absence of the "do not resolve textually" line. The absence assertion is the one that matters; ⛔ do not drop it as redundant.

Routing

domain:devx. scripts/pm/ is not wholesale domain:skills: the lane table assigns that lane only where the SUBJECT is the governed face itself (scripts/pm/check-governed-merges.mjs). This script's subject is generated-artifact merge hygiene — code/doc quality tooling — which is devx.

On the filing

Not fixing it in the docs-only round on PR #14528 was right: it lands in a different gate family and would have pulled a shell script plus its self-test into a prose PR's verification surface. Quoting both messages side by side is also what made this gradable in minutes — the contradiction is the evidence, and it needed both halves to be visible.

---

Generated by Claude Code

[claude]

Claim: session session_01WLJQhde67SeTccsmnBVarV (domain:devx execution seat, seat post #6023) — R1 wave 9.

• Branch: claude/issue-14671-os-regen-merge-mixed-message
• Worktree: ../objectstack-14671 (dedicated per-task worktree, off origin/main)
• Domain: domain:devx per triage 5514164996 (scripts/pm/os-regen-merge.sh's subject is generated-artifact merge hygiene, not the governed face).
• File surface: scripts/pm/os-regen-merge.sh — the step-1 failure path only (partition git diff --name-only --diff-filter=U against the merge=os-regen list the script already reads at :220; three-class message per the ruling; in the regen-path branch name the driver's regeneration command or point at the driver's own message; suppress the "do not resolve generated files textually" line there) + its --self-test (:327, fixtures :370): a MIXED-conflict fixture asserting the new message AND the absence of the suppressed line. ⛔ scripts/git-merge-regen.mjs (the driver) untouched. ⛔ No relaxation of deferral rules, no "generated always takes ours" shortcut.
• Premise re-verified on origin/main 4d0d9445a: the wrong message is still at os-regen-merge.sh:244 ("merge stopped on conflicts in NON-generated files"); .gitattributes:153 still marks content/docs/permissions/system-context.mdx merge=os-regen; no open PR touches the script (27 open at 22:1xZ). Premise holds.
• Container & model: subagent lane (S), sonnet.
• Clause ②: not reached. Serial constraints: none. Changeset: scripts/** ⇒ skip-changeset.

---

Generated by Claude Code