rvlib-shipkit 0.38.0 → 1.0.0

package/src/core/run-ci.ts

@@ -1,22 +1,25 @@
-// the ci gate — floor + contracts + repo tasks through the DAG runner, THEN
-// every discovered check (core/run-check.ts owns severity). Plain module
-// behind cmd_Ci (logic stays out of command classes) so tests can run the
-// gate in-process. Returns the exit code; json prints the structured summary.
-// Every run refreshes STATUS.md (write-status.ts — atomic + lock) unless
-// status:false, and the fix pass plus some checks WRITE, so a run is not
-// read-only unless frozen is set and --no-fix is passed.
+// THE GATE — `shipkit ci`: the mechanical fix pass, then every check the gate
+// asks for through the one runner (core/check-runner.ts, core/run-check.ts holds
+// the shared body). Plain module behind cmd_Ci (logic stays out of command
+// classes) so tests can run the gate in-process. Returns the exit code; json
+// prints the structured summary. Every run refreshes STATUS.md
+// (write-status.ts — atomic + lock) unless status:false, and the fix pass plus
+// some checks WRITE, so a run is not read-only unless frozen is set and
+// --no-fix is passed.
 import { join } from 'path'
-import { allTasks, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
-import { checkSideIds, collectChecks } from './run-check.ts'
+import { runCheckPass, type CheckOpts } from './run-check.ts'
+import { poolLines } from './slots.ts'
 import { runFixPass } from './run-fixers.ts'
-import { formatLine } from './wire.ts'
-import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
+import { formatLine, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
-import { withContractsScope } from '../contracts/contracts-once.ts'
-import { envTier, FULL_TESTS_ENV, gateInventory, gateUnits, tieredTasks, type TestTier } from '../ledger/gate-units.ts'
-import { UNIT_TABLE_FILE, writeUnitTable } from '../ledger/unit-table.ts'
-import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
+import { allTasks, composeChecks, envTier, FULL_TESTS_ENV, gateInventory, type TestTier } from '../ledger/gate-checks.ts'
+import { CHECK_TABLE_FILE, writeCheckTable } from '../ledger/check-table.ts'
+import { Ledger } from '../ledger/ledger.ts'
+import { RunLog, type InvokedBy } from '../ledger/run-log.ts'
+import { gateBinary } from '../ledger/toolchain-identity.ts'
+import type { CheckResult } from './check-runner.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -33,76 +36,81 @@ export type CiOpts = {
     fixRules?: boolean
     /** self-arm the git hooks in the fix pass (interactive ci entry only) */
     armHooks?: boolean
-    /** run only the checks that can block (core/run-check onlyBlocking) */
+    /** run only the checks that can block (core/run-checks onlyBlocking) */
     onlyBlockingChecks?: boolean
-    /** task ids the caller does not need. A sub-unit release skips the tasks
-     *  that gate the whole repo, since the unit's own gate already ran. */
+    /** check ids the caller does not need. A sub-unit release skips the steps
+     *  that gate the whole repo, since the check's own gate already ran. */
     skipTaskIds?: string[]
-    /** report-only for self-maintaining rules and checks (SHIPKIT_FROZEN
-     *  travels to child checks). The release path passes it: a rule that
-     *  rewrites package.json between the gate and `npm publish` packs a tree
-     *  that exists in no commit. */
+    /** report-only for self-maintaining checks (SHIPKIT_FROZEN travels to
+     *  children). The release path passes it: a check that rewrites
+     *  package.json between the gate and `npm publish` packs a tree that
+     *  exists in no commit. */
     frozen?: boolean
-    /** treat a NON-blocking check failure as fatal too. `release.requireHealthy`
-     *  is the only caller: a repo that wants a missing cred to stop a release
+    /** treat a NON-blocking failure as fatal too. `release.requireHealthy` is
+     *  the only caller: a repo that wants a missing cred to stop a release
      *  asks for it, and every other run keeps the declared severity. */
     failOnAdvisory?: boolean
-    /** run the tasks only. The TUI owns this: it renders the checks in its own
-     *  panel, and running the suite twice per refresh proves nothing twice. */
-    skipChecks?: boolean
+    /** the BUILD steps alone. The TUI owns this: it renders the rest in its
+     *  own panel, and running them twice per refresh proves the same thing
+     *  twice. */
+    buildOnly?: boolean
     /** line sink — commands pass their context stream; defaults to console */
     print?: (line: string) => void
-    /** per-task completion tap — the TUI tasks panel streams results in */
-    onTaskFinish?: (r: TaskResult) => void
+    /** per-CHECK completion tap, handed straight to the runner. The hub passes
+     *  it, so one gate run colours every row as it lands. */
+    onCheck?: CheckOpts['onCheck']
     /** the already-resolved config. A caller that holds one MUST pass it: two
      *  loads of repo.config.ts can disagree, and the release path classifies
-     *  rule-vs-probe severity from the config it holds. */
+     *  severity from the config it holds. */
     config?: RepoConfig
-    /** re-measure everything: no unit replays from the ledger, and what this
-     *  run measures is stored fresh. Travels to child checks as SHIPKIT_FRESH. */
+    /** run everything: no answer comes from the cache, and what this
+     *  run finds is stored fresh. Travels to children as SHIPKIT_FRESH. */
     fresh?: boolean
+    /** the gate binary this run is keyed on (default: the one running it).
+     *  Toolchain identity content-hashes the directory the entry lives in, so
+     *  a caller whose answers must survive an edit to that tree hands in a
+     *  stable one instead of betting on nobody writing to it mid-run. */
+    cliEntry?: string
     /** read the ledger at all. The release path passes false, unconditionally
      *  and not configurably: every remaining hole in the key is then capped at
      *  "an agent saw a stale local green", never "a stale green authorised a
      *  publish" (ledger/ledger.ts rule 4). */
     ledgerRead?: boolean
     /** which test tier the run asks the repo's suite for. 'quick' is the
-     *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every task, which
-     *  a suite reads to include the slow, real-world tiers it otherwise skips.
-     *  The release path always asks for 'full': a version published behind a
-     *  partial suite is a green nobody measured. Default reads the env var, so
-     *  `SHIPKIT_TEST_FULL=1 shipkit ci` works with no flag. */
+     *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every build step,
+     *  which a suite reads to include the slow tiers it otherwise skips. The
+     *  release path always asks for 'full': a version published behind a
+     *  partial suite is a green nobody measured. */
     tests?: TestTier
+    /** who started this run, as the run record files it */
+    invokedBy?: InvokedBy
 }
 
-export type { TestTier } from '../ledger/gate-units.ts'
-export { FULL_TESTS_ENV } from '../ledger/gate-units.ts'
+export type { TestTier } from '../ledger/gate-checks.ts'
+export { FULL_TESTS_ENV } from '../ledger/gate-checks.ts'
 
-/** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
- *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
+/** what STATUS.md may claim about this run. `--with` ADDS a check, so it stays
+ *  the full gate; `--only`, `--skip` and buildOnly each remove coverage, and
  *  a narrowed run that stamps the full gate's verdict is a green nobody
  *  measured. The label names the invocation either way. */
 function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
     const narrowing = [
         ...(o.onlyIds ?? []).map((i) => `--only ${i}`),
         ...(o.skipGroups ?? []).map((g) => `--skip ${g}`),
-        ...(o.skipChecks === true ? ['(tasks only)'] : []),
+        ...(o.buildOnly === true ? ['(build steps only)'] : []),
     ]
-    const parts = [...narrowing, ...(o.withIds ?? []).map((i) => `--with ${i}`)]
+    // the tier is part of what ran: a full tier gate runs every slow suite, one
+    // at a time, and a label without it reads as an everyday run
+    const tier = (o.tests ?? envTier()) === 'full' ? ['--full'] : []
+    const parts = [...narrowing, ...(o.withIds ?? []).map((i) => `--with ${i}`), ...tier]
     return { command: parts.length === 0 ? 'shipkit ci' : `shipkit ci ${parts.join(' ')}`, fullGate: narrowing.length === 0 }
 }
 
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
-    // ONE gate run: the `contracts` task evaluates, rule SK002 reads what it
-    // computed instead of evaluating a second time (contracts-once.ts)
-    return await withContractsScope(() => runCiInScope(root, o))
-}
-
-async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
-    const c = o.config ?? (await loadRepoConfig(root))
+    let c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
     // a NARROWED run repairs only the mechanical slots. The structural rule
@@ -110,185 +118,142 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     // that is the right price for the full gate and the wrong one for
     // `bun run test`, which routes here and must answer the one question its
     // name promises without leaving files in the agent's diff that it never
-    // wrote. Under CI it is worse than surprising, a formatting rewrite comes
+    // wrote. Under CI it is worse than surprising: a formatting rewrite comes
     // back as a test failure.
     const narrowed = (o.onlyIds ?? []).length > 0
-    if (o.fix !== false)
-        fixFailed = (await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink })).failed
-    else sink('skip: fix pass (--no-fix)')
-    const all = allTasks(c, root)
-    const { disabled, unfilled } = all
-    const skipIds = new Set(o.skipTaskIds ?? [])
+    if (o.fix !== false) {
+        const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink })
+        fixFailed = pass.failed
+        // a fixer that rewrote the config or moved a check file leaves the
+        // config above describing a repo that is gone, so the gate reads the
+        // one on disk. A config that no longer loads is the gate's answer
+        if (pass.reshaped) {
+            try { c = await loadRepoConfig(root, { fresh: true }) } catch (e) {
+                sink(`FAIL: repo.config.ts no longer loads after the fix pass — ${String(e).slice(0, 200)}`)
+                return 1
+            }
+        }
+    } else sink('skip: fix pass (--no-fix)')
     const tier: TestTier = o.tests ?? envTier()
-    const tasks = all.tasks
-        .filter((t) => !skipIds.has(t.id))
-        // the whole run carries the flag rather than one task id: a repo names
-        // its suites what it likes (`test`, `test:libs`, a prepublish script),
-        // and a gate that guesses which one is the tests will miss one
-        .map((t) => (tier === 'full' ? { ...t, env: { ...t.env, [FULL_TESTS_ENV]: '1' } } : t))
     // announced BEFORE the run, so a log that died mid-way still says which
     // tier it was asking for
     sink(tier === 'full'
         ? `ok: test tier FULL — every suite, the slow ones included (${FULL_TESTS_ENV}=1)`
         : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
-    for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
-    for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
-    for (const n of all.notes ?? []) sink(n)
+    for (const l of poolLines()) sink(l)
+    // a floor slot nothing could fill is VISIBLE — a thin gate must never look
+    // like a full one (the fresh-repo floor gap)
+    const floor = await allTasks(c, root)
+    for (const n of floor.notes ?? []) sink(n)
+    for (const u of floor.unfilled) {
+        sink(`skip: ${u.id} (${u.reason})`)
+        // asked for BY NAME and unfillable: this is where an agent lands after
+        // the harness refused it the raw runner, so the line says what to add
+        // rather than leaving it with `unknown check id` and no next move
+        if ((o.onlyIds ?? []).includes(u.id))
+            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
+    }
+    // the run record: one run id for every check of this gate, so a breakdown
+    // of the wall time is reconstructable. It is never read here, only written
+    const scope = ciScope(o)
+    const runLog = RunLog.open(root, { invocation: { kind: 'ci', label: scope.command, by: o.invokedBy ?? 'cli', narrowed: !scope.fullGate } })
     // THE LEDGER, opened once per run and AFTER the fix pass: the fixers
-    // rewrite source, and a scan taken before them would have every unit
+    // rewrite source, and a scan taken before them would have every check
     // discarded by its own gate's repair work.
     //
     // Registration is validated on the way in, and it is loud in the gate
-    // rather than only in `shipkit keys`, because a unit declaring two
+    // rather than only in `shipkit keys`, because a check declaring two
     // contradictory populations is a bug in what binds every repo. The
     // burn-down is one line, never a wall.
     let registrationFailed = false
     let ledger: Ledger | null = null
+    // ONE walk for the whole gate: the ledger is keyed on it and the run
+    // measures it, and two walks can disagree about what exists
+    const composed = await composeChecks(root, c, { tier })
     try {
-        ledger = Ledger.open(root, gateUnits(root, c, tasks), {
-            cliEntry: new URL('../cli.ts', import.meta.url).pathname,
+        ledger = Ledger.open(root, composed.map((g) => g.row.decl), {
+            cliEntry: o.cliEntry ?? gateBinary(),
             read: o.ledgerRead,
             fresh: o.fresh,
         })
         const reg = ledger.layer.registration
         for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
-        if (registrationFailed) sink('      fix: a unit declares `inputs` (content), or `ttl` (world), or `never: <reason>`, and never two of them')
+        if (registrationFailed) sink('      fix: a check declares `inputs` (content), or `ttl` (world), or `never: <reason>`, and never two of them')
         // both counts, always. Printing only the burn-down made `never:` the
         // cheap way to shrink the visible number, and that field carries no
         // verification at all: a growing decided population has to be as
         // visible as a shrinking undeclared one.
-        const decided = reg.units - reg.burnDown.length - reg.declared
+        const decided = reg.checks - reg.burnDown.length - reg.declared
         if (reg.burnDown.length > 0 || decided > 0)
-            sink(`skip: cache declarations — ${reg.declared}/${reg.units} declared, ${decided} decided uncacheable, ${reg.burnDown.length} undeclared, so they are measured every run (shipkit keys --burn-down)`)
+            sink(`skip: cache declarations — ${reg.declared}/${reg.checks} declared, ${decided} never cached on purpose, ${reg.burnDown.length} undeclared, so those run every time (shipkit keys --burn-down)`)
         if (ledger.layer.failure != null)
-            sink(`WARN the git scan failed, so NOTHING replays and nothing is stored this run — ${ledger.layer.failure}`)
+            sink(`WARN the git scan failed, so NOTHING comes from the cache and nothing is stored this run — ${ledger.layer.failure}`)
     } catch (e) {
         ledger = null
-        sink(`WARN ledger unavailable (${String(e).slice(0, 160)}) — every unit is measured this run, so the gate is correct and slower`)
+        sink(`WARN cache unavailable (${String(e).slice(0, 160)}) — every check runs this time, so the gate is correct and slower`)
     }
-    // a floor slot nothing could fill is VISIBLE — a thin gate must never
-    // look like a full one (the fresh-repo floor gap)
-    for (const u of unfilled) {
-        sink(`skip: ${u.id} (${u.reason})`)
-        // asked for BY NAME and unfillable: this is where an agent lands after
-        // the harness refused it the raw runner, so the line says what to add
-        // rather than leaving it with `unknown task id` and no next move
-        if ((o.onlyIds ?? []).includes(u.id))
-            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
-    }
-    // REPLAY, before the DAG sees the list. A replayed task is removed from
-    // the run entirely, which is also what makes its dependents correct: the
-    // runner treats a filtered dep as satisfied, and only a GREEN is ever
-    // stored, so a dependent can never start on the back of a red nobody saw.
-    // --only addresses tasks, rules and checks alike, so the task runner is
-    // told which ids belong to the other two surfaces rather than answering
-    // `unknown task id` for a check it was never asked to run
-    const otherIds = checkSideIds(root, c)
-    const selectable = new Set(selectTasks({ tasks, logDir: '', skipGroups: o.skipGroups ?? [], withIds: o.withIds ?? [], onlyIds: o.onlyIds ?? [], otherIds }).selected.map((t) => t.id))
-    const replayedTasks = new Map<string, UnitOutcome>()
-    const toRun = tasks
-        .filter((t) => {
-            if (ledger == null || !selectable.has(t.id)) return true
-            const hit = ledger.replay(t.id)
-            if (hit == null) return true
-            replayedTasks.set(t.id, hit)
-            for (const l of stampReplayed(hit.lines, hit.measuredMs)) sink(formatLine(l, false))
-            return false
-        })
-        // a dep ON a replayed task is DROPPED, not left dangling. The runner
-        // validates every dep against the list it was handed and dies with
-        // `unknown dep` otherwise, and dropping is the honest edge here: only a
-        // GREEN is ever replayed, so the dependent's precondition is met and
-        // this is the same "a filtered dep counts as satisfied" the runner
-        // already applies to --skip and opt-in tasks.
-        .map((t) => (t.deps?.some((d) => replayedTasks.has(d)) === true ? { ...t, deps: t.deps.filter((d) => !replayedTasks.has(d)) } : t))
-    // a NAMED task that replayed leaves the list, so its name has to leave the
-    // filters with it: the runner validates `--only`/`--with` against the list
-    // it was handed and answers `unknown task id`. `bun run typecheck` and
-    // `bun run test` route through `--only`, so this is the reflex verb every
-    // agent in every wired repo types, going red on a warm store.
-    const onlyIds = (o.onlyIds ?? []).filter((id) => !replayedTasks.has(id))
-    const withIds = (o.withIds ?? []).filter((id) => !replayedTasks.has(id))
-    // narrowed to nothing is NOT the same as "no filter": an empty --only would
-    // widen the run to every task
-    const nothingToRun = replayedTasks.size > 0 && (toRun.length === 0 || ((o.onlyIds ?? []).length > 0 && onlyIds.length === 0))
-    // every asked-for task replayed: the DAG has nothing to schedule, and
-    // running it anyway would print `all 0 tasks green`, which reads as a gate
-    // that measured nothing rather than one that already knew the answer
-    const summary = nothingToRun
-        ? { ok: true, results: [], interrupted: false }
-        : await runTasks({
-        tasks: toRun,
-        logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
-        cwd: root,
-        bail: o.bail ?? false,
-        skipGroups: o.skipGroups ?? [],
-        withIds,
-        onlyIds,
-        otherIds,
+    // THE RUN. One engine, one DAG, one pass over everything this gate asks
+    // for: `gate = false` opts a check out of the everyday gate, and
+    // failOnAdvisory (release.requireHealthy) re-arms the world probes,
+    // because a repo asking for exactly those must not have them silently
+    // dropped by the opt-out.
+    const run = await runCheckPass(root, {
+        status: false,
+        config: c,
+        composed,
+        audience: 'gate',
+        includeProactive: o.failOnAdvisory === true,
+        frozen: o.frozen,
+        onlyBlocking: o.onlyBlockingChecks,
+        only: o.onlyIds,
+        withIds: o.withIds,
+        skipGroups: o.skipGroups,
+        exclude: o.skipTaskIds,
+        buildOnly: o.buildOnly,
+        bail: o.bail,
+        fresh: o.fresh,
+        tier,
+        ledger,
+        runLog,
+        onCheck: o.onCheck,
+        reportHome: false,
         print: sink,
-        onTaskFinish: o.onTaskFinish,
     })
-    if (nothingToRun) sink(`ok: all ${replayedTasks.size} task(s) asked for replayed, none measured`)
-    // what the suite ACTUALLY ran, from its own summary line. A flag that was
-    // set proves the intent; the count proves the tests
-    for (const r of summary.results) {
-        if (ledger == null || r.status !== 'pass') continue
-        const surfaced = r.lines.filter((l) => l.kind === 'warn' || l.kind === 'fix-warn' || l.kind === 'skip')
-        ledger.record(r.id, {
-            status: surfaced.some((l) => l.kind === 'warn' || l.kind === 'fix-warn') ? 'warn' : 'pass',
-            // the headline is REBUILT rather than captured: the runner renders
-            // the wall time into it, and a duration baked into a stored line
-            // would be replayed as if this run had measured it
-            lines: [{ kind: 'ok', text: r.id }, ...surfaced],
-            lastLine: r.lastLine,
-            measuredMs: r.durationMs,
-        })
-    }
-    const ranTests = [...summary.results.map((r) => r.lastLine ?? ''), ...[...replayedTasks.values()].map((o) => o.lastLine ?? '')]
-        .map((l) => /Ran (\d+) tests?/.exec(l)?.[1])
-        .find((n) => n != null)
-    if (ranTests != null) sink(`ok: test tier ${tier}: ${ranTests} tests ran`)
-    // the checks, in the SAME command. there is no second surface: a check
-    // declares whether it blocks, and that is the only question about it.
-    // a narrowed run says what it did NOT look at: a green that only ever
-    // asked one question must not read like the full gate
-    if ((o.onlyIds ?? []).length > 0 && o.skipChecks !== true) sink(`skip: checks not named by --only (${(o.onlyIds ?? []).join(', ')})`)
-    // no release survey is pre-warmed here. It is ~3s of registry and `gh`
-    // network, and the only thing that ever read it is the lib-drift probe,
-    // which asks what is PUBLISHED and so has no business in a gate that asks
-    // whether this change is good. collectChecks owns the share path, so the
-    // checks that do want it still pay for exactly one survey between them.
-    const checks = o.skipChecks === true
-        ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        // `gate = false` opts a check out of the EVERYDAY gate. failOnAdvisory
-        // is release.requireHealthy, a repo saying it wants a missing cred to
-        // stop its publish, so it re-arms them: the opt-out must not silently
-        // drop the one request that asks for exactly these probes.
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds, fresh: o.fresh, ledger, reportHome: false, gateOnly: o.failOnAdvisory !== true })
-    const color = process.stdout.isTTY && process.env.NO_COLOR == null
-    for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
-    for (const u of checks.undeclared) {
+    // what the suite ACTUALLY ran, from its own headline. A flag that was set
+    // proves the intent; the count proves the tests
+    // proves the intent; the count proves the tests. Every test check counts,
+    // one per unit
+    const counts = run.results.map((r) => /Ran (\d+) tests?/.exec(r.lastLine)?.[1]).filter((n) => n != null).map(Number)
+    if (counts.length > 0) sink(`ok: test tier ${tier}: ${counts.reduce((a, b) => a + b, 0)} tests ran${counts.length > 1 ? ` in ${counts.length} test checks` : ''}`)
+    for (const u of run.undeclared) {
         sink(`FAIL: ${u} does not declare whether it blocks`)
-        sink(`      fix: add \`export const blocking = true\` (about this repo) or \`false\` (about the world) to that file`)
+        sink(`      fix: add \`blocking: true\` (about this repo) or \`false\` (about the world) to that check`)
+    }
+    // a switch wired to no check does nothing, silently, which is the one thing
+    // a toggle must never do
+    for (const id of run.unknownWhen) {
+        sink(`FAIL: when.${id} names no check of this repo`)
+        sink(`      fix: \`shipkit checks\` lists every id; drop the entry or correct it`)
     }
     let advisoryFatal = false
-    if (checks.advisoryFailures.length > 0) {
+    if (run.advisoryFailures.length > 0) {
         if (o.failOnAdvisory === true) {
             advisoryFatal = true
-            sink(`FAIL: ${checks.advisoryFailures.length} non-blocking check(s) failing and release.requireHealthy is on: ${checks.advisoryFailures.join(', ')}`)
+            sink(`FAIL: ${run.advisoryFailures.length} non-blocking check(s) failing and release.requireHealthy is on: ${run.advisoryFailures.join(', ')}`)
             sink('      fix: shipkit check')
-        } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
+        } else sink(`WARN ${run.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${run.advisoryFailures.join(', ')}`)
     }
     // the post-run re-hash, then the store. NOTHING was written while the gate
-    // ran: a unit whose inputs moved under it answered about a tree that no
+    // ran: a check whose inputs moved under it answered about a tree that no
     // longer exists, and this is where that result is thrown away instead of
     // stored under a key that describes the file as it was before the edit.
     if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
-    const code = summary.ok && !fixFailed && !registrationFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
+    // one write for the whole gate, after everything has finished
+    for (const l of runLog.flush()) sink(formatLine(l, false))
+    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 ? 1 : 0
     // motherhome row (docsBase wiki on this disk) — never affects the gate,
-    // and never fires under frozen: a bump/release gate must not re-dirty
-    // the tree it just proved clean (field wart 2026-08-05, second head)
+    // and never fires under frozen: a bump/release gate must not re-dirty the
+    // tree it just proved clean
     if (o.frozen !== true) {
         const mh = reportToMotherhome(root, c)
         if (mh.note != null) print(mh.note)
@@ -301,14 +266,13 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
             ...ciScope(o),
             lines: collected,
             exitCode: code,
-            sidecar: { file: UNIT_TABLE_FILE, says: 'Every unit this repo can run, and whether it blocks you' },
+            sidecar: { file: CHECK_TABLE_FILE, says: 'Every check this repo can run, and whether it blocks you' },
         })
         if (!st.written) print(`WARN ${st.warn}`)
-        const units = writeUnitTable(root, { name: c.name, rows: gateInventory(root, c, tieredTasks(c, root, tier)) })
-        if (!units.written) print(`WARN ${units.warn}`)
-
+        const checks = writeCheckTable(root, { name: c.name, rows: composed.map((g) => g.row) })
+        if (!checks.written) print(`WARN ${checks.warn}`)
     }
     if (o.json === true)
-        print(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))
+        print(JSON.stringify({ ok: !run.blocked, interrupted: run.interrupted, disabled: floor.disabled, checks: run.results.map((r: CheckResult) => ({ ...r, lines: undefined })) }))
     return code
 }

package/src/core/run-fix.ts

@@ -0,0 +1,96 @@
+// `shipkit check --fix [<id> …]` — apply check autofixes, then re-run and
+// show the real end state. Never runs under ci (the gate stays pure), never
+// caches (a fixer must see reality). No ids = every fixable check; a
+// requested id that is unknown or unfixable fails loud instead of silently
+// narrowing.
+import { CheckCtx } from './check-ctx.ts'
+import { formatLine } from './wire.ts'
+import { whenOfRule, whenOfCheck, type WhenDecl } from './when.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { discoverChecks } from './discover-checks.ts'
+import { runCheckBody, type CheckDef, type CheckEnv } from '../check.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type FixOpts = {
+    ids?: string[]
+    /** drop the closing advisory: inside the ci fix pass it is noise, and it is
+     *  not wire-shaped, which the frozen output contract forbids */
+    quiet?: boolean
+    print?: (line: string) => void
+}
+
+export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const config = await loadRepoConfig(root)
+    const env: CheckEnv = { root, config }
+    // a fresh context per body: a fixer may rewrite the config, and the body
+    // after it must read the one on disk now
+    const ctx = (c: RepoConfig): CheckCtx => CheckCtx.open({ root, config: c })
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    /** one fixable check, whatever declared it */
+    type Target = { id: string; title: string; owner: string; run: CheckDef['run']; fix?: CheckDef['fix']; when: WhenDecl }
+    // a rule the repo still registers fixes exactly like a check file, one
+    // code path. Only a check that declared a `fix` is a target at all
+    const all: Target[] = [
+        ...(await discoverChecks(root)).map((u): Target => ({ id: u.id, title: u.title, owner: u.owner, run: u.def.run, fix: u.def.fix, when: whenOfCheck(config, u) })),
+        ...(config.rules ?? []).map((r): Target => ({
+            id: r.id, title: r.title, owner: r.owner, when: whenOfRule(config, r.id),
+            run: (c) => r.lint(c, { root: c.root, config: c.config }),
+            fix: r.fix == null ? undefined : (c) => r.fix!({ root: c.root, config: c.config }),
+        })),
+    ]
+
+    let targets = all.filter((r) => r.fix != null)
+    if (o.ids != null && o.ids.length > 0) {
+        for (const id of o.ids) {
+            const r = all.find((x) => x.id === id)
+            if (r == null) { print(`FAIL: unknown check '${id}' — see: shipkit checks`); return 1 }
+            if (r.fix == null) { print(`FAIL: [${id}] has no autofix — fix by hand: ${config.docsBase ?? ''}${r.owner}`); return 1 }
+        }
+        const wanted = new Set(o.ids)
+        targets = targets.filter((r) => wanted.has(r.id))
+    }
+
+    let exit = 0
+    for (const rule of targets) {
+        const before = ctx(env.config)
+        const off = rule.when
+        await runCheckBody(rule, before, off.at === 'off' ? { reason: off.reason } : undefined)
+        // a check that is OFF never autofixes: the repo broke that invariant on purpose
+        if (off.at === 'off') {
+            if (o.quiet !== true) print(`skip: [${rule.id}] ${rule.id} exempt: ${off.reason ?? ''}`)
+            continue
+        }
+        if (!before.failed && !before.warned) {
+            // inside the ci fix pass, a line per already-clean rule is a wall of
+            // nothing above the run that reports those same rules for real
+            if (o.quiet !== true) print(`ok: [${rule.id}] already clean — nothing to fix`)
+            continue
+        }
+        const f = await rule.fix!(ctx(env.config))
+        // an unchanged fix is the DESIGNED outcome for judgment findings, so
+        // it is an ok, not a warning. It carries a frozen wire prefix like
+        // every other line the fix pass emits: `shipkit ci` promises its whole
+        // output is parseable, and a bare line breaks that for every reader.
+        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `ok: [${rule.id}] fix changed nothing — ${f.summary}`)
+        // a fixer may rewrite repo.config.ts, and the re-run below and every
+        // fixer after it must read what is on disk now, never the config this
+        // pass loaded before the rewrite
+        if (f.changed) {
+            try { env.config = await loadRepoConfig(root, { fresh: true }) } catch (e) {
+                print(`FAIL: [${rule.id}] repo.config.ts no longer loads after the fix — ${String(e).slice(0, 200)}`)
+                return 1
+            }
+        }
+        const after = ctx(env.config)
+        await runCheckBody(rule, after)
+        // the fix already ran: advertising it again on surviving findings
+        // would send an agent in a loop
+        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix \S+$/, '') }, color))
+        if (after.failed) exit = 1
+    }
+    const unfixable = all.filter((r) => r.fix == null).length
+    if (unfixable > 0 && o.quiet !== true && (o.ids == null || o.ids.length === 0))
+        print(`${unfixable} check(s) have no autofix — they report in the run below`)
+    return exit
+}