rvlib-shipkit 0.38.1 → 1.0.1

package/src/{rules/SK013-one-way-in-policy.ts → checks/SK013-one-way-in-policy.check.ts}

@@ -12,13 +12,11 @@
 // Both are generated from ONE table (core/one-way-in-policy.ts). The file is
 // TRACKED on purpose: `.claude/settings.local.json` is gitignored by the house
 // scaffold, so a policy written there would bind exactly one checkout.
-import { existsSync, mkdirSync, readFileSync } from 'fs'
-import { dirname, isAbsolute, join } from 'path'
+import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
 import type { RepoConfig } from '../repo-config.ts'
-import type { FixResult, Rule, RuleEnv } from './rule.ts'
-import { atomicWrite } from '../core/locked-write.ts'
+import { check, type CheckCtx, type FixResult } from '../check.ts'
 
 const OWNER = 'build/shipkit.md'
 export const SETTINGS_PATH = '.claude/settings.json'
@@ -46,12 +44,23 @@ export function guardCommand(bin?: string): string {
     return isAbsolute(path) ? `bun "${path}"` : `bun "$CLAUDE_PROJECT_DIR/${path}"`
 }
 
-const readPkg = (root: string): { scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null => {
-    try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as never } catch { return null }
+/** the helpers below see the repo through the check context. A guard at an
+ *  absolute path lives outside the repo, so probing it goes through `c.exec`,
+ *  which keeps that answer out of the cache */
+type Disk = Pick<CheckCtx, 'read' | 'exists' | 'exec'>
+
+const existsOutside = async (d: Disk, abs: string): Promise<boolean> => (await d.exec(['test', '-e', abs])).code === 0
+
+const parsed = <T>(text: string | null): T | null => {
+    if (text == null) return null
+    try { return JSON.parse(text) as T } catch { return null }
 }
 
-const declaresShipkit = (root: string): boolean => {
-    const pkg = readPkg(root)
+type Pkg = { scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+const readPkg = (d: Disk): Pkg | null => parsed<Pkg>(d.read('package.json'))
+
+const declaresShipkit = (d: Disk): boolean => {
+    const pkg = readPkg(d)
     return pkg?.dependencies?.['rvlib-shipkit'] != null || pkg?.devDependencies?.['rvlib-shipkit'] != null
 }
 
@@ -59,13 +68,9 @@ const declaresShipkit = (root: string): boolean => {
  *  declares rvlib-shipkit, says the dependency is not installed, which
  *  `bun install` fixes and no edit to this repo can. Without the declaration
  *  no install ever brings it, so it is a path this repo got wrong like any other. */
-const isUninstalledDep = (root: string, rel: string): boolean => rel.startsWith('node_modules/') && declaresShipkit(root)
+const isUninstalledDep = (d: Disk, rel: string): boolean => rel.startsWith('node_modules/') && declaresShipkit(d)
 
-const readSettings = (root: string): Settings | null => {
-    const p = join(root, SETTINGS_PATH)
-    if (!existsSync(p)) return null
-    try { return JSON.parse(readFileSync(p, 'utf8')) as Settings } catch { return null }
-}
+const readSettings = (d: Disk): Settings | null => parsed<Settings>(d.read(SETTINGS_PATH))
 
 const guardHookCommand = (s: Settings): string | null => {
     for (const m of s.hooks?.['PreToolUse'] ?? [])
@@ -82,11 +87,11 @@ const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
  *  nothing, so the agent sees only the bare deny, which is the one failure
  *  this rule exists to prevent. Declaring it and never running it is worse
  *  than not declaring it, so it FAILs. */
-function guardScriptMissing(root: string, command: string): string | null {
+async function guardScriptMissing(d: Disk, command: string): Promise<string | null> {
     const rel = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)?.[1]
-    if (rel != null) return existsSync(join(root, rel)) ? null : rel
+    if (rel != null) return d.exists(rel) ? null : rel
     const abs = /^bun\s+["']?(\/[^"'\s]+)["']?/.exec(command.trim())?.[1]
-    if (abs != null) return existsSync(abs) ? null : abs
+    if (abs != null) return (await existsOutside(d, abs)) ? null : abs
     return null // a form this rule cannot resolve is not a form it may condemn
 }
 
@@ -94,42 +99,44 @@ function guardScriptMissing(root: string, command: string): string | null {
  *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
  *  repo's own dependency, else the copy of shipkit doing the fixing, which is
  *  the one the launcher falls back to in a repo that has none */
-export function guardCommandFor(root: string): string {
-    const bin = inferBin(readPkg(root)?.scripts ?? {})
+export async function guardCommandFor(d: Disk): Promise<string> {
+    const bin = inferBin(readPkg(d)?.scripts ?? {})
     if (bin != null) {
         const fromBin = guardCommand(bin)
-        if (guardScriptMissing(root, fromBin) == null) return fromBin
+        if ((await guardScriptMissing(d, fromBin)) == null) return fromBin
     }
-    if (declaresShipkit(root)) return guardCommand()
+    if (declaresShipkit(d)) return guardCommand()
     return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
-export const oneWayInPolicy: Rule = {
+export const oneWayInPolicy = check({
     id: 'SK013',
     blocking: true,
     title: 'one way in policy',
+    description: 'the agent settings deny every raw runner this repo governs and name the gate',
     owner: OWNER,
-    // .claude/settings.json, package.json, and whether the declared guard
-    // script resolves — the last one is a config-chosen path
-    inputs: ['.'],
-    lint: (t, env) => {
-        const want = denyRules(exemptSlots(env.config))
-        if (want.length === 0) return t.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
-        const s = readSettings(env.root)
+    // 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
+    run: async (c) => {
+        const d = c
+        const want = denyRules(exemptSlots(c.config))
+        if (want.length === 0) return c.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
+        const s = readSettings(d)
         if (s == null) {
-            t.fail(`${SETTINGS_PATH} ${existsSync(join(env.root, SETTINGS_PATH)) ? 'is unparseable' : 'missing'} — nothing stops an agent typing \`bun test\`, and a package.json script cannot intercept a bun builtin`)
+            c.fail(`${SETTINGS_PATH} ${d.exists(SETTINGS_PATH) ? 'is unparseable' : 'missing'} — nothing stops an agent typing \`bun test\`, and a package.json script cannot intercept a bun builtin`)
             return
         }
         const have = new Set(s.permissions?.deny ?? [])
         const missing = want.filter((r) => !have.has(r))
         if (missing.length > 0)
-            t.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
+            c.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
         const guard = guardHookCommand(s)
         let guardRuns = false
         if (guard == null)
-            t.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
+            c.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
         else {
-            const missing = guardScriptMissing(env.root, guard)
+            const missing = await guardScriptMissing(d, guard)
             guardRuns = missing == null
             // the hook is DECLARED either way, so it starts working the moment
             // the dependency lands: no second fix run, nothing to remember. An
@@ -137,13 +144,13 @@ export const oneWayInPolicy: Rule = {
             // that fixes it, not a red gate on a repo nobody has installed yet,
             // and the deny list is the floor throughout. A path this repo chose
             // and got wrong is still a FAIL: it will never resolve on its own.
-            if (missing != null && isUninstalledDep(env.root, missing))
-                t.warn(
+            if (missing != null && isUninstalledDep(d, missing))
+                c.warn(
                     `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which is not installed yet — until then a refusal names no replacement, and the deny list is the whole floor`,
                     `bun install (or bun add -d rvlib-shipkit)`,
                 )
             else if (missing != null)
-                t.fail(
+                c.fail(
                     `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which does not exist — every Bash call errors and no refusal ever names the shipkit command`,
                     `point it at this repo's own copy of hooks/one-way-in-guard.ts, or delete the hook and let the deny list stand alone`,
                 )
@@ -151,18 +158,18 @@ export const oneWayInPolicy: Rule = {
         // the summary states only what the file actually delivers: claiming the
         // replacement is named while the guard cannot run is the green that
         // measured nothing, one line under the WARN that says otherwise
-        if (!t.failed)
-            t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s)${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
+        if (!c.failed)
+            c.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s)${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
     },
     // 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: (env: RuleEnv): FixResult => {
-        const want = denyRules(exemptSlots(env.config))
+    fix: async (c): Promise<FixResult> => {
+        const d = c
+        const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }
-        const p = join(env.root, SETTINGS_PATH)
-        const existing = readSettings(env.root)
-        if (existing == null && existsSync(p)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
+        const existing = readSettings(d)
+        if (existing == null && c.exists(SETTINGS_PATH)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
         const s: Settings = existing ?? {}
         const changes: string[] = []
         const deny = s.permissions?.deny ?? []
@@ -171,7 +178,7 @@ export const oneWayInPolicy: Rule = {
             s.permissions = { ...s.permissions, deny: [...deny, ...added] }
             changes.push(`${added.length} raw runner(s) denied`)
         }
-        const wantGuard = guardCommandFor(env.root)
+        const wantGuard = await guardCommandFor(d)
         if (!hasGuardHook(s)) {
             const pre = s.hooks?.['PreToolUse'] ?? []
             s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: wantGuard }] }] }
@@ -183,16 +190,17 @@ export const oneWayInPolicy: Rule = {
             for (const m of s.hooks?.['PreToolUse'] ?? [])
                 for (const h of m.hooks ?? []) {
                     if (h.command?.includes('one-way-in-guard') !== true) continue
-                    const missing = guardScriptMissing(env.root, h.command)
-                    if (missing == null || isUninstalledDep(env.root, missing) || h.command === wantGuard) continue
-                    if (guardScriptMissing(env.root, wantGuard) != null) continue
+                    const missing = await guardScriptMissing(d, h.command)
+                    if (missing == null || isUninstalledDep(d, missing) || h.command === wantGuard) continue
+                    if ((await guardScriptMissing(d, wantGuard)) != null) continue
                     changes.push(`PreToolUse guard repointed from ${missing}, which does not exist`)
                     h.command = wantGuard
                 }
         }
         if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
-        mkdirSync(dirname(p), { recursive: true })
-        atomicWrite(p, JSON.stringify(s, null, 2) + '\n')
+        c.write(SETTINGS_PATH, JSON.stringify(s, null, 2) + '\n')
         return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
     },
-}
+})
+
+export default oneWayInPolicy

package/src/{rules/SK014-prose-ste.ts → checks/SK014-prose-ste.check.ts}

@@ -17,34 +17,48 @@
 // 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 type { Rule } from './rule.ts'
+import { check } from '../check.ts'
 
 const OWNER = 'identity/writing-voice.md'
 
-export const proseSte: Rule = {
+export const proseSte = check({
     id: 'SK014',
     blocking: true,
     title: 'STE prose',
+    description: 'house prose passes the mechanical STE rules',
     owner: OWNER,
-    inputs: ['.'],
-    lint: (t, env) => {
-        const cfg = env.config.prose
+    // 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
+    run: (c) => {
+        const cfg = c.config.prose
         if (cfg == null || (cfg.include ?? []).length === 0) {
-            t.ok(`no prose scope declared — add \`prose: { include: [...] }\` to repo.config.ts to gate house prose on STE`)
+            c.ok(`no prose scope declared — add \`prose: { include: [...] }\` to repo.config.ts to gate house prose on STE`)
+            return
+        }
+        const r = runProseCheck({ c, config: cfg })
+        // a scope that resolves to zero files reads exactly like a clean repo,
+        // and it is the opposite: the repo asked for the gate and the gate
+        // inspects nothing. A green here is coverage nobody has.
+        if (r.files === 0) {
+            c.warn(
+                `prose scope matches no file: ${(cfg.include ?? []).join(', ')} — declared and inspecting nothing`,
+                'fix the globs in repo.config.ts prose.include (or its exempt list), or drop the key to opt out',
+            )
             return
         }
-        const r = runProseCheck({ root: env.root, config: cfg })
         const blocking = r.byTier.fix + r.byTier.hard
-        for (const l of proseLines(r, { cap: 12, tiers: ['fix', 'hard'] })) t.note(l)
+        for (const l of proseLines(r, { cap: 12, tiers: ['fix', 'hard'] })) c.note(l)
         if (blocking > 0)
-            t.fail(
+            c.fail(
                 `${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,
             )
         if (cfg.baseline != null && r.byTier.soft > cfg.baseline)
-            t.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 (sentence length, passive voice), above the declared baseline of ${cfg.baseline} — the ratchet only goes down`)
         else if (r.byTier.soft > 0)
-            t.warn(`${r.byTier.soft} soft hit(s): sentence length and passive voice need a human read${cfg.baseline != null ? ` (baseline ${cfg.baseline})` : ''}`)
-        if (!t.failed && blocking === 0) t.ok(`${r.files} file(s) STE-clean on the mechanical rules`)
+            c.warn(`${r.byTier.soft} soft hit(s): sentence length and passive voice need a human read${cfg.baseline != null ? ` (baseline ${cfg.baseline})` : ''}`)
+        if (!c.failed && blocking === 0) c.ok(`${r.files} file(s) STE-clean on the mechanical rules`)
     }
-}
+})
+
+export default proseSte

package/src/{rules/SK015-nested-repo.ts → checks/SK015-nested-repo.check.ts}

@@ -3,27 +3,30 @@
 // sites that write history refuse on the disk fact either way (core/nesting.ts),
 // so this rule is about the declaration telling the truth to the next reader.
 import { nestedIn } from '../core/nesting.ts'
-import type { Rule } from './rule.ts'
+import { check } from '../check.ts'
 
-export const nestedRepo: Rule = {
+export const nestedRepo = check({
     id: 'SK015',
     blocking: true,
     title: 'nested repo',
-    owner: 'build/shipkit.md',
+    description: 'a config inside a larger work tree declares `nested: true`, and only there',
+    owner: 'build/shipkit/config-keys.md',
     never: 'reads where the git work tree root sits, which no content inside the repo describes',
-    lint: (t, env) => {
-        const top = nestedIn(env.root)
-        const declared = env.config.nested === true
+    run: (c) => {
+        const top = nestedIn(c.root)
+        const declared = c.config.nested === true
         if (top != null && !declared) {
-            t.fail(`repo.config.ts sits inside the git repo at ${top} and does not declare it`)
-            t.lines.push({ kind: 'fix-fail', text: 'add `nested: true` to repo.config.ts: shipkit then owns this folder only, and never writes the parent history' })
+            c.fail(`repo.config.ts sits inside the git repo at ${top} and does not declare it`)
+            c.lines.push({ kind: 'fix-fail', text: 'add `nested: true` to repo.config.ts: shipkit then owns this folder only, and never writes the parent history' })
             return
         }
         if (top == null && declared) {
-            t.fail('repo.config.ts declares `nested: true`, but this folder is its own git work tree root (or sits outside git)')
-            t.lines.push({ kind: 'fix-fail', text: 'delete `nested: true` from repo.config.ts' })
+            c.fail('repo.config.ts declares `nested: true`, but this folder is its own git work tree root (or sits outside git)')
+            c.lines.push({ kind: 'fix-fail', text: 'delete `nested: true` from repo.config.ts' })
             return
         }
-        t.ok(top == null ? 'not nested, and not declared nested' : `nested in ${top}, declared`)
+        c.ok(top == null ? 'not nested, and not declared nested' : `nested in ${top}, declared`)
     },
-}
+})
+
+export default nestedRepo

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

@@ -0,0 +1,182 @@
+// 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.
+// 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.
+//
+// It WARNs rather than FAILs for the whole window, because the repo is not
+// broken: it is behind. The day the shapes are refused, `defineRepo` and
+// discovery say so at load, which is a louder place than a lint row.
+//
+// It reads and writes through `c` alone. The config half of the rewrite loads
+// repo.config.ts as a module, which no read can stand for, so it runs in its
+// own process (core/config-rewrite.ts) through `c.exec`.
+import { join } from 'path'
+import { checkFileRunBy, dropConfigKey, legacyShapes, scriptPort, taskCheckSource, checkFileName } from '../core/legacy-shapes.ts'
+import type { ConfigPlan, ConfigRewrite } from '../core/config-rewrite.ts'
+import { check, type CheckCtx, type FixResult, type TaskDef } from '../check.ts'
+
+/** the config half of the rewrite, run as its own process */
+const CONFIG_REWRITE = join(import.meta.dir, '../core/config-rewrite.ts')
+
+/** what applies the config half of a plan and says what it did */
+export type ConfigRewriter = (plan: ConfigPlan) => Promise<ConfigRewrite>
+
+/** the fixer's rewriter: core/config-rewrite.ts in its own process, since
+ *  loading repo.config.ts as a module is not a read the context records */
+const inOwnProcess = (c: CheckCtx): ConfigRewriter => async (plan) => {
+    const r = await c.exec([process.execPath, CONFIG_REWRITE, c.root, JSON.stringify(plan)], { cwd: c.root, timeoutMs: 60_000 })
+    try {
+        return JSON.parse(r.out.trim().split('\n').at(-1) ?? '') as ConfigRewrite
+    } catch {
+        return { did: [], hand: [`the repo.config.ts rewrite did not answer (exit ${r.code}${r.timedOut ? ', timed out' : ''}: ${r.out.trim().slice(0, 160)}) — apply ${JSON.stringify(plan)} by hand`] }
+    }
+}
+
+const OWNER = 'build/shipkit/writing-a-check.md'
+
+export const legacyCheckShapes = check({
+    id: 'SK016',
+    title: 'legacy check shapes',
+    description: 'every check declaration uses the current check file shape',
+    owner: OWNER,
+    // about THIS repo's own declarations, so it is a repo fact. It only ever
+    // warns while the window is open, which is the severity, not the axis
+    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
+    run: (c) => {
+        const s = legacyShapes(c, c.config)
+        if (s.count === 0 && s.placeholders.length === 0) {
+            c.ok('no legacy declaration: every check in this repo is a check file')
+            return
+        }
+        // the one thing the migration cannot write: a sentence only the
+        // author knows. The check loads and runs meanwhile, so it is a warning
+        // that names each file, never a refusal
+        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',
+            )
+        if (s.count === 0) return
+        // one WARN per shape, never a bare line: the gate promises every line
+        // it prints carries a wire prefix, and this check runs in every gate
+        if (s.checkFiles.length > 0) {
+            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 (s.checkDefaults) c.warn(`repo.config.ts checkDefaults lets a file forget \`blocking\` — the value belongs in each file`)
+        if (s.tasks.length > 0) {
+            const data = s.tasks.filter((x) => x.data).length
+            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>' }\``)
+        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',
+        )
+    },
+    fix: async (c) => await fixLegacyShapes(c),
+})
+
+export default legacyCheckShapes
+
+/** the rewrite. Everything it cannot do without guessing is NAMED in the
+ *  summary instead of attempted, so a repo is never left half migrated.
+ *  `rewrite` applies the config half, in its own process unless a caller
+ *  that may load the config in process hands `rewriteConfig` itself */
+export async function fixLegacyShapes(c: CheckCtx, rewrite: ConfigRewriter = inOwnProcess(c)): Promise<FixResult> {
+    const { root } = c
+    const config = c.config
+    const s = legacyShapes(c, config)
+    const todo = (rel: string): string => `${rel}: replace the TODO with one line stating what must be true`
+    if (s.count === 0)
+        return { changed: false, summary: s.placeholders.length === 0 ? 'nothing legacy left to rewrite' : `nothing mechanical left. ${s.placeholders.length} by hand: ${s.placeholders.map(todo).join(' | ')}` }
+
+    const did: string[] = []
+    const hand: string[] = s.placeholders.map(todo)
+    const source = (rel: string): string => c.read(rel) ?? ''
+
+    // THE PLAN, before any write. A check script is never rewritten: its body
+    // prints and exits in a process of its own, and the one body a check file
+    // has is `run: (c) => …` (SK020 refuses a check file that spawns itself).
+    // Moving prints onto `c` is a hand pass, so each script is listed with
+    // where it goes, and the static reader keeps running it meanwhile. The
+    // tasks move all together or not at all: the `tasks` key is dropped
+    // whole, and a task that runs a script waits for that script's port
+    const tasks = config.tasks ?? []
+    const checkRels = new Set(s.checkFiles.map((f) => f.rel))
+    const runsOf = new Map<TaskDef, { rel: string; rest: string[] }>()
+    for (const t of tasks) {
+        const r = t.logic == null ? checkFileRunBy(t, root) : null
+        if (r != null && checkRels.has(r.rel)) runsOf.set(t, r)
+    }
+    const fileIds = new Set(s.checkFiles.map((f) => f.read.name))
+    const configText = source('repo.config.ts')
+    const taskBlock: string[] = []
+    if (tasks.length > 0 && dropConfigKey(configText, 'tasks') == null) taskBlock.push('the `tasks` key could not be read mechanically')
+    for (const t of tasks) {
+        const runs = runsOf.get(t)
+        if (t.logic != null || t.cmd == null) taskBlock.push(`task ${t.id}: its body is \`logic\`, a function — move it into ${checkFileName(t.id)} beside repo.config.ts as \`run\``)
+        else if (runs != null) taskBlock.push(`task ${t.id}: it runs ${runs.rel}, a check script — port that file first, then drop the task: the check file is the check`)
+        else if (fileIds.has(t.id)) taskBlock.push(`task ${t.id}: a check file answers to the same id, and the task does not simply run that file, so the two are different checks — rename one of them`)
+        else if (c.exists(checkFileName(t.id))) taskBlock.push(`task ${t.id}: ${checkFileName(t.id)} already exists beside repo.config.ts, so its check file needs another name`)
+    }
+    const tasksMove = tasks.length > 0 && taskBlock.length === 0
+    if (!tasksMove) {
+        for (const l of taskBlock) hand.push(l)
+        if (tasks.length > 0) hand.push(`the ${tasks.length} task(s) stay in repo.config.ts until the line(s) above are done, then they move together`)
+    }
+
+    // 1. the check scripts, each listed with where it goes. Its declarations
+    //    are what the static reader read, so the port loses none of them
+    for (const f of s.checkFiles) hand.push(`${f.rel}: ${scriptPort(f.read, config.checkDefaults?.blocking)}`)
+    const filesLeft = s.checkFiles.length
+
+    // 2. the tasks that are DATA, each as its own check file beside the
+    //    config (the plan refused a name another file already holds)
+    for (const t of tasksMove ? tasks : []) {
+        const name = checkFileName(t.id)
+        c.write(name, taskCheckSource(t, root))
+        did.push(`task ${t.id} → ${name}`)
+        // a config entry carries no prose, so nothing can be lifted: the file
+        // passes the shape and a human owes it the line
+        hand.push(`${name}: a task declaration carried no prose — replace the TODO with one line stating what must be true`)
+    }
+
+    // 3. a rule is a function too, and the file it was written in owns the
+    //    names it closes over. The fixer says where it goes, never guesses
+    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}`
+    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) {
+        const out = await rewrite(cfgPlan)
+        did.push(...out.did)
+        hand.push(...out.hand)
+        if (out.restored != null)
+            return { changed: did.length > 0, summary: `repo.config.ts was left as it was, its rewrite did not load back (${out.restored}). Done: ${did.join('; ') || 'nothing'}` }
+    }
+
+    const summary = [
+        did.length > 0 ? did.join('; ') : 'nothing mechanical left',
+        ...(hand.length > 0 ? [`${hand.length} by hand: ${hand.join(' | ')}`] : []),
+    ].join('. ')
+    return { changed: did.length > 0, summary }
+}