rvlib-shipkit 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.
+- **The graphs section stops advertising a graph the server does not serve.** A repo without a `wiki/` dir, which every fresh `shipkit start` is, still got a `wiki graph` card, and opening it embedded the hub's own 404 body ("not found — the hub page is at /") inside the card. Routes, `/hub.json` tools and cards now read ONE `GraphMount[]` that `resolveHubDeps` resolves (`HubDeps.wikiGraph` and `HubDeps.agentGraph` are gone, `HubDeps.graphs` replaces both), instead of the collection re-deriving the wiki graph from the repo root. A graph that is not mounted has no card, and the test asserts every href the section advertises answers 200.
+
 ## 0.30.0
 
 - **The studio asset page is tools on one shared canvas, not tabs on a drawer.** Every metadata family is a toggleable TOOL: `oval`, `legs`, `size` (the geometry editor split into its parts), each repo `customPanel`, `asset json`, `roll meta`. Several can be on at once, the URL records the set (`#<assetId>?tools=a,b`, shareable, restored on load), and the last set per kind is remembered. Kit-declared TABS (`meta.tabs: [{ id, tools }]`) are one-click presets, validated at kit load (an undeclared panel OR an unknown tool id refuses, loud). Panel tools float as draggable cards ON the canvas (a drag clamps inside the stage), `customPanel({ anchor: 'bl' })` starts a card bottom-left, so switching a tab never reflows the stage, and the drawer, its tab row and the bottom json body are deleted. Toggling a custom editor on does fold the variants bar, the one deliberate reflow. Custom panels can draw on the art in place: `api.stageOverlay()` returns an element covering the displayed roll (the tint-mask painter paints THERE, controls stay in its floating card), `api.dropOverlays()` cleans up on unmount, and the host calls it. Variants (rolls) move to a thin resizable right bar (drag handle, width remembered, slim-rail collapse, auto-folds when a custom editor turns on). The prompt keeps its fold. The stage remeasures through a ResizeObserver, so overlays track the image through any layout change, not only window resizes.

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.30.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/graphs.ts

@@ -1,34 +1,32 @@
-// graphs collection — the mounted md graphs as CHECKED section entries:
-// each graph instance carries its lint state (orphans + dangling refs =
-// yellow with counts; clean = quiet). Custom wiki-graph providers (repos
-// with their own loader + their own lint) get a link-only instance — their
-// repo lint owns correctness, never double-judged here.
-import { existsSync } from 'fs'
-import { join } from 'path'
+// graphs collection — the MOUNTED md graphs as CHECKED section entries. The
+// mounts arrive as data from the hub's own route resolution (serve/run-serve),
+// never re-derived here: a card linking at an unmounted route renders the 404
+// body inside its iframe. Each instance carries its lint state (orphans +
+// dangling refs = yellow with counts; clean = quiet). A graph whose lint
+// belongs to another repo is link-only, never double-judged here.
 import { lintMd } from '../wiki/lint-md.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
 import type { Collection, Instance } from './collection-types.ts'
 
-export function graphsCollection(root: string, o: { customWiki: boolean; agentIndex?: string }): Collection {
+export function graphsCollection(mounts: GraphMount[]): Collection {
     return {
         id: 'graphs',
         title: 'graphs',
         media: 'data',
-        list: async () => {
-            const out: Instance[] = []
-            const checked = (id: string, title: string, href: string, dir: string, index?: string): Instance => {
-                const r = lintMd({ root: dir, index })
+        list: async () =>
+            mounts.map((m): Instance => {
+                const id = `graph:${m.id}`
+                const href = `/graph/${m.id}`
+                const label = m.note != null ? `${m.label} (${m.note})` : m.label
+                if (m.lint == null) return { id, text: label, href }
+                const r = lintMd({ root: m.lint.root, index: m.lint.index })
                 const issues = r.orphans.length + r.dangling.length
                 return {
                     id,
-                    text: issues === 0 ? title : `${title} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
+                    text: issues === 0 ? label : `${label} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
                     severity: issues === 0 ? undefined : 'yellow',
                     href,
                 }
-            }
-            if (o.customWiki) out.push({ id: 'graph:wiki', text: 'wiki graph (repo-owned lint)', href: '/graph/wiki' })
-            else out.push(checked('graph:wiki', 'wiki graph', '/graph/wiki', root))
-            if (existsSync(join(root, 'agent'))) out.push(checked('graph:agent', 'agent graph', '/graph/agent', join(root, 'agent'), o.agentIndex))
-            return out
-        },
+            }),
     }
 }

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