rvlib-shipkit 1.4.0 → 1.5.0

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

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