rvlib-shipkit 2.1.1 → 2.3.0

package/src/collections/review.ts

@@ -0,0 +1,70 @@
+// the review store and the trailer cuts as tree rows (wiki build/shipkit/review.md). Under the review section, one row a
+// card that waits on HIM (the owner's verdict, his answer to a question): yellow, so `sk needs` lists it too. Under the trailer
+// section, one row a cut, its open frame notes in the slot: they wait on agents, never on him, so a cut is never yellow.
+// Each collection exists only where the repo has its folder, so a repo with none draws the section greyed
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { STATUS_LABEL, isFrame, stateOf } from '../review/model.ts'
+import { readAllCached, storeDir } from '../review/store.ts'
+import { statusOf, waitingOnOwner } from '../review/threads.ts'
+import { cutsOf, trailerIds } from '../review/trailer-desk.ts'
+import { REVIEW_COL, TRAILER_COL, type Collection, type Instance } from './collection-types.ts'
+
+export function reviewCollection(root: string): Collection | null {
+    const dir = storeDir(root)
+    if (!existsSync(dir)) return null
+    return {
+        id: REVIEW_COL,
+        title: 'review',
+        kind: 'card',
+        media: 'image',
+        list: async () => {
+            const { items } = readAllCached(dir)
+            return waitingOnOwner(items).map(({ head: x }): Instance => ({
+                id: `card:${x.item.id}`,
+                text: `${x.item.title} (${STATUS_LABEL[statusOf(x, items)]})`,
+                label: x.item.title,
+                slot: x.item.origin.by === 'agent' ? (x.item.origin.lane ?? 'card') : 'question',
+                type: 'card',
+                path: `.shipkit/review/${x.item.id}`,
+                severity: 'yellow',
+                verbs: ['approve'],
+            }))
+        },
+    }
+}
+
+export function trailersCollection(root: string): Collection | null {
+    const ids = trailerIds(root)
+    if (ids.length === 0) return null
+    return {
+        id: TRAILER_COL,
+        title: 'trailer',
+        kind: 'cut',
+        media: 'image',
+        list: async () => {
+            const dir = storeDir(root)
+            const items = existsSync(dir) ? readAllCached(dir).items : []
+            const open = new Map<string, number>()
+            for (const x of items) {
+                const s = x.item.subject
+                if (isFrame(s) && stateOf(x, false).state !== 'closed') open.set(`${s.trailer}/${s.cut}`, (open.get(`${s.trailer}/${s.cut}`) ?? 0) + 1)
+            }
+            return ids.flatMap((id) =>
+                cutsOf(join(root, 'trailer', id)).map((c): Instance => {
+                    const n = open.get(`${id}/${c.cut}`) ?? 0
+                    const rendered = existsSync(join(root, 'trailer', id, 'out', `${c.name}.mp4`))
+                    return {
+                        id: `cut:${id}/${c.cut}`,
+                        text: `${id} ${c.cut}${rendered ? '' : ' (not rendered)'}${n > 0 ? `, ${n} open note${n > 1 ? 's' : ''}` : ''}`,
+                        label: ids.length > 1 ? `${id} · ${c.cut}` : c.cut,
+                        slot: n > 0 ? `${n} open` : rendered ? '' : 'no render',
+                        type: 'cut',
+                        path: c.trailer === null ? `trailer/${id}/out/${c.name}.mp4` : `trailer/${id}/${c.cut}.trailer`,
+                        state: rendered ? 'idle' : 'quiet',
+                    }
+                }),
+            )
+        },
+    }
+}

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,12 @@ 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
+    // the one feedback store: review cards and frame notes, one folder an item (review/store.ts)
+    review: sk('review'),
+    // 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 +51,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/reflect/prompt-corpus.ts

@@ -2,13 +2,12 @@
 // 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.
+// What counts as typed is the shared transcript reader's call (transcript.ts):
+// this module finds the files, dedupes and renders.
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { basename, join, resolve } from 'path'
+import { isTypedPrompt, readTranscriptLine } from './transcript.ts'
 
 export type PromptEntry = {
     uuid: string
@@ -56,121 +55,23 @@ export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
 /** 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 }
-}
-
-/** the typed prompt out of one transcript line, or null when the line is not one
- * 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 */
-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 { isTypedPrompt } from './transcript.ts'
 
 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',
-        })
+        for (const ev of readTranscriptLine(line)) {
+            if (ev.kind !== 'prompt') continue
+            out.push({
+                uuid: ev.uuid ?? `${ev.origin === 'typed' ? 'typed' : 'queue'}:${ctx.sessionId}:${ev.timestamp}`,
+                timestamp: ev.timestamp,
+                sessionId: ev.sessionId ?? ctx.sessionId,
+                account: ctx.account,
+                text: ev.text,
+                origin: ev.origin,
+            })
+        }
     }
     return out
 }