rvlib-shipkit 0.11.0 → 0.13.0

package/src/core/locked-write.ts

@@ -0,0 +1,39 @@
+// ONE file-lock + atomic-write concern (extracted from write-status when
+// motherhome became the second multi-writer): the lock spans a caller's
+// whole read-modify-write, the write lands via tmp + rename so a killed
+// process can never leave a torn file, and the loser of a race SKIPS —
+// never corrupts, never blocks.
+import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { basename, dirname, join } from 'path'
+
+// a writer that died without unlocking must not wedge the file forever
+const LOCK_STALE_MS = 120_000
+
+export type LockOutcome<T> = { ok: true; value: T } | { ok: false; warn: string }
+
+export function withFileLock<T>(path: string, fn: () => T): LockOutcome<T> {
+    const lockPath = `${path}.lock`
+    const grab = (): boolean => {
+        try { writeFileSync(lockPath, String(process.pid), { flag: 'wx' }); return true } catch { return false }
+    }
+    if (!grab()) {
+        let stale = false
+        try { stale = Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS } catch {
+            // lock vanished between grab and stat — the racing writer just
+            // finished; still skip this round rather than fight over it
+        }
+        if (stale) rmSync(lockPath, { force: true })
+        if (!stale || !grab()) return { ok: false, warn: `${path} locked by another writer — skipped this round` }
+    }
+    try {
+        return { ok: true, value: fn() }
+    } finally {
+        rmSync(lockPath, { force: true })
+    }
+}
+
+export function atomicWrite(path: string, content: string): void {
+    const tmpPath = join(dirname(path), `.${basename(path)}.tmp-${process.pid}`)
+    writeFileSync(tmpPath, content)
+    renameSync(tmpPath, path)
+}

package/src/core/motherhome.ts

@@ -0,0 +1,87 @@
+// Report to the motherhome — upsert this repo's row into the docsBase
+// wiki's `build/shipkit/local-projects.md`, when that page ALREADY EXISTS
+// on this disk. The lib NEVER creates the page and never writes into a
+// relative or URL docsBase: the page is a tracked wiki file, so a real
+// docs checkout has it, and a consumer that merely set docsBase as a
+// fix-pointer prefix must never find surprise files in its docs tree.
+// The whole read-modify-write runs under the shared file lock
+// (core/locked-write) — concurrent reporters never lose rows or tear the
+// file; the loser skips and self-heals on its next run. Rows whose repo
+// path no longer exists are pruned on every write. Churn control: a row
+// rewrites only when its DATA changes or its last-seen day is older than
+// 7 days. Never fails the calling command.
+import { existsSync, readFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, resolve } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { atomicWrite, withFileLock } from './locked-write.ts'
+
+const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
+const END = '<!-- <<< shipkit local-projects -->'
+const STALE_DAYS = 7
+
+type Row = { name: string; root: string; version: string; mode: string; seen: string }
+
+const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
+
+const parseRow = (line: string): Row | null => {
+    const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
+    return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
+}
+
+function libVersion(): string {
+    try { return (JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}
+
+// how this repo consumes the lib — `?` on an unreadable package.json (a
+// read failure must never be rendered as the fact 'path')
+function consumptionMode(root: string): string {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        const spec = { ...pkg.dependencies, ...pkg.devDependencies }['rvlib-shipkit']
+        if (spec == null) return 'path'
+        if (spec.startsWith('link:')) return 'link'
+        if (spec.startsWith('file:')) return 'file'
+        return 'npm'
+    } catch { return '?' }
+}
+
+export type MotherhomeOutcome = { wrote: boolean; note?: string }
+
+export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
+    try {
+        if (config.docsBase == null) return { wrote: false }
+        const base = config.docsBase.startsWith('~/') ? join(homedir(), config.docsBase.slice(2)) : config.docsBase
+        // absolute local paths only — a relative docsBase would resolve
+        // against CWD, a URL is a display prefix
+        if (!base.startsWith('/')) return { wrote: false }
+        const page = join(base, 'build/shipkit/local-projects.md')
+        if (!existsSync(page)) return { wrote: false }
+
+        const mode = consumptionMode(root)
+        // source-consumed code is not the published release its version
+        // string names — disclose it
+        const version = mode === 'npm' ? libVersion() : `${libVersion()}+src`
+        const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
+
+        const r = withFileLock(page, (): MotherhomeOutcome => {
+            const lines = readFileSync(page, 'utf8').split('\n')
+            const b = lines.indexOf(BEGIN)
+            const e = lines.indexOf(END)
+            if (b === -1 || e === -1 || e < b) return { wrote: false, note: `WARN motherhome upsert skipped — markers missing/corrupted in ${page}` }
+            const rows = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
+            const cur = rows.find((row) => row.root === me.root)
+            const dataSame = cur != null && cur.name === me.name && cur.version === me.version && cur.mode === me.mode
+            const fresh = cur != null && (Date.parse(today) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
+            if (dataSame && fresh) return { wrote: false }
+            // prune rows for repos that no longer exist at their recorded path
+            const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
+            atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
+            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})` }
+        })
+        // lock lost to a racing reporter — self-heals on the next run
+        return r.ok ? r.value : { wrote: false }
+    } catch (err) {
+        return { wrote: false, note: `WARN motherhome upsert failed (${String(err).slice(0, 120)}) — registry may be stale` }
+    }
+}

package/src/core/run-check.ts

@@ -8,9 +8,10 @@ import { join, relative } from 'path'
 import { CheckSuite, type CheckOutcome } from './check-suite.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
-import { activeContracts, applyContractsResult, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
-import { evaluatePackageJson } from './package-json-check.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { reportToMotherhome } from './motherhome.ts'
+import { RULES } from '../rules/rule-registry.ts'
+import { runRuleLint } from '../rules/rule.ts'
 import { formatLine, parseWireOutput } from './wire.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -22,6 +23,8 @@ const CHECK_TIMEOUT_MS = 120_000
 export type CheckOpts = {
     json?: boolean
     fresh?: boolean
+    /** report-only for self-maintaining rules (SK005 never touches package.json) */
+    frozen?: boolean
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
     /** line sink — commands pass their context stream; defaults to console */
@@ -33,20 +36,24 @@ export type CheckOpts = {
 export async function runCheck(root: string, o: CheckOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const c = await loadRepoConfig(root)
+    // env carries the flags to child checks — restored after the run so a
+    // long-lived caller (doctor, TUI, hub) is never poisoned by one
+    // fresh/frozen invocation
+    const prevFresh = process.env.SHIPKIT_FRESH
+    const prevFrozen = process.env.SHIPKIT_FROZEN
     if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
+    if (o.frozen === true) process.env.SHIPKIT_FROZEN = '1'
     const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
-    suite.addCheck({
-        name: 'contracts',
-        logic: async (t) => {
-            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
-        },
-    })
-    // built-in shape probe (meta/rv-conventions/package-json.md) — doctor
-    // surface only, deliberately absent from the ci gate
-    suite.addCheck({
-        name: 'package.json',
-        logic: (t) => evaluatePackageJson(t, root, c),
-    })
+    // built-in SK rules (rules/rule-registry.ts) — id-tagged, crash-safe,
+    // fix-pointer floor (rules/rule.ts runRuleLint owns the semantics);
+    // doctor surface only, deliberately absent from the ci gate
+    for (const rule of RULES)
+        suite.addCheck({
+            name: rule.title,
+            remainValidFor: rule.ttl,
+            cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
+            logic: (t) => runRuleLint(rule, t, { root, config: c }),
+        })
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
         ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
@@ -69,12 +76,18 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
         })
     }
     const r = await suite.execute()
+    if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
+    if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
+    // report to the motherhome (docsBase wiki on this disk) — never fails
+    // the check, notes only when it wrote or broke
+    const mh = reportToMotherhome(root, c)
     const statusOutcome = o.status !== false
         ? writeStatus(root, { name: c.name, command: 'shipkit check', lines: r.lines.map((l) => formatLine(l, false)), exitCode: r.exitCode })
         : null
     if (o.json === true) { print(JSON.stringify(r)); return r.exitCode }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of r.lines) print(formatLine(l, color))
+    if (mh.note != null) print(mh.note)
     if (statusOutcome != null && !statusOutcome.written) print(`WARN ${statusOutcome.warn}`)
     return r.exitCode
 }

package/src/core/run-ci.ts

@@ -5,6 +5,7 @@
 // atomic + lock) unless status:false.
 import { join } from 'path'
 import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { reportToMotherhome } from './motherhome.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -44,6 +45,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         onTaskFinish: o.onTaskFinish,
     })
     const code = summary.ok ? 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 })
         if (!st.written) print(`WARN ${st.warn}`)

package/src/core/write-status.ts

@@ -1,11 +1,11 @@
 // 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 (tmp file + rename) and lock-guarded:
+// shape rv-doctor pioneered. Atomic + lock-guarded via core/locked-write:
 // concurrent runners never interleave — the loser skips with a WARN
 // outcome, never corrupts the file.
 
-import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
 import { join } from 'path'
+import { atomicWrite, withFileLock } from './locked-write.ts'
 
 export type StatusInput = {
     /** repo name — headline */
@@ -20,25 +20,10 @@ export type StatusInput = {
 export type StatusOutcome = { written: boolean; warn?: string }
 
 const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '')
-// a runner that died without unlocking must not wedge STATUS.md forever
-const LOCK_STALE_MS = 120_000
 
 export function writeStatus(root: string, s: StatusInput): StatusOutcome {
-    const lockPath = join(root, 'STATUS.md.lock')
-    const grab = (): boolean => {
-        try { writeFileSync(lockPath, String(process.pid), { flag: 'wx' }); return true } catch { return false }
-    }
-    if (!grab()) {
-        let stale = false
-        try { stale = Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS } catch {
-            // lock vanished between grab and stat — the racing writer just
-            // finished; still skip this round rather than fight over it
-        }
-        if (stale) rmSync(lockPath, { force: true })
-        if (!stale || !grab())
-            return { written: false, warn: `STATUS.md locked by another runner (${lockPath}) — skipped this write` }
-    }
-    try {
+    const target = join(root, 'STATUS.md')
+    const r = withFileLock(target, () => {
         const clean = s.lines.map(stripAnsi)
         const fails = clean.filter((l) => l.startsWith('FAIL')).length
         const warns = clean.filter((l) => l.startsWith('WARN')).length
@@ -60,11 +45,7 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
 ${clean.join('\n').trim()}
 \`\`\`
 `
-        const tmpPath = join(root, `.STATUS.md.tmp-${process.pid}`)
-        writeFileSync(tmpPath, body)
-        renameSync(tmpPath, join(root, 'STATUS.md'))
-        return { written: true }
-    } finally {
-        rmSync(lockPath, { force: true })
-    }
+        atomicWrite(target, body)
+    })
+    return r.ok ? { written: true } : { written: false, warn: `STATUS.md locked by another runner — skipped this write` }
 }

package/src/init-repo.ts

@@ -7,7 +7,10 @@
 // by path instead of from node_modules.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { defineRepo, resolveFloor } from './repo-config.ts'
+import { canonicalBodies } from './core/canonical-scripts.ts'
+import { reportToMotherhome } from './core/motherhome.ts'
+import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
+import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
 const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'rvlib-shipkit'
 
@@ -28,7 +31,18 @@ export type InitOpts = {
 
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
     const configPath = join(root, 'repo.config.ts')
-    if (existsSync(configPath)) { console.log(`skip: repo.config.ts already exists`); return 0 }
+    if (existsSync(configPath)) {
+        console.log(`skip: repo.config.ts already exists`)
+        // adoption path: re-running init on an existing repo still converges
+        // its .gitignore policy block (same fixer as `check --fix SK004`),
+        // with the repo's own contributed lines honored
+        const cfg = await loadRepoConfig(root)
+        const g = await gitignorePolicy.fix!({ root, config: cfg })
+        console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        const mh = reportToMotherhome(root, cfg)
+        if (mh.note != null) console.log(mh.note)
+        return 0
+    }
     const pkgPath = join(root, 'package.json')
     if (!existsSync(pkgPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
     const pkgRaw = readFileSync(pkgPath, 'utf8')
@@ -38,23 +52,22 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     console.log('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
     pkg.scripts ??= {}
-    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
     let added = 0
-    // canonical script NAME → shipkit command (hub runs `shipkit serve`) —
-    // vocabulary owned by meta/rv-conventions/package-json.md
-    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve', mv: 'mv' } as const
-    for (const [k, cmd] of Object.entries(CANONICAL)) {
-        const v = run(cmd)
+    // canonical script bodies — ONE source (core/canonical-scripts.ts),
+    // shared with rule SK001's autofix; vocabulary owned by
+    // meta/rv-conventions/package-json.md
+    for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
         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`)
     }
-    // baseline `test` is universal (bun test) — lint/fmt bodies are
-    // stack-specific, the scaffold pages own those
-    if (pkg.scripts['test'] == null) { pkg.scripts['test'] = 'bun test'; added++ }
     if (added > 0) {
         writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
         console.log(`ok: ${added} package.json script(s) added`)
     }
+    // the .gitignore policy block (contract git policy) — same fixer as
+    // `shipkit check --fix SK004`, one code path
+    const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
+    console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     // show what the gate actually is — a thin floor must be seen at init
     // time, not discovered after a bad commit slipped through
     const floor = resolveFloor(defineRepo({ name }), root)

package/src/reflect/prompt-corpus.ts

@@ -0,0 +1,305 @@
+// shipkit reflect — mine the user's TYPED prompts out of Claude Code transcripts.
+// Transcripts live at <configRoot>/projects/<slug>/*.jsonl where <slug> is the
+// repo's absolute path with EVERY non-alphanumeric char replaced by '-'.
+//
+// A corpus is only as good as what it excludes: the harness writes many
+// user-role entries the human never typed (tool results, command wrappers,
+// compaction summaries, subagent prompts). Every filter below exists because
+// one of them polluted a real extraction pass.
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { homedir } from 'os'
+import { basename, join, resolve } from 'path'
+
+export type PromptEntry = {
+    uuid: string
+    timestamp: string
+    sessionId: string
+    /** config root the prompt came from, e.g. `.claude` */
+    account: string
+    text: string
+    /** 'queued' = typed WHILE the agent was working (a `queue-operation` entry).
+     * Same human, higher signal: corrections and standing conventions land there. */
+    origin: 'typed' | 'queued'
+}
+
+export type ConfigRoot = { account: string; projects: string }
+
+const siblingConfigDirs = (home: string): string[] => {
+    if (!existsSync(home)) return []
+    return readdirSync(home)
+        .filter((d) => d.startsWith('.claude-'))
+        .map((d) => join(home, d))
+}
+
+/** EVERY Claude Code config root on this machine, unioned: $CLAUDE_CONFIG_DIR
+ * (`:` 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). */
+export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
+    const fromEnv = (process.env.CLAUDE_CONFIG_DIR ?? '')
+        .split(/[:,]/)
+        .map((p) => p.trim())
+        .filter((p) => p !== '')
+    const seen = new Set<string>()
+    const roots: ConfigRoot[] = []
+    for (const dir of [...fromEnv, join(home, '.claude'), ...siblingConfigDirs(home)]) {
+        const projects = join(resolve(dir), 'projects')
+        if (seen.has(projects) || !existsSync(projects)) continue
+        seen.add(projects)
+        roots.push({ account: basename(resolve(dir)), projects })
+    }
+    return roots
+}
+
+/** Claude Code slugs EVERY non-alphanumeric char to '-', not just '/' */
+export const projectSlug = (repoPath: string): string => resolve(repoPath).replace(/[^a-zA-Z0-9]/g, '-')
+
+// wrappers the harness injects as user-role entries — none of them are typed
+const NOISE_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+    '<system-reminder>',
+    '<task-notification>',
+    'Caveat: The messages below',
+    '[Request interrupted',
+    'This session is being continued from a previous conversation',
+]
+
+export function isTypedPrompt(text: string): boolean {
+    const trimmed = text.trim()
+    if (trimmed === '') return false
+    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
+}
+
+type RawEntry = {
+    type?: unknown
+    entrypoint?: unknown
+    uuid?: unknown
+    timestamp?: unknown
+    sessionId?: unknown
+    isMeta?: unknown
+    isSidechain?: unknown
+    isCompactSummary?: unknown
+    /** queue-operation entries only */
+    operation?: unknown
+    content?: unknown
+    message?: { role?: unknown; content?: unknown }
+}
+
+/** His words out of one transcript line, or null when the line is not a prompt
+ * he typed. isSidechain = a subagent prompt the AGENT wrote; isMeta and
+ * isCompactSummary = harness-generated. Content is a string for a plain prompt,
+ * an array of blocks when the message carried pastes or attachments (the text
+ * blocks in there are still his). */
+export function promptTextOf(line: string): { text: string; entry: RawEntry } | null {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return null // truncated tail line of a live session
+    }
+    if (parsed == null || typeof parsed !== 'object') return null
+    const entry = parsed as RawEntry
+    if (entry.type !== 'user') return null
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
+    if (entry.entrypoint === 'sdk-cli') return null // a script drove this session, nobody typed it
+    if (entry.message?.role !== 'user') return null
+    const content = entry.message.content
+    let text: string
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+        const parts = content
+            .filter((b): b is { type: string; text: string } => b?.type === 'text' && typeof b?.text === 'string')
+            .map((b) => b.text)
+        if (parts.length === 0) return null // pure tool_result turn
+        text = parts.join('\n')
+    } else return null
+    // the harness appends reminder blocks INSIDE real prompts — strip, keep the text
+    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+    // a slash-command entry is a harness WRAPPER around typed text:
+    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
+    // Dropping the whole entry throws away real instructions and repro pastes.
+    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
+    if (args?.[1] != null) {
+        const body = args[1].trim()
+        if (body === '') return null // bare invocation, nothing typed
+        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
+        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
+    }
+    if (!isTypedPrompt(text)) return null
+    return { text, entry }
+}
+
+/** 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). */
+export function queuedTextOf(line: string): { text: string; entry: RawEntry } | null {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return null
+    }
+    if (parsed == null || typeof parsed !== 'object') return null
+    const entry = parsed as RawEntry
+    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
+    if (typeof entry.content !== 'string') return null
+    const text = entry.content.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+    if (!isTypedPrompt(text)) return null
+    return { text, entry }
+}
+
+export function extractPrompts(jsonl: string, ctx: { sessionId: string; account: string }): PromptEntry[] {
+    const out: PromptEntry[] = []
+    for (const line of jsonl.split('\n')) {
+        if (line.trim() === '') continue
+        const queued = queuedTextOf(line)
+        const hit = queued ?? promptTextOf(line)
+        if (hit == null) continue
+        const timestamp = typeof hit.entry.timestamp === 'string' ? hit.entry.timestamp : ''
+        const fallbackId = `${queued == null ? 'typed' : 'queue'}:${ctx.sessionId}:${timestamp}`
+        out.push({
+            uuid: typeof hit.entry.uuid === 'string' ? hit.entry.uuid : fallbackId,
+            timestamp,
+            sessionId: typeof hit.entry.sessionId === 'string' ? hit.entry.sessionId : ctx.sessionId,
+            account: ctx.account,
+            text: hit.text,
+            origin: queued == null ? 'typed' : 'queued',
+        })
+    }
+    return out
+}
+
+/** Genuine repetition is SIGNAL (saying it twice raises priority), so dedupe
+ * must remove only mechanical copies:
+ *   - a resumed/forked session replaying an entry (same uuid, or same text at
+ *     the same instant),
+ *   - a queued prompt that later became a user message (same text, any gap —
+ *     one keystroke, two records).
+ * Anything else repeated is kept, so the corpus never manufactures a priority
+ * he did not give. Input must be chronological. */
+const REPEAT_WINDOW_MS = 5 * 60 * 1000
+
+const normalize = (text: string): string => text.replace(/\s+/g, ' ').trim().toLowerCase()
+
+export function dedupePrompts(prompts: PromptEntry[]): PromptEntry[] {
+    const seenUuid = new Set<string>()
+    const lastSeenAt = new Map<string, number>()
+    /** queued texts not yet matched by their user-message twin — consumption is
+     * ONE-time, so a genuine re-ask of the same words later still counts */
+    const awaitingConsume = new Set<string>()
+    const out: PromptEntry[] = []
+    for (const p of prompts) {
+        if (seenUuid.has(p.uuid)) continue
+        seenUuid.add(p.uuid)
+        const key = normalize(p.text)
+        const at = Number.isNaN(Date.parse(p.timestamp)) ? 0 : Date.parse(p.timestamp)
+        const prev = lastSeenAt.get(key)
+        if (prev != null) {
+            if (awaitingConsume.has(key) && p.origin === 'typed') {
+                awaitingConsume.delete(key) // the queued keystroke arriving as a message
+                lastSeenAt.set(key, at)
+                continue
+            }
+            if (at - prev < REPEAT_WINDOW_MS) continue // replay, or a resend seconds apart
+        }
+        lastSeenAt.set(key, at)
+        if (p.origin === 'queued') awaitingConsume.add(key)
+        out.push(p)
+    }
+    return out
+}
+
+/** Sessions whose transcript was pruned by retention survive only as a
+ * truncated firstPrompt in the per-project sessions-index.json. */
+function indexFallbackPrompts(dir: string, account: string, have: Set<string>): PromptEntry[] {
+    const indexPath = join(dir, 'sessions-index.json')
+    if (!existsSync(indexPath)) return []
+    let index: { entries?: unknown }
+    try {
+        index = JSON.parse(readFileSync(indexPath, 'utf8')) as { entries?: unknown }
+    } catch {
+        return []
+    }
+    const entries = Array.isArray(index.entries) ? index.entries : []
+    const out: PromptEntry[] = []
+    for (const raw of entries) {
+        const e = raw as { sessionId?: string; firstPrompt?: string; created?: string; fullPath?: string }
+        if (typeof e.sessionId !== 'string' || have.has(e.sessionId)) continue
+        if (typeof e.fullPath === 'string' && existsSync(e.fullPath)) continue
+        if (typeof e.firstPrompt !== 'string' || !isTypedPrompt(e.firstPrompt)) continue
+        out.push({
+            uuid: `index:${e.sessionId}`,
+            timestamp: typeof e.created === 'string' ? e.created : '',
+            sessionId: e.sessionId,
+            account,
+            text: `${e.firstPrompt}\n\n[transcript pruned — first prompt only, truncated]`,
+            origin: 'typed',
+        })
+    }
+    return out
+}
+
+export type RepoCorpus = {
+    /** project dirs actually scanned, across every config root */
+    dirs: string[]
+    /** config roots searched — printed when nothing was found */
+    roots: string[]
+    prompts: PromptEntry[]
+}
+
+/** Every prompt he typed in a repo: all config roots, the repo's project dir
+ * PLUS its worktree dirs (`<slug>--claude-worktrees-*`), deduped, chronological. */
+export function collectRepoPrompts(repoPath: string, roots: ConfigRoot[] = discoverConfigRoots()): RepoCorpus {
+    const slug = projectSlug(repoPath)
+    const dirs: string[] = []
+    const prompts: PromptEntry[] = []
+    for (const root of roots) {
+        const projectDirs = readdirSync(root.projects).filter(
+            (d) => d === slug || d.startsWith(`${slug}--claude-worktrees-`),
+        )
+        for (const projectDir of projectDirs) {
+            const dir = join(root.projects, projectDir)
+            dirs.push(dir)
+            const sessions = new Set<string>()
+            for (const file of readdirSync(dir)) {
+                if (!file.endsWith('.jsonl')) continue
+                const sessionId = file.replace(/\.jsonl$/, '')
+                sessions.add(sessionId)
+                prompts.push(
+                    ...extractPrompts(readFileSync(join(dir, file), 'utf8'), { sessionId, account: root.account }),
+                )
+            }
+            prompts.push(...indexFallbackPrompts(dir, root.account, sessions))
+        }
+    }
+    prompts.sort((a, b) => a.timestamp.localeCompare(b.timestamp))
+    return { dirs, roots: roots.map((r) => r.projects), prompts: dedupePrompts(prompts) }
+}
+
+/** Fence a prompt so its own backticks and markdown cannot break the document */
+function fenced(text: string): string {
+    const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map((m) => m[0].length))
+    const fence = '`'.repeat(Math.max(3, longest + 1))
+    return `${fence}text\n${text}\n${fence}`
+}
+
+/** Chronological corpus, one numbered section per prompt — meant to be read as
+ * a corpus, not as a task list. */
+export function corpusMarkdown(repoPath: string, prompts: PromptEntry[]): string {
+    const queued = prompts.filter((p) => p.origin === 'queued').length
+    const count = queued === 0 ? `${prompts.length}` : `${prompts.length}, ${queued} queued mid-run`
+    const lines: string[] = [`# prompt corpus — ${resolve(repoPath)} (${count})`, '']
+    prompts.forEach((p, i) => {
+        const when = p.timestamp.replace('T', ' ').slice(0, 16)
+        const tag = p.origin === 'queued' ? ' · queued' : ''
+        lines.push(`## ${i + 1} · ${when} · ${p.account} · ${p.sessionId.slice(0, 8)}${tag}`, '', fenced(p.text), '')
+    })
+    return `${lines.join('\n')}\n`
+}