rvlib-shipkit 2.1.0 → 2.2.0

package/src/cli/kit/verb.ts

@@ -0,0 +1,157 @@
+// a project CLI command over code that already exists is a ROW, never a second
+// implementation: `verbs([...])` turns rows into clipanion commands that spawn
+// the script, ask the warm tool, or run the command line, from the repo root.
+// A family file imports this module and nothing heavy at its top: the bare
+// listing loads every family.
+import { type BaseContext, Command, type CommandClass as ClipanionClass, Option } from 'clipanion'
+import { existsSync } from 'fs'
+import { isAbsolute, resolve } from 'path'
+
+/** what a kit command sees in `this.context`, beside clipanion's streams */
+export type KitContext = BaseContext & {
+    /** the repo root: every row runs from it */
+    root: string
+    /** where the caller stood: a filmable row's `--out` resolves against it */
+    cwd: string
+    /** every command class registered in this process (the docs read their marks) */
+    classes: CommandClass[]
+    /** the warm path of a `{ tool }` row, when the project has a warm host */
+    askTool?: AskTool
+}
+
+export type CommandClass = ClipanionClass<KitContext>
+
+/** asks a warm process for a tool's answer; null = no warm host, run the cold script */
+export type AskTool = (tool: string, args: string[]) => Promise<number | null>
+
+/** how a row runs */
+export type Run =
+    /** `bun <script> ...pre ...args` */
+    | { bun: string; pre?: string[] }
+    /** the warm host's answer when it runs (`askTool`), else `bun <cold> ...pre ...args` */
+    | { tool: string; cold: string; pre?: string[] }
+    /** any command line, the args appended */
+    | { cmd: string[] }
+
+/** a row that shoots a state: `still` writes one image at `--out`, `clip` a video, its length `--seconds` */
+export type Film = 'still' | 'clip'
+
+/** an everyday command, listed on the essentials page every session loads */
+export type Essential = {
+    /** its arguments as an agent types them: '<x> <y>' */
+    args?: string
+    /** how many of its examples the page shows under its line */
+    examples?: number
+}
+
+export type Verb = {
+    /** the words after the binary: 'world at' */
+    path: string
+    /** the group the listing prints it under */
+    category: string
+    /** one line, under 100 characters */
+    description: string
+    /** the longer text `--help` prints */
+    details?: string
+    /** [label, command line], each line starting with the binary and the row's words */
+    examples: [string, string][]
+    run: Run
+    /** 'own': `--help` also runs the tool with `--help`, which prints its flags and exits 0 */
+    help?: 'own'
+    essential?: Essential
+    /** filmable: takes `--out <path>`, a clip also `--seconds <n>` (a trailer `film` line calls it) */
+    film?: Film
+}
+
+/** the argv a row runs */
+export function argvOf(run: Run, args: readonly string[]): string[] {
+    if ('bun' in run) return ['bun', run.bun, ...(run.pre ?? []), ...args]
+    if ('tool' in run) return ['bun', run.cold, ...(run.pre ?? []), ...args]
+    return [...run.cmd, ...args]
+}
+
+/** what a row runs, as the commands page prints it */
+export function runText(run: Run): string {
+    if ('bun' in run) return [run.bun, ...(run.pre ?? [])].join(' ')
+    if ('tool' in run) return `tool ${run.tool} (cold: ${[run.cold, ...(run.pre ?? [])].join(' ')})`
+    return run.cmd.join(' ')
+}
+
+/** the value after `flag` in args (`--out x` or `--out=x`), with its index */
+function flagAt(args: readonly string[], flag: string): { i: number; value: string; joined: boolean } | null {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i]!
+        if (a === flag && i + 1 < args.length) return { i, value: args[i + 1]!, joined: false }
+        if (a.startsWith(`${flag}=`)) return { i, value: a.slice(flag.length + 1), joined: true }
+    }
+    return null
+}
+
+/** the film contract on one call: a usage error, or the args with `--out`
+ *  made absolute against the caller's cwd and the file the run must leave */
+export function filmCall(film: Film | undefined, args: readonly string[], cwd: string): { error: string } | { args: string[]; out: string | null } {
+    if (film == null) return { args: [...args], out: null }
+    if (film === 'still' && flagAt(args, '--seconds') != null) return { error: '--seconds films a clip, and this row films a still' }
+    const out = flagAt(args, '--out')
+    if (out == null) return { args: [...args], out: null }
+    const abs = isAbsolute(out.value) ? out.value : resolve(cwd, out.value)
+    const next = [...args]
+    if (out.joined) next[out.i] = `--out=${abs}`
+    else next[out.i + 1] = abs
+    return { args: next, out: abs }
+}
+
+const isHelp = (a: string): boolean => a === '--help' || a === '-h'
+
+/** runs an argv from `cwd` with the terminal handed over; its exit code */
+export async function spawnHere(argv: string[], cwd: string): Promise<number> {
+    const p = Bun.spawn(argv, { cwd, env: process.env, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+    return await p.exited
+}
+
+/** the row each class was made from, so the docs print what it runs */
+export const ROW_OF = new WeakMap<object, Verb>()
+
+/** one clipanion command per row: the args after the path go to the code as typed */
+export function verbs(rows: Verb[]): CommandClass[] {
+    return rows.map((v) => {
+        class VerbCommand extends Command<KitContext> {
+            static override paths = [v.path.split(' ')]
+            static override usage = Command.Usage({ category: v.category, description: v.description, details: v.details, examples: v.examples })
+            static essential = v.essential
+            static film = v.film
+            args = Option.Proxy()
+            async execute(): Promise<number> {
+                const { root, cwd } = this.context
+                if (this.args.some(isHelp)) {
+                    this.context.stdout.write(this.cli.usage(VerbCommand, { detailed: true }))
+                    if (v.help !== 'own') return 0
+                    this.context.stdout.write(`\nthe tool's own help:\n\n`)
+                    return spawnHere(argvOf(v.run, this.args), root)
+                }
+                const call = filmCall(v.film, this.args, cwd)
+                if ('error' in call) { this.context.stderr.write(`FAIL: ${v.path}: ${call.error}\n`); return 2 }
+                let code: number | null = null
+                if ('tool' in v.run && this.context.askTool != null) code = await this.context.askTool(v.run.tool, [...(v.run.pre ?? []), ...call.args])
+                code ??= await spawnHere(argvOf(v.run, call.args), root)
+                if (code === 0 && call.out != null && !existsSync(call.out)) {
+                    this.context.stderr.write(`FAIL: ${v.path} exited 0 and wrote no ${call.out}\n      fix: a filmable row writes its --out path\n`)
+                    return 1
+                }
+                return code
+            }
+        }
+        ROW_OF.set(VerbCommand, v)
+        return VerbCommand
+    })
+}
+
+/** the marks a command class carries: set by `verbs()` from its row, or
+ *  declared as statics on a hand written class */
+export function marksOf(c: object): { essential?: Essential; film?: Film } {
+    const o = c as { essential?: unknown; film?: unknown }
+    const out: { essential?: Essential; film?: Film } = {}
+    if (typeof o.essential === 'object' && o.essential !== null) out.essential = o.essential as Essential
+    if (o.film === 'still' || o.film === 'clip') out.film = o.film
+    return out
+}

package/src/cli/list-flag.ts

@@ -0,0 +1,3 @@
+/** a repeatable flag's values, each also split on commas: `--only a,b` is `--only a --only b` */
+export const listFlag = (values: readonly string[] | undefined): string[] =>
+    (values ?? []).flatMap((v) => v.split(',')).map((v) => v.trim()).filter((v) => v !== '')

package/src/cli.ts

@@ -7,6 +7,7 @@ import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
 import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
 import { BumpCommand } from './cli/cmd_Bump.ts'
+import { CallsCommand } from './cli/cmd_Calls.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
@@ -35,8 +36,10 @@ import { CacheAuditCommand } from './cli/cmd_CacheAudit.ts'
 import { TraceAuditCommand } from './cli/cmd_TraceAudit.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
+import { ShotCommand } from './cli/cmd_Shot.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
+import { TrailerCheckCommand, TrailerCommand, TrailerShotCommand } from './cli/cmd_Trailer.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -67,6 +70,9 @@ export function buildCli(): Cli {
     cli.register(MvCommand)
     cli.register(CheckCommand)
     cli.register(TuiCommand)
+    cli.register(TrailerCommand)
+    cli.register(TrailerCheckCommand)
+    cli.register(TrailerShotCommand)
     cli.register(ServeCommand)
     cli.register(PmCommand)
     cli.register(DaemonCommand)
@@ -91,6 +97,7 @@ export function buildCli(): Cli {
     cli.register(FleetCommand)
     cli.register(PbCollectionCommand)
     cli.register(SmokeCommand)
+    cli.register(ShotCommand)
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
     cli.register(GlobalProcessesCommand)
@@ -109,6 +116,7 @@ export function buildCli(): Cli {
     cli.register(TraceAuditCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
+    cli.register(CallsCommand)
     cli.register(ConfigKeysCommand)
 
     return cli
@@ -117,14 +125,17 @@ export function buildCli(): Cli {
 // only when this file IS the process, so importing it costs nothing. A repo's
 // installed copy first hands the command to the house source (handoff.ts). One copy
 // of the lib per process: a repo config that imports its own install lands on
-// this one (one-lib.ts), so the machine's version runs in every repo. Then pm
-// is started when it is down (autostart.ts), before the command runs
+// this one (one-lib.ts), so the machine's version runs in every repo. The run
+// is logged (cli/kit/calls.ts, read back by `sk calls`). Then pm is started
+// when it is down (autostart.ts), before the command runs
 if (import.meta.main) {
     const argv = aliasArgs(process.argv.slice(2))
     const { handoff } = await import('./home/handoff.ts')
     handoff(argv)
     const { installOneLib } = await import('./core/one-lib.ts')
     installOneLib()
+    const { callsFile, logCall } = await import('./cli/kit/calls.ts')
+    logCall(callsFile((await import('os')).homedir(), 'sk'), 'sk', argv)
     const { autostart } = await import('./home/autostart.ts')
     await autostart(argv)
     void buildCli().runExit(argv)

package/src/core/layout.ts

@@ -22,6 +22,9 @@ export const LAYOUT = {
     // a bug's repro test once its fix lands: kept for the record, never run
     // (bun test skips dot dirs), moved into the suite only when it earns its wait
     repros: sk('repros'),
+    // plans, arc boards and lane files: live state a crashed session resumes
+    // from. Tracked in a private repo only, since a board quotes the owner
+    plans: sk('plans'),
     // local: drafts, private notes, venue listings until they go live
     private: sk('private'),
     reflections: sk('reflections'),
@@ -33,8 +36,10 @@ export const LAYOUT = {
     discord: sk('discord'),
     // a review with no output file named by its caller (YYYYMMDD-HHMMSS-<name>.md)
     reviews: sk('reviews'),
-    // scratch: plans, logs, leases, detached runs, screenshots
+    // gitignored scratch, never a plan home: logs, leases, detached runs, screenshots
     tmp: sk('tmp'),
+    // a CLI's call log, `<cli>-calls.jsonl`: local, never tracked
+    logs: sk('logs'),
     // built app bundles, one per global process opened as an app (home/gui-app.ts)
     wrapper: sk('wrapper'),
     // generated on every run
@@ -44,7 +49,10 @@ export const LAYOUT = {
 } as const
 
 /** the children the SK004 block re-includes: everything else under `.shipkit/` stays local */
-export const TRACKED_DIRS = [LAYOUT.asks, LAYOUT.hooks, LAYOUT.identity, LAYOUT.assets, LAYOUT.comfy, LAYOUT.repros] as const
+export const TRACKED_DIRS = [LAYOUT.asks, LAYOUT.hooks, LAYOUT.identity, LAYOUT.assets, LAYOUT.comfy, LAYOUT.repros, LAYOUT.plans] as const
+
+/** a plan file name: `YYYYMMDD-HHMMSS-<slug>.md` */
+export const PLAN_FILE = /^\d{8}-\d{6}-.+\.md$/
 
 /** the machine-global private folder, under $HOME: one keyword list and one
  *  allowlist per machine, never copied into a repo */

package/src/core/migrate-layout.ts

@@ -3,8 +3,8 @@
 // repair a contract folder typed under a wrong name, in ONE pass and ONE commit.
 //
 // Nothing here is a decision, so no human is asked: `.rv-<x>/` became
-// `.shipkit/<x>/`, `asks/`, `hooks/` and the `tmp/` scratch moved in, the
-// generated files moved out of the root. A typo (`rv-reflections`, `.rv-reflection`) is the same
+// `.shipkit/<x>/`, `asks/`, `hooks/` and the `tmp/` scratch moved in (its dated
+// plans into `.shipkit/plans/`), the generated files moved out of the root. A typo (`rv-reflections`, `.rv-reflection`) is the same
 // move, because a folder under a name no scanner reads is silence.
 //
 // The invariant a reader breaks first: A MOVE NEVER CHANGES WHAT GIT TRACKS.
@@ -27,7 +27,7 @@ import { dirname, join, posix } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import { gitBin } from './git-bin.ts'
 import { probeGitRoot } from './git-root.ts'
-import { LAYOUT, MACHINE_PRIVATE, SHIPKIT_DIR } from './layout.ts'
+import { LAYOUT, MACHINE_PRIVATE, PLAN_FILE, SHIPKIT_DIR } from './layout.ts'
 import { machineCommit } from './machine-commit.ts'
 import { nestedIn } from './nesting.ts'
 
@@ -41,9 +41,11 @@ const CONFIG_FILE = 'repo.config.ts'
  *  hole where the list should be */
 export function layoutSummary(r: { moved: LayoutMove[]; removed: string[] }): string {
     const list = (xs: string[]): string => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`)
-    const folders = r.moved.filter((m) => m.kind !== 'cache').map((m) => `${m.from}/`)
+    const folders = r.moved.filter((m) => m.kind !== 'cache' && m.kind !== 'plan').map((m) => `${m.from}/`)
+    const plans = r.moved.filter((m) => m.kind === 'plan').length
     const parts = [
         ...(folders.length > 0 ? [`move ${list(folders)} under ${SHIPKIT_DIR}/`] : []),
+        ...(plans > 0 ? [`file ${plans} plan${plans === 1 ? '' : 's'} under ${LAYOUT.plans}/`] : []),
         ...(r.removed.length > 0 ? [`drop the root ${list(r.removed)}, which shipkit writes under ${SHIPKIT_DIR}/`] : []),
     ]
     return parts.join(', and ')
@@ -76,7 +78,8 @@ const shapeOf = (s: string): string => s.toLowerCase().replace(/^\.+/, '').repla
 
 const LEGACY_NAME = /^\.rv-([a-z0-9][a-z0-9-]*)$/
 
-export type MoveKind = 'contract' | 'typo' | 'asks' | 'hooks' | 'cache' | 'tmp'
+/** 'plan' moves one FILE, every other kind a folder */
+export type MoveKind = 'contract' | 'typo' | 'asks' | 'hooks' | 'cache' | 'tmp' | 'plan'
 /** a move onto a folder that already exists, whose files collide nowhere.
  *  `drop`: stale leases left behind rather than moved over the live ones */
 export type MergeMove = LayoutMove & { merge: true; drop?: string[] }
@@ -97,6 +100,10 @@ export type PlanInput = {
     legacyCache?: boolean
     /** a clone or a worktree sits somewhere under `tmp/` */
     tmpHoldsRepo?: boolean
+    /** file names at the top of `tmp/` */
+    tmpFiles?: string[]
+    /** names already under `.shipkit/plans/` */
+    planEntries?: string[]
 }
 
 /** a `.git` anywhere under a folder: a clone or a linked worktree, whose
@@ -146,7 +153,15 @@ export function planLayoutMigration(i: PlanInput): LayoutPlan {
     // every repo's scratch, shipkit's own logs and the repo's plans alike
     if (i.rootDirs.includes(LEGACY_TMP)) {
         if (i.tmpHoldsRepo === true) refusals.push({ from: LEGACY_TMP, to: LAYOUT.tmp, reason: 'a git checkout sits under it, and a moved worktree loses its registration' })
-        else add(LEGACY_TMP, LAYOUT.tmp, 'tmp')
+        else {
+            // a dated plan is live state, so it lands where plans live, never in
+            // the scratch any agent may empty. A name already taken there stays
+            // with the scratch rather than overwrite a plan
+            const taken = new Set(i.planEntries ?? [])
+            for (const f of (i.tmpFiles ?? []).filter((f) => PLAN_FILE.test(f) && !taken.has(f)).sort())
+                moves.push({ from: `${LEGACY_TMP}/${f}`, to: `${LAYOUT.plans}/${f}`, kind: 'plan' })
+            add(LEGACY_TMP, LAYOUT.tmp, 'tmp')
+        }
     }
     return { moves, refusals }
 }
@@ -293,7 +308,9 @@ function mergeWhereNothingCollides(root: string, plan: LayoutPlan): LayoutPlan {
         let clash = true
         let drop: string[] = []
         try {
-            const both = twin || !isDir(from) || !isDir(to) ? null : filesUnder(from).filter((f) => existsSync(join(to, f)))
+            // a plan leaves the scratch before it moves, so it collides nowhere
+            const filed = new Set(moves.filter((m) => m.kind === 'plan').map((m) => m.from.slice(r.from.length + 1)))
+            const both = twin || !isDir(from) || !isDir(to) ? null : filesUnder(from).filter((f) => !filed.has(f) && existsSync(join(to, f)))
             drop = scratch && both != null ? both.filter((f) => STALE_LEASE.test(f)) : []
             clash = both == null || both.length > drop.length
         } catch { clash = true }
@@ -361,6 +378,10 @@ const dirsIn = (root: string): string[] => {
 
 const isDir = (p: string): boolean => { try { return statSync(p).isDirectory() } catch { return false } }
 
+const filesIn = (dir: string): string[] => {
+    try { return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => e.name) } catch { return [] }
+}
+
 /** does core.hooksPath point at the legacy `hooks/`, holding a shipkit pre-commit */
 export function legacyHooksOurs(root: string): boolean {
     const r = git(root, ['config', 'core.hooksPath'])
@@ -405,13 +426,15 @@ export function readPlanInput(root: string, config?: RepoConfig): PlanInput {
         hooksOurs: existsSync(join(root, 'hooks')) && legacyHooksOurs(root),
         legacyCache: isDir(join(root, LEGACY_CACHE)),
         tmpHoldsRepo: isDir(join(root, LEGACY_TMP)) && holdsRepo(join(root, LEGACY_TMP)),
+        tmpFiles: filesIn(join(root, LEGACY_TMP)),
+        planEntries: isDir(join(root, LAYOUT.plans)) ? readdirSync(join(root, LAYOUT.plans)) : [],
     }
 }
 
 /** a repo still carrying the old layout: the names a check reports */
 export function legacyLayoutLeft(root: string, config?: RepoConfig): string[] {
     const plan = planLayoutMigration(readPlanInput(root, config))
-    return [...plan.moves.filter((m) => m.kind !== 'cache').map((m) => `${m.from}/`), ...plan.refusals.map((r) => `${r.from}/`)]
+    return [...plan.moves.filter((m) => m.kind !== 'cache' && m.kind !== 'plan').map((m) => `${m.from}/`), ...plan.refusals.map((r) => `${r.from}/`)]
 }
 
 const lsFiles = (root: string, paths: string[]): string[] => {

package/src/core/one-way-in-policy.ts

@@ -59,7 +59,7 @@ export const RAW_RUNNERS: readonly RawRunner[] = [
  *  segment at a time, so `cd x && bun test` is caught too */
 export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
     const off = new Set(exemptSlots)
-    return [...RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`), GIT_STASH_RULE]
+    return [...RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`), ...GIT_STASH_RULES]
 }
 
 // `git stash` in a tree that other agents share takes every agent's
@@ -69,11 +69,19 @@ export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
 // `bash -c '...'`, after git's own global options (`git -C dir stash`), or
 // through `eval`: the guard closes those (stashCallIn).
 export const GIT_STASH_HEAD = 'git stash'
-export const GIT_STASH_RULE = `Bash(${GIT_STASH_HEAD}*)`
 
-/** the stash subcommands that only read, which the guard lets through */
+/** the stash subcommands that only read: no deny row and no guard refusal touches them */
 const STASH_READS = new Set(['list', 'show'])
 
+/** the stash forms that move work, one deny row each. Claude Code matches a row by prefix, so one blanket
+ *  `Bash(git stash*)` row also refused `git stash list` and `git stash show`. `Bash(git stash)` (no star) is the bare
+ *  form, `git stash -*` the option led ones (`git stash -u`, `-m msg`), both meaning push */
+const STASH_WRITES = ['push', 'pop', 'apply', 'drop', 'clear', 'save', 'store', 'create', 'branch'] as const
+export const GIT_STASH_RULES: readonly string[] = [`Bash(${GIT_STASH_HEAD})`, `Bash(${GIT_STASH_HEAD} -*)`, ...STASH_WRITES.map((w) => `Bash(${GIT_STASH_HEAD} ${w}*)`)]
+
+/** the blanket row older repos carry: it blocks the reads too, SK013 replaces it with GIT_STASH_RULES */
+export const LEGACY_STASH_RULE = `Bash(${GIT_STASH_HEAD}*)`
+
 /** git's global options that take their value as the NEXT word */
 const GIT_VALUE_OPTS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env', '--exec-path'])
 
@@ -158,7 +166,7 @@ export function stashCallIn(command: string, depth = 0): string | null {
 
 /** what a stash refusal says: why, what to do instead, how to lift it */
 export function stashRefusal(segment: string): string {
-    return `\`${segment.slice(0, 80)}\` stashes: in a tree that other agents share, a stash takes every agent's uncommitted work, not just yours. Set your own work aside with a commit by pathspec (git commit -m … -- <paths>), and read an existing stash by revision: \`git log -g --oneline refs/stash\`, \`git show stash@{0}:<file>\`. Lifting this: delete the "${GIT_STASH_RULE}" line from .claude/settings.json permissions.deny (identity/how-we-commit.md).`
+    return `\`${segment.slice(0, 80)}\` stashes: in a tree that other agents share, a stash takes every agent's uncommitted work, not just yours. Set your own work aside with a commit by pathspec (git commit -m … -- <paths>), and read an existing stash by revision: \`git log -g --oneline refs/stash\`, \`git show stash@{0}:<file>\`. Reading a stash (\`git stash list\`, \`git stash show\`) is never refused. SK013 writes these rows in every shipkit repo (identity/how-we-commit.md): lifting them is a change to that rule, not a settings edit.`
 }
 
 /** what a refusal says. Never just the ban: a refusal with no replacement

package/src/mv/mv-md.ts

@@ -154,7 +154,8 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     let touched = 0
     for (const f of tracked) {
         const p = join(root, f)
-        if (!existsSync(p)) continue
+        // a submodule is one ls-files entry and a directory: nothing to read
+        if (!isFile(p)) continue
         const before = readFileSync(p, 'utf8')
         let after = retargetRelativeRefs(root, before, dirOf(f), dirOf(moves.get(f) ?? f), moves)
         for (const [oldTok, newTok] of pairs) after = after.replace(bound(oldTok), newTok)

package/src/reflect/prompt-corpus.ts

@@ -67,6 +67,11 @@ const NOISE_PREFIXES = [
     'Caveat: The messages below',
     '[Request interrupted',
     'This session is being continued from a previous conversation',
+    // model output parked in the queue (or wrapped as a meta entry): a
+    // sub-agent's hand-back, and a message another Claude session sent
+    '<agent-message',
+    '<cross-session-message',
+    'Another Claude session sent a message',
 ]
 
 export function isTypedPrompt(text: string): boolean {

package/src/scaffold/cli-skeleton.ts

@@ -0,0 +1,149 @@
+// the project CLI a started repo gets on day one: `src/cli.ts` on the kit
+// (cli/kit/), named for the project, one example family, and the package.json
+// `cli` script plus a `bin` of the project's name. Pure text here; the scaffold
+// writes it create-only, so a repo that already has any of it keeps its own.
+import { Cli } from 'clipanion'
+import { commandRows, type Definition, newCommandsPage, renderEssentials, renderMarkdown, spliceBlock } from '../cli/cmd_Commands.ts'
+import { builtinCommands } from '../cli/kit/builtins.ts'
+import { type Verb, verbs } from '../cli/kit/verb.ts'
+
+/** the entry: the family table and nothing else. `absolute`: the repo's
+ *  tsconfig maps `src/*`, the house import form; else a relative import */
+export function cliEntry(name: string, absolute = true): string {
+    return `#!/usr/bin/env bun
+// ${name}: the project CLI, one command for every act an agent or a human does in this repo.
+// A family is src/cli/cmd_<Family>.ts exporting \`commands\`; the table names the first words
+// each family owns, so a call loads its family alone. \`${name}\` lists every command.
+import { resolve } from 'path'
+import { runProjectCli } from 'rvlib-shipkit/cli-kit'
+
+await runProjectCli({
+    name: '${name}',
+    root: resolve(import.meta.dir, '..'),
+    families: [
+        { roots: ['dev', 'shot'], load: () => import('${absolute ? 'src/cli/cmd_Dev.ts' : './cli/cmd_Dev.ts'}') },
+    ],
+})
+`
+}
+
+/** the example family's live row, as data: the source text and the day-one
+ *  pages are both made from it, so they cannot disagree */
+export function exampleRow(name: string, devScript = false): Verb {
+    return {
+        path: 'dev',
+        category: 'Run',
+        description: devScript ? 'the dev process (package.json dev)' : 'the dev process: src/index.ts, restarted on save',
+        examples: [['start it', `${name} dev`]],
+        run: devScript ? { cmd: ['bun', 'run', 'dev'] } : { cmd: ['bun', '--watch', 'src/index.ts'] },
+        essential: {},
+    }
+}
+
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+
+/** the example family: a row over code that exists, and the shot row a visual
+ *  project uncomments once it has a renderer */
+export function exampleFamily(name: string, devScript = false): string {
+    const v = exampleRow(name, devScript)
+    const run = 'cmd' in v.run ? `{ cmd: [${v.run.cmd.map(q).join(', ')}] }` : ''
+    return `// a command over code that exists is a row: run is { bun: <script> }, { cmd: [...] }
+// or { tool, cold } (a warm host, else the cold script). Mark an everyday row
+// \`essential: {}\`. \`sk ci\` rewrites the agent pages (cli-pages.check.shipkit.ts), or: ${pagesCommand(name)}
+import { verbs } from 'rvlib-shipkit/cli-kit'
+
+export const commands = verbs([
+    {
+        path: ${q(v.path)},
+        category: ${q(v.category)},
+        description: ${q(v.description)},
+        examples: [[${v.examples[0]!.map(q).join(', ')}]],
+        run: ${run},
+        essential: {},
+    },
+    // a visual project: any state as a png, the same command filmed by a trailer line.
+    // film: 'still' means the script takes --out <path>; 'clip' also takes --seconds <n>.
+    // {
+    //     path: 'shot',
+    //     category: 'Look',
+    //     description: 'any state of the app as a png',
+    //     examples: [['the home screen', '${name} shot home --out shot.png']],
+    //     run: { bun: 'scripts/shot.ts' },
+    //     film: 'still',
+    // },
+])
+`
+}
+
+/** where a project CLI's two agent pages live */
+export const cliPages = (name: string): { all: string; essentials: string } => ({ all: `agent/${name}.md`, essentials: `agent/${name}-essentials.md` })
+
+/** the command that writes both pages */
+export const pagesCommand = (name: string): string => `${name} commands --out ${cliPages(name).all} --essentials ${cliPages(name).essentials}`
+
+/** the day-one pages, exactly as \`<name> commands --out … --essentials …\` writes them */
+export function skeletonPages(name: string, devScript = false): { all: string; essentials: string } {
+    const cli = new Cli({ binaryName: name })
+    const builtins = builtinCommands(name)
+    const classes = [...verbs([exampleRow(name, devScript)]), ...builtins.docs, ...builtins.calls]
+    for (const c of classes) cli.register(c)
+    const defs = cli.definitions() as Definition[]
+    const rows = commandRows(defs, (cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }), name, classes)
+    return {
+        all: spliceBlock(newCommandsPage(name, cliPages(name).all), renderMarkdown(rows, name), name)!,
+        essentials: renderEssentials(rows, name, pagesCommand(name)),
+    }
+}
+
+/** the package.json keys the project CLI needs, only where the key is free.
+ *  Returns the keys it filled */
+export function addCliKeys(pkg: { scripts?: Record<string, string>; bin?: Record<string, string> | string }, name: string): string[] {
+    const filled: string[] = []
+    pkg.scripts ??= {}
+    if (pkg.scripts.cli == null) { pkg.scripts.cli = 'bun src/cli.ts'; filled.push('scripts.cli') }
+    if (pkg.bin == null) { pkg.bin = { [name]: './src/cli.ts' }; filled.push(`bin.${name}`) }
+    return filled
+}
+
+/** what says a repo already has a CLI, its own or its product's: a `cli`
+ *  script, any `bin`, any script that runs a cli.ts or cli.js of the repo, a
+ *  src/cli.ts or a src/cli/ folder. null = the skeleton has room */
+export function existingCli(pkg: { scripts?: Record<string, string>; bin?: unknown } | null, files: { entry: boolean; cliDir: boolean }): string | null {
+    if (pkg?.scripts?.cli != null) return `package.json scripts.cli runs \`${pkg.scripts.cli}\``
+    if (pkg?.bin != null) return `package.json has a bin (${typeof pkg.bin === 'string' ? pkg.bin : Object.keys(pkg.bin as object).join(', ')})`
+    // a script running an installed tool's cli (the house `hub` runs shipkit's) is not the repo's own
+    const runner = Object.entries(pkg?.scripts ?? {}).find(([, body]) => body.split(/\s+/).some((w) => /\bcli\.(ts|js)$/.test(w) && !/node_modules\/|rvlib-shipkit/.test(w)))
+    if (runner != null) return `package.json scripts.${runner[0]} runs \`${runner[1]}\``
+    if (files.entry) return 'src/cli.ts exists'
+    if (files.cliDir) return 'src/cli/ exists'
+    return null
+}
+
+/** whether an installed rvlib-shipkit carries the kit: null = none installed */
+export function kitInstalled(installedPkg: { exports?: Record<string, unknown> } | null): boolean | null {
+    if (installedPkg == null) return null
+    return installedPkg.exports?.['./cli-kit'] != null
+}
+
+/** the check file that keeps both agent pages equal to the registry: the gate
+ *  fails a stale page and its fix pass writes it again */
+export function pagesCheckFile(name: string): string {
+    return `// agent/${name}.md and agent/${name}-essentials.md list the ${name} commands as the registry has them.
+// A stale page sends an agent at a command that does not exist; the gate's fix pass writes both again
+import { check } from 'rvlib-shipkit/src/check.ts'
+import { cliPagesCheck } from 'rvlib-shipkit/src/cli/kit/pages-check.ts'
+
+const pages = cliPagesCheck('${name}')
+
+export default check({
+    description: pages.description,
+    blocking: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'files', inputs: pages.inputs, key: null },
+    fix: 'ci',
+    applies: 'always',
+    run: pages.run,
+    repair: pages.repair,
+})
+`
+}

package/src/scaffold/files/agent-index.md

@@ -12,14 +12,14 @@ BEFORE the change it describes.
 
 **Always loaded every session:**
 
-@coding.md
+@coding.md{{CLI_INCLUDE}}
 
 Read the matching page before touching a surface:
 
 | read when touching… | page |
 |---|---|
 | any source file | `agent/coding.md` |
-| recent changes and why | `agent/changelog.md` |
+| recent changes and why | `agent/changelog.md` |{{CLI_ROW}}
 
 Grow this table: a subsystem, a service, a runbook each earn their own page,
 cross-linked from here.

package/src/scaffold/files/tsconfig.json

@@ -23,6 +23,9 @@
          "scripts/*": ["./scripts/*"]
       },
 
+      // no @types package loads unless named here: bun's globals (Bun, import.meta.dir)
+      "types": ["bun"],
+
       // every file is a module even with no import/export (standalone scripts)
       "moduleDetection": "force",
 

package/src/scaffold/files/verify-skill.md

@@ -12,7 +12,7 @@ description: Prove a change in THIS project actually works — drive the real fl
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
 - Logic → fast headless bun tests, run through `sk ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
-- Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
+- Look & feel → your own screenshot is a check before you report, never the verdict; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 
 ## This project