rvlib-shipkit 0.37.1 → 0.38.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.38.1
+
+- **The suite runner no longer refuses the test arguments of a repo with no `tests` block.** The floor spawns `bun suite-cli.ts [flags] -- <bun test args>`, and bun swallows a LEADING `--`. With no declaration there are no flags before it, so the runner saw `src/ tests/` bare and answered `unknown flag src/`, and a `bun test <args>` script with no `tests` block had a dead test slot on 0.38.0. The runner's own flags now end at `--` or at the first token that is not one of them. Pinned by a test fed both shapes, with a `bun test` flag and a separated declaration as controls.
+
+## 0.38.0
+
+- **A plain `bun test` floor runs its suites in parallel and times each one against a budget.** The floor `test` slot used to spawn `bun run test:raw`, which is one bun process running every suite on one core. Measured on a field repo: 71 suites in 74s, then a SIGKILL reported as `exited with code 1`, against 19.5s for the same suites in parallel workers. When the body is a literal `bun test …` (no cd, env prefix, pipe, quote or substitution, `--flag=value` allowed), the slot now runs `src/suite/suite-cli.ts`: every suite in `--parallel` workers, then the suites declared `serial` one at a time, with bun's own per-suite `--timings` read back. In the quick tier, the one every edit waits on, a suite over `repo.config.ts tests.budgetMs` (default 2000ms) runs again alone, and FAILs the task only when that alone timing is still over and it is not declared in `tests.slow` with `catches` (what no fast test catches) and `whyNotFast`. The quick tier leaves declared slow suites out, the full tier runs them, and a declared suite that runs under half the budget prints a WARN to drop the declaration without blocking. The full tier fails nothing on time and reports its three slowest suites. The full tier also runs one suite at a time: its suites spawn git and whole gates, and in parallel they measured slower than sequential and timed out. A killed suite prints `killed by SIGKILL while running <suite>`, from a crashed parallel worker or from the serial phase. The headline keeps `Ran N tests`. Any other script body runs as written, and the gate prints `skip: suite runner (…)` saying it is neither parallel nor timed. `defineRepo` refuses a declaration with a blank reason, a path outside the repo, a duplicate, or an unknown field, on the repo and on each `units[]` entry (paths relative to the unit), and the runner FAILs one naming a suite that does not exist.
+
+- **A repo task with an unknown field now fails at config load.** `defineRepo` refused a typo inside a `defaults` slot but not inside a `tasks` entry, and `repo.config.ts` usually sits outside every tsconfig, so no type error catches it either. A field repo declared `reads: ['.']` on its `fmt` and `build` tasks, where the field is `inputs`: both loaded as undeclared, and the 10s build re-ran on every gate over an unchanged tree. The error names the task and lists the valid fields.
+
+- **`ruleExempt`: a repo exempts one rule by id, with the reason.** `repo.config.ts ruleExempt: { SK003: '<why>' }`. The exempted rule does not lint and never autofixes. Every surface that runs it prints `skip: [SK003] SK003 exempt: <why>`, and `shipkit rules` marks it `EXEMPT here`. `defineRepo` throws on an id no built-in or repo rule carries, and on a blank reason. The reason is part of the rule's cache identity, so declaring or lifting an exemption never replays an old answer. It changes nothing a rule enforces anywhere else.
+
+- **A repo can be one folder of a larger git work tree: `nested: true`, rule SK015.** A `repo.config.ts` inside another repository used to treat the parent's history as its own. The contract folder repair renamed a tracked folder and landed a machine commit on the parent's branch, `machineCommit` committed wherever its anchor resolved, `bump` and `release` would tag and push the parent, SK007 judged the parent's github remote, SK009 scanned the parent's whole log, and the ledger keyed a declared input like `src` on the PARENT's `src`, so an edit inside the folder never moved its key. On the disk fact alone, declared or not (the fix pass runs before any rule): the repair leaves a tracked folder alone, `machineCommit` refuses an anchor that belongs to a nested config, `bump` and `release` refuse and name the parent, SK007 and SK009 skip and name it, the hooks skip with the nesting named, and the scan keys every declared path, the whole tree included, on the folder's own subtree. SK015 FAILs a nested folder that does not declare `nested: true`, and a work tree root that does. The generated-file untrack pass was already inert there, because it needs a `.git` in the folder, and a test now pins that.
+
 ## 0.37.1
 
 - **SK013 no longer wires a Bash guard that cannot run.** A consumer that runs shipkit from a checkout by ABSOLUTE path, with no `rvlib-shipkit` dependency and no `node_modules`, carried `bun "$CLAUDE_PROJECT_DIR/node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts"`, so every Bash call of every agent in that repo printed `Module not found`, while the rule only WARNed `not installed yet, bun install` and the gate stayed green. `bun install` installs nothing in a repo that declares no dependency, so that WARN now fires only when `package.json` declares `rvlib-shipkit`, and otherwise the missing guard FAILs. `guardCommand` glued an absolute cli path under the project dir (`$CLAUDE_PROJECT_DIR//Users/...`), and it now writes the absolute path alone. The lint resolves an absolute guard path too, where it used to pass any form it could not read. The fixer, which `shipkit ci` runs by default, repoints a guard whose script does not exist at the copy the repo actually runs: the cli path its scripts name when a guard sits beside it (a repo's own `src/cli.ts` matches the same script shape), else its declared dependency, else the shipkit doing the fixing, which is what the launcher falls back to. A guard that resolves, or waits on a declared install, stays as written, and a target that does not resolve itself is never written.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.37.1",
+    "version": "0.38.1",
     "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_Rules.ts

@@ -5,7 +5,16 @@
 // is a repo whose agents cannot know what binds them.
 import { Command, Option } from 'clipanion'
 import { RULES } from '../rules/rule-registry.ts'
-import { loadRepoConfig } from '../repo-config.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+
+export type RuleRow = { id: string; title: string; owner: string; blocking: boolean; fixable: boolean; source: 'shipkit' | 'repo'; exempt?: string }
+
+/** the catalog: built-in rules, then the repo's own */
+export function ruleRows(config: RepoConfig | null): RuleRow[] {
+    const row = (source: RuleRow['source']) => (r: { id: string; title: string; owner: string; blocking: boolean; fix?: unknown }): RuleRow =>
+        ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source, ...(config?.ruleExempt?.[r.id] == null ? {} : { exempt: config.ruleExempt[r.id] }) })
+    return [...RULES.map(row('shipkit')), ...(config?.rules ?? []).map(row('repo'))]
+}
 
 export class RulesCommand extends Command {
     static override paths = [['rules']]
@@ -24,13 +33,9 @@ export class RulesCommand extends Command {
     async execute(): Promise<number> {
         // a repo without repo.config.ts still gets the built-in catalog: this
         // command must answer "what rules exist" from anywhere
-        const repoRules = await loadRepoConfig(process.cwd())
-            .then((c) => c.rules ?? [])
-            .catch(() => [])
-        const rows = [
-            ...RULES.map((r) => ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source: 'shipkit' as const })),
-            ...repoRules.map((r) => ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source: 'repo' as const })),
-        ]
+        const config = await loadRepoConfig(process.cwd()).catch(() => null)
+        const repoRules = config?.rules ?? []
+        const rows = ruleRows(config)
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(rows)}\n`)
             return 0
@@ -38,7 +43,7 @@ export class RulesCommand extends Command {
         // a catalog, not a health run — no wire prefixes (`ok:` would assert
         // a passing check into anything that parses wire output)
         for (const r of rows)
-            this.context.stdout.write(`${r.blocking ? 'BLOCKS ' : 'warns  '}${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}\n`)
+            this.context.stdout.write(`${r.blocking ? 'BLOCKS ' : 'warns  '}${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}${r.exempt == null ? '' : ` · EXEMPT here: ${r.exempt}`}\n`)
         if (repoRules.length > 0)
             this.context.stdout.write(`\n${RULES.length} built-in · ${repoRules.length} repo-local (repo.config.ts rules)\n`)
         return 0

package/src/core/floor.ts

@@ -10,6 +10,7 @@ import { join } from 'path'
 import { fileURLToPath } from 'url'
 import { rawName, routesToShipkit } from './canonical-scripts.ts'
 import { resolveTypecheckProjects } from '../ts/tsconfig-projects.ts'
+import { parseBunTestScript, suiteFlags } from '../suite/judge-suites.ts'
 import type { TaskDef } from './task-runner.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
@@ -24,6 +25,21 @@ export type FloorResolution = {
     unfilled: { id: string; reason: string }[]
     /** where each registered slot came from (init prints this) */
     sources: Record<string, FloorSource>
+    /** skip lines about how a slot runs, printed by the gate */
+    notes?: string[]
+}
+
+/** a package.json body for a slot. A plain `bun test` in the test slot runs
+ *  through the suite runner (parallel, timed against the budget), anything
+ *  else runs as written and the gate says what that costs */
+function scriptCmd(c: RepoConfig, id: string, name: string, body: string, notes: string[]): string[] {
+    if (id !== 'test') return ['bun', 'run', name]
+    const args = parseBunTestScript(body)
+    if (args == null) {
+        notes.push(`skip: suite runner (script '${name}' is not a plain \`bun test\`, so its suites run as written: not in parallel, not timed against a budget)`)
+        return ['bun', 'run', name]
+    }
+    return ['bun', fileURLToPath(import.meta.resolve('rvlib-shipkit/src/suite/suite-cli.ts')), ...suiteFlags(c.tests), '--', ...args]
 }
 
 // zero-config floor (O6): with no script, imports:check/cycles resolve to
@@ -99,6 +115,7 @@ export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     const disabled: string[] = []
     const unfilled: { id: string; reason: string }[] = []
     const sources: Record<string, FloorSource> = {}
+    const notes: string[] = []
     for (const id of FLOOR_IDS) {
         const override = c.defaults?.[id]
         if (override === false) { disabled.push(id); continue }
@@ -116,13 +133,13 @@ export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
         // 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(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 }
+        if (raw != null) { tasks.push(decorate({ id, cmd: scriptCmd(c, id, rawName(id), raw, notes) })); sources[id] = 'package.json script'; continue }
+        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push(decorate({ id, cmd: scriptCmd(c, id, id, scripts[id]!, notes) })); 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(decorate(b.task)); sources[id] = b.source }
     }
-    return { tasks, disabled, unfilled, sources }
+    return { tasks, disabled, unfilled, sources, notes }
 }

package/src/core/locked-write.ts

@@ -146,7 +146,7 @@ export type LeaseOutcome<T> = { ok: true; value: T; waitedMs: number } | { ok: f
  *  that is gone or wedged, refused (never hung) past maxWaitMs. */
 export async function withMutateLease<T>(
     path: string,
-    o: { label: string; print?: (line: string) => void; maxWaitMs?: number; escape?: string },
+    o: { label: string; print?: (line: string) => void; maxWaitMs?: number; escape?: string; announceMs?: number },
     fn: () => T | Promise<T>,
 ): Promise<LeaseOutcome<T>> {
     const lockPath = `${path}.lock`
@@ -179,7 +179,7 @@ export async function withMutateLease<T>(
                 ok: false,
                 warn: `${o.label} lease held by ${holder == null ? 'an unreadable lock' : `pid ${holder.pid} (${holder.label})`} for ${Math.round(ageMs / 1000)}s — gave up after ${Math.round(waited / 1000)}s rather than run two of these at once. Lock: ${lockPath}${o.escape == null ? '' : `; skip this phase with ${o.escape}`}`,
             }
-        if (waited >= LEASE_ANNOUNCE_MS && waited - announced >= LEASE_REANNOUNCE_MS) {
+        if (waited >= (o.announceMs ?? LEASE_ANNOUNCE_MS) && waited - announced >= LEASE_REANNOUNCE_MS) {
             announced = waited
             print(`ok: waiting ${Math.round(waited / 1000)}s for the ${o.label} lease — ${holder == null ? 'an unreadable lock holds it' : `pid ${holder.pid} holds it (${holder.label})`}, lock ${lockPath}`)
         }

package/src/core/machine-commit.ts

@@ -18,6 +18,7 @@
 // not worth a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
 import { existsSync } from 'fs'
 import { join, resolve } from 'path'
+import { nestedConfigRoot } from './nesting.ts'
 
 const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
     const r = Bun.spawnSync(['git', ...args], { cwd })
@@ -40,6 +41,8 @@ export function machineCommit(o: MachineCommit): boolean {
         const top = git(resolve(o.anchor), ['rev-parse', '--show-toplevel'])
         if (!top.ok) return false // not a git repo, nothing to land
         const root = top.out
+        // an anchor inside a nested shipkit repo would land on the parent's branch
+        if (nestedConfigRoot(resolve(o.anchor), root) != null) return false
         // a detached HEAD or a repo with no commit yet has nowhere sane to land
         if (!git(root, ['symbolic-ref', '--quiet', 'HEAD']).ok) return false
         if (!git(root, ['rev-parse', '--verify', 'HEAD']).ok) return false

package/src/core/nesting.ts

@@ -0,0 +1,57 @@
+// a repo.config.ts can sit in ONE FOLDER of a larger git work tree (an
+// extension folder inside a product monorepo). shipkit then owns that folder
+// only: it never commits, untracks, tags or pushes on the parent's history, and
+// every path it hands git names a path inside the folder. `nested: true` in
+// repo.config.ts states it, rule SK015 fails when the declaration and the disk
+// disagree, and the call sites below refuse on the disk fact alone, declared or
+// not, because the fix pass runs before any rule can say so.
+import { existsSync, realpathSync } from 'fs'
+import { dirname, join } from 'path'
+
+const gitLine = (cwd: string, args: string[]): string | null => {
+    try {
+        const p = Bun.spawnSync(['git', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+        return p.exitCode === 0 ? p.stdout.toString().trim() : null
+    } catch {
+        return null
+    }
+}
+
+/** the work tree root holding `root` when it is a PARENT of `root`. null when
+ *  `root` is its own work tree root, or sits outside git */
+export function nestedIn(root: string): string | null {
+    const top = gitLine(root, ['rev-parse', '--show-toplevel'])
+    if (top == null || top === '') return null
+    try {
+        return realpathSync(top) === realpathSync(root) ? null : top
+    } catch {
+        return null
+    }
+}
+
+/** `root` relative to its work tree root, posix: '' at the root, else ending in '/' */
+export function treePrefix(root: string): string {
+    return gitLine(root, ['rev-parse', '--show-prefix']) ?? ''
+}
+
+/** the nearest repo.config.ts at or above `dir` and strictly below the work
+ *  tree root `top`: the nested shipkit repo `dir` belongs to, if any */
+export function nestedConfigRoot(dir: string, top: string): string | null {
+    let cur: string
+    let stop: string
+    try {
+        cur = realpathSync(dir)
+        stop = realpathSync(top)
+    } catch {
+        return null
+    }
+    while (cur !== stop && cur.startsWith(`${stop}/`)) {
+        if (existsSync(join(cur, 'repo.config.ts'))) return cur
+        cur = dirname(cur)
+    }
+    return null
+}
+
+/** the one refusal line every history-writing command prints */
+export const nestedRefusal = (top: string): string =>
+    `this repo is one folder of the git repo at ${top}, and that history is not shipkit's to commit, tag or push`

package/src/core/repair-contract-dirs.ts

@@ -22,6 +22,7 @@ import { readdirSync, renameSync, rmdirSync } from 'fs'
 import { join } from 'path'
 import { POLICY_LINES } from '../rules/SK004-gitignore-policy.ts'
 import { machineCommit } from './machine-commit.ts'
+import { nestedIn } from './nesting.ts'
 
 /** the always-ignored `.rv-*` contract folders, from the policy that owns them */
 export const contractDirNames = (): string[] =>
@@ -97,6 +98,8 @@ export function repairContractDirs(root: string): DirRepairResult {
     const renamed: DirRepair[] = []
     const removed: string[] = []
     const uncommitted: DirRepair[] = []
+    // a nested repo never untracks: the index and the commit are the parent's
+    const nested = plan.repairs.length === 0 ? null : nestedIn(root)
     for (const r of plan.repairs) {
         const from = join(root, r.from)
         const to = join(root, r.to)
@@ -113,7 +116,7 @@ export function repairContractDirs(root: string): DirRepairResult {
             // says those files are local. Untracked files rename freely: there
             // is nothing to lose and nothing to commit
             const tracked = isTracked(root, r.from)
-            if (tracked && !isIgnoredHere(root, r.to)) continue
+            if (tracked && (nested != null || !isIgnoredHere(root, r.to))) continue
             renameSync(from, to)
             renamed.push(r)
             // a repair that half happened is not the silence that was asked

package/src/core/run-check.ts

@@ -21,7 +21,7 @@ import { spawnWithTimeout } from './spawn-timeout.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { RULES } from '../rules/rule-registry.ts'
-import { runRuleLint } from '../rules/rule.ts'
+import { ruleCacheExtra, 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'
@@ -202,7 +202,7 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
             blocking: rule.blocking,
             name: rule.title,
             remainValidFor: rule.ttl,
-            cacheExtra: () => worldKey(rule.id, rule.cacheKey?.({ root, config: c })),
+            cacheExtra: () => worldKey(rule.id, ruleCacheExtra(rule, { root, config: c })),
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }

package/src/core/run-ci.ts

@@ -133,6 +133,7 @@ async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
         : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
     for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
+    for (const n of all.notes ?? []) sink(n)
     // THE LEDGER, opened once per run and AFTER the fix pass: the fixers
     // rewrite source, and a scan taken before them would have every unit
     // discarded by its own gate's repair work.

package/src/hooks/run-hooks.ts

@@ -70,7 +70,7 @@ export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
     if (top.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
     const topDir = top.stdout.toString().trim()
     try {
-        if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `work tree root is ${topDir}, not here` }
+        if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `nested in ${topDir}, which owns its own commit gates` }
     } catch {
         return { state: 'no-git', detail: 'work tree root unresolvable' }
     }

package/src/ledger/gate-units.ts

@@ -11,6 +11,7 @@ import { allTasks, type RepoConfig } from '../repo-config.ts'
 import type { TaskDef } from '../core/task-runner.ts'
 import { discoverChecks } from '../core/discover-checks.ts'
 import { RULES } from '../rules/rule-registry.ts'
+import { ruleCacheExtra } from '../rules/rule.ts'
 import type { UnitDecl } from './git-key.ts'
 
 /** the env var a repo's own suite reads to widen itself. It lives HERE because
@@ -103,7 +104,7 @@ export function gateInventory(root: string, c: RepoConfig, tasks?: TaskDef[]): U
                 code: r.code,
                 ttl: r.ttl,
                 never: r.never,
-                extra: r.cacheKey?.({ root, config: c }),
+                extra: ruleCacheExtra(r, { root, config: c }),
             },
             title: r.title,
             gate: true,

package/src/ledger/git-scan.ts

@@ -31,6 +31,7 @@
 //     retried and only a NON lock failure is fatal.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
+import { treePrefix } from '../core/nesting.ts'
 
 /** what a scan measured. Every OID is a git object id of the CURRENT disk
  *  content, tracked or not. */
@@ -244,15 +245,20 @@ export function scanPaths(root: string, rawPaths: string[]): ScanResult {
 
     const treeOid = gitOrThrow(root, ['write-tree'], indexFile).trim()
     const oidByPath = new Map<string, string>()
-    // the work tree's own id IS the tree the adds just produced — there is no
-    // `<tree>:` path to ask git for
-    if (wanted.includes(WHOLE_TREE)) oidByPath.set(WHOLE_TREE, treeOid)
+    // a declared path is relative to root, and `<tree>:<path>` reads from the
+    // work tree root. In a nested repo the two differ, so every query carries
+    // the folder's prefix, and the whole tree is the folder's own subtree
+    const prefix = treePrefix(root)
+    const underRoot = (p: string): string => (p === WHOLE_TREE ? prefix.replace(/\/$/, '') : `${prefix}${p}`)
+    // at a work tree root the whole tree IS the tree the adds just produced,
+    // there is no `<tree>:` path to ask git for
+    if (wanted.includes(WHOLE_TREE) && prefix === '') oidByPath.set(WHOLE_TREE, treeOid)
     const forceSet = new Set(forceAdd)
-    const plain = named.filter((p) => !forceSet.has(p))
+    const plain = [...named.filter((p) => !forceSet.has(p)), ...(wanted.includes(WHOLE_TREE) && prefix !== '' ? [WHOLE_TREE] : [])]
     for (const [tree, paths, index] of [[treeOid, plain, indexFile], [null, forceAdd, ignoredIndex]] as const) {
         if (paths.length === 0) continue
         const root_ = tree ?? gitOrThrow(root, ['write-tree'], index).trim()
-        const query = paths.map((p) => `${root_}:${p}`).join('\n')
+        const query = paths.map((p) => `${root_}:${underRoot(p)}`).join('\n')
         const p = Bun.spawnSync(['git', 'cat-file', '--batch-check'], {
             cwd: root,
             stdin: Buffer.from(`${query}\n`),

package/src/release/run-bump.ts

@@ -36,6 +36,7 @@ import { releaseScope } from './release-scope.ts'
 import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
 import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { nestedIn, nestedRefusal } from '../core/nesting.ts'
 
 export type BumpKind = 'major' | 'minor' | 'patch'
 
@@ -218,6 +219,8 @@ type Selected = { unit: ReleaseUnit; version: string; changelogRel: string; kind
 export async function runBump(root: string, config: RepoConfig, kind: BumpKind | null, o: BumpOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     if (o.all === true && o.unit != null) { print('FAIL: pass a unit or --all, never both'); return 1 }
+    const nested = nestedIn(root)
+    if (nested != null) { print(`FAIL: ${nestedRefusal(nested)}`); return 1 }
 
     const git: Git = (args) => gitAt(root, args)
     const cur = git(['rev-parse', '--abbrev-ref', 'HEAD']).out

package/src/release/run-release.ts

@@ -15,6 +15,7 @@ import { releaseScope } from './release-scope.ts'
 import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
 import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { nestedIn, nestedRefusal } from '../core/nesting.ts'
 
 // adding a FOURTH knob here is the signal that this shape wants rethinking
 // rather than another key (meta/gaps.md, release-path config keys accreting)
@@ -135,6 +136,8 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
 /** `shipkit release [unit]` — resolve the unit, then ship it. */
 export async function runRelease(root: string, config: RepoConfig, o: ReleaseOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
+    const nested = nestedIn(root)
+    if (nested != null) { print(`FAIL: ${nestedRefusal(nested)}`); return 1 }
     const { units, errors } = resolveUnits(root, config)
     const id = o.unit ?? 'root'
     // only THIS unit's own resolution has to hold: a broken sibling is not a

package/src/release/units.ts

@@ -8,6 +8,7 @@
 // rediscover packages (drift probes, per-lib tests, per-lib typecheck, the
 // stranded-tag probe) reads it instead of walking the tree with its own rules.
 import { existsSync, readFileSync, statSync } from 'fs'
+import type { TestsConfig } from '../suite/judge-suites.ts'
 import { basename, join, relative } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 
@@ -29,9 +30,11 @@ export type ReleaseUnitDecl = {
     githubRelease?: boolean
     /** repo-relative tsconfig for the unit's own typecheck (default '<dir>/tsconfig.json' when it exists) */
     tsconfig?: string
+    /** the unit's own suite budget, paths relative to the unit dir (suite/judge-suites.ts) */
+    tests?: TestsConfig
 }
 
-export const UNIT_DECL_KEYS: readonly string[] = ['dir', 'id', 'tag', 'changelog', 'npm', 'githubRelease', 'tsconfig']
+export const UNIT_DECL_KEYS: readonly string[] = ['dir', 'id', 'tag', 'changelog', 'npm', 'githubRelease', 'tsconfig', 'tests']
 
 /** a unit, fully resolved: no optionals, no defaults left to re-apply downstream */
 export type ReleaseUnit = {

package/src/repo-config.ts

@@ -27,6 +27,7 @@ import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
 import { TASK_DEF_KEYS, type TaskDef } from './core/task-runner.ts'
+import { testsConfigProblems, type TestsConfig } from './suite/judge-suites.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
 
@@ -87,6 +88,14 @@ export type RepoConfig = {
      *  rides into unrelated commits. `false` opts a repo out entirely, and
      *  `--frozen` suppresses it for one run the way it suppresses SK005. */
     untrackGenerated?: boolean
+    /** this repo is ONE FOLDER of a larger git work tree, and shipkit owns that
+     *  folder only: it never commits, untracks, tags or pushes on the parent's
+     *  history. Rule SK015 fails when this and the disk disagree (core/nesting.ts) */
+    nested?: boolean
+    /** rule id → the reason this repo breaks that invariant on purpose. An
+     *  exempted rule does not lint and prints a skip line carrying the reason.
+     *  `defineRepo` throws on an unknown id or a blank reason */
+    ruleExempt?: Record<string, string>
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
     visibility?: 'private' | 'public'
@@ -148,6 +157,10 @@ export type RepoConfig = {
      *  visits after a deploy, and how it logs in. The password is a secret
      *  NAME: the value never sits in config, argv or env. smoke/run-smoke.ts */
     smoke?: SmokeConfig
+    /** the suite budget for a plain `bun test` floor: per suite time limit, the
+     *  slow suites the quick tier leaves out, and the suites that cannot run in
+     *  parallel, each with its reason. suite/judge-suites.ts */
+    tests?: TestsConfig
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
     /** the `shipkit serve` hub: port + optional graph hooks */
@@ -155,7 +168,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -175,6 +188,8 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (typeof u.dir !== 'string' || u.dir === '') throw new Error(`defineRepo: every units[] entry needs a 'dir'`)
         for (const k of Object.keys(u))
             if (!UNIT_DECL_KEYS.includes(k)) throw new Error(`defineRepo: units['${u.dir}'] unknown key '${k}' (known: ${UNIT_DECL_KEYS.join(', ')})`)
+        const problems = u.tests != null ? testsConfigProblems(u.tests) : []
+        if (problems.length > 0) throw new Error(`defineRepo: units['${u.dir}'] ${problems[0]}`)
     }
     for (const d of c.notReleasable ?? []) {
         if (typeof d !== 'string' || d === '') throw new Error(`defineRepo: every notReleasable entry is a repo-relative dir path`)
@@ -195,12 +210,30 @@ export function defineRepo(c: RepoConfig): RepoConfig {
             if (!(TASK_DEF_KEYS as readonly string[]).includes(f))
                 throw new Error(`defineRepo: defaults.${k}.${f} is not a task field (fields: ${TASK_DEF_KEYS.join(', ')})`)
     }
+    // same promise for a repo task: repo.config.ts is often outside every
+    // tsconfig, so `reads` for `inputs` is no type error and the task never caches
+    for (const t of c.tasks ?? [])
+        for (const f of Object.keys(t))
+            if (!(TASK_DEF_KEYS as readonly string[]).includes(f))
+                throw new Error(`defineRepo: tasks['${t.id}'].${f} is not a task field (fields: ${TASK_DEF_KEYS.join(', ')})`)
+    // a slow or serial suite carries its case, or the declaration does not load
+    if (c.tests != null) {
+        const problems = testsConfigProblems(c.tests)
+        if (problems.length > 0) throw new Error(`defineRepo: ${problems[0]}`)
+    }
     for (const n of c.oneWayIn?.exempt ?? [])
         if (!(ROUTED_SCRIPTS as readonly string[]).includes(n))
             throw new Error(`defineRepo: oneWayIn.exempt '${n}' is not a governed script name (governed: ${ROUTED_SCRIPTS.join(', ')})`)
     // repo rules are validated against the built-ins, so a bad id, a duplicate,
     // or an SK squatter dies at config load, not silently mid-check
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
+    // an exemption silences a gate, so it names a rule that exists and says why
+    for (const [id, reason] of Object.entries(c.ruleExempt ?? {})) {
+        if (!BUILTIN_RULE_IDS.includes(id) && !(c.rules ?? []).some((r) => r.id === id))
+            throw new Error(`defineRepo: ruleExempt.${id} names no rule, the ids are in \`shipkit rules\``)
+        if (typeof reason !== 'string' || reason.trim() === '')
+            throw new Error(`defineRepo: ruleExempt.${id} needs a reason, an exemption nobody can explain is a silenced gate`)
+    }
     // a smoke typo would land as a run that visits nothing and exits 0
     if (c.smoke != null) validateSmokeConfig(c.smoke)
     // a leak-guard waiver is the one config row that can make a gate quieter,

package/src/rules/SK007-github-visibility.ts

@@ -14,6 +14,7 @@
 // erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
 // never cached.
 import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
+import { nestedIn } from '../core/nesting.ts'
 import type { Rule } from './rule.ts'
 
 export const githubVisibility: Rule = {
@@ -30,6 +31,9 @@ export const githubVisibility: Rule = {
         const declared = env.config.visibility ?? 'private'
         const skip = (why: string): void => void t.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
         const firstLine = firstGhLine
+        const nested = nestedIn(env.root)
+        if (nested != null)
+            return void t.lines.push({ kind: 'skip', text: `github visibility unverified, nested in ${nested}: the remote belongs to the parent repo (declared: ${declared})` })
 
         const remotes = await t.exec(['git', 'remote'], { cwd: env.root })
         if (remotes.code !== 0) return skip(`git says: ${firstLine(remotes.out) || `exit ${remotes.code}`}`)

package/src/rules/SK009-commit-ai-tells.ts

@@ -11,6 +11,7 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
+import { nestedIn } from '../core/nesting.ts'
 import type { Rule } from './rule.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
@@ -33,6 +34,9 @@ export const commitAiTells: Rule = {
     // work-tree content, so nothing a scan can produce describes this answer
     never: 'reads the full commit history and every ref name, neither of which is work-tree content',
     lint: async (t, env) => {
+        const nested = nestedIn(env.root)
+        if (nested != null)
+            return void t.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
         const declared = env.config.visibility ?? 'private'
         if (declared !== 'public')
             return t.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)

package/src/rules/SK015-nested-repo.ts

@@ -0,0 +1,29 @@
+// SK015 nested repo (build/shipkit.md): a repo.config.ts inside a larger git
+// work tree declares `nested: true`, and a work tree root never does. The call
+// sites that write history refuse on the disk fact either way (core/nesting.ts),
+// so this rule is about the declaration telling the truth to the next reader.
+import { nestedIn } from '../core/nesting.ts'
+import type { Rule } from './rule.ts'
+
+export const nestedRepo: Rule = {
+    id: 'SK015',
+    blocking: true,
+    title: 'nested repo',
+    owner: 'build/shipkit.md',
+    never: 'reads where the git work tree root sits, which no content inside the repo describes',
+    lint: (t, env) => {
+        const top = nestedIn(env.root)
+        const declared = env.config.nested === true
+        if (top != null && !declared) {
+            t.fail(`repo.config.ts sits inside the git repo at ${top} and does not declare it`)
+            t.lines.push({ kind: 'fix-fail', text: 'add `nested: true` to repo.config.ts: shipkit then owns this folder only, and never writes the parent history' })
+            return
+        }
+        if (top == null && declared) {
+            t.fail('repo.config.ts declares `nested: true`, but this folder is its own git work tree root (or sits outside git)')
+            t.lines.push({ kind: 'fix-fail', text: 'delete `nested: true` from repo.config.ts' })
+            return
+        }
+        t.ok(top == null ? 'not nested, and not declared nested' : `nested in ${top}, declared`)
+    },
+}

package/src/rules/rule-registry.ts

@@ -17,6 +17,7 @@ import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 import { configBarrelImport } from './SK012-config-barrel-import.ts'
 import { oneWayInPolicy } from './SK013-one-way-in-policy.ts'
 import { proseSte } from './SK014-prose-ste.ts'
+import { nestedRepo } from './SK015-nested-repo.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -33,6 +34,7 @@ export const RULES: readonly Rule[] = [
     configBarrelImport,
     oneWayInPolicy,
     proseSte,
+    nestedRepo,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/rules/rule.ts

@@ -60,11 +60,24 @@ export type Rule = {
     fix?: (env: RuleEnv) => FixResult | Promise<FixResult>
 }
 
+/** the config part of a rule's cache identity */
+export function ruleCacheExtra(rule: Rule, env: RuleEnv): string | undefined {
+    const key = rule.cacheKey?.(env)
+    const exempt = env.config.ruleExempt?.[rule.id]
+    return exempt == null ? key : `${key ?? ''}|exempt:${exempt}`
+}
+
 // THE one way to run a rule's lint (check suite + the --fix runner): a
 // throwing lint still fails with its id, a failing/warning run always
 // carries at least one fix: pointer (the lint's own precise ones win, else
 // docsBase + the rule's owner page), and every line gets tagged.
 export async function runRuleLint(rule: Rule, t: CheckCtx, env: RuleEnv): Promise<void> {
+    const exempt = env.config.ruleExempt?.[rule.id]
+    if (exempt != null) {
+        t.lines.push({ kind: 'skip', text: `${rule.id} exempt: ${exempt}` })
+        t.lines = tagRuleLines(rule, t.lines)
+        return
+    }
     try {
         await rule.lint(t, env)
     } catch (e) {

package/src/rules/run-fix.ts

@@ -40,6 +40,12 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
     for (const rule of targets) {
         const before = new CheckCtx(new Map())
         await runRuleLint(rule, before, env)
+        // an exempted rule never autofixes: the repo broke that invariant on purpose
+        const exempt = config.ruleExempt?.[rule.id]
+        if (exempt != null) {
+            if (o.quiet !== true) print(`skip: [${rule.id}] ${rule.id} exempt: ${exempt}`)
+            continue
+        }
         if (!before.failed && !before.warned) {
             // inside the ci fix pass, a line per already-clean rule is a wall of
             // nothing above the run that reports those same rules for real

package/src/suite/judge-suites.ts

@@ -0,0 +1,147 @@
+// the suite budget, as pure functions: which script is a plain `bun test`, how a
+// run splits into a parallel and a serial phase, and which suites broke the
+// budget. suite-cli.ts spawns, this module decides (meta/rv-conventions/test-speed.md).
+import { isAbsolute, posix } from 'path'
+
+export type SlowSuite = {
+    file: string
+    /** what this suite catches that no fast test can */
+    catches: string
+    /** why it cannot be made fast (smaller fixture, pure logic extracted) */
+    whyNotFast: string
+}
+export type SerialSuite = {
+    file: string
+    /** what breaks when it shares a run with other suites */
+    why: string
+}
+export type TestsConfig = {
+    /** per suite wall time in the quick tier (default 2000). A suite over it under the parallel run is timed again alone, and only that timing fails it. The full tier fails nothing on time */
+    budgetMs?: number
+    /** suites that break the budget on purpose: the full tier runs them, the quick tier does not */
+    slow?: SlowSuite[]
+    /** suites that cannot share a run: they run one at a time after the parallel phase */
+    serial?: SerialSuite[]
+}
+
+export const DEFAULT_BUDGET_MS = 2000
+const TESTS_KEYS = ['budgetMs', 'slow', 'serial']
+const SLOW_KEYS = ['file', 'catches', 'whyNotFast']
+const SERIAL_KEYS = ['file', 'why']
+const OWN_FLAGS = ['--budget-ms', '--slow', '--serial', '--declared-in']
+
+export const normSuitePath = (file: string): string => posix.normalize(file.replace(/\\/g, '/')).replace(/^\.\//, '')
+
+/** the arguments after `bun test`, or null when a shell would interpret the script
+ *  (cd, env prefix, pipes, quotes, substitution): that body stays the repo's own */
+export function parseBunTestScript(script: string): string[] | null {
+    const s = script.trim()
+    if (!/^bun test(\s|$)/.test(s)) return null
+    // `=` stays allowed: after `bun test` it only ever means `--flag=value`
+    if (/[&|;<>$`'"\\(){}*?!#~]/.test(s.slice('bun test'.length))) return null
+    return s.split(/\s+/).slice(2)
+}
+
+/** the flags the floor hands suite-cli.ts. Only file names travel: a reason edit
+ *  must not move the task's cache key */
+export function suiteFlags(t: TestsConfig | undefined): string[] {
+    if (t == null) return []
+    return [
+        ...(t.budgetMs != null ? ['--budget-ms', String(t.budgetMs)] : []),
+        ...(t.slow ?? []).flatMap((s) => ['--slow', s.file]),
+        ...(t.serial ?? []).flatMap((s) => ['--serial', s.file]),
+    ]
+}
+
+/** the inverse of suiteFlags, plus where the declarations live (printed in
+ *  every fix line) and the `bun test` arguments after `--` */
+export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs: string[]; declaredIn: string } | string {
+    const tests: Required<TestsConfig> = { budgetMs: DEFAULT_BUDGET_MS, slow: [], serial: [] }
+    let declaredIn = 'repo.config.ts tests'
+    // the runner's own flags end at `--` OR at the first token that is not one
+    // of them: bun swallows a LEADING `--`, so a repo with no declaration hands
+    // over the `bun test` arguments with no separator at all
+    let i = 0
+    for (; i < argv.length; i += 2) {
+        const flag = argv[i]!
+        if (flag === '--') { i++; break }
+        if (!OWN_FLAGS.includes(flag)) break
+        const value = argv[i + 1]
+        if (value == null || value === '--') return `${flag} needs a value`
+        if (flag === '--budget-ms') tests.budgetMs = Number(value)
+        else if (flag === '--slow') tests.slow.push({ file: value, catches: '(declared)', whyNotFast: '(declared)' })
+        else if (flag === '--serial') tests.serial.push({ file: value, why: '(declared)' })
+        else declaredIn = value
+    }
+    if (!(tests.budgetMs > 0)) return '--budget-ms must be a positive number'
+    return { tests, rawArgs: argv.slice(i), declaredIn }
+}
+
+/** what `bun test` receives in each phase. The serial phase names its files
+ *  explicitly, because bun reports no tests when a path is both named and ignored */
+export function planPhases(p: { tests: TestsConfig; tier: 'quick' | 'full'; rawArgs: string[]; parallel: boolean }): { parallel: string[]; serial: string[] | null } {
+    const slow = (p.tests.slow ?? []).map((s) => normSuitePath(s.file))
+    const serial = (p.tests.serial ?? []).map((s) => normSuitePath(s.file))
+    const ignored = [...new Set([...(p.tier === 'quick' ? slow : []), ...serial])]
+    const serialRun = serial.filter((f) => p.tier === 'full' || !slow.includes(f))
+    return {
+        parallel: [...p.rawArgs, ...(p.parallel ? ['--parallel'] : []), ...ignored.map((f) => `--path-ignore-patterns=${f}`)],
+        serial: serialRun.length > 0 ? [...p.rawArgs, ...serialRun] : null,
+    }
+}
+
+type Timed = { file: string; ms: number }
+
+export function judgeSuites(p: { timings: Record<string, number>; tests: TestsConfig; tier: 'quick' | 'full' }): { over: Timed[]; noLongerSlow: Timed[]; slowest: Timed[] } {
+    const budget = p.tests.budgetMs ?? DEFAULT_BUDGET_MS
+    const slow = new Set((p.tests.slow ?? []).map((s) => normSuitePath(s.file)))
+    const timed = Object.entries(p.timings).map(([file, ms]) => ({ file: normSuitePath(file), ms })).sort((a, b) => b.ms - a.ms)
+    return {
+        // the budget guards the tier every edit waits on. The full tier is
+        // where slow suites belong, and it only reports
+        over: p.tier === 'quick' ? timed.filter((t) => t.ms > budget && !slow.has(t.file)) : [],
+        // half the budget, so a declaration does not flap on timing noise
+        noLongerSlow: timed.filter((t) => slow.has(t.file) && t.ms < budget / 2),
+        slowest: timed.slice(0, 3),
+    }
+}
+
+/** what stays over budget once each suspect ran alone: a parallel timing
+ *  carries the load of every other suite and every other gate on the machine,
+ *  so only the alone timing can fail a suite */
+export function confirmOver(over: Timed[], alone: Record<string, number>, budgetMs: number): Timed[] {
+    const byFile = new Map(Object.entries(alone).map(([f, ms]) => [normSuitePath(f), ms]))
+    return over.map((t) => ({ file: t.file, ms: byFile.get(t.file) ?? t.ms })).filter((t) => t.ms > budgetMs)
+}
+
+/** the suites bun names as a crashed parallel worker */
+export function crashedWorkers(output: string): { file: string; signal: string }[] {
+    return [...output.matchAll(/^\s*✗\s+(\S+)\s+\(worker crashed: (SIG[A-Z0-9]+)\)\s*$/gm)].map((m) => ({ file: normSuitePath(m[1]!), signal: m[2]! }))
+}
+
+export function testsConfigProblems(t: TestsConfig): string[] {
+    const problems: string[] = []
+    for (const k of Object.keys(t)) if (!TESTS_KEYS.includes(k)) problems.push(`tests.${k} is not a tests field (fields: ${TESTS_KEYS.join(', ')})`)
+    if (t.budgetMs != null && !(typeof t.budgetMs === 'number' && t.budgetMs > 0)) problems.push('tests.budgetMs must be a positive number of milliseconds')
+    const lists: [string, { file: string }[], string[], [string, string][]][] = [
+        ['slow', t.slow ?? [], SLOW_KEYS, [['catches', 'what it catches that no fast test can'], ['whyNotFast', 'why it cannot be made fast']]],
+        ['serial', t.serial ?? [], SERIAL_KEYS, [['why', 'what breaks when it shares a run']]],
+    ]
+    for (const [name, entries, keys, reasons] of lists) {
+        const seen = new Set<string>()
+        for (const e of entries) {
+            const file = typeof e.file === 'string' ? e.file.trim() : ''
+            if (file === '') { problems.push(`tests.${name} has an entry with no file`); continue }
+            const rel = normSuitePath(file)
+            if (isAbsolute(file) || rel === '..' || rel.startsWith('../')) problems.push(`tests.${name} ${file} must be a path inside the repo`)
+            if (seen.has(rel)) problems.push(`tests.${name} names ${rel} twice`)
+            seen.add(rel)
+            for (const k of Object.keys(e)) if (!keys.includes(k)) problems.push(`tests.${name} ${rel}: ${k} is not a field (fields: ${keys.join(', ')})`)
+            for (const [k, says] of reasons) {
+                const v = (e as Record<string, unknown>)[k]
+                if (typeof v !== 'string' || v.trim() === '') problems.push(`tests.${name} ${rel} needs ${k}: ${says}`)
+            }
+        }
+    }
+    return problems
+}

package/src/suite/suite-cli.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env bun
+// the floor `test` slot for a plain `bun test` script: quick tier suites in
+// parallel workers, the full tier one at a time, the declared serial ones after,
+// and each quick tier suite timed against the budget.
+// The LAST stdout line is the task headline the gate prints, and it keeps bun's
+// `Ran N tests` so the gate can still report what ran.
+//
+// usage: suite-cli [--budget-ms N] [--slow file]... [--serial file]... [--declared-in <where>] -- <bun test args>
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { FULL_TESTS_ENV } from '../ledger/gate-units.ts'
+import { confirmOver, crashedWorkers, DEFAULT_BUDGET_MS, judgeSuites, normSuitePath, parseSuiteFlags, planPhases } from './judge-suites.ts'
+
+type Phase = { code: number; signal: string | null; out: string; timings: Record<string, number> }
+
+async function runPhase(args: string[], timingsFile: string | null, echo = true): Promise<Phase> {
+    const timing = timingsFile != null ? [`--timings=${timingsFile}`, '--update-timings'] : []
+    const proc = Bun.spawn(['bun', 'test', ...args, ...timing], { stdout: 'pipe', stderr: 'pipe', stdin: 'ignore' })
+    let out = ''
+    const pump = async (stream: ReadableStream<Uint8Array>, sink: NodeJS.WriteStream): Promise<void> => {
+        const dec = new TextDecoder()
+        for await (const chunk of stream) {
+            const text = dec.decode(chunk)
+            out += text
+            if (echo) sink.write(text)
+        }
+    }
+    await Promise.all([pump(proc.stdout, process.stdout), pump(proc.stderr, process.stderr)])
+    const code = await proc.exited
+    let timings: Record<string, number> = {}
+    try { if (timingsFile != null && existsSync(timingsFile)) timings = (JSON.parse(readFileSync(timingsFile, 'utf8')) as { files?: Record<string, number> }).files ?? {} }
+    catch { timings = {} }
+    return { code, signal: proc.signalCode ?? null, out, timings }
+}
+
+const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
+const lastCount = (out: string, re: RegExp): number => Number([...out.matchAll(re)].at(-1)?.[1] ?? 0)
+
+export async function suiteCli(argv: string[]): Promise<number> {
+    const parsed = parseSuiteFlags(argv)
+    if (typeof parsed === 'string') { console.log(`FAIL: suite runner: ${parsed}`); return 2 }
+    const { tests, rawArgs, declaredIn } = parsed
+    const tier = process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick'
+    const budget = tests.budgetMs ?? DEFAULT_BUDGET_MS
+
+    // a declaration naming a gone suite would silently stop excluding anything
+    const gone = [...(tests.slow ?? []).map((s) => ['slow', s.file]), ...(tests.serial ?? []).map((s) => ['serial', s.file])]
+        .filter(([, f]) => !existsSync(f!))
+    if (gone.length > 0) {
+        for (const [list, f] of gone) console.log(`FAIL: ${declaredIn}.${list} names ${normSuitePath(f!)}, which does not exist`)
+        return 1
+    }
+
+    const help = Bun.spawnSync(['bun', 'test', '--help'], { stdout: 'pipe', stderr: 'pipe' })
+    const helpText = `${help.stdout.toString()}${help.stderr.toString()}`
+    // the full tier runs one suite at a time: its suites spawn git and whole
+    // gates, and sharing a run measured slower than sequential and timed out
+    const parallel = helpText.includes('--parallel') && tier === 'quick'
+    const timed = helpText.includes('--update-timings')
+    const plan = planPhases({ tests, tier, rawArgs, parallel })
+    const dir = mkdtempSync(join(tmpdir(), 'shipkit-suite-'))
+    const notes: string[] = []
+    if (!helpText.includes('--parallel')) notes.push(`skip: parallel suites (bun ${Bun.version} has no --parallel)`)
+    if (!timed) notes.push(`skip: suite budget (bun ${Bun.version} writes no --timings)`)
+    try {
+        const p1 = await runPhase(plan.parallel, timed ? join(dir, 'parallel.json') : null)
+        const p2 = plan.serial != null ? await runPhase(plan.serial, timed ? join(dir, 'serial.json') : null) : null
+        const phases = [p1, ...(p2 != null ? [p2] : [])]
+        const ran = phases.reduce((n, p) => n + lastCount(p.out, /Ran (\d+) tests?/g), 0)
+        const failedTests = phases.reduce((n, p) => n + lastCount(p.out, /^\s*(\d+) fail$/gm), 0)
+        const timings = Object.assign({}, ...phases.map((p) => p.timings)) as Record<string, number>
+        const judged = judgeSuites({ timings, tests, tier })
+        const slowest = judged.slowest.length > 0 ? ` (slowest: ${judged.slowest.map((t) => `${t.file} ${secs(t.ms)}`).join(', ')})` : ''
+
+        // a parallel timing carries every other suite's load, so a suspect is
+        // timed again alone, one process, before it can fail the task
+        let over = judged.over
+        if (over.length > 0) {
+            const alone = await runPhase([...rawArgs, ...over.map((t) => t.file)], join(dir, 'alone.json'), false)
+            over = confirmOver(over, alone.timings, budget)
+        }
+
+        const killed = crashedWorkers(p1.out).map((c) => `killed by ${c.signal} while running ${c.file} (out of memory, or killed from outside)`)
+        if (p1.signal != null) killed.push(`killed by ${p1.signal} during the parallel run (out of memory, or killed from outside)`)
+        if (p2?.signal != null) {
+            const unfinished = (plan.serial ?? []).filter((a) => !a.startsWith('-') && !rawArgs.includes(a) && p2.timings[normSuitePath(a)] == null)
+            killed.push(`killed by ${p2.signal} while running ${unfinished.join(' or ')} (out of memory, or killed from outside)`)
+        }
+        // never blocking: a suite that got faster must not stop a release
+        const stale = judged.noLongerSlow.map((t) => `WARN ${declaredIn}.slow declares ${t.file}, which ran in ${secs(t.ms)}, under half the ${budget}ms budget: remove the declaration`)
+
+        for (const n of notes) console.log(n)
+        for (const s of stale) console.log(s)
+        const fails: string[] = [
+            ...killed.map((k) => `FAIL: ${k}`),
+            ...(failedTests > 0 || (phases.some((p) => p.code !== 0 && p.signal == null) && killed.length === 0)
+                ? [`FAIL: ${failedTests} test(s) failed, Ran ${ran} tests${slowest}`] : []),
+            ...(over.length > 0
+                ? [`FAIL: ${over.length} suite(s) over the ${budget}ms budget: ${over.map((t) => `${t.file} ${secs(t.ms)}`).join(', ')} (timed alone). Make each fast, or declare it in ${declaredIn}.slow with what it catches and why it cannot be fast`]
+                : []),
+        ]
+        // the most actionable failure prints LAST, where the gate reads its headline
+        for (const f of fails.slice(1).reverse()) console.log(f)
+        if (fails.length > 0) { console.log(fails[0]); return 1 }
+        const serialCount = plan.serial != null ? plan.serial.length - rawArgs.length : 0
+        console.log(`ok: Ran ${ran} tests across ${Object.keys(timings).length || '?'} suites, ${parallel ? 'parallel' : 'one at a time'}${serialCount > 0 ? ` then ${serialCount} serial` : ''}, ${tier} tier${slowest}`)
+        return 0
+    } finally {
+        rmSync(dir, { recursive: true, force: true })
+    }
+}
+
+if (import.meta.main) process.exit(await suiteCli(process.argv.slice(2)))