rvlib-shipkit 1.4.0 → 1.5.0

package/src/cli/cmd_When.ts

@@ -0,0 +1,71 @@
+// shipkit when — what runs when: the legend (every context, every value) and
+// one row per check with its declared value on each axis. The same data the
+// hub's when page draws (core/runs-matrix.ts), so the terminal and the page
+// cannot disagree.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { gateInventory } from '../ledger/gate-checks.ts'
+import { legendMarkdown, MATRIX_AXES, matrixLines, RUNS_LEGEND, runsCellsOf, type MatrixAxis } from '../core/runs-matrix.ts'
+import { spliceMarkedBlock } from '../core/doc-block.ts'
+
+export const LEGEND_BEGIN = '<!-- shipkit:when-legend -->'
+export const LEGEND_END = '<!-- /shipkit:when-legend -->'
+
+export class WhenCommand extends Command {
+    static override paths = [['when']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'what runs when: every check on every context, with the legend',
+        details: 'Every check on every context (commit, ci, full, release, health, save, clock, fix) and how its answer is cached, after the legend of every axis and value. Reports, never gates.',
+        examples: [
+            ['the legend, then every check', 'sk when'],
+            ['only what the quick gate runs', 'sk when --only onCi'],
+            ['the matrix without the legend', 'sk when --no-legend'],
+            ['machine-readable', 'sk when --json'],
+            ['write the legend into a docs page between its markers', 'sk when --out wiki/build/shipkit/runs.md'],
+            ['fail if that page is stale (lint mode)', 'sk when --out wiki/build/shipkit/runs.md --check'],
+        ],
+    })
+
+    only = Option.String('--only', { required: false, description: `only the rows one context runs: ${MATRIX_AXES.join(', ')}` })
+    legend = Option.Boolean('--legend', true, { description: 'print the legend first. Default on, --no-legend drops it' })
+    out = Option.String('--out', { required: false, description: 'host file carrying the shipkit:when-legend markers. The legend between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the legend is stale, write nothing' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { legend, rows: [{ id, title, from, blocking, build, runs: { cells, cache, off, derivedWhy } }] }' })
+
+    async execute(): Promise<number> {
+        if (this.out != null) return await this.writeLegend(this.out)
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        if (this.only != null && !(MATRIX_AXES as readonly string[]).includes(this.only)) {
+            this.context.stdout.write(`FAIL: --only takes one of ${MATRIX_AXES.join(', ')}, got '${this.only}'\n`)
+            return 1
+        }
+        const rows = (await gateInventory(root, c)).map((r) => ({ id: r.decl.id, title: r.title, from: r.from, blocking: r.blocking, build: r.build, runs: runsCellsOf(r) }))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify({ legend: RUNS_LEGEND, rows })}\n`)
+            return 0
+        }
+        for (const l of matrixLines(rows, { legend: this.legend, only: this.only as MatrixAxis | undefined })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+
+    /** the legend only depends on the binary, never on the repo */
+    private async writeLegend(path: string): Promise<number> {
+        const { existsSync, readFileSync, writeFileSync } = await import('fs')
+        if (!existsSync(path)) { this.context.stdout.write(`FAIL: ${path} does not exist\n`); return 1 }
+        const host = readFileSync(path, 'utf8')
+        const next = spliceMarkedBlock(host, legendMarkdown(), LEGEND_BEGIN, LEGEND_END)
+        if (next == null) { this.context.stdout.write(`FAIL: ${path} has no ${LEGEND_BEGIN} / ${LEGEND_END} markers\n`); return 1 }
+        if (next === host) { this.context.stdout.write(`ok: ${path} legend current\n`); return 0 }
+        if (this.check) {
+            this.context.stdout.write(`FAIL: ${path} legend is STALE, the binary's axes or values differ from the page\n`)
+            this.context.stdout.write(`      fix: shipkit when --out ${path}\n`)
+            return 1
+        }
+        writeFileSync(path, next)
+        this.context.stdout.write(`ok: ${path} legend rewritten\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Wiki.ts

@@ -10,8 +10,8 @@ export class WikiServeCommand extends Command {
         category: 'Wiki',
         description: 'live md link-graph server — reload = rescan',
         examples: [
-            ['serve the cwd wiki', 'shipkit wiki serve'],
-            ['serve a subtree on a port', 'shipkit wiki serve --root agent --index process.md --port 6162'],
+            ['serve the cwd wiki', 'sk wiki serve'],
+            ['serve a subtree on a port', 'sk wiki serve --root agent --index process.md --port 6162'],
         ],
     })
 
@@ -38,8 +38,8 @@ export class WikiLintCommand extends Command {
         category: 'Wiki',
         description: 'fail on orphan pages and dangling refs (exit 1)',
         examples: [
-            ['lint the cwd wiki', 'shipkit wiki lint'],
-            ['lint a subtree', 'shipkit wiki lint --root agent --index process.md'],
+            ['lint the cwd wiki', 'sk wiki lint'],
+            ['lint a subtree', 'sk wiki lint --root agent --index process.md'],
         ],
     })
 

package/src/cli.ts

@@ -11,7 +11,7 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand } from './cli/cmd_GlobalProcesses.ts'
+import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
@@ -29,6 +29,7 @@ import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
 import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
+import { WhenCommand } from './cli/cmd_When.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
@@ -43,7 +44,7 @@ import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 export function buildCli(): Cli {
     const cli = new Cli({
         binaryLabel: 'shipkit — repo toolkit',
-        binaryName: 'shipkit',
+        binaryName: 'sk',
         binaryVersion: LIB_VERSION,
         enableCapture: true, // console output pipes into the command streams (testable)
         enableColors: true,
@@ -91,10 +92,14 @@ export function buildCli(): Cli {
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
     cli.register(GlobalProcessesCommand)
+    cli.register(GlobalProcessStartCommand)
+    cli.register(GlobalProcessStopCommand)
+    cli.register(GlobalProcessRestartCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
+    cli.register(WhenCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(ConfigKeysCommand)

package/src/collections/checks.ts

@@ -20,6 +20,7 @@ import { rawName, routesToShipkit } from '../core/canonical-scripts.ts'
 import { FLOOR_IDS } from '../core/floor.ts'
 import { FOREVER_MS, formatLine, ttlMsOf } from '../core/wire.ts'
 import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
+import { runsCellsOf } from '../core/runs-matrix.ts'
 import { readLastLines, readRuns, runsPath, type LastLine, type RunRow } from '../ledger/run-log.ts'
 import { checkStatsFor, type CheckStat } from '../ledger/check-stats.ts'
 import { NEGATIVE_TTL_CAP_MS } from '../ledger/world-cache.ts'
@@ -114,6 +115,7 @@ function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat
         description: row.description,
         lastLines: wireLines,
         gate: row.gate,
+        runs: runsCellsOf(row),
         build: row.build,
         blocking: row.blocking,
         advisory,

package/src/collections/collection-types.ts

@@ -7,6 +7,7 @@
 // the docs wiki this lib ships beside.
 
 import type { WhenAt, WhenSource } from '../core/when.ts'
+import type { RunsCells } from '../core/runs-matrix.ts'
 import type { CheckFrom } from '../ledger/gate-checks.ts'
 
 export type NeedSeverity = 'red' | 'yellow'
@@ -22,14 +23,15 @@ export const RUNS_ID = 'runs'
  *  row, the runs page and the to fix list all open the same page by it */
 export const testId = (file: string): string => `test:${file}`
 
-/** where the tree files the test files no check reaches, in both views */
+/** the path segment of a test file no check reaches, where a check id sits
+ *  for the others, so the filter finds a test file by its check */
 export const NO_CHECK = 'in no check'
 
-/** the resource KIND, never the collection it came from: one folder holds
- *  several kinds, which is what makes the path tree worth having. There is no
+/** the resource KIND, never the collection it came from: it decides the
+ *  section a row lives under (hub-app/tree-build.ts KIND_SECTION). There is no
  *  catch all kind: a row belongs to an owner, and what belongs to the hub
  *  itself is its status (serve/hub-problems.ts), never a row */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 
@@ -53,6 +55,9 @@ export type CheckFacts = {
     lastLines: string[]
     /** does `shipkit ci` run it? false = proactive, `shipkit check` only */
     gate: boolean
+    /** every context it runs in and how it caches, as the when page draws
+     *  it (core/runs-matrix.ts) */
+    runs: RunsCells
     /** a BUILD STEP: the gate runs it, the health pass does not (derived from
      *  a floor slot or the repo's `tasks: []`, never declared by a check) */
     build: boolean

package/src/core/canonical-scripts.ts

@@ -30,7 +30,7 @@ export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, strin
     }
 }
 
-// ONE WAY IN (build/shipkit.md): the verification verbs an agent types from
+// ONE WAY IN (build/shipkit/one-way-in.md): the verification verbs an agent types from
 // muscle memory ROUTE to shipkit, so `bun run test` gets the cache and the
 // job attachment without anyone having to remember a rule. The tool body they
 // used to hold moves to `<name>:raw`, which is what shipkit itself runs and

package/src/core/check-runner.ts

@@ -40,15 +40,19 @@ import { machinePool, SLOT_HELD_ENV, takeSlot, type SlotPool } from './slots.ts'
 import { budgetLine, machineLoad } from './budget.ts'
 import { killTree, spawnWithTimeout } from './spawn-timeout.ts'
 import { FOREVER_MS, formatLine, parseWireOutput, type Line } from './wire.ts'
-import { offLine, type WhenDecl } from './when.ts'
+import { offLine, runsIn, type ResolvedRuns, type RunContext } from './runs.ts'
 import { runCheckBody, type CheckDef, type CheckEnv } from '../check.ts'
 import { Ledger, stampCached } from '../ledger/ledger.ts'
-import { attachedStamp } from './outcome-words.ts'
+import { attachedStamp, ranStamp } from './outcome-words.ts'
 import type { RunLog, RunStatus } from '../ledger/run-log.ts'
 import { liveStateOf } from '../ledger/live-runs.ts'
 import { CHECK_ID_ENV } from '../ledger/suite-log.ts'
 import { rememberWorld, replayWorld, worldKeyOf, type WorldCache } from '../ledger/world-cache.ts'
 import { extractProblems } from '../problems/extract.ts'
+
+/** the first line of a check that ran in this run, stamped with its cost. A
+ *  world answer carries its keep in a stamp already, so the cost joins it */
+const ranHere = (l: Line, ms: number): Line => (l.stamp != null && l.stamp.cached !== true ? { ...l, stamp: { ...l.stamp, ranMs: ms } } : { ...l, text: `${l.text} ${ranStamp(ms)}` })
 import { feedsProblemsPane, type Population, type Problem } from '../problems/problem-line.ts'
 
 /** the ceiling a check takes when it names none. A build step's floor
@@ -82,7 +86,8 @@ export type RunnableCheck = {
     blocking: boolean | null
     /** a build step: the gate runs it, the health pass does not */
     build: boolean
-    when: WhenDecl
+    /** every context it runs in, resolved (core/runs.ts) */
+    runs: ResolvedRuns
     deps: string[]
     group: string | null
     timeoutMs: number
@@ -159,8 +164,10 @@ export type RunChecksOpts = {
     root: string
     config: CheckEnv['config']
     audience: Audience
-    /** `release` checks are in at the full tier and out at the quick one */
+    /** the full tests tier: `onFull` decides instead of `onCi` */
     fullTier: boolean
+    /** the release preflight: `onRelease` decides, whatever the tier */
+    release?: boolean
     /** where a `cmd` check's whole output is streamed */
     logDir: string
     /** the world answers' store, null = nothing is remembered by TTL */
@@ -256,10 +263,13 @@ export type Selection = {
     errors: string[]
 }
 
+/** the axis each context reads, as a parked line names it */
+const CTX_AXIS: Record<RunContext, string> = { preCommit: 'onPreCommit', ci: 'onCi', full: 'onFull', release: 'onRelease', health: 'onHealth' }
+
 /** what this run asks about. The audience decides the shape of the question,
  *  `--only` and `--with` name checks past any filter, and OFF is the one word
  *  no flag lifts. */
-export function selectChecks(o: Pick<RunChecksOpts, 'checks' | 'audience' | 'fullTier' | 'skipGroups' | 'onlyIds' | 'withIds' | 'onlyBlocking' | 'buildOnly' | 'exclude' | 'includeProactive'>): Selection {
+export function selectChecks(o: Pick<RunChecksOpts, 'checks' | 'audience' | 'fullTier' | 'release' | 'skipGroups' | 'onlyIds' | 'withIds' | 'onlyBlocking' | 'buildOnly' | 'exclude' | 'includeProactive'>): Selection {
     const errors: string[] = []
     const ids = new Set(o.checks.map((u) => u.id))
     if (ids.size !== o.checks.length) errors.push('duplicate check ids')
@@ -318,26 +328,28 @@ export function selectChecks(o: Pick<RunChecksOpts, 'checks' | 'audience' | 'ful
         if (u.blocking == null) undeclared.push(u.id)
         selected.push(u)
     }
+    // the one context this run asks about: every row declares whether it
+    // runs there (core/runs.ts), and nothing is guessed from its kind
+    const ctx: RunContext = o.audience === 'health' ? 'health' : o.release === true ? 'release' : o.fullTier ? 'full' : 'ci'
     for (const u of o.checks) {
-        // IS IT THIS RUN'S BUSINESS AT ALL? The health pass never builds (a
-        // repo's test suite and its type checker answer "is my change good",
-        // which is the gate's question), the TUI's build panel asks for
-        // nothing else, and a sub-unit release skips what its own gate ran.
-        // A check out of scope here is not even reported as off: it is not part
-        // of this question.
+        // IS IT THIS RUN'S BUSINESS AT ALL? The TUI's build panel asks for
+        // nothing but build steps, and a sub-unit release skips what its own
+        // gate ran. A check out of scope here is not even reported as off: it
+        // is not part of this question.
         if (!named.has(u.id)) {
-            if (o.audience === 'health' && u.build) continue
             if (o.buildOnly === true && !u.build) continue
             if (excluded.has(u.id)) { parked.push({ id: u.id, text: `${u.id} (not part of this release, its own gate covers it)` }); continue }
         }
         // OFF is the one word that means never, past every other flag: a
         // switch a filter can lift is a suggestion
-        if (u.when.at === 'off') { off.push(u); continue }
+        if (u.runs.off != null) { off.push(u); continue }
         if (named.has(u.id)) { take(u); continue }
         if (u.group != null && skipGroups.has(u.group)) { parked.push({ id: u.id, text: `${u.id} (--skip ${u.group})` }); continue }
-        if (o.audience === 'gate') {
-            if (u.when.at === 'health' && o.includeProactive !== true) { parked.push({ id: u.id, text: `${u.id} (health)` }); continue }
-            if (u.when.at === 'release' && !o.fullTier) { parked.push({ id: u.id, text: `${u.id} (release)` }); continue }
+        if (!runsIn(u.runs, ctx)) {
+            // the health pass answers its own question and lists nothing else
+            if (ctx === 'health') continue
+            // release.requireHealthy asks the gate for the health probes too
+            if (!(o.includeProactive === true && u.runs.onHealth && !u.build)) { parked.push({ id: u.id, text: `${u.id} (not ${CTX_AXIS[ctx]})` }); continue }
         }
         if (o.onlyBlocking === true && u.blocking !== true) { if (u.blocking == null) undeclared.push(u.id); nonBlocking.set(u.id, u); continue }
         take(u)
@@ -471,7 +483,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     // OFF, in ONE place: skipped by name, never run, never stored, and the
     // reason printed where the verdict would have been
     for (const u of [...sel.off, ...(sel.offElsewhere ?? [])]) {
-        const line: Line = { kind: 'skip', text: offLine(u.id, u.when) }
+        const line: Line = { kind: 'skip', text: offLine(u.id, u.runs) }
         if (sel.off.includes(u)) emit(line); else (o.detail ?? print)(formatLine(line, color))
         report(u, { id: u.id, status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [line], problems: [], lastLine: line.text, note: 'off', logPath: null })
     }
@@ -566,9 +578,14 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         const ran = u.status === 'pass' || u.status === 'warn' ? testsRan(u.lastLine) : null
         const counted = ran != null && head != null && head.kind === 'ok' && (head.text === u.id || head.text.startsWith(`${u.id} (`))
         const id = counted ? `${u.id} ${ran} test${ran === 1 ? '' : 's'}` : u.id
-        const shown = u.synthetic && !u.replayed && head != null
-            ? [{ ...head, text: `${id} (${(u.ms / 1000).toFixed(1)}s)${u.tail}` }, ...u.lines.slice(1)]
+        const composed = u.synthetic && !u.replayed && head != null
+            ? [{ ...head, text: `${id} ${ranStamp(u.ms)}${u.tail}` }, ...u.lines.slice(1)]
             : counted ? [{ ...head, text: `${id}${head.text.slice(u.id.length)}` }, ...u.lines.slice(1)] : u.lines
+        // every line says where its answer came from: a replay carries its
+        // cached stamp already, so one that ran here says so and what it cost
+        const shown = u.synthetic || u.replayed || u.attached || u.startedAt === 0 || composed[0] == null
+            ? composed
+            : [ranHere(composed[0], u.ms), ...composed.slice(1)]
         // a caller printing its own verdict wants one line per green check and
         // only the warnings of a warned one; a failure prints whole
         const quiet = (l: Line, i: number): boolean =>
@@ -585,7 +602,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         const hit = o.ledger?.replay(u.id)
         if (hit != null) {
             u.replayed = true
-            u.lines = stampCached(hit.lines, hit.measuredMs)
+            u.lines = stampCached(hit.lines, hit.measuredMs, hit.at, clock())
             u.lastLine = hit.lastLine ?? ''
             u.status = hit.status
             // a replay stands for the verdict it replays, findings included:

package/src/core/config-rewrite.ts

@@ -1,14 +1,15 @@
-// THE CONFIG HALF of the SK016 migration, in its own process. Writing the
+// THE CONFIG HALF of the SK016 and SK029 migrations, in its own process. Writing the
 // managed block and reading the result back both LOAD repo.config.ts as a
 // module, which no check context read can stand for, so the fixer reaches it
 // through `c.exec` and the check file itself never imports the loader.
 //
 //   bun config-rewrite.ts <root> '<plan json>'   → one json line on stdout
 //
-// The order is the migration's: the `when` entries first, then each key is
-// dropped only once what leaned on it has a home, then the result is read
-// back through the loader and the previous bytes go back when it does not
-// survive.
+// The order is the migration's: a key the managed block holds (the retired
+// `when`) is dropped first, so the block describes the config again, then the
+// `off` entries are written into the block, then each other key is dropped
+// only once what leaned on it has a home. The result is read back through the
+// loader and the previous bytes go back when it does not survive.
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { atomicWrite } from './locked-write.ts'
@@ -17,10 +18,11 @@ import { writeGateBlock } from './when-block.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
 export type ConfigPlan = {
-    /** check id → `when` value, written into the managed block */
-    when: Record<string, string>
-    /** keys to drop, in order. `afterWhen` drops only once the block took the entries */
-    drop: { key: string; why: string; afterWhen?: boolean }[]
+    /** check id → why it is off, written into the managed block */
+    off: Record<string, string>
+    /** keys to drop, in order. `first` drops before the block is written (a
+     *  key inside it), `afterOff` only once the block took the entries */
+    drop: { key: string; why: string; phase?: 'first' | 'afterOff' }[]
     /** the config's `name` before the rewrite: what the read back must still say */
     name: string
 }
@@ -35,27 +37,38 @@ export type ConfigRewrite = {
 export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<ConfigRewrite> {
     const did: string[] = []
     const hand: string[] = []
-    let whenWritten = false
-    if (Object.keys(plan.when).length > 0) {
+    const path = join(root, 'repo.config.ts')
+    const before = readFileSync(path, 'utf8')
+    const drop = (text: string, d: ConfigPlan['drop'][number]): string => {
+        const next = dropConfigKey(text, d.key)
+        if (next == null) { hand.push(`repo.config.ts \`${d.key}\`: ${d.why}, and the key could not be read mechanically — delete it by hand`); return text }
+        did.push(`repo.config.ts drops \`${d.key}\``)
+        return next
+    }
+    let first = before
+    for (const d of plan.drop.filter((x) => x.phase === 'first')) first = drop(first, d)
+    if (first !== before) atomicWrite(path, first)
+    let offWritten = false
+    if (Object.keys(plan.off).length > 0) {
         try {
-            await writeGateBlock(root, { when: plan.when })
-            whenWritten = true
-            did.push(`${Object.keys(plan.when).length} when entr(ies) written into the managed block`)
+            await writeGateBlock(root, { off: plan.off })
+            offWritten = true
+            did.push(`${Object.keys(plan.off).length} off entr(ies) written into the managed block`)
         } catch (e) {
-            hand.push(`the \`when\` block refused the rewrite (${String(e).slice(0, 160)}) — write ${JSON.stringify(plan.when)} into it by hand`)
+            // a key dropped first held these entries: without the block they
+            // would be gone, so the file goes back as it was
+            if (first !== before) { atomicWrite(path, before); return { did: [], hand, restored: `the managed block refused off ${JSON.stringify(plan.off)}: ${String(e).slice(0, 160)}` } }
+            hand.push(`the managed block refused the rewrite (${String(e).slice(0, 160)}) — write off: ${JSON.stringify(plan.off)} into it by hand`)
         }
     }
-    const path = join(root, 'repo.config.ts')
-    const before = readFileSync(path, 'utf8')
-    let text = before
-    for (const d of plan.drop) {
-        if (d.afterWhen === true && !whenWritten) continue
-        const next = dropConfigKey(text, d.key)
-        if (next == null) hand.push(`repo.config.ts \`${d.key}\`: ${d.why}, and the key could not be read mechanically — delete it by hand`)
-        else { text = next; did.push(`repo.config.ts drops \`${d.key}\``) }
+    const mid = readFileSync(path, 'utf8')
+    let text = mid
+    for (const d of plan.drop.filter((x) => x.phase !== 'first')) {
+        if (d.phase === 'afterOff' && !offWritten) continue
+        text = drop(text, d)
     }
+    if (text !== mid) atomicWrite(path, text)
     if (text !== before) {
-        atomicWrite(path, text)
         try {
             const after = await loadRepoConfig(root, { fresh: true })
             if (after.name !== plan.name) throw new Error(`the config reads as '${String(after.name)}'`)

package/src/core/discover-checks.ts

@@ -110,7 +110,7 @@ export function isLegacyCheckFile(path: string): boolean {
 /** every built-in id, from the file names alone. Sync and import free, so
  *  `defineRepo` can read the namespace at config load. Read once per
  *  process: the toolkit's own files cannot appear mid run, and `defineRepo`
- *  asks for the list once per `when` entry. */
+ *  asks for the list once per `off` entry. */
 let builtinIds: string[] | null = null
 export function builtinCheckIds(): string[] {
     if (builtinIds != null) return builtinIds
@@ -144,6 +144,20 @@ async function load(path: string): Promise<CheckDef | null> {
     }
 }
 
+/** the stand in for a check file that does not load: it fails in every
+ *  context with the load error, so the file cannot drop out of a gate unseen */
+function unloadable(path: string, message: string): CheckDef {
+    return {
+        description: 'the check file loads',
+        blocking: true,
+        runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: false, onClock: false },
+        cache: { by: 'never', why: 'the file does not load' },
+        fix: 'none',
+        applies: 'always',
+        run: (c) => c.fail(`${basename(path)} does not load: ${message.replace(`${path}: `, '')}`, 'shipkit check --fix SK029 ports a retired check file with the values it ran on, and shipkit ci does it in its fix pass'),
+    }
+}
+
 /** every check this repo can run: its own files, plus the toolkit's. Throws
  *  on a registration nobody can act on (a duplicate id, a repo check squatting
  *  the reserved prefix, a built-in with no owner page), so a broken
@@ -170,7 +184,14 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
     const ids = new Set<string>()
     for (const f of [...builtins, ...own, ...units]) {
         const isBuiltin = builtins.includes(f)
-        const def = await load(f)
+        let def: CheckDef | null
+        try {
+            def = await load(f)
+        } catch (e) {
+            // a file that does not load is ONE red row, never a dead inventory:
+            // every other check still runs, and this one says why in every run
+            def = unloadable(f, (e as Error).message)
+        }
         if (def == null) continue
         const rel = isBuiltin ? null : relative(root, f).replace(/\\/g, '/')
         const fallback = isBuiltin

package/src/core/legacy-shapes.ts

@@ -22,6 +22,7 @@ import { fallbackNames, isCheckFilePath, readLegacyCheck, type LegacyCheck } fro
 import type { ScanCtx } from './check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { descriptionProblem, type TaskDef } from '../check.ts'
+import { deriveExplicit, type Derived } from './port-check-file.ts'
 
 /** the narrow module every rewritten file imports `check` from, and the ONE
  *  spelling: the barrel costs 400ms of module load and discovery imports
@@ -130,16 +131,34 @@ export const PLACEHOLDER_MARK = 'TODO: state what must be true'
  *  drops none of them. */
 export function scriptPort(read: LegacyCheck, fallbackBlocking: boolean | undefined): string {
     const blocking = read.blocking ?? fallbackBlocking
+    // what the ported `run` body resolves to: the script's own declarations,
+    // read as the gate read them, on a body keyed on what it reads
+    const d = explicitOf(deriveExplicit({
+        when: read.gate ? null : 'health',
+        build: false,
+        body: 'run',
+        ...(read.inputs != null ? { inputs: `[${read.inputs.map(q).join(', ')}]` } : {}),
+        ...(read.ttl != null ? { ttl: q(read.ttl) } : {}),
+        ...(read.never != null ? { never: q(read.never) } : {}),
+        repair: false,
+        rawAccess: null,
+    }, q))
     const fields = [
         blocking == null ? 'blocking: <true | false, it declares none>' : `blocking: ${blocking}`,
-        ...(read.inputs != null ? [`inputs: [${read.inputs.map(q).join(', ')}]`] : []),
-        ...(read.ttl != null ? [`ttl: ${q(read.ttl)}`] : []),
-        ...(read.never != null ? [`never: ${q(read.never)}`] : []),
-        ...(read.gate ? [] : [`when: 'health'`]),
+        `runs: ${d.runs}`,
+        `cache: ${d.cache}`,
+        `fix: ${q(d.fix)}`,
+        `applies: ${d.applies}`,
     ]
     return `a check script, run as its own process: port it by hand into \`export default check({ description, ${fields.join(', ')}, run: (c) => … })\`, each print a call on c (c.ok, c.warn, c.fail)`
 }
 
+/** a derivation that cannot fail on what a script or a task can declare */
+function explicitOf(d: Derived | { error: string }): Derived {
+    if ('error' in d) throw new Error(`the legacy declaration has no explicit form: ${d.error}`)
+    return d
+}
+
 /** the check file a task's argv runs through bun, `bun <file>` or `bun run
  *  <file>`, relative, `./` prefixed or absolute, resolved against the task's
  *  cwd. `rest` is what the argv passes after the file: a task that passes its
@@ -159,16 +178,24 @@ export function checkFileRunBy(t: Pick<TaskDef, 'cmd' | 'cwd'>, root: string): {
  *  always was: the gate runs it and the health pass leaves it out. */
 export function taskCheckSource(t: TaskDef, root: string): string {
     const own = t.description != null && descriptionProblem(t.description) == null ? t.description.trim() : null
-    const fields = [`id: ${q(t.id)},`, `description: ${q(own ?? descriptionPlaceholder())},`, 'blocking: true,', 'build: true,', `cmd: [${t.cmd!.map(q).join(', ')}],`]
+    // where it ran and how it was kept, as the gate and the planner read a
+    // task: an optIn one ran only by name
+    const d = explicitOf(deriveExplicit({
+        when: t.optIn === true ? 'health' : null,
+        build: true,
+        body: 'cmd',
+        ...(t.inputs != null ? { inputs: `[${t.inputs.map(q).join(', ')}]` } : {}),
+        ...(t.ttl != null ? { ttl: q(t.ttl) } : {}),
+        ...(t.never != null ? { never: q(t.never) } : {}),
+        repair: false,
+        rawAccess: null,
+    }, q))
+    const fields = [`id: ${q(t.id)},`, `description: ${q(own ?? descriptionPlaceholder())},`, 'blocking: true,', 'build: true,', `runs: ${d.runs},`, `cache: ${d.cache},`, `fix: ${q(d.fix)},`, `applies: ${d.applies},`, `cmd: [${t.cmd!.map(q).join(', ')}],`]
     if (t.deps != null && t.deps.length > 0) fields.push(`deps: [${t.deps.map(q).join(', ')}],`)
-    if (t.inputs != null) fields.push(`inputs: [${t.inputs.map(q).join(', ')}],`)
-    if (t.ttl != null) fields.push(`ttl: ${q(t.ttl)},`)
-    if (t.never != null) fields.push(`never: ${q(t.never)},`)
     if (t.group != null) fields.push(`group: ${q(t.group)},`)
     if (t.timeoutMs != null) fields.push(`timeoutMs: ${t.timeoutMs},`)
     if (t.env != null) fields.push(`env: { ${Object.entries(t.env).map(([k, v]) => `${q(k)}: ${q(v)}`).join(', ')} },`)
     if (t.cwd != null) fields.push(`cwd: ${q(t.cwd)},`)
-    if (t.optIn === true) fields.push(`when: 'health',`)
     const w = checkWrapper(root)
     return [...w.head, w.open, ...fields.map((f) => `    ${f}`), w.close, ''].join('\n')
 }
@@ -189,6 +216,8 @@ export function dropConfigKey(text: string, key: string): string | null {
     const start = at[0]!
     const end = statementEnd(lines, start)
     let from = start
-    while (from > 0 && lines[from - 1]!.trim().startsWith('//')) from--
+    // the comment block above the key goes with it, never a managed block
+    // marker (`// >>> shipkit …`): the key may be the first line inside one
+    while (from > 0 && lines[from - 1]!.trim().startsWith('//') && !/^\/\/ (>>>|<<<) shipkit/.test(lines[from - 1]!.trim())) from--
     return [...lines.slice(0, from), ...lines.slice(end + 1)].join('\n')
 }

package/src/core/one-way-in-policy.ts

@@ -1,4 +1,4 @@
-// ONE WAY IN, the harness half (build/shipkit.md). The package.json half
+// ONE WAY IN, the harness half (build/shipkit/one-way-in.md). The package.json half
 // (rule SK001) routes `bun run test` into shipkit, but `bun test` is a bun
 // BUILTIN: no script can intercept it, so a package.json alone leaves the
 // reflex wide open. Claude Code permission rules can close it.
@@ -76,7 +76,7 @@ export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
 export function refusal(r: RawRunner, segment?: string): string {
     const alt = r.iterate == null ? '' : `, or \`${r.iterate}\` to iterate on ONE suite while you fix a bug`
     const which = segment == null || segment.trim() === '' || segment.trim() === r.head ? '' : ` (refused on \`${segment.trim().slice(0, 80)}\`)`
-    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit.md, ONE WAY IN).`
+    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit/one-way-in.md).`
 }
 
 /** shell wrappers that do not change what is being run */

package/src/core/outcome-words.ts

@@ -38,8 +38,24 @@ export const checkVerdictWords = (status: 'pass' | 'warn' | 'fail' | 'skip' | nu
             : status === 'skip' ? 'skipped'
                 : status === 'pass' ? (o.replayed ? `passed, ${CACHED}` : 'passed') : 'never ran here'
 
-/** the stamp on the first line of a cached check: `(cached, 5.6s saved)` */
-export const cachedStamp = (savedMs: number): string => `(${CACHED}, ${(savedMs / 1000).toFixed(1)}s saved)`
+/** a span in its one biggest unit: `45s`, `12m`, `3h`, `2d` */
+export function spanShort(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** what a run cost: `12ms` under a second, `6.4s` past it */
+export const costShort = (ms: number): string => (ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : `${(ms / 1000).toFixed(1)}s`)
+
+/** the stamp on the first line of a cached check: how old the answer is and
+ *  what measuring it cost, `(cached, 3h old, 5.6s saved)` */
+export const cachedStamp = (savedMs: number, ageMs: number): string => `(${CACHED}, ${spanShort(ageMs)} old, ${costShort(savedMs)} saved)`
+
+/** the stamp on the first line of a check that ran in this run: `(ran 6.4s)` */
+export const ranStamp = (ms: number): string => `(${RAN} ${costShort(ms)})`
 
 /** the stamp on the first line of an attached check */
 export const attachedStamp = (pid: number, ranMs: number): string => `(${ATTACHED} to pid ${pid}, ${RAN} there in ${(ranMs / 1000).toFixed(1)}s)`