Skip to content

Widen check-docs-drift.mjs to cover the full config surface #4617

Description

@JSONbored

Context

Part of the review-stack architecture audit (parent epic — config-sprawl dimension).

scripts/check-docs-drift.mjs is a real, CI-enforced (npm run docs:drift-check, part of test:ci)
guard against config fields existing in code but missing from .gittensory.yml.example/docs — but it is
narrowly scoped to two extraction regexes: GITTENSORY_REVIEW_[A-Z0-9_]+ env flags, and fields matching
literal [a-zA-Z]+GateMode in src/types.ts (hand-enumerated in a 13-row GATE_MODE_MANIFEST,
check-docs-drift.mjs:51-65). Of the ~140+ fields across RepositorySettings and its nested config
types, only these 13 *GateMode fields have any automated documentation guarantee — everything else
(labels, autonomy, moderation, anti-abuse caps, AI-review sub-options, and the entire separate
FocusManifest/yml-only surface: wantedPaths, features, contentLane, review.* sub-block,
visual.*, etc.) relies on manual diligence.

Concrete instances this gap already produced

  • agentGlobalFreezeOverride (src/types.ts:1055): a DB column, OpenAPI field, read at ~20 call
    sites in src/queue/processors.ts plus src/github/client.ts:589,
    src/services/agent-action-executor.ts, src/mcp/server.ts:3266 — fully live. Appears nowhere in
    .gittensory.yml.example, config/examples/*.yml, or any docs page. A self-hoster who wants to
    re-activate one repo during a fleet-wide DB freeze has no way to discover this exists short of reading
    src/db/schema.ts.
  • review.visual.production_url (packages/gittensory-engine/src/focus-manifest.ts:722-728,2606):
    fully parsed, SSRF-validated, wired into screenshot base-URL resolution
    (src/review/visual/capture.ts:376-407) — the maintainer's own most recently shipped feature
    (PR fix(review): per-repo review.visual.production_url override for bot-capture #4564). .gittensory.yml.example's visual: block (lines 1006-1057), which explicitly claims to
    be "kept in sync by CI," never mentions it — because it lives in a different type
    (FocusManifest in packages/gittensory-engine) in a different package from RepositorySettings
    in src/types.ts, structurally invisible to the current checker.

Fix

  1. Widen check-docs-drift.mjs to enumerate every RepositorySettings field (not just *GateMode) and
    every parseable key in the FocusManifest type, not just the hand-picked list.
  2. As an immediate follow-up, document agentGlobalFreezeOverride and review.visual.production_url in
    .gittensory.yml.example (or the appropriate reference doc) so this checker starts green rather than
    immediately failing on rollout.

Acceptance criteria

  • check-docs-drift.mjs covers the full RepositorySettings + FocusManifest surface, not just
    *GateMode fields and GITTENSORY_REVIEW_* env flags.
  • agentGlobalFreezeOverride and review.visual.production_url are documented and pass the widened
    checker.
  • npm run docs:drift-check still passes for all other currently-documented fields (no false
    positives introduced).

Metadata

Metadata

Assignees

Labels

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

Projects

Status
Done

Relationships

None yet

Development

No branches or pull requests

Issue actions