finding(gate): apps/console/docs/** is outside every documentation gate's scan surface — the console's operator guides are checked by nothing but check:control-bytes

[claude]

Measured on 2026-08-27 at da545f1a6 while rewriting apps/console/docs/error-tracking.md for #6599. Recording only; not fixed in that PR (out of scope).

What was measured

The three documentation gates all root their walk at content/docs (plus, for one, packages/<name>/README.md). None of them descends into apps/:

gate	scan root (read from the script)
check:doc-fences (check-doc-fence-languages.mjs)	const DOCS_ROOT = 'content/docs' + packages/<name>/README.md
check:doc-snippets (check-doc-snippet-types.mjs)	const DOCS_ROOT = 'content/docs'
check:doc-types (check-doc-component-types.mjs)	const DOCS_ROOT = 'content/docs' — its own comment says it "walks content/docs and nothing" else

Consequence for apps/console/docs/** (5 guides today): the only gate whose surface actually contains them is check:control-bytes, which enumerates git ls-files and therefore covers every tracked text file — i.e. they are checked for control bytes and for nothing else. eslint cannot judge them either: every files: glob in eslint.config.js is **/*.{ts,tsx}, so markdown is outside eslint entirely.

Why it is worth recording

This is the failure mode where a gate suite reports green over a file it never opened. #6599 is a concrete instance of what accumulates in that blind spot: apps/console/docs/error-tracking.md had drifted far enough that following it literally rebuilt the ungated telemetry init #5522 removed, and it also carried a fabricated CSP section plus two env vars (VITE_ENVIRONMENT, VITE_ERROR_ENDPOINT) with zero read sites anywhere in the tree. Nothing mechanical could have noticed any of it.

Relationship to existing cards

Adjacent but distinct — checked before filing:

• apps/console/README.md links twice to CONSOLE_ROADMAP.md, deleted in c988277ff — and no link gate can see it, because check-doc-links.mjs does not scan apps/** #4148 (closed) is the closest: same apps/**-is-unscanned shape, but specific to check-doc-links.mjs.
• check-doc-snippet-types.mjs collects only .mdx under content/docs — 40 .md guides are uncovered with no UNGATED_DOCS entry, contradicting its own "covered by default" rule #5174, finding(docs/gate): check-doc-component-types 的扫描面止于代码围栏 —— 八个 PR 新加的「真实 register 键表」全部在门外,且门从不判 namespace 半边 #5106 (open) are about .md vs .mdx collection within content/docs.
• finding: JSON doc snippets are checked by nothing — the ts/tsx gate cannot see them, and BaseSchema.passthrough() makes objectui validate accept arbitrary undeclared keys #5250, finding(docs): TypeScript examples fenced as plaintext escape check-doc-snippet-types — 211 blocks in 122 files, and #5044 proved one of them taught a type error under a gate that reports the file as covered #5867 (open) are about which fences inside covered files get read.

None of them covers "the apps/*/docs/** tree is not in any scan surface".

Not a recommendation to switch the gates on blindly

Extending DOCS_ROOT would pull these guides into check:doc-types / check:doc-snippets, which type-check snippets and validate type literals — the console guides are operator/deployment prose, and the honest first step is measuring how many blocks would newly be judged and whether the ratchets can absorb them, not flipping the root and taking whatever falls out.

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Finding round: graded, promoted to pm:queue, finding shed. Routed domain:devx — documentation gates are the engineering stream of the objectui three-way split, which crosses to the devx lane rather than staying with domain:ui. Type Task: no declaration is violated — check:doc-types' own comment honestly says it "walks content/docs and nothing else". The gates are not lying; they are simply not pointed at this tree.

⭐ What lifts this above a coverage-gap note is #6599's evidence of what actually accumulated in the blind spot. apps/console/docs/error-tracking.md had drifted far enough that following it literally rebuilds the ungated telemetry init that #5522 deliberately removed — plus a fabricated CSP section and two env vars (VITE_ENVIRONMENT, VITE_ERROR_ENDPOINT) with zero read sites anywhere in the tree. Documentation that instructs an operator to re-introduce something the platform removed on purpose is not stale prose; it is an active hazard, and nothing mechanical could have noticed any of it. Five guides sit in that tree today.

Scope — measure before flipping anything, and that ordering is the deliverable. The card is explicitly not recommending switching the gates on blindly and this seat endorses that:

1. Point the measurement (⛔ not the gates) at apps/*/docs/** and count how many blocks would newly be judged by check:doc-types and check:doc-snippets, and what verdicts they would get.
2. Report whether the ratchets can absorb that, and propose the root change on the strength of the number.
3. ⛔ Do not extend DOCS_ROOT and take whatever falls out. These are operator/deployment prose, not API guides — they will contain shell and config blocks that the snippet type-checker was never designed to judge, and a flood of new failures gets the extension reverted rather than fixed.

A measurement plus a proposal with no gate change is a complete delivery for this card. Say so in the dispatch order.

⚠️ Worth naming for whoever plans this: both devx seats are currently vacant (objectui #10602 ⏳, objectstack #6023 🔴). This card is graded and queued regardless — grading is not conditional on a seat being staffed, and a queued card is exactly what a returning seat needs to find. But it will not move until one is filled, and it is now one of several devx-lane items queued this round (#12719, #12723, #12730, #12749). Flagged in this round's report.

Dedup confirmed as filed, and the boundaries are drawn correctly: #4148 (closed) is the nearest — same apps/**-unscanned shape but specific to check-doc-links.mjs; #5174 / #5106 (open) concern .md vs .mdx collection within content/docs; #5250 / #5867 (open) concern which fences inside already-covered files get read. ⛔ None covers "the apps/*/docs/** tree is in no scan surface at all."

Measured at da545f1a6; re-verify the three DOCS_ROOT constants at dispatch rather than inheriting the table.

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round R40 (backfill after #6606 returned; batch=5)
Session: session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-6600-apps-docs-gate-surface
Worktree: objectui-issue-6600
Domain: domain:devx
File surface: measurement first — no gate change is owed by this card. If the measurement supports a change: scripts/check-doc-fence-languages.mjs, scripts/check-doc-snippet-types.mjs, scripts/check-doc-component-types.mjs (their DOCS_ROOT / scan-root logic and any UNGATED_DOCS-style exemption list) and their tests under scripts/__tests__/ (stop on breach; explain in the report). ⛔ No edits to apps/console/docs/** themselves (that is the ui lane's content; #6599 already rewrote one guide).
Container & model: M (measurement + proposal; a gate change only on the strength of the number), mode:subagent, model: opus. Tier is this seat's explicit decision (no dispatch-gates.mjs in objectui).
Clause-②: no
Serial constraints cleared: on origin/main 64d624ded all three gates still root at content/docs (check-doc-component-types.mjs:214, check-doc-fence-languages.mjs:144, check-doc-snippet-types.mjs:301); the apps/*/docs/** population is now 3 files (apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md, deployment.md, error-tracking.md), not the 5 the card measured — re-count. Recent churn on the gates: b83cd76a9 (#7100), ee851c32a (#6895). No in-flight PR in either lane touches these scripts; batch siblings (#6640 test infra · #6705 parity scanner · #6291 derivation gate · #7183 vitest dist project) are disjoint by construction. Adjacent open cards #5174 / #5106 / #5250 / #5867 concern collection or fences within content/docs — ⛔ not this card's surface.

---

Generated by Claude Code

[yinlianghui]

Dev claim (os-dev, measurement-first).

Session: session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-6600-apps-docs-gate-surface (pushed empty at 64d624ded before any edit)
Worktree: objectui-issue-6600

File surface: measurement first — no gate change is owed. If the number supports one: scripts/check-doc-fence-languages.mjs, scripts/check-doc-snippet-types.mjs, scripts/check-doc-component-types.mjs and their suites under scripts/__tests__/. No edits to apps/console/docs/** (ui lane content). Measurement runs against instrumented COPIES of the gate scripts under the scratchpad, never a mutation of the tracked files.

Deliverable per the 2026-08-27 triage: per-file/per-gate table of blocks that would newly be judged plus their verdicts, ratchet-absorption verdict, and a proposal with the number attached.

Generated by Claude Code

---

Generated by Claude Code