fix(docs): the snippet gate walks Lume's build output, so it fails on any checkout where the site has been built

[rickylabs]

Summary

deno task docs:snippets (landed in #1374 / PR #1537) walks docs/site/** with no exclusion for
docs/site/_site/ — Lume's build output, which is gitignored. So the gate fails on any
checkout where the documentation site has been built, on content that is entirely unmodified.

$ deno task docs:snippets
docs snippets: FAIL _site/ai/chat-ui/index.md:86: unclosed ``` fence
EXIT=1

_site/ai/chat-ui/index.md is generated output. The "unclosed fence" is an artifact of rendering,
not a defect in any source page.

Why this is more than a local annoyance

The doc-audit profile and this gate are mutually incompatible in the same worktree.
.llm/harness/workflow/doc-audit.md gate 2 is "Site build (Lume) clean with the changeset applied",
so every audited docs changeset builds the site by design — and from that moment the snippet gate
fails in that worktree until someone deletes 24MB of build output and knows to.

This already cost a real diagnostic detour: the 0.0.6 docs lane hit it immediately after #1537
merged, while running the new gate against the next docs PR. The failure names a file nobody edited,
so the natural first read is "the changeset broke a page".

CI is currently unaffected — pages.yml:48 runs docs:snippets immediately before
deno task build at :51, on a clean checkout. That ordering is load-bearing and undeclared: swap
those two steps, add a second consumer of the task, or run on a warm workspace, and CI inherits the
same false red.

Evidence

Verified at d558f9ab2:

1. docs/site/.gitignore:2 — _site/. The directory is untracked build output (~24MB).
2. grep -nE "_site|skipDir|exclude|ignore" .llm/tools/docs/snippet-extractor.ts .llm/tools/docs/check-snippets.ts → no matches. The walker has no exclusion mechanism at all.
3. Removing docs/site/_site/ and re-running: exit 0, scanned=578 … tier1=35 checked=21 exempt=14 outside_floor=260 malformed=0 — the census is unchanged, confirming the failure was
   entirely build output.
4. deno task docs:snippets is invoked from exactly one place (pages.yml:48), three lines before
   the Lume build.

Scope

• Exclude generated and ignored paths from the walk. _site/ at minimum; the robust form is to skip
  anything git ignores, so the next generated directory does not reintroduce this.
• Make the failure legible if it ever recurs: a diagnostic naming a path under a build directory
  should say so rather than reporting it as a source-page defect.
• Consider asserting the pages.yml step order (snippet gate before Lume build) in the existing
  pages-workflow_test.ts, which already asserts the trigger arms — the ordering is currently an
  undeclared invariant that CI silently depends on.

Boundaries

• test(docs): docs:accuracy is a fixed-string needle checker — no docs/site code block is ever compiled, and a CLI change never revalidates the site #1374 shipped this gate and is closed; this is a defect in what it shipped, not a re-opening of
  its contract. The census, floors, marker grammar and negative controls are all unaffected — the
  only change is which files the walker visits.
• Not a goal: changing coverage, the Tier-1 floor, or the exemption budget. A correct exclusion must
  leave scanned=578 … checked=21 exempt=14 exactly as it is today.

Acceptance criteria

• deno task docs:snippets exits 0 on a checkout where docs/site/_site/ exists.
• The census after the fix is byte-identical to today's on a clean checkout.
• Negative test: a built site present in the worktree does not change the gate's verdict.
• Negative test: a genuinely unclosed fence in a source page still fails, so the exclusion
  does not blunt the gate.

The second negative test is the one that matters — an exclusion that is too broad would silently
shrink coverage, which is the defect class #1374 exists to end.

Provenance

Found by the 0.0.6 documentation-lane orchestrator immediately after #1537 merged, while running the
newly landed gate against PR #1541's content. The interlock worked exactly as intended — this is the
gate's own blind spot, not the content's.

[rickylabs]

Absorbed into the 0.0.6 documentation lane as PR-G

Owner confirms this lane's remaining ownership is exactly #1377, #1531, #1554 and this issue. It ships as PR-G, fix/1565-snippet-gate-build-output, carrying Closes #1565, and is a lane deliverable rather than a filing — it will appear in lane closeout.

Placement

After #1541 merges, and before #1554 and #1531.

It does not compete with #1541 on files — that PR touches docs/site/** content, two READMEs and one type fixture; this one touches .llm/tools/docs/**. But file disjointness is not the binding constraint. Head immutability is: #1541 is mid-evaluation on an immutable head, and anything that moves it or invites a re-merge invalidates the generation and costs another evaluation cycle.

It goes before #1554 and #1531 because both of those run docs:snippets locally, and the doc-audit profile's gate 2 requires a site build. Each would otherwise build the site, poison its own worktree, and hit a false red on content it never touched. Landing this first means each pays that cost zero times instead of once. It also clears the trap for sibling lanes — the fixes/release coordinator already has it on their radar for their waves 3–4, since a slice that builds the site for a reproduction would inherit a red that is not its own.

The constraint that decides whether this fix is correct

The acceptance already states it and it is worth restating as the primary risk: the census must come back byte-identical —

scanned=578 ts=211 tsx=77 typescript=7 ts_like=295 tier1=35 checked=21 exempt=14 outside_floor=260 malformed=0

An exclusion that is too broad silently shrinks coverage, and a shrunken census reads as a healthier gate. That is precisely the defect class #1374 was built to end, so a fix for that gate must not reintroduce it. The second negative test on this issue is the guard: a genuinely unclosed fence in a source page must still fail after the exclusion lands.

Preferred shape, though the implementer decides: skip what git ignores, rather than hardcoding _site/. Hardcoding fixes today's directory and leaves the next generated one to rediscover this.

Interim workaround for anyone blocked before this lands

rm -rf docs/site/_site && deno task docs:snippets

If that turns the gate green, the red was build output rather than your changeset.