rvlib-shipkit 1.4.0 → 1.6.0

package/src/checks/SK001-package-json-shape.check.ts

@@ -5,7 +5,7 @@
 // what it read: package.json, the probes below, the test file listing, and
 // whatever the floor resolution read.
 //
-// It also enforces the package.json half of ONE WAY IN (build/shipkit.md):
+// It also enforces the package.json half of ONE WAY IN (build/shipkit/one-way-in.md):
 // `test`, `lint` and `typecheck` ROUTE to `shipkit ci --only <id>` and the
 // tool body they used to hold sits at `<id>:raw`. That is what makes a cache
 // worth having: `bun run test` is the reflex, and the reflex has to land in
@@ -125,13 +125,14 @@ export function evaluatePackageJson(t: CheckCtx): void {
 //
 // a shipkit verb is never on this list. `shipkit ci`, `check`, `contracts`,
 // `tui`, `mv`, `assets`, `asks` are typed as themselves, and a package.json
-// row that only forwards to one is a second name for one capability
+// row that only forwards to one is a second name for one capability. nor is
+// a global process (ComfyUI, TTS): `shipkit gp start <id>` starts it from any
+// repo, so a per repo script would only copy it
 function requiredScripts(c: CheckCtx): Array<{ name: string; why: string }> {
     const required: Array<{ name: string; why: string }> = [
         // watch-mode serve — the ONE shipkit surface the bare verb cannot give
         { name: 'hub', why: 'shipkit repo' },
     ]
-    if (c.exists('.shipkit/comfy')) required.push({ name: 'comfy:up', why: '.shipkit/comfy/ exists' })
     if (c.exists('deploy.sh')) required.push({ name: 'up', why: 'deploy.sh exists' })
     return required
 }
@@ -197,12 +198,16 @@ export const packageJsonShape = check({
     title: 'package.json',
     description: 'package.json routes lint, typecheck and test through the gate',
     owner: OWNER,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => evaluatePackageJson(c),
     // mechanical repairs only: field flips + scripts whose canonical body the
-    // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
-    // named in the summary, never invented. rvlib-* roots untouched — their
+    // vocabulary page states. A body it does NOT state is named in the
+    // summary, never invented. rvlib-* roots untouched — their
     // license/private are publish decisions.
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const raw = c.read('package.json')
         if (raw == null) return { changed: false, summary: 'no package.json — nothing to fix' }
         if (rootPublishesNpm(c.config)) return { changed: false, summary: 'published to npm: its package.json is its public contract, never rewritten' }

package/src/checks/SK002-contracts-fulfillness.check.ts

@@ -16,6 +16,10 @@ export const contractsFulfillness = check({
     owner: 'meta/contracts.md',
     // keyed on what the contracts read: each artifact, each detector, and each
     // folder a glob walked through `c.entries`, a gitignored one included
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
     },

package/src/checks/SK003-claude-md-shape.check.ts

@@ -18,8 +18,12 @@ export const claudeMdShape = check({
     title: 'CLAUDE.md',
     description: 'CLAUDE.md loads the house wiki into every session',
     owner: 'meta/agent-folder.md',
-    // keyed on what it reads: CLAUDE.md and whether agent/index.md exists. The
-    // gitignore probe runs git, so an answer that took it is never stored
+    // keyed on what it reads: CLAUDE.md, whether agent/index.md exists, and
+    // the ignore files git read for the gitignore probe (c.exec runs traced)
+    runs: { onPreCommit: { budgetMs: 40 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         const hasAgent = c.exists('agent/index.md')
         const claude = c.read('CLAUDE.md')
@@ -53,7 +57,7 @@ export const claudeMdShape = check({
     // CLAUDE.md would lint green with the base include forever missing,
     // trading a loud FAIL for a permanent silent gap. Creation and prose
     // relocation stay human/machine-local (`shipkit start --include`).
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         if (!c.exists('agent/index.md')) return { changed: false, summary: 'no agent/index.md — nothing mechanical to fix' }
         const cur = c.read('CLAUDE.md')
         if (cur == null) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start <name> writes it), not autofixable' }

package/src/checks/SK004-gitignore-policy.check.ts

@@ -205,11 +205,14 @@ export const gitignorePolicy = check({
     title: '.gitignore',
     description: 'the managed .gitignore block keeps private contract folders out of git',
     owner: 'meta/contracts.md',
-    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
-    // carries and no read set records (the header says why)
-    inputs: ['.'],
     // it untracks generated files (a commit) unless the run is frozen
     writes: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
+    // carries and no read set records (the header says why)
+    cache: { by: 'files', inputs: ['.'], key: null },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         // a generated path still in the index is the half-applied state the
         // managed block cannot fix on its own
@@ -278,7 +281,7 @@ export const gitignorePolicy = check({
         }
         c.ok(`.gitignore policy block current, ${claimed.length + backProbes.size} patterns verified against git`)
     },
-    fix: async (c): Promise<FixResult> => {
+    repair: async (c): Promise<FixResult> => {
         // the move first: it writes the new block itself, before any folder moves
         const moved = process.env.SHIPKIT_FROZEN === '1' ? null : migrateLayout(c.root, { config: c.config, renderGitignore: (t, legacy, cfg) => renderPolicy(t, cfg ?? c.config, legacy) })
         const layout = moved == null ? null

package/src/checks/SK005-rvlib-versions.check.ts

@@ -10,7 +10,12 @@
 // Per rvlib-* dep:
 //   link:   → the symlink must resolve (a broken link dies cryptically at
 //             import time otherwise) — nothing to update, code is live
-//   semver  → installed vs npm latest; a BREAKING jump (a new major, or a
+//   semver  → installed vs npm latest. A semver pin whose node_modules
+//             entry is a `bun link` symlink is judged by the PIN's floor
+//             instead: the link carries the source, always the newest, while
+//             a fresh clone installs the pin. Behind, the pin moves through
+//             the same guarded update, and `bun link <name>` restores the
+//             link after it (a link that does not come back FAILs). A BREAKING jump (a new major, or a
 //             new 0.x minor) is never taken by itself
 //             (src/core/update-policy.ts: WARN naming `fleet --update --major`,
 //             package.json untouched); the rvlib-shipkit tree running this
@@ -46,7 +51,7 @@
 import { existsSync, readFileSync } from 'fs'
 import { basename, join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
-import { allowMajor, breakingAdvice, isBreaking } from '../core/update-policy.ts'
+import { allowMajor, breakingAdvice, isBreaking, isLinkedInstall, pinFloor } from '../core/update-policy.ts'
 import { isRunningCopy, rememberLatest } from '../core/self-update.ts'
 import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { mutateLease, withMutateLease } from '../core/locked-write.ts'
@@ -61,6 +66,13 @@ const installedVersion = (root: string, name: string): string | null => {
     try { return (JSON.parse(readFileSync(p, 'utf8')) as Pkg).version ?? null } catch { return null }
 }
 
+const readPin = (root: string, name: string): string | null => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as Pkg
+        return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? null
+    } catch { return null }
+}
+
 async function latestVersion(t: CheckCtx, name: string): Promise<string> {
     const res = await t.fetch(`https://registry.npmjs.org/${name}/latest`)
     if (!res.ok) throw new Error(`registry ${res.status}`)
@@ -74,23 +86,24 @@ export const rvlibVersions = check({
     blocking: true,
     title: 'rvlib versions',
     description: 'the rvlib packages installed here are as new as the published ones',
-    owner: 'build/shipkit.md',
-    ttl: '24h',
+    owner: 'build/shipkit/consuming.md',
     // it updates the rvlib deps unless the run is frozen
     writes: true,
-    planOff: (env) => {
-        let pkg: Pkg
-        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'no readable package.json' }
-        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).some((n) => n.startsWith('rvlib-')) ? null : 'no rvlib-* dependency'
-    },
-    cacheKey: (env) => {
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: false, onClock: { every: '24h', inactive: 'wait' } },
+    cache: { by: 'ttl', span: '24h', key: (env) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
         return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })
             .filter((n) => n.startsWith('rvlib-'))
             .sort()
-            .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
+            .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}${isLinkedInstall(env.root, n) ? ` pin ${readPin(env.root, n)}` : ''}`)
             .join(',') + (rootPublishesNpm(env.config) ? ' npm' : '')
+    } },
+    fix: 'none',
+    applies: (env) => {
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'no readable package.json' }
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).some((n) => n.startsWith('rvlib-')) ? null : 'no rvlib-* dependency'
     },
     run: async (c) => {
         let pkg: Pkg
@@ -100,39 +113,47 @@ export const rvlibVersions = check({
         const pm = detectPackageManager(c.root)
         const manifest = ['package.json', ...(isRefusal(pm) ? LOCK_FILES : pm.locks)]
 
-        const stale: Array<{ name: string; installed: string; latest: string }> = []
+        const stale: Array<{ name: string; installed: string; latest: string; linked: boolean }> = []
         for (const [name, spec] of deps) {
             if (spec.startsWith('link:')) {
                 if (installedVersion(c.root, name) == null) c.fail(`${name} is link: but the symlink does not resolve — re-run \`bun link ${name}\` (a broken link dies cryptically at import time)`)
                 else c.ok(`${name} (linked, live)`)
                 continue
             }
-            const installed = installedVersion(c.root, name)
-            if (installed == null) { c.fail(`${name} declared (${spec}) but not installed — ${isRefusal(pm) ? pm.refused : `run: ${pm.install.join(' ')}`}`); continue }
+            const onDisk = installedVersion(c.root, name)
+            if (onDisk == null) { c.fail(`${name} declared (${spec}) but not installed — ${isRefusal(pm) ? pm.refused : `run: ${pm.install.join(' ')}`}`); continue }
+            const linked = isLinkedInstall(c.root, name)
+            const floor = linked ? pinFloor(spec) : null
+            if (linked && floor == null) { c.ok(`${name} (linked to its source, pin ${spec} names no version to judge)`); continue }
+            const installed = floor ?? onDisk
+            // how the lines below name it: a linked dep is its pin, never the source it links
+            const label = linked ? `${name} pin ${installed}` : `${name} ${installed}`
             let latest: string
             try { latest = await latestVersion(c, name) } catch (e) {
-                c.lines.push({ kind: 'skip', text: `${name} ${installed} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
+                c.lines.push({ kind: 'skip', text: `${label} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
                 continue
             }
             // real semver order, not string difference — a dist-tag pointing
             // BEHIND the installed version (prerelease, unpublish window)
             // must never trigger a silent downgrade
             const cmp = Bun.semver.order(latest, installed)
-            if (cmp === 0) c.ok(`${name} ${installed} (latest)`)
-            else if (cmp < 0) c.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
+            if (cmp === 0) c.ok(`${label} (latest${linked ? ', linked to its source' : ''})`)
+            else if (cmp < 0) c.ok(`${label} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
             else if (isBreaking(installed, latest) && !allowMajor()) c.warn(breakingAdvice(name, latest, basename(c.root)))
-            else if (name === 'rvlib-shipkit' && isRunningCopy(c.root)) {
+            // a linked toolkit moves only its pin: the source tree this process
+            // runs from is never written, so the swap below cannot happen
+            else if (name === 'rvlib-shipkit' && !linked && isRunningCopy(c.root)) {
                 // swapping this tree under the running process is how a run
                 // meets modules of two versions. The startup self-update owns
                 // it: handing it the answer makes the next run update and
                 // restart before any check loads
                 rememberLatest(latest)
                 c.warn(`${name} ${installed} → ${latest} is the toolkit running this check, so it is not swapped mid run: the next shipkit run updates it and restarts before any check`)
-            } else stale.push({ name, installed, latest })
+            } else stale.push({ name, installed, latest, linked })
         }
         if (stale.length === 0) return
 
-        const drift = stale.map((s) => `${s.name} ${s.installed} → ${s.latest}`).join(', ')
+        const drift = stale.map((s) => `${s.name}${s.linked ? ' pin' : ''} ${s.installed} → ${s.latest}`).join(', ')
         const names = stale.map((s) => s.name)
         if (isRefusal(pm)) {
             c.warn(`newer rvlib live: ${drift}, not updating: ${pm.refused}`)
@@ -164,7 +185,11 @@ export const rvlibVersions = check({
         const leased = await withMutateLease(mutateLease(c.root, 'fix'), { label: 'self-update', print: () => {}, escape: 'SHIPKIT_FROZEN=1' }, async () => {
             const again = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
             if (again.code === 0 && again.out.trim() !== '') return null
-            return await c.exec(cmd, { cwd: c.root, timeoutMs: 120_000 })
+            const up = await c.exec(cmd, { cwd: c.root, timeoutMs: 120_000 })
+            // the update may swap a link for the tarball: put every link back,
+            // whatever the update did, inside the same lease
+            for (const s of stale) if (s.linked) await c.exec(['bun', 'link', s.name], { cwd: c.root, timeoutMs: 60_000 })
+            return up
         })
         if (!leased.ok) {
             c.warn(`newer rvlib live: ${drift} — self-update deferred (${leased.warn}); re-run check once that run finishes`)
@@ -188,6 +213,13 @@ export const rvlibVersions = check({
             return
         }
         for (const s of stale) {
+            if (s.linked) {
+                const now = pinFloor(readPin(c.root, s.name) ?? '')
+                if (!isLinkedInstall(c.root, s.name)) c.fail(`${s.name} pin ${s.installed} → ${now ?? 'unreadable'} but node_modules/${s.name} is no longer linked to its source — run: bun link ${s.name}`)
+                else if (now === s.latest) c.warn(`${s.name} pin ${s.installed} → ${now} self-updated, link to the source restored — commit the bump`)
+                else c.warn(`${s.name} updated but its pin reads ${now ?? 'unreadable'} (wanted ${s.latest}) — check package.json`)
+                continue
+            }
             const now = installedVersion(c.root, s.name)
             // WARN on purpose: the run MUTATED the repo and a follow-up
             // (restart watchers, commit) is owed — an ok here would be a

package/src/checks/SK006-npm-publish-safety.check.ts

@@ -40,6 +40,10 @@ export const npmPublishSafety = check({
     owner: 'meta/rv-conventions/package-json.md',
     // keyed on what it reads: the root package.json and every declared release
     // unit's, at the dirs the config picks
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const json = (rel: string): Pkg | null | 'unparseable' => {
             try { return c.json<Pkg>(rel) } catch { return 'unparseable' }

package/src/checks/SK007-github-visibility.check.ts

@@ -27,8 +27,10 @@ export const githubVisibility = check({
     title: 'github visibility',
     description: 'the github visibility of this repo matches the one it declares',
     owner: 'meta/contracts.md',
-    ttl: 'forever',
-    cacheKey: (env) => declaredVisibility(env.config),
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: 'once' },
+    cache: { by: 'fact', key: (env) => declaredVisibility(env.config) },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         const declared = declaredVisibility(c.config)
         const skip = (why: string): void => void c.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })

package/src/checks/SK008-reviewer-agent.check.ts

@@ -86,15 +86,17 @@ export const reviewerAgent = check({
     title: 'reviewer definition',
     description: 'the declared reviewer agent has its brief, its definition and read only tools',
     owner: 'identity/how-we-work.md',
+    runs: { onPreCommit: { budgetMs: 20 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the answer is the config, the definition file and the brief. The brief
     // is a CONFIG path that may sit outside the repo, so both files enter the
     // key by content, wherever they live
-    inputs: [CONFIG_FILE],
-    cacheKey: (env) => {
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: (env) => {
         const r = env.config.reviewer
         if (r == null) return 'no reviewer'
         return `${r.name}|${(r.tools ?? REVIEWER_TOOLS).join(',')}|def=${fileStamp(join(env.root, reviewerAgentPath(r.name)))}|${r.brief}=${fileStamp(configPath(env.root, r.brief))}`
-    },
+    } },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => {
         const r = c.config.reviewer
         if (r == null) return c.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
@@ -109,7 +111,7 @@ export const reviewerAgent = check({
     // create-if-missing only: an existing definition may carry a repo's own
     // tuned prompt, and silently rewriting that would cost more than the
     // finding it repairs. Violations in a present file stay a loud FAIL.
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const r = c.config.reviewer
         if (r == null) return { changed: false, summary: 'no reviewer declared — nothing to write' }
         const rel = reviewerAgentPath(r.name)

package/src/checks/SK009-commit-ai-tells.check.ts

@@ -81,9 +81,11 @@ export const commitAiTells = check({
     title: 'commit ai tells',
     description: 'the commit-msg hook that refuses AI attribution is armed, and no ref name tells',
     owner: 'identity/how-we-commit.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // git config and ref names, which no tree id describes, so they are the key
-    inputs: [CONFIG_FILE],
-    cacheKey: historyKey,
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: historyKey },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         const nested = nestedIn(c.root)
         if (nested != null) return void c.lines.push({ kind: 'skip', text: `commit gates not checked, nested in ${nested}: the parent repo owns them` })

package/src/checks/SK010-undeclared-unit.check.ts

@@ -40,6 +40,10 @@ export const undeclaredUnit = check({
     owner: 'build/shipkit/units.md',
     // keyed on what it reads: the listing of every package.json, each one it
     // opens, and the declared units' package.json
+    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 { units, errors, testOnly } = resolveUnits(c.root, c.config, checkUnitReader(c))
         // a DECLARED unit that does not resolve is a declaration bug and

package/src/checks/SK011-sibling-unit-ranges.check.ts

@@ -61,6 +61,10 @@ export const siblingUnitRanges = check({
     owner: 'build/shipkit/built-in-checks.md',
     // keyed on what it reads: every declared unit's package.json, at the dirs
     // the config picks
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const { units } = resolveUnits(c.root, c.config, checkUnitReader(c))
         const version = new Map(units.map((u) => [u.name, u.version]))

package/src/checks/SK012-config-barrel-import.check.ts

@@ -30,6 +30,10 @@ export const configBarrelImport = check({
     title: 'config import path',
     description: 'repo.config.ts imports `defineRepo` from the narrow module, never the barrel',
     owner: 'build/shipkit/config-keys.md',
+    runs: { onPreCommit: { budgetMs: 20 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => {
         const src = c.read(CONFIG)
         if (src == null) return void c.ok(`${CONFIG} absent — nothing to narrow`)
@@ -43,7 +47,7 @@ export const configBarrelImport = check({
         }
         c.fail(`${CONFIG} imports from the package barrel (~400ms of module load on every shipkit run, the pre-commit hook included)`)
     },
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const src = c.read(CONFIG)
         if (src == null) return { changed: false, summary: `${CONFIG} absent` }
         if (!BARREL.test(src)) return { changed: false, summary: 'already narrow' }

package/src/checks/SK013-one-way-in-policy.check.ts

@@ -1,4 +1,4 @@
-// SK013 — the harness half of ONE WAY IN (build/shipkit.md). Rule SK001 routes
+// SK013 — the harness half of ONE WAY IN (build/shipkit/one-way-in.md). Rule SK001 routes
 // the package.json scripts, and that alone is not enough: `bun test` is a bun
 // BUILTIN, so no script can intercept it and the reflex stays open. This rule
 // makes the repo carry the two things that CAN close it, and repairs them:
@@ -19,7 +19,7 @@ import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type CheckCtx, type FixResult } from '../check.ts'
 
-const OWNER = 'build/shipkit.md'
+const OWNER = 'build/shipkit/one-way-in.md'
 export const SETTINGS_PATH = '.claude/settings.json'
 
 type Settings = {
@@ -124,6 +124,10 @@ export const oneWayInPolicy = check({
     // keyed on what it reads: .claude/settings.json, package.json, and whether
     // the declared guard script resolves. A guard at an absolute path lives
     // outside the repo, so an answer that probed one is never stored
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const d = c
@@ -171,7 +175,7 @@ export const oneWayInPolicy = check({
     // MERGES, never rewrites: this file also carries the attribution silencer,
     // a repo's own allow list and its own hooks, and clobbering those to fix a
     // deny list would cost more than the finding it repairs
-    fix: async (c): Promise<FixResult> => {
+    repair: async (c): Promise<FixResult> => {
         if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const d = c
         const want = denyRules(exemptSlots(c.config))

package/src/checks/SK014-prose-ste.check.ts

@@ -30,6 +30,10 @@ export const proseSte = check({
     owner: OWNER,
     // keyed on what it reads: each include glob's listing and every file in
     // scope, so an edit outside the declared prose never reruns it
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const cfg = c.config.prose
         if (cfg == null || (cfg.include ?? []).length === 0) {

package/src/checks/SK015-nested-repo.check.ts

@@ -12,10 +12,12 @@ export const nestedRepo = check({
     title: 'nested repo',
     description: 'a config inside a larger work tree declares `nested: true`, and only there',
     owner: 'build/shipkit/config-keys.md',
+    runs: { onPreCommit: { budgetMs: 20 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the declaration, and where the git work tree root sits, which no tree
     // id describes, so its path is the rest of the key
-    inputs: [CONFIG_FILE],
-    cacheKey: (env) => `nested=${env.config.nested === true}|top=${nestedIn(env.root) ?? 'root'}`,
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: (env) => `nested=${env.config.nested === true}|top=${nestedIn(env.root) ?? 'root'}` },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const top = nestedIn(c.root)
         const declared = c.config.nested === true

package/src/checks/SK016-legacy-check-shapes.check.ts

@@ -49,6 +49,10 @@ export const legacyCheckShapes = check({
     blocking: true,
     // keyed on what it reads: the listing of check files, their sources, and
     // the config. A gitignored check file is no declaration of this repo
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'manual',
+    applies: 'always',
     run: (c) => {
         const s = legacyShapes(c, c.config)
         if (s.count === 0 && s.placeholders.length === 0) {
@@ -70,7 +74,7 @@ export const legacyCheckShapes = check({
             const head = s.checkFiles.slice(0, 3).map((f) => f.rel).join(', ')
             c.warn(`${s.checkFiles.length} legacy check script(s) read by the static reader: ${head}${s.checkFiles.length > 3 ? `, and ${s.checkFiles.length - 3} more` : ''}`)
             const off = s.checkFiles.filter((f) => !f.read.gate).length
-            if (off > 0) c.warn(`${off} of them carry \`export const gate = false\`, which is \`when: 'health'\``)
+            if (off > 0) c.warn(`${off} of them carry \`export const gate = false\`, which is every gate axis false and onHealth true`)
         }
         if (s.checkDefaults) c.warn(`repo.config.ts checkDefaults lets a file forget \`blocking\` — the value belongs in each file`)
         if (s.tasks.length > 0) {
@@ -78,10 +82,10 @@ export const legacyCheckShapes = check({
             c.warn(`${s.tasks.length} \`tasks: []\` entr(ies), ${data} of them pure data — each one is a *.check.ts file with \`build: true\``)
         }
         if (s.rules.length > 0) c.warn(`${s.rules.length} \`rules: []\` entr(ies): ${s.rules.join(', ')} — each one is a *.check.ts file whose \`run\` is its \`lint\``)
-        if (s.ruleExempt.length > 0) c.warn(`ruleExempt names ${s.ruleExempt.join(', ')} — the spelling is \`when: { id: 'off:<why>' }\``)
+        if (s.ruleExempt.length > 0) c.warn(`ruleExempt names ${s.ruleExempt.join(', ')} — the spelling is \`off: { id: '<why>' }\`, and \`shipkit ci\` ports it (SK029)`)
         // what the fixer rewrites without guessing: the exemptions, the tasks
         // once all of them are data, checkDefaults once no script leans on it
-        const mechanical = s.ruleExempt.length + (s.tasks.every((x) => x.data) ? s.tasks.length : 0) + (s.checkDefaults && s.checkFiles.length === 0 ? 1 : 0)
+        const mechanical = (s.tasks.every((x) => x.data) ? s.tasks.length : 0) + (s.checkDefaults && s.checkFiles.length === 0 ? 1 : 0)
         c.warn(
             `${s.count} declaration(s) in a shape the check file replaced: still read, and refused by the first shipkit release after \`shipkit fleet\` shows no repo below 0.40 and none still carrying a check script`,
             mechanical > 0
@@ -89,7 +93,7 @@ export const legacyCheckShapes = check({
                 : `nothing left is mechanical, so the port is by hand: each line above becomes a *.check.ts file (${OWNER})`,
         )
     },
-    fix: async (c) => await fixLegacyShapes(c),
+    repair: async (c) => await fixLegacyShapes(c),
 })
 
 export default legacyCheckShapes
@@ -162,17 +166,14 @@ export async function fixLegacyShapes(c: CheckCtx, rewrite: ConfigRewriter = inO
     for (const r of config.rules ?? [])
         hand.push(`rule ${r.id}: move it into ${checkFileName(r.id)} beside repo.config.ts, \`lint\` becomes \`run\` and \`code\` goes (the file's own path is its closure)`)
 
-    // 4. the exemptions that were their own key, as `when` entries (the
-    //    managed block is the one writer), then 5. the config keys, last: a
-    //    key is only dropped once every declaration that leaned on it has a
-    //    home. Both load the config, so they run in their own process
-    const cfgPlan: ConfigPlan = { when: {}, drop: [], name: config.name }
-    for (const [id, why] of Object.entries(config.ruleExempt ?? {})) cfgPlan.when[id] = `off:${why}`
+    // 4. the config keys, last: a key is only dropped once every declaration
+    //    that leaned on it has a home. It loads the config, so it runs in its
+    //    own process. `ruleExempt` is SK029's: it ports it into `off`
+    const cfgPlan: ConfigPlan = { off: {}, drop: [], name: config.name }
     if (s.checkDefaults && filesLeft === 0) cfgPlan.drop.push({ key: 'checkDefaults', why: 'every file now declares its own blocking' })
     else if (s.checkDefaults) hand.push(`repo.config.ts \`checkDefaults\` stays until the ${filesLeft} file(s) above declare their own \`blocking\``)
     if (tasksMove) cfgPlan.drop.push({ key: 'tasks', why: 'every task is a check file now' })
-    if (s.ruleExempt.length > 0) cfgPlan.drop.push({ key: 'ruleExempt', why: 'the exemptions are `when` entries now', afterWhen: true })
-    if (Object.keys(cfgPlan.when).length > 0 || cfgPlan.drop.length > 0) {
+    if (cfgPlan.drop.length > 0) {
         const out = await rewrite(cfgPlan)
         did.push(...out.did)
         hand.push(...out.hand)

package/src/checks/SK017-vscode-hub-task.check.ts

@@ -12,7 +12,7 @@ import { check } from '../check.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
 import { rootPublishesNpm } from '../core/repo-facts.ts'
-import { whenOfTask } from '../core/when.ts'
+import { repoOff } from '../core/when.ts'
 import { hubProblemMatcher } from '../problems/problem-line.ts'
 import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
 
@@ -24,12 +24,15 @@ type Arr = Extract<Node, { kind: 'array' }>
 
 const prop = (o: Obj, key: string): Node | undefined => o.props.find((p) => p.key === key)?.value
 
+/** the type checker binaries: tsc, and tsgo, its native port */
+const TSC_BINS = new Set(['tsc', 'tsgo'])
+
 /** the house type checker task and nothing that only looks like it: the exact
- *  label, a tsc binary, in watch mode */
+ *  label, a tsc or tsgo binary, in watch mode */
 function isTscWatcher(t: Record<string, unknown>): boolean {
     const cmd = typeof t['command'] === 'string' ? t['command'] : ''
     const args = Array.isArray(t['args']) ? t['args'] : []
-    return t['label'] === TSC_LABEL && basename(cmd) === 'tsc' && args.includes('--watch')
+    return t['label'] === TSC_LABEL && TSC_BINS.has(basename(cmd)) && args.includes('--watch')
 }
 
 /** the hub task: `bun run hub`, or the house label */
@@ -90,9 +93,17 @@ export function repairTasks(text: string, o: RepairOpts): { text: string; change
         if (/\/\/.*(master task|subtask)/i.test(text)) changes.push('a comment still describes a master task with subtasks: rewrite it by hand')
     }
 
+    // a wrapper that started only the TSC task starts nothing once it goes
+    const emptied = !dropTsc ? [] : tasks.items.flatMap((n, i) => (n !== wrapper && n.kind === 'object' && isWrapper(record(n)) && depsOf(n).length === 0 ? [i] : []))
+    for (const i of emptied) {
+        const [start, end] = removalSpan(text, tasks, i)
+        edits.push({ start, end, body: '' })
+        changes.push(`removed the '${labelOf(tasks.items[i]!)}' wrapper, which started nothing else`)
+    }
+
     if (dropTsc) {
         for (const t of items) {
-            if (t === wrapper) continue
+            if (t === wrapper || emptied.some((i) => tasks.items[i] === t)) continue
             const d = prop(t, 'dependsOn')
             if (d?.kind === 'array') {
                 const idx = d.items.findIndex((x) => x.kind === 'scalar' && x.value === TSC_LABEL)
@@ -148,13 +159,13 @@ export function repairTasks(text: string, o: RepairOpts): { text: string; change
 }
 
 /** whether this repo's gate runs a typecheck: a floor slot or a task that
- *  resolves, and no `when` turning it off */
+ *  resolves, and no `off` entry turning it off */
 export function typecheckOn(c: CheckCtx): boolean {
     const config = c.config
     let floor: ReturnType<typeof resolveFloor>
     try { floor = resolveFloor(config, c.root, checkFloorReader(c)) } catch { return false }
     const t = [...floor.tasks, ...(config.tasks ?? [])].find((x) => x.id === 'typecheck')
-    return t != null && whenOfTask(config, t).at !== 'off'
+    return t != null && repoOff(config, t.id) == null
 }
 
 /** the tasks file this check may touch: none, or left alone because .vscode/
@@ -178,6 +189,10 @@ export const vscodeHubTask = check({
     title: 'vscode hub task',
     description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
     owner: 'build/vscode-tasks.md',
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'manual',
+    applies: 'always',
     run: (c) => {
         if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const own = ownTasks(c)
@@ -190,7 +205,7 @@ export const vscodeHubTask = check({
         if (r.changes.length === 0) return c.ok(`${TASKS}: the hub task feeds the problems pane`)
         for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
     },
-    fix: (c) => {
+    repair: (c) => {
         if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const own = ownTasks(c)
         if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }

package/src/checks/SK018-test-files-run.check.ts

@@ -1,4 +1,4 @@
-// SK018 — every test file runs in a check (build/shipkit.md, the test checks).
+// SK018 — every test file runs in a check (build/shipkit/test-runner.md).
 // A `*.test.ts` that no check runs is a green nobody measured: the file says
 // something is proved, and nothing proves it. Each file belongs to the release
 // unit whose dir holds it (the root takes the rest), and the unit's own
@@ -12,7 +12,11 @@ export const testFilesRun = check({
     blocking: true,
     title: 'test files run',
     description: 'every test file in the repo runs in a test check or is ignored on purpose',
-    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) => {
         const files = c.list(TEST_GLOB).filter(isTestFile)
         if (files.length === 0) return c.ok('no test file in this repo')