rvlib-shipkit 1.4.0 → 1.6.0

package/src/core/trace-audit.ts

@@ -0,0 +1,120 @@
+// THE TRACED AUDIT: which gitignored paths a task reads that its key cannot
+// see. A task's key covers the tracked tree and the paths `ignoredInputs`
+// names; a generated type or a local fixture it reads outside those is a
+// stale green waiting for its first edit. Each gate task runs once under the
+// tracer (trace/tracer.ts), and the ignored paths it touched that no key
+// covers become that task's proposals: the keys read them at once
+// (core/audit-report.ts), and `sk trace-audit --fix` writes them into their
+// own managed block of repo.config.ts (core/ignored-block.ts).
+//
+// The tracer never decides a verdict here. A hole in the trace (a child that
+// ran untraced) costs this audit that task, said out loud, and never a green.
+//
+// The tracing costs about one traced gate, so the answer is kept under the
+// git common dir and reused while it is young: rule SK031 in
+// the health pass pays for it, and the fix pass that applies it reads it.
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, posix } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { composeChecks } from '../ledger/gate-checks.ts'
+import { isNamesInput } from '../ledger/git-key.ts'
+import { readTrace } from '../trace/read-trace.ts'
+import { dropTrace, learnBlind, traceUnavailable, tracedCommand } from '../trace/tracer.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
+import { gitBin } from './git-bin.ts'
+import { auditReportPath, ignoredFor, pendingByTask, readAuditReport, type AuditReport, type AuditTask, type IgnoredInputs } from './audit-report.ts'
+import { addIgnoredInputs } from './ignored-block.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+/** how long an audit answers for the tree: about a day, like SK030 */
+export const AUDIT_KEEP_MS = 20 * 60 * 60 * 1000
+
+export type { AuditReport, AuditTask } from './audit-report.ts'
+export { readAuditReport } from './audit-report.ts'
+
+/** the paths of `paths` git ignores */
+function gitIgnored(root: string, paths: string[]): Set<string> {
+    if (paths.length === 0) return new Set()
+    const p = Bun.spawnSync([gitBin(), 'check-ignore', '--stdin'], { cwd: root, stdin: Buffer.from(`${paths.join('\n')}\n`), stdout: 'pipe', stderr: 'pipe' })
+    return new Set(p.stdout.toString().split('\n').filter((l) => l !== ''))
+}
+
+const under = (p: string, dir: string): boolean => p === dir || p.startsWith(`${dir}/`)
+
+/** is this ignored path already in a key: bytes under a content entry, or a
+ *  listing or probe under a names entry */
+function covered(p: string, listing: boolean, extras: string[]): boolean {
+    return extras.some((e) => (isNamesInput(e) ? listing && under(p, e.slice(0, -3)) : under(p, e)))
+}
+
+/** the fewest entries that cover what was read: each file by itself, or its
+ *  dir once more than three files there were read; each listed dir as
+ *  `dir/**`, the outermost one only */
+export function proposeInputs(content: string[], listed: string[]): string[] {
+    const byDir = new Map<string, string[]>()
+    for (const f of content) byDir.set(posix.dirname(f), [...(byDir.get(posix.dirname(f)) ?? []), f])
+    const bytes = [...byDir].flatMap(([dir, files]) => (files.length > 3 && dir !== '.' ? [dir] : files))
+    const minimal = (xs: string[]): string[] => {
+        const sorted = [...new Set(xs)].sort()
+        return sorted.filter((x) => !sorted.some((y) => y !== x && under(x, y)))
+    }
+    return [...minimal(bytes), ...minimal(listed).map((d) => `${d}/**`)].sort()
+}
+
+/** trace every gate task of the repo once and report what its key misses */
+export async function traceAudit(root: string, config: RepoConfig, o: { fresh?: boolean; now?: number; env?: Record<string, string | undefined> } = {}): Promise<AuditReport> {
+    const now = o.now ?? Date.now()
+    const kept = readAuditReport(root)
+    if (o.fresh !== true && kept != null && kept.skipped == null && now - kept.at < AUDIT_KEEP_MS) return kept
+    const env = o.env ?? process.env
+    const off = traceUnavailable(env)
+    if (off != null) return { at: now, skipped: off, tasks: [] }
+    const tasks: AuditTask[] = []
+    for (const g of await composeChecks(root, config)) {
+        const u = g.runnable
+        if (u.body.cmd == null || g.row.runs.off != null || !g.row.runs.onCi || g.row.decl.inputs == null) continue
+        const cwd = u.body.cwd ?? root
+        const t = tracedCommand(u.body.cmd, cwd, env)
+        if ('reason' in t) { tasks.push({ id: u.id, status: 'unaudited', why: t.reason, uncovered: [], propose: [] }); continue }
+        try {
+            await spawnWithTimeout(t.cmd, { timeoutMs: u.timeoutMs, env: { ...process.env, ...u.body.env, ...t.env }, cwd })
+            const r = await readTrace(t.dir, root)
+            if (r.reads == null) {
+                const learned = r.blind.length > 0 ? learnBlind(r.blind) : null
+                tasks.push({ id: u.id, status: 'unaudited', why: [r.why, learned].filter((x) => x != null).join('; '), uncovered: [], propose: [] })
+                continue
+            }
+            // bytes: a file it opened or stat'ed, or found by a probe; a
+            // listing: a dir it read the entries of, or found by a probe
+            // Finder rewrites .DS_Store at will, and no tool's verdict reads it
+            const rel = (p: string): boolean => !p.startsWith('/') && p !== '.' && !p.split('/').includes('node_modules') && !p.startsWith('.git/') && posix.basename(p) !== '.DS_Store'
+            const files = [...new Set([...Object.keys(r.reads.files), ...Object.keys(r.reads.sigs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'file').map(([p]) => p)])].filter(rel)
+            const dirs = [...new Set([...Object.keys(r.reads.dirs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'dir').map(([p]) => p)])].filter(rel)
+            const ignored = gitIgnored(root, [...files, ...dirs])
+            const extras = ignoredFor(config.ignoredInputs, u.id)
+            const missF = files.filter((p) => ignored.has(p) && !covered(p, false, extras))
+            const missD = dirs.filter((p) => ignored.has(p) && !covered(p, true, extras))
+            tasks.push({ id: u.id, status: 'audited', uncovered: [...missF, ...missD].sort(), propose: proposeInputs(missF, missD) })
+        } finally {
+            dropTrace(t.dir)
+        }
+    }
+    const report: AuditReport = { at: now, tasks }
+    try {
+        mkdirSync(dirname(auditReportPath(root)), { recursive: true })
+        writeFileSync(auditReportPath(root), JSON.stringify(report, null, 2))
+    } catch { /* an audit that cannot be kept is measured again next time */ }
+    return report
+}
+
+/** write what the kept audit proposes into the managed block. Nothing is
+ *  traced here, so the fix pass can call it on every run */
+export async function applyAudit(root: string): Promise<{ added: IgnoredInputs; note: string | null }> {
+    const r = readAuditReport(root)
+    if (r == null || r.skipped != null) return { added: {}, note: r?.skipped ?? 'no audit yet: sk trace-audit runs one' }
+    const added = pendingByTask(r, (await loadRepoConfig(root, { fresh: true })).ignoredInputs ?? {})
+    if (Object.keys(added).length === 0) return { added, note: null }
+    await addIgnoredInputs(root, added)
+    return { added, note: null }
+}
+

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))
 }

package/src/core/wire.ts

@@ -3,31 +3,27 @@
 // exit 0/1. FROZEN: consumers grep startsWith('FAIL'/'WARN'/'skip:') — a
 // prefix change is a breaking change of the whole toolkit.
 
-import { CACHED, RAN } from './outcome-words.ts'
+import { CACHED, costShort, RAN, spanShort } from './outcome-words.ts'
+
+export { spanShort }
 
 /** when a remembered world answer was measured, and until when it keeps
  *  (null: until its declaration changes). Kept as data, never as text, and
  *  rendered against the reader's clock: a time frozen into the line reads
  *  as a future expiry long after it passed */
-export type Stamp = { at: number; until: number | null; cached?: boolean }
+export type Stamp = { at: number; until: number | null; cached?: boolean; ranMs?: number }
 
 export type Line = { kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'; text: string; stamp?: Stamp }
 
-/** a span in its one biggest unit: `45s`, `12m`, `3h`, `2d` */
-export function spanShort(ms: number): string {
-    const s = Math.max(0, Math.round(ms / 1000))
-    if (s < 60) return `${s}s`
-    if (s < 3600) return `${Math.floor(s / 60)}m`
-    if (s < 86400) return `${Math.floor(s / 3600)}h`
-    return `${Math.floor(s / 86400)}d`
-}
-
-/** `cached, ran 3h ago, kept 57m more`, `ran 1d ago, expired 1d ago` */
+/** `cached, 3h old, kept 57m more` for a replay, `ran 0.4s, kept 1h more`
+ *  for an answer this run measured, `ran 1d ago, expired 1d ago` for one
+ *  read back later */
 export function stampWords(s: Stamp, now: number): string {
     const age = now - s.at
-    const ran = age < 1000 ? `${RAN} just now` : `${RAN} ${spanShort(age)} ago`
     const keeps = s.until == null ? 'kept until its declaration changes' : s.until > now ? `kept ${spanShort(s.until - now)} more` : `expired ${spanShort(now - s.until)} ago`
-    return `${s.cached === true ? `${CACHED}, ` : ''}${ran}, ${keeps}`
+    if (s.cached === true) return `${CACHED}, ${spanShort(age)} old, ${keeps}`
+    if (s.ranMs != null) return `${RAN} ${costShort(s.ranMs)}, ${keeps}`
+    return `${age < 1000 ? `${RAN} just now` : `${RAN} ${spanShort(age)} ago`}, ${keeps}`
 }
 
 /** a line's text as a reader sees it now, its stamp rendered */

package/src/fleet/scan-fleet.ts

@@ -14,7 +14,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { isArchived } from '../core/archived.ts'
 import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
-import { isBreaking } from '../core/update-policy.ts'
+import { isBreaking, isLinkedInstall, pinFloor } from '../core/update-policy.ts'
 
 export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
 
@@ -24,6 +24,11 @@ export type FleetDep = {
     pin: string
     /** what node_modules actually carries, null when nothing is installed */
     installed: string | null
+    /** node_modules/<name> is a `bun link` symlink to a source tree */
+    linkedInstall: boolean
+    /** the version freshness is judged by: the pin's floor under a link
+     *  (a fresh clone installs the pin, never the source), else `installed` */
+    at: string | null
     /** npm latest, null when the registry was not consulted or not reachable */
     latest: string | null
 }
@@ -54,6 +59,13 @@ const readPkg = (dir: string): Pkg | null => {
 
 export const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
 
+/** what `FleetDep.at` reads now, for a verdict after an update ran */
+export const judgedVersion = (dir: string, name: string): string | null => {
+    if (!isLinkedInstall(dir, name)) return installedVersion(dir, name)
+    const pkg = readPkg(dir)
+    return pinFloor(pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name] ?? '')
+}
+
 /** semver-ish compare, enough to answer "is this one behind that one". A
  *  prerelease tag sorts before its release, which is the safe direction: it
  *  reports behind rather than pretending parity. */
@@ -89,7 +101,11 @@ export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[
         const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
         const names = Object.keys(all).filter((n) => n.startsWith(prefix))
         if (names.length === 0) continue
-        const deps: FleetDep[] = names.sort().map((name) => ({ name, pin: all[name]!, installed: installedVersion(dir, name), latest: null }))
+        const deps: FleetDep[] = names.sort().map((name) => {
+            const installed = installedVersion(dir, name)
+            const linkedInstall = isLinkedInstall(dir, name)
+            return { name, pin: all[name]!, installed, linkedInstall, at: linkedInstall ? pinFloor(all[name]!) : installed, latest: null }
+        })
         out.push({
             name: e,
             dir,
@@ -120,8 +136,8 @@ export async function resolveLatest(repos: FleetRepo[], fetchLatest: (name: stri
     )
     for (const r of repos) {
         for (const d of r.deps) d.latest = latest.get(d.name) ?? null
-        r.behind = r.deps.filter((d) => d.installed != null && d.latest != null && isBehind(d.installed, d.latest))
-        r.breaking = r.behind.filter((d) => isBreaking(d.installed!, d.latest!))
+        r.behind = r.deps.filter((d) => d.at != null && d.latest != null && isBehind(d.at, d.latest))
+        r.breaking = r.behind.filter((d) => isBreaking(d.at!, d.latest!))
     }
     return latest
 }