rvlib-shipkit 0.38.1 → 1.0.1

package/src/cli/cmd_Ci.ts

@@ -1,6 +1,8 @@
 // shipkit ci — the commit/deploy gate. Thin clipanion surface; logic in
 // core/run-ci.ts.
 import { Command, Option } from 'clipanion'
+import { join } from 'path'
+import { recordExit, startDetached } from '../core/jobs.ts'
 import { runCi } from '../core/run-ci.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 
@@ -9,35 +11,68 @@ export class CiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'THE command. Repairs what a machine can (formatter, imports, repo shape), runs every task, then every check. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
+        description: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
             ['full gate, mechanical fixes applied', 'shipkit ci'],
             ['gate without the repair pass (checks can still write)', 'shipkit ci --no-fix'],
             ['leave repo config files alone', 'shipkit ci --no-fix-rules'],
             ['stop at the first failure', 'shipkit ci --bail'],
-            ['one task + its dep closure', 'shipkit ci --only typecheck'],
-            ['re-measure everything, replay nothing', 'shipkit ci --fresh'],
-            ['include an opt-in task', 'shipkit ci --with up:itch'],
+            ['one check + its dep closure', 'shipkit ci --only typecheck'],
+            ['every check declaring one group', 'shipkit ci --only wiki'],
+            ['run everything, take nothing from the cache', 'shipkit ci --fresh'],
+            ['include an opt in check', 'shipkit ci --with up:itch'],
+            ['in the background, read it back with shipkit status', 'shipkit ci --detach'],
         ],
     })
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
-    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
-    fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural rule autofixes too. Default on. --no-fix-rules leaves repo config alone' })
-    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
-    skip = Option.Array('--skip', [], { description: 'skip a task group (repeatable)' })
-    withIds = Option.Array('--with', [], { description: 'include an opt-in task (repeatable)' })
-    only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })
-    fresh = Option.Boolean('--fresh', false, { description: 'measure everything: no unit replays from the ledger, and what this run measures is stored fresh' })
+    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural autofixes of the built-in checks too. Default on. --no-fix-rules leaves repo config alone' })
+    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining checks: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
+    skip = Option.Array('--skip', [], { description: 'skip a check group (repeatable)' })
+    withIds = Option.Array('--with', [], { description: 'include a check the quick gate leaves out (repeatable)' })
+    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group' })
+    fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
+    detach = Option.Boolean('--detach', false, { description: 'start this gate in the background and return at once with a run id. `shipkit status <id>` prints it. The gate is an ordinary one: same cache, same run record' })
+    job = Option.String('--job', { hidden: true })
+
     async execute(): Promise<number> {
+        const root = process.cwd()
+        if (this.detach) {
+            const d = startDetached(root, { cli: join(import.meta.dir, '../cli.ts'), args: this.argsAgain() })
+            for (const l of d.lines) this.context.stdout.write(`${l}\n`)
+            return 0
+        }
+        const code = await this.gate(root)
+        if (this.job != null) recordExit(root, this.job, code)
+        return code
+    }
+
+    /** this invocation's flags, --detach aside, for the gate that runs detached */
+    private argsAgain(): string[] {
+        return [
+            ...(this.bail ? ['--bail'] : []),
+            ...(this.json ? ['--json'] : []),
+            ...(this.fix ? [] : ['--no-fix']),
+            ...(this.fixRules ? [] : ['--no-fix-rules']),
+            ...(this.frozen ? ['--frozen'] : []),
+            ...this.skip.flatMap((v) => ['--skip', v]),
+            ...this.withIds.flatMap((v) => ['--with', v]),
+            ...this.only.flatMap((v) => ['--only', v]),
+            ...(this.fresh ? ['--fresh'] : []),
+            ...(this.full ? ['--full'] : []),
+        ]
+    }
+
+    private async gate(root: string): Promise<number> {
         // a stale toolkit updates itself and restarts this exact invocation
         // (loop-guarded, skipped under CI/frozen/source consumption)
-        await maybeSelfUpdateAndRestart(process.cwd())
+        await maybeSelfUpdateAndRestart(root)
         try {
-            return await runCi(process.cwd(), {
+            return await runCi(root, {
                 bail: this.bail,
                 json: this.json,
                 fix: this.fix,

package/src/cli/cmd_Commands.ts

@@ -2,6 +2,7 @@
 // drifts the moment a flag changes, and then teaches commands that do not
 // exist. rendering the live registry makes the doc a build artifact.
 import { Command, Option } from 'clipanion'
+import { spliceMarkedBlock } from '../core/doc-block.ts'
 
 export type CommandOption = { definition: string; description: string }
 export type CommandRow = {
@@ -74,12 +75,7 @@ export const END = '<!-- /shipkit:commands -->'
 /** replace the marked block in a host file. Returns null when the markers are
  *  missing, so a renamed or hand-mangled host fails loud instead of silently
  *  writing nothing. */
-export function spliceBlock(host: string, block: string): string | null {
-    const a = host.indexOf(BEGIN)
-    const b = host.indexOf(END)
-    if (a === -1 || b === -1 || b < a) return null
-    return `${host.slice(0, a + BEGIN.length)}\n\n${block}\n\n${host.slice(b)}`
-}
+export const spliceBlock = (host: string, block: string): string | null => spliceMarkedBlock(host, block, BEGIN, END)
 
 export class CommandsCommand extends Command {
     static override paths = [['commands']]

package/src/cli/cmd_ConfigKeys.ts

@@ -0,0 +1,69 @@
+// `shipkit config-keys` — the repo.config.ts surface as markdown, read from
+// the types themselves. Twin of `shipkit commands`: the binary is the source,
+// the page is the artifact, and a lint in the docs repo fails when the two
+// disagree.
+import { fileURLToPath } from 'url'
+import { Command, Option } from 'clipanion'
+import { BEGIN, END, CHECK_BEGIN, CHECK_END, configKeys, renderKeys, undocumented } from '../core/config-keys.ts'
+import { spliceMarkedBlock } from '../core/doc-block.ts'
+
+/** the two types the walks start from, and the files that declare them: what
+ *  a repo declares in its CONFIG, and what one `*.check.ts` file declares */
+export const CONFIG_TYPE = 'RepoConfig'
+export const CHECK_TYPE = 'CheckDef'
+export const configSourceFile = (): string => fileURLToPath(new URL('../repo-config.ts', import.meta.url))
+export const checkSourceFile = (): string => fileURLToPath(new URL('../check.ts', import.meta.url))
+
+export class ConfigKeysCommand extends Command {
+    static override paths = [['config-keys']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every repo.config.ts key and every check field with its doc, read from the types — the source a config reference page is generated FROM',
+        examples: [
+            ['markdown reference', 'shipkit config-keys'],
+            ['machine-readable', 'shipkit config-keys --json'],
+            ['write into a docs page between the markers', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md'],
+            ['fail if that page is stale (lint mode)', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md --check'],
+            ['name the keys carrying no doc comment', 'shipkit config-keys --undocumented'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable { config, check } of [{path, name, type, optional, doc, depth}]' })
+    out = Option.String('--out', { description: 'host file carrying the shipkit:config-keys and shipkit:check-keys markers. Both blocks are rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
+    undocumented = Option.Boolean('--undocumented', false, { description: 'list the keys with no doc comment in the source, and exit 1 if there are any' })
+
+    async execute(): Promise<number> {
+        const keys = configKeys(configSourceFile(), CONFIG_TYPE)
+        const checkKeys = configKeys(checkSourceFile(), CHECK_TYPE)
+        if (this.undocumented) {
+            const missing = [...undocumented(keys), ...undocumented(checkKeys)]
+            if (missing.length === 0) { this.context.stdout.write(`ok: every ${CONFIG_TYPE} and ${CHECK_TYPE} key carries a doc comment (${keys.length + checkKeys.length} keys)\n`); return 0 }
+            this.context.stdout.write(`FAIL: ${missing.length} key(s) carry no doc comment — a key nobody documented is a key nobody uses\n`)
+            for (const p of missing) this.context.stdout.write(`      ${p}\n`)
+            return 1
+        }
+        if (this.out == null) {
+            this.context.stdout.write(this.json ? `${JSON.stringify({ config: keys, check: checkKeys })}\n` : `${renderKeys(keys)}\n\n${renderKeys(checkKeys)}\n`)
+            return 0
+        }
+        const { existsSync, readFileSync, writeFileSync } = await import('fs')
+        if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
+        const host = readFileSync(this.out, 'utf8')
+        const spliced = spliceMarkedBlock(host, renderKeys(keys), BEGIN, END)
+        if (spliced == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
+        const next = spliceMarkedBlock(spliced, renderKeys(checkKeys), CHECK_BEGIN, CHECK_END)
+        if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${CHECK_BEGIN} / ${CHECK_END} markers\n`); return 1 }
+        const total = keys.length + checkKeys.length
+        if (next === host) { this.context.stdout.write(`ok: ${this.out} config reference current (${total} keys)\n`); return 0 }
+        if (this.check) {
+            this.context.stdout.write(`FAIL: ${this.out} config reference is STALE — the types carry keys the page does not list\n`)
+            this.context.stdout.write(`      fix: shipkit config-keys --out ${this.out}\n`)
+            return 1
+        }
+        writeFileSync(this.out, next)
+        this.context.stdout.write(`ok: ${this.out} config reference rewritten (${total} keys)\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Contracts.ts

@@ -8,7 +8,7 @@ export class ContractsCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'release-contract fulfillness, fast and filesystem-only — deploy tasks dep on it',
+        description: 'release-contract fulfillness, fast and filesystem-only — deploy checks dep on it',
         examples: [
             ['all applicable contracts', 'shipkit contracts'],
             ['one venue', 'shipkit contracts --venue itch'],

package/src/cli/cmd_Fleet.ts

@@ -5,10 +5,17 @@
 import { Command, Option } from 'clipanion'
 import { existsSync } from 'fs'
 import { join } from 'path'
-import { npmLatest, resolveLatest, scanFleet, type FleetRepo } from '../fleet/scan-fleet.ts'
+import { npmLatest, resolveLatest, scanFleet, updateRefusal, type FleetRepo } from '../fleet/scan-fleet.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
+import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
 
 const short = (name: string): string => name.replace(/^rvlib-/, '')
+// the hand-run fallback speaks the manager THAT repo installs with: telling
+// an npm consumer to run bun leaves its package-lock.json behind
+const manualUpdate = (r: FleetRepo): string => {
+    const pm = detectPackageManager(r.dir)
+    return isRefusal(pm) ? `<its package manager> update ${r.behind.map((d) => d.name).join(' ')} (${pm.refused})` : pm.update(r.behind.map((d) => d.name)).join(' ')
+}
 
 export class FleetCommand extends Command {
     static override paths = [['fleet']]
@@ -88,9 +95,15 @@ export class FleetCommand extends Command {
                 failed++
                 continue
             }
+            const refused = updateRefusal(r)
+            if (refused != null) {
+                w(`WARN ${r.name}: not updating: ${refused}`)
+                failed++
+                continue
+            }
             const cli = join(r.dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')
             if (!existsSync(cli)) {
-                w(`WARN ${r.name}: no shipkit installed, so it cannot update itself — run: cd ${r.dir} && bun update --latest ${r.behind.map((d) => d.name).join(' ')}`)
+                w(`WARN ${r.name}: no shipkit installed, so it cannot update itself — run: cd ${r.dir} && ${manualUpdate(r)}`)
                 failed++
                 continue
             }
@@ -105,7 +118,7 @@ export class FleetCommand extends Command {
             else {
                 failed++
                 w(`WARN ${r.name} did not move — ${line ?? `check exited ${res.code} with no rvlib line`}`)
-                w(`      fix: cd ${r.dir} && bun update --latest ${r.behind.map((d) => d.name).join(' ')}`)
+                w(`      fix: cd ${r.dir} && ${manualUpdate(r)}`)
             }
         }
         // a repo whose gate refused (dirty tree, frozen, a lease held elsewhere)

package/src/cli/cmd_Hooks.ts

@@ -13,7 +13,7 @@ export class HooksInstallCommand extends Command {
     static override paths = [['hooks', 'install']]
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'write hooks/pre-commit + hooks/commit-msg and point core.hooksPath at them (idempotent)',
+        description: 'write .shipkit/hooks/pre-commit + .shipkit/hooks/commit-msg and point core.hooksPath at them (idempotent)',
         examples: [['wire the hooks', 'shipkit hooks install']],
     })
 

package/src/cli/cmd_Keys.ts

@@ -1,24 +1,26 @@
-// shipkit keys — what every gate unit is keyed on, and what it is NOT.
+// shipkit keys — what every gate check is keyed on, and what it is NOT.
 //
-// Nothing is cached yet. This command exists so the key layer is auditable by
-// eye BEFORE anything replays off it: a cache whose keys nobody can read is a
+// This command exists so the key layer is auditable by eye, whatever the
+// cache serves off it: a cache whose keys nobody can read is a
 // cache nobody can debug the day it serves a wrong answer. `--why <id>` prints
 // the exact component list a key was hashed from, which is the only honest
 // answer to "why did this key move".
 import { createHash } from 'crypto'
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
-import { envTier, FULL_TESTS_ENV, gateUnits, tieredTasks } from '../ledger/gate-units.ts'
+import { envTier, FULL_TESTS_ENV, gateChecks } from '../ledger/gate-checks.ts'
 import { KeyLayer } from '../ledger/git-key.ts'
+import { Ledger } from '../ledger/ledger.ts'
+import { gateBinary } from '../ledger/toolchain-identity.ts'
 
 export class KeysCommand extends Command {
     static override paths = [['keys']]
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'the cache key of every gate unit (task, rule, check), and the reason the undeclared ones have none. Reports, never gates',
+        description: 'the cache key of every gate check, and the reason the undeclared ones have none. Reports, never gates',
         examples: [
-            ['every unit and its key', 'shipkit keys'],
+            ['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'],
@@ -27,9 +29,9 @@ export class KeysCommand extends Command {
         ],
     })
 
-    json = Option.Boolean('--json', false, { description: 'machine-readable { units: UnitKey[], burnDown, errors, scanMs }' })
-    burnDown = Option.Boolean('--burn-down', false, { description: 'list only the units nothing can cache yet, and why' })
-    why = Option.String('--why', { required: false, description: 'print every component that went into ONE unit\'s key' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { checks: CheckKey[], burnDown, errors, scanMs }' })
+    burnDown = Option.Boolean('--burn-down', false, { description: 'list only the checks nothing can cache yet, and why' })
+    why = Option.String('--why', { required: false, description: 'print every component that went into ONE check\'s key' })
     full = Option.Boolean('--full', false, { description: `render the keys a FULL-tier run asks for (same as ${FULL_TESTS_ENV}=1). The tier is in every task's key` })
     rescan = Option.Boolean('--rescan', false, { description: 'run the post-run re-hash and name every input that moved since the scan' })
 
@@ -40,29 +42,51 @@ export class KeysCommand extends Command {
         // every task's env, which is in the key, so a surface that renders keys
         // without it renders a tier nobody asked for
         const tier = this.full ? 'full' : envTier()
-        const decls = gateUnits(root, c, tieredTasks(c, root, tier))
-        const layer = KeyLayer.open(root, decls, { cliEntry: new URL('../cli.ts', import.meta.url).pathname })
+        const decls = await gateChecks(root, c, { tier })
+        const layer = KeyLayer.open(root, decls, { cliEntry: gateBinary() })
         const keys = layer.keys()
         const out = (l: string): void => { this.context.stdout.write(`${l}\n`) }
 
         if (this.json) {
             const drift = this.rescan ? layer.rescan() : null
-            out(JSON.stringify({ tier, units: keys, burnDown: layer.registration.burnDown, errors: layer.registration.errors, layerMs: Math.round(layer.openMs), scanMs: Math.round(layer.scanMs), failure: layer.failure, drift }))
+            out(JSON.stringify({ tier, checks: keys, burnDown: layer.registration.burnDown, errors: layer.registration.errors, layerMs: Math.round(layer.openMs), scanMs: Math.round(layer.scanMs), failure: layer.failure, drift }))
             return layer.registration.errors.length > 0 || layer.failure != null ? 1 : 0
         }
 
         if (this.why != null) {
             const k = keys.find((u) => u.id.toLowerCase() === this.why!.toLowerCase())
             if (k == null) {
-                out(`FAIL: no gate unit '${this.why}' — run \`shipkit keys\` for the list`)
+                out(`FAIL: no gate check '${this.why}' — run \`shipkit keys\` for the list`)
                 return 1
             }
-            out(`${k.kind} ${k.id} — ${k.population}`)
+            out(`${k.id} — ${k.population}`)
             if (k.key == null) {
                 out(`      no key: ${k.reason ?? 'undeclared'}`)
                 return 0
             }
             out(`      key ${k.key}`)
+            if (k.population === 'reads') {
+                for (const comp of k.components) out(`      ${comp}`)
+                // the rest of its identity is what it READ, stored with the
+                // answer and re-checked before any replay
+                const set = Ledger.open(root, decls, { cliEntry: gateBinary(), read: true }).storedReads(k.id)
+                if (set == null) {
+                    out('      no stored answer yet: the next run records what it reads')
+                    return 0
+                }
+                const files = Object.entries(set.files)
+                const exists = Object.entries(set.exists)
+                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)` : ''}`)
+                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'}`)
+                return 0
+            }
             // the excluded block is 44 lines here and it buries the component
             // that actually moved. It stays HASHED line by line, so this is a
             // rendering choice and not a different key: the digest moves with
@@ -81,22 +105,23 @@ export class KeysCommand extends Command {
 
         for (const e of layer.registration.errors) out(`FAIL: ${e}`)
         if (layer.failure != null) {
-            out(`FAIL: git scan failed, no unit may be keyed — ${layer.failure}`)
+            out(`FAIL: git scan failed, no check may be keyed — ${layer.failure}`)
             out('      fix: nothing is cached, so the gate is unaffected. A stale scratch index clears with: rm .git/shipkit/scan.idx')
         }
 
-        // the burn-down is what nobody has LOOKED at. A unit that declared
+        // the burn-down is what nobody has LOOKED at. A check that declared
         // `never` with a reason has been looked at, and listing it here would
         // put four permanent rows on a list whose whole job is to shrink
         const decided = new Set(layer.decls.filter((d) => d.never != null && d.never !== '').map((d) => d.id))
         const shown = this.burnDown ? keys.filter((k) => k.population === 'none' && !decided.has(k.id)) : keys
-        for (const k of shown) out(`${k.population.padEnd(7)} ${k.kind.padEnd(5)} ${k.id.padEnd(28)} ${k.key ?? `— ${k.reason ?? ''}`}`)
+        for (const k of shown) out(`${k.population.padEnd(7)} ${k.id.padEnd(28)} ${k.key ?? `— ${k.reason ?? ''}`}`)
 
         const content = keys.filter((k) => k.population === 'content').length
+        const reads = keys.filter((k) => k.population === 'reads').length
         const world = keys.filter((k) => k.population === 'world').length
         const none = keys.filter((k) => k.population === 'none').length
         const todo = layer.registration.burnDown.length
-        out(`\n${keys.length} units — ${content} content, ${world} world, ${none} uncacheable (${none - todo} decided, ${todo} still undeclared) · ${tier} test tier · key layer ${Math.round(layer.openMs)}ms, of which ${Math.round(layer.scanMs)}ms of git`)
+        out(`\n${keys.length} checks — ${content} content, ${reads} reads, ${world} world, ${none} never cached (${none - todo} on purpose, ${todo} still undeclared) · ${tier} test tier · key layer ${Math.round(layer.openMs)}ms, of which ${Math.round(layer.scanMs)}ms of git`)
         if (todo > 0 && !this.burnDown) out(`      the burn-down: shipkit keys --burn-down`)
 
         if (this.rescan) {

package/src/cli/cmd_Mv.ts

@@ -1,5 +1,5 @@
 // shipkit mv, ONE rename command for the whole repo. An md page routes to
-// mv/mv-md.ts (page + sibling asset dir + check.ts + every tracked ref);
+// mv/mv-md.ts (page + sibling asset dir + its check file + every tracked ref);
 // anything else runs shipkit's own rename, which rewrites every path
 // reference in the code. Renaming used to mean knowing WHICH tool applied,
 // and knowing that is exactly the kind of doubt the toolkit exists to remove.
@@ -12,7 +12,7 @@ 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 check.ts) or a code file or folder. Dry run by default. Renames must be CHEAP',
+        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',
         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'],

package/src/cli/cmd_Prose.ts

@@ -4,6 +4,7 @@
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
 import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
 
 export class ProseCommand extends Command {
     static override paths = [['prose']]
@@ -39,7 +40,7 @@ export class ProseCommand extends Command {
             )
             return 0
         }
-        const r = runProseCheck({ root, config: cfg, paths: explicit ? this.targets : undefined, fix: this.fix })
+        const r = runProseCheck({ c: CheckCtx.open({ root, config }), config: cfg, paths: explicit ? this.targets : undefined, fix: this.fix })
         if (this.json) {
             // every hit carries its file: a flat list without one cannot be
             // acted on, and the grouping is already in byFile
@@ -48,6 +49,14 @@ export class ProseCommand extends Command {
             return r.byTier.fix + r.byTier.hard > 0 ? 1 : 0
         }
         const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        // a declared scope that resolves to nothing reads as `0 file(s)
+        // STE-clean`, the same green a clean repo gets, over a check that
+        // inspected no file at all (rule SK014 warns on the same fact)
+        if (!explicit && r.files === 0) {
+            w(`WARN prose scope matches no file: ${(cfg.include ?? []).join(', ')} — declared and inspecting nothing`)
+            w('      fix: fix the globs in repo.config.ts prose.include (or its exempt list), or drop the key to opt out')
+            return 0
+        }
         if (r.fixed.length > 0) w(`ok: rewrote ${r.fixed.length} file(s)`)
         for (const l of proseLines(r, { cap: Number(this.cap) || 25 })) w(l)
         const blocking = r.byTier.fix + r.byTier.hard

package/src/cli/cmd_Releases.ts

@@ -1,4 +1,4 @@
-// shipkit releases — every release unit and where it actually stands. Thin
+// shipkit releases — every releasing unit and where it actually stands. Thin
 // clipanion surface; logic in release/run-releases.ts.
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
@@ -9,7 +9,7 @@ export class ReleasesCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'every release unit 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 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'],

package/src/cli/cmd_Serve.ts

@@ -8,7 +8,7 @@ export class ServeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Serve',
-        description: 'ONE server, ONE page: media studio + asks + creds + posts + health + graphs, with drill-down graph pages',
+        description: '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'],

package/src/cli/cmd_Start.ts

@@ -9,10 +9,10 @@ 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, .rv-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. Seeding CLAUDE.md include lines also opts the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer). Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        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`',
         examples: [
-            ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push', 'shipkit start pong'],
-            ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
+            ['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'],
@@ -21,9 +21,9 @@ export class StartCommand extends Command {
 
     name = Option.String()
     root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
-    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept. Omitted means the run only creates the dir' })
-    alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add' })
-    skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring' })
+    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept. Omitted: the house template (HOUSE_INCLUDE in src/start-repo.ts), the base wiki include then `@./agent/index.md`, and on a machine without that wiki the agent route alone' })
+    alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add. Omitted: `@./CLAUDE.local.md`, the public-repo indirection' })
+    skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring. Omitted: the house list (HOUSE_SKIP in src/start-repo.ts)' })
     github = Option.Boolean('--github', { description: 'ON by default when a repo is being STARTED (a dir this run created, or one with a package.json): it gets a PRIVATE github repo wired as origin, and the first commit is pushed to it. Pass --github to force it for a pre-existing folder, --no-github to keep everything local, the first commit included (SHIPKIT_NO_GITHUB=1 does it for every run)' })
 
     async execute(): Promise<number> {

package/src/cli/cmd_Status.ts

@@ -0,0 +1,25 @@
+// shipkit status — read back a gate started with `shipkit ci --detach`. Thin
+// clipanion surface; logic in core/jobs.ts.
+import { Command, Option } from 'clipanion'
+import { jobStatus, STILL_RUNNING } from '../core/jobs.ts'
+
+export class StatusCommand extends Command {
+    static override paths = [['status']]
+
+    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`,
+        examples: [
+            ['the latest detached run of this checkout', 'shipkit status'],
+            ['one run by id', 'shipkit status ci-mf3k2a-1x2y'],
+        ],
+    })
+
+    id = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        const r = jobStatus(process.cwd(), this.id)
+        for (const l of r.lines) this.context.stdout.write(`${l}\n`)
+        return r.code
+    }
+}

package/src/cli/cmd_Tui.ts

@@ -1,5 +1,5 @@
 // shipkit tui — the live dashboard: Tasks (the ci gate, streamed through
-// the DAG runner) + Checks (contracts + discovered *.check.ts) built in,
+// the DAG runner) + checks (everything the health pass asks for) built in,
 // repo extras injected via repo.config `tui: { panels: [...] }`.
 // The body lives in src/tui/run-tui.ts and is loaded ONLY when the command
 // runs: the react/ink chain must never load for `shipkit ci` in a repo
@@ -11,7 +11,7 @@ export class TuiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'live dashboard: ci tasks + discovered checks, plus panels the repo injects via repo.config tui.panels',
+        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']],
     })
 

package/src/cli.ts

@@ -9,6 +9,7 @@ import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenComma
 import { BumpCommand } from './cli/cmd_Bump.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
+import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { FleetCommand } from './cli/cmd_Fleet.ts'
@@ -22,10 +23,10 @@ import { ProseCommand } from './cli/cmd_Prose.ts'
 import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
-import { RulesCommand } from './cli/cmd_Rules.ts'
-import { UnitsCommand } from './cli/cmd_Units.ts'
+import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
+import { StatusCommand } from './cli/cmd_Status.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
@@ -47,6 +48,7 @@ export function buildCli(): Cli {
     cli.register(Builtins.HelpCommand)
     cli.register(Builtins.VersionCommand)
     cli.register(CiCommand)
+    cli.register(StatusCommand)
     cli.register(BumpCommand)
     cli.register(ReleaseCommand)
     cli.register(ReleasesCommand)
@@ -77,10 +79,11 @@ export function buildCli(): Cli {
     cli.register(ProseCommand)
     cli.register(SmokeCommand)
     cli.register(ReflectCommand)
-    cli.register(RulesCommand)
     cli.register(KeysCommand)
-    cli.register(UnitsCommand)
+    cli.register(ChecksCommand)
+    cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
+    cli.register(ConfigKeysCommand)
 
     return cli
 }

package/src/collections/actions.ts

@@ -10,7 +10,7 @@ const today = (): string => new Date().toISOString().slice(0, 10)
 
 const postPath = (root: string, channel: string, file: string): string => {
     if (channel.includes('/') || channel.includes('..') || file.includes('/') || file.includes('..')) throw new Error('bad path')
-    const p = join(root, '.rv-social', channel, file)
+    const p = join(root, '.shipkit/social', channel, file)
     if (!existsSync(p)) throw new Error(`no such post: ${channel}/${file}`)
     return p
 }
@@ -25,7 +25,7 @@ const setStatus = (p: string, status: string): void => {
  *  (files KEPT — rejections are training data for the next generation) */
 export function pickPostVariant(root: string, channel: string, file: string): void {
     const p = postPath(root, channel, file)
-    const dir = join(root, '.rv-social', channel)
+    const dir = join(root, '.shipkit/social', channel)
     const slug = parsePostFile(dir, channel, file).slug
     setStatus(p, 'picked')
     for (const f of readdirSync(dir).filter((x) => x.endsWith('.md') && x !== file)) {
@@ -55,11 +55,11 @@ export function appendPostFeedback(root: string, channel: string, file: string,
     writeFileSync(p, /^## Feedback\s*$/m.test(md) ? `${md.trimEnd()}\n${line}\n` : `${md.trimEnd()}\n\n## Feedback\n${line}\n`)
 }
 
-/** an asset remark → `.rv-assets/notes.md` (git-tracked; the studio
+/** an asset remark → `.shipkit/assets/notes.md` (git-tracked; the studio
  *  workspace is gitignored, so notes live beside kit.ts) */
 export function appendAssetNote(root: string, assetId: string, text: string): void {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assetId)) throw new Error('bad asset id')
-    const p = join(root, '.rv-assets', 'notes.md')
+    const p = join(root, '.shipkit/assets', 'notes.md')
     const line = `- ${today()} [${assetId}]: ${text.replace(/\n+/g, ' ').trim()}`
     writeFileSync(p, existsSync(p) ? `${readFileSync(p, 'utf8').trimEnd()}\n${line}\n` : `# asset notes, read by agents at boot\n\n${line}\n`)
 }