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
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
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.
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).
Context
Part of the review-stack architecture audit (parent epic — config-sprawl dimension).
scripts/check-docs-drift.mjsis a real, CI-enforced (npm run docs:drift-check, part oftest:ci)guard against config fields existing in code but missing from
.gittensory.yml.example/docs — but it isnarrowly scoped to two extraction regexes:
GITTENSORY_REVIEW_[A-Z0-9_]+env flags, and fields matchingliteral
[a-zA-Z]+GateModeinsrc/types.ts(hand-enumerated in a 13-rowGATE_MODE_MANIFEST,check-docs-drift.mjs:51-65). Of the ~140+ fields acrossRepositorySettingsand its nested configtypes, only these 13
*GateModefields 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 callsites in
src/queue/processors.tsplussrc/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 tore-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'svisual:block (lines 1006-1057), which explicitly claims tobe "kept in sync by CI," never mentions it — because it lives in a different type
(
FocusManifestinpackages/gittensory-engine) in a different package fromRepositorySettingsin
src/types.ts, structurally invisible to the current checker.Fix
check-docs-drift.mjsto enumerate everyRepositorySettingsfield (not just*GateMode) andevery parseable key in the
FocusManifesttype, not just the hand-picked list.agentGlobalFreezeOverrideandreview.visual.production_urlin.gittensory.yml.example(or the appropriate reference doc) so this checker starts green rather thanimmediately failing on rollout.
Acceptance criteria
check-docs-drift.mjscovers the fullRepositorySettings+FocusManifestsurface, not just*GateModefields andGITTENSORY_REVIEW_*env flags.agentGlobalFreezeOverrideandreview.visual.production_urlare documented and pass the widenedchecker.
npm run docs:drift-checkstill passes for all other currently-documented fields (no falsepositives introduced).