rvlib-shipkit 1.4.0 → 1.6.0

package/src/cli/cmd_Keys.ts

@@ -19,14 +19,15 @@ export class KeysCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'the cache key of every gate check, and the reason the undeclared ones have none. Reports, never gates',
+        description: 'the cache key of every gate check, and why the others have none',
+        details: 'the cache key of every gate check, and the reason the undeclared ones have none. Reports, never gates',
         examples: [
-            ['every check and its key', 'shipkit keys'],
-            ['only the ones nothing can cache yet', 'shipkit keys --burn-down'],
-            ['why this key is what it is', 'shipkit keys --why typecheck'],
-            ['re-hash after the fact and report drift', 'shipkit keys --rescan'],
-            ['the keys a --full gate asks for', 'shipkit keys --full'],
-            ['machine-readable', 'shipkit keys --json'],
+            ['every check and its key', 'sk keys'],
+            ['only the ones nothing can cache yet', 'sk keys --burn-down'],
+            ['why this key is what it is', 'sk keys --why typecheck'],
+            ['re-hash after the fact and report drift', 'sk keys --rescan'],
+            ['the keys a --full gate asks for', 'sk keys --full'],
+            ['machine-readable', 'sk keys --json'],
         ],
     })
 
@@ -74,6 +75,14 @@ export class KeysCommand extends Command {
                 return 0
             }
             out(`      key ${k.key}`)
+            // a lib hash names nothing by itself: the files behind it are what
+            // an edit has to touch to move this key
+            const lib = k.libFiles ?? []
+            if (lib.length > 0) {
+                out(`      toolkit files in its lib components: ${lib.length}`)
+                for (const f of lib.slice(0, 12)) out(`        ${f}`)
+                if (lib.length > 12) out(`        … ${lib.length - 12} more (shipkit keys --json)`)
+            }
             if (k.population === 'reads') {
                 for (const comp of k.components) out(`      ${comp}`)
                 // the rest of its identity is what it READ, stored with the
@@ -88,12 +97,15 @@ export class KeysCommand extends Command {
                 const lists = Object.entries(set.lists)
                 const dirs = Object.entries(set.dirs ?? {})
                 const links = Object.entries(set.links ?? {})
-                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}`)
+                // outside the repo a traced read is keyed on stat alone
+                const outside = Object.keys(set.sigs ?? {}).filter((p) => !(p in set.files))
+                out(`      read set: ${files.length} file(s), ${exists.length} existence probe(s), ${lists.length} listing(s), ${dirs.length} dir read(s)${links.length > 0 ? `, ${links.length} link probe(s)` : ''}${outside.length > 0 ? `, ${outside.length} file(s) outside the repo, by stat` : ''}`)
                 for (const [p, oid] of files) out(`        read ${p}=${oid ?? 'absent'}`)
                 for (const [p, kind] of exists) out(`        exists ${p}=${kind ?? 'absent'}`)
                 for (const [g, h] of lists) out(`        list ${g}=${h}`)
                 for (const [d, h] of dirs) out(`        entries ${d}=${h ?? 'absent'}`)
                 for (const [p, is] of links) out(`        link ${p}=${is ? 'yes' : 'no'}`)
+                for (const p of outside) out(`        stat ${p}=${set.sigs![p]}`)
                 return 0
             }
             // the excluded block is 44 lines here and it buries the component

package/src/cli/cmd_Mv.ts

@@ -12,13 +12,14 @@ export class MvCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Refactor',
-        description: 'rename anything and sweep every reference: an md page (plus its sibling dir and its check file) or a code file or folder. Dry run by default. Renames must be CHEAP',
+        description: 'rename a file, folder or md page and rewrite every reference (dry run by default)',
+        details: 'rename anything and sweep every reference: an md page (plus its sibling dir and its check file) or a code file or folder. Dry run by default. Renames must be CHEAP',
         examples: [
-            ['dry run, the default, shows what changes', 'shipkit mv docs/old-name.md docs/new-name.md'],
-            ['apply it', 'shipkit mv docs/old-name.md docs/new-name.md --write'],
-            ['apply + one conventional commit', 'shipkit mv docs/old-name.md docs/new-name.md --commit'],
-            ['a code file, every import rewritten', 'shipkit mv src/old-mod.ts src/new-mod.ts --write'],
-            ['a whole folder', 'shipkit mv src/old-dir src/new-dir --write'],
+            ['dry run, the default, shows what changes', 'sk mv docs/old-name.md docs/new-name.md'],
+            ['apply it', 'sk mv docs/old-name.md docs/new-name.md --write'],
+            ['apply + one conventional commit', 'sk mv docs/old-name.md docs/new-name.md --commit'],
+            ['a code file, every import rewritten', 'sk mv src/old-mod.ts src/new-mod.ts --write'],
+            ['a whole folder', 'sk mv src/old-dir src/new-dir --write'],
         ],
     })
 

package/src/cli/cmd_Needs.ts

@@ -12,10 +12,11 @@ export class NeedsCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'everything blocked on a human, red/yellow by collection — report-only, exit 0 always (check/ci are the gates)',
+        description: 'everything blocked on a human, by collection. Report only',
+        details: 'everything blocked on a human, red/yellow by collection — report-only, exit 0 always (check/ci are the gates)',
         examples: [
-            ['what needs me', 'shipkit needs'],
-            ['machine-readable (agents, drills, cross-repo rollups)', 'shipkit needs --json'],
+            ['what needs me', 'sk needs'],
+            ['machine-readable (agents, drills, cross-repo rollups)', 'sk needs --json'],
         ],
     })
 

package/src/cli/cmd_Overview.ts

@@ -77,17 +77,18 @@ export class OverviewCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Home',
-        description: 'the overview page in the console: every monitor widget as text, from the html the daemon last rendered, then the processes as `shipkit gp` prints them (pm, the daemon and the web with pid, uptime and version, then every global process). When pm or the daemon does not answer, it says which and prints what is still known. Always exits 0',
+        description: 'the overview page as text: the widgets, then every process',
+        details: 'the overview page in the console: every monitor widget as text, from the html the daemon last rendered, then the processes as `shipkit gp` prints them (pm, the daemon and the web with pid, uptime and version, then every global process). When pm or the daemon does not answer, it says which and prints what is still known. Always exits 0',
         examples: [
-            ['the overview', 'shipkit overview'],
-            ['the answers the page reads, as json', 'shipkit overview --json'],
+            ['the overview', 'sk overview'],
+            ['the answers the page reads, as json', 'sk overview --json'],
         ],
     })
 
     json = Option.Boolean('--json', false, { description: 'the answers as json: { now, pm, daemon, processes, widgets }, processes as `shipkit gp --json`, widgets the daemon route\'s payload' })
 
     async execute(): Promise<number> {
-        const a = await overviewAnswer({ ...localProcessDeps(process.cwd()), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
+        const a = await overviewAnswer({ ...(await localProcessDeps(process.cwd())), pm: () => askPm(), daemon: () => askDaemon(), widgets: () => askWidgets(), now: Date.now() })
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
             return 0

package/src/cli/cmd_Pb.ts

@@ -10,8 +10,8 @@ export class PbCollectionCommand extends Command {
         category: 'Scaffold',
         description: "a collection's CRUD UI folder from the app's generated pb types: columns, card, grid, form, index",
         examples: [
-            ['see the whole folder before it exists', 'shipkit pb collection orders --dry-run'],
-            ['write src/collections/orders/', 'shipkit pb collection orders'],
+            ['see the whole folder before it exists', 'sk pb collection orders --dry-run'],
+            ['write src/collections/orders/', 'sk pb collection orders'],
         ],
     })
 

package/src/cli/cmd_Planned.ts

@@ -78,12 +78,13 @@ export class PlannedCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Home',
-        description: 'the planned page in the console: every check the machine runs on its own time, running now, then next, each with its repo, check and title, when, the rule that planned it and its last result. Asks the daemon, which holds the plan. With the daemon down it says so and exits 0',
+        description: 'the plan as text: every check the machine runs on its own time',
+        details: 'the planned page in the console: every check the machine runs on its own time, running now, then next, each with its repo, check and title, when, the rule that planned it and its last result. Asks the daemon, which holds the plan. With the daemon down it says so and exits 0',
         examples: [
-            ['the plan, as the page lists it', 'shipkit planned'],
-            ['one repo only', 'shipkit planned --repo my-app'],
-            ['also the checks that only a save runs', 'shipkit planned --all'],
-            ['the route\'s exact payload', 'shipkit planned --json'],
+            ['the plan, as the page lists it', 'sk planned'],
+            ['one repo only', 'sk planned --repo my-app'],
+            ['also the checks that only a save runs', 'sk planned --all'],
+            ['the route\'s exact payload', 'sk planned --json'],
         ],
     })
 

package/src/cli/cmd_Prose.ts

@@ -13,11 +13,11 @@ export class ProseCommand extends Command {
         category: 'Health',
         description: 'STE prose check (identity/writing-voice.md): mechanical fixes, hard violations, soft warnings',
         examples: [
-            ['every file this repo declares as prose', 'shipkit prose'],
-            ['one file while drafting', 'shipkit prose wiki/build/shipkit.md'],
-            ['apply every mechanical rewrite', 'shipkit prose --fix'],
-            ['the procedural 20-word limit', 'shipkit prose --strict'],
-            ['machine-readable', 'shipkit prose --json'],
+            ['every file this repo declares as prose', 'sk prose'],
+            ['one file while drafting', 'sk prose wiki/build/shipkit.md'],
+            ['apply every mechanical rewrite', 'sk prose --fix'],
+            ['the procedural 20-word limit', 'sk prose --strict'],
+            ['machine-readable', 'sk prose --json'],
         ],
     })
 

package/src/cli/cmd_Reflect.ts

@@ -17,14 +17,14 @@ export class ReflectCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description:
-            "the user's typed prompts across every Claude Code session of a repo — chronological md corpus for retrospectives",
+        description: "the user's prompts across every Claude Code session of a repo, as a corpus",
+        details: "the user's typed prompts across every Claude Code session of a repo — chronological md corpus for retrospectives",
         examples: [
-            ['corpus for the current repo', 'shipkit reflect'],
-            ['corpus for other repos', 'shipkit reflect ~/dev/one-repo ~/dev/another-repo'],
-            ['drop the long pastes', 'shipkit reflect --short'],
-            ['batch to files instead of stdout', 'shipkit reflect ~/dev/a ~/dev/b --out stats'],
-            ['machine-readable', 'shipkit reflect --json'],
+            ['corpus for the current repo', 'sk reflect'],
+            ['corpus for other repos', 'sk reflect ~/dev/one-repo ~/dev/another-repo'],
+            ['drop the long pastes', 'sk reflect --short'],
+            ['batch to files instead of stdout', 'sk reflect ~/dev/a ~/dev/b --out stats'],
+            ['machine-readable', 'sk reflect --json'],
         ],
     })
 

package/src/cli/cmd_Release.ts

@@ -9,12 +9,13 @@ export class ReleaseCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'cut a release for ONE unit (default the repo root): ci gate → npm publish (non-private only) → git tag → push → GitHub release, notes from that unit CHANGELOG section. Resumable after a partial failure, which is why it takes no --all.',
+        description: 'cut a release of one unit: gate, npm publish, tag, push, GitHub release',
+        details: 'cut a release for ONE unit (default the repo root): ci gate → npm publish (non-private only) → git tag → push → GitHub release, notes from that unit CHANGELOG section. Resumable after a partial failure, which is why it takes no --all.',
         examples: [
-            ['rehearse — touches nothing', 'shipkit release --dry-run'],
-            ['release the version in package.json', 'shipkit release'],
-            ['finish a sub-unit bump stopped part way (ids: shipkit releases)', 'shipkit release rvlib-shipkit'],
-            ['release with dirt elsewhere in the worktree', 'shipkit release --allow-dirty'],
+            ['rehearse — touches nothing', 'sk release --dry-run'],
+            ['release the version in package.json', 'sk release'],
+            ['finish a sub-unit bump stopped part way (ids: shipkit releases)', 'sk release rvlib-shipkit'],
+            ['release with dirt elsewhere in the worktree', 'sk release --allow-dirty'],
         ],
     })
 

package/src/cli/cmd_Releases.ts

@@ -9,11 +9,12 @@ export class ReleasesCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'every unit that releases and where it stands: version, npm, tag local and remote, GitHub release, drift. Reports, never gates (only an unresolvable config exits non-zero)',
+        description: 'every release unit and where it stands: version, npm, tags, GitHub',
+        details: 'every unit that releases and where it stands: version, npm, tag local and remote, GitHub release, drift. Reports, never gates (only an unresolvable config exits non-zero)',
         examples: [
-            ['what is published and what is not', 'shipkit releases'],
-            ['filesystem + local git only, no network', 'shipkit releases --offline'],
-            ['machine-readable', 'shipkit releases --json'],
+            ['what is published and what is not', 'sk releases'],
+            ['filesystem + local git only, no network', 'sk releases --offline'],
+            ['machine-readable', 'sk releases --json'],
         ],
     })
 

package/src/cli/cmd_Serve.ts

@@ -1,17 +1,17 @@
 // shipkit serve — the ONE hub server per repo (one vscode folder-open task,
 // clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
 import { Command, Option } from 'clipanion'
-import { runServe } from '../serve/run-serve.ts'
 
 export class ServeCommand extends Command {
     static override paths = [['serve']]
 
     static override usage = Command.Usage({
         category: 'Serve',
-        description: 'ONE server, ONE page: media studio + asks + creds + posts + health + wikis, each wiki a link graph page',
+        description: 'the repo hub: one server, one page (assets, asks, creds, posts, health, wikis)',
+        details: 'ONE server, ONE page: media studio + asks + creds + posts + health + wikis, each wiki a link graph page',
         examples: [
-            ['serve the repo toolbox', 'shipkit serve'],
-            ['pin the port for this launch', 'shipkit serve --port 4804'],
+            ['serve the repo toolbox', 'sk serve'],
+            ['pin the port for this launch', 'sk serve --port 4804'],
         ],
     })
 
@@ -26,6 +26,8 @@ export class ServeCommand extends Command {
                 return 1
             }
         }
+        // the hub runtime carries the image tools: loaded when it serves
+        const { runServe } = await import('../serve/run-serve.ts')
         return runServe(process.cwd(), {
             print: (l) => this.context.stdout.write(`${l}\n`),
             printErr: (l) => this.context.stderr.write(`${l}\n`),

package/src/cli/cmd_Smoke.ts

@@ -10,11 +10,12 @@ export class SmokeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'browser smoke pass over a deployed web app: login through the app, visit every declared route, read only, screenshots + console/network problems + host quota. Exit code = failed routes',
+        description: 'browser smoke pass over a deployed web app, every declared route',
+        details: 'browser smoke pass over a deployed web app: login through the app, visit every declared route, read only, screenshots + console/network problems + host quota. Exit code = failed routes',
         examples: [
-            ['every route in repo.config smoke, against its base url', 'shipkit smoke'],
-            ['a preview deploy', 'shipkit smoke --base https://abc123.my-app.pages.dev'],
-            ['two routes only', 'shipkit smoke --routes /orders,/clients'],
+            ['every route in repo.config smoke, against its base url', 'sk smoke'],
+            ['a preview deploy', 'sk smoke --base https://abc123.my-app.pages.dev'],
+            ['two routes only', 'sk smoke --routes /orders,/clients'],
         ],
     })
 

package/src/cli/cmd_Start.ts

@@ -9,13 +9,14 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create or enter ~/dev/<name> from anywhere, ready to work in',
+        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
-            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'shipkit start pong'],
-            ['another house: replace the include lines', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
-            ['adopt a pre-existing repo from anywhere', 'shipkit start my-old-project'],
-            ['force the private github repo for a folder that was already there', 'shipkit start old-notes --github'],
-            ['local git and the first commit, never touch github', 'shipkit start pong --no-github'],
+            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],
+            ['another house: replace the include lines', "sk start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
+            ['adopt a pre-existing repo from anywhere', 'sk start my-old-project'],
+            ['force the private github repo for a folder that was already there', 'sk start old-notes --github'],
+            ['local git and the first commit, never touch github', 'sk start pong --no-github'],
         ],
     })
 

package/src/cli/cmd_Status.ts

@@ -8,10 +8,11 @@ export class StatusCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: `a gate started with \`shipkit ci --detach\`: its wire lines so far, then its verdict. Exit code = the gate's own once it finished, ${STILL_RUNNING} while it still runs, 1 when it died without one`,
+        description: 'the output and verdict of a gate started with `sk ci --detach`',
+        details: `a gate started with \`shipkit ci --detach\`: its wire lines so far, then its verdict. Exit code = the gate's own once it finished, ${STILL_RUNNING} while it still runs, 1 when it died without one`,
         examples: [
-            ['the latest detached run of this checkout', 'shipkit status'],
-            ['one run by id', 'shipkit status ci-mf3k2a-1x2y'],
+            ['the latest detached run of this checkout', 'sk status'],
+            ['one run by id', 'sk status ci-mf3k2a-1x2y'],
         ],
     })
 

package/src/cli/cmd_TraceAudit.ts

@@ -0,0 +1,62 @@
+// sk trace-audit — which gitignored paths each gate task reads that its key
+// cannot see, found by running the task once under the tracer, and with
+// --fix written into repo.config.ts (core/trace-audit.ts).
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { applyAudit, traceAudit } from '../core/trace-audit.ts'
+import { describeByTask } from '../core/audit-report.ts'
+import { setTraceEnabled } from '../trace/tracer.ts'
+
+export class TraceAuditCommand extends Command {
+    static override paths = [['trace-audit']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'gitignored paths a gate task reads that its key misses, found by tracing it once',
+        details: 'Runs each gate task once under the tracer (on by default: --disable for this machine, or SHIPKIT_TRACE=0 for one run) and lists the gitignored paths it read that neither the tracked tree nor repo.config ignoredInputs covers. The answer is kept for about a day under the git common dir, where every worktree reads it, and each finding joins the key of the task that read it at once. --fix writes the findings into the managed block of repo.config.ts, per task, without tracing again. Exit 1 when a key misses something.',
+        examples: [
+            ['audit, reusing a recent answer', 'sk trace-audit'],
+            ['trace again now', 'sk trace-audit --fresh'],
+            ['write the proposals into repo.config.ts', 'sk trace-audit --fix'],
+            ['machine-readable', 'sk trace-audit --json'],
+            ['stop tracing on this machine', 'sk trace-audit --disable'],
+            ['trace again, the default', 'sk trace-audit --enable'],
+        ],
+    })
+
+    fresh = Option.Boolean('--fresh', false, { description: 'trace again even when a recent answer is kept' })
+    fix = Option.Boolean('--fix', false, { description: 'write the kept proposals into repo.config.ts ignoredInputs' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable report' })
+    enable = Option.Boolean('--enable', false, { description: 'turn tracing back on for this machine, the default: the daemon\'s health pass audits about daily (SK031)' })
+    disable = Option.Boolean('--disable', false, { description: 'stop tracing on this machine: nothing audits here until --enable' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const out = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+        if (this.enable || this.disable) {
+            setTraceEnabled(this.enable)
+            out(this.enable ? 'ok: tracing is on for this machine: the health pass audits each repo about daily (SK031)' : 'ok: tracing is off for this machine')
+            return 0
+        }
+        if (this.fix) {
+            let r: Awaited<ReturnType<typeof applyAudit>>
+            // a config the block writer refuses (a hand edit, a key declared
+            // outside the markers) is an answer for a human, never a crash
+            try { r = await applyAudit(root) } catch (e) { out(`FAIL: ${(e as Error).message}`); return 1 }
+            if (r.note != null) out(`skip: ${r.note}`)
+            else out(Object.keys(r.added).length === 0 ? 'ok: repo.config.ts ignoredInputs already covers every path the audit found' : `ok: repo.config.ts ignoredInputs gained ${describeByTask(r.added)}`)
+            return 0
+        }
+        const r = await traceAudit(root, await loadRepoConfig(root), { fresh: this.fresh })
+        const missing = r.tasks.filter((t) => t.uncovered.length > 0)
+        if (this.json) { out(JSON.stringify(r)); return missing.length > 0 ? 1 : 0 }
+        if (r.skipped != null) { out(`skip: nothing traced: ${r.skipped}`); return 0 }
+        for (const t of r.tasks) {
+            if (t.status === 'unaudited') out(`WARN ${t.id} could not be audited: ${t.why}`)
+            else if (t.uncovered.length > 0) out(`FAIL: ${t.id} reads ${t.uncovered.length} gitignored path(s) its key misses: ${t.uncovered.slice(0, 5).join(', ')}${t.uncovered.length > 5 ? ', …' : ''}`)
+            else out(`ok: ${t.id}: its key covers every gitignored path it read`)
+        }
+        if (missing.length > 0) out(`      fix: sk trace-audit --fix adds ${describeByTask(Object.fromEntries(missing.map((t) => [t.id, t.propose])))} to repo.config.ts ignoredInputs`)
+        return missing.length > 0 ? 1 : 0
+    }
+}

package/src/cli/cmd_Tui.ts

@@ -11,8 +11,9 @@ export class TuiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'live dashboard: the gate build steps + every other check, plus panels the repo injects via repo.config tui.panels',
-        examples: [['open the dashboard', 'shipkit tui']],
+        description: 'live dashboard: the gate steps, every other check, the repo\'s panels',
+        details: 'live dashboard: the gate build steps + every other check, plus panels the repo injects via repo.config tui.panels',
+        examples: [['open the dashboard', 'sk tui']],
     })
 
     async execute(): Promise<number> {

package/src/cli/cmd_When.ts

@@ -0,0 +1,71 @@
+// shipkit when — what runs when: the legend (every context, every value) and
+// one row per check with its declared value on each axis. The same data the
+// hub's when page draws (core/runs-matrix.ts), so the terminal and the page
+// cannot disagree.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { gateInventory } from '../ledger/gate-checks.ts'
+import { legendMarkdown, MATRIX_AXES, matrixLines, RUNS_LEGEND, runsCellsOf, type MatrixAxis } from '../core/runs-matrix.ts'
+import { spliceMarkedBlock } from '../core/doc-block.ts'
+
+export const LEGEND_BEGIN = '<!-- shipkit:when-legend -->'
+export const LEGEND_END = '<!-- /shipkit:when-legend -->'
+
+export class WhenCommand extends Command {
+    static override paths = [['when']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'what runs when: every check on every context, with the legend',
+        details: 'Every check on every context (commit, ci, full, release, health, save, clock, fix) and how its answer is cached, after the legend of every axis and value. Reports, never gates.',
+        examples: [
+            ['the legend, then every check', 'sk when'],
+            ['only what the quick gate runs', 'sk when --only onCi'],
+            ['the matrix without the legend', 'sk when --no-legend'],
+            ['machine-readable', 'sk when --json'],
+            ['write the legend into a docs page between its markers', 'sk when --out wiki/build/shipkit/runs.md'],
+            ['fail if that page is stale (lint mode)', 'sk when --out wiki/build/shipkit/runs.md --check'],
+        ],
+    })
+
+    only = Option.String('--only', { required: false, description: `only the rows one context runs: ${MATRIX_AXES.join(', ')}` })
+    legend = Option.Boolean('--legend', true, { description: 'print the legend first. Default on, --no-legend drops it' })
+    out = Option.String('--out', { required: false, description: 'host file carrying the shipkit:when-legend markers. The legend between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the legend is stale, write nothing' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { legend, rows: [{ id, title, from, blocking, build, runs: { cells, cache, off, derivedWhy } }] }' })
+
+    async execute(): Promise<number> {
+        if (this.out != null) return await this.writeLegend(this.out)
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        if (this.only != null && !(MATRIX_AXES as readonly string[]).includes(this.only)) {
+            this.context.stdout.write(`FAIL: --only takes one of ${MATRIX_AXES.join(', ')}, got '${this.only}'\n`)
+            return 1
+        }
+        const rows = (await gateInventory(root, c)).map((r) => ({ id: r.decl.id, title: r.title, from: r.from, blocking: r.blocking, build: r.build, runs: runsCellsOf(r) }))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify({ legend: RUNS_LEGEND, rows })}\n`)
+            return 0
+        }
+        for (const l of matrixLines(rows, { legend: this.legend, only: this.only as MatrixAxis | undefined })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+
+    /** the legend only depends on the binary, never on the repo */
+    private async writeLegend(path: string): Promise<number> {
+        const { existsSync, readFileSync, writeFileSync } = await import('fs')
+        if (!existsSync(path)) { this.context.stdout.write(`FAIL: ${path} does not exist\n`); return 1 }
+        const host = readFileSync(path, 'utf8')
+        const next = spliceMarkedBlock(host, legendMarkdown(), LEGEND_BEGIN, LEGEND_END)
+        if (next == null) { this.context.stdout.write(`FAIL: ${path} has no ${LEGEND_BEGIN} / ${LEGEND_END} markers\n`); return 1 }
+        if (next === host) { this.context.stdout.write(`ok: ${path} legend current\n`); return 0 }
+        if (this.check) {
+            this.context.stdout.write(`FAIL: ${path} legend is STALE, the binary's axes or values differ from the page\n`)
+            this.context.stdout.write(`      fix: shipkit when --out ${path}\n`)
+            return 1
+        }
+        writeFileSync(path, next)
+        this.context.stdout.write(`ok: ${path} legend rewritten\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Wiki.ts

@@ -10,8 +10,8 @@ export class WikiServeCommand extends Command {
         category: 'Wiki',
         description: 'live md link-graph server — reload = rescan',
         examples: [
-            ['serve the cwd wiki', 'shipkit wiki serve'],
-            ['serve a subtree on a port', 'shipkit wiki serve --root agent --index process.md --port 6162'],
+            ['serve the cwd wiki', 'sk wiki serve'],
+            ['serve a subtree on a port', 'sk wiki serve --root agent --index process.md --port 6162'],
         ],
     })
 
@@ -38,8 +38,8 @@ export class WikiLintCommand extends Command {
         category: 'Wiki',
         description: 'fail on orphan pages and dangling refs (exit 1)',
         examples: [
-            ['lint the cwd wiki', 'shipkit wiki lint'],
-            ['lint a subtree', 'shipkit wiki lint --root agent --index process.md'],
+            ['lint the cwd wiki', 'sk wiki lint'],
+            ['lint a subtree', 'sk wiki lint --root agent --index process.md'],
         ],
     })
 

package/src/cli.ts

@@ -11,7 +11,7 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand } from './cli/cmd_GlobalProcesses.ts'
+import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
@@ -29,6 +29,9 @@ import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
 import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
+import { WhenCommand } from './cli/cmd_When.ts'
+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 { StatusCommand } from './cli/cmd_Status.ts'
@@ -43,7 +46,7 @@ import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 export function buildCli(): Cli {
     const cli = new Cli({
         binaryLabel: 'shipkit — repo toolkit',
-        binaryName: 'shipkit',
+        binaryName: 'sk',
         binaryVersion: LIB_VERSION,
         enableCapture: true, // console output pipes into the command streams (testable)
         enableColors: true,
@@ -91,10 +94,16 @@ export function buildCli(): Cli {
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
     cli.register(GlobalProcessesCommand)
+    cli.register(GlobalProcessStartCommand)
+    cli.register(GlobalProcessStopCommand)
+    cli.register(GlobalProcessRestartCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
+    cli.register(WhenCommand)
+    cli.register(CacheAuditCommand)
+    cli.register(TraceAuditCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(ConfigKeysCommand)

package/src/collections/checks.ts

@@ -20,6 +20,7 @@ import { rawName, routesToShipkit } from '../core/canonical-scripts.ts'
 import { FLOOR_IDS } from '../core/floor.ts'
 import { FOREVER_MS, formatLine, ttlMsOf } from '../core/wire.ts'
 import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
+import { runsCellsOf } from '../core/runs-matrix.ts'
 import { readLastLines, readRuns, runsPath, type LastLine, type RunRow } from '../ledger/run-log.ts'
 import { checkStatsFor, type CheckStat } from '../ledger/check-stats.ts'
 import { NEGATIVE_TTL_CAP_MS } from '../ledger/world-cache.ts'
@@ -114,6 +115,7 @@ function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat
         description: row.description,
         lastLines: wireLines,
         gate: row.gate,
+        runs: runsCellsOf(row),
         build: row.build,
         blocking: row.blocking,
         advisory,

package/src/collections/collection-types.ts

@@ -7,6 +7,7 @@
 // the docs wiki this lib ships beside.
 
 import type { WhenAt, WhenSource } from '../core/when.ts'
+import type { RunsCells } from '../core/runs-matrix.ts'
 import type { CheckFrom } from '../ledger/gate-checks.ts'
 
 export type NeedSeverity = 'red' | 'yellow'
@@ -22,14 +23,15 @@ export const RUNS_ID = 'runs'
  *  row, the runs page and the to fix list all open the same page by it */
 export const testId = (file: string): string => `test:${file}`
 
-/** where the tree files the test files no check reaches, in both views */
+/** the path segment of a test file no check reaches, where a check id sits
+ *  for the others, so the filter finds a test file by its check */
 export const NO_CHECK = 'in no check'
 
-/** the resource KIND, never the collection it came from: one folder holds
- *  several kinds, which is what makes the path tree worth having. There is no
+/** the resource KIND, never the collection it came from: it decides the
+ *  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'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 
@@ -53,6 +55,9 @@ export type CheckFacts = {
     lastLines: string[]
     /** does `shipkit ci` run it? false = proactive, `shipkit check` only */
     gate: boolean
+    /** every context it runs in and how it caches, as the when page draws
+     *  it (core/runs-matrix.ts) */
+    runs: RunsCells
     /** a BUILD STEP: the gate runs it, the health pass does not (derived from
      *  a floor slot or the repo's `tasks: []`, never declared by a check) */
     build: boolean
@@ -223,6 +228,9 @@ export type Instance = {
      *  kind, a secret present or missing, a post its venue, an asset its roll
      *  count. Absent = this kind has nothing to say there */
     slot?: string
+    /** the group it sits in on the tree, under its section: an asset's kit
+     *  category. Absent = directly under the section */
+    group?: string
     type: ResourceType
     /** a slash path. Where a truth file exists this IS its repo-relative
      *  path; otherwise a VIRTUAL path under a root named for the type, and