rvlib-shipkit 2.2.0 → 2.3.0

package/src/cli/cmd_Time.ts

@@ -0,0 +1,112 @@
+// `sk time`: where the agents' time went in a repo, read from every Claude
+// Code transcript on the machine (every config root, sub-agents included)
+// through the agent time index (agent-time/store.ts). REPORT ONLY: exit 0 with
+// a report, 1 when nothing matched, 2 on a bad flag.
+import { Command, Option } from 'clipanion'
+import { resolve } from 'path'
+
+const BIG_BYTES = 50 * 1024 * 1024
+
+export class TimeCommand extends Command {
+    static override paths = [['time']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'where agent time went in a repo, every account: waits, slow and failing commands, feedback',
+        details: [
+            'Reads every Claude Code transcript under every config root (~/.claude, ~/.claude-<name>), sub-agent runs included, through an index at ~/.shipkit/agent-time.sqlite.',
+            'The first run builds the index (niced, resumable, progress on stderr); later runs read only what changed. The index keeps sessions Claude Code has pruned.',
+            'Views: summary (default), commands, tools, slow, fails, feedback, sessions, turns. A Bash command is grouped by its shape (`git commit`, `bun test <file>`, `sk ci --only lint`).',
+            'Turns: every call costs a model turn before it, so the summary gives the model time before each call, the share of single read calls and the share sent in parallel, for the main sessions and the sub-agents; `turns` lists the runs and the read shapes by the model time they cost.',
+            'Wall time is cut once per moment: tools in flight, a sub-agent in flight, waiting on a background task, waiting on you (an idle gap past 30 minutes is left out), else the model.',
+            'Commands and prompts are masked through the leak guard keyword list and token shapes before they print.',
+        ].join(' '),
+        examples: [
+            ['this repo, the last 7 days', 'sk time'],
+            ['every command shape, 30 days', 'sk time commands --since 30d'],
+            ['what he said while it ran', 'sk time feedback --since all'],
+            ['the runs by their turns, and what the reads cost', 'sk time turns --since 30d'],
+            ['two repos, every recorded session', 'sk time ~/dev/pkm-multi ~/dev/procedural-creatures --since all'],
+            ['every repo on the machine', 'sk time --all'],
+            ['for a script', 'sk time --json'],
+        ],
+    })
+
+    args = Option.Rest()
+    all = Option.Boolean('--all', false, { description: 'every repo with transcripts on this machine' })
+    since = Option.String('--since', '7d', { description: '30m, 2h, 7d, a date, or all' })
+    top = Option.String('--top', '20', { description: 'rows per list in a sub view' })
+    json = Option.Boolean('--json', false, { description: 'the whole report as json' })
+
+    async execute(): Promise<number> {
+        const { VIEWS, render } = await import('../agent-time/render.ts')
+        const { sinceOf } = await import('./kit/calls.ts')
+        const err = this.context.stderr
+        const tty = (err as { isTTY?: boolean }).isTTY === true
+        const views = this.args.filter((a) => (VIEWS as readonly string[]).includes(a))
+        const repoArgs = this.args.filter((a) => !views.includes(a))
+        const bad = repoArgs.find((a) => !a.includes('/') && !a.startsWith('.') && !a.startsWith('~'))
+        if (views.length > 1 || bad != null) {
+            err.write(`FAIL: ${bad == null ? `one view at a time, not ${views.join(' and ')}` : `unknown view '${bad}'`}: ${VIEWS.join(', ')}, or a repo path\n`)
+            return 2
+        }
+        const view = (views[0] ?? 'summary') as (typeof VIEWS)[number]
+        const now = Date.now()
+        const from = this.since === 'all' ? null : sinceOf(this.since, now)
+        if (from === null && this.since !== 'all') {
+            err.write(`FAIL: --since ${this.since}: 30m, 2h, 7d, a date, or all\n`)
+            return 2
+        }
+        const top = Number(this.top)
+        if (!Number.isInteger(top) || top <= 0) {
+            err.write(`FAIL: --top ${this.top}: a positive whole number\n`)
+            return 2
+        }
+
+        const { indexTranscripts, listTranscripts, loadWindow, markGone, openIndex, repoOfProject, agentTimeDbPath } = await import('../agent-time/store.ts')
+        const { discoverConfigRoots, projectSlug } = await import('../reflect/prompt-corpus.ts')
+        const { buildReport } = await import('../agent-time/report.ts')
+        const { loadMasker } = await import('../agent-time/mask.ts')
+
+        const repos = repoArgs.length > 0 ? repoArgs.map((r) => resolve(r)) : [process.cwd()]
+        const slugs = repos.map(projectSlug)
+        const keep = this.all ? () => true : (p: string) => slugs.some((s) => p === s || p.startsWith(`${s}--claude-worktrees-`))
+        const roots = discoverConfigRoots()
+        const db = openIndex()
+        try {
+            const files = listTranscripts(roots, keep)
+            const pending = files.length
+            const tIndex = performance.now()
+            let lastPrint = 0
+            let niced = false
+            const res = indexTranscripts(db, files, (p) => {
+                if (p.bytes < BIG_BYTES) return
+                if (!niced) {
+                    niced = true
+                    try { (require('os') as typeof import('os')).setPriority(0, 15) } catch { /* not allowed: index at the normal priority */ }
+                }
+                const t = performance.now()
+                if (t - lastPrint < (tty ? 200 : 10_000) && p.done < p.files) return
+                lastPrint = t
+                const line = `index: ${p.done}/${p.files} files, ${(p.doneBytes / 1e9).toFixed(1)}/${(p.bytes / 1e9).toFixed(1)} GB, ${Math.round((t - tIndex) / 1000)}s`
+                err.write(tty ? `\r${line}` : `${line}\n`)
+            })
+            if (res.bytes >= BIG_BYTES) err.write(`${tty ? '\n' : ''}index: read ${res.read} of ${pending} files, ${(res.bytes / 1e9).toFixed(2)} GB in ${(res.ms / 1000).toFixed(1)}s (${agentTimeDbPath()})\n`)
+            markGone(db, files, keep)
+            const loaded = loadWindow(db, keep, from ?? 0, now)
+            const labels = this.all ? [...new Set(loaded.files.map((f) => repoOfProject(f.project)))].sort() : slugs.map((s) => repoOfProject(s))
+            if (loaded.files.length === 0) {
+                err.write(`FAIL: no agent session in ${labels.join(', ') || 'any repo'} ${from == null ? 'ever' : `since ${new Date(from).toISOString().slice(0, 10)}`}\n`)
+                err.write(`      looked under: ${roots.map((r) => r.projects).join(' · ')}\n`)
+                err.write(`      fix: widen it, --since all, or name a repo that ran Claude Code sessions\n`)
+                return 1
+            }
+            const report = buildReport(loaded, { repos: labels, from, to: now, repoOf: (p) => repoOfProject(p) }, loadMasker(repos[0] ?? null))
+            if (this.json) this.context.stdout.write(`${JSON.stringify(report)}\n`)
+            else this.context.stdout.write(render(report, view, top))
+            return 0
+        } finally {
+            db.close()
+        }
+    }
+}

package/src/cli/cmd_Trailer.ts

@@ -2,7 +2,7 @@
 // Every module loads inside execute: the cli registers this file on every `sk` call
 import { Command, Option } from 'clipanion'
 
-const DETAILS = `the trailer language: shots with a film line each (clip <file>, image <file>, card, run "<cmd {out}>", url <route> through the shot service, or a film row of the project CLI), titles in the brand's look, cuts, sections in bars, music, sfx and voice; a \`vertical\` header finishes a short with the brand's lockup, watermark and end card. Outputs land in trailer/<trailer>/out/. Page: wiki build/trailer.md`
+const DETAILS = `the trailer language: shots with a film line each (clip <file>, image <file>, card, run "<cmd {out}>", url <route> through the shot service, grid and split of other takes, or a film row of the project CLI), footage blocks, titles in the brand's look, cuts, sections in bars, music, sfx and voice; a \`vertical\` header finishes a short with the brand's lockup, watermark and end card. A repo plugs in one trailer({...}) unit: sounds by id, the world's paths, content checks, a line's own take. Outputs land in trailer/<trailer>/out/. Page: wiki build/trailer.md`
 
 /** --refilm alone: every stale take; --refilm a,b: those shots */
 const refilmOf = (v: string | boolean | undefined): 'stale' | ReadonlySet<string> | null => (v === undefined || v === false ? null : v === true ? 'stale' : new Set(v.split(',')))
@@ -42,7 +42,7 @@ export class TrailerCommand extends Command {
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
             if (!b.sayErrors(l, say, cwd)) return 1
             await b.build(l, { refilm: refilmOf(this.refilm), final: this.final, say, cwd })
             return 0
@@ -69,16 +69,41 @@ export class TrailerCheckCommand extends Command {
         return run(this.context, async (say, root, cwd) => {
             const t0 = performance.now()
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
             if (!b.sayErrors(l, say, cwd)) return 1
-            const { takesOf, worldStamp } = await import('../trailer/footage.ts')
-            for (const line of b.timeline(l, takesOf(l.t, root), worldStamp(root), cwd)) say(line)
+            for (const line of b.timeline(l, b.takesOfLoaded(l), await b.worldOf(l), cwd)) say(line)
             say(`ok: checked in ${((performance.now() - t0) / 1000).toFixed(2)} s`)
             return 0
         })
     }
 }
 
+export class TrailerScoreCommand extends Command {
+    static override paths = [['trailer', 'score']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'the score alone, no picture: its wav, its waveform png, each section\'s level and the loudness',
+        details: `${DETAILS}. The score renders offline in Bun from the file's score, track, drums, code, section and play lines; a section whose notes are silent fails`,
+        examples: [
+            ['the score of the one cut', 'sk trailer score'],
+            ['the score of a named cut', 'sk trailer score trailer/launch'],
+        ],
+    })
+
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            await b.auditionScore(l, { refilm: null, final: false, say, cwd })
+            return 0
+        })
+    }
+}
+
 export class TrailerShotCommand extends Command {
     static override paths = [['trailer', 'shot']]
 
@@ -99,10 +124,238 @@ export class TrailerShotCommand extends Command {
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
             if (!b.sayErrors(l, say, cwd)) return 1
             await b.previewShot(l, this.name, { refilm: refilmOf(this.refilm), final: false, say, cwd })
             return 0
         })
     }
 }
+
+/** a cut loaded and checked, its errors said; null when it has one */
+async function loaded(file: string | undefined, say: (l: string) => void, root: string, cwd: string) {
+    const b = await import('../trailer/build.ts')
+    const l = await b.load(b.trailerFile(file, root, cwd), root)
+    return b.sayErrors(l, say, cwd) ? l : null
+}
+
+export class TrailerSectionCommand extends Command {
+    static override paths = [['trailer', 'section']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'one section alone with its window of the sound: out/<cut>-<section>.mp4',
+        details: `${DETAILS}. \`start\` is the shots before the first section; only a section the cache misses renders`,
+        examples: [['a section of the one cut', 'sk trailer section drop']],
+    })
+
+    name = Option.String({ required: true })
+    file = Option.String({ required: false })
+    final = Option.Boolean('--final', false, { description: 'encode with x264 for a release' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            await (await import('../trailer/build.ts')).previewSection(l, this.name, { refilm: null, final: this.final, say, cwd })
+            return 0
+        })
+    }
+}
+
+export class TrailerLevelsCommand extends Command {
+    static override paths = [['trailer', 'levels']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'each section\'s mean and peak in the built mp4, and its step from the section before',
+        details: DETAILS,
+        examples: [['the levels of the one cut', 'sk trailer levels']],
+    })
+
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            await (await import('../trailer/passage.ts')).levels(l, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerClipCommand extends Command {
+    static override paths = [['trailer', 'clip']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'a passage of the built cut with its sound, from a section, mark, shot or second',
+        details: `${DETAILS}. --version cuts the same passage of a kept version beside it, read from versions/<v>.trailer`,
+        examples: [
+            ['a section', 'sk trailer clip drop'],
+            ['from a shot to a mark, before and after', 'sk trailer clip hero hit --version v3'],
+        ],
+    })
+
+    from = Option.String({ required: true })
+    rest = Option.Rest({ required: 0 })
+    version = Option.String('--version', { description: 'a kept version (v<n>): the same passage of it beside' })
+    pad = Option.String('--pad', { description: 'seconds of room before and after' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const { existsSync } = await import('node:fs')
+            const { resolve } = await import('node:path')
+            // the second word is a moment unless it names a file or a folder
+            const [a, b] = this.rest
+            const isPath = (w: string | undefined): boolean => w !== undefined && (w.endsWith('.trailer') || existsSync(resolve(cwd, w)))
+            const to = a !== undefined && !isPath(a) ? a : this.from
+            const file = a !== undefined && !isPath(a) ? b : a
+            const l = await loaded(file, say, root, cwd)
+            if (!l) return 1
+            const pad = Number(this.pad ?? 0)
+            if (!Number.isFinite(pad) || pad < 0) throw new Error(`--pad wants seconds, got ${this.pad}`)
+            await (await import('../trailer/passage.ts')).clip(l, this.from, to, pad, this.version, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerKeepCommand extends Command {
+    static override paths = [['trailer', 'keep']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'keep the built cut as a version: versions/v<n>.trailer, its video, strip and takes',
+        details: `${DETAILS}. Refuses a version already kept; prints the index row, commit and tag left to do`,
+        examples: [['keep the one cut', 'sk trailer keep v4']],
+    })
+
+    version = Option.String({ required: true })
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            ;(await import('../trailer/passage.ts')).keep(l, this.version, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerFootageCommand extends Command {
+    static override paths = [['trailer', 'footage']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'the take file of each shot or footage block, the raw take before the stitch trims it',
+        details: DETAILS,
+        examples: [['two shots of the one cut', 'sk trailer footage intro,hero']],
+    })
+
+    names = Option.String({ required: true })
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            ;(await import('../trailer/passage.ts')).footage(l, this.names.split(','), say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerWatchCommand extends Command {
+    static override paths = [['trailer', 'watch']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'build again after each save in the cut\'s folder (ctrl-c stops)',
+        details: DETAILS,
+        examples: [['the one cut', 'sk trailer watch']],
+    })
+
+    file = Option.String({ required: false })
+    final = Option.Boolean('--final', false, { description: 'encode with x264 for a release' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const { watch } = await import('node:fs')
+            const { dirname, relative } = await import('node:path')
+            const file = b.trailerFile(this.file, root, cwd)
+            let busy = false
+            let again = false
+            const once = async (): Promise<void> => {
+                if (busy) {
+                    again = true
+                    return
+                }
+                busy = true
+                try {
+                    const l = await b.load(file, root, { fresh: true })
+                    if (b.sayErrors(l, say, cwd)) await b.build(l, { refilm: null, final: this.final, say, cwd })
+                } catch (e) {
+                    say(`FAIL: ${e instanceof Error ? e.message : String(e)}`)
+                }
+                busy = false
+                if (again) {
+                    again = false
+                    await once()
+                }
+            }
+            await once()
+            say(`watching ${relative(cwd, file)} and its folder's recipes (ctrl-c stops)`)
+            let timer: ReturnType<typeof setTimeout> | null = null
+            watch(dirname(file), (_, f) => {
+                if (!f || f.startsWith('out') || f.startsWith('versions') || f.endsWith('.md')) return
+                if (timer) clearTimeout(timer)
+                timer = setTimeout(() => void once(), 200)
+            })
+            await new Promise(() => undefined)
+            return 0
+        })
+    }
+}
+
+export class TrailerPruneCommand extends Command {
+    static override paths = [['trailer', 'prune']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'trim the trailer cache to what the cuts use, what each folder frees',
+        details: `${DETAILS}. Every build, section and shot runs it after its stitch; a file younger than an hour stays`,
+        examples: [
+            ['what it would free', 'sk trailer prune --dry'],
+            ['free it', 'sk trailer prune'],
+        ],
+    })
+
+    dry = Option.Boolean('--dry', false, { description: 'say what each folder would free, delete nothing' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root) => {
+            const { prune, sayPruned } = await import('../trailer/prune.ts')
+            for (const line of sayPruned(await prune(root, { dry: this.dry }), this.dry)) say(line)
+            return 0
+        })
+    }
+}
+
+/** every `sk trailer` verb, registered by cli.ts */
+export const TRAILER_COMMANDS = [
+    TrailerCommand,
+    TrailerCheckCommand,
+    TrailerScoreCommand,
+    TrailerShotCommand,
+    TrailerSectionCommand,
+    TrailerLevelsCommand,
+    TrailerClipCommand,
+    TrailerKeepCommand,
+    TrailerFootageCommand,
+    TrailerWatchCommand,
+    TrailerPruneCommand,
+]

package/src/cli/kit/verb.ts

@@ -61,6 +61,10 @@ export type Verb = {
     essential?: Essential
     /** filmable: takes `--out <path>`, a clip also `--seconds <n>` (a trailer `film` line calls it) */
     film?: Film
+    /** with film: the row's take version, a bump films every trailer take of the row again */
+    version?: number | string
+    /** with film: `own`, a clip that films as long as it plays (no `--seconds`) */
+    length?: 'own'
 }
 
 /** the argv a row runs */
@@ -120,6 +124,8 @@ export function verbs(rows: Verb[]): CommandClass[] {
             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
+            static filmVersion = v.version
+            static filmLength = v.length
             args = Option.Proxy()
             async execute(): Promise<number> {
                 const { root, cwd } = this.context
@@ -148,10 +154,14 @@ export function verbs(rows: Verb[]): CommandClass[] {
 
 /** 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 } = {}
+export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } {
+    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown }
+    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } = {}
     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
+    if (o.film === 'still' || o.film === 'clip') {
+        out.film = o.film
+        if (typeof o.filmVersion === 'number' || typeof o.filmVersion === 'string') out.version = o.filmVersion
+        if (o.filmLength === 'own') out.length = 'own'
+    }
     return out
 }

package/src/cli.ts

@@ -8,6 +8,7 @@ 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 { TimeCommand } from './cli/cmd_Time.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
@@ -39,7 +40,8 @@ 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 { TRAILER_COMMANDS } from './cli/cmd_Trailer.ts'
+import { REVIEW_COMMANDS } from './cli/cmd_Review.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -70,9 +72,8 @@ export function buildCli(): Cli {
     cli.register(MvCommand)
     cli.register(CheckCommand)
     cli.register(TuiCommand)
-    cli.register(TrailerCommand)
-    cli.register(TrailerCheckCommand)
-    cli.register(TrailerShotCommand)
+    for (const c of TRAILER_COMMANDS) cli.register(c)
+    for (const c of REVIEW_COMMANDS) cli.register(c)
     cli.register(ServeCommand)
     cli.register(PmCommand)
     cli.register(DaemonCommand)
@@ -117,6 +118,7 @@ export function buildCli(): Cli {
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(CallsCommand)
+    cli.register(TimeCommand)
     cli.register(ConfigKeysCommand)
 
     return cli

package/src/collections/collection-types.ts

@@ -31,7 +31,12 @@ export const NO_CHECK = 'in no check'
  *  section a row lives under (hub-app/tree-build.ts KIND_SECTION). There is no
  *  catch all kind: a row belongs to an owner, and what belongs to the hub
  *  itself is its status (serve/hub-problems.ts), never a row */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process', 'card', 'cut'] as const
+
+/** the collection of the review cards that wait on him (collections/review.ts) */
+export const REVIEW_COL = 'review'
+/** the collection of the trailer cuts, one row a cut (collections/review.ts) */
+export const TRAILER_COL = 'trailers'
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 

package/src/collections/providers.ts

@@ -27,6 +27,7 @@ import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
 import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
 import { reflectionsCollection } from './reflections.ts'
+import { reviewCollection, trailersCollection } from './review.ts'
 import { testsCollection } from './tests.ts'
 import { checksCollection } from './checks.ts'
 import { LAYOUT } from '../core/layout.ts'
@@ -417,5 +418,7 @@ export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit |
         socialPostsCollection(root),
         reflectionsCollection(root),
         testsCollection(root, c),
+        // only where the repo has a review store or a trailer folder: the section of a repo with none is greyed
+        ...[reviewCollection(root), trailersCollection(root)].filter((x): x is Collection => x !== null),
     ]
 }

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

@@ -36,6 +36,8 @@ export const LAYOUT = {
     discord: sk('discord'),
     // a review with no output file named by its caller (YYYYMMDD-HHMMSS-<name>.md)
     reviews: sk('reviews'),
+    // 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