rvlib-shipkit 0.13.0 → 0.16.0

package/src/core/run-ci.ts

@@ -1,11 +1,16 @@
-// the ci gate — floor + contracts + repo tasks through the DAG runner.
-// Plain module behind cmd_Ci (logic stays out of command classes) so tests
-// can run the gate in-process. Returns the exit code; json prints the
-// structured summary. Every run refreshes STATUS.md (write-status.ts —
-// atomic + lock) unless status:false.
+// the ci gate — floor + contracts + repo tasks through the DAG runner, THEN
+// every discovered check (core/run-check.ts owns severity). Plain module
+// behind cmd_Ci (logic stays out of command classes) so tests can run the
+// gate in-process. Returns the exit code; json prints the structured summary.
+// Every run refreshes STATUS.md (write-status.ts — atomic + lock) unless
+// status:false, and the fix pass plus some checks WRITE, so a run is not
+// read-only unless frozen is set and --no-fix is passed.
 import { join } from 'path'
-import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { allTasks, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
+import { collectChecks } from './run-check.ts'
+import { runFixPass } from './run-fixers.ts'
+import { formatLine } from './wire.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -17,17 +22,57 @@ export type CiOpts = {
     onlyIds?: string[]
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
+    /** repair the mechanical slots before gating. default on locally, verify
+     *  mode under CI. core/run-fixers.ts owns the scope. */
+    fix?: boolean
+    /** also apply the structural SK rule fixers during the fix pass */
+    fixRules?: boolean
+    /** report-only for self-maintaining rules and checks (SHIPKIT_FROZEN
+     *  travels to child checks). The release path passes it: a rule that
+     *  rewrites package.json between the gate and `npm publish` packs a tree
+     *  that exists in no commit. */
+    frozen?: boolean
+    /** treat a NON-blocking check failure as fatal too. `release.requireHealthy`
+     *  is the only caller: a repo that wants a missing cred to stop a release
+     *  asks for it, and every other run keeps the declared severity. */
+    failOnAdvisory?: boolean
+    /** run the tasks only. The TUI owns this: it renders the checks in its own
+     *  panel, and running the suite twice per refresh proves nothing twice. */
+    skipChecks?: boolean
     /** line sink — commands pass their context stream; defaults to console */
     print?: (line: string) => void
     /** per-task completion tap — the TUI tasks panel streams results in */
     onTaskFinish?: (r: TaskResult) => void
+    /** the already-resolved config. A caller that holds one MUST pass it: two
+     *  loads of repo.config.ts can disagree, and the release path classifies
+     *  rule-vs-probe severity from the config it holds. */
+    config?: RepoConfig
+}
+
+/** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
+ *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
+ *  a narrowed run that stamps the full gate's verdict is a green nobody
+ *  measured. The label names the invocation either way. */
+function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
+    const narrowing = [
+        ...(o.onlyIds ?? []).map((i) => `--only ${i}`),
+        ...(o.skipGroups ?? []).map((g) => `--skip ${g}`),
+        ...(o.skipChecks === true ? ['(tasks only)'] : []),
+    ]
+    const parts = [...narrowing, ...(o.withIds ?? []).map((i) => `--with ${i}`)]
+    return { command: parts.length === 0 ? 'shipkit ci' : `shipkit ci ${parts.join(' ')}`, fullGate: narrowing.length === 0 }
 }
 
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
-    const c = await loadRepoConfig(root)
+    const c = o.config ?? (await loadRepoConfig(root))
+    // mechanical failures are not information, so they never cost a round trip
+    let fixFailed = false
+    if (o.fix !== false)
+        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, print: sink })).failed
+    else sink('skip: fix pass (--no-fix)')
     const { tasks, disabled, unfilled } = allTasks(c, root)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
@@ -44,12 +89,33 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
-    const code = summary.ok ? 0 : 1
+    // the checks, in the SAME command. there is no second surface: a check
+    // declares whether it blocks, and that is the only question about it.
+    const checks = o.skipChecks === true
+        ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen })
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
+    for (const u of checks.undeclared) {
+        sink(`FAIL: ${u} does not declare whether it blocks`)
+        sink(`      fix: add \`export const blocking = true\` (about this repo) or \`false\` (about the world) to that file`)
+    }
+    let advisoryFatal = false
+    if (checks.advisoryFailures.length > 0) {
+        if (o.failOnAdvisory === true) {
+            advisoryFatal = true
+            sink(`FAIL: ${checks.advisoryFailures.length} non-blocking check(s) failing and release.requireHealthy is on: ${checks.advisoryFailures.join(', ')}`)
+            sink('      fix: shipkit check')
+        } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
+    }
+    const code = summary.ok && !fixFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
     // motherhome row (docsBase wiki on this disk) — never affects the gate
     const mh = reportToMotherhome(root, c)
     if (mh.note != null) print(mh.note)
     if (o.status !== false) {
-        const st = writeStatus(root, { name: c.name, command: 'shipkit ci', lines: collected, exitCode: code })
+        // scope is named in the file: ci proves the gate, not repo health, and
+        // a bare GREEN here would claim clear-to-ship on a repo with red checks
+        const st = writeStatus(root, { name: c.name, ...ciScope(o), lines: collected, exitCode: code })
         if (!st.written) print(`WARN ${st.warn}`)
     }
     if (o.json === true)

package/src/core/run-fixers.ts

@@ -0,0 +1,144 @@
+// what `shipkit ci` repairs before it gates.
+//
+// mechanical slots only (formatter, import canonicaliser): they rewrite the
+// files the agent is already editing and their output is total. structural
+// SK rule fixers rewrite repo config, so they stay behind --fix-rules.
+//
+// under CI the same fixers run in verify mode instead: a gate that silently
+// rewrites the tree it checks can turn red green with no commit. one
+// mechanism, two modes, rather than a formatter plus a format:check that
+// drift apart.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import type { RepoConfig } from '../repo-config.ts'
+import { runFix } from '../rules/run-fix.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
+
+const FIXER_TIMEOUT_MS = 120_000
+
+export type FixerSlot = {
+    id: string
+    cmd: string[]
+    source: 'package.json script' | 'built-in (rvlib-ts-tools)'
+}
+
+export type FixerResolution = {
+    slots: FixerSlot[]
+    /** slots nothing could fill, printed, never silent */
+    unfilled: { id: string; reason: string }[]
+}
+
+// one fixer per mechanical concern. `fmt` accepts the two names the house
+// vocabulary allows so a repo that calls it `format` is not silently unfixed.
+const FMT_SCRIPTS = ['fmt', 'format'] as const
+
+export function resolveFixers(root: string): FixerResolution {
+    const pkgPath = join(root, 'package.json')
+    let scripts: Record<string, string> = {}
+    if (existsSync(pkgPath)) {
+        try { scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
+        catch (e) { throw new Error(`package.json unparseable — fixers cannot register: ${String(e).slice(0, 120)}`) }
+    }
+    const slots: FixerSlot[] = []
+    const unfilled: { id: string; reason: string }[] = []
+
+    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null)
+    if (fmtName != null) slots.push({ id: 'fmt', cmd: ['bun', 'run', fmtName], source: 'package.json script' })
+    else unfilled.push({ id: 'fmt', reason: `no 'fmt' or 'format' script — formatting stays a manual step` })
+
+    if (scripts['imports:fix'] != null) slots.push({ id: 'imports:fix', cmd: ['bun', 'run', 'imports:fix'], source: 'package.json script' })
+    else {
+        let cli: string | null = null
+        try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) } catch { cli = null }
+        if (cli == null) unfilled.push({ id: 'imports:fix', reason: `no 'imports:fix' script and rvlib-ts-tools is unresolvable` })
+        else slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (rvlib-ts-tools)' })
+    }
+    return { slots, unfilled }
+}
+
+/** worktree fingerprint: every dirty path mapped to `<status>:<content hash>`,
+ *  or null outside a git repo. The fix pass diffs this before and after so the
+ *  report names real files instead of asserting "fixed" and hoping.
+ *
+ *  The hash is load-bearing, not decoration. Status alone is blind to the most
+ *  common case there is: a file the agent already edited (` M`) that a fixer
+ *  then reformats stays ` M`, so a status-only compare reports "nothing to
+ *  rewrite" while the tree changed under it, and in verify mode that is a
+ *  silent green on unformatted code. Hashing is confined to the dirty set,
+ *  which is small by construction. */
+function treeState(root: string): Map<string, string> | null {
+    const p = Bun.spawnSync(['git', 'status', '--porcelain'], { cwd: root })
+    if (p.exitCode !== 0) return null
+    const m = new Map<string, string>()
+    for (const l of p.stdout.toString().split('\n')) {
+        if (l.trim() === '') continue
+        const status = l.slice(0, 2)
+        // rename entries read `R  old -> new`; the new path is what exists
+        const path = l.slice(3).trim().split(' -> ').at(-1) ?? ''
+        if (path === '') continue
+        const abs = join(root, path.replace(/^"|"$/g, ''))
+        let hash = 'absent'
+        try { if (existsSync(abs)) hash = String(Bun.hash(readFileSync(abs))) } catch { hash = 'unreadable' }
+        m.set(path, `${status}:${hash}`)
+    }
+    return m
+}
+
+export type FixPassOpts = {
+    /** also apply the structural SK rule fixers (default false) */
+    rules?: boolean
+    print: (line: string) => void
+}
+
+export type FixPassResult = {
+    ran: boolean
+    /** paths whose git status changed across the pass */
+    touched: string[]
+    /** verify mode only: a fixer had to rewrite something, so the commit is not clean */
+    failed: boolean
+}
+
+export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpts): Promise<FixPassResult> {
+    // verify mode: same fixers, but rewriting anything means the COMMIT was
+    // not clean, and the gate says so instead of quietly repairing it
+    const verify = process.env.CI != null && process.env.CI !== ''
+    const { slots, unfilled } = resolveFixers(root)
+    for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)
+    const before = treeState(root)
+
+    for (const s of slots) {
+        const r = await spawnWithTimeout(s.cmd, { cwd: root, timeoutMs: FIXER_TIMEOUT_MS })
+        // a broken fixer must never be mistaken for a clean one: the gate
+        // still runs, but the failure is loud and names the command
+        if (r.code !== 0)
+            o.print(`WARN fix ${s.id} failed (exit ${r.code}) — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}; the gate below still ran`)
+    }
+    // structural repo-config repair is never implicit, and never in verify mode
+    if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print })
+
+    const after = treeState(root)
+    const touched: string[] = []
+    if (before != null && after != null) {
+        for (const [path, st] of after) if (before.get(path) !== st) touched.push(path)
+        // a file the fixer restored to its committed state disappears from
+        // porcelain entirely, that is still a change worth naming
+        for (const path of before.keys()) if (!after.has(path)) touched.push(path)
+    }
+    const list = `${touched.slice(0, 8).join(' ')}${touched.length > 8 ? ` … +${touched.length - 8}` : ''}`
+    if (before == null) {
+        o.print(`ok: fix pass ran, ${slots.length} fixer(s) (not a git repo — rewritten files cannot be listed)`)
+        return { ran: true, touched, failed: false }
+    }
+    if (touched.length === 0) {
+        o.print(`ok: ${verify ? 'fixers verified' : 'fix pass'} clean (${slots.length} fixer(s), nothing to rewrite)`)
+        return { ran: true, touched, failed: false }
+    }
+    if (verify) {
+        o.print(`FAIL: ${touched.length} file(s) are not fixer-clean: ${list}`)
+        o.print(`      fix: run \`shipkit ci\` locally (the fix pass rewrites them) and commit the result`)
+        return { ran: true, touched, failed: true }
+    }
+    o.print(`ok: fix pass rewrote ${touched.length} file(s): ${list}`)
+    return { ran: true, touched, failed: false }
+}

package/src/core/write-status.ts

@@ -1,6 +1,5 @@
-// THE STATUS.md writer — every repo gets one (O4, one-runner GO
-// 2026-07-22): timestamp header + verdict + fenced compact render, the
-// shape rv-doctor pioneered. Atomic + lock-guarded via core/locked-write:
+// THE STATUS.md writer — every repo gets one: timestamp header + verdict +
+// fenced compact render. Atomic + lock-guarded via core/locked-write:
 // concurrent runners never interleave — the loser skips with a WARN
 // outcome, never corrupts the file.
 
@@ -12,6 +11,10 @@ export type StatusInput = {
     name: string
     /** the command that produced this render, e.g. 'shipkit ci' */
     command: string
+    /** the run covered the WHOLE gate, so a green may say "clear to ship".
+     *  Absent means it did not: the claim is opt-in, because a caller that
+     *  forgets it costs a nag and a caller that over-claims costs a release. */
+    fullGate?: boolean
     /** the run's printed lines (ANSI stripped here) */
     lines: string[]
     exitCode: number
@@ -27,11 +30,17 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
         const clean = s.lines.map(stripAnsi)
         const fails = clean.filter((l) => l.startsWith('FAIL')).length
         const warns = clean.filter((l) => l.startsWith('WARN')).length
+        // only the full gate may say "clear to ship": a checks-only run proves
+        // the repo is sound, never that the build passes, and a narrowed gate
+        // proves only the slice it ran. the scope rides on the WARN verdict
+        // too, or a narrowed green hides behind a nag nobody reads twice
+        const full = s.fullGate === true
+        const scope = full ? 'clear to ship' : `${s.command} ran, not the whole gate`
         const verdict = s.exitCode !== 0 || fails > 0
             ? `RED — ${Math.max(fails, 1)} FAIL line${fails === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
             : warns > 0
-                ? `GREEN with nags — ${warns} WARN. Proceed.`
-                : 'GREEN — clear to ship.'
+                ? `GREEN with nags — ${warns} WARN. ${full ? 'Proceed.' : `${scope}.`}`
+                : `GREEN — ${scope}.`
         // local time, not UTC — an evening run must not stamp yesterday's date
         const now = new Date()
         const p = (n: number): string => String(n).padStart(2, '0')

package/src/hooks/commit-message.ts

@@ -0,0 +1,42 @@
+// the commit-message predicate, shared by the commit-msg hook (blocks at
+// write time) and SK009 (audits history). one implementation, or the two
+// drift and the drift only shows when a repo goes public.
+//
+// mechanical text rules only, so this stays publishable.
+
+export type OffenseKind = 'dash' | 'attribution'
+export type Offense = { line: number; text: string; kind: OffenseKind; why: string }
+
+/** trailers and footers that name an assistant, plus the robot emoji. */
+export const AI_ATTRIBUTION =
+    /(?:co-authored-by|assisted-by|signed-off-by):[^\n]*\b(?:claude|anthropic|copilot|chatgpt|openai|cursor|aider|devin|gemini)\b|generated with[^\n]*\b(?:claude|copilot|chatgpt|gemini)\b|🤖/i
+
+/** everything below git's scissors line is the verbose-mode diff, which git
+ *  strips before committing, diff content is not ours to police. */
+export function stripNonMessage(message: string): string {
+    const scissors = message.search(/^# -+ >8 -+$/m)
+    return scissors === -1 ? message : message.slice(0, scissors)
+}
+
+/** offenses in ONE commit message (or one commit body from `git log`).
+ *  `#` comment lines never land in the message and are ignored; a `Revert "…"`
+ *  title quotes the reverted subject verbatim and is exempt; a line-start
+ *  `- ` bullet is a list marker, not punctuation. */
+export function commitMessageOffenses(message: string): Offense[] {
+    const offenses: Offense[] = []
+    stripNonMessage(message).split('\n').forEach((raw, i) => {
+        if (raw.startsWith('#')) return
+        if (i === 0 && /^Revert "/.test(raw)) return
+        if (/[—–]/.test(raw))
+            offenses.push({ line: i + 1, text: raw, kind: 'dash', why: 'em/en dash: use a comma, a period, parentheses, or a new sentence' })
+        const body = raw.replace(/^\s*[-*] /, '')
+        if (body.includes(' - '))
+            offenses.push({ line: i + 1, text: raw, kind: 'dash', why: 'inline " - " separator: same fix' })
+        if (AI_ATTRIBUTION.test(raw))
+            offenses.push({ line: i + 1, text: raw, kind: 'attribution', why: 'AI attribution: no assistant trailer, "Generated with" footer, or robot emoji' })
+    })
+    return offenses
+}
+
+export const hasDashPunctuation = (message: string): boolean => commitMessageOffenses(message).some((o) => o.kind === 'dash')
+export const hasAiAttribution = (message: string): boolean => commitMessageOffenses(message).some((o) => o.kind === 'attribution')

package/src/hooks/run-hooks.ts

@@ -0,0 +1,131 @@
+// the git-hook gates, owned by the toolkit rather than by per-repo shell.
+//
+// hand-rolled hooks are invisible to `shipkit check`: a repo reports green
+// while its next commit is already doomed, and nothing can enumerate what
+// the hooks enforce. `shipkit hooks list` answers that without reading shell.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { commitMessageOffenses } from './commit-message.ts'
+import { runLeakGuard } from './leak-guard.ts'
+import { spawnWithTimeout } from '../core/spawn-timeout.ts'
+import type { RepoConfig } from '../repo-config.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') */
+    keywordFile?: string
+    /** disable a built-in gate, visible in `hooks list`, never silent */
+    disable?: ('leak-guard' | 'commit-message')[]
+}
+
+const HOOK_DIR = 'hooks'
+const HOOKS = ['pre-commit', 'commit-msg'] as const
+
+/** wire `core.hooksPath` and write the two hook bodies. Idempotent. */
+export function installHooks(root: string, binInvocation: string): { written: string[]; note: string } {
+    const dir = join(root, HOOK_DIR)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const written: string[] = []
+    for (const h of HOOKS) {
+        const body = h === 'commit-msg'
+            ? `#!/bin/sh\nexec ${binInvocation} hooks commit-msg "$1"\n`
+            : `#!/bin/sh\nexec ${binInvocation} hooks pre-commit\n`
+        const path = join(dir, h)
+        const prev = existsSync(path) ? readFileSync(path, 'utf8') : ''
+        if (prev !== body) { writeFileSync(path, body, { mode: 0o755 }); written.push(`${HOOK_DIR}/${h}`) }
+    }
+    const cfg = Bun.spawnSync(['git', 'config', 'core.hooksPath', HOOK_DIR], { cwd: root })
+    return {
+        written,
+        note: cfg.exitCode === 0 ? `core.hooksPath=${HOOK_DIR}` : `WARN could not set core.hooksPath (exit ${cfg.exitCode}) — hooks will not fire`,
+    }
+}
+
+export type GateOutcome = { id: string; ok: boolean; lines: string[] }
+
+/** the pre-commit gate: built-in leak guard, then the repo's own commands. */
+export async function runPreCommit(root: string, config: RepoConfig): Promise<GateOutcome[]> {
+    const h = config.hooks ?? {}
+    const out: GateOutcome[] = []
+    if (!(h.disable ?? []).includes('leak-guard')) {
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile })
+        if (r.status === 'skipped') out.push({ id: 'leak-guard', ok: true, lines: [`skip: leak-guard (${r.reason})`] })
+        else if (r.status === 'clean') out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean (${r.patterns} pattern(s))`] })
+        else out.push({
+            id: 'leak-guard',
+            ok: false,
+            lines: [
+                `FAIL: leak-guard matched ${r.hits.length} banned pattern(s) — this commit would leak private content`,
+                ...r.hits.map((x) => `      ${x.where}: ${x.pattern}`),
+                `      fix: remove the content, or edit the keyword file if the pattern is wrong`,
+            ],
+        })
+    }
+    for (const c of h.preCommit ?? []) {
+        const r = await spawnWithTimeout(c.cmd, { cwd: root, timeoutMs: 120_000 })
+        out.push({
+            id: c.id,
+            ok: r.code === 0,
+            lines: r.code === 0 ? [`ok: ${c.id}`] : [`FAIL: ${c.id} (exit ${r.code})`, ...r.out.trim().split('\n').slice(-30).map((l) => `      ${l}`)],
+        })
+    }
+    return out
+}
+
+/** the commit-msg gate: the shared message predicate, then the repo's own. */
+export async function runCommitMsg(root: string, config: RepoConfig, messageFile: string): Promise<GateOutcome[]> {
+    const h = config.hooks ?? {}
+    const out: GateOutcome[] = []
+    const message = readFileSync(messageFile, 'utf8')
+    if (!(h.disable ?? []).includes('commit-message')) {
+        const offenses = commitMessageOffenses(message)
+        out.push(offenses.length === 0
+            ? { id: 'commit-message', ok: true, lines: ['ok: commit message clean (no dash punctuation, no AI attribution)'] }
+            : {
+                id: 'commit-message',
+                ok: false,
+                lines: [
+                    `FAIL: commit message has ${offenses.length} offense(s)`,
+                    ...offenses.map((o) => `      line ${o.line}: ${o.text.slice(0, 100)}\n        ${o.why}`),
+                ],
+            })
+    }
+    // the leak guard also reads the MESSAGE, a private name pasted into a
+    // commit body is as public as one pasted into a file
+    if (!(h.disable ?? []).includes('leak-guard')) {
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, text: [{ label: 'commit message', content: message }] })
+        if (r.status === 'hit')
+            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${x.pattern}`)] })
+    }
+    for (const c of h.commitMsg ?? []) {
+        const r = await spawnWithTimeout([...c.cmd, messageFile], { cwd: root, timeoutMs: 60_000 })
+        out.push({
+            id: c.id,
+            ok: r.code === 0,
+            lines: r.code === 0 ? [`ok: ${c.id}`] : [`FAIL: ${c.id} (exit ${r.code})`, ...r.out.trim().split('\n').slice(-30).map((l) => `      ${l}`)],
+        })
+    }
+    return out
+}
+
+/** what blocks a commit here, the enumeration hand-rolled hooks never had. */
+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'
+    // 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)) ? '' : ` (INACTIVE, ${kw} absent)`
+    return [
+        `pre-commit  leak-guard${leakState} — staged content + paths vs ${kw}`,
+        ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
+        `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution`,
+        `commit-msg  leak-guard${leakState} — the message text`,
+        ...(h.commitMsg ?? []).map((c) => `commit-msg  ${c.id} — ${c.cmd.join(' ')}`),
+    ]
+}

package/src/init-repo.ts

@@ -3,11 +3,13 @@
 // deps — every gap is printed, never silent). Plain module behind cmd_Init.
 // Refuses to overwrite an existing config; script merge never clobbers
 // existing keys. `bin` switches script bodies from the npm bin to an
-// in-repo-source CLI path (`bun <path> ci`) for repos that consume shipkit
-// by path instead of from node_modules.
+// in-repo-source CLI path for repos that consume shipkit by path instead of
+// from node_modules. Only bodies shipkit cannot express as a verb are
+// scaffolded: an alias script would be a second name for one capability.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
+import { hasTestFiles } from './rules/SK001-package-json-shape.ts'
 import { reportToMotherhome } from './core/motherhome.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
@@ -19,6 +21,9 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // the mandated 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: no config — drop a <name>.check.ts file anywhere,
     // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
 })
@@ -56,7 +61,10 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // canonical script bodies — ONE source (core/canonical-scripts.ts),
     // shared with rule SK001's autofix; vocabulary owned by
     // meta/rv-conventions/package-json.md
+    // `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 (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
         else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
     }
@@ -73,8 +81,8 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const floor = resolveFloor(defineRepo({ name }), root)
     for (const t of floor.tasks) console.log(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
     for (const u of floor.unfilled) console.log(`skip: ${u.id} (${u.reason})`)
-    // scripts call the `shipkit` bin — dead on arrival unless the package is
-    // actually installed (field bug 2026-07-22: init via bunx, no dep, exit 127)
+    // 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) {
         try {
             Bun.resolveSync('rvlib-shipkit', root)
@@ -83,7 +91,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
             console.log('      fix: bun add -d rvlib-shipkit')
         }
     }
-    console.log('next: fill venues/social in repo.config.ts, then `bun run ci`')
+    console.log('next: fill venues/social in repo.config.ts, then `shipkit ci`')
     console.log('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
     return 0
 }

package/src/reflect/prompt-corpus.ts

@@ -35,8 +35,8 @@ const siblingConfigDirs = (home: string): string[] => {
  * (`:` or `,` separated) PLUS ~/.claude PLUS any sibling ~/.claude-<name>
  * holding a projects/ dir. Additive on purpose — a second local account keeps
  * its own transcripts, and the env var only names the account running RIGHT
- * NOW, so honoring it alone hides every session of the other one (field bug
- * 2026-07-24: a corpus mined that way lost a third of his prompts). */
+ * NOW, so honoring it alone hides every session of the other one — a corpus
+ * mined from a single root is silently partial. */
 export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
     const fromEnv = (process.env.CLAUDE_CONFIG_DIR ?? '')
         .split(/[:,]/)
@@ -137,8 +137,7 @@ export function promptTextOf(line: string): { text: string; entry: RawEntry } |
 /** A prompt he typed while the agent was still working: the harness parks it as
  * `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
  * first, it may NEVER become a user message. Skipping these loses exactly the
- * mid-flight corrections and standing conventions a retrospective is for
- * (measured 2026-07-26: 72 such texts invisible in this repo alone). */
+ * mid-flight corrections and standing conventions a retrospective is for */
 export function queuedTextOf(line: string): { text: string; entry: RawEntry } | null {
     let parsed: unknown
     try {

package/src/release/changelog.ts

@@ -0,0 +1,53 @@
+// reading a versioned CHANGELOG, in one place, because two readers of the
+// same file always drift and the release then ships notes nobody wrote.
+// House convention: newest first, one `## <version>` per released version,
+// `## Unreleased` on top while work accumulates.
+
+/** matches `## 1.2.3`, `## [1.2.3]`, and a dated heading in any of the dash
+ *  shapes real changelogs use (`## 1.2.3 — 2026-07-28`). The dash here is
+ *  DATA in someone's changelog, not prose this repo controls. */
+export const changelogHeading = (version: string): RegExp =>
+    new RegExp(`^##\\s*\\[?${version.replace(/\./g, '\\.')}\\]?\\s*(?:[-–—:(].*)?$`)
+
+/** the `## <version>` section of a versioned changelog, as release notes.
+ *  Throws when the section is missing or empty: a release with no notes is a
+ *  release nobody can read later. */
+export function extractChangelogSection(p: { changelog: string; version: string }): string {
+    const lines = p.changelog.split('\n')
+    const head = changelogHeading(p.version)
+    const start = lines.findIndex((l) => head.test(l.trim()))
+    if (start === -1) throw new Error(`CHANGELOG has no "## ${p.version}" section — write the notes, then release`)
+    let end = lines.length
+    for (let i = start + 1; i < lines.length; i++)
+        if (lines[i]?.startsWith('## ')) { end = i; break }
+    const body = lines.slice(start + 1, end).join('\n').trim()
+    if (body === '') throw new Error(`CHANGELOG section "## ${p.version}" is empty — write the notes, then release`)
+    return body
+}
+
+export const hasVersionSection = (changelog: string, version: string): boolean =>
+    changelog.split('\n').some((l) => changelogHeading(version).test(l.trim()))
+
+const UNRELEASED = /^##\s*\[?unreleased\]?\s*$/i
+
+export const hasUnreleasedHeading = (changelog: string): boolean =>
+    changelog.split('\n').some((l) => UNRELEASED.test(l.trim()))
+
+/** rename the Unreleased heading to the new version. Returns the new text, or
+ *  an error when there is no such section or it carries no notes: a version
+ *  with empty notes is a version nobody can read later. */
+export function promoteUnreleased(changelog: string, version: string): { text: string } | { error: string } {
+    const lines = changelog.split('\n')
+    const at = lines.findIndex((l) => UNRELEASED.test(l.trim()))
+    if (at === -1) return { error: `CHANGELOG has no "## Unreleased" section — write the notes for this version under one, then bump` }
+    let end = lines.length
+    for (let i = at + 1; i < lines.length; i++) if (lines[i]?.startsWith('## ')) { end = i; break }
+    if (lines.slice(at + 1, end).join('\n').trim() === '')
+        return { error: `the "## Unreleased" section is empty — write what changed, then bump` }
+    lines[at] = `## ${version}`
+    return { text: lines.join('\n') }
+}
+
+/** does this unit have notes waiting? `--all` selects on exactly this: having
+ *  something to say IS the decision to ship. */
+export const hasUnreleasedNotes = (changelog: string): boolean => !('error' in promoteUnreleased(changelog, '0.0.0'))