Skip to content

feat(ci): add a docs-drift check for GITTENSORY_REVIEW_* flags, @gittensory commands, and gate-mode dimensions #3047

Description

@JSONbored

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:

  • 4 real GITTENSORY_REVIEW_* flags (_ENRICHMENT, _INLINE_COMMENTS, _PLANNER, _SCREENSHOTS)
  • 5 real gate-mode dimensions (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)
  • 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:

  1. A GITTENSORY_REVIEW_* flag declared in src/env.d.ts is missing from docs.tuning.tsx or docs.privacy-security.tsx.
  2. 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.
  3. 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.

Deliverables

  • scripts/check-docs-drift.mjs
  • test/unit/check-docs-drift-script.test.ts
  • package.json (docs:drift-check script + test:ci wiring)

Expected outcomes

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.

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.

Projects

Status
In Progress

Relationships

None yet

Development

No branches or pull requests

Issue actions