rvlib-shipkit 0.34.0 → 0.35.1

package/src/ledger/ledger.ts

@@ -0,0 +1,202 @@
+// THE LEDGER — the CONTENT half of the three populations: a unit's answer,
+// stored under the identity of the question it answered, replayed only when
+// that identity is bit-for-bit the same question again.
+//
+// ledger/git-key.ts owns the identity, ledger/store.ts owns the file. This
+// module owns the POLICY, and the policy is where a cache turns into a false
+// green, so every rule below exists because a specific failure was reproduced
+// during the design pass:
+//
+//  1. DEFAULT DENY. A unit that declared nothing is never replayed and never
+//     stored. Forgetting to declare costs speed, never correctness, which is
+//     what makes the burn-down a to-do rather than a hazard.
+//  2. POST RUN RE HASH. Results are BUFFERED while the gate runs and written
+//     only after the inputs are hashed a second time. A unit whose inputs
+//     moved between its run and that second hash answered about a tree that no
+//     longer exists, so its result is discarded rather than stored under a key
+//     that describes the file as it was BEFORE the edit. Three agents in one
+//     checkout is the normal case here, so that window is not theoretical.
+//  3. THE GATE BINARY IS IN THE KEY. Editing shipkit moves every key in every
+//     repo (ledger/toolchain-identity.ts content-hashes the cli tree).
+//  4. RELEASE NEVER READS IT. `bump` and `release` pass read:false, not
+//     configurably. Every remaining hole is then capped at "an agent saw a
+//     stale local green", never "a stale green authorised a publish".
+//  5. NO SILENT REPLAY. Every replayed line is stamped with the word
+//     `replayed` and what the measured run cost, and the run prints hit, miss
+//     and uncacheable counts. A cached green that cannot be told from a
+//     measured green is the bug this whole design exists to not ship.
+//  6. ONLY A GREEN REPLAYS. A red is the one outcome an agent acts on
+//     immediately, and acting on it changes content, which moves the key — so
+//     replaying a red buys almost nothing, while an undeclared flake would
+//     pin its red until something unrelated happened to change. The safe
+//     direction here is re-measuring, and it costs only the run that was
+//     already going red.
+import type { RvtConfig } from '../ts/config.ts'
+import type { Line } from '../core/wire.ts'
+import { KeyLayer, type UnitDecl, type UnitKey } from './git-key.ts'
+import { entryPath, FRESH_ENV, KEEP_MS, readStored, storeRoot, sweepStore, writeStored } from './store.ts'
+
+/** the env var that turns the READ path on or off for a whole session.
+ *  Writing is unconditional either way: an entry nobody reads breaks nothing. */
+export const LEDGER_ENV = 'SHIPKIT_LEDGER'
+
+/** where unit results live inside the one store */
+const NS = 'units'
+
+/** whether the read path is on by default, before any flag.
+ *
+ *  It shipped OFF and ran that way while two other efforts gated in this
+ *  checkout, because a bug here would have handed one of them a green nobody
+ *  measured. It went ON once eleven scenarios pinned the failure modes, a race
+ *  of five real gates on one checkout agreed on one verdict, and the dark run
+ *  had turned up and fixed a false green in the key layer that predates it.
+ *  `SHIPKIT_LEDGER=0` turns it off for a session, and this line is the revert. */
+export const READ_DEFAULT = true
+
+export type UnitOutcome = {
+    /** only a green is ever stored (rule 6 above) */
+    status: 'pass' | 'warn'
+    lines: Line[]
+    /** the task-runner headline, which the gate greps for the test count */
+    lastLine?: string
+    /** what the measured run cost, ms — printed on the replay so a hit says
+     *  what it saved instead of pretending the work was free */
+    measuredMs: number
+}
+
+export type LedgerOpts = {
+    /** the cli entry driving this run (toolchain identity needs it) */
+    cliEntry: string
+    /** read the store at all. false = every unit is measured this run. */
+    read?: boolean
+    /** this run re-measures everything, and re-stores what it measured */
+    fresh?: boolean
+    /** module-graph config, loaded from the repo when omitted */
+    cfg?: RvtConfig
+    now?: () => number
+}
+
+export type CommitReport = {
+    /** unit ids written to the store */
+    stored: string[]
+    /** unit ids whose result was thrown away because an input moved */
+    discarded: string[]
+    /** the paths that moved */
+    drifted: string[]
+    /** the re-hash itself failed; nothing was stored */
+    error: string | null
+    ms: number
+}
+
+/** is the read path on for this process? A run may still turn it off. */
+export function ledgerReadEnabled(): boolean {
+    const v = process.env[LEDGER_ENV]
+    if (v === '1' || v === 'true') return true
+    if (v === '0' || v === 'false') return false
+    return READ_DEFAULT
+}
+
+export class Ledger {
+    private readonly buffered = new Map<string, UnitOutcome>()
+    private readonly keys = new Map<string, UnitKey>()
+    private hits = 0
+    private misses = 0
+    private unkeyed = 0
+
+    private constructor(
+        readonly layer: KeyLayer,
+        private readonly store: string,
+        /** replays are allowed */
+        readonly reading: boolean,
+        private readonly now: () => number,
+    ) {}
+
+    static open(root: string, decls: UnitDecl[], o: LedgerOpts): Ledger {
+        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg })
+        const fresh = o.fresh === true || process.env[FRESH_ENV] != null
+        const reading = (o.read ?? ledgerReadEnabled()) && !fresh
+        return new Ledger(layer, storeRoot(root), reading, o.now ?? Date.now)
+    }
+
+    /** the key for a unit, computed once per run and remembered: `keyFor`
+     *  re-derives the component list every call, and the gate asks twice (once
+     *  to replay, once to record). */
+    private key(id: string): UnitKey {
+        let k = this.keys.get(id)
+        if (k == null) { k = this.layer.keyFor(id); this.keys.set(id, k) }
+        return k
+    }
+
+    private path(k: UnitKey): string {
+        return entryPath(this.store, NS, `${k.kind}:${k.id}`, k.key!)
+    }
+
+    /** the stored answer for this unit, or null when it must run. Counts what
+     *  it was asked, so the run can report hit/miss/uncacheable honestly. */
+    replay(id: string): UnitOutcome | null {
+        const k = this.key(id)
+        if (k.key == null) { this.unkeyed++; return null }
+        if (!this.reading) { this.misses++; return null }
+        const e = readStored<UnitOutcome>(this.path(k), k.key)
+        if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
+        this.hits++
+        return e.payload
+    }
+
+    /** buffer what a unit just measured. Nothing reaches the store until
+     *  commit() has re-hashed the inputs (rule 2). */
+    record(id: string, outcome: UnitOutcome): void {
+        const k = this.key(id)
+        if (k.key == null) return
+        this.buffered.set(id, outcome)
+    }
+
+    /** re-hash, then write what still describes the tree on disk. */
+    commit(): CommitReport {
+        const empty: CommitReport = { stored: [], discarded: [], drifted: [], error: null, ms: 0 }
+        if (this.buffered.size === 0) return empty
+        const started = performance.now()
+        const d = this.layer.rescan()
+        if (d.error != null) return { ...empty, discarded: [...this.buffered.keys()].sort(), error: d.error, ms: performance.now() - started }
+        const touched = this.layer.unitsTouchedBy(d.drifted)
+        const stored: string[] = []
+        const discarded: string[] = []
+        for (const [id, outcome] of this.buffered) {
+            if (touched.has(id)) { discarded.push(id); continue }
+            const k = this.key(id)
+            writeStored(this.path(k), k.key!, outcome, this.now())
+            stored.push(id)
+        }
+        sweepStore(this.store, NS, this.now(), KEEP_MS)
+        return { stored: stored.sort(), discarded: discarded.sort(), drifted: d.drifted, error: null, ms: performance.now() - started }
+    }
+
+    get counts(): { hit: number; miss: number; uncacheable: number } {
+        return { hit: this.hits, miss: this.misses, uncacheable: this.unkeyed }
+    }
+
+    /** the one line a run prints about its own cache. Never silent: a run that
+     *  replayed nothing says so, so a green is always attributable. */
+    header(commit: CommitReport): Line[] {
+        const c = this.counts
+        const asked = c.hit + c.miss + c.uncacheable
+        if (asked === 0) return []
+        const out: Line[] = []
+        // `skip:` and not a bare note: the ci wire prefixes are a frozen
+        // contract every agent and every parser reads, and these lines are
+        // exactly what the run did NOT measure
+        const mode = this.reading ? '' : this.layer.failure != null ? ', reads off because the git scan failed' : ', reads off'
+        out.push({ kind: 'skip', text: `ledger — ${c.hit} replayed, ${c.miss} measured, ${c.uncacheable} uncacheable${mode}` })
+        if (commit.error != null) out.push({ kind: 'warn', text: `ledger stored nothing this run — the post-run re-hash failed: ${commit.error}` })
+        else if (commit.discarded.length > 0)
+            out.push({ kind: 'skip', text: `ledger stored nothing for ${commit.discarded.length} unit(s) — ${commit.drifted.slice(0, 3).join(', ')}${commit.drifted.length > 3 ? ` +${commit.drifted.length - 3} more` : ''} moved while the gate ran` })
+        return out
+    }
+}
+
+/** stamp a replayed unit's lines. The FIRST line carries the word, because
+ *  that is the line an agent reads, and a replay that renders identically to a
+ *  measurement is the one thing this design refuses to ship. */
+export function stampReplayed(lines: Line[], measuredMs: number): Line[] {
+    return lines.map((l, i) => (i === 0 ? { ...l, text: `${l.text} (replayed, ${(measuredMs / 1000).toFixed(1)}s saved)` } : l))
+}

package/src/ledger/store.ts

@@ -0,0 +1,122 @@
+// ONE STORE. Everything this toolkit remembers between runs lives here, in
+// one shape, under one root, busted by one flag.
+//
+// There used to be two: `tmp/.shipkit-cache` for the check orchestrator and
+// `tmp/.check-cache` for the page checks, each with its own bust env var, each
+// per worktree. Two stores means two staleness windows over one question, and
+// the stamps in this repo's own history went BACKWARDS between checkouts
+// because of it. This module is the single mechanism; what differs between
+// populations is the KEY, never the storage.
+//
+// THE SHAPE, unchanged from the check cache slice 2 landed and proved:
+// one immutable file per key, named by the key, written tmp + rename. No
+// lock, no merge, no read-modify-write, and no prune of another runner's
+// entries. Three agents in one checkout is the normal case, so the only safe
+// aggregate is no aggregate: a run with a different key writes a DIFFERENT
+// file, a run with the same key replaces its own whole answer or none of it,
+// and housekeeping sweeps by AGE, which needs no knowledge of what the
+// current run knows about.
+//
+// WHERE. `<git-common-dir>/shipkit/store/`, which is SHARED by every linked
+// worktree of the repo. That is safe only because no key component is a path:
+// the toolchain identity content-hashes the gate binary and every installed
+// package, so two worktrees carrying different installs produce different
+// keys and simply miss each other (ledger/toolchain-identity.ts owns the
+// measurement). It is also outside the work tree, so nothing here can dirty a
+// diff or reach a commit.
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+
+/** the storage FORMAT. Bumped when the envelope changes, so an old file can
+ *  never be handed to a new reader. The KEY carries everything about the
+ *  question; this is only about the file around it. */
+export const STORE_VERSION = 1
+
+/** the ONE env var that busts every remembered answer, content or TTL. */
+export const FRESH_ENV = 'SHIPKIT_FRESH'
+
+/** one remembered answer. `key` is stored as well as hashed into the file
+ *  name, and re-checked on read: a name collision must miss, never serve a
+ *  neighbour's answer. */
+export type Stored<T> = {
+    v: number
+    key: string
+    /** when it was written, ms since epoch */
+    at: number
+    payload: T
+}
+
+/** how long a superseded entry survives. Far past the longest TTL any check
+ *  declares, so a live entry is never swept out from under a replay. */
+export const KEEP_MS = 30 * 24 * 60 * 60 * 1000
+
+/** where this repo's remembered answers live.
+ *
+ *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
+ *  git dir but shares the common one, and slice 3 measured that sharing is
+ *  SAFE here because every key component is content or a version string.
+ *  A tree that is not a git repo at all still gets a store, under `tmp/`,
+ *  because a scaffold in progress must not crash on it. */
+export function storeRoot(root: string): string {
+    const p = Bun.spawnSync(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const dir = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+    return dir === '' ? join(root, 'tmp/.shipkit-store') : join(dir, 'shipkit/store')
+}
+
+const slug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
+
+/** where ONE answer lives. The key is in the file NAME, so a run whose key
+ *  moved writes a new file instead of rewriting the old one, and two runners
+ *  with different keys never collide. `ns` keeps populations apart so a sweep
+ *  or a manual `rm` can be scoped. */
+export function entryPath(store: string, ns: string, name: string, key: string): string {
+    const h = new Bun.CryptoHasher('sha256').update(`${ns}\0${name}\0${key}`).digest('hex').slice(0, 12)
+    return join(store, slug(ns), `${slug(name)}.${h}.json`)
+}
+
+/** a missing or half-written file reads as "no answer", which is the safe
+ *  side: the unit runs. tmp + rename means half-written cannot happen from a
+ *  shipkit write, so this only ever catches a truncated file from something
+ *  else, and treats it the same way. */
+export function readStored<T>(path: string, key: string): Stored<T> | null {
+    try {
+        const e = JSON.parse(readFileSync(path, 'utf8')) as Partial<Stored<T>>
+        if (e.v !== STORE_VERSION || e.key !== key || typeof e.at !== 'number' || e.payload == null) return null
+        return e as Stored<T>
+    } catch { return null }
+}
+
+export function writeStored<T>(path: string, key: string, payload: T, at: number): void {
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, payload }))
+    } catch {
+        // a store that cannot be written is slow, never wrong: the answer was
+        // already printed, and the next run measures again
+    }
+}
+
+export function dropStored(path: string): void {
+    try { rmSync(path, { force: true }) } catch { /* raced with another runner: it is gone either way */ }
+}
+
+/** age-based housekeeping. Sweeping by "the units I know about" is what made
+ *  the old prune wrong: a run narrowed with --only knows about one unit and
+ *  would delete the other sixty-five. */
+export function sweepStore(store: string, ns: string, now: number, keepMs = KEEP_MS): void {
+    const dir = join(store, slug(ns))
+    const cutoff = now - keepMs
+    try {
+        for (const f of readdirSync(dir)) {
+            // `.<name>.tmp-<pid>` is what atomicWrite lands beside its target,
+            // and a writer killed between the write and the rename leaves one
+            // behind. Sweeping only *.json accreted them without bound.
+            if (!f.endsWith('.json') && !/\.tmp-\d+$/.test(f)) continue
+            const p = join(dir, f)
+            try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+        }
+    } catch {
+        // no dir yet, or unreadable: housekeeping never fails a run
+    }
+}

package/src/ledger/toolchain-identity.ts

@@ -75,6 +75,36 @@ function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
     h.update(`clifiles=${files.length}\n`)
 }
 
+/**
+ * what ONE install holds, as a hash: every top-level package's name, version
+ * and link target.
+ *
+ * Exported because a repo's own install is not the only one a gate can run
+ * against. Sub-packages carry their own `node_modules`, gitignored like every
+ * other, so no git key can see them and the root toolchain does not describe
+ * them either. A unit whose declared inputs COVER such a directory folds this
+ * in beside the path, or the toolchain component stops at the repo root while
+ * the task it is meant to describe does not.
+ *
+ * ~2ms per install, and only for a path a scan already reported as ignored.
+ */
+export function installIdentity(nodeModules: string): string {
+    if (!existsSync(nodeModules)) return 'install=absent'
+    const h = createHash('sha256')
+    let names: string[] = []
+    try { names = installedNames(nodeModules) } catch { return 'install=unreadable' }
+    for (const n of names) {
+        const dir = join(nodeModules, n)
+        let version = 'MISSING'
+        try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
+        let link = ''
+        try { if (lstatSync(dir).isSymbolicLink()) link = `->${realpathSync(dir)}` } catch {}
+        h.update(`${n}@${version}${link}\n`)
+    }
+    h.update(`n=${names.length}\n`)
+    return `install=${h.digest('hex').slice(0, 16)}`
+}
+
 /**
  * the identity of the program about to run, for `repoRoot`, driven by `cliEntry`.
  *

package/src/pb/collection-scaffold.ts

@@ -101,7 +101,7 @@ function columnsFile(col: PbCollection): string {
     lines.push('// means the cell is derived and the database cannot order by it.')
     lines.push('// labels are plain text, swap them for i18n.t.<collection>.<field> when the')
     lines.push('// app carries a dict.')
-    lines.push(`import type { Column } from "rvlib-pb-shell"`)
+    lines.push(`import type { Column } from "rvlib-pb/ui"`)
     lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
     lines.push('')
     lines.push(`export const columns: Column<${col.prefix}Response>[] = [`)
@@ -144,8 +144,8 @@ function gridFile(col: PbCollection): string {
     return [
         `// the default grid for \`${col.name}\`. A page that wants the plain table renders`,
         '// this; a page that wants extra columns passes its own to LiveGrid directly.',
-        `import type { LiveList } from "rvlib-pb-mobx"`,
-        `import { LiveGrid } from "rvlib-pb-shell"`,
+        `import type { LiveList } from "rvlib-pb"`,
+        `import { LiveGrid } from "rvlib-pb/ui"`,
         `import type { ${col.prefix}Response } from "${TYPES}"`,
         `import { columns } from "./columns"`,
         '',
@@ -247,7 +247,7 @@ function indexFile(col: PbCollection, hasForm: boolean): string {
     lines.push('// registration: after this import, a LiveGrid or LiveCards over')
     lines.push(`// \`${col.name}\` with no columns of its own knows what to render, and any`)
     lines.push('// relation cell pointing AT one knows how to name it.')
-    lines.push(`import { defineCollectionUI } from "rvlib-pb-shell"`)
+    lines.push(`import { defineCollectionUI } from "rvlib-pb/ui"`)
     lines.push(`import { db } from "${PB}"`)
     lines.push(`import { ${col.prefix}Card } from "./card"`)
     lines.push(`import { columns } from "./columns"`)

package/src/release/run-release.ts

@@ -110,6 +110,11 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         frozen: true,
         status: false,
         config,
+        // THE CAP ON EVERY REMAINING HOLE IN THE KEY. Not a flag, not a config
+        // field: a release re-measures every unit, so the worst a wrong key
+        // can ever produce is an agent looking at a stale local green, never a
+        // stale green that authorised a publish (ledger/ledger.ts rule 4).
+        ledgerRead: false,
         // the FULL tier, always. A release runs on a clean tree with time to
         // spare, and the suites the working gate skips (the ones that build
         // real repositories) are exactly the ones a publish must not be wrong

package/src/release/run-releases.ts

@@ -204,7 +204,13 @@ export function attentionLines(r: UnitReport): string[] {
     // shape of a command
     const KIND = '<patch|minor|major>'
 
-    if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
+    if (r.npmTarget && r.npmLatest === 'unpublished') {
+        // NO version of this name is on the registry, which every drift branch
+        // below reads as "a bit behind" and none of them says. Every `bun add
+        // <name>` in a doc, a seed or a scaffold answers 404 while this holds,
+        // and that is the one state where the docs are not stale but dead
+        out.push(`WARN ${r.id}: nothing is published under the name ${r.name} — every "bun add ${r.name}" 404s until ${notesClause}shipkit bump ${KIND} ${r.id}`)
+    } else if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
         // the trap: a version stamped into package.json while work kept
         // landing. Publishing it ships that work under notes describing none
         // of it, so the answer is a NEW version, never this one.

package/src/repo-config.ts

@@ -23,7 +23,7 @@ import type { Rule } from './rules/rule.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
-import type { TaskDef } from './core/task-runner.ts'
+import { TASK_DEF_KEYS, type TaskDef } from './core/task-runner.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
 
@@ -51,8 +51,13 @@ export type RepoConfig = {
     social?: string[]
     /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
     docsBase?: string
-    /** override a floor task's def, or `false` to disable (always visible) */
-    defaults?: Record<string, TaskDef | false>
+    /** a floor slot: `false` disables it (always visible), a def with a
+     *  `cmd` or `logic` REPLACES it, and a def with neither DECORATES whatever
+     *  fills it. The decoration is how a repo declares what its own `test`
+     *  script reads (`{ test: { inputs: ['tests', 'src'] } }`) without
+     *  restating the command: the read set is repo knowledge, the command is
+     *  already in package.json, and restating it is a second source of truth. */
+    defaults?: Record<string, Partial<TaskDef> | false>
     /** repo-specific commit-gate tasks; deps double as race guards */
     tasks?: TaskDef[]
     /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
@@ -158,9 +163,19 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (isAbsolute(d) || rel === '.' || rel === '' || rel === '..' || rel.startsWith('../'))
             throw new Error(`defineRepo: notReleasable '${d}' is the repo root or outside it, and would excuse every package at once — name one package dir per entry`)
     }
-    for (const k of Object.keys(c.defaults ?? {}))
+    for (const [k, slot] of Object.entries(c.defaults ?? {})) {
         if (!(FLOOR_IDS as readonly string[]).includes(k))
             throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
+        // the slot's own FIELDS, not just its name. A slot with no cmd or logic
+        // decorates the resolved task, so a typo there (`input` for `inputs`)
+        // is not a type error at any call site and lands as a task that is
+        // simply never cached, silently, which is the one direction this file
+        // promises a typo cannot go.
+        if (slot === false || slot == null) continue
+        for (const f of Object.keys(slot))
+            if (!(TASK_DEF_KEYS as readonly string[]).includes(f))
+                throw new Error(`defineRepo: defaults.${k}.${f} is not a task field (fields: ${TASK_DEF_KEYS.join(', ')})`)
+    }
     for (const n of c.oneWayIn?.exempt ?? [])
         if (!(ROUTED_SCRIPTS as readonly string[]).includes(n))
             throw new Error(`defineRepo: oneWayIn.exempt '${n}' is not a governed script name (governed: ${ROUTED_SCRIPTS.join(', ')})`)
@@ -181,6 +196,13 @@ export async function loadRepoConfig(root: string): Promise<RepoConfig> {
 // the contracts commit-gate task — venue deploy tasks should dep on it.
 // Same SK002-tagged rendering as `shipkit check` and `shipkit contracts`
 // (contracts/apply-contracts.ts is the one bridge).
+//
+// DELIBERATELY UNDECLARED for the ledger, and this is where that decision
+// lives rather than in a commit message. It runs in process, shares one
+// evaluation with rule SK002 through `withContractsScope`, and measures 0.0s,
+// so a key would be risk against no reward. It is not `never:` either: the
+// contract dirs describe it perfectly well, so claiming nothing can is false,
+// and `never` has to keep meaning "somebody looked and no key exists".
 export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',

package/src/rules/SK004-gitignore-policy.ts

@@ -1,6 +1,5 @@
 // SK004 — the .gitignore policy block (meta/contracts.md git policy; tmp/
-// included because shipkit itself writes tmp/.shipkit-cache in every
-// repo). A marker-keyed managed block so the always-gitignored contract
+// included because shipkit writes its per-run logs there in every repo). A marker-keyed managed block so the always-gitignored contract
 // surfaces can never silently rot per repo. Ecosystem-specific names the
 // published lib may not carry ride as repo-contributed lines:
 // `defineRepo({ gitignore: [...] })` renders them INSIDE the block, so the

package/src/rules/SK013-one-way-in-policy.ts

@@ -103,10 +103,12 @@ export const oneWayInPolicy: Rule = {
         if (missing.length > 0)
             t.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
         const guard = guardHookCommand(s)
+        let guardRuns = false
         if (guard == null)
             t.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
         else {
             const missing = guardScriptMissing(env.root, guard)
+            guardRuns = missing == null
             // the hook is DECLARED either way, so it starts working the moment
             // the dependency lands: no second fix run, nothing to remember. An
             // uninstalled dependency is therefore a WARN naming the command
@@ -124,7 +126,11 @@ export const oneWayInPolicy: Rule = {
                     `point it at this repo's own copy of hooks/one-way-in-guard.ts, or delete the hook and let the deny list stand alone`,
                 )
         }
-        if (!t.failed) t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s), with the replacement named`)
+        // the summary states only what the file actually delivers: claiming the
+        // replacement is named while the guard cannot run is the green that
+        // measured nothing, one line under the WARN that says otherwise
+        if (!t.failed)
+            t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s)${guardRuns ? ', with the replacement named' : ' — the guard that names the replacement is declared, not yet runnable'}`)
     },
     // MERGES, never rewrites: this file also carries the attribution silencer,
     // a repo's own allow list and its own hooks, and clobbering those to fix a