rvlib-shipkit 0.35.7 → 0.36.0

package/CHANGELOG.md

@@ -1,9 +1,32 @@
 # Changelog
 
+## 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.
+- **`--only <check>` ran the check and then exited 1 saying it did not exist.** `selectTasks` validates the flag against the TASK list alone, so naming a discovered check or a rule ran it and still printed `unknown task id`. The flag addresses three surfaces, so the task runner is now handed the ids owned by the other two (rule ids, rule titles, check names, check paths). This is what makes the opt-out safe to use: a check taken off the gate stays reachable by name.
+- The `run-check.ts` comment on the release-survey share path no longer describes a pre-warm `runCi` deleted, and says who the single owner is.
+
 ## 0.35.7
 
 - **`shipkit ci` no longer pre-warms a release survey nothing in the gate reads.** `runCi` started `collectReports` next to the tasks and awaited it before the checks, to hide ~3s of npm registry and `gh` network behind the task DAG. Its only consumer was ever the lib-drift probe, which asks what is PUBLISHED and therefore belongs to `shipkit releases` and the bump gate rather than to a gate that asks whether this change is good. Measured on a repo whose drift checks had left the gate: warm no-op 4.3s with the pre-warm, 1.2s without. Deleted rather than made conditional, because nothing is left to condition it on and a second mechanism guessing which check wants a survey is exactly the source-sniffing this scanner already retired. `collectChecks` creates, shares and cleans up the share path when it was not handed one, so the checks that DO want a survey still pay for exactly one between them, and `shipkit check` is unchanged. Honest cost: a repo that keeps a lib-drift check inside its gate loses the overlap and is up to 3s slower there.
-- **`export const gate = false` was parsed, filtered on, and never honoured** (the fix itself shipped in 0.35.6, which carried no note for it). The CLI declares `--only` as `Option.Array('--only', [])`, so a plain `shipkit ci` hands the check filter an EMPTY ARRAY and never `undefined`. The guard tested `only == null`, which is false for `[]`, so every gate run read as a narrowed one and no check ever opted out: a repo could declare fifteen world probes off-gate and watch all fifteen run anyway. `matchesOnly`, two hundred lines up in the same file, already used the right predicate, and the `only` field's own doc comment already said "Empty or absent means everything". Both readers now call one exported `isNarrowed`, so `--only` has a single meaning and no second place to get it wrong. Pinned by three tests that call `collectChecks` the way the CLI calls it: the gate skips a `gate = false` check, `shipkit check` still runs it, and naming it in `--only` still reaches it.
+- **`export const gate = false` was parsed, filtered on, and never honoured** (the fix itself shipped in 0.35.6, which carried no note for it). The CLI declares `--only` as `Option.Array('--only', [])`, so a plain `shipkit ci` hands the check filter an EMPTY ARRAY and never `undefined`. The guard tested `only == null`, which is false for `[]`, so every gate run read as a narrowed one and no check ever opted out: a repo could declare fifteen world probes off-gate and watch all fifteen run anyway. `matchesOnly`, two hundred lines up in the same file, already used the right predicate, and the `only` field's own doc comment already said "Empty or absent means everything". Both readers of the CHECK filter now call one exported `isNarrowed`. `--only` also names rules and discovered checks, so the task runner is handed those ids too rather than answering `unknown task id` for a check it was never asked to run. Pinned by three tests that call `collectChecks` the way the CLI calls it: the gate skips a `gate = false` check, `shipkit check` still runs it, and naming it in `--only` still reaches it.
 - **The adopt path writes `.vscode/tasks.json` alone, and derives what goes in it.** 0.35.6 wrote `settings.json` too, which turns eslint off and hands formatting to an oxc extension: landing that in a repo that lints with eslint silences the linter that repo chose, and that is an answer only its own author gets to give. It also wrote a canned `👁  TSC` watcher pointed at `tsconfig.json`. Against a solution config (`files: []` plus `references`) that watcher needs `--build`, type checks ZERO files without it, and reports a clean problems pane forever, which is worse than no task at all. The TSC subtask is now written only when the root tsconfig resolves inputs, `build/vscode-tasks.md` stays the owner of the per-project analysis for every other watcher, and `init` names that page in its output rather than implying the file is finished.
 - **A symlinked `.vscode/` is left alone.** It is a dotfiles pattern pointing at a SHARED directory, and writing through it landed files outside the repo being wired.
 - **A `repo.config.ts` with no `name` no longer kills `init` with an opaque `TypeError`.** The config loader validates nothing and hands back the raw default export, and the port arithmetic iterates the name it is given. That resolution now sits inside the same guard as the write, falls back to the directory name, and a failure there costs one WARN after everything else has already landed.

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.7",
+    "version": "0.36.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'
 
@@ -78,15 +80,25 @@ export type CheckOpts = {
  *  one they last saw on the wire. */
 export function matchesOnly(only: string[] | undefined, ...names: string[]): boolean {
     if (!isNarrowed(only)) return true
-    return only!.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
+    return only.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
 }
 
 /** did the operator narrow this run? The ONE reading of `--only` everywhere: an
  *  empty list is not a selection, it is the absence of one. */
-export function isNarrowed(only: string[] | undefined): boolean {
+export function isNarrowed(only: string[] | undefined): only is string[] {
     return only != null && only.length > 0
 }
 
+/** every id `--only` can name that is NOT a task: rule ids, rule titles,
+ *  discovered check names and their repo-relative paths. `--only` addresses all
+ *  three surfaces, so the task runner has to be told which ids belong to the
+ *  other two, or it answers `unknown task id` for a check that does run. */
+export function checkSideIds(root: string, c: RepoConfig): string[] {
+    const ids = [...RULES, ...(c.rules ?? [])].flatMap((r) => [r.id, r.title])
+    for (const d of discoverChecks(root)) ids.push(d.name, relative(root, d.path))
+    return ids
+}
+
 export type CheckRun = {
     /** wire lines, with non-blocking failures already downgraded to warnings */
     lines: Line[]
@@ -194,12 +206,13 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
-    // ONE release survey for the whole run: five discovered checks call
-    // collectReports, each in its own subprocess, and the survey is ~4s of
+    // ONE release survey for the whole run: several discovered checks call
+    // collectReports, each in its own subprocess, and the survey is ~3s of
     // network. The path is per RUN and never reused across runs, so nothing
     // here can serve a stale answer to a later gate (releases-share.ts).
-    // a caller that already opened one (runCi, which starts the survey next to
-    // the tasks) owns it, cleanup included; otherwise this run owns its own
+    // This is the ONLY owner: nothing else in shipkit sets the variable, and an
+    // inherited one can only come from a caller outside the binary, which then
+    // owns its own cleanup.
     const inherited = process.env[SHARE_ENV]
     const sharePath = inherited != null && inherited !== '' ? inherited : join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
     const childEnv: Record<string, string | undefined> = {
@@ -279,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
 }