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
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
checkRunMode → contextCheckMode — requires a DB migration, openapi update, and yml key alias.
Part of #5270 (roadmap epic).
Context
Two distinct GitHub check-runs exist with confusingly-similar controlling field names: the Gate check ("Gittensory Orb Review Agent") controlled by
reviewCheckMode, published viacreateOrUpdateGateCheckRun(); and the Context check ("Gittensory Context") controlled bycheckRunMode, published viacreateOrUpdateCheckRun().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:66correctly callsreviewCheckModethe gate's "master switch," but lines 298-300 saycheckRunMode"publishes the Gittensory Orb Review Agent check" — backwards;checkRunModepublishes Gittensory Context.apps/gittensory-ui/src/routes/docs.github-app.tsx:149-151says "Both are controlled per repo bycheckRunMode" — false for the Gate check — and self-contradicts the same file's own lines 168-169, which correctly namereviewCheckModeas the gate's authority.Separately,
src/review/repo-profile.ts:58-62's comment lumps live-and-activecheckRunModetogether with genuinely-deprecatedgateCheckModeas "legacy fields kept only for API/back-compat display and no longer drive this decision" — inaccurate forcheckRunMode, which actively gates the Context check's publication in production (settings-preview.ts:109,backfill.ts,processors.ts:9603).checkRunModealso has zero JSDoc on its own declaration (types.ts:709), unlike its neighborreviewCheckMode.An operator trusting either bad passage could believe they've enabled required-check enforcement (Gittensory Orb Review Agent) via
checkRunModewhen they haven't — a real misconfiguration risk for the product's core gating mechanism.scripts/check-docs-drift.mjsstructurally cannot catch this —checkRunModeisn't a*GateModefield so it's outsideGATE_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
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;checkRunDetailLevelonly affects the Context check's output.src/review/repo-profile.ts:59-60— scope the "legacy" claim togateCheckModeonly; statecheckRunModeis live and independently governs the Context check.checkRunMode(types.ts:709) cross-referencingreviewCheckModeand pointing at README's disambiguation section.checkRunDetailLeveloption still listed atdocs.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
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-716vs718-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-169checkRunMode→contextCheckMode— requires a DB migration, openapi update, and yml key alias.Part of #5270 (roadmap epic).