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
What happened. Running
bash scripts/pm/os-regen-merge.shon a branch that had editedcontent/docs/permissions/system-context.mdxwhileorigin/mainhad also moved it, the run stopped at step 1 with:The only conflicted path was
content/docs/permissions/system-context.mdx, which is amerge=os-regenpath (.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.mjsclassifies this page as MIXED (generated anchors plus hand-written prose) and deliberately declines to defer it: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.shexists 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 themerge=os-regenpattern list the script has already read, and print one sentence per class:The script's
--self-testalready 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/maininto 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