Skip to content

Fix docs that describe checkRunMode/reviewCheckMode backwards #5283

Description

@JSONbored

Context

Two distinct GitHub check-runs exist with confusingly-similar controlling field names: the Gate check ("Gittensory Orb Review Agent") controlled by reviewCheckMode, published via createOrUpdateGateCheckRun(); and the Context check ("Gittensory Context") controlled by checkRunMode, published via createOrUpdateCheckRun().

The codebase's own docs get this backwards in two locations, one self-contradicting internally:

  • apps/gittensory-ui/src/routes/docs.how-reviews-work.tsx:66 correctly calls reviewCheckMode the gate's "master switch," but lines 298-300 say checkRunMode "publishes the Gittensory Orb Review Agent check" — backwards; checkRunMode publishes Gittensory Context.
  • apps/gittensory-ui/src/routes/docs.github-app.tsx:149-151 says "Both are controlled per repo by checkRunMode" — false for the Gate check — and self-contradicts the same file's own lines 168-169, which correctly name reviewCheckMode as the gate's authority.

Separately, src/review/repo-profile.ts:58-62's comment lumps live-and-active checkRunMode together with genuinely-deprecated gateCheckMode as "legacy fields kept only for API/back-compat display and no longer drive this decision" — inaccurate for checkRunMode, which actively gates the Context check's publication in production (settings-preview.ts:109, backfill.ts, processors.ts:9603). checkRunMode also has zero JSDoc on its own declaration (types.ts:709), unlike its neighbor reviewCheckMode.

An operator trusting either bad passage could believe they've enabled required-check enforcement (Gittensory Orb Review Agent) via checkRunMode when they haven't — a real misconfiguration risk for the product's core gating mechanism. scripts/check-docs-drift.mjs structurally cannot catch this — checkRunMode isn't a *GateMode field so it's outside GATE_MODE_MANIFEST.

Note: .gittensory.yml.example:562-568, docs.github-app.tsx:168+, and README's "Check-run and comment surfaces, disambiguated" section already state this correctly — the fix is confined to the two bad passages plus the internal code comment.

Requirements

  • Only fix the two identified bad doc passages + the misleading code comment + missing JSDoc; do not attempt a repo-wide rewrite (most surfaces are already correct).

Deliverables

  • docs.how-reviews-work.tsx:298-300 — correct the check name to "Gittensory Context."
  • docs.github-app.tsx:149-151 — split the sentence: Gate check → reviewCheckMode; Context check → checkRunMode; checkRunDetailLevel only affects the Context check's output.
  • src/review/repo-profile.ts:59-60 — scope the "legacy" claim to gateCheckMode only; state checkRunMode is live and independently governs the Context check.
  • Add a short JSDoc to checkRunMode (types.ts:709) cross-referencing reviewCheckMode and pointing at README's disambiguation section.
  • While in these three files, also fix the stale "deep" checkRunDetailLevel option still listed at docs.how-reviews-work.tsx:301, docs.tuning.tsx:477, docs.github-app.tsx:152 — the type was narrowed to "minimal" | "standard" only (types.ts:705-706, Resolve dead config branches (wire or remove) #4620) and "deep" was never removed from prose.

Expected Outcome

An operator reading either docs page gets the correct field→check-run mapping; no page contradicts another page.

Links & Resources

  • Evidence: src/types.ts:709,612-626,726-728; src/db/schema.ts:51,53,57; src/review/check-names.ts:3-5; src/github/app.ts:695-716 vs 718-750; src/signals/settings-preview.ts:109; src/review/repo-profile.ts:57-62; docs.how-reviews-work.tsx:66,298-301; docs.github-app.tsx:149-152,168-169
  • Optional larger follow-up (separate ticket, not in scope here): rename checkRunModecontextCheckMode — requires a DB migration, openapi update, and yml key alias.

Part of #5270 (roadmap epic).

Metadata

Metadata

Assignees

Labels

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

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions