rvlib-shipkit 1.8.0 → 2.0.0

package/src/core/pre-commit-discovery.ts

@@ -0,0 +1,106 @@
+// discovery for the pre-commit gate: import ONLY the check files that run a
+// body at commit. Full discovery imports every check file to read one field,
+// and a repo file that imports heavy modules at its top level then costs every
+// commit, seconds once its sources moved since the last transpile.
+//
+// A table beside the per worktree git dir remembers, per file, whether it
+// declares `onPreCommit`, keyed on the file's mtime and size. A file whose
+// stamp still matches and that runs nothing at commit is never imported. A
+// file that moved is imported again, and every import is timed, so a slow
+// one is named on the commit that pays for it.
+//
+// The stamp is the file's own: a check that takes its `runs` from another
+// module is re-read when its own file moves, or when the table is dropped.
+import { mkdirSync, readFileSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { gitRoot } from './git-root.ts'
+import { atomicWrite } from './locked-write.ts'
+import { BUILTIN_CHECK_DIR, discoverChecks, type DiscoveredCheck } from './discover-checks.ts'
+
+/** a repo check file whose import takes longer than this, warm, is named */
+export const SLOW_IMPORT_MS = 30
+
+const TABLE_VERSION = 1
+
+type Row = { stamp: string; preCommit: boolean }
+type Table = { v: number; files: Record<string, Row> }
+
+export const declarationsTable = (root: string): string | null => {
+    const dir = gitRoot(root)?.gitDir
+    return dir == null ? null : join(dir, 'shipkit', 'check-declarations.json')
+}
+
+function readTable(path: string | null): Table {
+    if (path == null) return { v: TABLE_VERSION, files: {} }
+    try {
+        const t = JSON.parse(readFileSync(path, 'utf8')) as Table
+        if (t.v === TABLE_VERSION && t.files != null && typeof t.files === 'object') return t
+    } catch {}
+    return { v: TABLE_VERSION, files: {} }
+}
+
+const stampOf = (path: string): string | null => {
+    try {
+        const s = statSync(path)
+        return `${s.mtimeMs}:${s.size}`
+    } catch {
+        return null
+    }
+}
+
+export type PreCommitDiscovery = {
+    /** what discovery returns, minus the files the table skipped */
+    checks: DiscoveredCheck[]
+    /** repo check files whose import took longer than SLOW_IMPORT_MS */
+    slow: { path: string; ms: number }[]
+    /** how many files were imported, and how many the table skipped */
+    imported: number
+    skipped: number
+}
+
+export async function discoverPreCommit(root: string): Promise<PreCommitDiscovery> {
+    const path = declarationsTable(root)
+    const table = readTable(path)
+    const stamps = new Map<string, string | null>()
+    const stamp = (f: string): string | null => {
+        if (!stamps.has(f)) stamps.set(f, stampOf(f))
+        return stamps.get(f) ?? null
+    }
+    let changed = false
+    let skipped = 0
+    let imported = 0
+    const slow: { path: string; ms: number }[] = []
+    const checks = await discoverChecks(root, {
+        skip: (f) => {
+            const row = table.files[f]
+            const hit = row != null && !row.preCommit && row.stamp === stamp(f)
+            if (hit) skipped++
+            return hit
+        },
+        imported: (f, ms, def, loaded) => {
+            imported++
+            if (!f.startsWith(`${BUILTIN_CHECK_DIR}/`) && ms > SLOW_IMPORT_MS) slow.push({ path: f, ms })
+            const s = stamp(f)
+            // a file that did not load is asked again next time: its error is
+            // the gate's to show, never the table's to remember
+            if (!loaded || s == null) return
+            const row: Row = { stamp: s, preCommit: def != null && def.runs.onPreCommit !== false }
+            const prev = table.files[f]
+            if (prev?.stamp === row.stamp && prev.preCommit === row.preCommit) return
+            table.files[f] = row
+            changed = true
+        },
+    })
+    if (changed && path != null) {
+        // a row whose file is gone is dropped, so the table never outgrows the repo
+        for (const f of Object.keys(table.files)) if (stamp(f) == null) delete table.files[f]
+        try {
+            mkdirSync(dirname(path), { recursive: true })
+            atomicWrite(path, JSON.stringify(table))
+        } catch {
+            // a table that cannot be written costs the next commit the full
+            // import, never its answer
+        }
+    }
+    return { checks, slow, imported, skipped }
+}

package/src/core/retired-checks.ts

@@ -2,6 +2,8 @@
 // id is never reused, so a doc or a changelog may still name one, and
 // discovery refuses a built-in that takes one again.
 export const RETIRED_CHECK_IDS: Readonly<Record<string, string>> = {
+    SK009: 'the AI attribution guard is gone: no rule polices commit trailers',
+    SK014: 'the STE prose rule is gone: no rule polices prose style',
     SK021: "the gh login is a machine fact: the house repo's github-login check runs src/core/gh-login.ts",
     SK023: "the store caps are the machine daemon's health: the house repo's stores-under-cap check",
 }

package/src/core/run-ci.ts

@@ -10,6 +10,7 @@ import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { passScope, runCheckPass, type CheckOpts } from './run-check.ts'
 import { poolLines } from './slots.ts'
+import { fixPassRuns } from './fix-scope.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { outcomeCounts } from './outcome-words.ts'
@@ -29,8 +30,9 @@ export type CiOpts = {
     onlyIds?: string[]
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
-    /** repair the mechanical slots before gating. default on locally, verify
-     *  mode under CI. core/run-fixers.ts owns the scope. */
+    /** repair the mechanical slots before gating, verify mode under CI.
+     *  Unset: on for a whole gate, off for a narrowed one (core/fix-scope.ts).
+     *  core/run-fixers.ts owns the scope. */
     fix?: boolean
     /** also apply the repairs of the checks declaring `fix: 'ci'` during the
      *  fix pass */
@@ -135,19 +137,22 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // what the reader never acts on: kept for STATUS.md and --verbose, never
     // printed on a default run, where every line costs a reader tokens
     const detail = (l: string): void => { collected.push(l); if (o.verbose === true) print(l) }
+    // a check that answered green says nothing a reader acts on: the verdict
+    // counts it. What needs a reader (a WARN, a FAIL and its fix, a wait for a
+    // machine slot) always prints
+    const checkLine = (l: string): void => (/^(ok|skip): /.test(l) && !/^ok: waiting\b/.test(l) ? detail : sink)(l)
     let c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
-    // a NARROWED run repairs only the mechanical slots. The structural rule
-    // fixers rewrite package.json and repo config, and arming rewrites hooks/:
-    // that is the right price for the full gate and the wrong one for
-    // `bun run test`, which routes here and must answer the one question its
-    // name promises without leaving files in the agent's diff that it never
-    // wrote. Under CI it is worse than surprising: a formatting rewrite comes
-    // back as a test failure.
+    // a NARROWED run repairs nothing unless --fix asks, and even then only
+    // what the named checks own: their own ci repair and the fixer slot that
+    // governs one of them. `bun run test` routes here and must answer the one
+    // question its name promises without leaving files in the agent's diff
+    // that it never wrote: in a shared tree a tree wide fixer rewrites every
+    // other agent's files too. Arming rewrites hooks/: the full gate's price alone
     const narrowed = (o.onlyIds ?? []).length > 0
-    if (o.fix !== false) {
-        const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail })
+    if (fixPassRuns(o)) {
+        const pass = await runFixPass(root, c, { rules: o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail, ...(narrowed ? { only: o.onlyIds } : {}) })
         fixFailed = pass.failed
         // a fixer that rewrote the config or moved a check file leaves the
         // config above describing a repo that is gone, so the gate reads the
@@ -158,7 +163,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
                 return 1
             }
         }
-    } else detail('skip: fix pass (--no-fix)')
+    } else detail(o.fix === false ? 'skip: fix pass (--no-fix)' : 'skip: fix pass (a --only run leaves the tree alone, --fix repairs first)')
     const tier: TestTier = o.tests ?? envTier()
     // announced BEFORE the run (under --verbose, and in every release log),
     // so a log that died mid-way still says which tier it was asking for
@@ -178,7 +183,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         // the harness refused it the raw runner, so the line says what to add
         // rather than leaving it with `unknown check id` and no next move
         if ((o.onlyIds ?? []).includes(u.id))
-            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
+            sink(u.id === 'lint'
+                ? `      fix: add a [lint] section to bunfig.toml, then \`shipkit ci --only lint\` runs \`bun lint\` (build/typescript.md)`
+                : `      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
     }
     // the run record: one run id for every check of this gate, so a breakdown
     // of the wall time is reconstructable. It is never read here, only written
@@ -251,7 +258,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         runLog,
         onCheck: o.onCheck,
         reportHome: false,
-        print: sink,
+        print: checkLine,
         detail,
     })
     // what the suite ACTUALLY ran, from its own headline. A flag that was set
@@ -288,10 +295,10 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
         // why every check that did not replay ran, grouped: a re-run nobody
         // can explain costs a reader more than the line does
-        for (const { line, quiet } of ledger.explain()) (quiet ? detail : sink)(formatLine(line, false))
+        for (const { line } of ledger.explain()) detail(formatLine(line, false))
     }
     // one write for the whole gate, after everything has finished
-    for (const l of runLog.flush()) sink(formatLine(l, false))
+    for (const l of runLog.flush()) checkLine(formatLine(l, false))
     const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownOff.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     // THE VERDICT, one line and only on a pass: a red run already said so in
     // its FAIL lines. The whole gate adds the tier and the cache counts, which

package/src/core/run-fix.ts

@@ -15,6 +15,10 @@ import type { RepoConfig } from '../repo-config.ts'
 
 export type FixOpts = {
     ids?: string[]
+    /** the gate's `--only` names: of the ci repairs, only the ones these
+     *  name, by check id or by group, and silently none for a name that has
+     *  no repair */
+    scope?: string[]
     /** drop the closing advisory: inside the ci fix pass it is noise, and it is
      *  not wire-shaped, which the frozen output contract forbids */
     quiet?: boolean
@@ -55,6 +59,11 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
 
     // no ids: the repairs declared for the gate. A manual one runs by name
     let targets = all.filter((r) => r.fix != null && r.when === 'ci')
+    if (o.scope != null) {
+        const named = new Set(o.scope)
+        const groups = new Map((await gateInventory(root, config)).map((r) => [r.decl.id, r.group]))
+        targets = targets.filter((r) => named.has(r.id) || named.has(groups.get(r.id) ?? ''))
+    }
     if (o.ids != null && o.ids.length > 0) {
         for (const id of o.ids) {
             const r = all.find((x) => x.id === id)

package/src/core/run-fixers.ts

@@ -1,20 +1,20 @@
 // what `shipkit ci` repairs before it gates.
 //
-// mechanical slots only (formatter, import canonicaliser): they rewrite the
-// files the agent is already editing and their output is total. structural
-// SK rule fixers rewrite repo config, so they stay behind --fix-rules.
+// mechanical slots only (the import canonicaliser): it rewrites the files the
+// agent is already editing and its output is total. structural SK rule fixers
+// rewrite repo config, so they stay behind --fix-rules. no formatter runs
+// here: formatting is a manual `bun fmt`, never a gate step.
 //
 // under CI the same fixers run in verify mode instead: a gate that silently
 // rewrites the tree it checks can turn red green with no commit. one
-// mechanism, two modes, rather than a formatter plus a format:check that
-// drift apart.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+// mechanism, two modes, rather than a fixer plus a check that drift apart.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { dirname, isAbsolute, join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { runFix } from './run-fix.ts'
-import { routesToShipkit } from './canonical-scripts.ts'
+import { repoOff } from './when.ts'
 import { discoverLegacyChecks } from './discover-legacy-checks.ts'
 import { repoCheckFiles } from './discover-checks.ts'
 import { mutateLease, withMutateLease } from './locked-write.ts'
@@ -24,6 +24,8 @@ import { spawnWithTimeout } from './spawn-timeout.ts'
 import { gitBin } from './git-bin.ts'
 import { LAYOUT } from './layout.ts'
 import { gateBinary, toolchainIdentity } from '../ledger/toolchain-identity.ts'
+import { isVendored } from './vendored.ts'
+import { readVendored } from './vendored-read.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
 
@@ -35,8 +37,6 @@ export type FixerSlot = {
 
 export type FixerResolution = {
     slots: FixerSlot[]
-    /** slots nothing could fill, printed, never silent */
-    unfilled: { id: string; reason: string }[]
     /** slots the repo turned off, printed with the same vocabulary the task
      *  side uses, so a disable is never invisible in the output */
     disabled: { id: string; reason: string }[]
@@ -47,10 +47,6 @@ export type FixerResolution = {
 // anyway is the config saying one thing and the tool doing another.
 const GOVERNED_BY: Record<string, string> = { 'imports:fix': 'imports:check' }
 
-// one fixer per mechanical concern. `fmt` accepts the two names the house
-// vocabulary allows so a repo that calls it `format` is not silently unfixed.
-const FMT_SCRIPTS = ['fmt', 'format'] as const
-
 export function resolveFixers(root: string, config?: RepoConfig): FixerResolution {
     const pkgPath = join(root, 'package.json')
     let scripts: Record<string, string> = {}
@@ -59,31 +55,23 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
         catch (e) { throw new Error(`package.json unparseable — fixers cannot register: ${String(e).slice(0, 120)}`) }
     }
     const slots: FixerSlot[] = []
-    const unfilled: { id: string; reason: string }[] = []
     const disabled: { id: string; reason: string }[] = []
     const offByConfig = (id: string): boolean => {
         const governing = GOVERNED_BY[id]
         if (governing == null) return false
-        if (config?.defaults?.[governing] !== false) return false
-        disabled.push({ id, reason: `skipped-by-config (defaults: { '${governing}': false })` })
+        const off = config == null ? null : repoOff(config, governing)
+        if (off == null) return false
+        disabled.push({ id, reason: `skipped-by-config (${governing} is off: ${off.reason})` })
         return true
     }
 
-    // `fmt` is the one slot the fix pass invokes BY SCRIPT, so it is the one
-    // name ONE WAY IN deliberately leaves raw: a routed body here would make
-    // the fixer spawn the gate that spawns the fixer
-    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null && !routesToShipkit(scripts[n]!))
-    if (fmtName != null) slots.push({ id: 'fmt', cmd: ['bun', 'run', fmtName], source: 'package.json script' })
-    else if (FMT_SCRIPTS.some((n) => scripts[n] != null)) unfilled.push({ id: 'fmt', reason: `the 'fmt' script routes back to shipkit — the fix pass runs it, so it holds the formatter itself` })
-    else unfilled.push({ id: 'fmt', reason: `no 'fmt' or 'format' script — formatting stays a manual step` })
-
     if (offByConfig('imports:fix')) { /* the repo said no, in the one place that governs both directions */ }
     else if (scripts['imports:fix'] != null) slots.push({ id: 'imports:fix', cmd: ['bun', 'run', 'imports:fix'], source: 'package.json script' })
     else {
         const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
         slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (shipkit)' })
     }
-    return { slots, unfilled, disabled }
+    return { slots, disabled }
 }
 
 /** worktree fingerprint: every dirty path mapped to its CONTENT hash, or null
@@ -101,10 +89,9 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
  *  bytes attributes only what a fixer can actually have done.
  *
  *  It watches the WHOLE tree on purpose. A narrower porcelain was tried and
- *  deleted: the only fixer whose targets are declarable is the formatter, and
- *  the same pass also runs the rule fixers, which rewrite package.json,
- *  .gitignore, CLAUDE.md and .claude/, none of them inside a formatter's
- *  scope. Narrowing to the formatter's paths therefore hid real rewrites from
+ *  deleted: the same pass also runs the rule fixers, which rewrite
+ *  package.json, .gitignore, CLAUDE.md and .claude/, none of them inside a
+ *  source fixer's scope. Narrowing to the fixers' paths therefore hid real rewrites from
  *  the verify mode, which is a silent green on a tree a fixer changed. What
  *  actually stops another agent's work being reported here is the lease plus
  *  the byte comparison, not a path list. */
@@ -125,6 +112,50 @@ function treeState(root: string): Map<string, string> | null {
     return m
 }
 
+/** the vendored files whose work tree differs from the index, each with its
+ *  bytes (null when deleted). One pathspec limited diff, paths relative to
+ *  `root` even in a nested repo, so a repo with no vendored dir costs nothing */
+function vendoredState(root: string, dirs: readonly string[]): Map<string, Buffer | null> {
+    const m = new Map<string, Buffer | null>()
+    if (dirs.length === 0) return m
+    const p = Bun.spawnSync([gitBin(), 'diff', '--name-only', '--relative', '-z', '--', ...dirs], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    if (p.exitCode !== 0) return m
+    for (const path of p.stdout.toString().split('\0')) {
+        if (path === '' || !isVendored(path, dirs)) continue
+        try { m.set(path, readFileSync(join(root, path))) } catch { m.set(path, null) }
+    }
+    return m
+}
+
+/** put back every vendored file a fixer changed since `before`: its bytes from
+ *  before when it differed from the index then, the index's otherwise */
+function restoreVendored(root: string, dirs: readonly string[], before: Map<string, Buffer | null>): { restored: string[]; failed: string[] } {
+    const restored: string[] = []
+    const failed: string[] = []
+    const fromIndex: string[] = []
+    const now = vendoredState(root, dirs)
+    const putBack = (path: string, was: Buffer | null): void => {
+        try {
+            if (was === null) rmSync(join(root, path), { force: true })
+            else writeFileSync(join(root, path), was)
+            restored.push(path)
+        } catch { failed.push(path) }
+    }
+    for (const [path, bytes] of now) {
+        const was = before.get(path)
+        if (was === undefined) fromIndex.push(path)
+        else if (was === null ? bytes !== null : bytes === null || !was.equals(bytes)) putBack(path, was)
+    }
+    // differed from the index before and matches it now: a fixer undid an edit
+    for (const [path, was] of before) if (!now.has(path)) putBack(path, was)
+    if (fromIndex.length > 0) {
+        const p = Bun.spawnSync([gitBin(), 'checkout', '--', ...fromIndex], { cwd: root, stdout: 'ignore', stderr: 'ignore' })
+        if (p.exitCode === 0) restored.push(...fromIndex)
+        else failed.push(...fromIndex)
+    }
+    return { restored: restored.sort(), failed: failed.sort() }
+}
+
 /** where the key of the last clean fix pass is kept, per checkout */
 const memoPath = (root: string): string => join(root, LAYOUT.tmp, 'fix-pass.key')
 
@@ -173,7 +204,11 @@ export type FixPassOpts = {
      *  mutate the tree they are about to ship) */
     armHooks?: boolean
     print: (line: string) => void
-    /** where the lines nobody acts on go (a clean pass, an unfilled slot).
+    /** a narrowed pass (`sk ci --only <ids> --fix`): only the repairs these
+     *  ids own, their own ci repair and the fixer slot that governs one of
+     *  them */
+    only?: string[]
+    /** where the lines nobody acts on go (a clean pass, a disabled slot).
      *  Default: print. `shipkit ci` shows them only under --verbose */
     detail?: (line: string) => void
 }
@@ -194,7 +229,7 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // not clean, and the gate says so instead of quietly repairing it
     const verify = process.env.CI != null && process.env.CI !== ''
     // EVERY write this function makes sits inside one lease. Three agents in
-    // one checkout is the normal case, and two formatters rewriting the same
+    // one checkout is the normal case, and two fixers rewriting the same
     // file at once, or two runs arming hooks and rewriting package.json
     // together, is the one hazard a snapshot diff cannot even detect. The
     // loser waits rather than skipping, because a skipped repair never
@@ -260,17 +295,34 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
         else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
     const detail = o.detail ?? o.print
-    const { slots, unfilled, disabled } = resolveFixers(root, config)
-    for (const u of unfilled) detail(`skip: ${u.id} (${u.reason})`)
+    const resolution = resolveFixers(root, config)
+    const { disabled } = resolution
+    const named = o.only == null ? null : new Set(o.only)
+    const slots = named == null ? resolution.slots : resolution.slots.filter((s) => named.has(GOVERNED_BY[s.id] ?? ''))
+    if (named != null) for (const s of resolution.slots) if (!slots.includes(s)) detail(`skip: ${s.id} (--only ${o.only!.join(', ')} names no check it repairs)`)
     for (const d of disabled) detail(`skip: ${d.id} (${d.reason})`)
     const before = treeState(root)
     // the fixers already ran clean over exactly this tree (HEAD, every dirty
     // path's bytes, the toolchain, the commands): running them again rewrites
-    // nothing and costs a whole formatter pass. CI never skips: there the
+    // nothing and costs a whole fixer pass. CI never skips: there the
     // pass IS the check
     const memo = verify || before == null ? null : fixMemo(root, before, slots.map((s) => s.cmd))
     const skip = memo != null && readMemo(root) === memo
     let fixersOk = true
+    // third party code stays byte identical: whatever a fixer wrote under a
+    // vendored dir goes back at once, and the fixer is named so the repo
+    // scopes it (it walked those files for nothing)
+    let vendored: string[] = []
+    try { vendored = readVendored(root) } catch (e) { o.print(`WARN vendored dirs unreadable, nothing guards them this pass: ${String((e as Error)?.message ?? e).slice(0, 160)}`) }
+    let guard = vendoredState(root, vendored)
+    const putBack = (who: string): void => {
+        if (vendored.length === 0) return
+        const { restored, failed } = restoreVendored(root, vendored, guard)
+        if (restored.length > 0) o.print(`WARN ${who} rewrote ${restored.length} vendored file(s), put back byte for byte: ${restored.slice(0, 4).join(' ')}${restored.length > 4 ? ` … +${restored.length - 4}` : ''}`)
+        if (restored.length > 0) o.print(`      fix: scope ${who} to leave ${vendored.join(', ')} out (repo.config.ts \`vendored\`)`)
+        if (failed.length > 0) o.print(`WARN ${who} rewrote vendored file(s) that could not be put back: ${failed.slice(0, 4).join(' ')} — restore them with git checkout`)
+        guard = vendoredState(root, vendored)
+    }
     if (skip) detail(`ok: fixers skipped, the tree is unchanged since they last ran clean (${slots.length} fixer(s))`)
     else for (const s of slots) {
         const r = await spawnWithTimeout(s.cmd, { cwd: root, timeoutMs: FIXER_TIMEOUT_MS })
@@ -280,9 +332,13 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
             fixersOk = false
             o.print(`WARN fix ${s.id} failed (exit ${r.code}) — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}; the gate below still ran`)
         }
+        putBack(`fix ${s.id} (${s.cmd.join(' ').slice(0, 60)})`)
     }
     // structural repo-config repair is never implicit, and never in verify mode
-    if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print, detail: o.detail, config })
+    if (o.rules === true && !verify) {
+        await runFix(root, { quiet: true, print: o.print, detail: o.detail, config, ...(o.only == null ? {} : { scope: o.only }) })
+        putBack('the rule repairs')
+    }
 
     const after = treeState(root)
     const reshaped = shapeStamp(root) !== shapeBefore

package/src/core/runs-matrix.ts

@@ -5,6 +5,9 @@
 import type { CheckRow } from '../ledger/gate-checks.ts'
 import { cellText, RUNS_KEYS, type RunsAxis, type RunsSource } from './runs.ts'
 
+/** the commit column's words for a commit gate (hooks/hook-gates.ts HookName) */
+const HOOK_WORDS: readonly string[] = ['pre-commit', 'commit-msg', 'both']
+
 export type MatrixAxis = RunsAxis | 'fix'
 
 export const MATRIX_AXES: readonly MatrixAxis[] = [...RUNS_KEYS, 'fix']
@@ -103,6 +106,9 @@ export function runsCellsOf(row: CheckRow): RunsCells {
     const r = row.runs
     const cells = Object.fromEntries(MATRIX_AXES.map((k) => {
         const v = k === 'fix' ? r.fix : r[k]
+        // a commit gate runs in a git hook rather than as an onPreCommit body,
+        // and the commit column names which hook
+        if (k === 'onPreCommit' && row.hook != null) return [k, { text: row.hook, on: r.off == null, source: r.source[k] }]
         const on = r.off == null && v !== false && v !== 'none'
         return [k, { text: cellText(r, k), on, source: r.source[k] }]
     })) as Record<MatrixAxis, RunsCell>
@@ -127,6 +133,7 @@ export function runsWords(c: RunsCells): string {
  *  prints short (yes, ·, moved, 24h); the legend names the declared value */
 export function cellMeaning(k: MatrixAxis | 'cache', text: string): string {
     const values = RUNS_LEGEND.find((a) => a.axis === k)!.values
+    if (k === 'onPreCommit' && HOOK_WORDS.includes(text)) return 'a commit gate: that git hook runs it on every commit, and `shipkit hooks list` shows it'
     const declared = k === 'cache'
         ? text.split(/[\s:]/)[0]!
         : text === 'yes' ? 'true'

package/src/core/slots.ts

@@ -4,6 +4,11 @@
 // mutate lease's non blocking form (locked-write.ts tryLease): a slot whose
 // holder died is free at once, and a live holder heartbeats it.
 //
+// A slot is a check, and a check is often a whole multi core tool (bun test
+// workers, linter threads, tsc), so slots alone never bound the CPU. Past the
+// cores the pool admits fewer slots in proportion to the 1 minute load, never
+// fewer than one (admittedSlots). A slot already held is never taken back.
+//
 // The one constraint a reader breaks first: a process started BY a check
 // (SHIPKIT_SLOT_HELD=1 in its environment) takes no slot. It already runs on
 // its parent's, and a parent waiting on a child that waits for a slot the
@@ -12,6 +17,8 @@ import { mkdirSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { leaseHolder, tryLease } from './locked-write.ts'
+import { machineLoad } from './budget.ts'
+import type { MachineLoad } from '../suite/judge-suites.ts'
 import { PARALLEL_ENV, parallelCap, parallelCapInfo } from './parallel.ts'
 
 /** where the slots live, for a test that must not touch the machine's pool */
@@ -19,7 +26,9 @@ export const SLOTS_DIR_ENV = 'SHIPKIT_SLOTS_DIR'
 /** set for every process a check spawns: it runs on its parent's slot */
 export const SLOT_HELD_ENV = 'SHIPKIT_SLOT_HELD'
 
-export type SlotPool = { dir: string; size: number }
+/** `load`: the reading that scales what the pool admits. Omitted: the whole
+ *  size, whatever the machine runs (a test's own pool) */
+export type SlotPool = { dir: string; size: number; load?: () => MachineLoad }
 
 export type SlotHolder = { slot: number; pid: number; repo: string; check: string; since: number }
 
@@ -37,9 +46,18 @@ export const autoGatePool = (): SlotPool => ({ dir: `${poolDir()}-auto-gate`, si
 
 /** this process's pool, or null when it runs inside a check that holds one */
 export function machinePool(): SlotPool | null {
-    return process.env[SLOT_HELD_ENV] === '1' ? null : { dir: poolDir(), size: parallelCap() }
+    return process.env[SLOT_HELD_ENV] === '1' ? null : { dir: poolDir(), size: parallelCap(), load: machineLoad }
 }
 
+/** how many of `size` slots a machine at this load admits: all of them up to
+ *  a load of one per core, then size × cores / load, never below one. At 20
+ *  on 8 cores a pool of 8 admits 3, at 81 it admits 1 */
+export const admittedSlots = (size: number, m: MachineLoad): number =>
+    Math.max(1, Math.min(size, Math.floor((size * m.cores) / Math.max(m.cores, m.load1))))
+
+const admitWords = (size: number, admitted: number, m: MachineLoad): string =>
+    `the pool admits ${admitted} of its ${size} slots at load ${m.load1.toFixed(1)} on ${m.cores} cores`
+
 /** who holds which slot right now, dead holders left out. Every slot file in
  *  the dir is read, so a slot taken under a larger size still shows. */
 export function poolOccupancy(pool: SlotPool = { dir: poolDir(), size: parallelCap() }): { size: number; dir: string; held: SlotHolder[] } {
@@ -64,25 +82,37 @@ export function poolLines(): string[] {
         ...(info.problem == null ? [] : [`WARN ${info.problem}`]),
         pool == null
             ? `ok: parallel: inside a check that holds a machine slot, so this run takes none (up to ${info.cap} at once in this process)`
-            : `ok: parallel: one machine pool of ${info.cap} slot(s) shared by every shipkit process, ${poolOccupancy(pool).held.length} held now (${why})`,
+            : `ok: parallel: one machine pool of ${info.cap} slot(s) shared by every shipkit process, ${poolOccupancy(pool).held.length} held now (${why})${loadNote(pool)}`,
     ]
 }
 
+const loadNote = (pool: SlotPool): string => {
+    const m = pool.load?.()
+    if (m == null) return ''
+    const admitted = admittedSlots(pool.size, m)
+    return admitted < pool.size ? `; ${admitWords(pool.size, admitted, m)}` : ''
+}
+
 /** wait for a free slot and hold it until release(). null = abort said stop. */
 export async function takeSlot(
     pool: SlotPool,
     who: { repo: string; check: string },
-    o: { abort?: () => boolean; pollMs?: number; onWait?: (held: SlotHolder[]) => void } = {},
+    o: { abort?: () => boolean; pollMs?: number; onWait?: (held: SlotHolder[], why: string) => void } = {},
 ): Promise<{ slot: number; release: () => void } | null> {
     mkdirSync(pool.dir, { recursive: true })
     let heard = false
     for (;;) {
-        for (let slot = 0; slot < pool.size; slot++) {
+        const m = pool.load?.() ?? null
+        const admitted = m == null ? pool.size : admittedSlots(pool.size, m)
+        for (let slot = 0; slot < admitted; slot++) {
             const lease = tryLease(join(pool.dir, `slot-${slot}`), who.check, { repo: who.repo, check: who.check })
             if (lease != null) return { slot, release: lease.release }
         }
         if (o.abort?.() === true) return null
-        if (!heard) { heard = true; o.onWait?.(poolOccupancy(pool).held) }
+        if (!heard) {
+            heard = true
+            o.onWait?.(poolOccupancy(pool).held, m != null && admitted < pool.size ? admitWords(pool.size, admitted, m) : `all ${pool.size} slots are held`)
+        }
         await Bun.sleep(o.pollMs ?? SLOT_POLL_MS)
     }
 }

package/src/core/vendored-read.ts

@@ -0,0 +1,39 @@
+// the disk half of core/vendored.ts: a repo's vendored dirs, read off its
+// config text, remembered per root while the file holds still.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { dirname, join, resolve } from 'path'
+import { vendoredOfText } from './vendored.ts'
+
+const CONFIG_FILE = 'repo.config.ts'
+
+const memo = new Map<string, { stamp: string; dirs: string[] }>()
+
+/** the vendored dirs of the repo at `root`, from its config text. Empty with
+ *  no config. Remembered per root while the file's size and mtime hold */
+export function readVendored(root: string): string[] {
+    const path = join(root, CONFIG_FILE)
+    let stamp: string
+    try {
+        const s = statSync(path)
+        stamp = `${s.size}:${s.mtimeMs}`
+    } catch {
+        return []
+    }
+    const hit = memo.get(root)
+    if (hit?.stamp === stamp) return hit.dirs
+    const dirs = vendoredOfText(readFileSync(path, 'utf8'))
+    memo.set(root, { stamp, dirs })
+    return dirs
+}
+
+/** the repo a dir sits in (the nearest dir up holding repo.config.ts) and its
+ *  vendored dirs, null outside any shipkit repo */
+export function vendoredAround(dir: string): { root: string; dirs: string[] } | null {
+    let cur = resolve(dir)
+    for (;;) {
+        if (existsSync(join(cur, CONFIG_FILE))) return { root: cur, dirs: readVendored(cur) }
+        const up = dirname(cur)
+        if (up === cur) return null
+        cur = up
+    }
+}