You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A 2026-07-04 audit of the 30 website docs pages (apps/gittensory-ui/src/routes/docs.*.tsx) found the same failure pattern repeatedly: a config/command/schema fact lives in exactly one place in code, and a docs page hand-copies it with no link back. Concretely, this shipped and went undocumented until caught by hand:
4 real GITTENSORY_REVIEW_* flags (_ENRICHMENT, _INLINE_COMMENTS, _PLANNER, _SCREENSHOTS)
an entire 9-command maintainer-only queue-digest family (queue-summary, confirmed-miners, review-now, needs-author, duplicate-clusters, burden-forecast, intake-health, outcome-patterns, noise-report)
None of this required a docs PR to ship, so nothing forced a docs update. This is the mechanical floor of a larger "keep docs in sync" effort (see the Phase 6 sibling issues on #1953) -- the part that can be a straight presence check, not an LLM judgment call.
Goal
A CI check, npm run docs:drift-check, wired into test:ci, that fails when:
A GITTENSORY_REVIEW_* flag declared in src/env.d.ts is missing from docs.tuning.tsx or docs.privacy-security.tsx.
A command id from either catalog in src/github/commands.ts (PUBLIC_MENTION_COMMAND_CATALOG, MAINTAINER_QUEUE_DIGEST_COMMAND_CATALOG) is missing (as @gittensory <id>) from docs.maintainer-workflow.tsx or docs.maintainer-install-trust.tsx.
A *GateMode field on RepositorySettings (src/types.ts) has no entry in a hand-maintained alias manifest inside the check script -- this part can't be a pure string match, since the same field is spelled differently per page (e.g. gate.size on docs.tuning.tsx's dotted YAML style vs. bare sizeGateMode on docs.how-reviews-work.tsx/docs.github-app.tsx). The manifest maps each field to its alias spellings and the pages that must mention at least one. The automatic part is verifying every REAL field has a manifest row (so a new field can't silently ship undocumented) plus that each row's aliases are actually present on its pages.
Requirements
Regex-based extraction (no TS compile step) from src/env.d.ts, src/github/commands.ts, src/types.ts. Guard every extraction with a minimum-count sanity floor (e.g. "expected 10+ flags, found 0") so a broken regex fails loudly instead of vacuously passing every check.
Plain node, matching scripts/check-ui-mcp-version-copy.mjs's style (no TS imports needed, so no tsx).
Exported pure functions + a main() guarded by process.argv[1] === fileURLToPath(import.meta.url), matching scripts/check-schema-drift.mjs's pattern.
Unit tests in test/unit/check-docs-drift-script.test.ts, including a "regression guard" test asserting the REAL current repo state passes cleanly (mirroring check-schema-drift-script.test.ts's own regression-guard test).
Wire docs:drift-check into test:ci immediately after ui:version-audit.
A new GITTENSORY_REVIEW_* flag, @gittensory command, or gate-mode field shipped without a doc update fails CI instead of silently drifting for weeks -- the same enforcement the codebase already applies to OpenAPI/schema parity via ui:openapi:settings-parity.
Context
A 2026-07-04 audit of the 30 website docs pages (apps/gittensory-ui/src/routes/docs.*.tsx) found the same failure pattern repeatedly: a config/command/schema fact lives in exactly one place in code, and a docs page hand-copies it with no link back. Concretely, this shipped and went undocumented until caught by hand:
GITTENSORY_REVIEW_*flags (_ENRICHMENT,_INLINE_COMMENTS,_PLANNER,_SCREENSHOTS)sizeGateMode,lockfileIntegrityGateMode,claGateMode,selfAuthoredLinkedIssueGateMode,moderationGateMode-- the last shipped by feat(selfhost): add a modular moderation-rules engine with a cross-repo violation ledger #2746 and was found undocumented while drafting this very issue)queue-summary,confirmed-miners,review-now,needs-author,duplicate-clusters,burden-forecast,intake-health,outcome-patterns,noise-report)None of this required a docs PR to ship, so nothing forced a docs update. This is the mechanical floor of a larger "keep docs in sync" effort (see the Phase 6 sibling issues on #1953) -- the part that can be a straight presence check, not an LLM judgment call.
Goal
A CI check,
npm run docs:drift-check, wired intotest:ci, that fails when:GITTENSORY_REVIEW_*flag declared insrc/env.d.tsis missing fromdocs.tuning.tsxordocs.privacy-security.tsx.src/github/commands.ts(PUBLIC_MENTION_COMMAND_CATALOG,MAINTAINER_QUEUE_DIGEST_COMMAND_CATALOG) is missing (as@gittensory <id>) fromdocs.maintainer-workflow.tsxordocs.maintainer-install-trust.tsx.*GateModefield onRepositorySettings(src/types.ts) has no entry in a hand-maintained alias manifest inside the check script -- this part can't be a pure string match, since the same field is spelled differently per page (e.g.gate.sizeon docs.tuning.tsx's dotted YAML style vs. baresizeGateModeon docs.how-reviews-work.tsx/docs.github-app.tsx). The manifest maps each field to its alias spellings and the pages that must mention at least one. The automatic part is verifying every REAL field has a manifest row (so a new field can't silently ship undocumented) plus that each row's aliases are actually present on its pages.Requirements
src/env.d.ts,src/github/commands.ts,src/types.ts. Guard every extraction with a minimum-count sanity floor (e.g. "expected 10+ flags, found 0") so a broken regex fails loudly instead of vacuously passing every check.node, matchingscripts/check-ui-mcp-version-copy.mjs's style (no TS imports needed, so notsx).main()guarded byprocess.argv[1] === fileURLToPath(import.meta.url), matchingscripts/check-schema-drift.mjs's pattern.test/unit/check-docs-drift-script.test.ts, including a "regression guard" test asserting the REAL current repo state passes cleanly (mirroringcheck-schema-drift-script.test.ts's own regression-guard test).docs:drift-checkintotest:ciimmediately afterui:version-audit.Deliverables
scripts/check-docs-drift.mjstest/unit/check-docs-drift-script.test.tspackage.json(docs:drift-checkscript +test:ciwiring)Expected outcomes
A new
GITTENSORY_REVIEW_*flag,@gittensorycommand, or gate-mode field shipped without a doc update fails CI instead of silently drifting for weeks -- the same enforcement the codebase already applies to OpenAPI/schema parity viaui:openapi:settings-parity.