[CI] Docs tier-drift's path filter watches the templates but not docs/guide, so a change to the generated output alone skips the only gate that checks it

[azchohfi]

Summary

docs/guide/*.md is generated from docs/_pipeline/templates/*.md.dt. The only gate that detects drift between them is the Docs tier-drift CI job — and its path filter watches the templates, not the generated output.

A change that touches only docs/guide/*.md and leaves the template untouched sets docs-templates=false, skips the job, and ships with no gate at all.

OBSERVED_AT 2026-08-01T13:45:35Z    main = 1ed2644e

.github/workflows/ci.yml:71
  if echo "$files" | grep -qE '^(docs/_pipeline/templates/|docs/_pipeline/apps/|src/Reactor\.Cli/Docs/)'; then
    docs-templates=true

  'docs/_pipeline' in the filter block : True
  'docs/guide'     in the filter block : FALSE     <- the artifact it protects

No unit-test gate compensates

The other two generated artifacts in this repo are gated by tests that run in the Unit Tests leg, which executes on every non-Markdown change:

artifact	gate	runs when
samples/ReactorGallery/reactor-search-index.json	SearchIndexGeneratorTests.Index_IsUpToDate	every non-md change
skills/reactor.api.txt (+ plugins copy)	ApiIndexGeneratorTests	every non-md change
docs/guide/*.md	Docs tier-drift CI job only	only when a template/app/CLI path changes

Searched every test referencing md.dt — CrossLinkLintTests, DiagramTests, TierLintTests, TierLintOrchestratorTests, FlexPanelCssBehaviorFixtures, VersionSingleSourceTests. The only one touching both docs/guide and a compile step is VersionSingleSourceTests, and it is version-only — seven tests about version literals/tokens, Assert.Equal occurrences: 0.

Why this is reachable, not theoretical

Found while verifying a merge. git merge-tree on two open PRs reports:

CONFLICT (content): ... 5 files ...
Auto-merging docs/_pipeline/templates/data-system.md.dt
Auto-merging docs/guide/data-system.md                    <- generated output, SILENT
Auto-merging tests/.../DataGridEditFixtures.cs

Git merges the template and its generated output as two unrelated text files. It can interleave two generated outputs into a file the generator would never emit, and no conflict marker appears on either.

In that particular merge the template also changes, so the gate would fire. That is incidental. Any of these skips it:

• a merge where only one side changed the template, so only the output auto-merges
• a hand-edit of docs/guide/*.md (forbidden by AGENTS.md — and this gate is what enforces it)
• a revert or cherry-pick touching only the output

The absence of a conflict marker is not evidence that regeneration can be skipped — and here nothing downstream will catch it either.

Suggested fix

Add docs/guide/ to the docs-templates filter at ci.yml:71:

if echo "$files" | grep -qE '^(docs/_pipeline/templates/|docs/_pipeline/apps/|src/Reactor\.Cli/Docs/|docs/guide/)'; then

The job already does the right comparison (docs compile --no-screenshots --ci then fails with "docs/guide is out of date with the doc templates" at :670) — it simply is not invited to run when only its subject changes.

Non-vacuity check for the fix: modify one byte of a committed docs/guide/*.md without touching any template, and confirm Docs tier-drift runs and fails. Under the current filter it does not run at all.

---

Surfaced by the #1010 session's observation that merge-tree's auto-merge lines matter more than its conflict list; filter and gate coverage verified independently here.

[azchohfi]

Reachability confirmed: both sides of a live merge edit BOTH the template and its generated output, and one deletes lines from each

OBSERVED_AT 2026-08-01T14:05:37Z    added/deleted vs main
pr1010   docs/_pipeline/templates/data-system.md.dt   9 / 0
pr1016   docs/_pipeline/templates/data-system.md.dt   9 / 2
pr1010   docs/guide/data-system.md                    9 / 0
pr1016   docs/guide/data-system.md                    9 / 2

git merge-tree on that pair auto-merges both files with no conflict marker. Git treats the generated
output and its template as two unrelated text files, so the merged .md is not necessarily what
mur docs compile emits from the merged .dt — and with docs/guide/ absent from the docs-templates
filter, a merge that touched only the output would not even run the job that checks.

In this pair the template also changes, so the gate would fire. That is incidental, not protective.

Verbatim from the session that found it, because it is the general form:

"The patch is relative to their branch, so my check only showed my ADDITIONS land consistently on their
tree — it never showed the merged .md is what the generator emits from the merged .dt. My check was
narrower than the claim I hung on it."

[azchohfi]

The mechanism that makes this reachable by a careful person: the generated docs carry PROSE, and prose conflicts look hand-resolvable

The issue above establishes that a docs/guide/-only change skips the gate. The obvious objection is
"who hand-edits generated output?" — and without an answer this reads as a guard against carelessness.
Measured today on an open PR, here is the answer.

docs/guide/analyzer-architecture.md is generated, and alongside its diagnostic tables it carries
paragraphs making semantic claims. On #1015 at d26dcbd5:

main   `ElementPool.CleanElement` clears far more attached properties than instance ones,
       so this was the larger half of REACTOR_POOL_001's subject matter...

#1015  `ElementPool.CleanElement` USED TO CLEAR far more ... Issue #985 HAS SINCE CLOSED
       THE GAP from the other side (the receiver-gated Padding/CornerRadius/Border*/
       Background/IsEnabled chain), SO THE TWO HALVES ARE NOW COMPARABLE IN SIZE.

Meanwhile the diagnostic table rows are byte-identical across the change:

MOD_003  ROW CHANGED : False
POOL_001 ROW CHANGED : False

Three consequences for this issue

1. Prose is the content class that invites hand-resolution. A conflict in a generated table looks
machine-owned and prompts a regenerate. A conflict in two paragraphs of English looks like an ordinary
text merge, and the conflict markers are physically in the .md, so that is where a careful person
resolves it — touching only docs/guide/, setting docs-templates=false, and skipping the only gate.

2. Structural checks cannot substitute. Any count-, row-, or schema-based check on these files reports
no change across the diff above. The rows held steady while the meaning moved — so the compensating
gate people would reach for first is exactly the one that cannot see this.

3. It is not hypothetical for the pending merges. docs/guide/data-system.md auto-merges silently on
the #1010 -> #1016 pair (already in the body), and docs/guide/analyzer-architecture.md is modified by
#1015. Both are generated files whose diffs contain prose, and neither is gated unless the same commit
also happens to touch a template.

Sharpening the title's implication

"Gate-agnostic" and "ungated" are the same measurement with opposite valence — one says nothing depends
on it, the other says nothing checks it. These files were described to me as the former by a session
reporting blast radius. They are the latter, which argues for more care rather than less, and a word that
reports a risk as a reassurance is worse than a wrong number: a wrong number invites a re-measurement.

Suggested fix is unchanged and one line — add docs/guide/ to the ci.yml:71 filter so a
generated-output-only change still runs Docs tier-drift. It is a strict widening: no currently-passing
change starts failing unless it genuinely drifted from its template.