rvlib-shipkit 1.3.0 → 1.5.0

package/src/ledger/toolchain-identity.ts

@@ -26,16 +26,12 @@
 // cache slower than the gate it caches. No tool produces that state; a human
 // debugging on purpose can delete the ledger.
 import { createHash } from 'crypto'
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'fs'
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'fs'
 import { isAbsolute, join, relative, resolve } from 'path'
 
 export type Toolchain = {
     /** the identity, 16 hex chars, stable for identical programs */
     id: string
-    /** non-empty means DO NOT CACHE this run: something in the toolchain is
-     *  neither in the repo's git tree nor pinned by a version string, so no
-     *  key can describe it. Each entry says which package and why. */
-    uncacheable: string[]
 }
 
 /** the gate binary driving THIS process, which is what the key hashes when a
@@ -62,25 +58,40 @@ function installedNames(nm: string): string[] {
     return names.sort()
 }
 
-/** the gate binary's own source, content-hashed. This is what makes editing
- *  shipkit invalidate every key in every repo, in-repo copy or dependency. */
-function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
-    const srcRoot = resolve(cli, '..')
-    const files: string[] = []
-    const walk = (d: string): void => {
-        for (const e of readdirSync(d, { withFileTypes: true })) {
-            if (e.name === 'node_modules' || e.name.startsWith('.')) continue
-            const p = join(d, e.name)
-            if (e.isDirectory()) walk(p)
-            else files.push(p)
+/** every file under `dir`, hashed as its path, its size and its bytes in
+ *  path order, so a rename or a line moved between files moves the hash too.
+ *  Its own installs and dot entries are left out. A symlink is followed (a
+ *  cycle is walked once), and one that cannot be read THROWS: a tree only
+ *  partly read must never be keyed as if it were whole */
+function hashTree(h: ReturnType<typeof createHash>, dir: string, tag: string): void {
+    const files: { rel: string; abs: string }[] = []
+    const seen = new Set<string>()
+    const walk = (d: string, rel: string): void => {
+        const real = realpathSync(d)
+        if (seen.has(real)) return
+        seen.add(real)
+        for (const name of readdirSync(d)) {
+            if (name === 'node_modules' || name.startsWith('.')) continue
+            const abs = join(d, name)
+            const r = rel === '' ? name : `${rel}/${name}`
+            if (statSync(abs).isDirectory()) walk(abs, r)
+            else files.push({ rel: r, abs })
         }
     }
-    walk(srcRoot)
-    files.sort()
-    for (const f of files) h.update(readFileSync(f))
-    h.update(`clifiles=${files.length}\n`)
+    walk(dir, '')
+    files.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))
+    for (const f of files) {
+        const bytes = readFileSync(f.abs)
+        h.update(`${f.rel}\0${bytes.length}\0`)
+        h.update(bytes)
+    }
+    h.update(`${tag}=${files.length}\n`)
 }
 
+/** the gate binary's own source, content-hashed. This is what makes editing
+ *  shipkit invalidate every key in every repo, in-repo copy or dependency. */
+const hashCliTree = (h: ReturnType<typeof createHash>, cli: string): void => hashTree(h, resolve(cli, '..'), 'clifiles')
+
 /**
  * what ONE install holds, as a hash: every top-level package's name, version
  * and link target.
@@ -119,7 +130,6 @@ export function installIdentity(nodeModules: string): string {
  */
 export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain {
     const h = createHash('sha256')
-    const uncacheable: string[] = []
     // BOTH sides resolved, or the comparison is wrong on macOS: /var is a
     // symlink to /private/var, so an in-repo cli under a resolved path reads
     // as outside an unresolved root. That mistake is silent and expensive: it
@@ -151,27 +161,35 @@ export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain
     if (!existsSync(nm)) {
         // a worktree nobody installed is a REAL difference, not a missing input
         h.update('nm=absent\n')
-        return { id: h.digest('hex').slice(0, 16), uncacheable }
+        return { id: h.digest('hex').slice(0, 16) }
     }
     const names = installedNames(nm)
     for (const n of names) {
         const dir = join(nm, n)
         let link = ''
+        let outside: string | null = null
         try {
             if (lstatSync(dir).isSymbolicLink()) {
                 const target = realpathSync(dir)
                 link = `->${target}`
-                // a `bun link`ed package is live source under someone else's
-                // edit: its content is in neither this repo's git tree nor its
-                // version string, so nothing here can describe it
-                if (!inRepo(root, target)) uncacheable.push(`${n} links outside the repo (${target})`)
+                if (!inRepo(root, target)) outside = target
             }
         } catch {}
+        // a `bun link`ed package is live source under someone else's edit:
+        // neither this repo's git tree nor its version string describes it, so
+        // its files do, and so does what it has installed itself, since its
+        // own imports resolve there. Outside the try on purpose: a linked tree
+        // that cannot be read throws, and the key layer then keys nothing.
+        // ~20ms for the whole rvlib-shipkit tree
+        if (outside != null) {
+            hashTree(h, outside, `linked:${n}`)
+            h.update(`${installIdentity(join(outside, 'node_modules'))}\n`)
+        }
         let version = 'MISSING'
         try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
         h.update(`${n}@${version}${link}\n`)
     }
     // the count catches a removal that leaves every survivor identical
     h.update(`n=${names.length}\n`)
-    return { id: h.digest('hex').slice(0, 16), uncacheable }
+    return { id: h.digest('hex').slice(0, 16) }
 }

package/src/ledger/world-cache.ts

@@ -31,9 +31,8 @@
 // A measured negative may be kept only for a check about the WORLD. One about
 // THIS REPO is fixed by a human and the next run goes green, so replaying its
 // red would be the cache lying about work already done.
-import { FOREVER_MS, fmtStamp, type Line } from '../core/wire.ts'
+import { FOREVER_MS, type Line, type Stamp } from '../core/wire.ts'
 import { FRESH_ENV, withAnswers, type Answers, type Stored } from './store.ts'
-import { CACHED, RAN } from '../core/outcome-words.ts'
 
 /** the longest a MEASURED NEGATIVE is remembered, whatever TTL was declared.
  *  Long enough to stop a re-ask storm inside one working session, short
@@ -80,11 +79,21 @@ function adoptTimed(a: Answers, ns: string, name: string, key: string): Stored<L
         return head != null && e.key.slice(head[0].length) === rest && Array.isArray(e.payload) && e.payload.length > 0 && e.payload.every((l) => l.kind === 'ok' || l.kind === 'note')
     })
     if (old == null) return null
-    const payload = old.payload.map((l, i): Line => (i !== 0 ? l : { ...l, text: l.text.replace(new RegExp(`\\((${CACHED} at [^)]*?) until [^)]*\\)$`), '($1 until its declaration changes)') }))
+    const payload = unbake(old.payload)
     a.write([{ ns, name, key, payload, at: old.at, keeps: FOREVER_MS }], { now: old.at })
     return { ...old, key, keeps: FOREVER_MS, payload }
 }
 
+/** the times an older build wrote into the first line's text, as `(cached at
+ *  <stamp> until <stamp>)` or `(ran at <stamp>, kept until <stamp>)`: the
+ *  entry holds them as data, so the text drops them */
+const BAKED = / \((?:cached|ran) at \d{4}-\d\d-\d\d \d\d:\d\d:\d\d,? (?:kept )?until [^)]*\)$/
+const unbake = (lines: Line[]): Line[] => lines.map((l, i) => (i === 0 ? { ...l, text: l.text.replace(BAKED, '') } : l))
+
+/** the first line, stamped with when its answer was measured and until when it keeps */
+const stamped = (lines: Line[], stamp: Stamp): Line[] => lines.map((l, i) => (i === 0 ? { ...l, stamp } : l))
+const untilOf = (at: number, keeps: number): number | null => (keeps >= FOREVER_MS ? null : at + keeps)
+
 /** the answer for this key, or the one a forever key adopts */
 const readOrAdopt = (a: Answers, ns: string, name: string, key: string): Stored<Line[]> | null => a.read<Line[]>(ns, name, key) ?? adoptTimed(a, ns, name, key)
 
@@ -104,11 +113,9 @@ export function replayWorld(c: WorldCache, name: string, key: string, ttlMs: num
     if (entry == null || !Array.isArray(entry.payload)) return null
     const keeps = entry.keeps ?? ttlMs
     if (now - entry.at >= keeps || now < entry.at) return null
-    // the stamp was baked in when the answer was MEASURED (below): a replay
-    // prints the stored lines VERBATIM, so the live run and every later replay
-    // render the same string. Annotating replays but not live runs diffed on
-    // every fresh-vs-cached alternation, so neither side annotates.
-    return entry.payload
+    // the times ride as data on the first line, rendered by whoever prints it
+    // against its own clock, so a line read a day later says how old it is
+    return stamped(unbake(entry.payload), { at: entry.at, until: untilOf(entry.at, keeps), cached: true })
 }
 
 export type Measured = {
@@ -150,11 +157,6 @@ export function rememberWorld(c: WorldCache, name: string, key: string, ttlMs: n
         return m.lines
     }
     const now = c.now()
-    const lines = m.lines.map((l, i): Line =>
-        i !== 0 ? l
-        : keepsFor >= FOREVER_MS ? { ...l, text: `${l.text} (${CACHED} at ${fmtStamp(now)} until its declaration changes)` }
-        : { ...l, text: `${l.text} (${m.clean ? `${CACHED} at ${fmtStamp(now)} until` : `${RAN} at ${fmtStamp(now)}, kept until`} ${fmtStamp(now + keepsFor)})` },
-    )
-    withAnswers(c.db, (a) => a.write([{ ns: c.ns, name, key, payload: lines, at: now, keeps: keepsFor }], { now }))
-    return lines
+    withAnswers(c.db, (a) => a.write([{ ns: c.ns, name, key, payload: m.lines, at: now, keeps: keepsFor }], { now }))
+    return stamped(m.lines, { at: now, until: untilOf(now, keepsFor) })
 }

package/src/plan/repo-source.ts

@@ -12,6 +12,7 @@ import { Ledger } from '../ledger/ledger.ts'
 import { answersDb } from '../ledger/store.ts'
 import { hasWorld, worldKeyOf, type WorldCache } from '../ledger/world-cache.ts'
 import { FOREVER, FOREVER_MS } from '../core/wire.ts'
+import { planned } from '../core/runs.ts'
 import { ONCE, type LastResult } from './cadence.ts'
 import { openDb } from '../ledger/db.ts'
 import { readLastResults } from '../ledger/run-log.ts'
@@ -21,57 +22,33 @@ import { movedSince } from '../serve/tracked-watch.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { PlanCheck, PlanReason, PlanSource } from './planner.ts'
 
-/** the rows the plan covers: what a gate or a health pass runs. A release
- *  check, an off one and an opt in build step wait for whoever names them */
+/** the rows the plan covers: every live row declaring `onSave` or
+ *  `onClock` (core/runs.ts). Nothing else is ever planned */
 export function plannable(row: CheckRow): boolean {
-    if (row.when.at !== 'always' && row.when.at !== 'health') return false
-    // nothing to do in this repo on a clock (check.ts planOff)
-    if (row.planOff != null) return false
-    if (row.optIn) return false
-    return !(row.build && row.when.at === 'health')
+    return planned(row.runs)
 }
 
-/** a REPO check nothing can key and that declares no cadence runs about
- *  once a day, never in step, until it declares what it depends on. No
- *  built-in may land here (tests/plan-default-range.test.ts) */
-const DEFAULT_EVERY: [string, string] = ['20h', '28h']
-
 /** why the plan cannot tell when this check's answer moves, or null when it
- *  can: a key, a ttl, a build step or a declared cadence says it */
+ *  can. With every axis explicit, a planned row always says: kept as the
+ *  burn-down reader for rows declaring a save trigger on nothing keyed */
 export function planGap(row: CheckRow): string | null {
+    if (row.runs.onSave !== 'moved') return null
     const pop = populationOf(row.decl)
-    if (pop === 'content' || pop === 'reads' || pop === 'world' || row.build) return null
-    if (row.plan?.every !== undefined || row.plan?.cron != null) return null
-    const why = row.decl.never != null && row.decl.never !== '' ? `never cached (${row.decl.never})` : (row.decl.uncacheable ?? 'declares neither inputs nor ttl')
-    return `${why}, and no every: nothing says when its answer moves`
+    if (pop === 'content' || pop === 'reads' || isForever(row)) return null
+    return `onSave 'moved' but nothing keys it (${row.decl.uncacheable ?? row.decl.declError ?? 'no key'}), so every save moves it`
 }
 
-/** one inventory row as a plan check. A world check keeps its ttl as its
- *  cadence; a build step and a check keyed on its files wait for a save (its
- *  answer replays until a file moves, so a clock re-asks nothing); a repo
- *  check with no cadence runs at its own stable point of the default range,
- *  and a built-in with none waits for a save and shows on the burn-down */
+/** one inventory row as a plan check, straight from its declared axes:
+ *  `onClock` is the cadence, `onSave` whether a save can make it due */
 export function planCheckOf(row: CheckRow): PlanCheck {
-    const pop = populationOf(row.decl)
-    const keyed = pop === 'content' || pop === 'reads'
-    const ttl = row.decl.ttl != null && row.decl.ttl !== '' ? row.decl.ttl : null
-    const fallback =
-        ttl === FOREVER ? { value: ONCE, why: 'a decided fact: ttl forever' }
-        : ttl != null ? { value: ttl, why: 'its ttl' }
-        : row.build ? { value: null, why: 'a build step' }
-        : keyed ? { value: null, why: 'keyed on its files' }
-        : row.from === 'repo' ? { value: DEFAULT_EVERY, why: 'the default range' }
-        : { value: null, why: 'a built-in declaring nothing, see shipkit keys --burn-down' }
-    // a gate check nothing can key waits for a save only when no cadence
-    // says when to run it: a range or an every it declares is the rule
-    const clocked = fallback.value != null || row.plan?.every !== undefined || row.plan?.cron != null
+    const clock = row.runs.onClock
+    const plan = clock === false ? {} : clock === ONCE ? { every: ONCE } : { every: clock.every, whenInactive: clock.inactive }
     return {
         id: row.decl.id,
         title: row.title,
-        plan: row.plan ?? {},
-        // a decided fact is keyed on its declaration, so a save can move it
-        onChange: isForever(row) || (pop !== 'world' && (keyed || (row.gate && !clocked))),
-        fallback,
+        plan,
+        onChange: row.runs.onSave !== false,
+        fallback: { value: null, why: 'onClock false: only a save runs it' },
     }
 }
 
@@ -182,6 +159,8 @@ export function repoSource(d: RepoSourceDeps): PlanSource {
                     moved.delete(c.id)
                     continue
                 }
+                // 'burst': every quiet save burst, whatever moved
+                if (r.runs.onSave === 'burst') { out.push(c.id); continue }
                 const k = ledger.layer.keyFor(c.id)
                 if (k.key == null) {
                     out.push(c.id)

package/src/release/run-release.ts

@@ -112,6 +112,11 @@ export type ReleaseOpts = {
 export async function runReleaseGate(root: string, config: RepoConfig, print: (l: string) => void, o: { fix?: boolean; units?: ReleaseUnit[] } = {}): Promise<number> {
     return await runCi(root, {
         fix: o.fix ?? false,
+        // a check's repair never runs on the release path (runs.onRelease):
+        // only the mechanical slots (the formatter) may, when bump asks
+        fixRules: false,
+        // the rows declaring onRelease, whatever the tier
+        release: true,
         frozen: true,
         status: false,
         config,

package/src/repo-config.ts

@@ -59,29 +59,11 @@ export type ServeConfig = {
      *  prints beside localhost and rides on every ping message, because a
      *  phone cannot resolve localhost */
     publicHost?: string
-    /** the long running processes this repo needs (a dev server, a watcher).
-     *  The hub supervises them: a switch each on its page, a crash restarts,
-     *  and they outlive a hub restart */
-    processes?: ProcessDecl[]
     /** the ids of the global processes this repo needs (any house repo's
      *  `globalProcess` unit files). The home rail marks the repo while one is off */
     uses?: string[]
 }
 
-/** one long running process a repo needs, supervised by its hub */
-export type ProcessDecl = {
-    /** kebab-case, unique in this repo */
-    id: string
-    /** the command as a list of words, run from the repo root */
-    cmd: string[]
-    /** where it runs, repo-relative (default the repo root) */
-    cwd?: string
-    /** the url it serves, probed for up and shown as a link */
-    url?: string
-    /** starts with the hub. Default false: it starts from its switch */
-    auto?: boolean
-}
-
 export type RepoConfig = {
     /** the repo name, as every surface prints it: the gate header, the hub
      *  title, the motherhome row, the default hub port hash. The pre-commit
@@ -146,12 +128,17 @@ export type RepoConfig = {
     /** notify command for new RED needs while the hub serves, `{message}` substituted, as in a push-notification CLI */
     notifyCommand?: string
     /** the `.shipkit/<venue>/` release contracts: which ones this repo is excused
-     *  from, and any manifest the published toolkit does not carry. */
+     *  from, any manifest the published toolkit does not carry, and the dir
+     *  its site serves when the deploy does not say. */
     contracts?: {
         /** venue id to the reason it is waived. The only bypass, and it always prints */
         exempt?: Record<string, string>
         /** manifests declared by this repo, beside the built-in venues */
         extra?: ContractManifest[]
+        /** the dir the site serves, repo-relative, where the identity contract
+         *  wants favicon.png, og.png and logo.*. Absent: the dir the deploy names
+         *  (a Pages workflow's artifact path, a wrangler output dir), else `public` */
+        webRoot?: string
     }
     /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
      *  block — for ecosystem-specific names the published lib may not carry */
@@ -166,21 +153,25 @@ export type RepoConfig = {
      *  folder only: it never commits, untracks, tags or pushes on the parent's
      *  history. Rule SK015 fails when this and the disk disagree (core/nesting.ts) */
     nested?: boolean
-    /** WHERE EACH CHECK RUNS, keyed by check id. One declaration for a
-     *  question that used to have three: `'always'` every gate and every
-     *  health pass, `'release'` only at `--full` and on the release path,
-     *  `'health'` only in the health pass, `'off:<reason>'` not at all.
-     *  `defineRepo` throws on a value it cannot parse, on an `off` with no
-     *  reason, and on an id no check carries. The hub writes this
-     *  map through the managed block in this file (core/when-block.ts). */
+    /** THE CHECKS THIS REPO TURNS OFF, check id → why. The one thing a repo
+     *  says about a check it does not own: where a check runs is its own
+     *  declaration (build/shipkit/runs.md), and an off check runs in no
+     *  context. `defineRepo` throws on a blank reason and on a rule id no
+     *  check carries. The hub writes this map through the managed block in
+     *  this file (core/when-block.ts). */
+    off?: Record<string, string>
+    /** RETIRED, read only while SK029 ports it into `off`: an `'off:<why>'`
+     *  value reads as `off`, and any other word is refused, because a repo
+     *  no longer places a check. Dies once `shipkit fleet` shows no repo
+     *  carrying it */
     when?: Record<string, string>
     /** WHAT A HEALTHY RUN OF EACH CHECK TAKES, in ms, keyed by check id. A
      *  check that passes over its budget prints a WARN and reads yellow, and
      *  never blocks. It wins over the check's own `budgetMs` and the default
      *  for its kind (core/budget.ts). An id no check carries fails the run,
-     *  the same as a `when` entry. */
+     *  the same as an `off` entry. */
     budgets?: Record<string, number>
-    /** DEPRECATED, read into `when` as `off:<reason>`: rule id → the reason
+    /** RETIRED, read as `off` while SK029 ports it there: rule id → the reason
      *  this repo breaks that invariant on purpose. An exempted rule does not
      *  lint and prints a skip line carrying the reason. `defineRepo` throws on
      *  an unknown id or a blank reason */
@@ -210,7 +201,7 @@ export type RepoConfig = {
         /** widens the read-only tool allowlist SK008 enforces (default Read, Grep, Glob, Bash) */
         tools?: string[]
     }
-    /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
+    /** ONE WAY IN escape hatch (build/shipkit/one-way-in.md): governed script names this
      *  repo keeps as a direct tool call. Declared per NAME, never as a list of
      *  banned binaries: the invariant is about which VERBS an agent reaches
      *  for, and a binary blocklist goes stale the day a repo changes runner.
@@ -295,18 +286,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
-
-const KEBAB = /^[a-z0-9][a-z0-9-]*$/
-const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
-
-/** why a process declaration cannot run, or null */
-export function processProblem(d: ProcessDecl): string | null {
-    if (!KEBAB.test(d.id ?? '')) return `serve.processes: id '${String(d.id)}' must be kebab-case`
-    if (!words(d.cmd)) return `serve.processes['${d.id}'] needs cmd: a list of words`
-    if (d.url != null && !/^https?:\/\//.test(d.url)) return `serve.processes['${d.id}'].url must be an http url`
-    return null
-}
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -316,13 +296,8 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // a half-declared reviewer would lint a path like `.claude/agents/.md`
     if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
         throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
-    const pids = new Set<string>()
-    for (const d of c.serve?.processes ?? []) {
-        const why = processProblem(d)
-        if (why != null) throw new Error(`defineRepo: ${why}`)
-        if (pids.has(d.id)) throw new Error(`defineRepo: serve.processes declares '${d.id}' twice`)
-        pids.add(d.id)
-    }
+    if (c.serve != null && 'processes' in c.serve)
+        throw new Error(`defineRepo: serve.processes was removed; declare each process in a <name>.shipkit.ts file as \`export default globalProcess({...})\``)
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))
@@ -379,17 +354,22 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // repo rules are validated against the built-ins, so a bad id, a duplicate,
     // or an SK squatter dies at config load, not silently mid-check
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: builtinCheckIds() })
-    // a `when` moves a check off the gate, so a value it cannot act on dies
-    // here. The RULE namespace is the one this file can check: a task is
-    // resolved from the floor and a check is discovered on disk, so those two
-    // are caught by the gate against the real inventory (core/when.ts
-    // unknownWhenIds)
+    // `off` silences a check, so it names one that exists and says why. The
+    // RULE namespace is the one this file can check: a task is resolved from
+    // the floor and a check is discovered on disk, so those two are caught by
+    // the gate against the real inventory (core/when.ts unknownOffIds)
+    for (const [id, reason] of Object.entries(c.off ?? {})) {
+        if (id.trim() === '') throw new Error(`defineRepo: off has an entry with no check id`)
+        if (typeof reason !== 'string' || reason.trim() === '') throw new Error(`defineRepo: off.${id} needs a reason: a check nobody can explain is a silenced gate`)
+        if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
+            throw new Error(`defineRepo: off.${id} names no rule, the ids are in \`shipkit checks\``)
+    }
+    // the retired `when`: only its `off:<why>` word still means something
     for (const [id, raw] of Object.entries(c.when ?? {})) {
-        if (id.trim() === '') throw new Error(`defineRepo: when has an entry with no check id`)
         const w = parseWhen(raw)
         if (typeof w === 'string') throw new Error(`defineRepo: when.${id} ${w}`)
-        if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
-            throw new Error(`defineRepo: when.${id} names no rule, the ids are in \`shipkit checks\``)
+        if (w.at !== 'off')
+            throw new Error(`defineRepo: when.${id} '${raw}' no longer places a check: every check declares where it runs (build/shipkit/runs.md). A repo can only turn one off: off: { ${id}: '<why>' }`)
     }
     // a budget turns a slow pass yellow, so a value it cannot compare with dies here
     for (const [id, v] of Object.entries(c.budgets ?? {})) {

package/src/rules/rule.ts

@@ -6,14 +6,14 @@
 //
 // A new invariant is a `<name>.check.ts` file: `check({ blocking, run })`,
 // dropped anywhere in the repo, discovered with no config edit.
-import { whenOfRule } from '../core/when.ts'
+import { repoOff } from '../core/when.ts'
 import { tagCheckLines, checkCacheExtra, type Rule, type RuleEnv } from '../check.ts'
 
 export type { FixResult, Rule, RuleEnv } from '../check.ts'
 
 /** the config part of a rule's cache identity, including where it runs */
 export function ruleCacheExtra(rule: Rule, env: RuleEnv): string | undefined {
-    return checkCacheExtra(rule, env, whenOfRule(env.config, rule.id))
+    return checkCacheExtra(rule.cacheKey?.(env), repoOff(env.config, rule.id)?.reason ?? null)
 }
 
 /** tag every severity line with the rule id (check.ts owns the rendering) */

package/src/scaffold/files/agent-coding.md

@@ -7,7 +7,7 @@ always-loaded one, and route the rest by surface.
 ## Gates
 
 - **Spec-first**: the `agent/` page changes BEFORE the code it describes.
-- **`shipkit ci` is the verification.** Run it, not the linter, the
+- **`sk ci` is the verification.** Run it, not the linter, the
   typechecker and the tests one at a time.
 - **Repro before fix**: write the failing test, then fix, then re-run it.
 - One code path per concern. Delete the redundant mechanism rather than

package/src/scaffold/files/agent-index.md

@@ -5,7 +5,7 @@
 ## Quick start
 
 - `bun run hub` → the repo toolbox at http://localhost:{{PORT}}
-- `shipkit ci` → THE gate: run it to check your work, never the parts
+- `sk ci` → THE gate: run it to check your work, never the parts
 
 This folder is the project's internal wiki and its SPEC. Update the page
 BEFORE the change it describes.

package/src/scaffold/files/verify-skill.md

@@ -11,12 +11,12 @@ description: Prove a change in THIS project actually works — drive the real fl
 
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
-- Logic → fast headless bun tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
+- Logic → fast headless bun tests, run through `sk ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
 - Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 
 ## This project
-- Full gate: `shipkit ci` — THE command, never the linter, the typechecker
+- Full gate: `sk ci` — THE command, never the linter, the typechecker
   and the tests one at a time.
 - TODO, fill these in once the stack exists: the dev server command and its
   port (check it is not already running: `curl -s localhost:PORT >/dev/null

package/src/serve/hub-app/activity-st.ts

@@ -9,6 +9,7 @@ import { clampCap, DEFAULT_CAP, DEFAULT_MINUTES, idleRow, WINDOW_MINUTES, type A
 // the words the page and `shipkit cross-repo-activity` share live beside the shapes
 export { ageShort, CAP_MAX, CAP_MIN, clampCap, DEFAULT_CAP, dirtWords, filesWords, upstreamWords, windowWords } from '../../home/activity-shape.ts'
 import type { HomeSt } from './home-st.ts'
+import { ownTrouble, reach } from './reach.ts'
 
 export const ACTIVITY_POLL_MS = 60_000
 const MINUTES_KEY = 'home:activity:minutes'
@@ -105,11 +106,11 @@ export class ActivitySt {
     /** the repo in Fork, the git client: the daemon opens it by name */
     async openFork(name: string): Promise<void> {
         try {
-            const r = await fetch('/api/projects/fork', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name }) })
+            const r = await reach('/api/projects/fork', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name }) })
             if (!r.ok) throw new Error(await r.text())
             runInAction(() => { this.error = '' })
         } catch (e) {
-            runInAction(() => { this.error = `open ${name} in Fork: ${(e as Error).message}` })
+            runInAction(() => { this.error = ownTrouble(e, this.st.machine, (m) => `open ${name} in Fork: ${m}`) })
         }
     }
 
@@ -128,12 +129,12 @@ export class ActivitySt {
         const id = ++this.gen
         runInAction(() => { this.loading = true; this.nextAt = Date.now() + ACTIVITY_POLL_MS })
         try {
-            const r = await fetch(`/api/home/activity.json?m=${this.minutes}${fresh ? '&fresh=1' : ''}`, { signal: AbortSignal.timeout(30_000) })
+            const r = await reach(`/api/home/activity.json?m=${this.minutes}${fresh ? '&fresh=1' : ''}`, { signal: AbortSignal.timeout(30_000) })
             if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
             const j = (await r.json()) as ActivityAnswer
             runInAction(() => { if (id === this.gen) { this.data = j; this.error = '' } })
         } catch (e) {
-            runInAction(() => { if (id === this.gen) this.error = (e as Error).message })
+            runInAction(() => { if (id === this.gen) this.error = ownTrouble(e, this.st.machine) })
         } finally {
             // the countdown starts when the answer lands, so reads never overlap
             runInAction(() => { if (id === this.gen) { this.loading = false; this.nextAt = Date.now() + ACTIVITY_POLL_MS } })

package/src/serve/hub-app/activity-view.tsx

@@ -52,7 +52,7 @@ const Next = observer(({ app }: { app: HomeSt }) => {
 })
 
 /** one commit's cells; `old` is the last one, from before the window */
-const Commit = ({ c, now, old }: { c: ActivityCommit; now: number; old: boolean }) => (
+export const Commit = ({ c, now, old }: { c: ActivityCommit; now: number; old: boolean }) => (
     <>
         <td className="acsha">{c.sha}</td>
         <td className="acwhen" title={stampWords(c.at)}>{ageShort(c.at, now)}</td>
@@ -71,12 +71,12 @@ export const failingOf = (r: ActivityRow): StatusCheck[] => {
     if (r.failing != null) return r.failing
     const c = r.status
     if (c == null) return []
-    const one = (id: string, status: 'fail' | 'warn'): StatusCheck => ({ id, title: id, status, at: c.since[id] ?? null, line: '' })
+    const one = (id: string, status: 'fail' | 'warn'): StatusCheck => ({ id, title: id, status, at: c.since[id] ?? null, line: '', lines: [] })
     return [...c.reds.map((id) => one(id, 'fail')), ...c.warns.map((id) => one(id, 'warn'))]
 }
 
 /** each failing and warning check: its id (a link to its page), its title,
- *  how old that outcome is, and the first line it printed about it */
+ *  how old that outcome is, and every line it printed about it */
 export const CheckList = observer(({ app, r }: { app: HomeSt; r: ActivityRow }) => {
     const now = app.activity.now
     return (
@@ -93,7 +93,7 @@ export const CheckList = observer(({ app, r }: { app: HomeSt; r: ActivityRow })
                         {c.title !== c.id ? <span className="acchktitle">{c.title}</span> : null}
                         {c.at == null ? null : <span className="acdim" title={stampWords(c.at)}>{ageShort(c.at, now)}</span>}
                     </span>
-                    {c.line === '' ? null : <span className="acchkline">{c.line}</span>}
+                    {(c.lines ?? (c.line === '' ? [] : [c.line])).map((l, i) => <span key={i} className="acchkline">{l}</span>)}
                 </li>
             ))}
         </ul>

package/src/serve/hub-app/admin-view.tsx

@@ -26,17 +26,19 @@ export const AdminPage = observer(({ app }: { app: RepoSt }) => {
                 <span className="tid">admin</span>
                 <h3 className="ctitle">{name}</h3>
             </div>
-            <Row title="reload the hub" says={`stops ${name}'s hub in the daemon and loads it again, its repo.config.ts read fresh and its processes started again. The daemon already does it on its own when repo.config.ts changes: this is for a hub that is stuck.${w == null ? '' : ` Its hub is ${w.status} now.`}`}>
-                <button className="ghost" onClick={() => void a.reload()}>reload</button>
-            </Row>
-            <Row title="keep active" says="an active repo runs the checks the plan holds for it and gets its red pings. It is active on its own while an agent works in it or VS Code has it open: this keeps it active without either.">
-                <label className="adflag"><input type="checkbox" checked={a.active} onChange={(e) => void a.setActive(e.currentTarget.checked)} />active</label>
-            </Row>
-            <Row title="archive" says="it leaves the project list for the archived page, and nothing runs there: no hub, no watch, no plan rows, no processes, no widgets. Written to repo.config.ts as archived: true, and undone from the archived page.">
-                {a.confirming
-                    ? <span className="adconfirm"><span>archive {name}?</span><button className="primary" onClick={() => a.archive()}>archive it</button><button className="ghost" onClick={() => a.cancel()}>cancel</button></span>
-                    : <button className="ghost" onClick={() => a.askArchive()}>archive</button>}
-            </Row>
+            <div className="adbox">
+                <Row title="reload the hub" says={`stops ${name}'s hub in the daemon and loads it again, its repo.config.ts read fresh and its processes started again. The daemon already does it on its own when repo.config.ts changes: this is for a hub that is stuck.${w == null ? '' : ` Its hub is ${w.status} now.`}`}>
+                    <button className="ghost" onClick={() => void a.reload()}>reload</button>
+                </Row>
+                <Row title="keep active" says="an active repo runs the checks the plan holds for it and gets its red pings. It is active on its own while an agent works in it or VS Code has it open: this keeps it active without either.">
+                    <label className="adflag"><input type="checkbox" checked={a.active} onChange={(e) => void a.setActive(e.currentTarget.checked)} />active</label>
+                </Row>
+                <Row title="archive" says="it leaves the project list for the archived page, and nothing runs there: no hub, no watch, no plan rows, no processes, no widgets. Written to repo.config.ts as archived: true, and undone from the archived page.">
+                    {a.confirming
+                        ? <span className="adconfirm"><span>archive {name}?</span><button className="primary" onClick={() => a.archive()}>archive it</button><button className="ghost" onClick={() => a.cancel()}>cancel</button></span>
+                        : <button className="ghost" onClick={() => a.askArchive()}>archive</button>}
+                </Row>
+            </div>
         </div>
     )
 })