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:
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
Measured on 2026-08-27 at
da545f1a6while rewritingapps/console/docs/error-tracking.mdfor #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 intoapps/:check:doc-fences(check-doc-fence-languages.mjs)const DOCS_ROOT = 'content/docs'+packages/<name>/README.mdcheck: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 "walkscontent/docsand nothing" elseConsequence for
apps/console/docs/**(5 guides today): the only gate whose surface actually contains them ischeck:control-bytes, which enumeratesgit ls-filesand therefore covers every tracked text file — i.e. they are checked for control bytes and for nothing else.eslintcannot judge them either: everyfiles:glob ineslint.config.jsis**/*.{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.mdhad 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/**-is-unscanned shape, but specific tocheck-doc-links.mjs..mdxunder content/docs — 40.mdguides 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.mdvs.mdxcollection withincontent/docs.BaseSchema.passthrough()makesobjectui validateaccept 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_ROOTwould pull these guides intocheck:doc-types/check:doc-snippets, which type-check snippets and validatetypeliterals — 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