rvlib-shipkit 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -1,4 +1,24 @@
-# Changelog
+## 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.
+
+- **The gate says what an undeclared floor costs, and declares nothing on a repo's behalf.** A slot with no `inputs`, no `ttl` and no `never` is measured every run, and `resolveFloor` declares none for any of the five, so a second gate over an UNCHANGED tree re-runs everything: 17.4s per gate measured on a field repo, 14.8s of it the test task, against the shape an agent actually runs (verify, commit, verify again). Nothing pointed at the repair either, since `shipkit init` scaffolded no `defaults` block, so a fresh repo stayed that way until somebody read `shipkit keys --burn-down` and knew what to write. `init` now scaffolds the commented `defaults` line naming the fix.
+- **What this release deliberately does NOT do is auto-declare `['.']` for those slots**, and the reason is worth more than the speed. `['.']` is not the work tree, it is the TRACKED tree: `git-scan` force-adds only a path a declaration NAMES, so an ignored path enters a key by NAME and never by content. Every floor task reads ignored content in an ordinary repo, a suite through its fixtures and its local database, tsc and the two graph walks through generated types and `node_modules`. Measured on a scratch repo: warm the ledger with two green runs, break a gitignored file the suite reads, and the third gate prints `ok: test (replayed, 0.0s saved)` over a suite that exits 1. `tests/floor-cache-safety.test.ts` holds that repro, watched fail, with the declaring lookalike beside it still replaying. Speed here is bought by a REPO declaring what its own tasks read, which is the only declaration with a real hit rate anyway.
+- Two doc sentences that argued the other way are corrected where they live: `TaskDef.inputs` no longer says `['.']` "cannot under declare", and the `git-key` header no longer promises the never-cached default is the whole safety story without naming who can declare on a unit's behalf.
+
+- **SK004 asks git what is ignored, instead of trusting the text it wrote.** The rule compared the managed block to the expected string and stopped there, so it reported `current` over a repo where git ignored none of what the block claims. Two ways that happens, both from the field. A bare `printf 'work/\n' >> .gitignore` onto a file whose last line carried no terminator fuses the two into `sourcework/`, which ignores neither path, and the file ends with a newline afterwards so nothing textual looks wrong (cost in that repo: 1.1GB and 700 screenshots pushed across four commits, a rejected push, and a `git filter-repo` rewrite). And a negation below the block is the DOCUMENTED override, so nothing stopped one landing on `.rv-private/`, the directory holding the keyword list the leak guard itself reads. Every policy pattern is now probed through one `git check-ignore --stdin` call and a contradiction FAILs, naming the pattern and the `check-ignore -v` that reports the winning line. The three venue folders stay exempt, because unignoring one is how a live listing ships. A `.gitignore` that does not end with a newline is now a FAIL of its own, since that missing byte is the trap rather than a cosmetic defect, and `--fix` terminates the file even when the block is current. Outside a git repo the rule states the block went unverified rather than reporting a green nothing measured.
+
+- **A check declaration the gate's own formatter wrote was unreadable to the gate.** `BLOCKING_RE` and `GATE_RE` both ended in `\s*$`, and oxfmt (which the fix pass RUNS) terminates every statement with a semicolon. So `shipkit ci` reformatted `export const blocking = false` into `export const blocking = false;`, then failed the file with `does not declare whether it blocks` and printed as the fix the exact line it had just written. Two repos in the field shipped `// oxfmt-ignore` workarounds to get a green gate. The worse half was silent: a `export const gate = false;` was not read either, so a world probe that had opted out of the gate quietly re-entered it, and a repo could declare fifteen off-gate probes and watch all fifteen run. Both readers now accept an optional `as const` and an optional semicolon through one shared tail. `INPUTS_RE`, `TTL_RE` and `NEVER_RE` never anchored the line end, so they were never affected. Pinned by three tests: the formatted shapes, the gate opt-out in both spellings, and a CONTROL that the unterminated shapes and a silent file still read as before.
 
 ## 0.37.0
 

package/package.json

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

package/src/cli/cmd_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/discover-checks.ts

@@ -42,7 +42,11 @@ export type DiscoveredCheck = {
 
 // read without importing: checks run as subprocesses, and discovery must stay
 // pure-fs. `export const blocking = true` (or false), nothing cleverer.
-const BLOCKING_RE = /^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)\s*$/m
+// the tail is the gate's OWN formatter: oxfmt terminates every statement, and
+// the fix pass runs it, so a reader that refuses a semicolon refuses the shape
+// the gate itself just wrote.
+const TAIL = String.raw`(?:\s+as\s+const)?\s*;?\s*$`
+const BLOCKING_RE = new RegExp(String.raw`^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)` + TAIL, 'm')
 // `export const inputs = ['a', 'b']`, single or multi line. Anything cleverer
 // (a computed list, a spread) is deliberately unreadable here and lands as no
 // declaration, which means never cached: a scanner guessing at a program is
@@ -53,7 +57,7 @@ const NEVER_RE = /^\s*export\s+const\s+never\s*(?::\s*string\s*)?=\s*['"]([^'"]+
 // `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 GATE_RE = new RegExp(String.raw`^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false` + TAIL, 'm')
 const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
 
 export function discoverChecks(root: string): DiscoveredCheck[] {

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
@@ -68,6 +84,24 @@ function builtinFloorTask(id: string, root: string): { task: TaskDef; source: Fl
     return `no package.json '${id}' script`
 }
 
+// NOTHING here declares a read set on a repo's behalf, and that is a decision
+// rather than an omission. A floor slot with no `inputs` is measured every run,
+// which costs speed and never correctness (ledger/git-key.ts owns that default).
+//
+// The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
+// under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
+// path a declaration NAMES, so an ignored path enters the key by name and never
+// by content. Every floor slot reads ignored content in an ordinary repo, a
+// suite through its fixtures and a local database, tsc and the graph walks
+// through generated types and node_modules. Shipped for one day, that made the
+// gate print `ok: test (replayed)` over a suite that exits 1
+// (tests/floor-cache-safety.test.ts holds the repro).
+//
+// Speed here is bought by a REPO saying what its own tasks read, in
+// `defaults`, which is the only declaration with a real hit rate anyway.
+// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
+// still undeclared, and the gate prints the cost of it once per run.
+
 export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
     const pkgPath = join(root, 'package.json')
     let scripts: Record<string, string> = {}
@@ -81,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 }
@@ -98,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/core/task-runner.ts

@@ -36,8 +36,12 @@ export type TaskDef = {
      *  speed and never correctness. A list MISSING a path the command reads is
      *  the one that costs correctness: the key cannot move when that path
      *  changes, so the answer replays over a tree it no longer describes. Over
-     *  declaring costs a re-run, under declaring is a false green, and `['.']`
-     *  is the whole work tree and cannot under declare. A task carries no code
+     *  declaring costs a re-run, under declaring is a false green. `['.']` is
+     *  the whole TRACKED tree, and it is NOT a catch-all: an ignored path
+     *  enters a key by name and never by content, so a task reading a
+     *  gitignored fixture, a built dir or a .env under declares with `['.']`
+     *  exactly as it would with a narrow list. A task that reads the network,
+     *  a keychain or the clock declares `ttl`, never `inputs`. A task carries no code
      *  closure, so the script it runs belongs in here too.
      *  Declaring both this and `ttl` is a registration failure. */
     inputs?: string[]

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/init-repo.ts

@@ -29,10 +29,14 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'], selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'], the .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // lint, typecheck, imports:check and cycles replay off the tracked tree.
+    // \`test\` measures every run until you say what it reads, because an
+    // ignored path (a fixture, a local db, a .env) is not in a tree key:
+    // defaults: { test: { inputs: ['tests', 'src', 'package.json'] } },
     // .comfy-ts/ holds schema dumps naming a private model collection.
     // gitignore (SK004) is advisory, this pre-commit gate is not
     hooks: { blockedPaths: ['.comfy-ts/'] },
-    // the mandated reviewer agent type (rule SK008). Uncomment with YOUR
+    // the declared reviewer agent type (rule SK008). Uncomment with YOUR
     // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
     // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
     // health checks need no config. Drop a <name>.check.ts file anywhere,

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-key.ts

@@ -16,8 +16,11 @@
 //   NEITHER  declares nothing. Never cached. This is the DEFAULT, and it is
 //            the whole safety story: forgetting to declare costs speed, never
 //            correctness, so the burn-down list below is a to-do rather than a
-//            hazard. Declaring BOTH is a registration failure, loud, because
-//            the two answers contradict each other.
+//            hazard. It holds only while nothing declares ON a unit's behalf:
+//            the gate floor gives `['.']` to the four slots tracked source
+//            decides and deliberately leaves `test` here (core/floor.ts says
+//            why). Declaring BOTH is a registration failure, loud, because the
+//            two answers contradict each other.
 //
 // CROSS WORKTREE. Every component here is content addressed or a version
 // string; not one of them is an absolute path. Two worktrees of one repo

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,15 +88,23 @@ 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'
-    /** the reviewer agent type this repo mandates: `.claude/agents/<name>.md`,
+    /** the reviewer agent type this repo declares: `.claude/agents/<name>.md`,
      *  whose system prompt points at `brief` (an md file holding the standing
      *  review framing — one home, shared across repos). `tools` overrides the
      *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
      *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
-     *  mandated reviewer. */
+     *  declared reviewer. */
     reviewer?: { name: string; brief: string; tools?: string[] }
     /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
      *  repo keeps as a direct tool call. Declared per NAME, never as a list of
@@ -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,