rvlib-shipkit 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.34.0
+
+- **SK013's autofix was manufacturing the FAIL its own lint then raised.** It wired a PreToolUse hook at `node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts` whether or not that path existed, so any repo that runs shipkit through the global shim without installing the package came out of a repair pass permanently red. A machine-clearable red that a machine just created is a design bug. The hook is still declared in every case, so it starts working the moment the dependency lands, with no second fix run: what changed is the verdict. A guard under `node_modules/` that is not there yet is an uninstalled dependency, so it WARNs and names `bun install`, with the deny list standing as the whole floor meanwhile. A guard path the repo chose and got wrong still FAILs, because that one never resolves on its own.
+
+- **Three agents in ONE checkout is the normal case, and shipkit is now correct under it.** Everything a run WRITES to the worktree (the fix pass, SK005's `bun update --latest`, hooks arming, the asks archive) takes a blocking lease named for that concern, under the gitignored `tmp/`. The loser waits, because a skipped repair never happens; a holder that is gone or wedged is stolen; a live one is refused by NAME with the lock path and the flag that skips the phase, capped at 60s so nothing hangs. Measured on five real gates racing one repository: with the lease, five of five read-modify-writes survive; without it, four of five are lost and nothing on screen says so. Both lock primitives were raced before they were trusted, and both first versions failed: `writeFileSync(..., 'wx')` publishes a NAME before a body, so a reader in that window steals a live holder's lease (6 of 20 trials overlapped), and a `read, rmSync, grab` steal lets every racer win it (18 of 40 overlapped, peak 3 inside the phase at once). The lock is `linkSync`d into place from a complete body, and a steal is a single `renameSync` that exactly one racer can perform.
+- **The check cache is one immutable file per check, version and cache key**, under `<cacheDir>/<suite>/`, replacing one aggregate json read at the top of a run and rewritten at the bottom, unlocked. Three reproduced failures die with it: two overlapping runs where the second's write drops every entry the first recorded, a torn read that a bare catch turned into an empty cache, and a prune step that deleted "entries for checks I do not know about", which is exactly what a run narrowed by `--only` is. Nothing merges, nothing prunes, no lock is taken, and no check touches a neighbour's entry. Superseded key files are swept by AGE after 30 days, which needs no knowledge of the current check set.
+- **Every task run owns `tmp/shipkit-ci/run-<pid>-<started>-<seq>/`.** The runner used to wipe the shared log dir at the top of every run, so a second gate deleted the logs the first was still streaming into and its FAIL line pointed at a path that no longer existed. Old dirs, and the per run release survey files a killed run leaves behind, are swept only when the pid is gone and the grace window has passed.
+- **`shipkit bump` and `shipkit release` commit with a PATHSPEC.** A bare `git commit` takes the whole index, and agents in one checkout share one index, so a neighbour who staged a file a second earlier got it committed under "release 0.4.0" and tagged. Bump also asks `git worktree list` before merging and refuses by name when the release branch is checked out in another worktree, instead of dying on a raw git fatal or moving another agent's HEAD.
+- **`core.hooksPath` retries on lock contention.** Two worktrees share one `.git/config`, so two runs arming at once made one of them report "hooks will not fire" about a repo whose hooks were fine.
+- **Under CI, a fix pass that never ran now FAILs.** In verify mode the fix pass IS the check, so reporting "not run" and exiting 0 passed a commit nobody verified.
+- **BREAKING, one export**: `checkAsks(dir, print)` is now `checkAsks(root, dir, print)` and returns a Promise, because the archive takes the repo's lease. Two concurrent runs used to spawn every probe twice and then throw an uncaught ENOENT when the loser renamed a file the winner had already moved.
+- Every rule fixer writes through `atomicWrite`, so a killed run cannot leave a half written `package.json`, `.gitignore`, `CLAUDE.md` or `.claude/settings.json`. SK004's managed block gains `.*.tmp-*` in the same change, because that is the debris such a kill leaves anywhere in the tree.
+- `run-fix.ts`'s unchanged-fix line carries a wire prefix. `shipkit ci` promises every line it emits is parseable, and that one was bare.
+
+- **The typecheck slot could report green over a file that does not compile.** A solution-style `tsconfig.json` (`"files": []` plus `references`, which is the standard vite shape) makes `tsc --noEmit` compile ZERO files and exit 0, so the built-in typecheck floor printed `ok: typecheck (0.1s)` with a type error sitting in `src/`. Every other failure in this tool is loud; this one was a green indistinguishable from a measured one. `ts/tsconfig-projects.ts` now resolves the set of projects a typecheck must visit: it walks `references`, and it keeps a referencing config in that set whenever the config compiles inputs of its OWN, because `references` does not suppress them. Only `"files": []` with no `include`, or an empty `include`, makes a config compile nothing; a bare `{ references: [...] }` still compiles the whole tree, since tsc defaults `include` to `**/*`. A reference may name a directory, cycles terminate, and a config reaching nothing that compiles is reported as VACUOUS. The floor spawns `ts/typecheck-cli.ts`, which resolves at RUN time so a tsconfig edited after resolution still counts, runs every project instead of stopping at the first red, and on success NAMES the projects it checked. A vacuous config or a dangling reference registers that runner too and exits non-zero, rather than leaving the slot unfilled: an unfilled slot is a skip, the gate still exits 0, and a repo with no typecheck coverage would read exactly like one that passed. `release/unit-gate.ts` ran the same vacuous command as a PUBLISH gate and got the same treatment.
+- **`parseJsonc` is a quote-aware scanner instead of two regexes**, because tsconfig is the one dialect where the regex version cannot work: `"src/**/*"` is a `/*` carrying its own `*/`, so a block-comment regex eats an arbitrary span of a valid file. Measured over the real tsconfigs on this machine, the old version THREW on 8 of them and silently rewrote `"src/**/*.ts"` to `"src*.ts"` in 8 more. It parses 80 of 80 now. This matters more than it did yesterday: the same parser gates typecheck and publish.
+- **`bun run test:raw` takes a FILE filter, not a name filter.** Measured: bun's positional argument matches the test file path, and a single test by name is `bun run test:raw -- -t "<name>"`. The wrong form was in 0.33.0's own notes, in two verify-skill templates, on `build/shipkit.md`, and in the refusal message an agent reads at the exact moment it is blocked.
+
+## 0.33.0
+
+- **ONE WAY IN, enforced. A wired repo's `test`, `lint` and `typecheck` scripts route through shipkit, and the harness refuses the raw runner.** Measured in a real wired repo before this: `"lint": "eslint ."`, `"test": "bun test"`, no ci script, an empty `.claude/`. An agent doing the obvious thing ran the tool, shipkit never heard the call, and the cache it was building was worthless. **This changes the shape of every wired repo's package.json**, and 0.32.0 already shipped the first half of it without saying so, which is the gap this note closes. Rule SK001 (blocking, autofixable) now FAILs a governed script that runs the tool directly; the fix slides the body to `<id>:raw` and makes the name `shipkit ci --only <id>`. `<id>:raw` is what the gate itself runs, and what you use to iterate on one suite. Those THREE names only: `imports:check` and `cycles` are shipkit's own vocabulary, and `fmt` is the slot the fix pass invokes by script, so routing it would make the fixer call itself. `resolveFloor` moved to `core/floor.ts` and refuses to run a routed script, which spawns the gate from inside the gate.
+- **New rule SK013 (blocking, autofixable) writes the harness half**, because a package.json cannot reach it: `bun test` is a bun builtin and no script can intercept it. A tracked `.claude/settings.json` gets `permissions.deny` for every raw runner plus a PreToolUse guard, both rendered from ONE table. The deny is the floor, unbypassable in either direction; the guard is the messenger, because a bare deny tells the model only that it was denied and it then goes hunting for another runner. Every refusal names the shipkit command, the narrow way in, and the exact line that lifts it. The guard reads the deny list out of the settings FILE, so deleting one `Bash(...)` line lifts both mechanisms at once. It also catches what a prefix rule cannot (`CI=1 bun test`, `./node_modules/.bin/tsc`) and segments at quote depth zero, so a commit message quoting a runner is data. SK013 FAILs when the declared guard script does not resolve: a hook that errors refuses nothing.
+- **`shipkit init` repairs an existing repo, not just a fresh one**, calling the same fixers `shipkit check --fix` runs. That is the half that matters, because the repos that need this most already exist. `shipkit start` inherits it.
+- **A `--only` run repairs the mechanical slots ALONE.** The structural rule fixers rewrite package.json and repo config, and arming rewrites `hooks/`. That is the right price for the full gate and the wrong one for `bun run test`, which now routes here: the reflex verb must not leave files in an agent's diff that it never wrote, and under CI a formatting rewrite came back as a test failure.
+- **Escaping it**: delete the `Bash(<runner>*)` line from `.claude/settings.json`; or `repo.config.ts oneWayIn: { exempt: ['test'] }`, which drops the script requirement and the shell rules together (an unknown name throws at config load); a slot turned off with `defaults: { lint: false }` is exempt already. `bun run test:raw <test file>` stays open for iterating on one suite, and one test by name is `bun run test:raw -- -t "<name>"`. A repo with sub-packages gives each one its own `test:raw`, or the escape does not reach where the work is. The formatter is deliberately not denied at all.
+- `--allow-dirty` now says WHY it is safe in one place and not the other: `npm publish` packs the working tree, not the commit, so dirt in other paths cannot reach the tarball and dirt inside the unit ships a half-written file under a tag that describes something else.
+
 ## 0.32.0
 
 - **`shipkit pb collection <name>` scaffolds a PocketBase collection's whole UI folder.** Building a CRUD screen meant retyping a schema that already exists in the app's generated types, one column at a time, and the boring half of that is exactly where a column goes missing. The command reads `src/pb.types.ts` (`.tsx` and `.d.ts` too), resolves one collection, and writes `src/collections/<name>/`: `columns.tsx` with one entry per response field, `card.tsx`, `grid.tsx` over `LiveGrid`, `form.tsx` (a create/edit modal writing through `db` fire and forget), and an `index.ts` calling `defineCollectionUI`. It then registers the folder in `src/collections/index.ts`, creating that file when it is the first one, because a collection folder nothing imports is dead code whose failure mode is a runtime throw. A field the schema cannot turn into a cell on its own (relation, file, json, raw html) is emitted COMMENTED with the reason rather than dropped, because a missing column is invisible and a commented one takes ten seconds to accept or delete. The card leads on the fields a human reads, not on the first three of an alphabetical record block, and the label picks the first of `name`, `label`, `title`, `number`, `code`, `email`, else `id`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.32.0",
+    "version": "0.34.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",
@@ -28,6 +28,9 @@
         "mobx": "^7.0.0",
         "mobx-react-lite": "^5.0.0"
     },
+    "scripts": {
+        "test:raw": "bun test"
+    },
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",

package/src/asks/asks-queue.ts

@@ -6,6 +6,7 @@
 // Stdout contract (FROZEN — consumers parse the prefixes): `closed +
 // archived <file>` / `archived <file>` / `still <status> <file>` / `N closed`.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs'
+import { atomicWrite, mutateLease, withMutateLease } from '../core/locked-write.ts'
 import { join } from 'path'
 
 export type Ask = { file: string; status: string; kind: string; created: string; blocks: string; check: string | null; title: string }
@@ -53,7 +54,19 @@ export function doneAsks(dir: string): Ask[] {
     return readdirSync(done).filter((f) => f.endsWith('.md')).sort().reverse().map((f) => parse(done, f))
 }
 
-export function checkAsks(dir: string, print: (line: string) => void = console.log): { closed: number } {
+/** probe every open ask and archive the ones that now pass. Under the repo's
+ *  mutate lease: two runs racing here each spawn every probe (which reach the
+ *  world), and then one of them renames a file the other already moved, which
+ *  is an uncaught ENOENT rather than a message. The loser waits and finds
+ *  nothing left to close, which is the correct answer. */
+export async function checkAsks(root: string, dir: string, print: (line: string) => void = console.log): Promise<{ closed: number }> {
+    const leased = await withMutateLease(mutateLease(root, 'asks'), { label: 'asks archive', print, maxWaitMs: 45_000 }, () => checkAsksBody(dir, print))
+    if (leased.ok) return leased.value
+    print(`WARN asks check skipped — ${leased.warn}`)
+    return { closed: 0 }
+}
+
+function checkAsksBody(dir: string, print: (line: string) => void): { closed: number } {
     const done = join(dir, 'done')
     mkdirSync(done, { recursive: true })
     let closed = 0
@@ -63,7 +76,7 @@ export function checkAsks(dir: string, print: (line: string) => void = console.l
         const p = Bun.spawnSync(['bash', '-lc', a.check])
         if (p.exitCode === 0) {
             const md = readFileSync(join(dir, a.file), 'utf8').replace(/^status:.*$/m, `status: done\nclosed: ${new Date().toISOString().slice(0, 10)}`)
-            writeFileSync(join(dir, a.file), md)
+            atomicWrite(join(dir, a.file), md)
             renameSync(join(dir, a.file), join(done, a.file))
             print(`closed + archived ${a.file}`)
             closed++

package/src/cli/cmd_Asks.ts

@@ -41,7 +41,8 @@ export class AsksCheckCommand extends Command {
 
     async execute(): Promise<number> {
         try {
-            checkAsks(await asksDir(process.cwd()))
+            const root = process.cwd()
+            await checkAsks(root, await asksDir(root))
             return 0
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)

package/src/cli/cmd_Keys.ts

@@ -0,0 +1,107 @@
+// shipkit keys — what every gate unit is keyed on, and what it is NOT.
+//
+// Nothing is cached yet. This command exists so the key layer is auditable by
+// eye BEFORE anything replays off it: a cache whose keys nobody can read is a
+// cache nobody can debug the day it serves a wrong answer. `--why <id>` prints
+// the exact component list a key was hashed from, which is the only honest
+// answer to "why did this key move".
+import { createHash } from 'crypto'
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { gateUnits } from '../ledger/gate-units.ts'
+import { KeyLayer } from '../ledger/git-key.ts'
+
+export class KeysCommand extends Command {
+    static override paths = [['keys']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'the cache key of every gate unit (task, rule, check), and the reason the undeclared ones have none. Reports, never gates',
+        examples: [
+            ['every unit and its key', 'shipkit keys'],
+            ['only the ones nothing can cache yet', 'shipkit keys --burn-down'],
+            ['why this key is what it is', 'shipkit keys --why typecheck'],
+            ['re-hash after the fact and report drift', 'shipkit keys --rescan'],
+            ['machine-readable', 'shipkit keys --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable { units: UnitKey[], burnDown, errors, scanMs }' })
+    burnDown = Option.Boolean('--burn-down', false, { description: 'list only the units nothing can cache yet, and why' })
+    why = Option.String('--why', { required: false, description: 'print every component that went into ONE unit\'s key' })
+    rescan = Option.Boolean('--rescan', false, { description: 'run the post-run re-hash and name every input that moved since the scan' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        const decls = gateUnits(root, c)
+        const layer = KeyLayer.open(root, decls, { cliEntry: new URL('../cli.ts', import.meta.url).pathname })
+        const keys = layer.keys()
+        const out = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+
+        if (this.json) {
+            const drift = this.rescan ? layer.rescan() : null
+            out(JSON.stringify({ units: keys, burnDown: layer.registration.burnDown, errors: layer.registration.errors, layerMs: Math.round(layer.openMs), scanMs: Math.round(layer.scanMs), failure: layer.failure, drift }))
+            return layer.registration.errors.length > 0 || layer.failure != null ? 1 : 0
+        }
+
+        if (this.why != null) {
+            const k = keys.find((u) => u.id.toLowerCase() === this.why!.toLowerCase())
+            if (k == null) {
+                out(`FAIL: no gate unit '${this.why}' — run \`shipkit keys\` for the list`)
+                return 1
+            }
+            out(`${k.kind} ${k.id} — ${k.population}`)
+            if (k.key == null) {
+                out(`      no key: ${k.reason ?? 'undeclared'}`)
+                return 0
+            }
+            out(`      key ${k.key}`)
+            // the excluded block is 44 lines here and it buries the component
+            // that actually moved. It stays HASHED line by line, so this is a
+            // rendering choice and not a different key: the digest moves with
+            // the set, which is what answers "why did this move", and --json
+            // still carries every path.
+            const excluded = k.components.filter((c) => c.startsWith('excluded='))
+            for (const comp of k.components) if (!comp.startsWith('excluded=')) out(`      ${comp}`)
+            if (excluded.length > 0) {
+                const digest = createHash('sha256').update(excluded.join('\n')).digest('hex').slice(0, 8)
+                out(`      excluded ${excluded.length} path(s), digest ${digest} — not in the key's content, only in its meaning`)
+                for (const c of excluded.slice(0, 3)) out(`        ${c.slice('excluded='.length)}`)
+                if (excluded.length > 3) out(`        … ${excluded.length - 3} more (shipkit keys --json)`)
+            }
+            return 0
+        }
+
+        for (const e of layer.registration.errors) out(`FAIL: ${e}`)
+        if (layer.failure != null) {
+            out(`FAIL: git scan failed, no unit may be keyed — ${layer.failure}`)
+            out('      fix: nothing is cached, so the gate is unaffected. A stale scratch index clears with: rm .git/shipkit/scan.idx')
+        }
+
+        // the burn-down is what nobody has LOOKED at. A unit that declared
+        // `never` with a reason has been looked at, and listing it here would
+        // put four permanent rows on a list whose whole job is to shrink
+        const decided = new Set(layer.decls.filter((d) => d.never != null && d.never !== '').map((d) => d.id))
+        const shown = this.burnDown ? keys.filter((k) => k.population === 'none' && !decided.has(k.id)) : keys
+        for (const k of shown) out(`${k.population.padEnd(7)} ${k.kind.padEnd(5)} ${k.id.padEnd(28)} ${k.key ?? `— ${k.reason ?? ''}`}`)
+
+        const content = keys.filter((k) => k.population === 'content').length
+        const world = keys.filter((k) => k.population === 'world').length
+        const none = keys.filter((k) => k.population === 'none').length
+        const todo = layer.registration.burnDown.length
+        out(`\n${keys.length} units — ${content} content, ${world} world, ${none} uncacheable (${none - todo} decided, ${todo} still undeclared) · key layer ${Math.round(layer.openMs)}ms, of which ${Math.round(layer.scanMs)}ms of git`)
+        if (todo > 0 && !this.burnDown) out(`      the burn-down: shipkit keys --burn-down`)
+
+        if (this.rescan) {
+            const d = layer.rescan()
+            if (d.error != null) out(`FAIL: re-hash failed — ${d.error}`)
+            else if (d.drifted.length === 0) out(`ok: post-run re-hash clean, nothing moved (${Math.round(d.ms)}ms)`)
+            else {
+                out(`WARN ${d.drifted.length} input(s) moved since the scan — a run would discard its results rather than store them:`)
+                for (const p of d.drifted) out(`      ${p}`)
+            }
+        }
+        return layer.registration.errors.length > 0 || layer.failure != null ? 1 : 0
+    }
+}

package/src/cli.ts

@@ -13,6 +13,7 @@ import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cli/cmd_Hooks.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
+import { KeysCommand } from './cli/cmd_Keys.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { PbCollectionCommand } from './cli/cmd_Pb.ts'
@@ -70,6 +71,7 @@ export function buildCli(): Cli {
     cli.register(PbCollectionCommand)
     cli.register(ReflectCommand)
     cli.register(RulesCommand)
+    cli.register(KeysCommand)
     cli.register(CommandsCommand)
 
     return cli

package/src/core/canonical-scripts.ts

@@ -60,7 +60,9 @@ export function routedBody(id: string, opts: ScriptStyle = {}): string {
  *  under a shipkit checkout (a repo calling rvlib's source-graph cli by path)
  *  is not a route back in. */
 export function routesToShipkit(body: string): boolean {
-    return /\bshipkit\b/.test(body) && /\bci\b/.test(body)
+    // the `ci` verb must belong to the shipkit invocation, not merely appear
+    // somewhere in the line: `shipkit contracts && bun run x:ci` routes nothing
+    return /\bshipkit\b\S*(?:\s+\S+)*?\s+ci(?:\s|$)/.test(body.split(/&&|\|\||;/)[0] ?? body)
 }
 
 // recover the consumption style from existing scripts: any shipkit command

package/src/core/check-suite.ts

@@ -2,22 +2,60 @@
 // renders the v0 wire contract (wire.ts) with exit code.
 //
 // The TTL cache is the API-spam guard: a passing check with `remainValidFor`
-// replays from `<cacheDir>/<name>.json` without touching the network. Only
-// clean passes are cached; WARN/FAIL evict. Busts: version bump, secret
-// rotation (key hashes the secret value), `<freshEnv>=1`.
+// replays without touching the network. Only clean passes are cached;
+// WARN/FAIL evict. Busts: version bump, secret rotation (key hashes the
+// secret value), `<freshEnv>=1`.
+//
+// STORAGE: one immutable file per (check, version, cache key), under
+// `<cacheDir>/<suite>/`. Three agents in one checkout is the normal case, so
+// there is no shared file to lose a write to: a run with a different key
+// writes a DIFFERENT file, a run with the same key replaces its own by tmp +
+// rename (whole answer or nothing, never half), and nothing is pruned,
+// because pruning by "the checks I know about" deletes the entries of a
+// runner that narrowed itself with --only. It replaced one aggregate JSON
+// read at the top of the run and rewritten at the bottom, which lost every
+// entry another runner wrote in between and served a torn read as an empty
+// cache.
 //
 // Secret VALUES never enter this module's state beyond the injected
 // getSecret call + a truncated hash for cache-busting.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { join } from 'path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { dirname, join } from 'path'
 import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
+import { atomicWrite } from './locked-write.ts'
 import { fmtStamp, formatLine, parseDuration, type Line } from './wire.ts'
 
 type Logic = (t: CheckCtx) => unknown
 type Prep = { skip?: string; cacheExtra?: string }
 type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic; blocking: boolean }
 type CacheEntry = { version: number; key: string; at: number; lines: Line[] }
-type CacheFile = Record<string, CacheEntry>
+
+/** a missing or half-written file reads as "no answer", which is the safe
+ *  side: the check runs. tmp + rename means half-written cannot happen from a
+ *  shipkit write, so this only ever catches a truncated file from something
+ *  else, and treats it the same way. */
+const readEntry = (path: string): CacheEntry | null => {
+    try {
+        const e = JSON.parse(readFileSync(path, 'utf8')) as Partial<CacheEntry>
+        return Array.isArray(e.lines) && typeof e.at === 'number' && typeof e.version === 'number' && typeof e.key === 'string' ? (e as CacheEntry) : null
+    } catch { return null }
+}
+
+const writeEntry = (path: string, e: CacheEntry): void => {
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        atomicWrite(path, JSON.stringify(e))
+    } catch {
+        // a cache that cannot be written is slow, never wrong: the answer was
+        // already printed, and the next run measures again
+    }
+}
+
+const slug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
+
+/** how long a superseded key's file survives. Far past the longest TTL any
+ *  check declares, so a live entry is never swept out from under a replay. */
+const SUPERSEDED_KEEP_MS = 30 * 24 * 60 * 60 * 1000
 
 export type GetSecret = (name: string, field: 'get' | 'account') => string | null
 
@@ -128,18 +166,47 @@ export class CheckSuite {
         })
     }
 
+    /** the key is in the file name, so a check whose key moves leaves its old
+     *  file behind forever. A rule keyed on installed versions writes one per
+     *  upgrade, so the dir accretes without bound in a repo nobody clears.
+     *  Sweeping by AGE needs no knowledge of the current check set, which is
+     *  what made the old prune wrong: a run narrowed by --only knows about one
+     *  check and would have deleted the other twenty four. */
+    private sweepSuperseded(): void {
+        const dir = join(this.cacheDir, slug(this.name))
+        const cutoff = this.now() - SUPERSEDED_KEEP_MS
+        try {
+            for (const f of readdirSync(dir)) {
+                if (!f.endsWith('.json')) continue
+                const p = join(dir, f)
+                try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true }) } catch { /* raced with another runner: it is gone either way */ }
+            }
+        } catch {
+            // no dir yet, or unreadable: housekeeping never fails a run
+        }
+    }
+
+    /** where this check's answer for THIS key lives. The key is in the file
+     *  NAME, so a run whose key moved writes a new file rather than rewriting
+     *  the old one, and two runners with different keys never collide. */
+    private entryPath(r: Runner, key: string): string {
+        const h = new Bun.CryptoHasher('sha256').update(`${r.name}\0${r.version}\0${key}`).digest('hex').slice(0, 12)
+        return join(this.cacheDir, slug(this.name), `${slug(r.name)}.${h}.json`)
+    }
+
     // test seam — run() prints + exits; execute() returns the structured result
     /** ONE check: cache replay, run, classify, and what it wants remembered.
      *  Pure with respect to its neighbours, which is what lets execute() run
      *  them together. */
-    private async runOne(r: Runner, cache: CacheFile): Promise<{ lines: Line[]; skip: string | null; ran: boolean; failed: boolean; store: CacheEntry | null; evict: boolean }> {
+    private async runOne(r: Runner): Promise<{ lines: Line[]; skip: string | null; ran: boolean; failed: boolean }> {
         const prep = r.prep?.() ?? {}
         if (prep.skip != null) {
             this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
-            return { lines: [], skip: prep.skip, ran: false, failed: false, store: null, evict: false }
+            return { lines: [], skip: prep.skip, ran: false, failed: false }
         }
         const key = prep.cacheExtra ?? ''
-        const entry = cache[r.name]
+        const entryPath = this.entryPath(r, key)
+        const entry = readEntry(entryPath)
         const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
             && entry != null && entry.version === r.version && entry.key === key
             && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
@@ -154,7 +221,7 @@ export class CheckSuite {
             // answer, and demoting it to a pass would hide a real finding
             const replayedWarn = entry.lines.some((l) => l.kind === 'warn' || l.kind === 'fail')
             this.onResult?.(r.name, { lines: entry.lines, status: replayedWarn ? 'warn' : 'pass', cached: true })
-            return { lines: entry.lines, skip: null, ran: true, failed: false, store: null, evict: false }
+            return { lines: entry.lines, skip: null, ran: true, failed: false }
         }
         const t = new CheckCtx(this.toolPaths)
         try {
@@ -194,23 +261,28 @@ export class CheckSuite {
             ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (${clean ? 'cached' : 'measured'} at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
             : t.lines
         this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
-        return {
-            lines,
-            skip: null,
-            ran: true,
-            failed: t.failed,
-            store: cacheable && r.ttlMs > 0 ? { version: r.version, key, at: this.now(), lines } : null,
+        // this check writes its OWN file, and only its own: nothing here reads
+        // or rewrites a neighbour's entry, so a racing runner can lose nothing
+        if (r.ttlMs > 0) {
+            if (cacheable) writeEntry(entryPath, { version: r.version, key, at: this.now(), lines })
             // an unmeasured run evicts whatever was stored: a later run must
-            // re-probe rather than replay an answer recorded before the outage
-            evict: r.ttlMs > 0 && !cacheable && entry != null,
+            // re-probe rather than replay an answer recorded before the outage.
+            // A racing runner may have written a good answer into that same
+            // file a moment ago and lose it here, which costs one re-probe and
+            // can never produce a stale green, so it is the safe direction.
+            else if (entry != null) rmSync(entryPath, { force: true })
         }
+        return { lines, skip: null, ran: true, failed: t.failed }
     }
 
     async execute(): Promise<{ lines: Line[]; exitCode: number }> {
-        const cachePath = join(this.cacheDir, `${this.name}.json`)
-        let cache: CacheFile = {}
-        try { cache = JSON.parse(readFileSync(cachePath, 'utf8')) } catch {}
-        let cacheDirty = false
+        // the aggregate file this replaced. Deleting it here is the migration:
+        // nothing reads it any more, and leaving it would have a future reader
+        // believe there are two cache layers. DIES when every consumer repo is
+        // past rvlib-shipkit 0.34.0, since after that no tree can still carry
+        // one; it costs an unlink of a path that is not there.
+        rmSync(join(this.cacheDir, `${this.name}.json`), { force: true })
+        this.sweepSuperseded()
 
         // CONCURRENT, bounded. Checks are independent by contract: each answers
         // one question about the world or the repo and shares nothing with its
@@ -227,7 +299,7 @@ export class CheckSuite {
             for (;;) {
                 const i = next++
                 if (i >= this.runners.length) return
-                results[i] = await this.runOne(this.runners[i]!, cache)
+                results[i] = await this.runOne(this.runners[i]!)
             }
         }
         await Promise.all(Array.from({ length: Math.min(cap, this.runners.length) }, () => worker()))
@@ -238,13 +310,10 @@ export class CheckSuite {
         let anyFail = false
         for (let i = 0; i < this.runners.length; i++) {
             const r = results[i]!
-            const name = this.runners[i]!.name
             out.push(...r.lines)
             if (r.skip != null) skipped.push(r.skip)
             if (r.ran) ran++
             if (r.failed) anyFail = true
-            if (r.store != null) { cache[name] = r.store; cacheDirty = true }
-            else if (r.evict) { delete cache[name]; cacheDirty = true }
         }
 
         // contract: `skip:` lines ONLY when no check ran at all (whole probe is
@@ -253,13 +322,6 @@ export class CheckSuite {
         if (ran === 0) out.push(...skipped.map((s): Line => ({ kind: 'skip', text: `${s} (creds gate reports it)` })))
         else out.push(...skipped.map((s): Line => ({ kind: 'note', text: `${s} — validation skipped (creds gate reports it)` })))
 
-        if (cacheDirty) {
-            // prune entries for renamed/removed checks — the file must not accrete
-            const known = new Set(this.runners.map((r) => r.name))
-            for (const k of Object.keys(cache)) if (!known.has(k)) delete cache[k]
-            mkdirSync(this.cacheDir, { recursive: true })
-            writeFileSync(cachePath, JSON.stringify(cache))
-        }
         return { lines: out, exitCode: anyFail ? 1 : 0 }
     }
 

package/src/core/discover-checks.ts

@@ -23,11 +23,30 @@ export type DiscoveredCheck = {
      *  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
 }
 
 // read without importing: checks run as subprocesses, and discovery must stay
 // pure-fs. `export const blocking = true` (or false), nothing cleverer.
 const BLOCKING_RE = /^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)\s*$/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 unit 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
+const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
 
 export function discoverChecks(root: string): DiscoveredCheck[] {
     const files: string[] = []
@@ -52,12 +71,22 @@ export function discoverChecks(root: string): DiscoveredCheck[] {
         // TTL cache — caching it again up here would double the staleness
         let selfCached = false
         let blocking: boolean | null = null
+        let inputs: string[] | null = null
+        let ttl: string | null = null
+        let never: string | null = null
         try {
             const src = readFileSync(f, 'utf8')
             selfCached = /PageValidator|CheckSuite/.test(src)
             const m = src.match(BLOCKING_RE)
             blocking = m == null ? null : m[1] === 'true'
+            const im = src.match(INPUTS_RE)
+            if (im != null) {
+                const items = [...im[1]!.matchAll(STRING_ITEM_RE)].map((x) => x[1]!)
+                if (items.length > 0) inputs = items
+            }
+            ttl = src.match(TTL_RE)?.[1] ?? null
+            never = src.match(NEVER_RE)?.[1] ?? null
         } catch {}
-        return { path: f, name, selfCached, blocking }
+        return { path: f, name, selfCached, blocking, inputs, ttl, never }
     })
 }

package/src/core/floor.ts

@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
 import { rawName, routesToShipkit } from './canonical-scripts.ts'
+import { resolveTypecheckProjects } from '../ts/tsconfig-projects.ts'
 import type { TaskDef } from './task-runner.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
@@ -40,11 +41,29 @@ function builtinFloorTask(id: string, root: string): { task: TaskDef; source: Fl
         }
     }
     if (id === 'typecheck') {
-        if (!existsSync(join(root, 'tsconfig.json'))) return `no 'typecheck' script and no tsconfig.json`
+        const tsconfig = join(root, 'tsconfig.json')
+        if (!existsSync(tsconfig)) return `no 'typecheck' script and no tsconfig.json`
         const local = join(root, 'node_modules/.bin/tsc')
         const tsc = existsSync(local) ? local : Bun.which('tsc')
         if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
-        return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+        // `tsc --noEmit` over a solution-style config (`files: []` plus
+        // `references`) compiles ZERO files and exits 0, so the slot reports a
+        // green nobody measured. only a config that is its OWN single project
+        // keeps the plain command; everything else goes through the runner,
+        // which resolves and REPORTS what it checked.
+        //
+        // a config that compiles nothing, or references a path that is gone,
+        // registers the runner too rather than leaving the slot unfilled: an
+        // unfilled slot is a skip, `shipkit ci` still exits 0, and a repo with
+        // no typecheck coverage would look the same as a repo that passed.
+        let plain = false
+        try {
+            const projects = resolveTypecheckProjects(tsconfig)
+            plain = projects.projects.length === 1 && projects.projects[0] === tsconfig && projects.missing.length === 0
+        } catch { plain = false }
+        if (plain) return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+        const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/typecheck-cli.ts'))
+        return { task: { id, cmd: ['bun', cli, tsc, tsconfig] }, source: 'built-in (tsc)' }
     }
     return `no package.json '${id}' script`
 }