rvlib-shipkit 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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`.
+- **The output is the house dialect, not a second one.** `X.` Mantine globals rather than `@mantine/core` imports, `observer(function Name_())` around the form, the `{ record?, onClose }` props `CollectionUI['form']` actually declares, and `defineCollectionUI` called as the void statement it is. A generator that invents its own shape is worse than no generator: what it writes is what the next developer copies. `key` is set only where the server can really order by the column, so a joined multi-value cell no longer claims sortability it does not have, and an auth collection's `verified`, `email`, `username` and `emailVisibility` get no control, since PocketBase routes those through endpoints a plain patch never reaches.
+- **It refuses rather than half-writing.** No generated types, a file that is not typegen output, a collection the schema does not carry, one of PocketBase's own `_`-prefixed internals, a record block that is missing or unreadable, or a block where not one field parsed: each exits non-zero naming the file, the known collection names and the typegen command that produces them. A single field whose type is unrecognised is named in a `WARN` instead of quietly becoming a commented column. Writes are create-only: a path that already exists is reported and left byte for byte as it is, so a re-run after a schema change can never eat hand-written UI. `--dry-run` prints the plan AND every file body in full and touches nothing, which is what an agent should reach for first.
+- **A path shipkit generates is ignored AND untracked, in one operation.** `.gitignore` does nothing to a file that is already tracked, so a generated path that is only ignored keeps dirtying every tree forever and rides into unrelated commits as a mystery diff. Rule SK004 now FAILs while a declared generated path is still in the index, and its autofix removes it with `git rm --cached` and commits exactly that, `chore(machine): untrack <path>`, through the hooks. The file stays on disk. First customers: `STATUS.md`, `STATUS.md.lock` and `.STATUS.md.tmp-*`, which shipkit rewrites on every run and nothing ever reads a past version of. Only literal paths are removable, never a glob, because `git rm --cached` driven by a wildcard is how a fixer eats source. It refuses, by name, mid-merge, mid-rebase, on a detached HEAD, before the first commit, and whenever anything else is already staged, so the migration commit can never sweep up someone's work. A hook that rejects it restores the index rather than leaving a staged deletion behind, which is the failure mode it exists to stop. `--frozen` suppresses it and `untrackGenerated: false` opts a repo out.
+- **Two test tiers, and every run says which one it is.** `shipkit ci` runs the QUICK tier: pure logic, no child process, no repository on disk, so the working gate stays fast. `shipkit bump` and `shipkit release` always run the FULL tier, before the version commit, so a red suite aborts the release instead of leaving a half-published repo. `shipkit ci --full` (or `SHIPKIT_TEST_FULL=1`, which the gate sets for every task) runs it by hand. Both directions print a tier line and the test count actually run, because a log that does not name the tier cannot be told from one that quietly skipped half the suite.
+- Reading the schema is a LINE parse of generated code, not a TypeScript AST: shipkit carries no typescript dependency and typegen writes one field per line. Record blocks parameterised by a json field are handled, and so is a file a formatter has rewritten with trailing semicolons, which is the normal state of any repo whose formatter covers `src/**`.
+
 ## 0.31.0
 
 - **Every repo browses its shared wiki from its own hub.** A repo whose CLAUDE.md include chain points at a wiki living in another repo (`@~/dev/<other-repo>/wiki/index.md`, read from `CLAUDE.md`, `CLAUDE.local.md` or `CLAUDE.private.md`) mounts it at `/graph/base`, named after the repo that owns it. That wiki binds every agent working here, so the hub lets a human read it where the work happens. An index inside the repo is skipped, since it is already its own mount, and the card carries no lint verdict: the owning repo lints its own pages.

package/README.md

@@ -46,6 +46,9 @@ shipkit wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
 shipkit mv        rename an md page + its sibling dir, sweeping every ref
 shipkit assets    serve|fill|add|gen|identity|check — the asset atelier
                   (declare kinds in .rv-assets/kit.ts, roll, curate, ship)
+shipkit pb        collection <name> — scaffold a PocketBase collection's UI
+                  folder (columns/card/grid/form/index) from the app's
+                  generated pb types, create-only          [--dry-run]
 shipkit serve     the repo's ONE server: hub page, graphs, studio, status
 shipkit reflect   your prompts across every Claude Code session of a repo:
                   all config roots, queued-mid-run ones included, harness

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.31.0",
+    "version": "0.32.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/cli/cmd_Bump.ts

@@ -32,6 +32,7 @@ export class BumpCommand extends Command {
     dryRun = Option.Boolean('--dry-run', false, { description: 'rehearse: run every preflight, the gate and the prepublish scripts, then stop before any version is written. the gate can rewrite files, and the merge is probed rather than performed, so the release branch never moves' })
     noRelease = Option.Boolean('--no-release', false, { description: 'stop after the version commit, do not tag or publish' })
     noMerge = Option.Boolean('--no-merge', false, { description: 'refuse on a feature branch instead of merging it into the release branch' })
+    allowDirty = Option.Boolean('--allow-dirty', false, { description: "proceed with uncommitted changes inside what this release writes. Dirt in OTHER units is already ignored, so this is only for when the scoping judges wrong. A sub-unit's OWN directory still refuses, the same as `release`, and no flag lifts that: `npm publish` packs the WORKING TREE rather than the commit, so forcing past it ships the half-written file under a tag that describes something else" })
     all = Option.Boolean('--all', false, { description: 'bump every unit whose changelog carries Unreleased notes, in declared order, root last. Given a kind it applies to ALL of them. Given none, each unit takes the kind from its own "## Unreleased (minor)" heading, and a unit whose heading is silent refuses' })
 
     async execute(): Promise<number> {
@@ -51,6 +52,7 @@ export class BumpCommand extends Command {
                 noMerge: this.noMerge,
                 unit,
                 all: this.all,
+                allowDirty: this.allowDirty,
                 print: (l) => this.context.stdout.write(`${l}\n`),
             })
         } catch (e) {

package/src/cli/cmd_Ci.ts

@@ -24,10 +24,11 @@ export class CiCommand extends Command {
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
     fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
     fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural rule autofixes too. Default on. --no-fix-rules leaves repo config alone' })
-    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules (SK005 never touches package.json). STATUS.md is still refreshed, so no combination of flags makes the run write nothing' })
+    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
     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)' })
+    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> {
         // a stale toolkit updates itself and restarts this exact invocation
@@ -44,6 +45,7 @@ export class CiCommand extends Command {
                 skipGroups: this.skip,
                 withIds: this.withIds,
                 onlyIds: this.only,
+                ...(this.full ? { tests: 'full' as const } : {}),
                 print: (l) => this.context.stdout.write(`${l}\n`),
             })
         } catch (e) {

package/src/cli/cmd_Pb.ts

@@ -0,0 +1,27 @@
+// shipkit pb — scaffolding for a PocketBase app, run from THAT app's root.
+// Thin clipanion surface; the schema parse and the emitters live in pb/.
+import { Command, Option } from 'clipanion'
+import { runPbCollection } from '../pb/run-pb.ts'
+
+export class PbCollectionCommand extends Command {
+    static override paths = [['pb', 'collection']]
+
+    static override usage = Command.Usage({
+        category: 'Scaffold',
+        description: "a collection's CRUD UI folder from the app's generated pb types: columns, card, grid, form, index",
+        examples: [
+            ['see the whole folder before it exists', 'shipkit pb collection orders --dry-run'],
+            ['write src/collections/orders/', 'shipkit pb collection orders'],
+        ],
+    })
+
+    name = Option.String()
+    dryRun = Option.Boolean('--dry-run', false, { description: 'print every file in full, write nothing' })
+
+    async execute(): Promise<number> {
+        return runPbCollection(process.cwd(), this.name, {
+            print: (l) => this.context.stdout.write(`${l}\n`),
+            printErr: (l) => this.context.stderr.write(`${l}\n`),
+        }, { dryRun: this.dryRun })
+    }
+}

package/src/cli/cmd_Release.ts

@@ -20,7 +20,7 @@ export class ReleaseCommand extends Command {
 
     unit = Option.String({ required: false })
     dryRun = Option.Boolean('--dry-run', false, { description: 'run every preflight and print the plan, change nothing' })
-    allowDirty = Option.Boolean('--allow-dirty', false, { description: 'release from an unclean tree (the tag will not contain it). A SUB-unit still refuses on dirt inside its own path' })
+    allowDirty = Option.Boolean('--allow-dirty', false, { description: 'release from an unclean tree (the tag will not contain it). Safe for dirt in OTHER paths only: `npm publish` packs the WORKING TREE, not the commit, so a SUB-unit still refuses on dirt inside its own path rather than ship a half-written file under a tag that describes something else' })
     skipGate = Option.Boolean('--skip-gate', false, { description: 'skip the ci gate preflight — publishes unverified, use only to recover a stuck release' })
 
     async execute(): Promise<number> {

package/src/cli/cmd_Wiki.ts

@@ -27,7 +27,7 @@ export class WikiServeCommand extends Command {
             this.context.stderr.write(`FAIL --port '${this.port}' is not a port number\n`)
             return 1
         }
-        return runWikiServe({ root: this.root, index: this.index, skip: this.skip, port, title: this.title })
+        return runWikiServe({ root: this.root, index: this.index, skip: this.skip, port, title: this.title, print: (l) => this.context.stdout.write(`${l}\n`) })
     }
 }
 
@@ -48,6 +48,6 @@ export class WikiLintCommand extends Command {
     skip = Option.String('--skip', { required: false, description: 'comma-separated dir names to exclude from the scan' })
 
     async execute(): Promise<number> {
-        return runWikiLint({ root: this.root, index: this.index, skip: this.skip })
+        return runWikiLint({ root: this.root, index: this.index, skip: this.skip, print: (l) => this.context.stdout.write(`${l}\n`) })
     }
 }

package/src/cli.ts

@@ -15,6 +15,7 @@ import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreC
 import { InitCommand } from './cli/cmd_Init.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
+import { PbCollectionCommand } from './cli/cmd_Pb.ts'
 import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
@@ -26,44 +27,53 @@ import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
 const version = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
 
-const cli = new Cli({
-    binaryLabel: 'shipkit — repo toolkit',
-    binaryName: 'shipkit',
-    binaryVersion: version,
-    enableCapture: true, // console output pipes into the command streams (testable)
-    enableColors: true,
-})
+/** the registry, built but NOT run: a test drives the real binary in process
+ *  instead of paying a cold bun start per assertion (~250ms each), and the
+ *  wiring it exercises is the wiring that ships. */
+export function buildCli(): Cli {
+    const cli = new Cli({
+        binaryLabel: 'shipkit — repo toolkit',
+        binaryName: 'shipkit',
+        binaryVersion: version,
+        enableCapture: true, // console output pipes into the command streams (testable)
+        enableColors: true,
+    })
 
-cli.register(Builtins.HelpCommand)
-cli.register(Builtins.VersionCommand)
-cli.register(CiCommand)
-cli.register(BumpCommand)
-cli.register(ReleaseCommand)
-cli.register(ReleasesCommand)
-cli.register(HooksInstallCommand)
-cli.register(HooksPreCommitCommand)
-cli.register(HooksCommitMsgCommand)
-cli.register(HooksListCommand)
-cli.register(MvCommand)
-cli.register(CheckCommand)
-cli.register(TuiCommand)
-cli.register(ServeCommand)
-cli.register(ContractsCommand)
-cli.register(AsksCommand)
-cli.register(AsksCheckCommand)
-cli.register(AskNewCommand)
-cli.register(WikiServeCommand)
-cli.register(WikiLintCommand)
-cli.register(AssetsFillCommand)
-cli.register(AssetsAddCommand)
-cli.register(AssetsGenCommand)
-cli.register(AssetsIdentityCommand)
-cli.register(AssetsCheckCommand)
-cli.register(InitCommand)
-cli.register(StartCommand)
-cli.register(NeedsCommand)
-cli.register(ReflectCommand)
-cli.register(RulesCommand)
-cli.register(CommandsCommand)
+    cli.register(Builtins.HelpCommand)
+    cli.register(Builtins.VersionCommand)
+    cli.register(CiCommand)
+    cli.register(BumpCommand)
+    cli.register(ReleaseCommand)
+    cli.register(ReleasesCommand)
+    cli.register(HooksInstallCommand)
+    cli.register(HooksPreCommitCommand)
+    cli.register(HooksCommitMsgCommand)
+    cli.register(HooksListCommand)
+    cli.register(MvCommand)
+    cli.register(CheckCommand)
+    cli.register(TuiCommand)
+    cli.register(ServeCommand)
+    cli.register(ContractsCommand)
+    cli.register(AsksCommand)
+    cli.register(AsksCheckCommand)
+    cli.register(AskNewCommand)
+    cli.register(WikiServeCommand)
+    cli.register(WikiLintCommand)
+    cli.register(AssetsFillCommand)
+    cli.register(AssetsAddCommand)
+    cli.register(AssetsGenCommand)
+    cli.register(AssetsIdentityCommand)
+    cli.register(AssetsCheckCommand)
+    cli.register(InitCommand)
+    cli.register(StartCommand)
+    cli.register(NeedsCommand)
+    cli.register(PbCollectionCommand)
+    cli.register(ReflectCommand)
+    cli.register(RulesCommand)
+    cli.register(CommandsCommand)
 
-cli.runExit(process.argv.slice(2))
+    return cli
+}
+
+// only when this file IS the process, so importing it costs nothing
+if (import.meta.main) void buildCli().runExit(process.argv.slice(2))

package/src/collections/providers.ts

@@ -13,7 +13,10 @@ import { join } from 'path'
 import { isStale } from '../assets/gen/derived.ts'
 import { allAssets, mediaOf, type ResolvedKit } from '../assets/kit-config.ts'
 import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
-import { healIdentity } from '../assets/run-assets.ts'
+// TYPE only, plus a lazy import at the call site. run-assets pulls the comfy
+// runtime and the canvas binding, ~400ms of module load, and the hub's
+// collection list is built on every request by callers that mostly never heal
+import type { healIdentity } from '../assets/run-assets.ts'
 import { doneAsks, openAsks } from '../asks/asks-queue.ts'
 import { evaluateContracts } from '../contracts/contracts-engine.ts'
 import { parseWireOutput } from '../core/wire.ts'
@@ -171,7 +174,9 @@ const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { se
  *  Identity self-heals BEFORE surfacing; manual with nothing uploaded =
  *  red (provide); rolls with no pick = yellow (a default exists, taste
  *  pending — auto-pick-first is blessed); stale = yellow. */
-export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal: typeof healIdentity = healIdentity): Collection {
+const healLazily: typeof healIdentity = async (root) => (await import('../assets/run-assets.ts')).healIdentity(root)
+
+export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal: typeof healIdentity = healLazily): Collection {
     return {
         id: 'media',
         title: 'assets',

package/src/contracts/contracts-once.ts

@@ -0,0 +1,43 @@
+// ONE contract evaluation per gate run.
+//
+// Two surfaces report fulfillness inside a single `shipkit ci`: the `contracts`
+// TASK, which exists because deploy tasks declare `deps: ['contracts']` and so
+// need a real ordering edge in the DAG, and rule SK002, which exists because a
+// `shipkit check` with no task phase must still report it. Both are load
+// bearing and neither can be deleted: dropping the task would silently ungate
+// every deploy that depends on it, since checks run AFTER every task.
+//
+// So they stay two REPORTS of one evaluation. The task runs first and its
+// result is what SK002 reads. THE TASK IS AUTHORITATIVE (contracts.md says so
+// too); SK002 evaluating on its own is the fallback for a run with no task
+// phase, not a second opinion.
+//
+// The scope is EXPLICIT and never ambient. A memo that outlived its run would
+// let the hub, which rebuilds its collection list on every request, answer
+// from a snapshot of whatever the last gate saw. Only a caller that owns a run
+// opens one.
+import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts-engine.ts'
+import type { ContractManifest } from './contract-types.ts'
+
+let open = false
+let cached: { key: string; result: Promise<ContractsResult> } | null = null
+
+/** run `fn` as ONE gate run: contract evaluation inside it happens once. */
+export async function withContractsScope<T>(fn: () => Promise<T>): Promise<T> {
+    const outer = open
+    open = true
+    try { return await fn() } finally { if (!outer) { open = false; cached = null } }
+}
+
+/** the evaluation, memoised only while a run scope is open. Outside one it is
+ *  a plain call, so `shipkit contracts` and the hub always measure reality. */
+export function evaluateContractsOnce(manifests: ContractManifest[], cfg: ContractsConfig): Promise<ContractsResult> {
+    if (!open) return evaluateContracts(manifests, cfg)
+    // the config decides the verdict, so it belongs in the identity: a run that
+    // somehow evaluated two different configs must not serve one for the other
+    const key = JSON.stringify(cfg)
+    if (cached != null && cached.key === key) return cached.result
+    const result = evaluateContracts(manifests, cfg)
+    cached = { key, result }
+    return result
+}

package/src/core/canonical-scripts.ts

@@ -30,6 +30,39 @@ export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, strin
     }
 }
 
+// ONE WAY IN (build/shipkit.md): the verification verbs an agent types from
+// muscle memory ROUTE to shipkit, so `bun run test` gets the cache and the
+// job attachment without anyone having to remember a rule. The tool body they
+// used to hold moves to `<name>:raw`, which is what shipkit itself runs and
+// what an agent uses to iterate on one repro file.
+//
+// only these three. `imports:check` and `cycles` are shipkit's own vocabulary
+// (nobody reaches for them by reflex) and `fmt` is the slot shipkit's fix pass
+// invokes, so routing it would make the fixer call itself.
+export const ROUTED_SCRIPTS = ['test', 'lint', 'typecheck'] as const
+
+export const RAW_SUFFIX = ':raw'
+
+/** where the tool body lives once `<id>` routes to shipkit */
+export const rawName = (id: string): string => `${id}${RAW_SUFFIX}`
+
+/** what a routed `<id>` script says. `--only` narrows to the one question the
+ *  name promises: `bun run test` must not become a full gate behind the
+ *  agent's back */
+export function routedBody(id: string, opts: ScriptStyle = {}): string {
+    return `${opts.bin != null ? `bun ${opts.bin}` : 'shipkit'} ci --only ${id}`
+}
+
+/** does this body hand the question to `shipkit ci` rather than to a tool ?
+ *  every invocation form counts: the bin, `bunx rvlib-shipkit`, an in-repo
+ *  `…/cli.ts` path. A body that does is never run AS a floor task, on pain of
+ *  infinite recursion. The `ci` half is load-bearing: a body that merely lives
+ *  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)
+}
+
 // recover the consumption style from existing scripts: any shipkit command
 // already running `bun <path>/cli.ts <cmd>` fixes the style for new bodies
 export function inferBin(scripts: Record<string, string>): string | undefined {

package/src/core/check-ctx.ts

@@ -13,10 +13,23 @@ export class CheckCtx {
     lines: Line[] = []
     failed = false
     warned = false
+    /** 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
+     *  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>) {}
 
     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
+     *  nothing to remember */
+    unreachable(msg: string, fix?: string): void {
+        this.unmeasured = true
+        this.warn(msg, fix)
+    }
     warn(msg: string, fix?: string): void {
         this.warned = true
         this.lines.push({ kind: 'warn', text: msg })

package/src/core/check-suite.ts

@@ -15,8 +15,9 @@ 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 }
-type CacheFile = Record<string, { version: number; key: string; at: number; lines: Line[] }>
+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
 
@@ -61,8 +62,12 @@ export class CheckSuite {
         this.onResult = opts.onResult
     }
 
-    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic }): void {
-        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic })
+    /** `blocking` decides what a NEGATIVE result may be cached as: see the
+     *  measured-negative rule in execute(). Default true, the safe side: a
+     *  check that never declared itself is treated as being about this repo,
+     *  so its failures are never replayed. */
+    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic; blocking?: boolean }): void {
+        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic, blocking: spec.blocking ?? true })
     }
 
     defineRequiredTool(name: string, opts: { candidates?: string[]; probe?: { args: string[]; expect?: RegExp }; fix: string }): void {
@@ -97,6 +102,12 @@ export class CheckSuite {
         const validate = spec.validate as (v: unknown, t: CheckCtx) => unknown
         let payload: unknown
         this.runners.push({
+            // conservative on purpose: a secret probe keeps today's behaviour,
+            // where no negative is remembered. Its cache key already hashes the
+            // secret VALUE, so a rotation busts it, which would make caching a
+            // measured 403 sound. That is a severity call for whoever owns the
+            // secrets surface, not a side effect of this change.
+            blocking: true,
             // bare secret name — this shows up in human-facing WARN/FAIL lines
             name: names.length === 1 ? primary : primary.split('/').slice(0, 2).join('/') + '/*',
             ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0,
@@ -118,65 +129,122 @@ export class CheckSuite {
     }
 
     // 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 }> {
+        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 }
+        }
+        const key = prep.cacheExtra ?? ''
+        const entry = cache[r.name]
+        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
+        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
+            // later replay render the same string, and the line changes
+            // only when a re-validation happens. Annotating replays but
+            // not live runs still diffed on every fresh-vs-cached
+            // 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 t = new CheckCtx(this.toolPaths)
+        try {
+            await r.logic(t)
+        } catch (e) {
+            // both of these mean the probe never reached its subject, so the
+            // run has no answer to remember
+            if (e instanceof RateLimited) t.unreachable(`${r.name} not validated this run (${e.message}) — retry later`)
+            else if (e instanceof ToolUnresolved) { t.unmeasured = true; t.note(`${r.name} skipped (${e.message})`) }
+            else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
+        }
+        // AN ANSWER CACHES. THE ABSENCE OF ONE DOES NOT. That distinction, not
+        // pass-versus-fail, is what decides cacheability here, and a future
+        // reader is warned off "fixing" the asymmetry:
+        //
+        //   measured negative  a probe that RAN and came back bad ("the box is
+        //                      off", "the token answered 403", "five repos are
+        //                      uncatalogued") is a real answer about the world.
+        //                      Replaying it for its TTL is CORRECT: the world
+        //                      does not fix itself between two gate runs, and
+        //                      re-asking every 30 seconds spends a third-party
+        //                      API call to be told the same thing.
+        //   unmeasured         a probe that could not run at all ("registry
+        //                      unreachable", "no cred", "rate limited", tool
+        //                      missing) produced no answer. Caching it asserts
+        //                      a dead network as fact long after it recovered.
+        //                      `skip` lines and the unmeasured flag mark these.
+        //
+        // A measured negative caches ONLY for a check about the WORLD. A
+        // blocking check reports THIS REPO, where the whole point is that a
+        // human fixes it and the next run goes green: replaying its red for a
+        // TTL would be the cache lying about work already done.
+        const unmeasured = t.unmeasured || t.lines.some((l) => l.kind === 'skip')
+        const clean = !t.failed && !t.warned
+        const cacheable = r.ttlMs > 0 && !unmeasured && (clean || !r.blocking)
+        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,
+            // 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,
+        }
+    }
+
     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
 
+        // CONCURRENT, bounded. Checks are independent by contract: each answers
+        // one question about the world or the repo and shares nothing with its
+        // neighbours, and most of the wall time is a network round trip or a
+        // cold `bun` start. In series, twenty checks cost the SUM; together
+        // they cost the slowest one. Measured on this repo: 18.4s to 6.0s.
+        // Order is preserved by collecting per runner and concatenating in
+        // declaration order, so the wire output is byte-identical to the
+        // sequential run and the frozen contract still holds.
+        const cap = Math.max(2, Math.min(8, navigator.hardwareConcurrency || 4))
+        const results = new Array<Awaited<ReturnType<CheckSuite['runOne']>>>(this.runners.length)
+        let next = 0
+        const worker = async (): Promise<void> => {
+            for (;;) {
+                const i = next++
+                if (i >= this.runners.length) return
+                results[i] = await this.runOne(this.runners[i]!, cache)
+            }
+        }
+        await Promise.all(Array.from({ length: Math.min(cap, this.runners.length) }, () => worker()))
+
         const out: Line[] = []
         const skipped: string[] = []
         let ran = 0
         let anyFail = false
-
-        for (const r of this.runners) {
-            const prep = r.prep?.() ?? {}
-            if (prep.skip != null) {
-                skipped.push(prep.skip)
-                this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
-                continue
-            }
-            ran++
-            const key = prep.cacheExtra ?? ''
-            const entry = cache[r.name]
-            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
-            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
-                // later replay render the same string, and the line changes
-                // only when a re-validation happens. Annotating replays but
-                // not live runs still diffed on every fresh-vs-cached
-                // alternation, so neither side annotates
-                out.push(...entry.lines)
-                this.onResult?.(r.name, { lines: entry.lines, status: 'pass', cached: true }) // only clean passes are cached
-                continue
-            }
-            const t = new CheckCtx(this.toolPaths)
-            try {
-                await r.logic(t)
-            } catch (e) {
-                if (e instanceof RateLimited) t.warn(`${r.name} not validated this run (${e.message}) — retry later`)
-                else if (e instanceof ToolUnresolved) t.note(`${r.name} skipped (${e.message})`)
-                else t.fail(`${r.name} errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
-            }
-            // a skip line is an UNKNOWN, not a clean pass — replaying
-            // "registry unreachable" for a TTL asserts a dead network as
-            // fact long after it recovered
-            const cacheable = r.ttlMs > 0 && !t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')
-            const lines = cacheable
-                ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
-                : t.lines
-            out.push(...lines)
-            this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
-            if (t.failed) anyFail = true
-            if (r.ttlMs > 0) {
-                if (cacheable) { cache[r.name] = { version: r.version, key, at: this.now(), lines }; cacheDirty = true }
-                // a WARN/FAIL evicts the stale pass — a later run must re-probe,
-                // not replay an ok recorded before the breakage
-                else if (entry != null) { delete cache[r.name]; cacheDirty = true }
-            }
+        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