rvlib-shipkit 1.3.0 → 1.5.0

package/src/core/runs.ts

@@ -0,0 +1,242 @@
+// WHERE A CHECK RUNS AND HOW ITS ANSWER IS KEPT, declared in full by every
+// check, with no default anywhere.
+//
+// Every context that can run a check body or its repair is one key of `runs`,
+// plus `fix` (which command applies the repair), `cache` (how the answer is
+// kept) and `applies` (whether this repo gives it anything to do). A check
+// file writes every key. A row with no file to say it in (a floor slot, a
+// config task, a legacy form) gets every key from the code that derives it,
+// with the reason, so no row ever resolves to a value nobody wrote.
+//
+// the one constraint a reader breaks first: a missing key is a load error,
+// never a default. `runsProblem` and `cacheProblem` are the only judges, and
+// `check()` calls both at import time.
+import type { CheckEnv } from '../check.ts'
+import { cadenceOf, ONCE, type Every, type WhenInactiveDecl } from '../plan/cadence.ts'
+import { parseDuration } from './wire.ts'
+
+// ── the declaration ──────────────────────────────────────────────────────
+
+/** the pre-commit hook: never, or in process on the working tree under a
+ *  budget of at most PRE_COMMIT_MAX_MS */
+export type OnPreCommit = false | { budgetMs: number }
+/** the daemon after a quiet save burst: never, only when the check's key
+ *  moved, or after every burst */
+export type OnSave = false | 'moved' | 'burst'
+/** the daemon on its own time: never, once while no answer exists for the
+ *  fact's key, or on a period with what to do while the repo is inactive */
+export type OnClock = false | 'once' | { every: Every; inactive: WhenInactiveDecl }
+
+export type Runs = {
+    /** `git commit`, in the pre-commit hook, before the message */
+    onPreCommit: OnPreCommit
+    /** `shipkit ci`: the gate an agent runs once before it pushes its work,
+     *  and a whole run from the hub's run button */
+    onCi: boolean
+    /** `shipkit ci --full`: the full tests tier. Every `onCi` row is here too */
+    onFull: boolean
+    /** the preflight of `shipkit bump` and `shipkit release`: full tier,
+     *  frozen, no cache read, no repair */
+    onRelease: boolean
+    /** `shipkit check`, the TUI checks panel, the hub health run */
+    onHealth: boolean
+    /** the daemon, after a quiet save burst in the repo */
+    onSave: OnSave
+    /** the daemon, on its own time */
+    onClock: OnClock
+}
+
+/** which command applies the check's `repair`: none exists, the gate's fix
+ *  pass (and `shipkit check --fix`), or only `shipkit check --fix <id>` */
+export type FixWhen = 'none' | 'ci' | 'manual'
+
+/** how an answer is kept. Every variant names its one parameter */
+export type CacheDecl =
+    /** keyed on the content of these repo paths (and the check's own code) */
+    | { by: 'files'; inputs: string[]; key: ((env: CheckEnv) => string) | null }
+    /** keyed on what the body read through its context, re-checked before a replay */
+    | { by: 'reads' }
+    /** a clean answer about the world keeps for `span` */
+    | { by: 'ttl'; span: string; key: ((env: CheckEnv) => string) | null }
+    /** a decided fact, keyed on the declared value alone, never expires */
+    | { by: 'fact'; key: (env: CheckEnv) => string }
+    /** no key can describe it, with the reason: measured every time */
+    | { by: 'never'; why: string }
+
+export type CacheBy = CacheDecl['by']
+
+/** whether this repo gives the check anything to do. A reason back makes the
+ *  row n/a in every context: never run, never planned, shown with the reason */
+export type Applies = 'always' | ((env: CheckEnv) => string | null)
+
+export const RUNS_KEYS = ['onPreCommit', 'onCi', 'onFull', 'onRelease', 'onHealth', 'onSave', 'onClock'] as const
+export type RunsAxis = (typeof RUNS_KEYS)[number]
+export const CACHE_BY: readonly CacheBy[] = ['files', 'reads', 'ttl', 'fact', 'never']
+export const FIX_WHEN: readonly FixWhen[] = ['none', 'ci', 'manual']
+
+/** the ceiling a pre-commit check may declare. The hook boots in about
+ *  500ms, and the text gates it already runs cost 50 to 100ms together, so a
+ *  check that needs more than this belongs in `onCi` */
+export const PRE_COMMIT_MAX_MS = 100
+
+// ── the judges ───────────────────────────────────────────────────────────
+
+const isBool = (v: unknown): v is boolean => typeof v === 'boolean'
+
+function everyProblem(v: unknown): string | null {
+    if (typeof v === 'function') return null
+    if (v == null || v === ONCE) return `onClock.every takes a span, a range, a cron or a function, never ${JSON.stringify(v)} (use onClock: false or 'once')`
+    const c = cadenceOf(v as Every & (string | [string, string]), '')
+    return typeof c === 'string' ? `onClock.every: ${c}` : null
+}
+
+/** what is wrong with a `runs` object, or null. Every key is required */
+export function runsProblem(r: unknown): string | null {
+    if (r == null || typeof r !== 'object') return `runs is required: { ${RUNS_KEYS.join(', ')} }, every key explicit`
+    const o = r as Record<string, unknown>
+    const missing = RUNS_KEYS.filter((k) => !(k in o))
+    if (missing.length > 0) return `runs is missing ${missing.join(', ')}: every key is explicit, no default`
+    const unknown = Object.keys(o).filter((k) => !(RUNS_KEYS as readonly string[]).includes(k))
+    if (unknown.length > 0) return `runs has unknown key ${unknown.join(', ')} (the keys: ${RUNS_KEYS.join(', ')})`
+    const p = o.onPreCommit
+    if (p !== false) {
+        const b = (p as { budgetMs?: unknown } | null)?.budgetMs
+        if (p == null || typeof p !== 'object' || typeof b !== 'number' || !Number.isInteger(b) || b < 1 || b > PRE_COMMIT_MAX_MS)
+            return `runs.onPreCommit takes false or { budgetMs: 1..${PRE_COMMIT_MAX_MS} }`
+    }
+    for (const k of ['onCi', 'onFull', 'onRelease', 'onHealth'] as const) if (!isBool(o[k])) return `runs.${k} takes true or false`
+    if (o.onSave !== false && o.onSave !== 'moved' && o.onSave !== 'burst') return `runs.onSave takes false, 'moved' or 'burst'`
+    const c = o.onClock
+    if (c !== false && c !== ONCE) {
+        if (c == null || typeof c !== 'object') return `runs.onClock takes false, 'once' or { every, inactive }`
+        const cc = c as { every?: unknown; inactive?: unknown }
+        if (!('every' in cc) || !('inactive' in cc)) return `runs.onClock takes { every, inactive }, both keys explicit`
+        const e = everyProblem(cc.every)
+        if (e != null) return `runs.${e}`
+        if (typeof cc.inactive !== 'function' && cc.inactive !== 'run' && cc.inactive !== 'wait') return `runs.onClock.inactive takes 'run', 'wait' or a function returning one`
+    }
+    if (o.onCi === true && o.onFull !== true) return `runs.onCi true needs onFull true: the full gate is the quick gate plus more`
+    return null
+}
+
+/** what is wrong with a `cache` object, or null */
+export function cacheProblem(c: unknown): string | null {
+    if (c == null || typeof c !== 'object') return `cache is required: { by: ${CACHE_BY.map((b) => `'${b}'`).join(' | ')}, ... }`
+    const o = c as Record<string, unknown>
+    const want: Record<CacheBy, string[]> = { files: ['inputs', 'key'], reads: [], ttl: ['span', 'key'], fact: ['key'], never: ['why'] }
+    const by = o.by as CacheBy
+    if (!CACHE_BY.includes(by)) return `cache.by takes ${CACHE_BY.map((b) => `'${b}'`).join(', ')}`
+    const keys = want[by]
+    const missing = keys.filter((k) => !(k in o))
+    if (missing.length > 0) return `cache { by: '${by}' } is missing ${missing.join(', ')}: every key is explicit`
+    const unknown = Object.keys(o).filter((k) => k !== 'by' && !keys.includes(k))
+    if (unknown.length > 0) return `cache { by: '${by}' } has unknown key ${unknown.join(', ')} (it takes ${keys.length === 0 ? 'nothing else' : keys.join(', ')})`
+    if (by === 'files' && (!Array.isArray(o.inputs) || o.inputs.length === 0 || o.inputs.some((p) => typeof p !== 'string' || p === ''))) return `cache.inputs is a non empty list of repo relative paths`
+    if ((by === 'files' || by === 'ttl') && o.key !== null && typeof o.key !== 'function') return `cache.key is null or a function of { root, config }`
+    if (by === 'fact' && typeof o.key !== 'function') return `cache { by: 'fact' } needs key: a function of { root, config } returning the declared value`
+    if (by === 'ttl') {
+        if (typeof o.span !== 'string') return `cache.span is a duration, as in '24h'`
+        try { if (parseDuration(o.span) <= 0) return `cache.span must be above zero` } catch (e) { return `cache.span: ${(e as Error).message}` }
+    }
+    if (by === 'never' && (typeof o.why !== 'string' || o.why.trim() === '')) return `cache { by: 'never' } needs why: the reason no key can describe it`
+    return null
+}
+
+/** what a whole declaration must satisfy together, or null */
+export type WholeDecl = { runs: Runs; cache: CacheDecl; fix: FixWhen; repair: unknown; build: boolean; body: 'run' | 'cmd'; blocking: boolean }
+
+export function combinationProblem(d: WholeDecl): string | null {
+    const { runs: r, cache: c } = d
+    if (!FIX_WHEN.includes(d.fix)) return `fix takes 'none', 'ci' or 'manual'`
+    if (d.fix !== 'none' && typeof d.repair !== 'function') return `fix '${d.fix}' needs a repair function`
+    if (d.fix === 'none' && d.repair != null) return `a repair function needs fix 'ci' or 'manual', never 'none'`
+    if (d.fix === 'ci' && !r.onCi) return `fix 'ci' needs onCi true: the gate's fix pass runs the body first, so a check the gate does not run would run there anyway. Say 'manual'`
+    if (d.build && (r.onHealth || r.onPreCommit !== false || d.fix !== 'none'))
+        return `a build step runs only in gates: onHealth false, onPreCommit false, fix 'none' (a tool repairs its own findings)`
+    if (r.onPreCommit !== false) {
+        if (d.body === 'cmd') return `onPreCommit needs an in process run body, never a cmd`
+        if (!d.blocking) return `onPreCommit needs blocking true: the hook only refuses, it never warns about the world`
+        if (c.by === 'ttl' || c.by === 'fact' || c.by === 'never') return `onPreCommit needs cache files or reads: the hook reads the tree, never the world`
+    }
+    if (r.onSave === 'moved' && (c.by === 'ttl' || c.by === 'never')) return `onSave 'moved' needs cache files, reads or fact: nothing can move under ${c.by}`
+    if (r.onClock === ONCE && c.by !== 'fact') return `onClock 'once' needs cache fact: once means while no answer exists for the fact's key`
+    if (c.by === 'fact' && r.onClock !== ONCE) return `cache fact needs onClock 'once': a fact nobody runs once is a fact never answered`
+    if (c.by === 'reads' && d.body === 'cmd') return `cache reads needs a run body: a subprocess records no reads, say files or never`
+    const triggered = r.onPreCommit !== false || r.onCi || r.onFull || r.onRelease || r.onHealth || r.onSave !== false || r.onClock !== false
+    // an opt in build step (a deploy) is the one row nothing but a name runs:
+    // `shipkit ci --with <id>` asks it on purpose
+    if (!triggered && d.fix === 'none' && !d.build) return `nothing runs it: every trigger is false and fix is 'none'. Delete the file, turn it off in the repo with a reason, or make it an opt in build step (build: true)`
+    return null
+}
+
+// ── the resolved row ─────────────────────────────────────────────────────
+
+/** where one resolved value came from */
+export type RunsSource = 'check file' | 'repo.config.ts' | 'derived'
+
+export type ResolvedRuns = Runs & {
+    fix: FixWhen
+    /** a reason the row runs in no context: the repo turned it off, or it
+     *  does not apply here. Null for a live row */
+    off: string | null
+    /** where each value came from */
+    source: Record<RunsAxis | 'fix', RunsSource>
+    /** why a derived row has the values it has, null for a declared one */
+    derivedWhy: string | null
+}
+
+/** every value from one source */
+export function sourced(r: Runs, fix: FixWhen, from: RunsSource, derivedWhy: string | null = null, off: string | null = null): ResolvedRuns {
+    const source = Object.fromEntries([...RUNS_KEYS, 'fix'].map((k) => [k, from])) as ResolvedRuns['source']
+    return { ...r, fix, off, source, derivedWhy }
+}
+
+/** runs in no context at all */
+export const NOWHERE: Runs = { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: false, onSave: false, onClock: false }
+
+/** the context a runner asks about */
+export type RunContext = 'preCommit' | 'ci' | 'full' | 'release' | 'health'
+
+/** does this context run the row? Off is never */
+export function runsIn(r: ResolvedRuns, ctx: RunContext): boolean {
+    if (r.off != null) return false
+    switch (ctx) {
+        case 'preCommit': return r.onPreCommit !== false
+        case 'ci': return r.onCi
+        case 'full': return r.onFull
+        case 'release': return r.onRelease
+        case 'health': return r.onHealth
+    }
+}
+
+/** the daemon plans it at all */
+export const planned = (r: ResolvedRuns): boolean => r.off == null && (r.onSave !== false || r.onClock !== false)
+
+/** the one line a surface prints for a row that is off */
+export const offLine = (id: string, r: ResolvedRuns): string => `${id} off: ${r.off ?? '(no reason)'}`
+
+/** the cell a matrix prints for one axis */
+export function cellText(r: ResolvedRuns, k: RunsAxis | 'fix'): string {
+    const v = k === 'fix' ? r.fix : r[k]
+    if (v === true) return 'yes'
+    if (v === false) return '·'
+    if (typeof v === 'string') return v
+    if (k === 'onPreCommit') return `${(v as { budgetMs: number }).budgetMs}ms`
+    const c = v as { every: Every; inactive: WhenInactiveDecl }
+    const every = typeof c.every === 'function' ? 'fn' : Array.isArray(c.every) ? `${c.every[0]}..${c.every[1]}` : String(c.every)
+    return `${every}${c.inactive === 'run' ? ' (runs inactive)' : ''}`
+}
+
+/** a files cache as one short cell: three paths, then a count */
+export const filesText = (inputs: string[]): string => `files ${inputs.length <= 3 ? inputs.join(' ') : `${inputs.slice(0, 3).join(' ')} +${inputs.length - 3}`}`
+
+/** the cache variant as one short cell */
+export function cacheText(c: CacheDecl): string {
+    switch (c.by) {
+        case 'files': return filesText(c.inputs)
+        case 'reads': return 'reads'
+        case 'ttl': return `ttl ${c.span}`
+        case 'fact': return 'fact'
+        case 'never': return `never: ${c.why}`
+    }
+}

package/src/core/update-policy.ts

@@ -2,6 +2,8 @@
 // startup self-update and `shipkit fleet --update`. An automatic update never
 // crosses a breaking boundary. It reports the jump and names the one command
 // that takes it on purpose.
+import { lstatSync } from 'fs'
+import { join } from 'path'
 
 /** set by `shipkit fleet --update --major` on the repo run it spawns */
 export const ALLOW_MAJOR_ENV = 'SHIPKIT_ALLOW_MAJOR'
@@ -23,3 +25,21 @@ export function isBreaking(installed: string, latest: string): boolean {
  *  name, which is what `fleet --only` matches */
 export const breakingAdvice = (name: string, latest: string, repo: string): string =>
     `${name} ${latest} available (breaking): run \`shipkit fleet --update --major --only ${repo}\``
+
+/** the lowest version a semver pin admits (`^1.3.0` → 1.3.0, `1.3.0` →
+ *  1.3.0), null for anything else (`link:`, a tag, a url, a range with two
+ *  ends). What a fresh clone of the repo installs is judged from this */
+export function pinFloor(spec: string): string | null {
+    const m = /^(?:[\^~]|>=|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(spec.trim())
+    return m?.[1] ?? null
+}
+
+/** true when node_modules/<name> is a symlink (`bun link <name>`): it then
+ *  carries a source tree, whose version says nothing about what the repo pins */
+export function isLinkedInstall(root: string, name: string): boolean {
+    try {
+        return lstatSync(join(root, 'node_modules', name)).isSymbolicLink()
+    } catch {
+        return false
+    }
+}

package/src/core/when-block.ts

@@ -12,7 +12,7 @@
 //   1. the file must not have moved since the caller read it (`expect`)
 //   2. the block must still MATCH what the config loads, or a hand edit the
 //      writer cannot account for would be silently overwritten
-//   3. a `when` or `tests` declared outside the block is refused, because a
+//   3. an `off` or `tests` declared outside the block is refused, because a
 //      second declaration is a duplicate key rather than a merge
 //   4. the value is validated the way `defineRepo` validates it, before it
 //      reaches the file
@@ -28,7 +28,6 @@ import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { atomicWrite } from './locked-write.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
-import { parseWhen } from './when.ts'
 import type { SlowSuite, TestsConfig } from '../suite/judge-suites.ts'
 import { normWord, proseWordsProblems, type ProseAllowWord, type ProseBanWord, type ProseWords } from '../prose/ste.ts'
 
@@ -41,7 +40,7 @@ export const WORDS_END = '// <<< shipkit prose words'
 
 /** every key this block owns. A repo declaring one of them outside the
  *  markers keeps it, and the block refuses to write rather than duplicate it */
-const OWNED = ['when', 'tests'] as const
+const OWNED = ['off', 'tests'] as const
 
 export type BlockState = 'missing-file' | 'missing-block' | 'stale' | 'current'
 
@@ -51,7 +50,8 @@ export type GateBlock = {
      *  the write, and a mismatch means somebody else edited it meanwhile */
     hash: string
     state: BlockState
-    when: Record<string, string>
+    /** check id → why this repo turns it off */
+    off: Record<string, string>
     tests: TestsConfig
     /** true when a key this block owns is declared outside the markers */
     declaredOutside: boolean
@@ -65,8 +65,8 @@ export type GateBlock = {
 }
 
 export type GateEdit = {
-    /** check id → the value, or null to drop the entry */
-    when?: Record<string, string | null>
+    /** check id → why it is off, or null to turn it back on */
+    off?: Record<string, string | null>
     /** suites to declare slow, each with the case `defineRepo` demands */
     slow?: SlowSuite[]
     /** suite files to drop back to the quick tier */
@@ -109,12 +109,12 @@ const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'
 const k = (s: string): string => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : q(s))
 
 /** the bytes between the markers, markers included */
-export function renderGateBlock(when: Record<string, string>, tests: TestsConfig, pad: string): string[] {
+export function renderGateBlock(off: Record<string, string>, tests: TestsConfig, pad: string): string[] {
     const out = [`${pad}${GATE_BEGIN}`]
-    const ids = Object.keys(when).sort()
+    const ids = Object.keys(off).sort()
     if (ids.length > 0) {
-        out.push(`${pad}when: {`)
-        for (const id of ids) out.push(`${pad}${pad}${k(id)}: ${q(when[id]!)},`)
+        out.push(`${pad}off: {`)
+        for (const id of ids) out.push(`${pad}${pad}${k(id)}: ${q(off[id]!)},`)
         out.push(`${pad}},`)
     }
     const slow = tests.slow ?? []
@@ -219,13 +219,13 @@ export function configDirty(root: string): boolean {
 /** what the block holds today, and whether it still describes the config */
 export async function readGateBlock(root: string): Promise<GateBlock> {
     const path = configPath(root)
-    if (!existsSync(path)) return { path, hash: '', state: 'missing-file', when: {}, tests: {}, declaredOutside: false, words: {}, wordsState: 'no-prose', wordsOutside: false }
+    if (!existsSync(path)) return { path, hash: '', state: 'missing-file', off: {}, tests: {}, declaredOutside: false, words: {}, wordsState: 'no-prose', wordsOutside: false }
     const text = readFileSync(path, 'utf8')
     const lines = text.split('\n')
     const b = lines.findIndex(isBegin)
     const e = lines.findIndex(isEnd)
     const c = await loadRepoConfig(root, { fresh: true })
-    const when = c.when ?? {}
+    const off = c.off ?? {}
     const tests = c.tests ?? {}
     const hash = sha(text)
     const w = locateWords(lines, c)
@@ -234,7 +234,7 @@ export async function readGateBlock(root: string): Promise<GateBlock> {
         // no block: the keys it owns must be unclaimed, or a write would be a
         // second declaration of the same key rather than an edit of the first
         const declaredOutside = OWNED.some((key) => c[key] != null)
-        return { path, hash, state: 'missing-block', when, tests, declaredOutside, ...wordsPart }
+        return { path, hash, state: 'missing-block', off, tests, declaredOutside, ...wordsPart }
     }
     // the block DESCRIBES the config when re-rendering the loaded values
     // reproduces it byte for byte. Anything else (a hand edit, a second
@@ -242,25 +242,25 @@ export async function readGateBlock(root: string): Promise<GateBlock> {
     // stale refuses instead of overwriting what somebody wrote
     const pad = indentOf(lines.slice(b + 1, e))
     const current = lines.slice(b, e + 1).join('\n')
-    const expected = renderGateBlock(when, tests, pad === '' ? indentOf(lines) : pad).join('\n')
-    return { path, hash, state: current === expected ? 'current' : 'stale', when, tests, declaredOutside: false, ...wordsPart }
+    const expected = renderGateBlock(off, tests, pad === '' ? indentOf(lines) : pad).join('\n')
+    return { path, hash, state: current === expected ? 'current' : 'stale', off, tests, declaredOutside: false, ...wordsPart }
 }
 
 /** does what the loader read back say what was written? BOTH keys the block
- *  owns, not just `when`: a `tests` entry that loads and parses differently
+ *  owns, not just `off`: a `tests` entry that loads and parses differently
  *  (a renderer that drops a field, a loader that reshapes one) is exactly
  *  what reading the result back exists to catch, and comparing half of the
  *  block would let that half through. Key and array ORDER are the renderer's,
  *  so the comparison is by content. */
-export function roundTripProblem(wrote: { when: Record<string, string>; tests: TestsConfig; words?: ProseWords }, loaded: RepoConfig): string | null {
-    const normWhen = (m: Record<string, string> | undefined): string => JSON.stringify(Object.entries(m ?? {}).sort())
+export function roundTripProblem(wrote: { off: Record<string, string>; tests: TestsConfig; words?: ProseWords }, loaded: RepoConfig): string | null {
+    const normOff = (m: Record<string, string> | undefined): string => JSON.stringify(Object.entries(m ?? {}).sort())
     const normTests = (t: TestsConfig | undefined): string =>
         JSON.stringify({
             budgetMs: t?.budgetMs ?? null,
             slow: (t?.slow ?? []).map((s) => [s.file, s.catches, s.whyNotFast]).sort(),
             serial: (t?.serial ?? []).map((s) => [s.file, s.why]).sort(),
         })
-    if (normWhen(loaded.when) !== normWhen(wrote.when)) return `the loader read when ${JSON.stringify(loaded.when ?? {})}`
+    if (normOff(loaded.off) !== normOff(wrote.off)) return `the loader read off ${JSON.stringify(loaded.off ?? {})}`
     if (normTests(loaded.tests) !== normTests(wrote.tests)) return `the loader read tests ${JSON.stringify(loaded.tests ?? {})}`
     if (wrote.words != null) {
         const normWords = (x: ProseWords | undefined): string => {
@@ -315,13 +315,13 @@ export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?:
     if (before.state === 'missing-file') throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
     if (o.expect != null && o.expect !== before.hash)
         throw new Error(`repo.config.ts changed since you read it, reload the page and set it again, so this edit cannot overwrite one made elsewhere`)
-    const touchGate = edit.when != null || edit.slow != null || edit.slowRemove != null
+    const touchGate = edit.off != null || edit.slow != null || edit.slowRemove != null
     const touchWords = edit.words != null
-    if (!touchGate && !touchWords) throw new Error(`nothing to write: the edit names no when, no slow suite and no prose word`)
+    if (!touchGate && !touchWords) throw new Error(`nothing to write: the edit names no off, no slow suite and no prose word`)
     if (touchGate && before.state === 'stale')
         throw new Error(`the shipkit gate block in repo.config.ts no longer matches what the config loads, so it was hand edited or something else declares these keys — reconcile it by hand, then use the switch again`)
     if (touchGate && before.state === 'missing-block' && before.declaredOutside)
-        throw new Error(`repo.config.ts declares \`when\` or \`tests\` outside the managed block — move that declaration between the markers first, or the switch would write a duplicate key`)
+        throw new Error(`repo.config.ts declares \`off\` or \`tests\` outside the managed block — move that declaration between the markers first, or the switch would write a duplicate key`)
     if (touchWords && before.wordsState === 'no-prose')
         throw new Error(`repo.config.ts has no \`prose: {\` line to write the word lists under — declare \`prose: { include: [...] }\` first, the lists only matter to a repo rule SK014 checks`)
     if (touchWords && before.wordsState === 'stale')
@@ -331,12 +331,11 @@ export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?:
 
     // the next values, validated the way defineRepo validates them, BEFORE
     // anything reaches the file
-    const when: Record<string, string> = { ...before.when }
-    for (const [id, raw] of Object.entries(edit.when ?? {})) {
-        if (raw == null) { delete when[id]; continue }
-        const w = parseWhen(raw)
-        if (typeof w === 'string') throw new Error(`when.${id} ${w}`)
-        when[id] = raw
+    const off: Record<string, string> = { ...before.off }
+    for (const [id, why] of Object.entries(edit.off ?? {})) {
+        if (why == null) { delete off[id]; continue }
+        if (typeof why !== 'string' || why.trim() === '') throw new Error(`off.${id} needs a reason: a check nobody can explain is a silenced gate`)
+        off[id] = why.trim()
     }
     const slow = [...(before.tests.slow ?? [])]
     for (const s of edit.slow ?? []) {
@@ -360,7 +359,7 @@ export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?:
         const b = lines.findIndex(isBegin)
         const e = lines.findIndex(isEnd)
         const pad = b === -1 ? indentOf(lines) : indentOf(lines.slice(b + 1, e)) || indentOf(lines)
-        const block = renderGateBlock(when, tests, pad)
+        const block = renderGateBlock(off, tests, pad)
         if (b !== -1 && e !== -1) out = [...lines.slice(0, b), ...block, ...lines.slice(e + 1)]
         else {
             // the anchor is the object literal `defineRepo({` opens. Without it
@@ -391,7 +390,7 @@ export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?:
     // round trip is a broken config, so the previous bytes go back
     try {
         const after = await loadRepoConfig(root, { fresh: true })
-        const problem = roundTripProblem({ when, tests, words }, after)
+        const problem = roundTripProblem({ off, tests, words }, after)
         if (problem != null) throw new Error(`the block did not round trip: ${problem}`)
     } catch (err) {
         atomicWrite(before.path, text)

package/src/core/when.ts

@@ -1,42 +1,34 @@
-// WHERE A CHECK RUNS, in ONE declaration, keyed by check id.
+// THE CHECKS A REPO TURNS OFF: `off: { <id>: '<why>' }` in repo.config.ts,
+// the switch the hub writes inside its managed block. Where a check runs is
+// its own declaration (core/runs.ts); the one thing a repo says about a check
+// it does not own is that it does not run here, and why. An off row runs in
+// no context, and every surface shows it with its reason.
 //
-// The question "does this run, and where" used to be answered in three
-// unrelated places with three vocabularies: `ruleExempt` for a rule, `optIn`
-// for a task, `export const gate` inside a check file. Nothing could read the
-// three together, so no surface could show them on one row and no surface
-// could write one.
-//
-// Four answers, and they are the words on screen:
-//   always     every gate and every health pass
-//   release    out of the quick gate, in at `--full` and on the release path
-//   health     the health pass (`shipkit check`) only, never a gate
-//   off:<why>  not run at all, and the reason is mandatory
-//
-// The third word says what it MEANS, never which command runs it: a value
-// nobody can read is a switch nobody moves.
-import type { TestTier, CheckRow } from '../ledger/gate-checks.ts'
+// Two retired spellings still read as off while SK029 ports them: a `when`
+// entry `'off:<why>'` (defineRepo refuses the other words) and `ruleExempt`.
+// They die once `shipkit fleet` shows no repo carrying them.
+import type { CheckRow } from '../ledger/gate-checks.ts'
+import type { ResolvedRuns } from './runs.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
+/** the coarse word a resolved row reads as on the check page */
 export type WhenAt = 'always' | 'release' | 'health' | 'off'
 
-/** which declaration is answering: the `when` key the switch writes, one of
- *  the check file's own `when`, one of the three spellings the key replaces,
- *  or the default nobody wrote */
-export type WhenSource = 'when' | 'check-file' | 'ruleExempt' | 'optIn' | 'gate-export' | 'defaults' | 'default'
+/** which declaration is answering: the repo's `off`, one of its two retired
+ *  spellings, the check file, the `defaults` block, or a derived row */
+export type WhenSource = 'off' | 'when' | 'ruleExempt' | 'check-file' | 'defaults' | 'default'
 
 export type WhenDecl = { at: WhenAt; reason: string | null; source: WhenSource }
 
 export const WHEN_AT: readonly WhenAt[] = ['always', 'release', 'health', 'off']
 
-/** the words a config value may use */
+/** the words a retired `when` value used */
 const WORDS: Record<string, WhenAt> = { always: 'always', release: 'release', health: 'health' }
 
-const DEFAULT: WhenDecl = { at: 'always', reason: null, source: 'default' }
-
-/** one config value, or the problem with it. A string back is the message
- *  `defineRepo` throws, so a bad value dies at config load and never mid gate */
+/** one retired `when` value, or the problem with it. defineRepo refuses every
+ *  word but `off:<why>`, which reads as `off` */
 export function parseWhen(raw: unknown): WhenDecl | string {
-    if (typeof raw !== 'string') return `must be a string: always, release, health, or off:<reason>`
+    if (typeof raw !== 'string') return `must be a string: off:<reason>`
     const v = raw.trim()
     if (v === 'off' || v.startsWith('off:')) {
         const reason = v.slice(4).trim()
@@ -44,92 +36,38 @@ export function parseWhen(raw: unknown): WhenDecl | string {
         return { at: 'off', reason, source: 'when' }
     }
     const at = WORDS[v]
-    if (at == null) return `'${v}' is not a when value (always, release, health, off:<reason>)`
+    if (at == null) return `'${v}' is not a when value (off:<reason>)`
     return { at, reason: null, source: 'when' }
 }
 
-/** the explicit `when` entry for one id, or null. A value that does not parse
- *  is null here: `defineRepo` already refused it, so reaching this with one
- *  means the config was never loaded through it */
-export function declaredWhen(c: RepoConfig, id: string): WhenDecl | null {
-    const raw = c.when?.[id]
-    if (raw == null) return null
-    const w = parseWhen(raw)
-    return typeof w === 'string' ? null : w
-}
+/** the repo turned this check off, with why and where it said so, or null */
+export type RepoOff = { reason: string; source: 'off' | 'when' | 'ruleExempt' }
 
-/** a rule: `when` wins, then `ruleExempt`, which is off with its reason */
-export function whenOfRule(c: RepoConfig, id: string): WhenDecl {
-    const w = declaredWhen(c, id)
-    if (w != null) return w
+export function repoOff(c: RepoConfig, id: string): RepoOff | null {
+    const own = c.off?.[id]
+    if (own != null) return { reason: own, source: 'off' }
+    const w = c.when?.[id] == null ? null : parseWhen(c.when[id])
+    if (w != null && typeof w !== 'string' && w.at === 'off') return { reason: w.reason ?? '', source: 'when' }
     const exempt = c.ruleExempt?.[id]
-    if (exempt != null) return { at: 'off', reason: exempt, source: 'ruleExempt' }
-    return DEFAULT
-}
-
-/** a task: `when` wins, then `optIn`, which means off the default gate and
- *  reachable by name (`--with <id>`), which is what `health` means for a task */
-export function whenOfTask(c: RepoConfig, t: { id: string; optIn?: boolean }): WhenDecl {
-    const w = declaredWhen(c, t.id)
-    if (w != null) return w
-    if (t.optIn === true) return { at: 'health', reason: null, source: 'optIn' }
-    return DEFAULT
-}
-
-/** a floor slot the repo turned off with `defaults: { <id>: false }`. That
- *  declaration REMOVES the task, so it wins over any `when`: a row claiming
- *  always over a slot that resolves to nothing is a check the gate never
- *  runs and nobody can see. The source is the `defaults` block itself, and
- *  the reason names the line, so a page can say which declaration answered */
-export function whenOfDisabledSlot(id: string): WhenDecl {
-    return { at: 'off', reason: `defaults.${id}: false`, source: 'defaults' }
+    return exempt == null ? null : { reason: exempt, source: 'ruleExempt' }
 }
 
-/** a discovered check: the repo's `when` wins, then the file's own `when`,
- *  so a config can move a check whose file the repo does not own */
-export function whenOfCheck(c: RepoConfig, u: { id: string; def: { when?: string } }): WhenDecl {
-    const w = declaredWhen(c, u.id)
-    if (w != null) return w
-    // the legacy spelling still moves a check the repo does not own, and a
-    // repo statement wins over the file's own default
-    const exempt = c.ruleExempt?.[u.id]
-    if (exempt != null) return { at: 'off', reason: exempt, source: 'ruleExempt' }
-    if (u.def.when == null) return DEFAULT
-    const own = parseWhen(u.def.when)
-    // `check()` already refused anything unparseable, so reaching this with a
-    // string means the object never went through it
-    return typeof own === 'string' ? DEFAULT : { ...own, source: 'check-file' }
-}
-
-/** a discovered check: `when` wins, then the file's own `export const gate` */
-export function whenOfLegacyCheck(c: RepoConfig, d: { name: string; gate: boolean }): WhenDecl {
-    const w = declaredWhen(c, d.name)
-    if (w != null) return w
-    if (!d.gate) return { at: 'health', reason: null, source: 'gate-export' }
-    return DEFAULT
-}
-
-/** does the GATE run it at this tier? `shipkit check` asks `runsInCheck` */
-export function runsInGate(w: WhenDecl, tier: TestTier): boolean {
-    if (w.at === 'off' || w.at === 'health') return false
-    return w.at === 'release' ? tier === 'full' : true
-}
-
-/** does the health pass run it? everything but off: `shipkit check` is where
- *  a proactive probe belongs, and only off means never */
-export function runsInCheck(w: WhenDecl): boolean {
-    return w.at !== 'off'
-}
+/** a resolved row the repo turned off: it runs in no context */
+export const withRepoOff = (base: ResolvedRuns, off: RepoOff | null): ResolvedRuns => (off == null ? base : { ...base, off: off.reason })
 
-/** the ONE line a surface prints for a check that is off */
-export function offLine(id: string, w: WhenDecl): string {
-    return `${id} off: ${w.reason ?? '(no reason)'}`
+/** the coarse word a resolved row reads as, for the check page. Derived,
+ *  never declared */
+export function whenSummary(r: ResolvedRuns, off: RepoOff | { reason: string; source: 'defaults' } | null, fromFile: boolean): WhenDecl {
+    const source: WhenSource = off?.source ?? (fromFile ? 'check-file' : 'default')
+    if (r.off != null) return { at: 'off', reason: r.off, source }
+    const at: WhenAt = r.onCi ? 'always' : r.onFull || r.onRelease ? 'release' : r.onHealth || r.onSave !== false || r.onClock !== false ? 'health' : 'off'
+    return { at, reason: at === 'off' ? 'no context runs it' : null, source }
 }
 
-/** ids in `when` that name no check of this repo. `defineRepo` can only check
- *  the rule namespace: a task is resolved from the floor and a check is
- *  discovered on disk, so this is where the rest is caught, loud */
-export function unknownWhenIds(rows: CheckRow[], c: RepoConfig): string[] {
+/** ids the repo turns off that name no check of this repo. `defineRepo` can
+ *  only check the rule namespace: a task is resolved from the floor and a
+ *  check is discovered on disk, so this is where the rest is caught, loud */
+export function unknownOffIds(rows: CheckRow[], c: RepoConfig): string[] {
     const known = new Set(rows.map((r) => r.decl.id))
-    return Object.keys(c.when ?? {}).filter((id) => !known.has(id))
+    return [...new Set([...Object.keys(c.off ?? {}), ...Object.keys(c.when ?? {})])].filter((id) => !known.has(id))
 }