rvlib-shipkit 0.35.8 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.37.0
+
+- **The leak guard grew an allowlist, because it had no way to be wrong.** Every keyword matched as a case-insensitive substring over the staged added lines, so a four letter row landed inside a real npm dependency name and inside a base64 integrity hash in `bun.lock`, and that lockfile became uncommittable forever with no per repo override of any kind. The only way past was `--no-verify`, which disarms every other gate too, so the guard was training people to switch it off. Two answers ship, in this order. A `w:<word>` keyword row now matches on word boundaries spelled in unicode rather than with `\b`, which is ascii only and would let an accented name match inside a longer accented word: that makes the PATTERN smarter rather than the guard looser, and it is opt in, so a keyword file that carries no `w:` row behaves exactly as before. Then `repo.config.ts hooks.leakAllow` (with the machine-global twin `~/.rv-private/leak-allow.json`) declares a known-good match: `paths` names the files, `patterns` names the keywords, and `inHashes` narrows to a match that falls inside a content hash, where the bytes are an address rather than prose. `paths` plus `patterns` is the shape to reach for, because it waives one keyword in named files while the same keyword still blocks everywhere else, and a single occurrence outside a hash refuses an `inHashes` entry outright.
+- **A waiver is never silent.** Each entry carries a required `reason`, every waiver that fires PRINTS with that reason and the entry that owns it (on the FAIL path too, so a partial waive is visible beside what still blocks), and `hooks list` counts the declared waivers. An entry with no reason, with neither `paths` nor `patterns`, or with an unknown key dies at config load through `defineRepo`, and an allowlist file that will not parse waives nothing and WARNs, so a broken waiver leaves the guard stricter rather than looser.
+- **A tracked allowlist never becomes a copy of the private keyword list.** An entry names a keyword by FINGERPRINT (`fp:` plus 12 hex of its sha256), printed beside every hit, which is how a waiver gets written without anyone typing the private word into git. `repo.config.ts` takes the fingerprint form alone and refuses a literal by name. The private machine-global file may use either. The honest limit is stated in the source: a fingerprint stops the list being read off a tracked file and is no defence against a targeted guess.
+- The staged diff is now parsed per FILE (`addedLinesByFile`), so a hit says which file it came from and a waiver can name one. Which file a line belongs to is decided by COUNTING each hunk body from the size its header declares, never by trusting a `+++ …` line wherever it appears: an added line whose own text starts with `++` reaches the parser looking exactly like a file header, and believing one inside a hunk would let ordinary looking text drop every added line after it (`++ /dev/null`) or file the rest under a name a waiver covers (`++ b/bun.lock`). Substring rows match through a case-insensitive regex instead of `indexOf` over a lowercased copy, because one unicode character lowercases into two and slides every offset after it, and those offsets are what decide whether a match sits inside a content hash. A content-hash span is consulted ONLY by an entry that asked for `inHashes`: an api token is also a long base64 run, so skipping those spans by default would silence the guard on the exact shape it exists to catch.
+
+## 0.36.0
+
+- **`shipkit smoke` — verify the way the end user does, after a deploy.** A read only Playwright pass: it logs in through the app's OWN login page, visits every route `repo.config.ts smoke` declares, samples the body text until it stops growing (a `waitFor` selector first, because a spinner holds the length constant), counts the selector's matches, measures whether the PAGE scrolls sideways, screenshots each route under `tmp/smoke/`, and collects console errors, page errors, failed requests and 4xx/5xx responses. The exit code is the number of failed routes. The password is a secret NAME, read through the repo's new `credsReadCommand` template (the READ twin of `credsCommand`, `{name}` and `{field}` substituted, no shell), never argv, env or config, and `defineRepo` refuses a value typed where the name belongs and a login declared without the reader. Playwright is resolved from the CONSUMER repo at run time, never carried by this package: a repo without it gets one line naming `bun add -d playwright && npx playwright install chromium`. When the host sends `x-pockethost-ratelimit-ip-hourly-*` headers, the report prints the budget and labels a CORS-shaped failure as the backend refusing rather than the app failing, telling the hourly quota from the concurrent cap by the remaining count. Between routes it pauses `paceMs` (default 3000, measured against a 15-concurrent cap: 0 reported 8 of 12 routes, 3000 reports 12 of 12). A route with `open` (a link selector) follows the first match's href after it and judges the landed page as its own row, which is how a detail page with a real id gets visited without the config knowing one. The login form lives at `login.path`, default `/login`. A problem collected during the login is a failed row of its own, and the pause runs before the row label moves, so a previous page's late failure lands on the page that caused it. `emailSecret` is refused when the reader template carries no `{field}`: the account read would answer the value, and the run would type the password into the identity box, where a failed-login journal keeps it.
+
+- **The bootstrap wires `origin` as `git@`, never `https://`.** The remote came from `gh config get git_protocol`, which defaults to https, so a started repo got an https origin that re-asks for a credential on every push and says nothing about it until the first push fails. That call is gone, and the https url left the `repo view --json` field list with it: the remote is the `sshUrl` gh returned, and an answer carrying none is a WARN rather than a url the module builds itself, because it knows no host and a guessed `github.com` is the same silent failure one host over. The test account still answers `git_protocol` https and still hands back an https url beside the ssh one, so the two tests pinning this run against a hostile environment rather than an absent one.
+
+- **`shipkit fleet` — the repos on this disk that install the toolkit, and how stale each one is.** Measured on a real machine the day it landed: 10 of 14 repos behind, `rvlib-shipkit` spread across 0.21.0, 0.24.0, 0.26.0, 0.30.0, 0.35.5 and 0.35.8, and one repo two majors behind on `rvlib-pb-mobx`. A doctrine page that documents the current binary is loaded into repos running six different ones, so the drift was invisible from any single repo. It SCANS rather than reading the reporting registry, because that registry only carries repos that already report, and a repo that never reported is the one most likely to be stale. `--update` never writes: it runs each repo's own `check --fix SK005`, which owns the update with the lease and the guards it already has. It judges by SK005's own line rather than by the exit code, because that code covers every rule in that repo. A changed MAJOR is refused without `--major`, and that is deliberately not the semver rule: on a 0.x package every minor is breaking, which fired on 10 of 14 repos including the jumps SK005 performs by itself daily, so the flag was rewritten to fire only on the case a human has to own.
+
+- **`shipkit prose` + rule SK014 — the STE standard, enforceable.** ASD-STE100 was house doctrine with no tooling: three regex classes lived inside one repo's hand-rolled lint, and nothing shipped to any consumer. The checker now lives here, in `prose/ste.ts`, with the file walking and the wire lines in `prose/run-prose.ts`. Three tiers, and the split is the whole design. `fix` classes are mechanical (contractions, latin, one-to-one substitutions that carry their verb inflection across, empty words) and `--fix` rewrites them idempotently. `hard` classes are real violations whose repair is a judgement call (banned modal, semicolon, `-ing` after a comma, perfect tense, a vague word carrying no measurable fact), so they FAIL and name what STE wants instead: `should` becomes `must` or `can` depending on what the writer meant, and a machine that guesses writes a false requirement. `soft` classes (sentence length, passive voice, paragraph length) need a human read, so they WARN, and an optional `baseline` turns them into a ratchet that only goes down. Scope is DECLARED, never assumed: a repo with no `prose.include` is skipped with the line that opts it in.
+- **The Untouchables are masked before any rule runs**, and the mask preserves every offset: frontmatter, code fences, inline code, double-quoted verbatim spans, URLs and link targets, blockquotes. A checker that rewrites a quoted requirement destroys the thing the quote was protecting, and a reported line number that is off by a fence is a line number nobody trusts. A code span counts as ONE word toward a sentence limit, and an em-dash separator is structure rather than sentence punctuation, so a route line is not read as one forty-word sentence.
+- The approved-word dictionary is deliberately NOT in this package. It is copyrighted, so it cannot ride in a tarball, and it bans most of a toolkit's own vocabulary: `check` is a noun only, `run`, `render`, `delete`, `verify` and `confirm` are all not-approved verbs. Pragmatic mode, the structural rules plus a slop table, is what ships.
+
+- **`shipkit units` — the inventory that no command owned.** Every task, rule and discovered check on one table, with what each declared about itself: whether `shipkit ci` runs it or only `shipkit check`, whether a failure blocks or warns, its cache population and TTL, what it reads, and who owns it. `shipkit rules` covers a third of the rows and `shipkit keys` answers a different question (what a unit is keyed on right now), so the one thing an operator most needs, can this stop me, had no surface at all and was answered by opening source files. `--proactive` narrows to the units the gate never runs, `--blocking` to the ones that can stop you, `--json` is the machine shape, `--out <file>` writes the markdown table.
+- **`STATUS.full.md`, refreshed beside STATUS.md by both `ci` and `check`.** Generated, gitignored and untracked through the same SK004 policy as STATUS.md. It deliberately carries NO run state: no timestamp, no key hashes, no verdict, so the file moves only when a declaration moves and its diff is the audit trail of that change. STATUS.md links to it.
+- **A measured NEGATIVE no longer caches for the unit's full TTL.** `check-suite.ts` decided cacheability with `(clean || !r.blocking)`, so any non-blocking check remembered a red for its whole window. With long TTLs that is a red outliving the fix that cleared it, and a discovered check's world key carries no rotation material, so re-minting the credential does not bust it either. A clean answer still keeps for the declared TTL, because "the world is fine" is what a long TTL is for. A negative keeps for one hour at most. `Stored<T>` grew an optional `keeps`, so an entry carries its own window instead of the reader inferring one from the unit, and old entries without it fall back to the declared TTL.
+- `gateInventory()` in `ledger/gate-units.ts` is now the single walk of the three registries, and `gateUnits()` is that list narrowed to the cache declaration. A surface can no longer enumerate a different unit set than the one the key layer keyed. `StatusInput` grew an optional `sidecar`, so a caller that writes no companion file never advertises one.
+
 ## 0.35.8
 
 - **`release.requireHealthy` had become a no-op for exactly the checks it exists for.** `runCi` hardcoded `gateOnly: true` on its checks call, and `requireHealthy` is implemented one layer up as `onlyBlockingChecks: false` plus `failOnAdvisory: true`. The gate filter runs before severity is considered, so a repo that asked for a missing publish credential to stop its release had that request silently dropped the moment its cred check declared `gate = false`. Reproduced through `runCi` with the exact option shape the release path builds, against a check exiting 1 with a FAIL line: the line never appeared and the gate returned 0. `gateOnly` now yields to `failOnAdvisory`, so `requireHealthy` re-arms every opted-out check. Two tests, one per option shape.

package/README.md

@@ -49,6 +49,12 @@ shipkit assets    serve|fill|add|gen|identity|check — the asset atelier
 shipkit pb        collection <name> — scaffold a PocketBase collection's UI
                   folder (columns/card/grid/form/index) from the app's
                   generated pb types, create-only          [--dry-run]
+shipkit smoke     browser pass over a DEPLOYED web app, read only: login
+                  through the app's own form, every route in repo.config
+                  `smoke`, screenshots, console/network problems, the host
+                  quota headers, a detail page per `open` link. Exit code =
+                  failed routes. Needs playwright in the repo
+                                          [--base <url> --routes /a,/b]
 shipkit serve     the repo's ONE server: hub page, graphs, studio, status
 shipkit reflect   your prompts across every Claude Code session of a repo:
                   all config roots, queued-mid-run ones included, harness

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.35.8",
+    "version": "0.37.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/cli/cmd_Bump.ts

@@ -16,7 +16,7 @@ export class BumpCommand extends Command {
             ['a breaking release', 'shipkit bump major'],
             ['one sub-unit (ids: shipkit releases)', 'shipkit bump minor rvlib-shipkit'],
             ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'shipkit bump --all'],
-            ['every unit that has Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
+            ['every unit carrying Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
             ['one unit, kind from its own heading', 'shipkit bump rvlib-shipkit'],
             ['rehearse the whole thing', 'shipkit bump minor --dry-run'],
             ['bump and commit, release later', 'shipkit bump patch --no-release'],

package/src/cli/cmd_Fleet.ts

@@ -0,0 +1,116 @@
+// shipkit fleet — every repo on this disk that installs the toolkit, and how
+// far behind each one is. Reports by default. `--update` hands the work to
+// each repo's OWN shipkit, so rule SK005 performs the update with the lease,
+// the dirty-tree guard and the frozen guard it already owns.
+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 { spawnWithTimeout } from '../core/spawn-timeout.ts'
+
+const short = (name: string): string => name.replace(/^rvlib-/, '')
+
+export class FleetCommand extends Command {
+    static override paths = [['fleet']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every repo on this disk that installs the toolkit, and how far behind each one is',
+        examples: [
+            ['what is stale out there', 'shipkit fleet'],
+            ['filesystem only, no registry', 'shipkit fleet --offline'],
+            ['bring every behind repo up, through its own gate', 'shipkit fleet --update'],
+            ['one repo only', 'shipkit fleet --update --only my-app'],
+            ['machine-readable', 'shipkit fleet --json'],
+        ],
+    })
+
+    root = Option.String('--root', { required: false, description: 'directory holding the repos (default: the parent of this repo)' })
+    update = Option.Boolean('--update', false, { description: "run each behind repo's own `shipkit check`, which is where rule SK005 performs the guarded update" })
+    only = Option.Array('--only', { description: 'limit to these repo directory names (repeatable)' })
+    offline = Option.Boolean('--offline', false, { description: 'skip the registry: report what is installed, never what is current' })
+    major = Option.Boolean('--major', false, { description: 'let --update cross a breaking boundary too. Default off: a major (or a 0.x minor) is a porting job, not a bump' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable FleetRepo[]' })
+
+    async execute(): Promise<number> {
+        const root = this.root ?? join(process.cwd(), '..')
+        let repos = scanFleet(root)
+        if (this.only != null && this.only.length > 0) repos = repos.filter((r) => this.only!.includes(r.name))
+        const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        if (repos.length === 0) {
+            w(`skip: no repo under ${root} depends on an rvlib-* package`)
+            return 0
+        }
+        if (!this.offline) await resolveLatest(repos, npmLatest)
+
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(repos, null, 2)}\n`)
+            return 0
+        }
+
+        for (const r of repos) w(this.row(r))
+        const behind = repos.filter((r) => r.behind.length > 0 && !r.linked)
+        if (this.offline) {
+            w(`ok: ${repos.length} repo(s) scanned, registry not consulted (--offline)`)
+            return 0
+        }
+        if (behind.length === 0) {
+            w(`ok: ${repos.length} repo(s), every published dep current`)
+            return 0
+        }
+        if (!this.update) {
+            w(`WARN ${behind.length}/${repos.length} repo(s) behind — rerun with --update, which runs each repo's own gate so SK005 does the write`)
+            return 0
+        }
+        return await this.runUpdates(behind, w)
+    }
+
+    private row(r: FleetRepo): string {
+        const cells = r.deps.map((d) => {
+            if (d.pin.startsWith('link:') || d.pin.startsWith('file:')) return `${short(d.name)}=source`
+            const at = d.installed ?? 'absent'
+            const stale = r.behind.some((b) => b.name === d.name)
+            const breaks = r.breaking.some((b) => b.name === d.name)
+            return stale ? `${short(d.name)} ${at} → ${d.latest}${breaks ? ' BREAKING' : ''}` : `${short(d.name)} ${at}`
+        })
+        const flag = r.linked ? 'source' : r.breaking.length > 0 ? `${r.breaking.length} BREAKING` : r.behind.length > 0 ? `${r.behind.length} behind` : 'current'
+        return `  ${r.name.padEnd(24)} ${flag.padEnd(10)} ${cells.join(', ')}`
+    }
+
+    /** the update is NOT performed here. Each repo runs its own binary, which
+     *  is the only copy whose SK005 matches the rules that repo is pinned to,
+     *  and the only one holding that repo's mutate lease. */
+    private async runUpdates(behind: FleetRepo[], w: (l: string) => void): Promise<number> {
+        let failed = 0
+        for (const r of behind) {
+            if (r.breaking.length > 0 && !this.major) {
+                w(`WARN ${r.name}: ${r.breaking.map((d) => `${short(d.name)} ${d.installed} → ${d.latest}`).join(', ')} crosses a breaking boundary — that is a porting job. Rerun with --major once somebody owns it`)
+                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(' ')}`)
+                failed++
+                continue
+            }
+            // `check --fix SK005` is the narrow form: a bare rule id is refused,
+            // and a full `check` pays for every world probe to reach one rule
+            const res = await spawnWithTimeout(['bun', cli, 'check', '--fix', 'SK005'], { cwd: r.dir, timeoutMs: 180_000 })
+            // judge by what SK005 SAID, never by the exit code: that code covers
+            // every rule in that repo, and a repo can be red for a reason this
+            // command neither caused nor owns
+            const line = res.out.split('\n').find((l) => /\brvlib-/.test(l) && (l.startsWith('ok:') || l.startsWith('WARN') || l.startsWith('FAIL')))
+            if (line?.startsWith('ok:') === true) w(`ok: ${r.name} — ${line.slice(4)}`)
+            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(' ')}`)
+            }
+        }
+        // a repo whose gate refused (dirty tree, frozen, a lease held elsewhere)
+        // is a REPORT, not a failure of this command: SK005 defers on purpose
+        w(failed === 0 ? `ok: ${behind.length} repo(s) updated through their own gate` : `WARN ${failed}/${behind.length} repo(s) did not update — each line above says why`)
+        return 0
+    }
+}

package/src/cli/cmd_Prose.ts

@@ -0,0 +1,65 @@
+// shipkit prose — the STE checker as a command, so a writer can run it on one
+// file while drafting instead of waiting for the gate. Rule SK014 runs the
+// same module over the repo's declared scope.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
+
+export class ProseCommand extends Command {
+    static override paths = [['prose']]
+
+    static override usage = Command.Usage({
+        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'],
+        ],
+    })
+
+    // `targets`, not `paths`: clipanion's Command owns the static `paths`
+    targets = Option.Rest()
+    fix = Option.Boolean('--fix', false, { description: 'apply the mechanical rewrites (contractions, latin, one-to-one substitutions, empty words)' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { files, byClass, hits }' })
+    strict = Option.Boolean('--strict', false, { description: 'the 20-word procedural sentence limit instead of the 25-word descriptive one' })
+    cap = Option.String('--cap', '25', { description: 'how many hit lines to print before the per-class totals' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const config = await loadRepoConfig(root)
+        const cfg = { ...(config?.prose ?? {}) }
+        if (this.strict) cfg.strict = true
+        const explicit = this.targets.length > 0
+        if ((cfg.include ?? []).length === 0 && !explicit) {
+            this.context.stdout.write(
+                `skip: this repo declares no prose scope — add \`prose: { include: ['**/*.md'], exempt: [...] }\` to repo.config.ts (identity/writing-voice.md)\n`,
+            )
+            return 0
+        }
+        const r = runProseCheck({ root, 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
+            const hits = r.byFile.flatMap((f) => f.hits.map((h) => ({ file: f.file, ...h })))
+            this.context.stdout.write(`${JSON.stringify({ files: r.files, byTier: r.byTier, byClass: r.byClass, fixed: r.fixed, hits }, null, 2)}\n`)
+            return r.byTier.fix + r.byTier.hard > 0 ? 1 : 0
+        }
+        const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        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
+        const baseline = cfg.baseline
+        const overBaseline = baseline != null && r.byTier.soft > baseline
+        if (blocking === 0 && !overBaseline) {
+            w(`ok: ${r.files} file(s) STE-clean${r.byTier.soft > 0 ? `, ${r.byTier.soft} soft warning(s)${baseline != null ? ` (baseline ${baseline})` : ''}` : ''}`)
+            return 0
+        }
+        if (blocking > 0)
+            w(`FAIL: ${blocking} STE violation(s) in ${r.byFile.length} file(s) — ${classSummary(r)}${r.fixable > 0 ? `\n      fix: shipkit prose --fix clears ${r.fixable} of them` : ''}`)
+        if (overBaseline) w(`FAIL: ${r.byTier.soft} soft hits, above this repo's baseline of ${baseline} — lower the count, or move the baseline down in repo.config.ts`)
+        return 1
+    }
+}

package/src/cli/cmd_Smoke.ts

@@ -0,0 +1,42 @@
+// shipkit smoke — verify the way the end user does: after a deploy, log in
+// through the real login page, walk every route, read only. The routes and
+// the login come from repo.config.ts `smoke`, the password from the keychain.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { DEFAULT_PACE_MS, exitCodeFor, renderReport, runSmoke } from '../smoke/run-smoke.ts'
+
+export class SmokeCommand extends Command {
+    static override paths = [['smoke']]
+
+    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',
+        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'],
+        ],
+    })
+
+    base = Option.String('--base', { description: 'the url to visit instead of smoke.base (a preview deploy, a local dev server)' })
+    routes = Option.String('--routes', { description: 'comma-separated paths to visit instead of the whole list' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const config = await loadRepoConfig(root)
+        const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        if (config.smoke == null) {
+            w(`FAIL this repo declares no smoke config — add \`smoke: { base, routes, login? }\` to repo.config.ts (build/shipkit.md)`)
+            return 1
+        }
+        try {
+            const rep = await runSmoke(root, config.smoke, { base: this.base, routes: this.routes, credsReadCommand: config.credsReadCommand }, { print: w })
+            for (const l of renderReport(rep, { paceMs: config.smoke.paceMs ?? DEFAULT_PACE_MS })) w(l)
+            return exitCodeFor(rep)
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            this.context.stderr.write(`${msg.startsWith('FAIL') ? msg : `FAIL ${msg}`}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Start.ts

@@ -21,7 +21,7 @@ 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 only ensure the dir' })
+    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' })
     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)' })

package/src/cli/cmd_Units.ts

@@ -0,0 +1,82 @@
+// shipkit units — THE inventory: every task, rule and discovered check on one
+// table, with what it declared about itself. `shipkit rules` covers a third of
+// it, `shipkit keys` answers a different question (what is a unit keyed on,
+// right now), and neither says whether a unit blocks you or only reports the
+// world. That answer had no surface, so it was reconstructed by reading source
+// files, which is how a repo ends up with checks nobody can account for.
+import { writeFileSync } from 'fs'
+import { resolve } from 'path'
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { envTier, gateInventory, tieredTasks } from '../ledger/gate-units.ts'
+import { renderUnitTable } from '../ledger/unit-table.ts'
+import { classify } from '../ledger/git-key.ts'
+
+export class UnitsCommand extends Command {
+    static override paths = [['units']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every gate unit on one table: task, rule or check, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
+        examples: [
+            ['the whole inventory', 'shipkit units'],
+            ['the big markdown table, written to a file', 'shipkit units --out STATUS.full.md'],
+            ['only the ones the gate never runs', 'shipkit units --proactive'],
+            ['machine-readable', 'shipkit units --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable UnitRow[] with the resolved cache population' })
+    md = Option.Boolean('--md', false, { description: 'the full markdown table on stdout, the same bytes --out writes' })
+    out = Option.String('--out', { required: false, description: 'write the markdown table to this file instead of stdout' })
+    blocking = Option.Boolean('--blocking', false, { description: 'only units whose failure can stop you' })
+    proactive = Option.Boolean('--proactive', false, { description: 'only units the gate never runs (`shipkit check` reports them)' })
+    full = Option.Boolean('--full', false, { description: 'resolve tasks the way a FULL-tier run resolves them' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        const tier = this.full ? 'full' : envTier()
+        let rows = gateInventory(root, c, tieredTasks(c, root, tier))
+        if (this.blocking) rows = rows.filter((r) => r.blocking !== false)
+        if (this.proactive) rows = rows.filter((r) => !r.gate)
+
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(rows.map((r) => ({ ...r, population: classify(r.decl).population })))}\n`)
+            return 0
+        }
+
+        if (this.md || this.out != null) {
+            const md = renderUnitTable({ name: c.name, rows })
+            if (this.out != null) {
+                const target = resolve(root, this.out)
+                writeFileSync(target, `${md.trimEnd()}\n`)
+                this.context.stdout.write(`ok: ${rows.length} unit(s) written to ${this.out}\n`)
+                return 0
+            }
+            this.context.stdout.write(`${md}\n`)
+            return 0
+        }
+
+        // a catalog, not a health run — no wire prefixes, or anything parsing
+        // wire output reads this as a passing check
+        this.context.stdout.write(`${'kind'.padEnd(5)} ${'unit'.padEnd(28)} ${'runs in'.padEnd(9)} ${'failure'.padEnd(10)} ${'cache'.padEnd(11)} ttl\n`)
+        for (const r of rows) {
+            const cls = classify(r.decl)
+            const cache = cls.error != null ? 'BROKEN' : cls.population === 'none' ? (cls.decided === true ? 'never' : 'UNDECLARED') : cls.population
+            const blocking = r.blocking == null ? 'UNDECLARED' : r.blocking ? 'blocks' : 'warns'
+            const runsIn = r.optIn ? 'opt-in' : r.gate ? 'gate' : 'proactive'
+            this.context.stdout.write(
+                `${r.decl.kind.padEnd(5)} ${r.decl.id.padEnd(28)} ${runsIn.padEnd(9)} ${blocking.padEnd(10)} ${cache.padEnd(11)} ${r.decl.ttl ?? ''}\n`,
+            )
+        }
+        const undeclared = rows.filter((r) => { const cl = classify(r.decl); return cl.population === 'none' && cl.decided !== true }).length
+        const proactive = rows.filter((r) => !r.gate && !r.optIn).length
+        this.context.stdout.write(
+            `\n${rows.length} units — ${rows.length - proactive} in the gate, ${proactive} proactive · ${undeclared} still uncacheable with nobody having looked\n`,
+        )
+        if (undeclared > 0) this.context.stdout.write(`      why each one: shipkit keys --burn-down\n`)
+        this.context.stdout.write(`      the full table, refreshed by every gate run: STATUS.full.md\n`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -11,17 +11,21 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
+import { FleetCommand } from './cli/cmd_Fleet.ts'
 import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cli/cmd_Hooks.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
 import { KeysCommand } from './cli/cmd_Keys.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { PbCollectionCommand } from './cli/cmd_Pb.ts'
+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 { ServeCommand } from './cli/cmd_Serve.ts'
+import { SmokeCommand } from './cli/cmd_Smoke.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
@@ -68,10 +72,14 @@ export function buildCli(): Cli {
     cli.register(InitCommand)
     cli.register(StartCommand)
     cli.register(NeedsCommand)
+    cli.register(FleetCommand)
     cli.register(PbCollectionCommand)
+    cli.register(ProseCommand)
+    cli.register(SmokeCommand)
     cli.register(ReflectCommand)
     cli.register(RulesCommand)
     cli.register(KeysCommand)
+    cli.register(UnitsCommand)
     cli.register(CommandsCommand)
 
     return cli

package/src/core/check-suite.ts

@@ -24,6 +24,12 @@ type Logic = (t: CheckCtx) => unknown
 type Prep = { skip?: string; cacheExtra?: string }
 type Runner = { name: string; ttlMs: number; version: number; prep?: () => Prep; logic: Logic; blocking: boolean }
 
+/** the longest a MEASURED NEGATIVE is remembered, whatever TTL the unit
+ *  declared. Long enough to stop a re-ask storm inside one working session,
+ *  short enough that the world being fixed is noticed the same day. A clean
+ *  answer is not capped: "fine" is what a long TTL is for. */
+const NEGATIVE_TTL_CAP_MS = 60 * 60 * 1000
+
 export type GetSecret = (name: string, field: 'get' | 'account') => string | null
 
 export type SecretSpec = {
@@ -158,8 +164,12 @@ export class CheckSuite {
         const key = this.cacheKey(r, prep.cacheExtra ?? '')
         const path = entryPath(this.storeDir, this.name, r.name, key)
         const entry = readStored<Line[]>(path, key)
+        // an entry may keep for LESS than the declared TTL: a measured negative
+        // writes its own shorter window (below), so the run after a fix sees
+        // the fix rather than the memory of the breakage
+        const keeps = entry?.keeps ?? r.ttlMs
         const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
-            && entry != null && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
+            && entry != null && this.now() - entry.at < keeps && this.now() >= entry.at
         if (fresh) {
             // the stamp was baked in when the check RAN (below): a replay
             // prints the stored lines VERBATIM, so the live run and every
@@ -191,10 +201,19 @@ export class CheckSuite {
         //   measured negative  a probe that RAN and came back bad ("the box is
         //                      off", "the token answered 403", "five repos are
         //                      uncatalogued") is a real answer about the world.
-        //                      Replaying it for its TTL is CORRECT: the world
+        //                      Replaying it is CORRECT for a WHILE: the world
         //                      does not fix itself between two gate runs, and
         //                      re-asking every 30 seconds spends a third-party
-        //                      API call to be told the same thing.
+        //                      API call to be told the same thing. It is NOT
+        //                      correct for the full TTL, and that asymmetry is
+        //                      deliberate: a clean pass says the world is fine,
+        //                      which a long TTL is exactly right for, while a
+        //                      negative names something a HUMAN is expected to
+        //                      go fix, and the fix is invisible from here. A
+        //                      100d TTL over a revoked token would show the
+        //                      same red for 100 days after it was re-minted,
+        //                      because the token value is not in this key. So a
+        //                      negative keeps for NEGATIVE_TTL_CAP at most.
         //   unmeasured         a probe that could not run at all ("registry
         //                      unreachable", "no cred", "rate limited", tool
         //                      missing) produced no answer. Caching it asserts
@@ -208,14 +227,18 @@ export class CheckSuite {
         const unmeasured = t.unmeasured || t.lines.some((l) => l.kind === 'skip')
         const clean = !t.failed && !t.warned
         const cacheable = r.ttlMs > 0 && !unmeasured && (clean || !r.blocking)
+        // a clean answer keeps for the whole declared TTL. a negative keeps
+        // only long enough to stop the re-ask storm, so the run after a human
+        // fixes the world sees the fix instead of the memory of the breakage
+        const keepsFor = clean ? r.ttlMs : Math.min(r.ttlMs, NEGATIVE_TTL_CAP_MS)
         const lines = cacheable
-            ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (${clean ? 'cached' : 'measured'} at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + r.ttlMs)})` } : l))
+            ? t.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (${clean ? 'cached' : 'measured'} at ${fmtStamp(this.now())} until ${fmtStamp(this.now() + keepsFor)})` } : l))
             : t.lines
         this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false, ms: performance.now() - started })
         // this check writes its OWN file, and only its own: nothing here reads
         // or rewrites a neighbour's entry, so a racing runner can lose nothing
         if (r.ttlMs > 0) {
-            if (cacheable) writeStored(path, key, lines, this.now())
+            if (cacheable) writeStored(path, key, lines, this.now(), keepsFor)
             // an unmeasured run evicts whatever was stored: a later run must
             // re-probe rather than replay an answer recorded before the outage.
             // A racing runner may have written a good answer into that same

package/src/core/run-check.ts

@@ -24,6 +24,8 @@ import { RULES } from '../rules/rule-registry.ts'
 import { runRuleLint } from '../rules/rule.ts'
 import { formatLine, parseWireOutput, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
+import { gateInventory } from '../ledger/gate-units.ts'
+import { UNIT_TABLE_FILE, writeUnitTable } from '../ledger/unit-table.ts'
 import { SHARE_ENV } from '../release/releases-share.ts'
 import { rmSync } from 'fs'
 
@@ -290,8 +292,17 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
     if (o.status !== false) {
         // the producing command is named honestly: a checks-only run must not
         // overwrite the gate verdict with a green nobody gated
-        const st = writeStatus(root, { name: c.name, command: 'shipkit check', lines: run.lines.map((l) => formatLine(l, false)), exitCode: code })
+        const st = writeStatus(root, {
+            name: c.name,
+            command: 'shipkit check',
+            lines: run.lines.map((l) => formatLine(l, false)),
+            exitCode: code,
+            sidecar: { file: UNIT_TABLE_FILE, says: 'Every unit this repo can run, and whether it blocks you' },
+        })
         if (!st.written) print(`WARN ${st.warn}`)
+        const units = writeUnitTable(root, { name: c.name, rows: gateInventory(root, c) })
+        if (!units.written) print(`WARN ${units.warn}`)
+
     }
     return code
 }

package/src/core/run-ci.ts

@@ -14,7 +14,8 @@ import { formatLine } from './wire.ts'
 import { runTasks, selectTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 import { withContractsScope } from '../contracts/contracts-once.ts'
-import { envTier, FULL_TESTS_ENV, gateUnits, type TestTier } from '../ledger/gate-units.ts'
+import { envTier, FULL_TESTS_ENV, gateInventory, gateUnits, tieredTasks, type TestTier } from '../ledger/gate-units.ts'
+import { UNIT_TABLE_FILE, writeUnitTable } from '../ledger/unit-table.ts'
 import { Ledger, stampReplayed, type UnitOutcome } from '../ledger/ledger.ts'
 
 export type CiOpts = {
@@ -294,8 +295,17 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     if (o.status !== false) {
         // scope is named in the file: ci proves the gate, not repo health, and
         // a bare GREEN here would claim clear-to-ship on a repo with red checks
-        const st = writeStatus(root, { name: c.name, ...ciScope(o), lines: collected, exitCode: code })
+        const st = writeStatus(root, {
+            name: c.name,
+            ...ciScope(o),
+            lines: collected,
+            exitCode: code,
+            sidecar: { file: UNIT_TABLE_FILE, says: 'Every unit this repo can run, and whether it blocks you' },
+        })
         if (!st.written) print(`WARN ${st.warn}`)
+        const units = writeUnitTable(root, { name: c.name, rows: gateInventory(root, c, tieredTasks(c, root, tier)) })
+        if (!units.written) print(`WARN ${units.warn}`)
+
     }
     if (o.json === true)
         print(JSON.stringify({ ok: summary.ok, interrupted: summary.interrupted, disabled, tasks: summary.results.map((r) => ({ ...r, lines: undefined })) }))

package/src/core/write-status.ts

@@ -18,6 +18,10 @@ export type StatusInput = {
     /** the run's printed lines (ANSI stripped here) */
     lines: string[]
     exitCode: number
+    /** a companion file this run also refreshed, named so a reader finds it.
+     *  Optional because a caller that does not write one must not advertise
+     *  a file that is not there. */
+    sidecar?: { file: string; says: string }
 }
 
 export type StatusOutcome = { written: boolean; warn?: string }
@@ -61,7 +65,7 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
 # ${s.name} status, ${stamp}
 
 **${verdict}**
-
+${s.sidecar == null ? '' : `\n${s.sidecar.says}: [${s.sidecar.file}](${s.sidecar.file})\n`}
 \`\`\`
 ${clean.join('\n').trim()}
 \`\`\`