rvlib-shipkit 0.37.0 → 0.38.0

package/src/rules/SK004-gitignore-policy.ts

@@ -7,6 +7,7 @@
 // PLACE — lines below it (e.g. a live venue's `!.rv-itch/` override, where
 // last-match-wins) keep their position; everything outside the block is
 // never touched. `shipkit init` writes the same block through this fixer.
+import { execFileSync } from 'child_process'
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
@@ -58,6 +59,60 @@ export function policyPatterns(config: RepoConfig): string[] {
     return [...POLICY_LINES.filter((l) => !l.startsWith('#')), ...(config.gitignore ?? [])]
 }
 
+// the three venue folders are DESIGNED to be unignored below the block once a
+// listing is live (last-match-wins, the comment inside POLICY_LINES says so),
+// so an override on one of them is the mechanism working. Every other policy
+// path is a claim the block makes, and a claim git contradicts is a bug.
+function endsWithNewline(root: string): boolean {
+    const p = join(root, '.gitignore')
+    if (!existsSync(p)) return true
+    const text = readFileSync(p, 'utf8')
+    return text === '' || text.endsWith('\n')
+}
+
+const OVERRIDABLE = new Set(['.rv-itch/', '.rv-steam/', '.rv-discord/'])
+
+/** a path git can be asked about, for a pattern that may be a glob or a dir */
+function probePath(pattern: string): string {
+    if (pattern.endsWith('/')) return `${pattern}probe`
+    // `.*.tmp-*` and `*.loras.local.txt`: a literal standing in for the glob
+    return pattern.includes('*') ? pattern.replace(/\*/g, 'probe') : pattern
+}
+
+/** which of `paths` git does NOT ignore. null when this is not a git repo, so
+ *  a rule can say it did not measure rather than report a green it invented */
+export function notIgnored(root: string, paths: string[]): string[] | null {
+    if (paths.length === 0) return []
+    try {
+        // --stdin -z -n: one call, every path, and `-n` makes git print a row
+        // for the MISSES too, which is the answer we want
+        const out = execFileSync('git', ['check-ignore', '--stdin', '-z', '-n', '-v'], {
+            cwd: root, input: paths.join('\0'), encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        // -v -z rows are source\0line\0pattern\0path; an unignored path has an
+        // empty source and an empty pattern
+        const f = out.split('\0')
+        const miss: string[] = []
+        for (let i = 0; i + 3 < f.length + 1; i += 4) {
+            if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
+        }
+        return miss
+    } catch (e) {
+        // exit 1 means "none of them are ignored", which is an ANSWER, and git
+        // still wrote the rows we parse. Anything else (no repo, no git) is not
+        const err = e as { status?: number; stdout?: string }
+        if (err.status === 1 && typeof err.stdout === 'string') {
+            const f = err.stdout.split('\0')
+            const miss: string[] = []
+            for (let i = 0; i + 3 < f.length + 1; i += 4) {
+                if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
+            }
+            return miss
+        }
+        return null
+    }
+}
+
 type Parsed = { text: string; crlf: boolean; lines: string[]; b: number; e: number }
 
 function parse(root: string): Parsed | null {
@@ -122,11 +177,48 @@ export const gitignorePolicy: Rule = {
             case 'missing-block': return t.fail('.gitignore has no shipkit policy block — contract surfaces can leak into git')
             case 'corrupted': return t.fail('.gitignore policy block corrupted (unpaired marker)')
             case 'stale': return t.fail('.gitignore policy block is stale — the policy or repo-contributed lines moved since it was written')
-            case 'current': return t.ok(`.gitignore policy block current (${policyPatterns(env.config).length} patterns)`)
         }
+        // an unterminated last line is a TRAP, not a cosmetic defect: the next
+        // `>> .gitignore` fuses onto it and the result is one pattern that
+        // ignores neither path, with the file ending in a newline afterwards
+        // so nothing textual looks wrong
+        if (!endsWithNewline(env.root)) {
+            t.fail('.gitignore does not end with a newline — the next append fuses onto its last line and ignores neither path')
+            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) terminates it' })
+            return
+        }
+        // the block states what must be ignored. git is the only thing that
+        // knows whether it IS: a stray negation below the block, or a line
+        // fused into another, leaves the text current over a broken repo
+        const claimed = policyPatterns(env.config).filter((p) => !OVERRIDABLE.has(p))
+        const probes = new Map(claimed.map((p) => [probePath(p), p]))
+        const miss = notIgnored(env.root, [...probes.keys()])
+        if (miss == null) {
+            // not a git repo (a fixture, or a dir before `git init`). Say the
+            // verification did not run rather than reporting a green nothing
+            // measured, and stay quiet: there is nothing wrong here to fix
+            t.ok(`.gitignore policy block current (${claimed.length} patterns)`)
+            t.lines.push({ kind: 'skip', text: 'not a git repo here, so nothing verified the block against what git actually ignores' })
+            return
+        }
+        if (miss.length > 0) {
+            const names = [...new Set(miss.map((m) => probes.get(m) ?? m))]
+            t.fail(`.gitignore block claims ${names.join(', ')} ignored, git says otherwise — a negation below the block, or a line fused into its neighbour`)
+            t.lines.push({ kind: 'fix-fail', text: `git check-ignore -v ${miss[0]} names the line that wins` })
+            return
+        }
+        t.ok(`.gitignore policy block current, ${claimed.length} patterns verified against git`)
     },
     fix: (env: RuleEnv): FixResult => {
         const before = blockState(env.root, env.config)
+        // terminate an unterminated file even when the block itself is current:
+        // that missing byte is what the next append fuses onto
+        let terminated: string | null = null
+        if (before === 'current' && !endsWithNewline(env.root)) {
+            const p = join(env.root, '.gitignore')
+            atomicWrite(p, `${readFileSync(p, 'utf8')}\n`)
+            terminated = '.gitignore terminated with a newline (the next append would have fused onto its last line)'
+        }
         const blockSummary = before === 'current'
             ? null
             : before === 'missing-file' ? '.gitignore created with the policy block'
@@ -137,10 +229,10 @@ export const gitignorePolicy: Rule = {
         // the block must be written FIRST: untracking a path the ignore list
         // does not yet carry leaves it staged for re-add on the next `git add`
         const un = untrackGenerated(env.root, { enabled: env.config.untrackGenerated })
-        const parts = [blockSummary]
+        const parts = [blockSummary, terminated]
         if (un.did === 'untracked') parts.push(`untracked ${un.paths.join(', ')} (generated, now gitignored, committed as ${un.commit})`)
         if (un.did === 'refused') parts.push(`left ${trackedGeneratedPaths(env.root).join(', ')} tracked: ${un.why}`)
         const summary = parts.filter((x): x is string => x != null).join(' · ')
-        return { changed: blockSummary != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
+        return { changed: blockSummary != null || terminated != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
     },
 }

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/SK008-reviewer-agent.ts

@@ -1,4 +1,4 @@
-// SK008 — the mandated reviewer agent type. A repo that declares
+// SK008 — the declared reviewer agent type. A repo that declares
 // `reviewer: { name, brief }` must carry `.claude/agents/<name>.md`: an agent
 // definition whose system prompt POINTS at the brief file (ONE home for the
 // text, so review framing can never drift per repo) and whose `tools:` line
@@ -50,7 +50,7 @@ export function briefMissing(root: string, brief: string): boolean {
 function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
     return `---
 name: ${reviewer.name}
-description: The mandated critical reviewer for this repo. Use before every commit, and whenever a diff needs judging against what was actually asked for. Judges whether a change should exist at all, not just whether it is correct.
+description: The critical reviewer for this repo. Whether a review is worth its wall clock is the session's call: reach for it on code whose failure the gate cannot see, and tell it to verify by running rather than to opine. Judges whether a change should exist at all, not just whether it is correct.
 tools: ${(reviewer.tools ?? REVIEWER_TOOLS).join(', ')}
 model: opus
 ---
@@ -82,7 +82,7 @@ export const reviewerAgent: Rule = {
         const rel = reviewerAgentPath(r.name)
         const p = join(env.root, rel)
         if (briefMissing(env.root, r.brief)) t.fail(`the declared brief '${r.brief}' does not exist — every review's mandated first action would fail`)
-        if (!existsSync(p)) return t.fail(`${rel} missing — the mandated reviewer type is unavailable, so every review runs on whatever framing the spawner improvised`)
+        if (!existsSync(p)) return t.fail(`${rel} missing — the declared reviewer type is unavailable, so any review runs on whatever framing the spawner improvised`)
         const issues = reviewerAgentIssues(readFileSync(p, 'utf8'), r)
         for (const i of issues) t.fail(`${rel}: ${i}`)
         if (issues.length === 0 && !t.failed) t.ok(`${rel} → ${r.brief}`)

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/SK013-one-way-in-policy.ts

@@ -13,7 +13,7 @@
 // TRACKED on purpose: `.claude/settings.local.json` is gitignored by the house
 // scaffold, so a policy written there would bind exactly one checkout.
 import { existsSync, mkdirSync, readFileSync } from 'fs'
-import { dirname, join } from 'path'
+import { dirname, isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -36,19 +36,30 @@ export function exemptSlots(c: RepoConfig): Set<string> {
     return off
 }
 
-/** how the hook invokes the guard. `$CLAUDE_PROJECT_DIR` because a hook's cwd
- *  is not promised to be the repo root */
+/** how the hook invokes the guard. A relative path hangs off
+ *  `$CLAUDE_PROJECT_DIR` because a hook's cwd is not promised to be the repo
+ *  root, and an absolute one stands alone */
 export function guardCommand(bin?: string): string {
     const path = bin == null
         ? 'node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts'
         : bin.replace(/cli\.ts$/, 'hooks/one-way-in-guard.ts')
-    return `bun "$CLAUDE_PROJECT_DIR/${path}"`
+    return isAbsolute(path) ? `bun "${path}"` : `bun "$CLAUDE_PROJECT_DIR/${path}"`
 }
 
-/** a guard under `node_modules/` that is not there yet says the dependency is
- *  not installed, which `bun install` fixes and no edit to this repo can. Any
- *  other unresolvable path is a config this repo chose and got wrong. */
-const isUninstalledDep = (rel: string): boolean => rel.startsWith('node_modules/')
+const readPkg = (root: string): { scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null => {
+    try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as never } catch { return null }
+}
+
+const declaresShipkit = (root: string): boolean => {
+    const pkg = readPkg(root)
+    return pkg?.dependencies?.['rvlib-shipkit'] != null || pkg?.devDependencies?.['rvlib-shipkit'] != null
+}
+
+/** a guard under `node_modules/` that is not there yet, in a repo that
+ *  declares rvlib-shipkit, says the dependency is not installed, which
+ *  `bun install` fixes and no edit to this repo can. Without the declaration
+ *  no install ever brings it, so it is a path this repo got wrong like any other. */
+const isUninstalledDep = (root: string, rel: string): boolean => rel.startsWith('node_modules/') && declaresShipkit(root)
 
 const readSettings = (root: string): Settings | null => {
     const p = join(root, SETTINGS_PATH)
@@ -65,21 +76,32 @@ const guardHookCommand = (s: Settings): string | null => {
 
 const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
 
-/** the guard file the hook command points at, resolved against the repo root.
+/** the guard file the hook command points at, resolved against the repo root
+ *  when it hangs off `$CLAUDE_PROJECT_DIR`, as written when it is absolute.
  *  A hook whose script does not exist errors on EVERY Bash call and refuses
  *  nothing, so the agent sees only the bare deny, which is the one failure
  *  this rule exists to prevent. Declaring it and never running it is worse
  *  than not declaring it, so it FAILs. */
 function guardScriptMissing(root: string, command: string): string | null {
-    const m = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)
-    const rel = m?.[1]
-    if (rel == null) return null // a form this rule cannot resolve is not a form it may condemn
-    return existsSync(join(root, rel)) ? null : rel
+    const rel = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)?.[1]
+    if (rel != null) return existsSync(join(root, rel)) ? null : rel
+    const abs = /^bun\s+["']?(\/[^"'\s]+)["']?/.exec(command.trim())?.[1]
+    if (abs != null) return existsSync(abs) ? null : abs
+    return null // a form this rule cannot resolve is not a form it may condemn
 }
 
-const readBin = (root: string): string | undefined => {
-    try { return inferBin((JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}) }
-    catch { return undefined }
+/** the guard the fixer writes: the cli path the scripts run when a guard sits
+ *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
+ *  repo's own dependency, else the copy of shipkit doing the fixing, which is
+ *  the one the launcher falls back to in a repo that has none */
+export function guardCommandFor(root: string): string {
+    const bin = inferBin(readPkg(root)?.scripts ?? {})
+    if (bin != null) {
+        const fromBin = guardCommand(bin)
+        if (guardScriptMissing(root, fromBin) == null) return fromBin
+    }
+    if (declaresShipkit(root)) return guardCommand()
+    return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
 export const oneWayInPolicy: Rule = {
@@ -115,7 +137,7 @@ export const oneWayInPolicy: Rule = {
             // that fixes it, not a red gate on a repo nobody has installed yet,
             // and the deny list is the floor throughout. A path this repo chose
             // and got wrong is still a FAIL: it will never resolve on its own.
-            if (missing != null && isUninstalledDep(missing))
+            if (missing != null && isUninstalledDep(env.root, missing))
                 t.warn(
                     `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which is not installed yet — until then a refusal names no replacement, and the deny list is the whole floor`,
                     `bun install (or bun add -d rvlib-shipkit)`,
@@ -149,10 +171,24 @@ export const oneWayInPolicy: Rule = {
             s.permissions = { ...s.permissions, deny: [...deny, ...added] }
             changes.push(`${added.length} raw runner(s) denied`)
         }
+        const wantGuard = guardCommandFor(env.root)
         if (!hasGuardHook(s)) {
             const pre = s.hooks?.['PreToolUse'] ?? []
-            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: guardCommand(readBin(env.root)) }] }] }
+            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: wantGuard }] }] }
             changes.push('PreToolUse guard wired (every refusal names the shipkit command)')
+        } else {
+            // a guard that cannot run errors on every Bash call, so it is repointed
+            // at the copy this repo runs. One that resolves, or waits on a declared
+            // install, is the repo's choice and stays as written
+            for (const m of s.hooks?.['PreToolUse'] ?? [])
+                for (const h of m.hooks ?? []) {
+                    if (h.command?.includes('one-way-in-guard') !== true) continue
+                    const missing = guardScriptMissing(env.root, h.command)
+                    if (missing == null || isUninstalledDep(env.root, missing) || h.command === wantGuard) continue
+                    if (guardScriptMissing(env.root, wantGuard) != null) continue
+                    changes.push(`PreToolUse guard repointed from ${missing}, which does not exist`)
+                    h.command = wantGuard
+                }
         }
         if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
         mkdirSync(dirname(p), { recursive: true })

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,143 @@
+// 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']
+
+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'
+    let i = 0
+    for (; i < argv.length && argv[i] !== '--'; i++) {
+        const flag = argv[i]!
+        const value = argv[i + 1]
+        if (value == null || value === '--') return `${flag} needs a value`
+        i++
+        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 if (flag === '--declared-in') declaredIn = value
+        else return `unknown flag ${flag}`
+    }
+    if (!(tests.budgetMs > 0)) return '--budget-ms must be a positive number'
+    return { tests, rawArgs: argv.slice(i + 1), 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
+}