rvlib-shipkit 1.4.0 → 1.6.0

package/src/checks/SK019-tests-run-in-units.check.ts

@@ -1,5 +1,5 @@
-// SK019 — tests run through the generated test checks only (build/shipkit.md,
-// the test checks). The floor `test` slot and one `test:<unit>` per declared
+// SK019 — tests run through the generated test checks only (build/shipkit/test-runner.md).
+// The floor `test` slot and one `test:<unit>` per declared
 // unit are the ONE way tests run: in the unit's dir with its bunfig and
 // preload, parallel, timed against the budget, and planned file by file by
 // SK018. A hand written check that runs `bun test` itself is a second runner
@@ -9,7 +9,7 @@
 // Its own id rather than a line of SK018: SK018 answers "does every test file
 // run", this one "does anything else run them", and each is read from
 // different files (test files and bunfigs there, check sources and the config
-// here), so each keeps its own key, row and `when` switch.
+// here), so each keeps its own key, row and `off` switch.
 import { dirname, posix, relative } from 'path'
 import { check } from '../check.ts'
 import { repoCheckSources } from '../core/legacy-shapes.ts'
@@ -36,7 +36,11 @@ export const testsRunInUnits = check({
     blocking: true,
     title: 'tests run in unit checks',
     description: 'no check runs the test runner itself: tests run only in the generated test checks',
-    owner: 'build/shipkit.md',
+    owner: 'build/shipkit/test-runner.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         // the toolkit's own checks (this file's dir) live inside the repo that
         // hosts it, and a built-in that WRITES a test script (SK001) is not a

package/src/checks/SK020-self-spawning-check.check.ts

@@ -132,6 +132,10 @@ export const selfSpawningCheck = check({
     description: 'no check file runs its own body by spawning itself',
     owner: OWNER,
     blocking: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const found = repoCheckSources(c).flatMap((f) => {
             if (f.src == null || isLegacyCheckSource(f.src)) return []

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -1,4 +1,4 @@
-// SK022 machine runs the pin (build/shipkit.md): on a machine with a house
+// SK022 machine runs the pin (build/shipkit/home.md): on a machine with a house
 // every shipkit runs the house copy, whatever a repo installed, so a repo's
 // rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
 // newer than the one this process runs: a rule or an api that pin relies on
@@ -24,11 +24,13 @@ export const machineRunsThePin = check({
     blocking: false,
     title: 'machine runs the pin',
     description: 'the shipkit this machine runs is at least the version this repo pins',
-    owner: 'build/shipkit.md',
+    owner: 'build/shipkit/home.md',
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the pin, the install (gitignored) and the version this machine runs,
     // which is no file of the repo
-    inputs: ['package.json'],
-    cacheKey: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}`,
+    cache: { by: 'files', inputs: ['package.json'], key: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}` },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const pkg = c.json<Pkg>('package.json')
         const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]

package/src/checks/SK024-identity-colors.check.ts

@@ -18,9 +18,11 @@ export const identityColors = check({
     title: 'identity colors',
     description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
     owner: 'build/shipkit/built-in-checks.md',
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
     // the config, and the installed lib that says whether it knows the key
-    inputs: [CONFIG_FILE],
-    cacheKey: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}`,
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}` },
+    fix: 'manual',
+    applies: 'always',
     run: (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return c.note(`no ${CONFIG_FILE}`)
@@ -32,7 +34,7 @@ export const identityColors = check({
         if (why != null) return c.warn(`${CONFIG_FILE}: ${why}`, FIX)
         c.ok(`identity ${id!.colorLight} on light, ${id!.colorDark} on dark`)
     },
-    fix: async (c) => {
+    repair: async (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return { changed: false, summary: `no ${CONFIG_FILE}` }
         const have = identityOfText(text)

package/src/checks/SK025-release-drift.check.ts

@@ -41,11 +41,10 @@ export const releaseDrift = check({
     title: 'release drift',
     description: 'every unit this repo releases matches npm and its push remote',
     owner: 'build/shipkit/built-in-checks.md',
-    when: 'health',
-    ttl: '20h',
-    every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'),
-    planOff: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
-    cacheKey: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(','),
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'), inactive: 'wait' } },
+    cache: { by: 'ttl', span: '20h', key: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(',') },
+    fix: 'none',
+    applies: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
     run: async (c) => {
         const ids = new Set(releasedUnits(c.root, c.config).map((u) => u.id))
         if (ids.size === 0) return void c.lines.push({ kind: 'skip', text: 'this repo releases nothing: no npm root, no release config, no units' })

package/src/checks/SK026-asks-autoclose.check.ts

@@ -14,11 +14,11 @@ export const asksAutoclose = check({
     title: 'asks auto close',
     description: 'no open ask whose own probe passes stays in the queue',
     owner: 'build/shipkit/built-in-checks.md',
-    when: 'health',
-    never: "runs each open ask's own probe, a shell command that reads the world",
-    every: ['20h', '28h'],
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: "runs each open ask's own probe, a shell command that reads the world" },
+    fix: 'none',
     // it only probes an ask that carries one, and archives one marked done
-    planOff: (env) => {
+    applies: (env) => {
         const dir = join(env.root, env.config.asks?.dir ?? LAYOUT.asks)
         if (!existsSync(dir)) return 'no asks queue'
         return listAsks(dir).some((a) => a.check != null || a.status === 'done') ? null : 'no open ask carries a probe'

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -14,8 +14,11 @@ export const agentWikiLinks = check({
     title: 'agent wiki links',
     description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
     owner: 'meta/agent-folder.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
-    inputs: ['agent'],
+    cache: { by: 'files', inputs: ['agent'], key: null },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
         const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })

package/src/checks/SK028-readme.check.ts

@@ -60,7 +60,7 @@ const REQUIREMENTS: Requirement[] = [
 
 /** the other way out, for a repo that cannot show one: the rule off, with the
  *  reason `defineRepo` requires (core/when.ts) */
-const OFF = `or, when this repo cannot show one, turn the rule off with the reason: when: { SK028: 'off:<why this repo shows no screenshot>' } in repo.config.ts, inside its shipkit gate block`
+const OFF = `or, when this repo cannot show one, turn the rule off with the reason: off: { SK028: '<why this repo shows no screenshot>' } in repo.config.ts, inside its shipkit gate block`
 
 export const readme = check({
     id: 'SK028',
@@ -68,6 +68,10 @@ export const readme = check({
     title: 'readme',
     description: 'README.md exists and shows at least one screenshot',
     owner: 'build/shipkit/built-in-checks.md',
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const md = c.read(README)
         if (md == null) return c.warn(`${README}: exists: no ${README} at the repo root`, `write README.md: what the repo is, and a screenshot of it; ${OFF}`)

package/src/checks/SK029-explicit-check-files.check.ts

@@ -0,0 +1,95 @@
+// SK029 explicit check files (build/shipkit/runs.md owns the declaration):
+// every check file of the repo declares runs, cache, fix and applies, with
+// no retired key. A file that does not does not load, and discovery shows
+// it as one failing row. The repair ports it with the values the retired
+// keys resolved to (core/port-check-file.ts), so the check keeps running
+// where it ran, and the ci fix pass applies it before the gate reads the
+// files: a repo carried across by its first `shipkit ci`. The same holds for
+// the config: a retired `when` (only its `off:<why>` entries still load) and
+// `ruleExempt` become `off` entries in the managed block.
+import { join } from 'path'
+import { check, type FixResult } from '../check.ts'
+import { unportedCheckFiles } from '../core/port-check-files.ts'
+import type { PortRun } from '../core/port-check-cli.ts'
+import type { ConfigPlan, ConfigRewrite } from '../core/config-rewrite.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+/** the write half, run as its own process: it walks import closures on disk */
+const PORT_CLI = join(import.meta.dir, '../core/port-check-cli.ts')
+/** the config half, run as its own process: it loads repo.config.ts */
+const CONFIG_REWRITE = join(import.meta.dir, '../core/config-rewrite.ts')
+
+/** the retired config keys this repo still carries, and the `off` entries
+ *  they become. defineRepo already refused every `when` word but `off:<why>` */
+export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string> } {
+    const off: Record<string, string> = {}
+    for (const [id, raw] of Object.entries(c.when ?? {})) off[id] = raw.trim().replace(/^off:?/, '').trim()
+    for (const [id, why] of Object.entries(c.ruleExempt ?? {})) off[id] ??= why
+    const keys = [...(c.when != null ? ['when'] : []), ...(c.ruleExempt != null ? ['ruleExempt'] : [])]
+    return { keys, off }
+}
+
+export const explicitCheckFiles = check({
+    id: 'SK029',
+    title: 'explicit check files',
+    description: 'every check file declares runs, cache, fix and applies, and the config says only off',
+    owner: 'build/shipkit/runs.md',
+    blocking: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // the listing of check files and their sources, read through `c`
+    cache: { by: 'reads' },
+    // the port is mechanical: every value it writes is what the retired keys
+    // resolved to, so the fix pass applies it without asking
+    fix: 'ci',
+    applies: 'always',
+    run: (c) => {
+        const files = unportedCheckFiles(c)
+        const cfg = retiredOff(c.config)
+        if (files.length === 0 && cfg.keys.length === 0) return c.ok('every check file declares runs, cache, fix and applies, and the config says only off')
+        for (const f of files) c.fail(`${f.rel} still declares the retired shape (${f.keys.join(', ')}), so it does not load`)
+        if (cfg.keys.length > 0) c.fail(`repo.config.ts still carries ${cfg.keys.join(' and ')}: a repo only turns a check off, as off: { <id>: '<why>' }`)
+        c.fail(`${files.length + (cfg.keys.length > 0 ? 1 : 0)} file(s) to port`, 'shipkit check --fix SK029 ports each one with the values it ran on, and `shipkit ci` does it in its fix pass')
+    },
+    repair: async (c): Promise<FixResult> => {
+        const files = unportedCheckFiles(c)
+        const cfg = retiredOff(c.config)
+        if (files.length === 0 && cfg.keys.length === 0) return { changed: false, summary: 'every check file is explicit already, and the config says only off' }
+        const did: string[] = []
+        const hand: string[] = []
+        if (files.length > 0) {
+            const r = await c.exec([process.execPath, PORT_CLI, c.root, ...files.map((f) => f.rel)], { cwd: c.root, timeoutMs: 60_000 })
+            try {
+                const run = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') as PortRun
+                if (run.did.length > 0) did.push(`ported ${run.did.join('; ')}`)
+                hand.push(...run.hand)
+            } catch {
+                hand.push(`the port did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)}): port ${files.map((f) => f.rel).join(', ')} by hand (build/shipkit/runs.md)`)
+            }
+        }
+        if (cfg.keys.length > 0) {
+            // `when` sits inside the managed block, so it goes first and the
+            // block describes the config again before the entries land
+            const plan: ConfigPlan = {
+                off: cfg.off,
+                drop: [
+                    ...(c.config.when != null ? [{ key: 'when', why: 'its off entries are `off` now', phase: 'first' as const }] : []),
+                    ...(c.config.ruleExempt != null ? [{ key: 'ruleExempt', why: 'its exemptions are `off` now', phase: 'afterOff' as const }] : []),
+                ],
+                name: c.config.name,
+            }
+            const r = await c.exec([process.execPath, CONFIG_REWRITE, c.root, JSON.stringify(plan)], { cwd: c.root, timeoutMs: 60_000 })
+            try {
+                const out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') as ConfigRewrite
+                did.push(...out.did)
+                hand.push(...out.hand)
+                if (out.restored != null) hand.push(`repo.config.ts was left as it was: ${out.restored}`)
+            } catch {
+                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify(cfg.off)} by hand and drop ${cfg.keys.join(', ')}`)
+            }
+        }
+        const summary = [did.length > 0 ? did.join('; ') : 'nothing ported', ...(hand.length > 0 ? [`${hand.length} by hand: ${hand.join(' | ')}`] : [])].join('. ')
+        return { changed: did.length > 0, summary }
+    },
+})
+
+export default explicitCheckFiles

package/src/checks/SK030-cache-audit.check.ts

@@ -0,0 +1,34 @@
+// SK030 cache audit (build/shipkit/runs.md owns the cache): a sample of the
+// checks the cache answers is re-run fresh about once a day, and a cached
+// green a fresh run disagrees with fails, naming the check whose key misses a
+// path. The work is `sk cache-audit` (core/cache-audit.ts), in its own
+// process, because it runs other checks.
+import { join } from 'path'
+import { check } from '../check.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+export const cacheAudit = check({
+    id: 'SK030',
+    title: 'cache audit',
+    description: 'a sample of cached answers matches what a fresh run of each check says',
+    owner: 'build/shipkit/runs.md',
+    blocking: true,
+    // never a gate: it re-runs other checks. The daemon asks it about once a
+    // day, and only while somebody works in the repo
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: 'it runs other checks fresh, so its answer is that run itself' },
+    fix: 'none',
+    applies: 'always',
+    run: async (c) => {
+        const r = await c.exec([process.execPath, CLI, 'cache-audit', '--json'], { cwd: c.root, timeoutMs: 600_000 })
+        let out: { pool: number; rows: { id: string; cached: string; fresh: string; keyedOn: string }[]; stale: { id: string; cached: string; fresh: string; keyedOn: string }[] }
+        try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk cache-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
+        if (out.rows.length === 0) return c.note(`nothing to audit: the cache answers none of this repo's checks right now`)
+        for (const s of out.stale)
+            c.fail(`${s.id}: the cache said ${s.cached}, a fresh run says ${s.fresh}, so its key misses something it reads`, `${s.keyedOn === 'files' ? 'add the path to its cache.inputs' : 'move the read through c'}, then sk keys --why ${s.id}`)
+        if (out.stale.length === 0) c.ok(`${out.rows.map((x) => x.id).join(', ')}: every cached answer is what a fresh run says (${out.rows.length} of ${out.pool} cached)`)
+    },
+})
+
+export default cacheAudit

package/src/checks/SK031-trace-audit.check.ts

@@ -0,0 +1,39 @@
+// SK031 traced audit (build/shipkit/cache.md owns the key): about once a day
+// each gate task runs under the tracer, and a gitignored path it reads that
+// its key misses joins that task's key from the kept answer. SK032 carries the
+// kept proposals into repo.config.ts in the gate's fix pass. The work is
+// `sk trace-audit` (core/trace-audit.ts), in its own process, because it runs
+// the gate's tasks. On wherever the tracer runs, unless the machine opted out.
+import { join } from 'path'
+import { check } from '../check.ts'
+import { traceUnavailable } from '../trace/tracer.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+export const traceAuditCheck = check({
+    id: 'SK031',
+    title: 'traced audit',
+    description: 'every gitignored path a gate task reads is in its key',
+    owner: 'build/shipkit/cache.md',
+    blocking: false,
+    // never a gate: it runs the gate's tasks. The daemon asks it about once a
+    // day, and only while somebody works in the repo
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: 'it runs the gate tasks under the tracer, so its answer is that run itself' },
+    fix: 'none',
+    applies: () => traceUnavailable(),
+    run: async (c) => {
+        const r = await c.exec([process.execPath, CLI, 'trace-audit', '--json'], { cwd: c.root, timeoutMs: 1_200_000 })
+        let out: { skipped?: string; tasks: { id: string; status: string; why?: string; uncovered: string[]; propose: string[] }[] }
+        try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk trace-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
+        if (out.skipped != null) return c.note(`nothing traced: ${out.skipped}`)
+        for (const t of out.tasks.filter((x) => x.status === 'unaudited')) c.warn(`${t.id} could not be audited: ${t.why}`)
+        const missing = out.tasks.filter((x) => x.uncovered.length > 0)
+        // a finding joins its task's key at once (core/audit-report.ts), so it
+        // is news, never a failure: SK032 carries it into repo.config.ts
+        for (const t of missing) c.ok(`${t.id} reads ${t.uncovered.length} gitignored path(s) the config does not name, keyed from this audit: ${t.propose.join(', ')}`)
+        if (missing.length === 0) c.ok(`${out.tasks.filter((x) => x.status === 'audited').length} gate task(s) audited: every gitignored path they read is in their key`)
+    },
+})
+
+export default traceAuditCheck

package/src/checks/SK032-ignored-inputs.check.ts

@@ -0,0 +1,79 @@
+// SK032 ignored inputs current (build/shipkit/cache.md owns the key): what the
+// last traced audit (SK031) found a task reading outside its key is in
+// repo.config.ts ignoredInputs, so other machines and clones key it too. The repair writes the missing entries into
+// the managed block, so the gate's fix pass carries each finding into the
+// config. Nothing is traced here: it reads the audit SK031 kept.
+import { join } from 'path'
+import { check } from '../check.ts'
+import { describeByTask, pendingByTask, type AuditReport } from '../core/ignored-inputs.ts'
+
+const CLI = join(import.meta.dir, '../cli.ts')
+
+/** the first rvlib-shipkit release whose `defineRepo` knows `ignoredInputs`.
+ *  A repo whose pin allows an older one loads its config elsewhere (a CI job
+ *  installing from npm, a fresh clone) with that older copy, which refuses
+ *  the unknown key: so nothing is written until the pin says at least this */
+export const IGNORED_INPUTS_SINCE = '1.6.0'
+
+const parts = (v: string): number[] => v.split('.').map((n) => Number.parseInt(n, 10) || 0)
+const atLeast = (v: string, min: string): boolean => {
+    const a = parts(v), b = parts(min)
+    for (let i = 0; i < 3; i++) if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0)
+    return true
+}
+
+/** why the repo's pin cannot carry the key yet, or null. No pin (the repo
+ *  that hosts the toolkit, or one running it from source) can carry it */
+function pinTooOld(pkg: string | null): string | null {
+    if (pkg == null) return null
+    let range: string | undefined
+    try {
+        const j = JSON.parse(pkg) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        range = j.devDependencies?.['rvlib-shipkit'] ?? j.dependencies?.['rvlib-shipkit']
+    } catch {
+        return null
+    }
+    const min = range == null ? null : /(\d+\.\d+\.\d+)/.exec(range)?.[1] ?? null
+    if (min == null || range!.startsWith('link:') || range!.startsWith('file:') || range!.startsWith('workspace:')) return null
+    return atLeast(min, IGNORED_INPUTS_SINCE) ? null : `package.json pins rvlib-shipkit ${range}, which allows a release before ${IGNORED_INPUTS_SINCE} that refuses ignoredInputs: raise the pin to ^${IGNORED_INPUTS_SINCE} first`
+}
+
+/** the kept audit, read through c so the reads key follows it */
+function kept(text: string | null): AuditReport | null {
+    try { return text == null ? null : (JSON.parse(text) as AuditReport) } catch { return null }
+}
+
+export const ignoredInputsCheck = check({
+    id: 'SK032',
+    title: 'ignored inputs current',
+    description: 'every gitignored path the traced audit saw a task read is in ignoredInputs',
+    owner: 'build/shipkit/cache.md',
+    blocking: false,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: false, onHealth: true, onSave: false, onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
+    run: (c) => {
+        const missing = pendingByTask(kept(c.state('trace-audit.json')), c.config.ignoredInputs ?? {})
+        const n = Object.values(missing).flat().length
+        if (n === 0) return c.ok('repo.config.ts ignoredInputs covers what the last traced audit found')
+        // the keys on this machine already read the kept audit (core/audit-report.ts),
+        // so what is missing here is the copy other machines and clones see
+        const old = pinTooOld(c.read('package.json'))
+        if (old != null) return c.ok(`${n} path(s) the traced audit found are keyed on this machine only: ${old}`)
+        c.warn(`the traced audit found ${describeByTask(missing)}: keyed on this machine, not yet in repo.config.ts ignoredInputs`, 'sk ci writes them, and sk trace-audit --fix says why when it cannot')
+    },
+    repair: async (c) => {
+        const missing = pendingByTask(kept(c.state('trace-audit.json')), c.config.ignoredInputs ?? {})
+        if (Object.keys(missing).length === 0) return { changed: false, summary: 'nothing to add' }
+        const old = pinTooOld(c.read('package.json'))
+        if (old != null) return { changed: false, summary: old }
+        // the managed block writer loads repo.config.ts, which no read through
+        // c can stand for, so it runs in its own process
+        const r = await c.exec([process.execPath, CLI, 'trace-audit', '--fix'], { cwd: c.root, timeoutMs: 60_000 })
+        if (r.code !== 0) return { changed: false, summary: `sk trace-audit --fix failed: ${r.out.trim().split('\n').at(-1) ?? `exit ${r.code}`}` }
+        return { changed: true, summary: `repo.config.ts ignoredInputs gained ${describeByTask(missing)}` }
+    },
+})
+
+export default ignoredInputsCheck

package/src/cli/cmd_Asks.ts

@@ -15,7 +15,7 @@ export class AsksCommand extends Command {
     static override usage = Command.Usage({
         category: 'Asks',
         description: 'list open asks — the per-repo human action queue',
-        examples: [['list open asks', 'shipkit asks']],
+        examples: [['list open asks', 'sk asks']],
     })
 
     async execute(): Promise<number> {
@@ -37,7 +37,7 @@ export class AsksCheckCommand extends Command {
     static override usage = Command.Usage({
         category: 'Asks',
         description: 'probe every open ask and archive the ones whose check now passes',
-        examples: [['probe + auto-close', 'shipkit asks check']],
+        examples: [['probe + auto-close', 'sk asks check']],
     })
 
     async execute(): Promise<number> {
@@ -59,9 +59,9 @@ export class AskNewCommand extends Command {
         category: 'Asks',
         description: 'create a new ask file in the queue',
         examples: [
-            ['minimal', 'shipkit ask "rotate the API token"'],
-            ['with a reason', 'shipkit ask "buy the domain" --why "landing page is blocked on it"'],
-            ['with metadata', 'shipkit ask "buy the domain" --kind action --blocks deploy --check "dig +short example.com"'],
+            ['minimal', 'sk ask "rotate the API token"'],
+            ['with a reason', 'sk ask "buy the domain" --why "landing page is blocked on it"'],
+            ['with metadata', 'sk ask "buy the domain" --kind action --blocks deploy --check "dig +short example.com"'],
         ],
     })
 

package/src/cli/cmd_Assets.ts

@@ -2,7 +2,11 @@
 // (ComfyUI or procedural canvas), curate in the studio, ship with metadata
 // write-through. Thin clipanion surfaces; logic in assets/run-assets.ts.
 import { Command, Option } from 'clipanion'
-import { runAssetsCheck, runAssetsGen, runAssetsIdentity, runAssetsTopUp, type AssetsIo } from '../assets/run-assets.ts'
+import type { AssetsIo } from '../assets/run-assets.ts'
+
+// loaded when an assets command RUNS: it pulls in canvas, sharp and comfy-ts,
+// which every other command would otherwise pay for at startup
+const assets = (): Promise<typeof import('../assets/run-assets.ts')> => import('../assets/run-assets.ts')
 
 const ioOf = (cmd: Command): AssetsIo => ({
     print: (l) => cmd.context.stdout.write(`${l}\n`),
@@ -19,8 +23,8 @@ export class AssetsFillCommand extends Command {
         category: 'Assets',
         description: 'top rolls up to N per asset (canvas or comfy), sparsest-first',
         examples: [
-            ['every asset up to 8 rolls', 'shipkit assets fill 8'],
-            ['only two categories', 'shipkit assets fill 8 icons sprites'],
+            ['every asset up to 8 rolls', 'sk assets fill 8'],
+            ['only two categories', 'sk assets fill 8 icons sprites'],
         ],
     })
 
@@ -33,7 +37,7 @@ export class AssetsFillCommand extends Command {
             this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets fill <N> [category…]\n`)
             return 1
         }
-        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
+        return (await assets()).runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'fill', n, categories: this.categories })
     }
 }
 
@@ -43,7 +47,7 @@ export class AssetsAddCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'N more rolls per asset (canvas or comfy), regardless of what it has',
-        examples: [['3 fresh rolls everywhere', 'shipkit assets add 3']],
+        examples: [['3 fresh rolls everywhere', 'sk assets add 3']],
     })
 
     n = Option.String({ required: true })
@@ -55,7 +59,7 @@ export class AssetsAddCommand extends Command {
             this.context.stderr.write(`FAIL: '${this.n}' is not a positive roll count — usage: shipkit assets add <N> [category…]\n`)
             return 1
         }
-        return runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
+        return (await assets()).runAssetsTopUp(process.cwd(), ioOf(this), { mode: 'add', n, categories: this.categories })
     }
 }
 
@@ -66,8 +70,8 @@ export class AssetsGenCommand extends Command {
         category: 'Assets',
         description: 'one-shot rolls for a single asset (canvas or comfy)',
         examples: [
-            ['one roll', 'shipkit assets gen hero'],
-            ['five rolls', 'shipkit assets gen hero --n 5'],
+            ['one roll', 'sk assets gen hero'],
+            ['five rolls', 'sk assets gen hero --n 5'],
         ],
     })
 
@@ -76,7 +80,7 @@ export class AssetsGenCommand extends Command {
 
     async execute(): Promise<number> {
         const n = Math.max(1, Number(this.n) || 1)
-        return runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
+        return (await assets()).runAssetsGen(process.cwd(), ioOf(this), { assetId: this.assetId, n })
     }
 }
 
@@ -86,11 +90,11 @@ export class AssetsIdentityCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'render favicon/logo/OG from .shipkit/identity/brand.ts into public/',
-        examples: [['regenerate the identity outputs', 'shipkit assets identity']],
+        examples: [['regenerate the identity outputs', 'sk assets identity']],
     })
 
     async execute(): Promise<number> {
-        return runAssetsIdentity(process.cwd(), ioOf(this))
+        return (await assets()).runAssetsIdentity(process.cwd(), ioOf(this))
     }
 }
 
@@ -100,10 +104,10 @@ export class AssetsCheckCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'kit loads, kinds valid, cflow workflows load, drafts present, identity outputs present',
-        examples: [['health-check the asset pipeline', 'shipkit assets check']],
+        examples: [['health-check the asset pipeline', 'sk assets check']],
     })
 
     async execute(): Promise<number> {
-        return runAssetsCheck(process.cwd(), ioOf(this))
+        return (await assets()).runAssetsCheck(process.cwd(), ioOf(this))
     }
 }

package/src/cli/cmd_Bump.ts

@@ -9,18 +9,19 @@ export class BumpCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'ship a version in one word: bumps a unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
+        description: 'ship a version: merge, changelog, bump, gate, tag, push, release',
+        details: 'ship a version in one word: bumps a unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
         examples: [
-            ['a bugfix release of the repo itself', 'shipkit bump patch'],
-            ['a feature release', 'shipkit bump minor'],
-            ['a breaking release', 'shipkit bump major'],
-            ['one sub-unit (ids: shipkit releases)', 'shipkit bump minor rvlib-shipkit'],
-            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'shipkit bump --all'],
-            ['every unit carrying Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
-            ['one unit, kind from its own heading', 'shipkit bump rvlib-shipkit'],
-            ['rehearse the whole thing', 'shipkit bump minor --dry-run'],
-            ['bump and commit, release later', 'shipkit bump patch --no-release'],
-            ['from a feature branch, refuse rather than merge', 'shipkit bump patch --no-merge'],
+            ['a bugfix release of the repo itself', 'sk bump patch'],
+            ['a feature release', 'sk bump minor'],
+            ['a breaking release', 'sk bump major'],
+            ['one sub-unit (ids: shipkit releases)', 'sk bump minor rvlib-shipkit'],
+            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'sk bump --all'],
+            ['every unit carrying Unreleased notes, all at the same kind', 'sk bump patch --all'],
+            ['one unit, kind from its own heading', 'sk bump rvlib-shipkit'],
+            ['rehearse the whole thing', 'sk bump minor --dry-run'],
+            ['bump and commit, release later', 'sk bump patch --no-release'],
+            ['from a feature branch, refuse rather than merge', 'sk bump patch --no-merge'],
         ],
     })
 

package/src/cli/cmd_CacheAudit.ts

@@ -0,0 +1,43 @@
+// sk cache-audit — re-runs a sample of the checks the cache would answer right
+// now, fresh, and compares: a cached green a fresh run disagrees with is a
+// key that misses something its check reads (core/cache-audit.ts).
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { auditCache } from '../core/cache-audit.ts'
+
+export class CacheAuditCommand extends Command {
+    static override paths = [['cache-audit']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'is a cached green still true: re-run a sample of cached checks fresh and compare',
+        details: 'Picks checks the cache would answer right now (keyed on files or on reads), a different stable sample each day, runs each one fresh and compares its verdict with the cached one. A mismatch means the check key misses a path its body reads: the fresh answer replaces the stale one, and the line names the check. Exit 1 on a mismatch.',
+        examples: [
+            ['audit three cached checks', 'sk cache-audit'],
+            ['a bigger sample', 'sk cache-audit --sample 10'],
+            ['one check, by id', 'sk cache-audit --only SK004'],
+            ['machine-readable', 'sk cache-audit --json'],
+        ],
+    })
+
+    sample = Option.String('--sample', '3', { description: 'how many cached checks to re-run fresh (default 3)' })
+    only = Option.Array('--only', { description: 'audit these check ids instead of a sample' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { pool, rows, stale }' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const n = Number(this.sample)
+        if (!Number.isInteger(n) || n < 1) { this.context.stdout.write(`FAIL: --sample takes a whole number above 0, got '${this.sample}'\n`); return 1 }
+        const r = await auditCache(root, await loadRepoConfig(root), { sample: n, only: this.only })
+        if (this.json) { this.context.stdout.write(`${JSON.stringify(r)}\n`); return r.stale.length > 0 ? 1 : 0 }
+        if (r.rows.length === 0) { this.context.stdout.write(`skip: nothing to audit, the cache answers none of ${this.only?.join(', ') ?? 'the checks'} right now\n`); return 0 }
+        for (const row of r.rows) {
+            const same = row.fresh === row.cached || row.fresh === 'skip'
+            this.context.stdout.write(same
+                ? `ok: ${row.id} cached ${row.cached}, fresh ${row.fresh} (${row.ms}ms)\n`
+                : `FAIL: ${row.id} cached ${row.cached}, but a fresh run says ${row.fresh}: its key misses something it reads\n      fix: ${row.keyedOn === 'files' ? `add the path its body reads to its cache.inputs` : 'move the read through c, or declare cache files or never'}, then sk keys --why ${row.id}\n`)
+        }
+        this.context.stdout.write(r.stale.length === 0 ? `ok: ${r.rows.length} of ${r.pool} cached check(s) audited, every cached answer is what a fresh run says\n` : `FAIL: ${r.stale.length} of ${r.rows.length} audited check(s) served a stale answer\n`)
+        return r.stale.length > 0 ? 1 : 0
+    }
+}