rvlib-shipkit 0.38.1 → 1.0.1

package/src/core/when-block.ts

@@ -0,0 +1,401 @@
+// THE MANAGED BLOCK in `repo.config.ts`, so a switch on a page can move a
+// check without a second source of truth.
+//
+// The config is the ONE owner of what runs in this repo. A shadow store the
+// hub kept beside it would rot the first time somebody edited the file by
+// hand, which is the failure mode a control room cannot afford, so the hub
+// writes the config itself. It writes only the bytes between two markers, the
+// pattern this toolkit already uses twice (rule SK004 inside `.gitignore`,
+// `shipkit commands --out` inside a docs page).
+//
+// The paranoia, in order:
+//   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
+//      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
+//   5. the result is read back through the SAME loader the cli uses, and the
+//      previous bytes are restored when it does not round trip
+//
+// No external formatter runs over the file. The block is rendered in the
+// file's own indentation and quote style, and a formatter the repo scoped to
+// `src/` would land a whole file diff for a one line toggle.
+import { execFileSync } from 'child_process'
+import { createHash } from 'crypto'
+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'
+
+export const GATE_BEGIN = '// >>> shipkit gate — managed block, the hub writes it, edit outside the markers'
+export const GATE_END = '// <<< shipkit gate'
+/** the second managed block, INSIDE the `prose: {` object: the repo's own
+ *  word lists for rule SK014. Same writer, same paranoia, its own markers */
+export const WORDS_BEGIN = '// >>> shipkit prose words — managed block, the hub writes it, edit outside the markers'
+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
+
+export type BlockState = 'missing-file' | 'missing-block' | 'stale' | 'current'
+
+export type GateBlock = {
+    path: string
+    /** sha256 of the file as it is right now — the caller hands it back on
+     *  the write, and a mismatch means somebody else edited it meanwhile */
+    hash: string
+    state: BlockState
+    when: Record<string, string>
+    tests: TestsConfig
+    /** true when a key this block owns is declared outside the markers */
+    declaredOutside: boolean
+    /** the prose word lists as the config loads them */
+    words: ProseWords
+    /** the words block: `no-prose` when the config has no `prose: {` object
+     *  to write into, and the lists then mean nothing to rule SK014 anyway */
+    wordsState: BlockState | 'no-prose'
+    /** true when `prose.words` is declared outside the words markers */
+    wordsOutside: boolean
+}
+
+export type GateEdit = {
+    /** check id → the value, or null to drop the entry */
+    when?: 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 */
+    slowRemove?: string[]
+    /** the prose word lists: entries to add or replace (keyed by word), and
+     *  words to drop from either list */
+    words?: WordsEdit
+}
+
+export type WordsEdit = {
+    allow?: ProseAllowWord[]
+    ban?: ProseBanWord[]
+    /** words to drop, from whichever list holds them */
+    remove?: string[]
+}
+
+const sha = (s: string): string => createHash('sha256').update(s).digest('hex').slice(0, 16)
+
+const configPath = (root: string): string => join(root, 'repo.config.ts')
+
+/** the file's own indentation check, so the block reads like its neighbours */
+function indentOf(lines: string[]): string {
+    for (const l of lines) {
+        const m = /^([ \t]+)\S/.exec(l)
+        if (m != null) return m[1]!
+    }
+    return '    '
+}
+
+const isBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit gate')
+const isEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit gate')
+const isWordsBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit prose words')
+const isWordsEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit prose words')
+/** the one line the words block can be written under: `prose: {` alone */
+const isProseOpen = (l: string): boolean => /^\s*prose:\s*\{\s*$/.test(l)
+
+/** a single quoted TS string literal, escapes and all */
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+/** an object key: bare when it is a plain identifier, quoted otherwise */
+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[] {
+    const out = [`${pad}${GATE_BEGIN}`]
+    const ids = Object.keys(when).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}},`)
+    }
+    const slow = tests.slow ?? []
+    const serial = tests.serial ?? []
+    if (tests.budgetMs != null || slow.length > 0 || serial.length > 0) {
+        out.push(`${pad}tests: {`)
+        if (tests.budgetMs != null) out.push(`${pad}${pad}budgetMs: ${tests.budgetMs},`)
+        for (const [name, entries, keys] of [['slow', slow, ['file', 'catches', 'whyNotFast']], ['serial', serial, ['file', 'why']]] as const) {
+            if (entries.length === 0) continue
+            out.push(`${pad}${pad}${name}: [`)
+            for (const e of entries) {
+                out.push(`${pad}${pad}${pad}{`)
+                for (const f of keys) out.push(`${pad}${pad}${pad}${pad}${f}: ${q(String((e as Record<string, unknown>)[f] ?? ''))},`)
+                out.push(`${pad}${pad}${pad}},`)
+            }
+            out.push(`${pad}${pad}],`)
+        }
+        out.push(`${pad}},`)
+    }
+    out.push(`${pad}${GATE_END}`)
+    return out
+}
+
+/** the bytes between the words markers, markers included. Entries sorted by
+ *  word, so the block is a function of the lists and a reorder by hand reads
+ *  as a hand edit */
+export function renderWordsBlock(words: ProseWords, pad: string, unit = '    '): string[] {
+    const out = [`${pad}${WORDS_BEGIN}`]
+    const allow = [...(words.allow ?? [])].sort((a, b) => normWord(a.word).localeCompare(normWord(b.word)))
+    const ban = [...(words.ban ?? [])].sort((a, b) => normWord(a.word).localeCompare(normWord(b.word)))
+    if (allow.length > 0 || ban.length > 0) {
+        out.push(`${pad}words: {`)
+        const entry = (e: object, keys: string[]): string => {
+            const r = e as Record<string, unknown>
+            return `{ ${keys.filter((f) => typeof r[f] === 'string' && r[f] !== '').map((f) => `${f}: ${q(r[f] as string)}`).join(', ')} },`
+        }
+        const p1 = pad + unit
+        const p2 = p1 + unit
+        if (allow.length > 0) {
+            out.push(`${p1}allow: [`)
+            for (const a of allow) out.push(`${p2}${entry(a, ['word', 'reason'])}`)
+            out.push(`${p1}],`)
+        }
+        if (ban.length > 0) {
+            out.push(`${p1}ban: [`)
+            for (const b of ban) out.push(`${p2}${entry(b, ['word', 'to', 'reason'])}`)
+            out.push(`${p1}],`)
+        }
+        out.push(`${pad}},`)
+    }
+    out.push(`${pad}${WORDS_END}`)
+    return out
+}
+
+/** the words the loader read, in the shape the renderer writes: empty
+ *  strings dropped, so a round trip compares content and not spelling */
+const cleanWords = (w: ProseWords | undefined): ProseWords => {
+    const strip = <T extends object>(e: T): T => Object.fromEntries(Object.entries(e).filter(([, v]) => v != null && v !== '')) as T
+    const out: ProseWords = {}
+    if ((w?.allow ?? []).length > 0) out.allow = w!.allow!.map(strip)
+    if ((w?.ban ?? []).length > 0) out.ban = w!.ban!.map(strip)
+    return out
+}
+
+/** the indentation one level inside the line at `at` */
+const innerPad = (lines: string[], at: number): string => {
+    const own = /^([ \t]*)/.exec(lines[at] ?? '')?.[1] ?? ''
+    const unit = indentOf(lines)
+    return own + unit
+}
+
+/** where the words block sits and what state it is in */
+function locateWords(lines: string[], c: RepoConfig): { state: BlockState | 'no-prose'; b: number; e: number; open: number; pad: string; outside: boolean } {
+    const b = lines.findIndex(isWordsBegin)
+    const e = lines.findIndex(isWordsEnd)
+    const open = lines.findIndex(isProseOpen)
+    const words = cleanWords(c.prose?.words)
+    if (b !== -1 && e !== -1 && e > b) {
+        const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
+        const current = lines.slice(b, e + 1).join('\n')
+        const expected = renderWordsBlock(words, pad, indentOf(lines)).join('\n')
+        return { state: current === expected ? 'current' : 'stale', b, e, open, pad, outside: false }
+    }
+    if (open === -1) return { state: 'no-prose', b: -1, e: -1, open, pad: '', outside: c.prose?.words != null }
+    return { state: 'missing-block', b: -1, e: -1, open, pad: innerPad(lines, open), outside: c.prose?.words != null }
+}
+
+/** is repo.config.ts edited and not yet committed? The switch leaves it
+ *  DIRTY on purpose: a toggle is a change its owner reviews in a git client,
+ *  never a commit an agent makes for them. So the page has to say so. */
+export function configDirty(root: string): boolean {
+    try {
+        // stderr is swallowed on purpose: "not a git repository" is an
+        // ANSWER here, and printing it into every hub request is noise
+        return execFileSync('git', ['status', '--porcelain', '--', 'repo.config.ts'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() !== ''
+    } catch {
+        // no git, or no repository: dirt is unknowable rather than absent
+        return false
+    }
+}
+
+/** 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 }
+    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 tests = c.tests ?? {}
+    const hash = sha(text)
+    const w = locateWords(lines, c)
+    const wordsPart = { words: cleanWords(c.prose?.words), wordsState: w.state, wordsOutside: w.outside }
+    if (b === -1 || e === -1 || e < b) {
+        // 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 }
+    }
+    // the block DESCRIBES the config when re-rendering the loaded values
+    // reproduces it byte for byte. Anything else (a hand edit, a second
+    // declaration merging in, a formatter that reshaped it) is stale, and
+    // 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 }
+}
+
+/** 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
+ *  (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())
+    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 (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 => {
+            const c = cleanWords(x)
+            const by = (a: { word: string }, b: { word: string }) => normWord(a.word).localeCompare(normWord(b.word))
+            return JSON.stringify({ allow: [...(c.allow ?? [])].sort(by), ban: [...(c.ban ?? [])].sort(by) })
+        }
+        if (normWords(loaded.prose?.words) !== normWords(wrote.words)) return `the loader read prose.words ${JSON.stringify(loaded.prose?.words ?? {})}`
+    }
+    return null
+}
+
+/** the next word lists: an entry replaces the one with the same word in
+ *  EITHER list (moving a word from allow to ban is one edit), then `remove`
+ *  drops words. Judged the way defineRepo judges them */
+export function nextWords(before: ProseWords, edit: WordsEdit): ProseWords {
+    const allow = [...(before.allow ?? [])]
+    const ban = [...(before.ban ?? [])]
+    const drop = (w: string): void => {
+        const n = normWord(w)
+        for (const list of [allow, ban] as { word: string }[][]) {
+            const at = list.findIndex((x) => normWord(x.word) === n)
+            if (at !== -1) list.splice(at, 1)
+        }
+    }
+    const trimmed = <T extends { word: string }>(e: T): T =>
+        Object.fromEntries(Object.entries(e).filter(([, v]) => typeof v === 'string' && v.trim() !== '').map(([key, v]) => [key, (v as string).trim()])) as T
+    for (const a of edit.allow ?? []) {
+        if (typeof a?.word !== 'string' || normWord(a.word) === '') throw new Error(`prose.words.allow needs a word`)
+        drop(a.word)
+        allow.push(trimmed({ word: a.word, reason: a.reason }))
+    }
+    for (const b of edit.ban ?? []) {
+        if (typeof b?.word !== 'string' || normWord(b.word) === '') throw new Error(`prose.words.ban needs a word`)
+        drop(b.word)
+        ban.push(trimmed({ word: b.word, to: b.to, reason: b.reason }))
+    }
+    for (const w of edit.remove ?? []) drop(w)
+    const out: ProseWords = {}
+    if (allow.length > 0) out.allow = allow
+    if (ban.length > 0) out.ban = ban
+    const problems = proseWordsProblems(out)
+    if (problems.length > 0) throw new Error(problems[0])
+    return out
+}
+
+/** the ONE write path, for the switch, the slow suite form and the prose word
+ *  lists alike. Each block is rewritten only when the edit touches it, so a
+ *  word edit never inserts an empty gate block, and the reverse */
+export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?: string } = {}): Promise<GateBlock> {
+    const before = await readGateBlock(root)
+    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 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 && 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`)
+    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')
+        throw new Error(`the shipkit prose words block in repo.config.ts no longer matches what the config loads, so it was hand edited — reconcile it by hand, then edit the lists again`)
+    if (touchWords && before.wordsState === 'missing-block' && before.wordsOutside)
+        throw new Error(`repo.config.ts declares \`prose.words\` outside the managed block — move it between the markers first, or the page would write a duplicate key`)
+
+    // 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 slow = [...(before.tests.slow ?? [])]
+    for (const s of edit.slow ?? []) {
+        for (const f of ['catches', 'whyNotFast'] as const) {
+            if (typeof s[f] !== 'string' || s[f].trim() === '')
+                throw new Error(`tests.slow ${s.file} needs ${f}: ${f === 'catches' ? 'the regression this suite catches that no fast test can' : 'why the cost cannot come down, and what you tried'}`)
+        }
+        if (typeof s.file !== 'string' || s.file.trim() === '') throw new Error(`tests.slow needs a file`)
+        const at = slow.findIndex((x) => x.file === s.file)
+        if (at === -1) slow.push({ file: s.file, catches: s.catches, whyNotFast: s.whyNotFast })
+        else slow[at] = { file: s.file, catches: s.catches, whyNotFast: s.whyNotFast }
+    }
+    const dropped = new Set(edit.slowRemove ?? [])
+    const tests: TestsConfig = { ...before.tests, slow: slow.filter((s) => !dropped.has(s.file)) }
+    const words = touchWords ? nextWords(before.words, edit.words!) : undefined
+
+    const text = readFileSync(before.path, 'utf8')
+    let out = text.split('\n')
+    if (touchGate) {
+        const lines = out
+        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)
+        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
+            // there is nothing to write into, so the block is PRINTED for a
+            // human to paste rather than guessed at
+            const anchor = lines.findIndex((l) => /defineRepo\(\s*\{\s*$/.test(l))
+            if (anchor === -1)
+                throw new Error(`repo.config.ts has no \`defineRepo({\` line to write into — paste this block inside the config object by hand:\n${block.join('\n')}`)
+            out = [...lines.slice(0, anchor + 1), ...block, ...lines.slice(anchor + 1)]
+        }
+    }
+    if (words != null) {
+        const lines = out
+        const b = lines.findIndex(isWordsBegin)
+        const e = lines.findIndex(isWordsEnd)
+        const unit = indentOf(lines)
+        if (b !== -1 && e > b) {
+            const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
+            out = [...lines.slice(0, b), ...renderWordsBlock(words, pad, unit), ...lines.slice(e + 1)]
+        } else {
+            const open = lines.findIndex(isProseOpen)
+            out = [...lines.slice(0, open + 1), ...renderWordsBlock(words, innerPad(lines, open), unit), ...lines.slice(open + 1)]
+        }
+    }
+    atomicWrite(before.path, out.join('\n'))
+
+    // read it back through the loader the cli uses. A block that does not
+    // 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)
+        if (problem != null) throw new Error(`the block did not round trip: ${problem}`)
+    } catch (err) {
+        atomicWrite(before.path, text)
+        throw new Error(`repo.config.ts was left as it was: ${(err as Error).message}`)
+    }
+    return await readGateBlock(root)
+}

package/src/core/when.ts

@@ -0,0 +1,135 @@
+// WHERE A CHECK RUNS, in ONE declaration, keyed by check id.
+//
+// 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'
+import type { RepoConfig } from '../repo-config.ts'
+
+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'
+
+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 */
+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 */
+export function parseWhen(raw: unknown): WhenDecl | string {
+    if (typeof raw !== 'string') return `must be a string: always, release, health, or off:<reason>`
+    const v = raw.trim()
+    if (v === 'off' || v.startsWith('off:')) {
+        const reason = v.slice(4).trim()
+        if (reason === '') return `off needs a reason ('off:<why this repo turns it off>') — a check nobody can explain is a silenced gate`
+        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>)`
+    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
+}
+
+/** 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
+    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' }
+}
+
+/** 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'
+}
+
+/** 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)'}`
+}
+
+/** 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[] {
+    const known = new Set(rows.map((r) => r.decl.id))
+    return Object.keys(c.when ?? {}).filter((id) => !known.has(id))
+}

package/src/core/write-status.ts

@@ -3,8 +3,10 @@
 // concurrent runners never interleave — the loser skips with a WARN
 // outcome, never corrupts the file.
 
-import { join } from 'path'
+import { mkdirSync } from 'fs'
+import { dirname, join } from 'path'
 import { atomicWrite, withFileLock } from './locked-write.ts'
+import { LAYOUT } from './layout.ts'
 
 export type StatusInput = {
     /** repo name — headline */
@@ -34,7 +36,8 @@ const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '')
 const RUN_SUMMARY = /^FAIL:?\s+\d+\/\d+ failed:/
 
 export function writeStatus(root: string, s: StatusInput): StatusOutcome {
-    const target = join(root, 'STATUS.md')
+    const target = join(root, LAYOUT.status)
+    mkdirSync(dirname(target), { recursive: true })
     const r = withFileLock(target, () => {
         const clean = s.lines.map(stripAnsi)
         const fails = clean.filter((l) => l.startsWith('FAIL') && !RUN_SUMMARY.test(l)).length

package/src/fleet/scan-fleet.ts

@@ -12,6 +12,7 @@
 // so the fix travels through that one code path.
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
+import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
 
 export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
 
@@ -140,3 +141,18 @@ export async function npmLatest(name: string): Promise<string | null> {
     if (!res.ok) return null
     return ((await res.json()) as Pkg).version ?? null
 }
+
+/** the first release whose SK005 updates through the manager the repo's lock
+ *  files name. An older one runs bun whatever the lock says */
+export const PM_AWARE_SINCE = '1.0.0'
+
+/** why `fleet --update` must not hand this repo its own update, or null.
+ *  The fleet runs the REPO's shipkit, so what matters is what THAT binary
+ *  does: one older than PM_AWARE_SINCE updates an npm repo with bun */
+export function updateRefusal(r: FleetRepo): string | null {
+    const pm = detectPackageManager(r.dir)
+    if (isRefusal(pm)) return `cannot tell which package manager installs it: ${pm.refused}`
+    const own = r.deps.find((d) => d.name === 'rvlib-shipkit')?.installed
+    if (pm.name === 'bun' || own == null || !isBehind(own, PM_AWARE_SINCE)) return null
+    return `its shipkit ${own} updates with bun whatever the lock says, and it installs with ${pm.name}. Run: cd ${r.dir} && ${pm.update(r.behind.map((d) => d.name)).join(' ')}`
+}