rvlib-shipkit 0.38.1 → 1.0.1

package/src/hooks/leak-guard.ts

@@ -18,6 +18,8 @@
 import { createHash } from 'crypto'
 import { existsSync, readFileSync } from 'fs'
 import { basename, join } from 'path'
+import { gitBin } from '../core/git-bin.ts'
+import { KEYWORD_FILE, MACHINE_PRIVATE } from '../core/layout.ts'
 
 export type LeakHit = { where: string; pattern: string; file?: string }
 export type LeakWaiver = LeakHit & { reason: string; source: string }
@@ -78,6 +80,15 @@ export type ParsedPatterns = {
 
 const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
+/** a key shape is a token, so it starts where a token starts: `ask-the-...`
+ *  or `desk-lamp-...` is a word that ends in `sk`, never a key */
+export const SK_KEY_ROW = 're:(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{20,}'
+
+/** rows the hooks seeded before their shape was fixed, read as the fixed
+ *  shape. Their id stays the seeded row, so a waiver written against its
+ *  fingerprint keeps working */
+const SEEDED_ROW_FIXES: Record<string, string> = { 're:sk-[A-Za-z0-9_-]{20,}': SK_KEY_ROW }
+
 /** Parse the keyword file: blank lines and `#` comments dropped, `re:<pattern>`
  *  rows become case-insensitive regexes, `w:<word>` rows match on word
  *  boundaries, everything else a case-insensitive substring.
@@ -93,7 +104,7 @@ export function parsePatterns(text: string): ParsedPatterns {
         const row = raw.trim()
         if (row === '' || row.startsWith('#')) continue
         if (row.startsWith('re:')) {
-            try { regexes.push({ row, re: new RegExp(row.slice(3), 'i') }) }
+            try { regexes.push({ row, re: new RegExp((SEEDED_ROW_FIXES[row] ?? row).slice(3), 'i') }) }
             catch { /* a malformed row must not disable the whole guard */ }
         } else if (row.startsWith('w:')) {
             const word = row.slice(2).trim().toLowerCase()
@@ -227,11 +238,11 @@ export function leakAllowProblems(entries: unknown, where: string, tracked: bool
 
 /** the machine-global list every repo's guard also reads: one private list
  *  per machine, never copied into a repo (a copy rots, and a not-yet-ignored
- *  .rv-private/ would make the list itself committable). */
+ *  private folder would make the list itself committable). */
 export function globalKeywordFile(): string | null {
     const home = process.env.HOME ?? ''
     if (home === '') return null
-    const p = join(home, '.rv-private', 'banned-keywords.txt')
+    const p = join(home, MACHINE_PRIVATE, 'banned-keywords.txt')
     return existsSync(p) ? p : null
 }
 
@@ -240,7 +251,7 @@ export function globalKeywordFile(): string | null {
 export function globalAllowFile(): string | null {
     const home = process.env.HOME ?? ''
     if (home === '') return null
-    const p = join(home, '.rv-private', 'leak-allow.json')
+    const p = join(home, MACHINE_PRIVATE, 'leak-allow.json')
     return existsSync(p) ? p : null
 }
 
@@ -263,7 +274,7 @@ export function loadAllowFile(path: string, tracked: boolean): { entries: Loaded
 }
 
 export type LeakGuardOpts = {
-    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
+    /** path to the keyword file, relative to root (default .shipkit/private/banned-keywords.txt) */
     keywordFile?: string
     /** extra text to scan (a commit message, a release note) */
     text?: { label: string; content: string }[]
@@ -334,10 +345,10 @@ export function addedLinesByFile(diff: string): { file: string; content: string
 }
 
 export function runLeakGuard(root: string, o: LeakGuardOpts = {}): LeakGuardResult {
-    const rel = o.keywordFile ?? '.rv-private/banned-keywords.txt'
+    const rel = o.keywordFile ?? KEYWORD_FILE
     const file = join(root, rel)
     const sources = [existsSync(file) ? file : null, globalKeywordFile()].filter((f): f is string => f != null)
-    if (sources.length === 0) return { status: 'skipped', reason: `${rel} not found and no ~/.rv-private/banned-keywords.txt — no keyword list, no leak guard` }
+    if (sources.length === 0) return { status: 'skipped', reason: `${rel} not found and no machine-global banned-keywords.txt — no keyword list, no leak guard` }
     const patterns = parsePatterns(sources.map((f) => readFileSync(f, 'utf8')).join('\n'))
     const count = patterns.substrings.length + patterns.words.length + patterns.regexes.length
     if (count === 0) return { status: 'skipped', reason: `keyword file(s) have no patterns (${sources.join(', ')})` }
@@ -358,11 +369,11 @@ export function runLeakGuard(root: string, o: LeakGuardOpts = {}): LeakGuardResu
 
     const targets: ScanTarget[] = []
     if (o.staged !== false) {
-        const diff = Bun.spawnSync(['git', 'diff', '--cached'], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
+        const diff = Bun.spawnSync([gitBin(), 'diff', '--cached'], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
         if (diff.exitCode === 0)
             for (const f of addedLinesByFile(diff.stdout.toString())) targets.push({ where: 'staged content', file: f.file, content: f.content })
         // a filename can leak as loudly as a line of code
-        const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
+        const names = Bun.spawnSync([gitBin(), 'diff', '--cached', '--name-only'], { cwd: root })
         if (names.exitCode === 0) for (const n of names.stdout.toString().split('\n')) if (n.trim() !== '') targets.push({ where: 'staged path', file: n, content: n })
     }
     for (const t of o.text ?? []) targets.push({ where: t.label, content: t.content })

package/src/hooks/one-way-in-guard.ts

@@ -1,16 +1,17 @@
 #!/usr/bin/env bun
 // the PreToolUse guard for ONE WAY IN (core/one-way-in-policy.ts owns the
-// table and the wording). Its ONE job is to refuse a raw runner with the
-// shipkit command to type instead: `permissions.deny` already blocks these,
-// but a bare deny tells the model only that it was denied, and a refusal with
-// no replacement just sends it looking for another way in.
+// table and the wording). It refuses a raw runner with the shipkit command to
+// type instead: `permissions.deny` already blocks these, but a bare deny tells
+// the model only that it was denied, and a refusal with no replacement just
+// sends it looking for another way in. It also refuses a gate piped into
+// another command, whose exit code the pipe hides.
 //
 // It runs before EVERY Bash call, so it stays a leaf: one tiny import, one
 // small json read, no clipanion, no repo config. Anything it cannot decide it
 // waves through, because a guard that fails closed on its own bugs would wedge
 // a repo with no way to tell why, and `permissions.deny` is still the floor
 // underneath it. Measured at ~10ms per call.
-import { deniedHeads, rawRunnerHit, refusal } from '../core/one-way-in-policy.ts'
+import { deniedHeads, pipedGateIn, pipedGateRefusal, rawRunnerHit, refusal } from '../core/one-way-in-policy.ts'
 
 const input = await Bun.stdin.text()
 let command = ''
@@ -21,6 +22,13 @@ try {
 } catch {
     process.exit(0)
 }
+// a piped gate is refused whatever the deny list says: it is not a raw
+// runner, it is a verdict whose exit code the tail of the pipe replaces
+const piped = pipedGateIn(command)
+if (piped != null) {
+    console.error(pipedGateRefusal(piped))
+    process.exit(2)
+}
 // the settings file is the authority on WHICH runners this repo refuses, so
 // deleting one `Bash(...)` line lifts the deny and this refusal together
 const settingsPath = `${process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd()}/.claude/settings.json`

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 { globalAllowFile, globalKeywordFile, maskPattern, patternFingerprint, runLeakGuard, SK_KEY_ROW, 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,16 +141,16 @@ 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,
+export 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}
-re:sk-[A-Za-z0-9_-]{20,}
+${SK_KEY_ROW}
 re:ghp_[A-Za-z0-9]{36}
 re:xox[baprs]-[A-Za-z0-9-]{10,}
 `
@@ -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'
+    }
+}