rvlib-shipkit 0.14.0 → 0.17.0

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/root-identity.ts

@@ -0,0 +1,64 @@
+// a commit must not silently change WHICH REPO this is.
+//
+// the failure this exists for: a fixture builder ran with its cwd on the real
+// repo instead of a temp dir, overwrote the root package.json and
+// repo.config.ts with a throwaway shape, and committed. Every other gate
+// passed, because a gutted repo still lints, still typechecks and still has a
+// valid package.json. Only the NAME betrayed it.
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+export type IdentityOutcome =
+    | { status: 'skipped'; reason: string }
+    | { status: 'clean' }
+    | { status: 'changed'; changes: string[]; scratch: string[] }
+
+/** scratch files a refactor leaves behind. They are never a deliberate commit,
+ *  and one of them rode in with the fixture accident. */
+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 })
+    return { code: p.exitCode, out: p.stdout.toString() }
+}
+
+/** the `name:` a repo.config.ts declares, read textually: importing it would
+ *  run the file, and the staged version is exactly the one not to trust. */
+export function configName(source: string): string | null {
+    return source.match(/\bname\s*:\s*['"`]([^'"`]+)['"`]/)?.[1] ?? null
+}
+
+export function packageName(source: string): string | null {
+    try { return (JSON.parse(source) as { name?: string }).name ?? null }
+    catch { return null }
+}
+
+/** compare the INDEX against HEAD: what is about to be committed, versus what
+ *  the repo already agreed it is. Absent on either side is not a change, so
+ *  adding or removing a file is left to the rules that own that. */
+function identityDrift(root: string, path: string, read: (s: string) => string | null): string | null {
+    const staged = git(root, ['show', `:${path}`])
+    const head = git(root, ['show', `HEAD:${path}`])
+    if (staged.code !== 0 || head.code !== 0) return null
+    const before = read(head.out)
+    const after = read(staged.out)
+    if (before == null || after == null || before === after) return null
+    return `${path}: name '${before}' → '${after}'`
+}
+
+export function runRootIdentity(root: string): IdentityOutcome {
+    if (git(root, ['rev-parse', '--verify', 'HEAD']).code !== 0)
+        return { status: 'skipped', reason: 'no HEAD yet — nothing to compare the first commit against' }
+    if (process.env['SHIPKIT_ALLOW_IDENTITY_CHANGE'] === '1')
+        return { status: 'skipped', reason: 'SHIPKIT_ALLOW_IDENTITY_CHANGE=1' }
+
+    const changes = [
+        identityDrift(root, 'package.json', packageName),
+        ...(existsSync(join(root, 'repo.config.ts')) ? [identityDrift(root, 'repo.config.ts', configName)] : []),
+    ].filter((c): c is string => c != null)
+
+    const added = git(root, ['diff', '--cached', '--name-only', '--diff-filter=A'])
+    const scratch = added.out.split('\n').map((l) => l.trim()).filter((l) => l !== '' && SCRATCH.test(l))
+
+    return changes.length === 0 && scratch.length === 0 ? { status: 'clean' } : { status: 'changed', changes, scratch }
+}

package/src/hooks/run-hooks.ts

@@ -0,0 +1,149 @@
+// 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 { runRootIdentity } from './root-identity.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' | 'root-identity')[]
+}
+
+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`,
+            ],
+        })
+    }
+    if (!(h.disable ?? []).includes('root-identity')) {
+        const r = runRootIdentity(root)
+        if (r.status === 'skipped') out.push({ id: 'root-identity', ok: true, lines: [`skip: root-identity (${r.reason})`] })
+        else if (r.status === 'clean') out.push({ id: 'root-identity', ok: true, lines: ['ok: root-identity unchanged'] })
+        else out.push({
+            id: 'root-identity',
+            ok: false,
+            lines: [
+                `FAIL: this commit changes WHICH REPO this is, which is almost always a fixture that escaped its temp dir`,
+                ...r.changes.map((c) => `      ${c}`),
+                ...r.scratch.map((s) => `      adds a scratch file: ${s}`),
+                `      fix: restore the real files (git checkout HEAD -- package.json repo.config.ts) and drop the scratch files`,
+                `      a deliberate rename: SHIPKIT_ALLOW_IDENTITY_CHANGE=1 git commit ...`,
+            ],
+        })
+    }
+    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}`,
+        `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(' ')}`),
+        `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'
@@ -59,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`)
     }
@@ -76,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)
@@ -86,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,70 @@
+// 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()))
+
+// the heading may carry the kind this release IS: `## Unreleased (minor)`.
+// Whoever writes the notes knows whether they broke something, and that is
+// the only moment the answer is cheap. A batch release then needs no single
+// kind imposed across units that changed by different amounts.
+const UNRELEASED = /^##\s*\[?unreleased\]?\s*(?:\((major|minor|patch)\))?\s*$/i
+
+export type ReleaseKind = 'major' | 'minor' | 'patch'
+
+export const hasUnreleasedHeading = (changelog: string): boolean =>
+    changelog.split('\n').some((l) => UNRELEASED.test(l.trim()))
+
+/** the kind declared on the Unreleased heading, or null when it says nothing.
+ *  Null is never guessed into a kind: `--all` refuses and names the unit,
+ *  because a wrong version number reaches a registry and cannot be recalled. */
+export function declaredKind(changelog: string): ReleaseKind | null {
+    for (const l of changelog.split('\n')) {
+        const m = l.trim().match(UNRELEASED)
+        if (m != null) return (m[1]?.toLowerCase() as ReleaseKind | undefined) ?? null
+    }
+    return null
+}
+
+/** 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'))