rvlib-shipkit 0.34.0 → 0.35.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.35.1
+
+- **SK013's green line claimed a replacement that could not be named.** With the guard declared but not yet installed, the rule WARNed correctly and then printed `closes 14/14 raw runner(s), with the replacement named` directly underneath it. Both lines were about the same file and only one of them was true. The summary now reports what the file actually delivers: the guard is `declared, not yet runnable` until its script resolves.
+
+## 0.35.0
+
+- **`shipkit pb collection` mints imports of a package that exists.** The pocketbase data layer and the Mantine shell are one package now, `rvlib-pb`: the generated `columns.tsx`, `grid.tsx` and `index.ts` import `Column`, `LiveGrid` and `defineCollectionUI` from `rvlib-pb/ui`, and `LiveList` from `rvlib-pb`. The two tiers are different subpaths on purpose, so a generated grid that took its type from the ui subpath would typecheck and would put `@mantine/core` in the tsconfig of anything that reads it. This generator ships inside the tarball and writes into repos it never sees, so a stale specifier here keeps producing broken scaffolds long after a rename lands: the suite now asserts every import string the generator emits, which nothing did before.
+
 ## 0.34.0
 
 - **SK013's autofix was manufacturing the FAIL its own lint then raised.** It wired a PreToolUse hook at `node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts` whether or not that path existed, so any repo that runs shipkit through the global shim without installing the package came out of a repair pass permanently red. A machine-clearable red that a machine just created is a design bug. The hook is still declared in every case, so it starts working the moment the dependency lands, with no second fix run: what changed is the verdict. A guard under `node_modules/` that is not there yet is an uninstalled dependency, so it WARNs and names `bun install`, with the deny list standing as the whole floor meanwhile. A guard path the repo chose and got wrong still FAILs, because that one never resolves on its own.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.34.0",
+    "version": "0.35.1",
     "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",
     "type": "module",

package/src/cli/cmd_Ci.ts

@@ -16,6 +16,7 @@ export class CiCommand extends Command {
             ['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'],
         ],
     })
@@ -28,6 +29,7 @@ export class CiCommand extends Command {
     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' })
     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` })
 
     async execute(): Promise<number> {
@@ -45,6 +47,7 @@ export class CiCommand extends Command {
                 skipGroups: this.skip,
                 withIds: this.withIds,
                 onlyIds: this.only,
+                fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
                 print: (l) => this.context.stdout.write(`${l}\n`),
             })

package/src/cli/cmd_Keys.ts

@@ -8,7 +8,7 @@
 import { createHash } from 'crypto'
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
-import { gateUnits } from '../ledger/gate-units.ts'
+import { envTier, FULL_TESTS_ENV, gateUnits, tieredTasks } from '../ledger/gate-units.ts'
 import { KeyLayer } from '../ledger/git-key.ts'
 
 export class KeysCommand extends Command {
@@ -22,6 +22,7 @@ export class KeysCommand extends Command {
             ['only the ones nothing can cache yet', 'shipkit keys --burn-down'],
             ['why this key is what it is', 'shipkit keys --why typecheck'],
             ['re-hash after the fact and report drift', 'shipkit keys --rescan'],
+            ['the keys a --full gate asks for', 'shipkit keys --full'],
             ['machine-readable', 'shipkit keys --json'],
         ],
     })
@@ -29,19 +30,24 @@ 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' })
+    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' })
 
     async execute(): Promise<number> {
         const root = process.cwd()
         const c = await loadRepoConfig(root)
-        const decls = gateUnits(root, c)
+        // the TIER the gate would run, applied here too: `--full` rewrites
+        // 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 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({ 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, units: 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
         }
 
@@ -90,7 +96,7 @@ export class KeysCommand extends Command {
         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) · key layer ${Math.round(layer.openMs)}ms, of which ${Math.round(layer.scanMs)}ms of git`)
+        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`)
         if (todo > 0 && !this.burnDown) out(`      the burn-down: shipkit keys --burn-down`)
 
         if (this.rescan) {

package/src/core/check-suite.ts

@@ -6,56 +6,23 @@
 // WARN/FAIL evict. Busts: version bump, secret rotation (key hashes the
 // secret value), `<freshEnv>=1`.
 //
-// STORAGE: one immutable file per (check, version, cache key), under
-// `<cacheDir>/<suite>/`. Three agents in one checkout is the normal case, so
-// there is no shared file to lose a write to: a run with a different key
-// writes a DIFFERENT file, a run with the same key replaces its own by tmp +
-// rename (whole answer or nothing, never half), and nothing is pruned,
-// because pruning by "the checks I know about" deletes the entries of a
-// runner that narrowed itself with --only. It replaced one aggregate JSON
-// read at the top of the run and rewritten at the bottom, which lost every
-// entry another runner wrote in between and served a torn read as an empty
-// cache.
+// STORAGE is not this module's concern any more: ledger/store.ts owns the
+// one store, its shape, and its housekeeping (one immutable file per key,
+// tmp + rename, age-based sweep). This is the WORLD half of the three
+// populations — an answer nothing on disk describes, remembered for a TTL and
+// busted by rotation. The CONTENT half is keyed instead of timed and lives in
+// ledger/ledger.ts. Same store, different key.
 //
 // Secret VALUES never enter this module's state beyond the injected
 // getSecret call + a truncated hash for cache-busting.
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
-import { dirname, join } from 'path'
+import { existsSync } from 'fs'
 import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
-import { atomicWrite } from './locked-write.ts'
+import { dropStored, entryPath, FRESH_ENV, readStored, sweepStore, writeStored } from '../ledger/store.ts'
 import { fmtStamp, formatLine, parseDuration, type Line } from './wire.ts'
 
 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 }
-type CacheEntry = { version: number; key: string; at: number; lines: Line[] }
-
-/** a missing or half-written file reads as "no answer", which is the safe
- *  side: the check runs. tmp + rename means half-written cannot happen from a
- *  shipkit write, so this only ever catches a truncated file from something
- *  else, and treats it the same way. */
-const readEntry = (path: string): CacheEntry | null => {
-    try {
-        const e = JSON.parse(readFileSync(path, 'utf8')) as Partial<CacheEntry>
-        return Array.isArray(e.lines) && typeof e.at === 'number' && typeof e.version === 'number' && typeof e.key === 'string' ? (e as CacheEntry) : null
-    } catch { return null }
-}
-
-const writeEntry = (path: string, e: CacheEntry): void => {
-    try {
-        mkdirSync(dirname(path), { recursive: true })
-        atomicWrite(path, JSON.stringify(e))
-    } catch {
-        // a cache that cannot be written is slow, never wrong: the answer was
-        // already printed, and the next run measures again
-    }
-}
-
-const slug = (s: string): string => s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 60)
-
-/** how long a superseded key's file survives. Far past the longest TTL any
- *  check declares, so a live entry is never swept out from under a replay. */
-const SUPERSEDED_KEEP_MS = 30 * 24 * 60 * 60 * 1000
 
 export type GetSecret = (name: string, field: 'get' | 'account') => string | null
 
@@ -66,15 +33,19 @@ export type SecretSpec = {
     skipHint: string
 }
 
-export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean }
+export type CheckOutcome = { lines: Line[]; status: 'pass' | 'fail' | 'warn' | 'skip'; cached: boolean; /** wall time of the LOGIC, ms — 0 on a replay, since a replay measured nothing */ ms: number }
 
 export type CheckSuiteOpts = {
     name: string
-    cacheDir: string
+    /** the ONE store root (ledger/store.ts storeRoot). Injected rather than
+     *  resolved here so a test can point a suite at a scratch dir. */
+    storeDir: string
     now?: () => number
     /** secret backend — consumers inject their own store; default = nothing stored, every secret check skips */
     getSecret?: GetSecret
-    /** env var that busts the cache when set (consumer names it) */
+    /** TEST SEAM: the env var that busts this suite's replays. Production is
+     *  always the one house-wide flag (ledger/store.ts FRESH_ENV); a test
+     *  overrides it so busting one suite cannot poison a neighbour's run. */
     freshEnv?: string
     /** per-check completion tap (the TUI streams results in) — cached replays
      *  report cached:true, prep-skips (unstored secret) report status 'skip' */
@@ -85,7 +56,7 @@ export class CheckSuite {
     readonly name: string
     private runners: Runner[] = []
     private toolPaths = new Map<string, string>()
-    private cacheDir: string
+    private storeDir: string
     private now: () => number
     private getSecret: GetSecret
     private freshEnv: string
@@ -93,10 +64,10 @@ export class CheckSuite {
 
     constructor(opts: CheckSuiteOpts) {
         this.name = opts.name
-        this.cacheDir = opts.cacheDir
+        this.storeDir = opts.storeDir
         this.now = opts.now ?? Date.now
         this.getSecret = opts.getSecret ?? (() => null)
-        this.freshEnv = opts.freshEnv ?? 'SHIPKIT_FRESH'
+        this.freshEnv = opts.freshEnv ?? FRESH_ENV
         this.onResult = opts.onResult
     }
 
@@ -166,32 +137,12 @@ export class CheckSuite {
         })
     }
 
-    /** the key is in the file name, so a check whose key moves leaves its old
-     *  file behind forever. A rule keyed on installed versions writes one per
-     *  upgrade, so the dir accretes without bound in a repo nobody clears.
-     *  Sweeping by AGE needs no knowledge of the current check set, which is
-     *  what made the old prune wrong: a run narrowed by --only knows about one
-     *  check and would have deleted the other twenty four. */
-    private sweepSuperseded(): void {
-        const dir = join(this.cacheDir, slug(this.name))
-        const cutoff = this.now() - SUPERSEDED_KEEP_MS
-        try {
-            for (const f of readdirSync(dir)) {
-                if (!f.endsWith('.json')) continue
-                const p = join(dir, f)
-                try { if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true }) } catch { /* raced with another runner: it is gone either way */ }
-            }
-        } catch {
-            // no dir yet, or unreadable: housekeeping never fails a run
-        }
-    }
-
-    /** where this check's answer for THIS key lives. The key is in the file
-     *  NAME, so a run whose key moved writes a new file rather than rewriting
-     *  the old one, and two runners with different keys never collide. */
-    private entryPath(r: Runner, key: string): string {
-        const h = new Bun.CryptoHasher('sha256').update(`${r.name}\0${r.version}\0${key}`).digest('hex').slice(0, 12)
-        return join(this.cacheDir, slug(this.name), `${slug(r.name)}.${h}.json`)
+    /** the key a world answer is remembered under: the check's own version
+     *  plus whatever the prep declared (a secret's value hash, a rule's
+     *  cacheKey). A version bump and a rotation both move it, so neither can
+     *  replay across the change. */
+    private cacheKey(r: Runner, extra: string): string {
+        return `v${r.version}\0${extra}`
     }
 
     // test seam — run() prints + exits; execute() returns the structured result
@@ -201,15 +152,14 @@ export class CheckSuite {
     private async runOne(r: Runner): Promise<{ lines: Line[]; skip: string | null; ran: boolean; failed: boolean }> {
         const prep = r.prep?.() ?? {}
         if (prep.skip != null) {
-            this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false })
+            this.onResult?.(r.name, { lines: [{ kind: 'skip', text: prep.skip }], status: 'skip', cached: false, ms: 0 })
             return { lines: [], skip: prep.skip, ran: false, failed: false }
         }
-        const key = prep.cacheExtra ?? ''
-        const entryPath = this.entryPath(r, key)
-        const entry = readEntry(entryPath)
+        const key = this.cacheKey(r, prep.cacheExtra ?? '')
+        const path = entryPath(this.storeDir, this.name, r.name, key)
+        const entry = readStored<Line[]>(path, key)
         const fresh = r.ttlMs > 0 && process.env[this.freshEnv] == null
-            && entry != null && entry.version === r.version && entry.key === key
-            && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
+            && entry != null && this.now() - entry.at < r.ttlMs && 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
@@ -219,11 +169,12 @@ export class CheckSuite {
             // alternation, so neither side annotates
             // a replayed WORLD negative keeps its severity: it is still the
             // answer, and demoting it to a pass would hide a real finding
-            const replayedWarn = entry.lines.some((l) => l.kind === 'warn' || l.kind === 'fail')
-            this.onResult?.(r.name, { lines: entry.lines, status: replayedWarn ? 'warn' : 'pass', cached: true })
-            return { lines: entry.lines, skip: null, ran: true, failed: false }
+            const replayedWarn = entry.payload.some((l) => l.kind === 'warn' || l.kind === 'fail')
+            this.onResult?.(r.name, { lines: entry.payload, status: replayedWarn ? 'warn' : 'pass', cached: true, ms: 0 })
+            return { lines: entry.payload, skip: null, ran: true, failed: false }
         }
         const t = new CheckCtx(this.toolPaths)
+        const started = performance.now()
         try {
             await r.logic(t)
         } catch (e) {
@@ -260,29 +211,23 @@ export class CheckSuite {
         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
-        this.onResult?.(r.name, { lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
+        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) writeEntry(entryPath, { version: r.version, key, at: this.now(), lines })
+            if (cacheable) writeStored(path, key, lines, this.now())
             // 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
             // file a moment ago and lose it here, which costs one re-probe and
             // can never produce a stale green, so it is the safe direction.
-            else if (entry != null) rmSync(entryPath, { force: true })
+            else if (entry != null) dropStored(path)
         }
         return { lines, skip: null, ran: true, failed: t.failed }
     }
 
     async execute(): Promise<{ lines: Line[]; exitCode: number }> {
-        // the aggregate file this replaced. Deleting it here is the migration:
-        // nothing reads it any more, and leaving it would have a future reader
-        // believe there are two cache layers. DIES when every consumer repo is
-        // past rvlib-shipkit 0.34.0, since after that no tree can still carry
-        // one; it costs an unlink of a path that is not there.
-        rmSync(join(this.cacheDir, `${this.name}.json`), { force: true })
-        this.sweepSuperseded()
+        sweepStore(this.storeDir, this.name, this.now())
 
         // CONCURRENT, bounded. Checks are independent by contract: each answers
         // one question about the world or the repo and shares nothing with its

package/src/core/discover-checks.ts

@@ -17,8 +17,6 @@ export type DiscoveredCheck = {
     path: string
     /** display + cache name — file base, disambiguated by relative path on collision */
     name: string
-    /** file runs its own CheckSuite (own TTL cache) — the orchestrator must not double-cache it */
-    selfCached: boolean
     /** `export const blocking = true | false`, read statically. null = the file
      *  never said, which is an error: a check that silently does not block is
      *  the failure nobody sees. */
@@ -34,6 +32,12 @@ export type DiscoveredCheck = {
     /** `export const never = 'why'`, read statically — a DECIDED never
      *  cacheable, which takes the check off the burn-down list. */
     never: string | null
+    /** `export const gate = false`, read statically — this check is NOT part of
+     *  `shipkit ci`. `ci` answers "is my change good"; a check that answers
+     *  something else, and that can sit red for months without anything being
+     *  wrong, does not belong in the answer. `shipkit check` still runs it.
+     *  Default true: a check is in the gate unless it opts out by name. */
+    gate: boolean
 }
 
 // read without importing: checks run as subprocesses, and discovery must stay
@@ -46,6 +50,10 @@ const BLOCKING_RE = /^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(tru
 const INPUTS_RE = /^\s*export\s+const\s+inputs\s*(?::[^=]*)?=\s*\[([^\]]*)\]/m
 const TTL_RE = /^\s*export\s+const\s+ttl\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
 const NEVER_RE = /^\s*export\s+const\s+never\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
+// `export const gate = false` takes a check out of `shipkit ci`. Only the
+// literal false opts out: anything unreadable stays in the gate, because a
+// scanner that guesses its way to SKIPPING a check is how coverage disappears
+const GATE_RE = /^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false\s*$/m
 const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
 
 export function discoverChecks(root: string): DiscoveredCheck[] {
@@ -67,16 +75,13 @@ export function discoverChecks(root: string): DiscoveredCheck[] {
     return files.map((f) => {
         const base = baseOf(f)
         const name = (seen.get(base) ?? 0) > 1 ? relative(root, f).slice(0, -SUFFIX.length) : base
-        // a check built on CheckSuite/PageValidator replays from its OWN
-        // TTL cache — caching it again up here would double the staleness
-        let selfCached = false
         let blocking: boolean | null = null
         let inputs: string[] | null = null
         let ttl: string | null = null
         let never: string | null = null
+        let gate = true
         try {
             const src = readFileSync(f, 'utf8')
-            selfCached = /PageValidator|CheckSuite/.test(src)
             const m = src.match(BLOCKING_RE)
             blocking = m == null ? null : m[1] === 'true'
             const im = src.match(INPUTS_RE)
@@ -86,7 +91,8 @@ export function discoverChecks(root: string): DiscoveredCheck[] {
             }
             ttl = src.match(TTL_RE)?.[1] ?? null
             never = src.match(NEVER_RE)?.[1] ?? null
+            gate = src.match(GATE_RE) == null
         } catch {}
-        return { path: f, name, selfCached, blocking, inputs, ttl, never }
+        return { path: f, name, blocking, inputs, ttl, never, gate }
     })
 }

package/src/core/floor.ts

@@ -84,18 +84,27 @@ export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     for (const id of FLOOR_IDS) {
         const override = c.defaults?.[id]
         if (override === false) { disabled.push(id); continue }
-        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
+        // a FULL override brings its own body and replaces the slot. One that
+        // brings none DECORATES whatever fills it, which is how a repo declares
+        // what its `test` script reads without restating the command: the read
+        // set is repo knowledge, the command is not.
+        if (override != null && (override.cmd != null || override.logic != null)) {
+            tasks.push({ ...override, id: override.id ?? id } as TaskDef)
+            sources[id] = 'repo.config override'
+            continue
+        }
         // ONE WAY IN: `<id>` routes to `shipkit ci --only <id>`, so the TOOL
         // body lives at `<id>:raw` and that is what the gate runs. Running the
         // routed script here would spawn the gate from inside itself, forever
+        const decorate = (t: TaskDef): TaskDef => (override == null ? t : { ...t, ...override, id })
         const raw = scripts[rawName(id)]
-        if (raw != null) { tasks.push({ id, cmd: ['bun', 'run', rawName(id)] }); sources[id] = 'package.json script'; continue }
-        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
+        if (raw != null) { tasks.push(decorate({ id, cmd: ['bun', 'run', rawName(id)] })); sources[id] = 'package.json script'; continue }
+        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push(decorate({ id, cmd: ['bun', 'run', id] })); sources[id] = 'package.json script'; continue }
         const b = builtinFloorTask(id, root)
         // a routed script with nothing behind it measures NOTHING, and the
         // reason must say that rather than `no '<id>' script`, which is false
         if (typeof b === 'string') unfilled.push({ id, reason: scripts[id] != null ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })
-        else { tasks.push(b.task); sources[id] = b.source }
+        else { tasks.push(decorate(b.task)); sources[id] = b.source }
     }
     return { tasks, disabled, unfilled, sources }
 }

package/src/core/motherhome.ts

@@ -24,6 +24,58 @@ type Row = { name: string; root: string; version: string; mode: string; seen: st
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
+const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
+    const r = Bun.spawnSync(['git', ...args], { cwd })
+    return { ok: r.exitCode === 0, out: `${r.stdout.toString()}${r.stderr.toString()}`.trim() }
+}
+
+/**
+ * Commit the row we just wrote, and ONLY that file.
+ *
+ * This page is machine written and rewrites whenever a repo's shipkit version
+ * or consumption mode changes, so left alone it dirties the docs repo from a
+ * gate run nobody associates with it, and the dirt then rides into an unrelated
+ * commit or blocks a release. The row is not worth a human's attention in
+ * either direction, so the machine that writes it also lands it.
+ *
+ * Scoped hard, because several agents share this checkout:
+ * - `git commit -- <path>` takes the WORKING TREE version of that one path and
+ *   never reads the index, so a neighbour's staged work cannot ride along.
+ * - it refuses mid merge, mid rebase, on a detached HEAD, and before the first
+ *   commit, where an automatic commit is never what anyone wants.
+ * - it never pushes. Visibility is the human's call.
+ * - the hooks run, as they do for any commit. They are text checks of about a
+ *   second, and this fires only when the row's DATA changed, not every gate.
+ *
+ * Never throws and never fails the calling command: a registry row is not worth
+ * a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
+ */
+function autoCommitRow(page: string, name: string): string {
+    if (process.env['SHIPKIT_NO_AUTOCOMMIT'] === '1') return ''
+    try {
+        const dir = resolve(page, '..')
+        const top = git(dir, ['rev-parse', '--show-toplevel'])
+        if (!top.ok) return '' // the docs tree is not a git repo, nothing to land
+        const root = top.out
+        // a detached HEAD or a repo with no commit yet has nowhere sane to land
+        if (!git(root, ['symbolic-ref', '--quiet', 'HEAD']).ok) return ''
+        if (!git(root, ['rev-parse', '--verify', 'HEAD']).ok) return ''
+        for (const f of ['MERGE_HEAD', 'REBASE_HEAD', 'CHERRY_PICK_HEAD'])
+            if (existsSync(join(root, '.git', f))) return ''
+        const rel = page.startsWith(`${root}/`) ? page.slice(root.length + 1) : page
+        // one retry: a neighbour committing right now holds index.lock
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const r = git(root, ['commit', '-m', `chore(machine): refresh local-projects row (${name})`, '--', rel])
+            if (r.ok) return ' + committed'
+            if (!r.out.includes('index.lock')) return ''
+            Bun.sleepSync(300)
+        }
+        return ''
+    } catch {
+        return ''
+    }
+}
+
 const parseRow = (line: string): Row | null => {
     const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
@@ -90,7 +142,8 @@ export function reportToMotherhome(root: string, config: RepoConfig, today: stri
             // prune rows for repos that no longer exist at their recorded path
             const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
             atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
-            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})` }
+            const committed = autoCommitRow(page, me.name)
+            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})${committed}` }
         })
         // lock lost to a racing reporter — self-heals on the next run
         return r.ok ? r.value : { wrote: false }