rvlib-shipkit 1.3.0 → 1.5.0

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

@@ -1,23 +1,22 @@
-// SK009 — commit AI tells (identity/how-we-commit.md): a repo that will be
-// seen must not read as AI-driven. Prevention lives at the source (the
-// attribution setting + the standing from-commit-one ban, which binds every
-// repo because history follows a repo public and is never rewritten); this
-// rule is the declared-public tripwire: the FULL git log scanned for AI
-// attribution and dash punctuation, plus the tracked settings file that
-// silences attribution. Declared-private repos idle with an ok that RESTATES
-// the ban — a green line must never teach the wrong rule. The remedy for
-// pushed history is the owner's decision, never an automatic rewrite; only
-// an unpushed tip commit may be amended, and the fails say so.
+// SK009 commit AI tells (identity/how-we-commit.md): the commit-msg hook is
+// what refuses AI attribution, in every repo, so this check verifies the hook
+// is ARMED: shipkit's own hooksPath, or a foreign one whose commit-msg chains
+// the shipkit gate. It never scans history: what is pushed is accepted as it
+// is, and only a new commit can still be stopped. A declared-public repo also
+// needs the tracked attribution silencer, and its ref NAMES are checked (a
+// FABLE-checkpoint tag outs the agent like a trailer); a branch nobody pushed
+// is named "local only" and warns.
 import { createHash } from 'crypto'
 import { readFileSync } from 'fs'
-import { join } from 'path'
-import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
+import { isAbsolute, join } from 'path'
 import { nestedIn } from '../core/nesting.ts'
 import { gitBin } from '../core/git-bin.ts'
 import { fileStamp } from '../core/file-stamp.ts'
 import { CONFIG_FILE } from '../core/check-pass.ts'
+import { LAYOUT } from '../core/layout.ts'
 import { check, type CheckEnv } from '../check.ts'
 import { declaredVisibility } from '../core/repo-facts.ts'
+import { hookBinInvocation } from '../hooks/run-hooks.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
 // empty — the harness then never writes the trailer or the PR footer
@@ -30,81 +29,102 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
-/** what the answer depends on: the declared visibility, and for a public
- *  repo the commit HEAD names, every ref name and the silencer. So a commit,
- *  a fetch or a new tag asks again, and nothing else does */
+const readOrNull = (abs: string): string | null => {
+    try {
+        return readFileSync(abs, 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** a commit-msg body that runs the shipkit gate on the message: a live line
+ *  (never a comment) whose failure is not swallowed by `|| true` */
+const chainsShipkit = (body: string): boolean =>
+    body.split('\n').some((l) => !l.trim().startsWith('#') && /\bhooks\s+commit-msg\b/.test(l) && !/\|\|\s*(?:true|:)\b/.test(l))
+
+/** the chain line to paste into a foreign hook: a clone with no install skips
+ *  the gate with a note, rather than failing every commit */
+export const guardedChain = (bin: string): string => {
+    const cli = bin.replace(/^bun\s+/, '')
+    return `if [ -f ${cli} ]; then ${bin} hooks commit-msg "$1" || exit 1; else echo "commit-msg: rvlib-shipkit not installed (run bun install), attribution gate skipped" >&2; fi`
+}
+
+// ref NAMES tell too. bare match only for names with no other meaning;
+// vendor and codename words (cursor, openai, gemini, opus, fable, …) name
+// legitimate branches and features, they only match in a checkpoint/session shape
+const REF_TELL = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
+
+const gitOut = (root: string, args: string[]): { code: number; out: string } => {
+    const p = Bun.spawnSync([gitBin(), ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    return { code: p.exitCode, out: p.stdout.toString() }
+}
+
+/** what the answer depends on: the declared visibility, the hooksPath and the
+ *  commit-msg file it points at, and for a public repo every ref NAME and the
+ *  silencer. A commit moves none of them */
 export function historyKey(env: CheckEnv): string {
-    const declared = declaredVisibility(env.config)
     const nested = nestedIn(env.root)
     if (nested != null) return `nested in ${nested}`
-    if (declared !== 'public') return `declared ${declared}`
-    const git = (args: string[]): string => {
-        const p = Bun.spawnSync([gitBin(), ...args], { cwd: env.root, stdout: 'pipe', stderr: 'pipe' })
-        return p.exitCode === 0 ? p.stdout.toString() : `exit ${p.exitCode}`
-    }
-    const refs = git(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/tags', 'refs/heads', 'refs/remotes'])
-    const head = git(['rev-parse', 'HEAD'])
-    const digest = createHash('sha256').update(head).update('\0').update(refs).digest('hex').slice(0, 16)
-    return `public|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
+    const declared = declaredVisibility(env.config)
+    const hooksPath = gitOut(env.root, ['config', 'core.hooksPath'])
+    const dir = hooksPath.code === 0 ? hooksPath.out.trim() : ''
+    const hook = `hooks=${dir}|msg=${dir === '' ? 'none' : fileStamp(isAbsolute(dir) ? join(dir, 'commit-msg') : join(env.root, dir, 'commit-msg'))}`
+    if (declared !== 'public') return `declared ${declared}|${hook}`
+    const refs = gitOut(env.root, ['for-each-ref', '--format=%(refname)', 'refs/tags', 'refs/heads', 'refs/remotes']).out
+    const digest = createHash('sha256').update(refs).digest('hex').slice(0, 16)
+    return `public|${hook}|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
 }
 
 export const commitAiTells = check({
     id: 'SK009',
     blocking: true,
     title: 'commit ai tells',
-    description: 'the history of a public repo carries no AI attribution and no dash punctuation',
+    description: 'the commit-msg hook that refuses AI attribution is armed, and no ref name tells',
     owner: 'identity/how-we-commit.md',
-    // it scans the full `git log` and every ref name, which no tree id
-    // describes, so the refs themselves are the key
-    inputs: [CONFIG_FILE],
-    cacheKey: historyKey,
+    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
+    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 history not scanned, nested in ${nested}: that history belongs to the parent repo` })
-        const declared = declaredVisibility(c.config)
-        if (declared !== 'public')
-            return c.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
-        // %x1f separates hash from body, %x1e terminates the record — commit
-        // bodies are free text, so only unprintable separators are safe
-        const log = await c.exec(['git', 'log', '--format=%h%x1f%B%x1e'], { cwd: c.root, timeoutMs: 30_000 })
-        if (log.code !== 0) {
-            const first = log.out.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? `exit ${log.code}`
-            return void c.lines.push({ kind: 'skip', text: `commit history unverifiable — git says: ${first}` })
+        if (nested != null) return void c.lines.push({ kind: 'skip', text: `commit gates not checked, nested in ${nested}: the parent repo owns them` })
+        const top = await c.exec(['git', 'rev-parse', '--show-toplevel'], { cwd: c.root })
+        if (top.code !== 0) return void c.lines.push({ kind: 'skip', text: 'not a git repo: no commit to guard yet' })
+
+        const hp = await c.exec(['git', 'config', 'core.hooksPath'], { cwd: c.root })
+        const dir = hp.code === 0 ? hp.out.trim() : ''
+        const chain = guardedChain(hookBinInvocation(c.root))
+        if (dir === '' && process.env['CI'] != null && process.env['CI'] !== '') {
+            c.lines.push({ kind: 'skip', text: 'commit-msg hook not armed in this CI checkout: a CI run makes no commit, and the fix pass arms hooks on a machine only' })
+        } else if (dir === '') {
+            c.fail('the commit-msg hook is not armed, so nothing refuses an AI attribution trailer: run `shipkit hooks install` (`shipkit ci` arms it too)')
+        } else {
+            const body = isAbsolute(dir) ? readOrNull(join(dir, 'commit-msg')) : c.read(`${dir}/commit-msg`)
+            const own = dir === LAYOUT.hooks
+            if (body == null)
+                c.fail(`core.hooksPath=${dir} has no ${dir}/commit-msg, so nothing refuses an AI attribution trailer: ${own ? 'run `shipkit hooks install`' : `add one that runs \`${chain}\``}`)
+            else if (!chainsShipkit(body))
+                c.fail(`core.hooksPath=${dir}: its commit-msg (${body.split('\n').find((l) => l.trim() !== '' && !l.startsWith('#'))?.trim().slice(0, 80) ?? 'empty'}) does not run the shipkit gate, so nothing refuses AI attribution: add \`${chain}\` above its last line`)
+            else c.ok(`the commit-msg hook refuses AI attribution (${own ? dir : `${dir}, chained to the shipkit gate`})`)
         }
-        const commits = log.out
-            .split('\x1e')
-            .map((r) => r.trim())
-            .filter((r) => r !== '')
-            .map((r) => {
-                const cut = r.indexOf('\x1f')
-                return { hash: r.slice(0, cut), body: r.slice(cut + 1) }
-            })
-        if (commits.length === 0) return void c.lines.push({ kind: 'skip', text: 'commit history unverifiable — no commits yet' })
-        const remedy = 'an unpushed TIP commit may be amended; anything deeper is the owner\'s decision (history is never rewritten as a side effect)'
-        const sample = (hits: { hash: string }[]): string => hits.slice(0, 5).map((h) => h.hash).join(' ') + (hits.length > 5 ? ' …' : '')
-        const attributed = commits.filter((m) => hasAiAttribution(m.body))
-        const dashed = commits.filter((m) => hasDashPunctuation(m.body))
-        // ref NAMES tell too (a FABLE-checkpoint-3 tag outs the agent as
-        // loudly as a trailer). bare match only for names with no other
-        // meaning; vendor and codename words (cursor, openai, gemini, opus,
-        // fable, …) name legitimate branches and features, they only match in
-        // a checkpoint/session shape
-        const refTell = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
-        const refs = await c.exec(['git', 'for-each-ref', '--format=%(refname:short)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: c.root, timeoutMs: 30_000 })
-        if (refs.code !== 0) c.lines.push({ kind: 'skip', text: `ref names unverifiable — git for-each-ref exit ${refs.code}` })
-        const tellRefs = refs.code === 0 ? refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '' && refTell.test(r)) : []
-        if (tellRefs.length > 0)
-            c.fail(`${tellRefs.length} ref name(s) carry an AI tell in a declared-public repo (${tellRefs.slice(0, 5).join(' ')}${tellRefs.length > 5 ? ' …' : ''}) — rename or delete the refs before the flip; a pushed tag also needs the remote delete`)
-        if (attributed.length > 0)
-            c.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / a session trailer or claude.ai url / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
-        if (dashed.length > 0)
-            c.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
-        const silenced = attributionSilenced(c.root)
-        if (!silenced)
-            c.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
-        if (attributed.length === 0 && dashed.length === 0 && tellRefs.length === 0 && silenced)
-            c.ok(`${commits.length} commits + ${refs.code === 0 ? refs.out.split('\n').filter((r) => r.trim() !== '').length : 0} ref names scanned, attribution silenced in .claude/settings.json — no AI tells`)
+
+        if (declaredVisibility(c.config) !== 'public') return
+        if (!attributionSilenced(c.root))
+            c.fail(`.claude/settings.json does not silence AI attribution: track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
+        const refs = await c.exec(['git', 'for-each-ref', '--format=%(refname)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: c.root, timeoutMs: 30_000 })
+        if (refs.code !== 0) return void c.lines.push({ kind: 'skip', text: `ref names unverifiable: git for-each-ref exit ${refs.code}` })
+        const all = refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '')
+        const remote = new Set(all.filter((r) => r.startsWith('refs/remotes/')).map((r) => r.split('/').slice(3).join('/')))
+        const tells = all.filter((r) => REF_TELL.test(r.replace(/^refs\/(?:heads|tags|remotes)\//, '')))
+        const shown = (r: string): string => r.replace(/^refs\/(?:heads|tags|remotes)\//, '')
+        const local = tells.filter((r) => r.startsWith('refs/heads/') && !remote.has(shown(r)))
+        const out = tells.filter((r) => !local.includes(r) && !(r.startsWith('refs/heads/') && remote.has(shown(r))))
+        const list = (rs: string[], suffix = ''): string => rs.slice(0, 5).map((r) => `${shown(r)}${suffix}`).join(' ') + (rs.length > 5 ? ' …' : '')
+        if (out.length > 0)
+            c.fail(`${out.length} ref name(s) carry an AI tell in a declared-public repo (${list(out)}): rename or delete them, a pushed one on the remote too, then \`git fetch --prune\` so a remote ref deleted there leaves this clone`)
+        if (local.length > 0)
+            c.warn(`${local.length} branch name(s) carry an AI tell (${list(local, ' (local only)')}): never push them under this name, rename or delete 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

@@ -7,16 +7,17 @@
 //
 // The tier split is the whole design. `fix` and `hard` hits BLOCK: they are
 // mechanical, and a machine reporting them is never guessing. `soft` hits
-// (sentence length, passive voice) need a human read, so they WARN, and only
-// a declared `baseline` makes them blocking, as a ratchet that can only go
-// down.
+// (sentence length, passive voice, modals, semicolons, …) need a human read,
+// so they are a note, never an attention item, and only a declared
+// `baseline` makes them blocking, as a ratchet that can only go down.
 //
 // It carries NO `fix()` on purpose. `shipkit ci` runs `--fix-rules` by
 // default, so a rule with a fixer rewrites tracked files unattended, and
 // prose is not repo shape: a wrong package.json line is a config, a wrong
 // sentence is content. The rewrite lives behind an explicit `shipkit prose
 // --fix` that a human ran and can read the diff of.
-import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
+import { classSummary, proseLines, runProseCheck, type ProseReport } from '../prose/run-prose.ts'
+import { tierOf, type ProseClass } from '../prose/ste.ts'
 import { check } from '../check.ts'
 
 const OWNER = 'identity/writing-voice.md'
@@ -29,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) {
@@ -53,12 +58,21 @@ export const proseSte = check({
                 `${blocking} STE violation(s) across ${r.byFile.length}/${r.files} file(s) — ${classSummary(r)}`,
                 r.fixable > 0 ? `shipkit prose --fix rewrites ${r.fixable} of them` : undefined,
             )
+        const soft = softSummary(r)
         if (cfg.baseline != null && r.byTier.soft > cfg.baseline)
-            c.fail(`${r.byTier.soft} soft hits (sentence length, passive voice), above the declared baseline of ${cfg.baseline} — the ratchet only goes down`)
+            c.fail(`${r.byTier.soft} soft hits (${soft}), above the declared baseline of ${cfg.baseline}: the ratchet only goes down`)
         else if (r.byTier.soft > 0)
-            c.warn(`${r.byTier.soft} soft hit(s): sentence length and passive voice need a human read${cfg.baseline != null ? ` (baseline ${cfg.baseline})` : ''}`)
+            c.note(`${r.byTier.soft} soft hit(s) need a human read (${soft})${cfg.baseline != null ? `, within the baseline of ${cfg.baseline}` : ''}: \`shipkit prose\` lists them`)
         if (!c.failed && blocking === 0) c.ok(`${r.files} file(s) STE-clean on the mechanical rules`)
     }
 })
 
+/** every soft class with its count, most first */
+const softSummary = (r: ProseReport): string =>
+    Object.entries(r.byClass)
+        .filter(([cls]) => tierOf(cls as ProseClass) === 'soft')
+        .sort((a, b) => b[1] - a[1])
+        .map(([cls, n]) => `${cls} ${n}`)
+        .join(', ')
+
 export default proseSte

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

@@ -1,8 +1,9 @@
 // SK016 — the shapes the check file replaced, and the machine that
 // rewrites them (build/shipkit/writing-a-check.md owns the shape itself).
 //
-// The window: every shape below is READ through 0.40, named once per run, and
-// refused at the first release after `shipkit fleet` shows no repo below 0.40.
+// The window: every shape below is still READ, named once per run, and
+// refused at the first release after `shipkit fleet` shows no repo below 0.40
+// and none still carrying a check script.
 // So a repo on an old declaration keeps working, learns what to write instead
 // on every gate, and is carried across by one command, save what only a
 // reader can port: a check script's body, a rule, a task whose body is code.
@@ -48,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) {
@@ -60,7 +65,7 @@ export const legacyCheckShapes = check({
         if (s.placeholders.length > 0)
             c.warn(
                 `${s.placeholders.length} check file(s) still open with the TODO description the migration wrote: ${s.placeholders.join(', ')}`,
-                'replace each TODO with one line stating what must be true',
+                'by hand: replace each TODO with one line stating what must be true',
             )
         if (s.count === 0) return
         // one WARN per shape, never a bare line: the gate promises every line
@@ -69,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) {
@@ -77,13 +82,18 @@ 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.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 — read through 0.40, refused after`,
-            'shipkit check --fix SK016 rewrites what is mechanical and names the rest',
+            `${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
+                ? `shipkit check --fix SK016 rewrites ${mechanical} of them and names the rest`
+                : `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
@@ -156,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 []