rvlib-shipkit 1.3.0 → 1.5.0

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
@@ -56,6 +60,10 @@ import { feedsProblemsPane, type Population, type Problem } from '../problems/pr
  *  about the world. */
 export const CHECK_TIMEOUT_MS = 120_000
 
+/** the most findings a failed build step keeps beside its headline: a tool
+ *  that prints a wall of them is read in its log */
+const MAX_EXTRA = 20
+
 /** epoch ms that never goes backwards inside one process, whole numbers so a
  *  row's `at - ms` is its start exactly: the wall clock can step back (an NTP
  *  correction), and a check stamped before an earlier one ended makes the
@@ -78,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
@@ -155,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 */
@@ -252,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')
@@ -314,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)
@@ -431,6 +447,9 @@ type Live = RunnableCheck & CheckResult & {
     /** what the headline carries after the id: a failure's last line, or the
      *  reason it never ran */
     tail: string
+    /** a failed build step's other findings, the wire lines its tool printed
+     *  beside the one the headline carries */
+    extra: Line[]
 }
 
 export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
@@ -454,14 +473,17 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             blocking: u.blocking, advisory: r.advisory, lines: r.lines, problems: r.problems, logPath: r.logPath, lastLine: r.lastLine, note: r.note, attached,
         })
         // an attached check is filed as a replay: it measured nothing, and a
-        // row carrying its wait would read as a check running in this process
-        o.log?.add({ id: u.id, status: r.status, ms: r.ms, replayed: r.replayed || attached, lines: r.lines, at })
+        // row carrying its wait would read as a check running in this process.
+        // A non-blocking failure is filed as the warning the gate printed, so
+        // no surface reading the record paints red what the gate called orange
+        const filed = r.status === 'fail' && r.advisory ? 'warn' : r.status
+        o.log?.add({ id: u.id, status: filed, ms: r.ms, replayed: r.replayed || attached, lines: r.lines, at })
     }
 
     // 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 })
     }
@@ -476,7 +498,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const runDir = openRunDir(o.logDir)
     const checks: Live[] = sel.selected.map((u) => ({
         ...u,
-        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, synthetic: false, tail: '',
+        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, synthetic: false, tail: '', extra: [],
         logPath: u.body.cmd != null ? join(runDir, `${u.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
     }))
     const selectedIds = new Set(checks.map((u) => u.id))
@@ -556,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 =>
@@ -575,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:
@@ -670,14 +697,25 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         u.problems = findings(u, u.lines, r.out)
         const lastFail = u.lines.filter((l) => l.kind === 'fail').at(-1)
         if (lastFail != null) u.lastLine = lastFail.text.slice(0, 200)
+        // a tool that speaks the wire (the suite runner) ends on its FAIL
+        // lines, and the headline carries only the last one. Only that closing
+        // block is its report: a wire line earlier in the log is some test's
+        // own output
+        if (u.build && u.status === 'fail') {
+            const parsed = parseWireOutput(r.out)
+            let i = parsed.length
+            while (i > 0 && (parsed[i - 1]!.kind === 'fail' || parsed[i - 1]!.kind === 'fix-fail')) i--
+            u.extra = parsed.slice(i).filter((l) => !(l.kind === 'fail' && `FAIL: ${l.text}` === u.lastLine)).slice(-MAX_EXTRA)
+        }
     }
 
     /** a check that printed nothing of its own still has to report that it
      *  ran: the verdict, its name, and (at print time) what it cost */
     const headlineOf = (u: Live): void => {
         u.synthetic = true
-        u.tail = u.status === 'fail' ? (u.lastLine === '' ? '' : ` — ${u.lastLine}`) : u.status === 'skip' ? (u.note === '' ? '' : ` (${u.note})`) : ''
-        u.lines = [{ kind: u.status === 'fail' ? 'fail' : u.status === 'skip' ? 'skip' : 'ok', text: `${u.id}${u.tail}` }]
+        const more = u.extra.filter((l) => l.kind === 'fail').length
+        u.tail = u.status === 'fail' ? (u.lastLine === '' ? '' : ` — ${u.lastLine}${more > 0 ? ` (+${more} more below)` : ''}`) : u.status === 'skip' ? (u.note === '' ? '' : ` (${u.note})`) : ''
+        u.lines = [{ kind: u.status === 'fail' ? 'fail' : u.status === 'skip' ? 'skip' : 'ok', text: `${u.id}${u.tail}` }, ...u.extra]
     }
 
     /** what an attached asker adopts: the verdict and the lines BEFORE this

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

@@ -56,20 +56,23 @@ export type DiscoveredCheck = {
     from: CheckFrom
 }
 
-function walk(dir: string, out: string[], suffix = SUFFIX): void {
+function walk(dir: string, out: string[], suffix = SUFFIX, dirs?: string[]): void {
+    dirs?.push(dir)
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
     for (const e of entries) {
         if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix)
+            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix, dirs)
         } else if (e.name.endsWith(suffix)) out.push(join(dir, e.name))
     }
 }
 
-/** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted */
-export function repoUnitFiles(root: string): string[] {
+/** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted.
+ *  `dirs` collects every dir the walk read: a file added to one moves its
+ *  mtime, which is how a reader tells the list moved without walking again */
+export function repoUnitFiles(root: string, dirs?: string[]): string[] {
     const out: string[] = []
-    walk(root, out, UNIT_SUFFIX)
+    walk(root, out, UNIT_SUFFIX, dirs)
     return out.sort()
 }
 
@@ -107,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
@@ -141,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
@@ -167,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/layout.ts

@@ -32,6 +32,8 @@ export const LAYOUT = {
     reviews: sk('reviews'),
     // scratch: plans, logs, leases, detached runs, screenshots
     tmp: sk('tmp'),
+    // built app bundles, one per global process opened as an app (home/gui-app.ts)
+    wrapper: sk('wrapper'),
     // generated on every run
     status: sk('STATUS.md'),
     statusFull: sk('STATUS.full.md'),

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