rvlib-shipkit 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -1,12 +1,34 @@
 # Changelog
 
+## 0.35.0
+
+- **`shipkit pb collection` mints imports of a package that exists.** The pocketbase data layer and the Mantine shell are one package now, `rvlib-pb`: the generated `columns.tsx`, `grid.tsx` and `index.ts` import `Column`, `LiveGrid` and `defineCollectionUI` from `rvlib-pb/ui`, and `LiveList` from `rvlib-pb`. The two tiers are different subpaths on purpose, so a generated grid that took its type from the ui subpath would typecheck and would put `@mantine/core` in the tsconfig of anything that reads it. This generator ships inside the tarball and writes into repos it never sees, so a stale specifier here keeps producing broken scaffolds long after a rename lands: the suite now asserts every import string the generator emits, which nothing did before.
+
+## 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 <name filter>` stays open for iterating on one suite. 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.
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.33.0",
+    "version": "0.35.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",

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_Ci.ts

@@ -16,6 +16,7 @@ export class CiCommand extends Command {
             ['leave repo config files alone', 'shipkit ci --no-fix-rules'],
             ['stop at the first failure', 'shipkit ci --bail'],
             ['one task + its dep closure', 'shipkit ci --only typecheck'],
+            ['re-measure everything, replay nothing', 'shipkit ci --fresh'],
             ['include an opt-in task', 'shipkit ci --with up:itch'],
         ],
     })
@@ -28,6 +29,7 @@ export class CiCommand extends Command {
     skip = Option.Array('--skip', [], { description: 'skip a task group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include an opt-in task (repeatable)' })
     only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })
+    fresh = Option.Boolean('--fresh', false, { description: 'measure everything: no unit replays from the ledger, and what this run measures is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
     async execute(): Promise<number> {
@@ -45,6 +47,7 @@ export class CiCommand extends Command {
                 skipGroups: this.skip,
                 withIds: this.withIds,
                 onlyIds: this.only,
+                fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
                 print: (l) => this.context.stdout.write(`${l}\n`),
             })

package/src/cli/cmd_Keys.ts

@@ -0,0 +1,113 @@
+// 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 { envTier, FULL_TESTS_ENV, gateUnits, tieredTasks } 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'],
+            ['the keys a --full gate asks for', 'shipkit keys --full'],
+            ['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' })
+    full = Option.Boolean('--full', false, { description: `render the keys a FULL-tier run asks for (same as ${FULL_TESTS_ENV}=1). The tier is in every task'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)
+        // the TIER the gate would run, applied here too: `--full` rewrites
+        // every task's env, which is in the key, so a surface that renders keys
+        // without it renders a tier nobody asked for
+        const tier = this.full ? 'full' : envTier()
+        const decls = gateUnits(root, c, tieredTasks(c, root, tier))
+        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({ tier, 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) · ${tier} test tier · 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/check-suite.ts

@@ -2,22 +2,27 @@
 // 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 is not this module's concern any more: ledger/store.ts owns the
+// one store, its shape, and its housekeeping (one immutable file per key,
+// tmp + rename, age-based sweep). This is the WORLD half of the three
+// populations — an answer nothing on disk describes, remembered for a TTL and
+// busted by rotation. The CONTENT half is keyed instead of timed and lives in
+// ledger/ledger.ts. Same store, different key.
 //
 // 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 } from 'fs'
 import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
+import { dropStored, entryPath, FRESH_ENV, readStored, sweepStore, writeStored } from '../ledger/store.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>
 
 export type GetSecret = (name: string, field: 'get' | 'account') => string | null
 
@@ -28,15 +33,19 @@ export type SecretSpec = {
     skipHint: string
 }
 
-export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean }
+export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean; /** wall time of the LOGIC, ms — 0 on a replay, since a replay measured nothing */ ms: number }
 
 export type CheckSuiteOpts = {
     name: string
-    cacheDir: string
+    /** the ONE store root (ledger/store.ts storeRoot). Injected rather than
+     *  resolved here so a test can point a suite at a scratch dir. */
+    storeDir: string
     now?: () => number
     /** secret backend — consumers inject their own store; default = nothing stored, every secret check skips */
     getSecret?: GetSecret
-    /** env var that busts the cache when set (consumer names it) */
+    /** TEST SEAM: the env var that busts this suite's replays. Production is
+     *  always the one house-wide flag (ledger/store.ts FRESH_ENV); a test
+     *  overrides it so busting one suite cannot poison a neighbour's run. */
     freshEnv?: string
     /** per-check completion tap (the TUI streams results in) — cached replays
      *  report cached:true, prep-skips (unstored secret) report status 'skip' */
@@ -47,7 +56,7 @@ export class CheckSuite {
     readonly name: string
     private runners: Runner[] = []
     private toolPaths = new Map<string, string>()
-    private cacheDir: string
+    private storeDir: string
     private now: () => number
     private getSecret: GetSecret
     private freshEnv: string
@@ -55,10 +64,10 @@ export class CheckSuite {
 
     constructor(opts: CheckSuiteOpts) {
         this.name = opts.name
-        this.cacheDir = opts.cacheDir
+        this.storeDir = opts.storeDir
         this.now = opts.now ?? Date.now
         this.getSecret = opts.getSecret ?? (() => null)
-        this.freshEnv = opts.freshEnv ?? 'SHIPKIT_FRESH'
+        this.freshEnv = opts.freshEnv ?? FRESH_ENV
         this.onResult = opts.onResult
     }
 
@@ -128,21 +137,29 @@ export class CheckSuite {
         })
     }
 
+    /** the key a world answer is remembered under: the check's own version
+     *  plus whatever the prep declared (a secret's value hash, a rule's
+     *  cacheKey). A version bump and a rotation both move it, so neither can
+     *  replay across the change. */
+    private cacheKey(r: Runner, extra: string): string {
+        return `v${r.version}\0${extra}`
+    }
+
     // 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 }
+            this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false, ms: 0 })
+            return { lines: [], skip: prep.skip, ran: false, failed: false }
         }
-        const key = prep.cacheExtra ?? ''
-        const entry = cache[r.name]
+        const key = this.cacheKey(r, prep.cacheExtra ?? '')
+        const path = entryPath(this.storeDir, this.name, r.name, key)
+        const entry = readStored<Line[]>(path, key)
         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
+            && entry != null && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
         if (fresh) {
             // the stamp was baked in when the check RAN (below): a replay
             // prints the stored lines VERBATIM, so the live run and every
@@ -152,11 +169,12 @@ export class CheckSuite {
             // alternation, so neither side annotates
             // a replayed WORLD negative keeps its severity: it is still the
             // 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 }
+            const replayedWarn = entry.payload.some((l) => l.kind === 'warn' || l.kind === 'fail')
+            this.onResult?.(r.name, { lines: entry.payload, status: replayedWarn ? 'warn' : 'pass', cached: true, ms: 0 })
+            return { lines: entry.payload, skip: null, ran: true, failed: false }
         }
         const t = new CheckCtx(this.toolPaths)
+        const started = performance.now()
         try {
             await r.logic(t)
         } catch (e) {
@@ -193,24 +211,23 @@ export class CheckSuite {
         const lines = cacheable
             ? 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.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false, ms: performance.now() - started })
+        // 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) writeStored(path, key, lines, this.now())
             // 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) dropStored(path)
         }
+        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
+        sweepStore(this.storeDir, this.name, this.now())
 
         // CONCURRENT, bounded. Checks are independent by contract: each answers
         // one question about the world or the repo and shares nothing with its
@@ -227,7 +244,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 +255,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 +267,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

@@ -17,17 +17,34 @@ export type DiscoveredCheck = {
     path: string
     /** display + cache name — file base, disambiguated by relative path on collision */
     name: string
-    /** file runs its own CheckSuite (own TTL cache) — the orchestrator must not double-cache it */
-    selfCached: boolean
     /** `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
 }
 
 // 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[] = []
@@ -48,16 +65,22 @@ export function discoverChecks(root: string): DiscoveredCheck[] {
     return files.map((f) => {
         const base = baseOf(f)
         const name = (seen.get(base) ?? 0) > 1 ? relative(root, f).slice(0, -SUFFIX.length) : base
-        // a check built on CheckSuite/PageValidator replays from its OWN
-        // 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, 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`
 }
@@ -65,18 +84,27 @@ export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     for (const id of FLOOR_IDS) {
         const override = c.defaults?.[id]
         if (override === false) { disabled.push(id); continue }
-        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
+        // a FULL override brings its own body and replaces the slot. One that
+        // brings none DECORATES whatever fills it, which is how a repo declares
+        // what its `test` script reads without restating the command: the read
+        // set is repo knowledge, the command is not.
+        if (override != null && (override.cmd != null || override.logic != null)) {
+            tasks.push({ ...override, id: override.id ?? id } as TaskDef)
+            sources[id] = 'repo.config override'
+            continue
+        }
         // ONE WAY IN: `<id>` routes to `shipkit ci --only <id>`, so the TOOL
         // body lives at `<id>:raw` and that is what the gate runs. Running the
         // routed script here would spawn the gate from inside itself, forever
+        const decorate = (t: TaskDef): TaskDef => (override == null ? t : { ...t, ...override, id })
         const raw = scripts[rawName(id)]
-        if (raw != null) { tasks.push({ id, cmd: ['bun', 'run', rawName(id)] }); sources[id] = 'package.json script'; continue }
-        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
+        if (raw != null) { tasks.push(decorate({ id, cmd: ['bun', 'run', rawName(id)] })); sources[id] = 'package.json script'; continue }
+        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push(decorate({ id, cmd: ['bun', 'run', id] })); sources[id] = 'package.json script'; continue }
         const b = builtinFloorTask(id, root)
         // a routed script with nothing behind it measures NOTHING, and the
         // reason must say that rather than `no '<id>' script`, which is false
         if (typeof b === 'string') unfilled.push({ id, reason: scripts[id] != null ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })
-        else { tasks.push(b.task); sources[id] = b.source }
+        else { tasks.push(decorate(b.task)); sources[id] = b.source }
     }
     return { tasks, disabled, unfilled, sources }
 }