rvlib-shipkit 0.38.1 → 1.0.0

package/src/contracts/manifests/itch.contract.ts

@@ -1,30 +1,27 @@
-// normative WHAT for .rv-itch/ — the WHY + workflow live in the sibling page.
+// normative WHAT for .shipkit/itch/ — the WHY + workflow live in the sibling page.
 import { custom, defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
 
 export default defineContract({
     venue: 'itch',
-    dir: '.rv-itch',
+    dir: '.shipkit/itch',
     owner: 'distribute/itch.md',
     appliesTo: 'declared',
-    detect: [script('^(up|push):itch$'), fileContains('deploy.sh', 'butler push'), dirExists('.rv-itch')],
+    detect: [script('^(up|push):itch$'), fileContains('deploy.sh', 'butler push'), dirExists('.shipkit/itch')],
     artifacts: [
         // one AI-disclosure wording everywhere — page.md is its canonical home
-        md('.rv-itch/page.md', { mustContain: ['## AI disclosure'] }),
+        md('.shipkit/itch/page.md', { mustContain: ['## AI disclosure'] }),
         // every field of itch's create-project form, answered and ready to
         // paste — the listing is a browser-only act, so the artifact IS the
         // handoff (references/listing.template.md is the fill-in copy)
-        md('.rv-itch/listing.md', { mustContain: ['## Title', '## Short description or tagline', '## Classification', '## Genre', '## Tags', '## Visibility'] }),
+        md('.shipkit/itch/listing.md', { mustContain: ['## Title', '## Short description or tagline', '## Classification', '## Genre', '## Tags', '## Visibility'] }),
         // headings alone would pass the TEMPLATE copied in verbatim, and this
         // file exists to be pasted with no decision left in it
-        custom('.rv-itch/listing.md answered', (env) => {
-            const p = join(env.root, '.rv-itch/listing.md')
-            if (!existsSync(p)) return []
-            const text = readFileSync(p, 'utf8')
+        custom('.shipkit/itch/listing.md answered', (env) => {
+            const text = env.read('.shipkit/itch/listing.md')
+            if (text == null) return []
             const out: string[] = []
             const left = [...text.matchAll(/<[a-z][^<>\n]{2,60}>/g)].map((m) => m[0])
-            if (left.length > 0) out.push(`.rv-itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`)
+            if (left.length > 0) out.push(`.shipkit/itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`)
             // a heading with an EMPTY body is an unanswered field wearing no
             // placeholder (prose-level open decisions stay a human read).
             // fenced blocks stripped first (a ## inside one is not a field),
@@ -37,11 +34,11 @@ export default defineContract({
                     return !inline && body.every((l) => l.trim() === '')
                 })
                 .map((s) => s.split('\n')[0]!.trim())
-            if (empty.length > 0) out.push(`.rv-itch/listing.md field(s) with no answer under the heading: ${empty.slice(0, 3).join(', ')}${empty.length > 3 ? ' …' : ''}`)
+            if (empty.length > 0) out.push(`.shipkit/itch/listing.md field(s) with no answer under the heading: ${empty.slice(0, 3).join(', ')}${empty.length > 3 ? ' …' : ''}`)
             return out
         }),
         // itch DISPLAYS 630x500 and accepts larger — atLeast, never exact-size
-        png('.rv-itch/cover.png', 630, 500, { atLeast: true }),
-        glob('.rv-itch/screenshots/*.png', { min: 3 }),
+        png('.shipkit/itch/cover.png', 630, 500, { atLeast: true }),
+        glob('.shipkit/itch/screenshots/*.png', { min: 3 }),
     ],
 })

package/src/contracts/manifests/social.contract.ts

@@ -1,18 +1,18 @@
-// normative WHAT for .rv-social/ (posts ONLY — the Discord server contract is
+// normative WHAT for .shipkit/social/ (posts ONLY — the Discord server contract is
 // discord.contract.ts). Declared = the repo config lists social channels.
 import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'social',
-    dir: '.rv-social',
+    dir: '.shipkit/social',
     owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
-    detect: [dirExists('.rv-social')],
+    detect: [dirExists('.shipkit/social')],
     artifacts: [
         custom('declared-channel-dirs', (env) =>
             env.social
-                .filter((ch) => !env.exists(`.rv-social/${ch}`))
-                .map((ch) => `.rv-social/${ch}/ missing — declared social channel '${ch}' has no post folder`),
+                .filter((ch) => !env.exists(`.shipkit/social/${ch}`))
+                .map((ch) => `.shipkit/social/${ch}/ missing — declared social channel '${ch}' has no post folder`),
         ),
     ],
 })

package/src/contracts/manifests/steam.contract.ts

@@ -1,28 +1,28 @@
-// normative WHAT for .rv-steam/ — the WHY + workflow live in the sibling page.
+// normative WHAT for .shipkit/steam/ — the WHY + workflow live in the sibling page.
 // Capsule sizes as of 2026-07 — Valve churns them: re-verify at use, bump here.
 import { defineContract, dir, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'steam',
-    dir: '.rv-steam',
+    dir: '.shipkit/steam',
     owner: 'distribute/steam.md',
     appliesTo: 'declared',
-    detect: [script('^(up|push):steam$'), fileContains('deploy.sh', 'run_app_build'), dirExists('.rv-steam')],
+    detect: [script('^(up|push):steam$'), fileContains('deploy.sh', 'run_app_build'), dirExists('.shipkit/steam')],
     artifacts: [
-        // store.md carries the same AI-disclosure wording as .rv-itch/page.md
-        md('.rv-steam/store.md', { mustContain: ['## AI disclosure'] }),
-        png('.rv-steam/capsules/main.png', 1232, 706),
-        png('.rv-steam/capsules/header.png', 920, 430),
-        png('.rv-steam/capsules/small.png', 462, 174),
-        png('.rv-steam/capsules/vertical.png', 748, 896),
-        png('.rv-steam/capsules/library.png', 600, 900),
-        png('.rv-steam/capsules/library-hero.png', 3840, 1240),
-        png('.rv-steam/capsules/library-logo.png', 1280, 720),
-        png('.rv-steam/capsules/community-icon.png', 184, 184),
+        // store.md carries the same AI-disclosure wording as .shipkit/itch/page.md
+        md('.shipkit/steam/store.md', { mustContain: ['## AI disclosure'] }),
+        png('.shipkit/steam/capsules/main.png', 1232, 706),
+        png('.shipkit/steam/capsules/header.png', 920, 430),
+        png('.shipkit/steam/capsules/small.png', 462, 174),
+        png('.shipkit/steam/capsules/vertical.png', 748, 896),
+        png('.shipkit/steam/capsules/library.png', 600, 900),
+        png('.shipkit/steam/capsules/library-hero.png', 3840, 1240),
+        png('.shipkit/steam/capsules/library-logo.png', 1280, 720),
+        png('.shipkit/steam/capsules/community-icon.png', 184, 184),
         // .ico, dims not png-parseable — presence-checked only
-        file('.rv-steam/capsules/client-icon.ico'),
-        glob('.rv-steam/screenshots/*.png', { min: 5, width: 1920, height: 1080 }),
+        file('.shipkit/steam/capsules/client-icon.ico'),
+        glob('.shipkit/steam/screenshots/*.png', { min: 5, width: 1920, height: 1080 }),
         // vdf scripts only exist once the appid does — nag, don't block
-        dir('.rv-steam/vdf', { warnOnly: true }),
+        dir('.shipkit/steam/vdf', { warnOnly: true }),
     ],
 })

package/src/contracts/run-contracts.ts

@@ -2,7 +2,7 @@
 // behind cmd_Contracts; venue deploy scripts run it before any upload.
 import { loadRepoConfig } from '../repo-config.ts'
 import { CheckCtx } from '../core/check-ctx.ts'
-import { contractsFulfillness } from '../rules/SK002-contracts-fulfillness.ts'
+import { contractsFulfillness } from '../checks/SK002-contracts-fulfillness.check.ts'
 import { activeContracts, applyContractsResult, contractsConfigFrom } from './apply-contracts.ts'
 import { evaluateContracts } from './contracts-engine.ts'
 import { formatLine } from '../core/wire.ts'
@@ -24,14 +24,15 @@ export async function runContracts(root: string, o: ContractsOpts = {}): Promise
         manifests = manifests.filter((m) => m.venue === o.venue)
         if (manifests.length === 0) { printErr(`FAIL: unknown venue '${o.venue}'`); return 1 }
     }
-    const r = await evaluateContracts(manifests, contractsConfigFrom(c, root))
+    const disk = CheckCtx.open({ root, config: c })
+    const r = await evaluateContracts(manifests, contractsConfigFrom(c, disk), disk)
     if (o.json === true) {
         print(JSON.stringify({ ok: r.exitCode === 0, outcomes: r.outcomes }))
         return r.exitCode
     }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     // same SK002-tagged rendering as `shipkit check` and the ci task
-    const t = new CheckCtx(new Map())
+    const t = new CheckCtx()
     applyContractsResult(t, r, contractsFulfillness)
     for (const l of t.lines) print(formatLine(l, color))
     return r.exitCode

package/src/core/attach.ts

@@ -0,0 +1,96 @@
+// JOB ATTACHMENT: two processes asking ONE question (same check, same cache
+// key) get ONE measurement. The first takes `<slot>.lock` and measures, every
+// later asker waits on that lock and adopts the answer it left in
+// `<slot>.json`. The lock is the mutate lease (locked-write.ts), so a holder
+// that died is stolen and a wedged one is bounded, with no second mechanism.
+//
+// The one constraint a reader breaks first: an answer is adopted only when it
+// FINISHED after the asker asked, i.e. it was in flight, and never by an asker
+// that stole the lock: it just called that run gone, so it measures itself
+// rather than print a steal from a pid and then an attach to the same pid. The file is never a
+// cache: a red it holds must not replay for a later asker (the ledger replays
+// greens only), and a green reaches later askers through the ledger, after
+// its post-run re-hash.
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { dirname } from 'path'
+import { thisInstance } from './instance.ts'
+import { atomicWrite, withMutateLease } from './locked-write.ts'
+
+type Shared<T> = { pid: number; nonce?: string; finishedAt: number; value: T }
+
+export type ShareOutcome<T> =
+    | { kind: 'measured'; value: T }
+    | { kind: 'attached'; value: T; pid: number }
+    /** the wait was stopped (an interrupt, a bail): nothing ran */
+    | { kind: 'aborted' }
+    /** the holder outlived the wait bound: this asker measured anyway */
+    | { kind: 'overlapped'; value: T; warn: string }
+
+export type ShareOpts = {
+    /** when this asker asked: only an answer finished after it is adopted */
+    askedAt: number
+    label?: string
+    print?: (line: string) => void
+    /** the wait bound. Past the holder's own ceiling, so a live holder always
+     *  finishes first. */
+    maxWaitMs?: number
+    pollMs?: number
+    onWait?: (pid: number) => void
+    abort?: () => boolean
+}
+
+/** how long an answer file stays on disk. Only an in flight asker can adopt
+ *  one, so this is housekeeping, not a validity window. */
+const KEEP_MS = 60 * 60 * 1000
+
+const readShared = <T>(path: string): Shared<T> | null => {
+    try {
+        const s = JSON.parse(readFileSync(path, 'utf8')) as Partial<Shared<T>>
+        return typeof s.pid === 'number' && typeof s.finishedAt === 'number' && 'value' in s ? (s as Shared<T>) : null
+    } catch { return null }
+}
+
+const sweep = (dir: string, now: number): void => {
+    try {
+        for (const f of readdirSync(dir)) {
+            if (f.endsWith('.lock')) continue
+            const p = `${dir}/${f}`
+            try { if (statSync(p).mtimeMs < now - KEEP_MS) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+        }
+    } catch { /* housekeeping never fails a run */ }
+}
+
+/** run `body` once per in flight key. `share: false` from the body (it was
+ *  killed, it never reached its subject) leaves no answer, so a waiter
+ *  measures for itself rather than adopting a non answer. */
+export async function shareRun<T>(slot: string, o: ShareOpts, body: () => Promise<{ value: T; share: boolean }>): Promise<ShareOutcome<T>> {
+    const answer = `${slot}.json`
+    mkdirSync(dirname(slot), { recursive: true })
+    let stole = false
+    const leased = await withMutateLease(slot, {
+        label: o.label ?? 'shared run',
+        print: o.print,
+        maxWaitMs: o.maxWaitMs,
+        pollMs: o.pollMs,
+        announceMs: Number.POSITIVE_INFINITY,
+        onWait: (h) => o.onWait?.(h.pid),
+        onSteal: () => { stole = true },
+        abort: o.abort,
+    }, async (): Promise<ShareOutcome<T>> => {
+        const prior = readShared<T>(answer)
+        if (!stole && prior != null && prior.finishedAt >= o.askedAt) return { kind: 'attached', value: prior.value, pid: prior.pid }
+        const r = await body()
+        const now = Date.now()
+        if (r.share) {
+            try { atomicWrite(answer, JSON.stringify({ ...thisInstance(), finishedAt: now, value: r.value } satisfies Shared<T>)) } catch {
+                // an answer nobody can adopt costs the waiters a measurement, never a verdict
+            }
+        }
+        sweep(dirname(slot), now)
+        return { kind: 'measured', value: r.value }
+    })
+    if (leased.ok) return leased.value
+    if (leased.aborted === true) return { kind: 'aborted' }
+    const r = await body()
+    return { kind: 'overlapped', value: r.value, warn: leased.warn }
+}

package/src/core/canonical-scripts.ts

@@ -74,3 +74,28 @@ export function inferBin(scripts: Record<string, string>): string | undefined {
     }
     return undefined
 }
+
+/** what fills one floor slot, as far as package.json and `defaults` say: the
+ *  decision core/floor.ts turns into a task, and rule SK018 reads to know what
+ *  the root's tests run. `none` leaves the slot to a built-in, if it has one */
+export type SlotBody =
+    | { kind: 'off' }
+    | { kind: 'override' }
+    | { kind: 'script'; name: string; body: string }
+    | { kind: 'routed-empty' }
+    | { kind: 'none' }
+
+export function slotBody(id: string, override: { cmd?: unknown; logic?: unknown } | false | undefined, scripts: Record<string, string>): SlotBody {
+    if (override === false) return { kind: 'off' }
+    // a FULL override brings its own body and replaces the slot. One that
+    // brings none DECORATES whatever fills it
+    if (override != null && (override.cmd != null || override.logic != null)) return { kind: 'override' }
+    // ONE WAY IN: `<id>` routes to `shipkit ci --only <id>`, so the TOOL body
+    // lives at `<id>:raw`. Running the routed script would spawn the gate from
+    // inside itself, forever
+    const raw = scripts[rawName(id)]
+    if (raw != null) return { kind: 'script', name: rawName(id), body: raw }
+    const own = scripts[id]
+    if (own != null && !routesToShipkit(own)) return { kind: 'script', name: id, body: own }
+    return own != null ? { kind: 'routed-empty' } : { kind: 'none' }
+}

package/src/core/check-ctx.ts

@@ -1,13 +1,43 @@
-// CheckCtx — the per-check handle a probe's logic receives: outcome lines
-// (wire.ts kinds), guarded fetch/exec helpers, resolved-tool lookup.
+// CheckCtx — the ONE parameter a check body receives, and its only door to the
+// repo. Four parts:
+//
+//   report  c.ok / note / warn / fail / unreachable, the wire lines (wire.ts)
+//   where   c.root, c.config, c.frozen
+//   reads   c.read / json / exists / isLink / list / entries, each recorded with what it saw, and
+//           c.use(scan) for a scan every check of the pass shares (scan.ts)
+//   world   c.exec / fetch / tool, which no read set can describe
+//   writes  c.write / remove, for a `fix`
+//
+// What a body read is therefore KNOWN rather than declared: a `run` check that
+// declares no cache population is cached on its recorded reads
+// (ledger/ledger.ts), and one that reaches the world through exec, fetch or
+// tool marks its answer untracked, so it is never stored on a read set that
+// cannot describe it. A body whose code reaches the disk around `c` is never
+// keyed on its reads at all (core/raw-access.ts, checked at discovery).
+//
+// A context with no pass reports and reaches the world, and a repo read there
+// throws rather than guess a root.
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from './locked-write.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
+import { blobOid, dirEntries, entriesHash, isLinkAt, kindOf, listingHash, Reads, type DirEntry } from './read-set.ts'
+import { CheckPass } from './check-pass.ts'
+import { normalizeInput, WHOLE_TREE } from '../ledger/git-scan.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { Scan } from '../scan.ts'
 import type { Line } from './wire.ts'
 
-// thrown by t.fetch on 429 — the suite converts it to WARN, never FAIL
-export class RateLimited extends Error {}
-// thrown by t.tool when its defineRequiredTool check failed — that check
-// already FAILed the run; the dependent check notes it skipped, no double FAIL
-export class ToolUnresolved extends Error {}
+// thrown by t.fetch on 429: no answer, so the body runner (check.ts
+// runCheckBody) reports it as unreachable, never as a FAIL. It knows it by
+// name, so the narrow check module never loads this one
+export class RateLimited extends Error {
+    override name = 'RateLimited'
+}
+
+/** what a shared scan may do: know where it is and read. It reports nothing
+ *  and reaches no world, which is what lets its reads stand for its value. */
+export type ScanCtx = Pick<CheckCtx, 'root' | 'config' | 'frozen' | 'read' | 'bytes' | 'json' | 'exists' | 'isLink' | 'list' | 'entries' | 'use'>
 
 export class CheckCtx {
     lines: Line[] = []
@@ -16,12 +46,28 @@ export class CheckCtx {
     /** THIS RUN PRODUCED NO ANSWER: the probe could not run at all (network
      *  down, no cred, rate limited, tool missing). Distinct from a probe that
      *  ran and came back bad, which IS an answer. The cache replays answers
-     *  and never replays their absence (check-suite.ts, the measured-negative
+     *  and never replays their absence (ledger/world-cache.ts, the measured-negative
      *  rule). Set it whenever the reason a check is not green is that it never
      *  reached the thing it was asking about. */
     unmeasured = false
-    constructor(private toolPaths: Map<string, string>) {}
+    /** every repo read this context made, with what it saw */
+    readonly reads = new Reads()
+    /** why the reads cannot describe this answer (it reached the world), null
+     *  while they can */
+    untracked: string | null = null
 
+    constructor(
+        /** the runner pass this body runs in. Absent for a context that only
+         *  reports and reaches the world */
+        readonly pass: CheckPass | null = null,
+    ) {}
+
+    /** a context over one repo, outside any runner: a fixer, a test, a tool */
+    static open(where: { root: string; config: RepoConfig }): CheckCtx {
+        return new CheckCtx(new CheckPass(where.root, where.config))
+    }
+
+    // ── report ────────────────────────────────────────────────────────────
     ok(msg: string): void { this.lines.push({ kind: 'ok', text: msg }) }
     note(msg: string): void { this.lines.push({ kind: 'note', text: msg }) }
     /** a WARN that came back from something we could not reach — no answer, so
@@ -41,15 +87,155 @@ export class CheckCtx {
         if (fix != null) this.lines.push({ kind: 'fix-fail', text: fix })
     }
 
-    // path resolved by an earlier defineRequiredTool check (declaration order)
-    tool(name: string): string {
-        const p = this.toolPaths.get(name)
-        if (p == null) throw new ToolUnresolved(`tool '${name}' unresolved — its defineRequiredTool check failed or is declared after this check`)
+    // ── where ─────────────────────────────────────────────────────────────
+    private repo(what: string): CheckPass {
+        if (this.pass == null) throw new Error(`c.${what} needs a repo, and this context has no pass: it only reports and reaches the world`)
+        return this.pass
+    }
+    get root(): string { return this.repo('root').root }
+    /** the repo's config. Reading it records repo.config.ts and every repo
+     *  module it imports, so a config edit re-asks every check that consulted
+     *  it and none that did not */
+    get config(): RepoConfig {
+        const p = this.repo('config')
+        const deps = p.configReads()
+        for (const [f, oid] of deps.files) this.reads.file(f, oid)
+        if (deps.untracked != null && this.untracked == null) {
+            this.untrack(deps.untracked)
+            this.note(`not cached: ${deps.untracked}`)
+        }
+        return p.config
+    }
+    /** a report only run: a check that rewrites the repo must not */
+    get frozen(): boolean { return this.repo('frozen').frozen }
+    /** the fix pointer a failing body with none of its own gets: an owner
+     *  that is a file of this repo (a repo check's own path) as it stands, a
+     *  page of the docs wiki after `docsBase`. The runner's line, never the
+     *  body's, so nothing here is recorded as a read */
+    ownerPointer(owner: string): string {
+        const inRepo = this.pass != null && owner !== '' && existsSync(join(this.pass.root, owner))
+        return inRepo ? owner : `${this.pass?.config.docsBase ?? ''}${owner}`
+    }
+
+    // ── reads, recorded ───────────────────────────────────────────────────
+    private rel(path: string): string {
+        const p = normalizeInput(path)
+        if (p === WHOLE_TREE) throw new Error(`'${path}' is the repo root, not a file`)
         return p
     }
+    /** the text of a repo-relative file, null when there is none */
+    read(path: string): string | null {
+        return this.bytes(path)?.toString('utf8') ?? null
+    }
+    /** the raw bytes of a repo-relative file (an image, a binary), null when
+     *  there is none. Recorded exactly like `read` */
+    bytes(path: string): Buffer | null {
+        const p = this.rel(path)
+        let bytes: Buffer
+        try {
+            bytes = readFileSync(join(this.repo('read').root, p))
+        } catch (e) {
+            const code = (e as { code?: string }).code
+            if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'EISDIR') throw e
+            this.reads.file(p, null)
+            return null
+        }
+        this.reads.file(p, blobOid(bytes))
+        return bytes
+    }
+    /** a repo-relative json file, parsed. null when absent, and a parse error
+     *  throws naming the file */
+    json<T = unknown>(path: string): T | null {
+        const text = this.read(path)
+        if (text == null) return null
+        try {
+            return JSON.parse(text) as T
+        } catch (e) {
+            throw new Error(`${path} is not valid json (${String(e).slice(0, 120)})`)
+        }
+    }
+    /** whether something stands at this repo-relative path, or only a file,
+     *  or only a dir, when `kind` says which */
+    exists(path: string, kind?: 'file' | 'dir'): boolean {
+        const p = this.rel(path)
+        const found = kindOf(join(this.repo('exists').root, p))
+        this.reads.exist(p, found)
+        return kind == null ? found != null : found === kind
+    }
+    /** whether a symlink stands at this repo-relative path itself, which
+     *  `exists` cannot say: it follows the link to what it points at */
+    isLink(path: string): boolean {
+        const p = this.rel(path)
+        const is = isLinkAt(join(this.repo('isLink').root, p))
+        this.reads.link(p, is)
+        return is
+    }
+    /** every file matching `glob` that git sees (tracked, or untracked and not
+     *  ignored), repo-relative and sorted */
+    list(glob: string): string[] {
+        const view = this.repo('list').view()
+        const files = view.list(glob)
+        if (view.fallback != null) this.untrack(`listed without a git scan: ${view.fallback}`)
+        this.reads.list(glob, listingHash(files))
+        return files
+    }
+    /** the entries directly inside a repo-relative dir, read from the DISK,
+     *  sorted by name: ignored files included, which `list` leaves out (a
+     *  gitignored contract folder is still a folder a check must see). Empty
+     *  when no dir stands there. The listing is recorded, so an entry added,
+     *  removed or turned from a file into a dir runs the check again */
+    entries(dir: string): DirEntry[] {
+        const d = normalizeInput(dir)
+        const found = dirEntries(d === WHOLE_TREE ? this.repo('entries').root : join(this.repo('entries').root, d))
+        this.reads.dir(d, entriesHash(found))
+        return found ?? []
+    }
+    /** a scan's value, computed once per pass for every check that asks, with
+     *  its reads recorded into this check as if it had made them */
+    async use<T>(scan: Scan<T>): Promise<T> {
+        const pass = this.repo('use')
+        const s = pass.scan(scan, () => new CheckCtx(pass))
+        const value = await s.value
+        this.reads.merge(s.ctx.reads)
+        if (s.ctx.untracked != null) this.untrack(s.ctx.untracked)
+        return value
+    }
+
+    // ── writes, for a fixer ───────────────────────────────────────────────
+    /** write a repo-relative file whole, its dirs created, never torn. For a
+     *  `fix`: a body that writes is not a question, and nothing records it */
+    write(path: string, text: string): void {
+        const abs = join(this.repo('write').root, this.rel(path))
+        mkdirSync(dirname(abs), { recursive: true })
+        atomicWrite(abs, text)
+    }
+    /** delete a repo-relative file or dir, and nothing when it is absent */
+    remove(path: string): void {
+        rmSync(join(this.repo('remove').root, this.rel(path)), { recursive: true, force: true })
+    }
+
+    // ── world ─────────────────────────────────────────────────────────────
+    /** this answer depends on something no read here recorded (a path
+     *  outside the repo, git history), so it must never be stored on its
+     *  reads. exec, fetch and tool say it for themselves */
+    untrack(reason: string): void {
+        this.untracked ??= reason
+    }
+    private world(what: string): void {
+        this.untrack(`it reached the world through ${what}`)
+    }
+
+    /** where a binary lives on this machine, null when it is not installed.
+     *  An explicit candidate path that exists wins over PATH, so a stale
+     *  global never shadows the one a repo pins */
+    tool(name: string, candidates: string[] = []): string | null {
+        this.world('tool')
+        return candidates.find((p) => existsSync(p)) ?? Bun.which(name)
+    }
 
     // fetch with a default timeout; 429 → RateLimited → WARN upstream
     async fetch(url: string, init?: RequestInit & { timeoutMs?: number }): Promise<Response> {
+        this.world('fetch')
         const res = await fetch(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(init?.timeoutMs ?? 10_000) })
         if (res.status === 429) throw new RateLimited(`${new URL(url).host} → 429 rate-limited`)
         return res
@@ -58,6 +244,10 @@ export class CheckCtx {
     // spawn without the Bun.spawn throw-on-missing-binary gotcha; SIGTERM at
     // timeoutMs, SIGKILL 2s later (one code path: core/spawn-timeout.ts)
     async exec(cmd: string[], opts?: { env?: Record<string, string | undefined>; cwd?: string; timeoutMs?: number }): Promise<{ code: number; out: string; timedOut: boolean }> {
-        return spawnWithTimeout(cmd, { timeoutMs: opts?.timeoutMs ?? 15_000, env: opts?.env, cwd: opts?.cwd })
+        this.world('exec')
+        // the environment as it stands NOW: left out, Bun hands the child the
+        // one it started with, and a variable set since (a test seam, a flag
+        // the gate set) never reaches it
+        return spawnWithTimeout(cmd, { timeoutMs: opts?.timeoutMs ?? 15_000, env: opts?.env ?? { ...process.env }, cwd: opts?.cwd })
     }
 }

package/src/core/check-file-names.ts

@@ -0,0 +1,112 @@
+// WHICH files are check files, and what they are called, from paths and
+// source text alone. No disk access here, so a check that must know the
+// repo's check files (SK016) reads them through its context and stays cached
+// on what it read. core/discover-checks.ts walks the disk with the same rules.
+import { basename, relative } from 'path'
+
+export const CHECK_SUFFIX = '.check.ts'
+
+/** dirs discovery never walks into, beside every dot dir: installs, build
+ *  output, scratch, and templates meant for other repos */
+export const SKIPPED_DIRS: ReadonlySet<string> = new Set(['node_modules', 'dist', 'tmp', 'references'])
+
+/** is this repo-relative path a file discovery would find: the suffix, and no
+ *  dir on the way that the walk skips */
+export function isCheckFilePath(rel: string): boolean {
+    if (!rel.endsWith(CHECK_SUFFIX)) return false
+    const dirs = rel.split('/').slice(0, -1)
+    return dirs.every((d) => !SKIPPED_DIRS.has(d) && !d.startsWith('.'))
+}
+
+// a declaration only the legacy script shape writes, at the top level. A
+// comment or an indented line never matches, so a check file that MENTIONS
+// the old shape stays a check file
+const LEGACY_DECL_RE = /^[ \t]*export\s+const\s+(blocking|inputs|ttl|never|gate)\b/m
+// a default export that can be the check object: a call, a literal or a
+// name. A function or a class is a script's own business, never a check
+const DEFAULT_OBJECT_RE = /^[ \t]*export\s+default\s+(?!(async\s+)?function\b|class\b)\S/m
+
+/** is this `*.check.ts` source a legacy check SCRIPT rather than a check
+ *  file? Read, never imported: a script runs its whole body on import. It is
+ *  legacy when it carries a legacy declaration, or when nothing it exports by
+ *  default could be a check object. */
+export function isLegacyCheckSource(src: string): boolean {
+    return LEGACY_DECL_RE.test(src) || !DEFAULT_OBJECT_RE.test(src)
+}
+
+/** the name a repo file answers to when it declares no id: its basename, or
+ *  its repo-relative path when another `*.check.ts` shares that basename.
+ *  Counted over EVERY file with the suffix, legacy scripts included, so both
+ *  readers give one file one name. */
+export function fallbackNames(root: string, files: string[]): Map<string, string> {
+    const base = (f: string): string => basename(f).slice(0, -CHECK_SUFFIX.length)
+    const seen = new Map<string, number>()
+    for (const f of files) seen.set(base(f), (seen.get(base(f)) ?? 0) + 1)
+    return new Map(files.map((f) => [f, (seen.get(base(f)) ?? 0) > 1 ? relative(root, f).replace(/\\/g, '/').slice(0, -CHECK_SUFFIX.length) : base(f)]))
+}
+
+export type LegacyCheck = {
+    /** absolute path to the script */
+    path: string
+    /** display + cache name — file base, disambiguated by relative path on collision */
+    name: string
+    /** `export const blocking = true | false`, read statically. null = the file
+     *  never said, which is an error: a check that silently does not block is
+     *  the failure nobody sees. */
+    blocking: boolean | null
+    /** `export const inputs = ['a', 'b']`, read statically — the repo-relative
+     *  paths this check reads. Declares the CONTENT population for the ledger
+     *  key layer (ledger/git-key.ts). null = never cached, which is the safe
+     *  default and the whole point of default deny. */
+    inputs: string[] | null
+    /** `export const ttl = '24h'`, read statically — declares the WORLD
+     *  population: this check probes something no file on disk describes. */
+    ttl: string | null
+    /** `export const never = 'why'`, read statically — a DECIDED never
+     *  cacheable, which takes the check off the burn-down list. */
+    never: string | null
+    /** `export const gate = false`, read statically — this check is NOT part of
+     *  `shipkit ci`. `ci` answers "is my change good"; a check that answers
+     *  something else, and that can sit red for months without anything being
+     *  wrong, does not belong in the answer. `shipkit check` still runs it.
+     *  Default true: a check is in the gate unless it opts out by name. */
+    gate: boolean
+}
+
+// read without importing: checks run as subprocesses, and discovery must stay
+// pure-fs. `export const blocking = true` (or false), nothing cleverer.
+// the tail is the gate's OWN formatter: oxfmt terminates every statement, and
+// the fix pass runs it, so a reader that refuses a semicolon refuses the shape
+// the gate itself just wrote.
+const TAIL = String.raw`(?:\s+as\s+const)?\s*;?\s*$`
+const BLOCKING_RE = new RegExp(String.raw`^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)` + TAIL, 'm')
+// `export const inputs = ['a', 'b']`, single or multi line. Anything cleverer
+// (a computed list, a spread) is deliberately unreadable here and lands as no
+// declaration, which means never cached: a scanner guessing at a program is
+// how a key comes to describe files the check does not read.
+const INPUTS_RE = /^\s*export\s+const\s+inputs\s*(?::[^=]*)?=\s*\[([^\]]*)\]/m
+const TTL_RE = /^\s*export\s+const\s+ttl\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
+const NEVER_RE = /^\s*export\s+const\s+never\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
+// `export const gate = false` takes a check out of `shipkit ci`. Only the
+// literal false opts out: anything unreadable stays in the gate, because a
+// scanner that guesses its way to SKIPPING a check is how coverage disappears
+const GATE_RE = new RegExp(String.raw`^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false` + TAIL, 'm')
+const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
+
+/** the declarations of one legacy check script, read out of its source. Null
+ *  when the source is a check file instead */
+export function readLegacyCheck(path: string, name: string, src: string): LegacyCheck | null {
+    if (!isLegacyCheckSource(src)) return null
+    const m = src.match(BLOCKING_RE)
+    const im = src.match(INPUTS_RE)
+    const items = im == null ? [] : [...im[1]!.matchAll(STRING_ITEM_RE)].map((x) => x[1]!)
+    return {
+        path,
+        name,
+        blocking: m == null ? null : m[1] === 'true',
+        inputs: items.length > 0 ? items : null,
+        ttl: src.match(TTL_RE)?.[1] ?? null,
+        never: src.match(NEVER_RE)?.[1] ?? null,
+        gate: src.match(GATE_RE) == null,
+    }
+}