check:docs-audit-scope forces every page-adding docs PR across the .claude/** governed fence — 4 for 4, and 3 merged unnoticed

[claude]

The gate that forces every docs PR across the governed fence

scripts/pm/check-governed-merges.mjs:274-280 fences five surfaces as human-merge-only. One of them is .claude/**.

check:docs-audit-scope (run at .github/workflows/lint.yml:516, inside the lint: job = the Lint & Repo Gates required context) holds a generated page-scope block that lives at .claude/workflows/docs-accuracy-audit.js. Adding a page to content/docs/ makes that gate red; the gate's own --write regenerates the block; the block is inside the fence.

⇒ Adding a documentation page cannot be done without crossing a governed surface. Not "usually", not "if you are careless" — the two rules are jointly unsatisfiable for the whole class.

Measurement, not inference

Four page-adding docs PRs, each a +1/-0 edit to that exact file:

commit	PR	file diff
ece873001	#6891	.claude/workflows/docs-accuracy-audit.js +1/-0
f049f7fd4	#8964	same, +1/-0
e2b3c831e	#9449	same, +1/-0
ae67ad006	#9860	same, +1/-0

Three of the four merged with no one recording that the fence had been crossed. That is the defect worth fixing: a fence that fires on routine traffic trains every seat to read past it. The signal is not "an agent touched the instruction tree" any more — it is mostly "an agent ran a required gate's --write", and nothing downstream can tell the two apart.

What is NOT being proposed

• ⛔ Not "drop .claude/ from the fence." The fence is right about the instruction tree.
• ⛔ Not "let agents merge governed PRs." The human-merge rule is the point.
• ⛔ Not "hand-edit the block." The gate rejects hand-edits; that is why --write exists.

Candidate shapes (pick one, or reject all three)

1. Move the generated artifact out of the fence. The scope block is data the gate owns, not instruction-tree prose. Somewhere like scripts/generated/docs-audit-scope.json puts it under normal review while .claude/workflows/docs-accuracy-audit.js keeps the logic. Cost: one path change + the gate's reader.
2. Carve a generated-artifact exception into check-governed-merges.mjs — a per-surface generatedPaths list, so exactly this file (and any future --write target) is fenced against hand edits but not against its own generator's output. Cost: the checker must be able to tell "matches the generator's output" from "hand-edited", which means running the generator — real work, and the honest version of the rule.
3. Accept it and make the crossing visible — the fence stays, but check-governed-merges labels this class governed:generated instead of failing it into the same bucket as an AGENTS.md rewrite. Cheapest; keeps the human click; stops the class from diluting the signal.

My read: 2 is the correct rule and 1 is the cheap one that buys most of it. 3 alone leaves a human clicking merge on traffic no human judgement improves.

Open question for the maintainer

Was ruling 5 (.claude/** off-limits to dispatched devs) meant to cover generated artifacts under that prefix at all? Every answer here follows from that. I ruled on #9860 that it was not — the dev's regeneration stands — but that ruling is mine, made under a forced choice, and it should be confirmed or overturned rather than left as precedent-by-accident.

Prior art

Same family as #9747: a gate whose recognizer is narrower than the repo's real shapes, reporting the shortfall as a verdict instead of as "unrecognised". Here the fence's recognizer is path prefix, and the shape it cannot see is provenance.

---

Generated by Claude Code

[os-warren]

Triage (session session_01JEhkB6ShK2HHDzozy7Qwgz): decision-inbox intake. Two label corrections in one pass: domain:devx → domain:skills — the SUBJECT here is the governed fence itself (scripts/pm/check-governed-merges.mjs + the .claude/** surface definition), which the maintainer's 2026-08-18 ruling assigns to the skills lane, not devx; and dropping the leftover finding label (the card is graded into the inbox; the decision label is the state). Backfilling the standard facet block, which the card body's analysis already substantiates:

<!-- os-decision-facets -->

• Platform long-term coherence: option 2 (provenance-aware fence: hand edits fenced, generator output not) is the honest form of the rule; option 1 (move the generated scope block out of .claude/**, e.g. scripts/generated/) shrinks the anomaly instead — generated data was never instruction-tree prose, so relocating it makes the fence's path-prefix recognizer true again; option 3 keeps humans clicking merge on traffic no human judgement improves.
• Measured business pull: measured, 4-for-4 — every page-adding docs PR crosses the governed fence via the gate's own --write, and 3 of 4 merged with the crossing unrecorded. The cost is dilution of a governance control's signal, which this seat's own audit relies on every round.
• AI-agent error-resistance: a fence that fires on routine traffic trains every seat to read past it — the worst property a guardrail can have. Restoring "fence fires ⇒ a human should actually look" is the error-resistance win; both 1 and 2 achieve it, 3 only labels it.
• Startup scope discipline: 1 is a one-path move + gate-reader change; 2 requires the checker to run the generator to distinguish provenance (a real permanent mechanism); 3 is cheapest but leaves the dilution partly in place. Remove-the-anomaly (1) over build-the-mechanism (2) at this stage.

Recommendation: 1 now (relocate the generated artifact out of the fence), with 2 as the follow-up rule only if more --write targets accumulate under .claude/**. Options: 1 = move artifact out / 2 = provenance-aware fence / 3 = label the class governed:generated.
Confidence gap: no sweep has established whether OTHER generated artifacts already live under .claude/** (if several do, option 2's economics improve); and the body's own open question — whether ruling 5 was ever meant to cover generated artifacts — is prior to all three options: the filer's #9860 call (regeneration stands) is precedent-by-accident until confirmed or overturned here.

---

Generated by Claude Code