rvlib-shipkit 0.14.0 → 0.16.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/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'
@@ -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,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'))

package/src/release/git-facts.ts

@@ -0,0 +1,133 @@
+// the git questions a release asks, in one place: which remote to push to,
+// what the worktree is hiding, which tags exist here but nowhere else.
+// Deliberately dependency-free (no config load, no ci) so a check script can
+// import it without dragging the gate in.
+import type { RepoConfig } from '../repo-config.ts'
+
+export function git(root: string, args: string[]): { code: number; out: string } {
+    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
+}
+
+/** the push remote: the current branch's upstream when it has one, else the
+ *  repo's single remote, else refuse. Never prefers a name: a repo whose
+ *  remote is not called `origin` is normal, and guessing strands the tag
+ *  somewhere nobody looks. */
+export function deriveRemote(root: string): { remote: string } | { error: string } {
+    const branch = git(root, ['branch', '--show-current']).out
+    if (branch !== '') {
+        const r = git(root, ['config', '--get', `branch.${branch}.remote`])
+        if (r.code === 0 && r.out !== '') return { remote: r.out }
+    }
+    const r = git(root, ['remote'])
+    if (r.code !== 0) return { error: 'git remote failed (not a repo?)' }
+    const remotes = r.out.split('\n').map((l) => l.trim()).filter((l) => l !== '')
+    if (remotes.length === 0) return { error: 'no git remote configured' }
+    if (remotes.length === 1) return { remote: remotes[0]! }
+    return { error: `branch '${branch === '' ? '(detached)' : branch}' has no upstream and ${remotes.length} remotes exist (${remotes.join(', ')}) — set one with git push -u <remote> <branch>` }
+}
+
+/** the worktree's dirty paths, minus the runner's own log dir. running the
+ *  gate creates that dir, so counting it would make every gated release refuse
+ *  in any repo that does not gitignore it. */
+export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string): string {
+    const logRoot = (config.logDir ?? 'tmp/shipkit-ci').replace(/^\.\//, '').split('/')[0]!
+    const args = pathspec != null && pathspec !== '' ? ['status', '--porcelain', '--', pathspec] : ['status', '--porcelain']
+    return git(root, args).out
+        .split('\n')
+        .filter((l) => l.trim() !== '' && !l.slice(3).trim().replace(/^"|"$/g, '').startsWith(`${logRoot}/`) && l.slice(3).trim() !== `${logRoot}/`)
+        .join('\n')
+}
+
+export const tagExistsLocally = (root: string, tag: string): boolean =>
+    git(root, ['rev-parse', '--quiet', '--verify', `refs/tags/${tag}`]).code === 0
+
+export type RemoteTags = { tags: Set<string> } | { error: string }
+/** tag name → the COMMIT it names on the remote (the peeled oid when the tag
+ *  is annotated), so two tags of the same name can be compared by what they
+ *  describe rather than by their spelling */
+export type RemoteTagRefs = { refs: Map<string, string> } | { error: string }
+
+/** every tag the remote carries, with its commit. One `ls-remote` per repo,
+ *  never one per tag: the caller compares locally. Deliberately unpatterned,
+ *  because `ls-remote <pattern>` drops the peeled `^{}` line and leaves only
+ *  the tag OBJECT id, which differs between two tags of the same commit. */
+export function remoteTagRefs(root: string, remote: string): RemoteTagRefs {
+    const p = Bun.spawnSync(['git', 'ls-remote', '--tags', remote], { cwd: root, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
+    if (p.exitCode !== 0) return { error: `${p.stderr.toString()}${p.stdout.toString()}`.trim().split('\n').at(-1) ?? 'ls-remote failed' }
+    const refs = new Map<string, string>()
+    for (const line of p.stdout.toString().split('\n')) {
+        const [oid, ref] = line.split('\t')
+        const name = ref?.split('refs/tags/')[1]
+        if (oid == null || name == null || name === '') continue
+        const peeled = name.endsWith('^{}')
+        const key = peeled ? name.slice(0, -3) : name
+        // the peeled line always wins, whichever order it arrives in
+        if (peeled || !refs.has(key)) refs.set(key, oid)
+    }
+    return { refs }
+}
+
+export function remoteTags(root: string, remote: string): RemoteTags {
+    const r = remoteTagRefs(root, remote)
+    return 'error' in r ? r : { tags: new Set(r.refs.keys()) }
+}
+
+export type RemoteTagState =
+    | { state: 'absent' }
+    | { state: 'same'; oid: string }
+    /** the name is taken on the remote by another commit — the version is burnt */
+    | { state: 'different'; remoteOid: string; localOid: string | null }
+    | { state: 'unreadable'; error: string }
+
+/** what the remote says about ONE tag. Comparing NAMES is what let a burnt
+ *  version read as "fully released": the tag was there, describing a tree
+ *  nobody released. */
+export function remoteTagState(root: string, remote: string, tag: string): RemoteTagState {
+    const r = remoteTagRefs(root, remote)
+    if ('error' in r) return { state: 'unreadable', error: r.error }
+    const remoteOid = r.refs.get(tag)
+    if (remoteOid == null) return { state: 'absent' }
+    const local = git(root, ['rev-parse', `${tag}^{}`])
+    const localOid = local.code === 0 ? local.out : null
+    return localOid === remoteOid ? { state: 'same', oid: remoteOid } : { state: 'different', remoteOid, localOid }
+}
+
+export type MergeProbe =
+    | { state: 'clean' }
+    | { state: 'conflicts'; paths: string[] }
+    /** this git could not answer, so the caller must not claim either way */
+    | { state: 'unknown'; reason: string }
+
+/** would `from` merge into `tip` cleanly? Answered from the object database:
+ *  `git merge-tree --write-tree` (git 2.38+) writes nothing but objects, so no
+ *  ref moves and no file is checked out. That is what lets a REHEARSAL answer
+ *  the merge question without touching the branch a human treats as a gate.
+ *
+ *  exit 1 covers both conflicts and a ref git could not resolve, so the tree
+ *  oid on stdout is what separates them: no oid means no merge was attempted. */
+export function mergeProbe(root: string, tip: string, from: string): MergeProbe {
+    // env is passed explicitly: Bun resolves argv[0] against the PATH it
+    // captured at startup unless it is, so an older git ahead on PATH would
+    // never be reached, here or in a test that stages one
+    const p = Bun.spawnSync(['git', 'merge-tree', '--write-tree', '--name-only', tip, from], { cwd: root, env: process.env })
+    const out = p.stdout.toString()
+    const [head, ...rest] = out.split('\n')
+    const wroteTree = head != null && /^[0-9a-f]{40}$/.test(head.trim())
+    if (p.exitCode === 0 && wroteTree) return { state: 'clean' }
+    if (p.exitCode === 1 && wroteTree)
+        return { state: 'conflicts', paths: (rest.join('\n').split('\n\n')[0] ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '') }
+    const reason = `${p.stderr.toString()}${out}`.trim().split('\n').filter((l) => l !== '').at(-1) ?? `git merge-tree exited ${p.exitCode}`
+    return { state: 'unknown', reason: `${reason} (needs git 2.38+)` }
+}
+
+/** local tags matching any of the release units' tag shapes that the remote
+ *  does not have. A stranded tag is invisible where he looks (GitHub), so it
+ *  is a failure, not a note. */
+export function strandedTags(p: { root: string; globs: string[]; remote: string }): { stranded: string[]; local: string[] } | { error: string } {
+    const local = p.globs.flatMap((g) => git(p.root, ['tag', '-l', g]).out.split('\n').map((l) => l.trim()).filter((l) => l !== ''))
+    const uniq = [...new Set(local)].sort()
+    const r = remoteTags(p.root, p.remote)
+    if ('error' in r) return r
+    return { stranded: uniq.filter((t) => !r.tags.has(t)), local: uniq }
+}