rvlib-shipkit 0.38.0 → 1.0.0

package/src/hooks/root-identity.ts

@@ -7,6 +7,7 @@
 // valid package.json. Only the NAME betrayed it.
 import { existsSync } from 'fs'
 import { join } from 'path'
+import { gitBin } from '../core/git-bin.ts'
 
 export type IdentityOutcome =
     | { status: 'skipped'; reason: string }
@@ -18,7 +19,7 @@ export type IdentityOutcome =
 const SCRATCH = /\.(bak|orig|rej)$/
 
 const git = (root: string, args: string[]): { code: number; out: string } => {
-    const p = Bun.spawnSync(['git', ...args], { cwd: root, env: process.env })
+    const p = Bun.spawnSync([gitBin(), ...args], { cwd: root, env: process.env })
     return { code: p.exitCode, out: p.stdout.toString() }
 }
 

package/src/hooks/run-hooks.ts

@@ -6,31 +6,44 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { KEYWORD_FILE, LAYOUT } from '../core/layout.ts'
 import { commitMessageOffenses } from './commit-message.ts'
 import { globalAllowFile, globalKeywordFile, maskPattern, patternFingerprint, runLeakGuard, type LeakAllowEntry, type LeakHit, type LeakWaiver } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
+import { gitRoot } from '../core/git-root.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { gitBin } from '../core/git-bin.ts'
 
 export type HooksConfig = {
     /** repo-specific commands run in the pre-commit gate, after the built-ins.
-     *  Non-zero exit blocks the commit; stdout/stderr are shown. */
-    preCommit?: { id: string; cmd: string[] }[]
-    /** repo-specific commands run on the commit message; the message file path
-     *  is appended as the last argument. */
-    commitMsg?: { id: string; cmd: string[] }[]
-    /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
+     *  A non-zero exit blocks the commit, and the output is shown. */
+    preCommit?: {
+        /** gate name, printed by `shipkit hooks list` */
+        id: string
+        /** argv, run without a shell */
+        cmd: string[]
+    }[]
+    /** repo-specific commands run on the commit message. The message file path
+     *  arrives as the last argument. */
+    commitMsg?: {
+        /** gate name, printed by `shipkit hooks list` */
+        id: string
+        /** argv, with the message file path appended */
+        cmd: string[]
+    }[]
+    /** keyword file for the leak guard (default .shipkit/private/banned-keywords.txt) */
     keywordFile?: string
     /** known-good leak-guard matches this repo waives: a lockfile whose
      *  dependency names or integrity hashes collide with a keyword is the
      *  motivating case. Each entry carries a reason, and a waiver that fires
      *  PRINTS, so nothing passes silently. This file is tracked, so an entry
      *  names a pattern by fingerprint (`fp:…`, printed beside every hit) and
-     *  never by value. The machine-global twin is ~/.rv-private/leak-allow.json.
+     *  never by value. The machine-global twin is ~/.shipkit/private/leak-allow.json.
      *  hooks/leak-guard.ts */
     leakAllow?: LeakAllowEntry[]
-    /** staged-path prefixes that may never enter git (local state like
-     *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
+    /** staged-path prefixes that can never enter git (local state like
+     *  '.comfy-ts/'). A gitignore line is advisory and editable. This gate is not. */
     blockedPaths?: string[]
     /** words the commit-message language gate never counts as French
      *  (proper nouns that carry accents without being a language choice) */
@@ -41,7 +54,7 @@ export type HooksConfig = {
     disable?: ('leak-guard' | 'commit-message' | 'root-identity' | 'commit-language')[]
 }
 
-const HOOK_DIR = 'hooks'
+const HOOK_DIR = LAYOUT.hooks
 const HOOKS = ['pre-commit', 'commit-msg'] as const
 
 /** how a self-written hook body should invoke shipkit in this repo: the
@@ -66,15 +79,14 @@ export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git'
  *  arm (a subdir would set the parent's hooksPath onto a dir that does not
  *  exist there, disarming the parent's gates). */
 export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
-    const top = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], { cwd: root })
-    if (top.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
-    const topDir = top.stdout.toString().trim()
+    const topDir = gitRoot(root)?.top
+    if (topDir == null) return { state: 'no-git', detail: 'not a git repo' }
     try {
         if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `nested in ${topDir}, which owns its own commit gates` }
     } catch {
         return { state: 'no-git', detail: 'work tree root unresolvable' }
     }
-    const p = Bun.spawnSync(['git', 'config', 'core.hooksPath'], { cwd: root })
+    const p = Bun.spawnSync([gitBin(), 'config', 'core.hooksPath'], { cwd: root })
     const current = p.exitCode === 0 ? p.stdout.toString().trim() : ''
     if (current !== '' && current !== HOOK_DIR) return { state: 'foreign', detail: `core.hooksPath=${current}, foreign, left alone` }
     if (current === HOOK_DIR && HOOKS.every((h) => existsSync(join(root, HOOK_DIR, h)))) return { state: 'current', detail: 'hooks already armed' }
@@ -94,7 +106,7 @@ function setHooksPath(root: string): { code: number; detail: string } {
     let last = { code: -1, detail: '' }
     for (let attempt = 0; attempt < 5; attempt++) {
         if (attempt > 0) Bun.sleepSync(20 * 2 ** (attempt - 1))
-        const p = Bun.spawnSync(['git', 'config', 'core.hooksPath', HOOK_DIR], { cwd: root })
+        const p = Bun.spawnSync([gitBin(), 'config', 'core.hooksPath', HOOK_DIR], { cwd: root })
         if (p.exitCode === 0) return { code: 0, detail: '' }
         last = { code: p.exitCode, detail: p.stderr.toString().trim().split('\n')[0]?.slice(0, 120) ?? '' }
         // only lock contention is worth retrying; anything else is a real
@@ -129,12 +141,12 @@ export function installHooks(root: string, binInvocation: string, keywordFile?:
 
 // a starter so the leak guard bites from day one instead of skipping forever:
 // generic secret shapes only. private names live in the machine-global
-// ~/.rv-private/banned-keywords.txt, which the guard reads on every run
+// ~/.shipkit/private/banned-keywords.txt, which the guard reads on every run
 // (never copied into a repo: a copy rots and a copy can leak)
 const KEYWORD_STARTER = `# banned-keywords — the leak guard greps every commit (added lines, paths,
 # message) for these rows. one row = one case-insensitive substring, or
 # re:<regex>. add repo-specific names here; machine-wide private names go in
-# ~/.rv-private/banned-keywords.txt, read automatically alongside this file.
+# ~/.shipkit/private/banned-keywords.txt, read automatically alongside this file.
 # this file is gitignored on purpose: the list itself is private.
 re:-----BEGIN [A-Z ]*PRIVATE KEY-----
 re:AKIA[0-9A-Z]{16}
@@ -146,7 +158,7 @@ re:xox[baprs]-[A-Za-z0-9-]{10,}
 /** seed the configured keyword file with the generic starter so the guard is
  *  ARMED, not a skip. an existing file is never touched. */
 function seedKeywordFile(root: string, keywordFile?: string): string | null {
-    const rel = keywordFile ?? '.rv-private/banned-keywords.txt'
+    const rel = keywordFile ?? KEYWORD_FILE
     const dest = join(root, rel)
     if (existsSync(dest)) return null
     mkdirSync(dirname(dest), { recursive: true })
@@ -212,7 +224,7 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
         })
     }
     if ((h.blockedPaths ?? []).length > 0) {
-        const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
+        const names = Bun.spawnSync([gitBin(), 'diff', '--cached', '--name-only'], { cwd: root })
         const staged = names.stdout.toString().split('\n').filter(Boolean)
         const blocked = staged.filter((f) => h.blockedPaths!.some((p) => f.startsWith(p)))
         out.push(blocked.length === 0
@@ -305,16 +317,16 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
 export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     const h = config.hooks ?? {}
     const off = new Set(h.disable ?? [])
-    const kw = h.keywordFile ?? '.rv-private/banned-keywords.txt'
+    const kw = h.keywordFile ?? KEYWORD_FILE
     // a gate listed as active but unable to fire is worse than no listing:
     // this surface exists so nobody has to guess
-    const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.rv-private list)`
+    const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.shipkit/private list)`
     // a waiver nobody can enumerate is a hole nobody can audit: the count of
     // declared exemptions belongs on the same surface as the gate itself
     const waivers = (h.leakAllow ?? []).length + (globalAllowFile() != null ? 1 : 0)
-    const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.rv-private/leak-allow.json'}`
+    const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.shipkit/private/leak-allow.json'}`
     return [
-        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt${leakAllowState}`,
+        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.shipkit/private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),

package/src/init-repo.ts

@@ -9,12 +9,15 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { basename, join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
-import { hasTestFiles, packageJsonShape } from './rules/SK001-package-json-shape.ts'
-import { oneWayInPolicy } from './rules/SK013-one-way-in-policy.ts'
+import { CheckCtx } from './core/check-ctx.ts'
+import { hasTestFiles, packageJsonShape } from './checks/SK001-package-json-shape.check.ts'
+import { oneWayInPolicy } from './checks/SK013-one-way-in-policy.check.ts'
+import { listRepoFiles } from './core/floor.ts'
 import { reportToMotherhome } from './core/motherhome.ts'
 import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
-import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
+import { gitignorePolicy } from './checks/SK004-gitignore-policy.check.ts'
+import { vscodeHubTask } from './checks/SK017-vscode-hub-task.check.ts'
 import { editorErgonomics } from './scaffold/project-scaffold.ts'
 import { defaultHubPort } from './serve/hub-port.ts'
 
@@ -26,21 +29,23 @@ const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'r
 
 export default defineRepo({
     name: '${name}',
-    venues: [], // e.g. ['itch', 'steam'], selects which .rv-<venue>/ contracts are REQUIRED
-    social: [], // e.g. ['x', 'discord'], the .rv-social/<channel>/ post folders (+ .rv-discord/)
+    venues: [], // e.g. ['itch', 'steam'], selects which .shipkit/<venue>/ contracts are REQUIRED
+    social: [], // e.g. ['x', 'discord'], the .shipkit/social/<channel>/ post folders (+ .shipkit/discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
-    // lint, typecheck, imports:check and cycles replay off the tracked tree.
-    // \`test\` measures every run until you say what it reads, because an
+    // lint, typecheck, imports:check and cycles are cached on the tracked tree.
+    // \`test\` runs every time until you say what it reads, because an
     // ignored path (a fixture, a local db, a .env) is not in a tree key:
     // defaults: { test: { inputs: ['tests', 'src', 'package.json'] } },
-    // .comfy-ts/ holds schema dumps naming a private model collection.
-    // gitignore (SK004) is advisory, this pre-commit gate is not
-    hooks: { blockedPaths: ['.comfy-ts/'] },
+    // staged paths that may never enter git: local state, big derived output, a
+    // dump naming something private. gitignore (SK004) is advisory and editable,
+    // this pre-commit gate is not
+    hooks: { blockedPaths: ['.comfy-ts/hosts/', '.comfy-ts/cache/', '.comfy-ts/outputs/'] },
     // the declared reviewer agent type (rule SK008). Uncomment with YOUR
     // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
     // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
-    // health checks need no config. Drop a <name>.check.ts file anywhere,
-    // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
+    // checks need no config. Drop a <name>.check.ts file anywhere, and
+    // \`shipkit ci\`, \`shipkit check\` and the hub discover it
+    // every key this file accepts, one line each: \`shipkit config-keys\`
 })
 `
 
@@ -95,12 +100,12 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
-        const g = await gitignorePolicy.fix!({ root, config: cfg })
+        const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: cfg }))
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
         await repairOneWayIn(root, cfg, p)
-        furnishEditor(root, cfg, p)
+        await furnishEditor(root, cfg, p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -121,7 +126,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // `test` is scaffolded only once the repo has tests: `bun test` exits
     // non-zero with none, and a scaffold that reds the gate is a bad scaffold
     for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
-        if (k === 'test' && !hasTestFiles(root)) continue
+        if (k === 'test' && !hasTestFiles(listRepoFiles(root))) continue
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
         else if (pkg.scripts[k] !== v) p(`skip: package.json script '${k}' exists — left untouched`)
     }
@@ -131,10 +136,10 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
-    const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
+    const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: defineRepo({ name }) }))
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
-    furnishEditor(root, { name }, p)
+    await furnishEditor(root, { name }, p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -143,7 +148,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // matter, and reports them about a repo that has code in it
     const floor = resolveFloor(defineRepo({ name }), root)
     if (floor.tasks.length > 0) p(`ok: gate floor: ${floor.tasks.map((t) => t.id).join(', ')}`)
-    else p(`WARN the gate would check NOTHING here (${floor.unfilled.map((u) => u.id).join(', ')} all unresolved) — see \`shipkit rules\``)
+    else p(`WARN the gate would check NOTHING here (${floor.unfilled.map((u) => u.id).join(', ')} all unresolved) — see \`shipkit checks\``)
     // every verb comes from the `shipkit` bin — dead on arrival unless the
     // package is actually installed (bunx runs without adding the dep)
     if (opts.bin == null) {
@@ -174,7 +179,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
  *  files are the only half of that scaffold an adopted repo can be handed
  *  unasked, because they change no output of any command (project-scaffold.ts
  *  owns the line). Create-only, so a .vscode/ the repo brought with it wins. */
-function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: number } }, p: (line: string) => void): void {
+async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: number } }, p: (line: string) => void): Promise<void> {
     // the least important thing init does, and it runs AFTER repo.config.ts is
     // on disk: an unwritable .vscode (a read-only tree, a path that is a file),
     // or a config with no name at all, must not abort the run before the
@@ -183,9 +188,20 @@ function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: numb
     try {
         const name = repoName(root, undefined, cfg.name)
         const port = cfg.serve?.port ?? defaultHubPort(name)
-        if (editorErgonomics(root, { name, port }).length === 0) return void p('ok: .vscode/ is this repo\'s own, left untouched')
+        if (editorErgonomics(root, { name, port }).length === 0) {
+            // the repo's own file stays its own, except the hub task, which
+            // rule SK017 keeps feeding the problems pane
+            // a file SK017 cannot read is still the repo's own: it is never
+            // reported as missing, and it is never rewritten
+            let hub: { changed: boolean; summary: string }
+            try { hub = await vscodeHubTask.fix!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
+                p('ok: .vscode/ is this repo\'s own, left untouched')
+                return void p(`WARN .vscode/tasks.json does not parse (${e instanceof Error ? e.message : String(e)}): the hub task gets no problem matcher until it does`)
+            }
+            return void p(hub.changed ? `ok: ${hub.summary}` : 'ok: .vscode/ is this repo\'s own, left untouched')
+        }
         p(`ok: .vscode/tasks.json written — opening the folder starts the hub on ${port}`)
-        p('      next: add this stack\'s own watchers (dev server, css, tests) — build/vscode-tasks.md carries the shapes')
+        p('      next: add this stack\'s own watchers (dev server, css) — build/vscode-tasks.md carries the shapes')
     } catch (e) {
         p(`WARN no .vscode/tasks.json here: ${e instanceof Error ? e.message : String(e)} — opening the folder starts nothing, everything else landed`)
     }
@@ -198,8 +214,8 @@ function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: numb
  *  one that was not. The deny is a RESTRICTION, which is why it lands
  *  unconditionally where the scaffold's allow list stays opt in. */
 async function repairOneWayIn(root: string, config: Parameters<typeof defineRepo>[0], p: (line: string) => void): Promise<void> {
-    const pkg = await packageJsonShape.fix!({ root, config })
+    const pkg = await packageJsonShape.fix!(CheckCtx.open({ root, config }))
     if (pkg.changed) p(`ok: package.json — ${pkg.summary}`)
-    const policy = await oneWayInPolicy.fix!({ root, config })
+    const policy = await oneWayInPolicy.fix!(CheckCtx.open({ root, config }))
     p(policy.changed ? `ok: ${policy.summary}` : `ok: .claude/settings.json already closes every raw runner`)
 }

package/src/ledger/check-stats.ts

@@ -0,0 +1,155 @@
+// What a check costs, per check, from the two things this repo remembers: the
+// store (one file per key, greens only, `at` plus `measuredMs`) and the runs
+// run record beside it (every outcome, red included).
+//
+// The store is HISTORY here and the db is the record. They overlap for as
+// long as both describe the same run, so a stored entry is counted only when
+// it predates that CHECK's first row in the record: otherwise one measurement
+// lands in the average twice, and the sample count, the one number that says
+// whether an average means anything, is the first thing to lie.
+//
+// PER CHECK, never one boundary for the whole repo, because the two sources do
+// not cover the same checks. A discovered check NEVER enters the store: its
+// result lives in the check ttl cache or nowhere at all, so the store holds
+// rules and tasks only, and a surface reading it alone shows every check as
+// never measured however often it runs. The record is the only source that
+// measures a check, and the store is only ever the history of the other two.
+import { readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import type { RunRow, RunStatus } from './run-log.ts'
+import { readRuns, runsPath, runsStamp } from './run-log.ts'
+import { storeRoot } from './store.ts'
+
+/** one measurement read back off the store */
+export type StoreSample = { key: string; at: number; ms: number; status: RunStatus }
+
+export type CheckLast = { status: RunStatus; at: number; ms: number; replayed: boolean }
+
+export type CheckStat = {
+    /** the newest outcome, replayed or measured */
+    last: CheckLast | null
+    /** mean of the MEASURED runs, ms. null when nothing measured it */
+    avgMs: number | null
+    /** how many measurements the mean is over: an average over two runs is
+     *  not an average, and the page says which it is looking at */
+    samples: number
+    slowestMs: number | null
+    /** measurements that went red, out of `samples` */
+    failures: number
+    /** when it was last MEASURED rather than replayed, and what that said:
+     *  a remembered answer expires from its measurement, never its replay */
+    measuredAt?: number | null
+    measuredStatus?: RunStatus | null
+}
+
+/** the ONE merge. Pure, so the rules above are testable without a disk. */
+export function mergeCheckStats(o: { runs: RunRow[]; store: StoreSample[] }): Map<string, CheckStat> {
+    // each check's own first row is its boundary: what the store holds from
+    // before it is history the record never saw, and what comes after it is a
+    // measurement the record already carries. A check with no rows at all keeps
+    // its whole stored history
+    const firstRunAt = new Map<string, number>()
+    for (const r of o.runs) {
+        const prev = firstRunAt.get(r.id)
+        if (prev == null || r.at < prev) firstRunAt.set(r.id, r.at)
+    }
+    type Sample = { at: number; ms: number; status: RunStatus; full?: boolean }
+    const samples = new Map<string, Sample[]>()
+    const last = new Map<string, CheckLast>()
+    const push = (key: string, s: Sample): void => {
+        const list = samples.get(key) ?? []
+        list.push(s)
+        samples.set(key, list)
+    }
+    for (const s of o.store) {
+        if (s.at >= (firstRunAt.get(s.key) ?? Infinity)) continue
+        push(s.key, { at: s.at, ms: s.ms, status: s.status })
+        const prev = last.get(s.key)
+        if (prev == null || s.at > prev.at) last.set(s.key, { status: s.status, at: s.at, ms: s.ms, replayed: false })
+    }
+    for (const r of o.runs) {
+        // a replay measured nothing and a skip ran nothing: both are the last
+        // VERDICT and neither is a timing
+        if (!r.replayed && r.status !== 'skip') push(r.id, { at: r.at, ms: r.ms, status: r.status, ...(r.full === true ? { full: true } : {}) })
+        const prev = last.get(r.id)
+        if (prev == null || r.at >= prev.at) last.set(r.id, { status: r.status, at: r.at, ms: r.ms, replayed: r.replayed })
+    }
+    const out = new Map<string, CheckStat>()
+    for (const [key, l] of last) {
+        // the quick tier is what every edit waits on: a full tier run (every
+        // slow suite, one at a time) joins the numbers only of a check that
+        // never ran at the quick one
+        const all = samples.get(key) ?? []
+        const quick = all.filter((s) => s.full !== true)
+        const list = quick.length > 0 ? quick : all
+        const newest = list.reduce<Sample | null>((a, s) => (a == null || s.at >= a.at ? s : a), null)
+        out.set(key, {
+            last: l,
+            avgMs: list.length === 0 ? null : Math.round(list.reduce((a, s) => a + s.ms, 0) / list.length),
+            samples: list.length,
+            slowestMs: list.length === 0 ? null : Math.max(...list.map((s) => s.ms)),
+            failures: list.filter((s) => s.status === 'fail').length,
+            measuredAt: newest?.at ?? null,
+            measuredStatus: newest?.status ?? null,
+        })
+    }
+    return out
+}
+
+/** the store, read back. A check's file name is the slug of its id
+ *  (ledger/store.ts entryPath), so the caller's check list decides which
+ *  prefixes are read: deriving the id back OUT of a slug cannot work, since
+ *  both `:` and `/` slug to `_`. */
+export function scanCheckStore(store: string, checks: { id: string }[]): StoreSample[] {
+    const byPrefix = new Map<string, string>()
+    for (const u of checks) byPrefix.set(storeSlug(u.id), u.id)
+    const dir = join(store, 'checks')
+    const out: StoreSample[] = []
+    let files: string[] = []
+    try { files = readdirSync(dir) } catch { return out }
+    for (const f of files) {
+        if (!f.endsWith('.json')) continue
+        // `<slug>.<12 hex of the key>.json`
+        const key = byPrefix.get(f.replace(/\.[0-9a-f]{12}\.json$/, ''))
+        if (key == null) continue
+        try {
+            const e = JSON.parse(readFileSync(join(dir, f), 'utf8')) as { at?: number; payload?: { measuredMs?: number; status?: RunStatus } }
+            const ms = e.payload?.measuredMs
+            if (typeof e.at !== 'number' || typeof ms !== 'number') continue
+            out.push({ key, at: e.at, ms, status: e.payload?.status === 'warn' ? 'warn' : 'pass' })
+        } catch { /* a half written or foreign entry reads as no sample */ }
+    }
+    return out
+}
+
+/** ledger/store.ts entryPath's file name rule, which this module must agree
+ *  with byte for byte or it reads nothing */
+const storeSlug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
+
+type Cached = { stamp: string; stats: Map<string, CheckStat> }
+const cache = new Map<string, Cached>()
+
+/** the per check numbers for a repo, cached on what the two sources look like
+ *  from the outside: the store dir's mtime, plus what the run record holds.
+ *  The store is thousands of small files and the hub asks on a ten second
+ *  poll. The record's own FILE cannot answer for it: in WAL mode a commit
+ *  lands in the sidecar and the db's mtime does not move. */
+export function checkStatsFor(root: string, checks: { id: string }[], o?: { fresh?: boolean }): Map<string, CheckStat> {
+    const store = storeRoot(root)
+    const record = runsPath(root)
+    const stamp = `${checks.length}:${stampOf(join(store, 'checks'))}:${runsStamp(record)}`
+    const hit = cache.get(root)
+    if (o?.fresh !== true && hit != null && hit.stamp === stamp) return hit.stats
+    const stats = mergeCheckStats({ runs: readRuns(record), store: scanCheckStore(store, checks) })
+    cache.set(root, { stamp, stats })
+    return stats
+}
+
+const stampOf = (p: string): string => {
+    try {
+        const s = statSync(p)
+        return `${s.mtimeMs}/${s.size}`
+    } catch {
+        return 'none'
+    }
+}

package/src/ledger/check-table.ts

@@ -0,0 +1,179 @@
+// THE inventory render — every gate check as one markdown row, so the question
+// "what runs here, does it block me, and how often does it really run" has a
+// surface that is read rather than reconstructed from three commands.
+//
+// Deliberately carries NO live run state: no timestamps, no key hashes, no
+// last verdict. Everything here is what a check DECLARED about itself, so two
+// runs a week apart over an unchanged repo write identical bytes and the file
+// never churns. It is still generated, gitignored AND untracked like STATUS.md
+// (rules/untrack-generated.ts), so it is read on disk, never in git history.
+// Live keys are `shipkit keys`, live verdicts are STATUS.md.
+import { mkdirSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite, withFileLock } from '../core/locked-write.ts'
+import { classify } from './git-key.ts'
+import type { CheckRow } from './gate-checks.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+/** the sidecar every gate run refreshes beside STATUS.md */
+export const CHECK_TABLE_FILE = LAYOUT.statusFull
+
+/** a cell can never break the table it sits in */
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+
+export type CheckTableInput = {
+    /** repo name, for the headline */
+    name: string
+    rows: CheckRow[]
+}
+
+/** what a check's cache declaration means for how often it actually runs */
+function cacheOf(r: CheckRow): { population: string; ttl: string; reads: string; why: string } {
+    const c = classify(r.decl)
+    const inputs = r.decl.inputs ?? []
+    if (c.error != null) return { population: 'BROKEN', ttl: '', reads: '', why: c.error }
+    if (c.population === 'content') return { population: 'content', ttl: '', reads: inputs.join(', '), why: '' }
+    // what it read is recorded per run, so the table (which never churns)
+    // says where to look rather than a list that moves with every edit
+    if (r.decl.uncacheable != null) return { population: 'never', ttl: '', reads: '', why: r.decl.uncacheable }
+    if (c.population === 'reads') return { population: 'reads', ttl: '', reads: 'recorded per run (shipkit keys --why)', why: '' }
+    // no `reads` for these two: the cache column already says "world"/"never",
+    // and restating it on every such row is a column of noise
+    if (c.population === 'world') return { population: 'world', ttl: r.decl.ttl ?? '', reads: '', why: '' }
+    if (c.decided === true) return { population: 'never', ttl: '', reads: '', why: r.decl.never ?? '' }
+    return { population: 'UNDECLARED', ttl: '', reads: '', why: 'nobody has declared what this reads, so it re-runs every single time' }
+}
+
+/** EVERY CELL of one check's row, in the one vocabulary. Both renders read
+ *  this, so a column cannot exist on the terminal table and not in the file,
+ *  or say two different things in the two places. */
+export type CheckCells = {
+    check: string
+    runsIn: string
+    from: string
+    build: string
+    failure: string
+    cache: string
+    ttl: string
+    reads: string
+    owner: string
+}
+
+export function checkCells(r: CheckRow): CheckCells {
+    const c = cacheOf(r)
+    return {
+        check: r.decl.id,
+        runsIn: r.when.at,
+        from: r.from,
+        // a flag column: the word is in the header, so the cell only has to
+        // answer, and an empty cell is quieter than a column of `no`
+        build: r.build ? 'yes' : '',
+        failure: r.blocking == null ? 'UNDECLARED' : r.blocking ? 'blocks' : 'warns',
+        cache: c.population,
+        ttl: c.ttl,
+        reads: c.reads,
+        owner: r.owner ?? '',
+    }
+}
+
+export function renderCheckTable(input: CheckTableInput): string {
+    const { name, rows } = input
+    const builds = rows.filter((r) => r.build).length
+    const shipped = rows.filter((r) => r.from === 'shipkit').length
+
+    const body: string[] = []
+    body.push(`<!-- generated by \`shipkit checks\`, refreshed by every gate run, gitignored (SK004) -->`)
+    body.push(`# ${name} checks — ${rows.length} total`)
+    body.push('')
+    body.push(`Everything \`shipkit ci\` and \`shipkit check\` know how to run: ${builds} build step(s) the gate alone runs, ${rows.length - builds} the health pass reports too. ${shipped} ship with the toolkit, ${rows.length - shipped} belong to this repo.`)
+    body.push('')
+    body.push('- **runs in** — `always` means every `shipkit ci` runs it, so a red one says THIS change is broken. `release` means the quick gate leaves it out and `shipkit ci --full` plus the release path run it. `health` means only the health pass (`shipkit check`) runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit. `off` means this repo turned it off on purpose, and the reason is in `repo.config.ts when`.')
+    body.push('- **build** — `yes` means the gate alone runs it: it BUILDS (a compiler, a test suite, a bundler), so `shipkit check` leaves it out and reports everything else. A floor slot derives it from the package.json script behind it, and a `*.check.ts` declares it with `build: true`.')
+    body.push('- **on failure** — `blocks` stops the run. `warns` prints and carries on. `UNDECLARED` is a defect, not a setting: the check never said and the repo set no default, so the runner treats it as fatal by guess.')
+    body.push('- **cache** — `content` is cached while the files it reads are untouched. `world` is cached for its TTL, and a RED that ran is cached too, capped at one hour so the run after a fix sees the fix. `never` runs every time and somebody wrote down why. `UNDECLARED` runs every time and nobody has looked yet, which is the burn-down (`shipkit keys --burn-down`). `SHIPKIT_FRESH=1` busts all of it.')
+    const proactive = rows.filter((r) => r.when.at !== 'always').length
+    const warns = rows.filter((r) => r.blocking === false).length
+    const neverSaid = rows.filter((r) => r.blocking == null).length
+    const undeclared = rows.filter((r) => cacheOf(r).population === 'UNDECLARED')
+    body.push('')
+    // the most useful line in the file, so it sits ABOVE the 68 rows rather
+    // than under them
+    body.push(
+        `**${rows.length - proactive} always, ${proactive} not in the quick gate · ${warns} warn instead of blocking${neverSaid > 0 ? `, ${neverSaid} never said` : ''} · ${undeclared.length} never cached with nobody having looked.**`,
+    )
+    body.push('')
+    body.push('| check | runs in | from | build | on failure | cache | ttl | reads | owner |')
+    body.push('|---|---|---|---|---|---|---|---|---|')
+    for (const r of rows) {
+        const c = checkCells(r)
+        // the two answers a reader must never skim past are bolded, and only
+        // in the file: a terminal has no bold that a pipe survives
+        const loud = (v: string): string => (v === 'UNDECLARED' ? '**UNDECLARED**' : v)
+        body.push(
+            `| \`${cell(c.check)}\` | ${c.runsIn} | ${c.from} | ${c.build} | ${loud(c.failure)} | ${loud(c.cache)} | ${cell(c.ttl)} | ${cell(c.reads)} | ${c.owner === '' ? '' : `\`${cell(c.owner)}\``} |`,
+        )
+    }
+    body.push('')
+
+    const decided = rows.filter((r) => cacheOf(r).population === 'never')
+    if (undeclared.length > 0) {
+        body.push(`## ${undeclared.length} check(s) nothing can cache yet`)
+        body.push('')
+        body.push('Each of these runs on every single pass. Declaring `inputs` (it reads files), `ttl` (it reads the world) or `never` (nothing can describe it) is the fix, and the last one counts: a written reason is a decision, not a hole.')
+        body.push('')
+        for (const r of undeclared) body.push(`- \`${cell(r.decl.id)}\`${r.owner == null ? '' : ` — \`${cell(r.owner)}\``}`)
+        body.push('')
+    }
+    if (decided.length > 0) {
+        body.push(`## ${decided.length} check(s) never cached on purpose`)
+        body.push('')
+        for (const r of decided) body.push(`- \`${cell(r.decl.id)}\` — ${cell(r.decl.never ?? '')}`)
+        body.push('')
+    }
+
+    return body.join('\n')
+}
+
+/** the same inventory as a plain terminal table (`shipkit checks`). A catalog,
+ *  not a health run, so no line carries a wire prefix: anything parsing wire
+ *  output would read this as a passing check. */
+export function renderCheckLines(rows: CheckRow[]): string[] {
+    const out: string[] = [`${'check'.padEnd(28)} ${'runs in'.padEnd(8)} ${'from'.padEnd(8)} ${'build'.padEnd(6)} ${'failure'.padEnd(10)} ${'cache'.padEnd(11)} ttl`]
+    for (const r of rows) {
+        const c = checkCells(r)
+        out.push(`${c.check.padEnd(28)} ${c.runsIn.padEnd(8)} ${c.from.padEnd(8)} ${c.build.padEnd(6)} ${c.failure.padEnd(10)} ${c.cache.padEnd(11)} ${c.ttl}`)
+    }
+    const undeclared = rows.filter((r) => { const cl = classify(r.decl); return cl.population === 'none' && cl.decided !== true }).length
+    const proactive = rows.filter((r) => r.when.at !== 'always').length
+    out.push('')
+    out.push(`${rows.length} checks — ${rows.length - proactive} always, ${proactive} not in the quick gate · ${undeclared} never cached with nobody having looked`)
+    return out
+}
+
+/** THE FIXABLE CATALOG (`shipkit checks --fixable`): everything in this repo
+ *  that repairs itself, with the page that owns the invariant and where the
+ *  check runs, so an off one cannot look like a repair waiting to happen. A
+ *  catalog, not a health run, so no line carries a wire prefix. */
+export function renderFixableLines(rows: CheckRow[]): string[] {
+    if (rows.length === 0) return ['no check in this repo carries an autofix']
+    const name = (r: CheckRow): string => (r.title === r.decl.id ? r.decl.id : `${r.decl.id} ${r.title}`)
+    const w = Math.max(28, ...rows.map((r) => name(r).length))
+    const out: string[] = [`${'check'.padEnd(w)} ${'from'.padEnd(8)} ${'runs in'.padEnd(8)} ${'failure'.padEnd(10)} owner`]
+    for (const r of rows) {
+        const c = checkCells(r)
+        out.push(`${name(r).padEnd(w)} ${c.from.padEnd(8)} ${c.runsIn.padEnd(8)} ${c.failure.padEnd(10)} ${c.owner}`)
+    }
+    out.push('')
+    out.push(`${rows.length} check(s) repair themselves — one with \`shipkit check --fix ${rows[0]!.decl.id}\`, every one with \`shipkit check --fix\``)
+    return out
+}
+
+/** refresh the sidecar beside STATUS.md. Lock-guarded exactly like STATUS.md:
+ *  several runners in one checkout is the normal case, and the loser skipping
+ *  a render it would have written identically costs nothing. */
+export function writeCheckTable(root: string, input: CheckTableInput): { written: boolean; warn?: string } {
+    const target = join(root, CHECK_TABLE_FILE)
+    mkdirSync(dirname(target), { recursive: true })
+    const r = withFileLock(target, () => { atomicWrite(target, `${renderCheckTable(input).trimEnd()}\n`) })
+    return r.ok ? { written: true } : { written: false, warn: `${CHECK_TABLE_FILE} locked by another runner — skipped this write` }
+}