rvlib-shipkit 1.9.0 → 2.0.1

package/src/checks/SK019-tests-run-in-units.check.ts

@@ -15,6 +15,7 @@ import { check } from '../check.ts'
 import { repoCheckSources } from '../core/legacy-shapes.ts'
 import { argvRunsTests, commandRunsTests, sourceRunsTests, type ScriptReader } from '../suite/runner-shapes.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
+import { repoOff } from '../core/when.ts'
 
 /** the scripts of the package.json in `dir` (repo relative), then the root's */
 const scriptsIn = (c: CheckCtx, dir: string): ScriptReader => {
@@ -67,7 +68,7 @@ export const testsRunInUnits = check({
         }
         // a slot the package.json fills: its raw body, else its own script
         for (const id of OTHER_SLOTS) {
-            if (defaults[id] === false || (defaults[id] as { cmd?: unknown } | undefined)?.cmd != null) continue
+            if (repoOff(c.config, id) != null || (defaults[id] as { cmd?: unknown } | undefined)?.cmd != null) continue
             const name = root(`${id}:raw`) != null ? `${id}:raw` : id
             const body = root(name)
             const how = body == null ? null : commandRunsTests(body, (n) => (n === name ? null : root(n)))

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -30,9 +30,12 @@ export const agentWikiLinks = check({
         for (const f of orphans) {
             const by = namingPage(c.root, f, linked)
             const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
-            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)
+            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`, { at: { file: `agent/${f}` } })
+        }
+        for (const d of lint.dangling) {
+            const file = `agent/${d.from}`
+            c.fail(`${file}:${d.line}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`, { at: { file, line: d.line } })
         }
-        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`)
         if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
     },
 })

package/src/checks/SK029-explicit-check-files.check.ts

@@ -5,28 +5,44 @@
 // keys resolved to (core/port-check-file.ts), so the check keeps running
 // where it ran, and the ci fix pass applies it before the gate reads the
 // files: a repo carried across by its first `shipkit ci`. The same holds for
-// the config: a retired `when` (only its `off:<why>` entries still load) and
-// `ruleExempt` become `off` entries in the managed block.
+// the config: a retired `when` (only its `off:<why>` entries still load),
+// `ruleExempt`, `hooks.disable` and a `defaults` slot set to false become
+// `off` entries in the managed block.
 import { join } from 'path'
 import { check, type FixResult } from '../check.ts'
 import { unportedCheckFiles } from '../core/port-check-files.ts'
 import type { PortRun } from '../core/port-check-cli.ts'
 import type { ConfigPlan, ConfigRewrite } from '../core/config-rewrite.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { legacyOffReason } from '../core/when.ts'
 
 /** the write half, run as its own process: it walks import closures on disk */
 const PORT_CLI = join(import.meta.dir, '../core/port-check-cli.ts')
 /** the config half, run as its own process: it loads repo.config.ts */
 const CONFIG_REWRITE = join(import.meta.dir, '../core/config-rewrite.ts')
 
-/** the retired config keys this repo still carries, and the `off` entries
- *  they become. defineRepo already refused every `when` word but `off:<why>` */
-export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string> } {
+/** the retired config spellings this repo still carries, and the `off`
+ *  entries they become. defineRepo already refused every `when` word but
+ *  `off:<why>`. `hooks.disable` and a `defaults` slot set to false never said
+ *  why, so they are lifted with the comment above them, else with a reason
+ *  that says none was recorded (core/when.ts legacyOffReason) */
+export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string>; lift: NonNullable<ConfigPlan['lift']> } {
     const off: Record<string, string> = {}
     for (const [id, raw] of Object.entries(c.when ?? {})) off[id] = raw.trim().replace(/^off:?/, '').trim()
     for (const [id, why] of Object.entries(c.ruleExempt ?? {})) off[id] ??= why
-    const keys = [...(c.when != null ? ['when'] : []), ...(c.ruleExempt != null ? ['ruleExempt'] : [])]
-    return { keys, off }
+    const lift: NonNullable<ConfigPlan['lift']> = []
+    const disable = c.hooks?.disable ?? []
+    if (c.hooks?.disable != null)
+        lift.push({ parent: 'hooks', entry: 'disable', value: '\\[[^\\]\\[]*\\]', ids: disable, reason: Object.fromEntries(disable.map((id) => [id, legacyOffReason('hooks.disable', id)])) })
+    const slots = Object.entries(c.defaults ?? {}).filter(([, d]) => d === false).map(([id]) => id)
+    for (const id of slots) lift.push({ parent: 'defaults', entry: id, value: 'false', ids: [id], reason: { [id]: legacyOffReason('defaults', id) } })
+    const keys = [
+        ...(c.when != null ? ['when'] : []),
+        ...(c.ruleExempt != null ? ['ruleExempt'] : []),
+        ...(c.hooks?.disable != null ? ['hooks.disable'] : []),
+        ...slots.map((id) => `defaults.${id}: false`),
+    ]
+    return { keys, off, lift }
 }
 
 export const explicitCheckFiles = check({
@@ -76,6 +92,7 @@ export const explicitCheckFiles = check({
                     ...(c.config.ruleExempt != null ? [{ key: 'ruleExempt', why: 'its exemptions are `off` now', phase: 'afterOff' as const }] : []),
                 ],
                 name: c.config.name,
+                lift: cfg.lift,
             }
             const r = await c.exec([process.execPath, CONFIG_REWRITE, c.root, JSON.stringify(plan)], { cwd: c.root, timeoutMs: 60_000 })
             try {
@@ -84,7 +101,7 @@ export const explicitCheckFiles = check({
                 hand.push(...out.hand)
                 if (out.restored != null) hand.push(`repo.config.ts was left as it was: ${out.restored}`)
             } catch {
-                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify(cfg.off)} by hand and drop ${cfg.keys.join(', ')}`)
+                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify({ ...Object.assign({}, ...cfg.lift.map((l) => l.reason)), ...cfg.off })} by hand and drop ${cfg.keys.join(', ')}`)
             }
         }
         const summary = [did.length > 0 ? did.join('; ') : 'nothing ported', ...(hand.length > 0 ? [`${hand.length} by hand: ${hand.join(' | ')}`] : [])].join('. ')

package/src/checks/SK034-commit-gates-armed.check.ts

@@ -0,0 +1,90 @@
+// SK034 commit gates armed (build/shipkit/commit-gates.md): the leak guard and
+// the message gate run only from git's hooks, so a repo whose hooksPath is
+// unset, or points at a foreign dir that never calls shipkit, commits with
+// both dark and nothing says so. `sk ci` arms an unset path; a foreign one is
+// the repo's own, so the check names the line to chain into it.
+import { readFileSync } from 'fs'
+import { isAbsolute, join } from 'path'
+import { nestedIn } from '../core/nesting.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
+import { LAYOUT } from '../core/layout.ts'
+import { check, type CheckEnv } from '../check.ts'
+import { hookBinInvocation } from '../hooks/run-hooks.ts'
+
+const HOOKS = [
+    { name: 'pre-commit', arg: '', guards: 'the leak guard' },
+    { name: 'commit-msg', arg: ' "$1"', guards: 'the message gate' },
+] as const
+
+const readOrNull = (abs: string): string | null => {
+    try {
+        return readFileSync(abs, 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** a hook body that runs the shipkit gate: a live line (never a comment)
+ *  whose failure is not swallowed by `|| true` */
+export const chainsShipkit = (body: string, hook: string): boolean =>
+    body.split('\n').some((l) => !l.trim().startsWith('#') && new RegExp(`\\bhooks\\s+${hook}\\b`).test(l) && !/\|\|\s*(?:true|:)\b/.test(l))
+
+/** the line to paste into a foreign hook: a clone with no install skips the
+ *  gate with a note, rather than failing every commit */
+export const guardedChain = (bin: string, hook: string, arg: string): string => {
+    const cli = bin.replace(/^bun\s+/, '')
+    return `if [ -f ${cli} ]; then ${bin} hooks ${hook}${arg} || exit 1; else echo "${hook}: rvlib-shipkit not installed (run bun install), shipkit gate skipped" >&2; fi`
+}
+
+const hooksDir = (root: string): string => {
+    const p = Bun.spawnSync([gitBin(), 'config', 'core.hooksPath'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    return p.exitCode === 0 ? p.stdout.toString().trim() : ''
+}
+
+/** the hooksPath and the two hook files it points at. A commit moves none */
+export function gatesKey(env: CheckEnv): string {
+    const nested = nestedIn(env.root)
+    if (nested != null) return `nested in ${nested}`
+    const dir = hooksDir(env.root)
+    if (dir === '') return 'hooks='
+    const at = (h: string): string => fileStamp(isAbsolute(dir) ? join(dir, h) : join(env.root, dir, h))
+    return `hooks=${dir}|${HOOKS.map((h) => `${h.name}=${at(h.name)}`).join('|')}`
+}
+
+export const commitGatesArmed = check({
+    id: 'SK034',
+    blocking: true,
+    title: 'commit gates armed',
+    description: 'git runs the shipkit pre-commit and commit-msg gates on every commit',
+    owner: 'build/shipkit/commit-gates.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // git config and hook files outside any tree id, so they are the key
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: gatesKey },
+    fix: 'none',
+    applies: 'always',
+    run: async (c) => {
+        const nested = nestedIn(c.root)
+        if (nested != null) return void c.lines.push({ kind: 'skip', text: `commit gates not checked, nested in ${nested}: the parent repo owns them` })
+        const top = await c.exec(['git', 'rev-parse', '--show-toplevel'], { cwd: c.root })
+        if (top.code !== 0) return void c.lines.push({ kind: 'skip', text: 'not a git repo: no commit to guard yet' })
+        const hp = await c.exec(['git', 'config', 'core.hooksPath'], { cwd: c.root })
+        const dir = hp.code === 0 ? hp.out.trim() : ''
+        if (dir === '' && process.env['CI'] != null && process.env['CI'] !== '')
+            return void c.lines.push({ kind: 'skip', text: 'commit gates not armed in this CI checkout: a CI run makes no commit, and the fix pass arms hooks on a machine only' })
+        if (dir === '') return void c.fail('the commit gates are not armed, so a commit runs no leak guard and no message gate: run `shipkit hooks install` (`shipkit ci` arms them too)')
+        const own = dir === LAYOUT.hooks
+        const bin = hookBinInvocation(c.root)
+        for (const h of HOOKS) {
+            const body = isAbsolute(dir) ? readOrNull(join(dir, h.name)) : c.read(`${dir}/${h.name}`)
+            if (body == null)
+                c.fail(`core.hooksPath=${dir} has no ${h.name}, so ${h.guards} never runs: ${own ? 'run `shipkit hooks install`' : `add one that runs \`${guardedChain(bin, h.name, h.arg)}\``}`)
+            else if (!chainsShipkit(body, h.name))
+                c.fail(`core.hooksPath=${dir}: its ${h.name} does not run the shipkit gate, so ${h.guards} never runs: add \`${guardedChain(bin, h.name, h.arg)}\` above its last line`)
+        }
+        if (!c.failed) c.ok(`git runs the shipkit commit gates (${own ? dir : `${dir}, chained to shipkit`})`)
+    },
+})
+
+export default commitGatesArmed

package/src/cli/cmd_Ci.ts

@@ -14,14 +14,14 @@ export class CiCommand extends Command {
     static override usage = Command.Usage({
         category: 'Gate',
         description: 'THE gate: repairs what a machine can, then runs every check. Run this, not the parts',
-        details: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
+        details: 'THE command. Repairs what a machine can (imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
             ['full gate, mechanical fixes applied', 'sk ci'],
             ['gate without the repair pass (checks can still write)', 'sk ci --no-fix'],
             ['leave repo config files alone', 'sk ci --no-fix-rules'],
             ['stop at the first failure', 'sk ci --bail'],
             ['one check + its dep closure, the tree left alone', 'sk ci --only typecheck'],
-            ['one check, repairing the mechanical slots first', 'sk ci --only typecheck --fix'],
+            ['one check, its own repair first', 'sk ci --only SK004 --fix'],
             ['every check declaring one group', 'sk ci --only wiki'],
             ['run everything, take nothing from the cache', 'sk ci --fresh'],
             ['include an opt in check', 'sk ci --with up:itch'],
@@ -32,7 +32,7 @@ export class CiCommand extends Command {
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
-    fix = Option.Boolean('--fix', { description: 'repair the mechanical slots before gating. Default on for a whole gate and off for a --only run, which leaves the tree alone unless --fix is named. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fix = Option.Boolean('--fix', { description: 'repair before gating. Default on for a whole gate and off for a --only run, which leaves the tree alone unless --fix is named, and then repairs only what the named checks own. Nothing ever formats. --no-fix skips the repair pass, the checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
     fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural autofixes of the built-in checks too. Default on. --no-fix-rules leaves repo config alone' })
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining checks: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
     skip = Option.Array('--skip', [], { description: 'skip a check group (repeatable)' })

package/src/cli/cmd_Commands.ts

@@ -71,6 +71,20 @@ export function renderMarkdown(rows: CommandRow[]): string {
     return out.join('\n').trim()
 }
 
+/** the eager form: one line per command, its positional arguments and its
+ *  description. Flags and examples are `sk <command> --help`, so a page every
+ *  session loads costs a line per command, not a screen */
+export function renderCompact(rows: CommandRow[]): string {
+    const out: string[] = []
+    let cat = ''
+    for (const r of rows) {
+        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
+        const sig = r.usage.replace(/^\$0/, 'sk').replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `sk ${r.path}`
+        out.push(`- \`${sig}\` — ${r.description}`)
+    }
+    return out.join('\n').trim()
+}
+
 export const BEGIN = '<!-- shipkit:commands -->'
 export const END = '<!-- /shipkit:commands -->'
 
@@ -89,14 +103,16 @@ export class CommandsCommand extends Command {
         examples: [
             ['markdown index', 'sk commands'],
             ['machine-readable', 'sk commands --json'],
-            ['write into a docs page between the markers', 'sk commands --out wiki/build/shipkit-cli.md'],
-            ['fail if that page is stale (lint mode)', 'sk commands --out wiki/build/shipkit-cli.md --check'],
+            ['write into a docs page between the markers', 'sk commands --out docs/commands.md'],
+            ['one line per command, for a page every session loads', 'sk commands --compact --out wiki/build/shipkit-cli.md'],
+            ['fail if that page is stale (lint mode)', 'sk commands --compact --out wiki/build/shipkit-cli.md --check'],
         ],
     })
 
     json = Option.Boolean('--json', false, { description: 'machine-readable [{path, category, description}]' })
     out = Option.String('--out', { description: 'host file carrying the shipkit:commands markers. The block between them is rewritten' })
     check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
+    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `sk <command> --help`)' })
 
     async execute(): Promise<number> {
         const rows = commandRows(
@@ -104,18 +120,18 @@ export class CommandsCommand extends Command {
             (this.cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }),
         )
         if (this.out == null) {
-            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${renderMarkdown(rows)}\n`)
+            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows)}\n`)
             return 0
         }
         const { existsSync, readFileSync, writeFileSync } = await import('fs')
         if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
         const host = readFileSync(this.out, 'utf8')
-        const next = spliceBlock(host, renderMarkdown(rows))
+        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows))
         if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
         if (next === host) { this.context.stdout.write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return 0 }
         if (this.check) {
             this.context.stdout.write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
-            this.context.stdout.write(`      fix: shipkit commands --out ${this.out}\n`)
+            this.context.stdout.write(`      fix: shipkit commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
             return 1
         }
         writeFileSync(this.out, next)

package/src/cli/cmd_Hooks.ts

@@ -4,9 +4,13 @@ import { Command, Option } from 'clipanion'
 import { hookBinInvocation, installHooks, listGates, preCommitChecks, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
+// a gate that passed prints only what still needs a reader (a WARN, a waived
+// hit), so a clean commit costs one line, not one per gate
 const report = (out: GateOutcome[], write: (s: string) => void): number => {
-    for (const g of out) for (const l of g.lines) write(`${l}\n`)
-    return out.every((g) => g.ok) ? 0 : 1
+    for (const g of out) for (const l of g.lines) if (!g.ok || !l.startsWith('ok: ')) write(`${l}\n`)
+    const ok = out.every((g) => g.ok)
+    if (ok) write(`ok: ${out.length} commit gate(s) clean\n`)
+    return ok ? 0 : 1
 }
 
 export class HooksInstallCommand extends Command {

package/src/cli/cmd_Init.ts

@@ -8,7 +8,7 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'wire the current directory as a shipkit repo, like git init',
+        description: 'wire this dir as a shipkit repo, like git init: a private github repo and a push unless --no-github',
         details: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts + the create-only .vscode/ that starts the watchers and the hub on folder open, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
         examples: [
             ['wire the repo you are standing in', 'sk init'],

package/src/cli/cmd_Serve.ts

@@ -1,5 +1,4 @@
-// shipkit serve — the ONE hub server per repo (one vscode folder-open task,
-// clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
+// shipkit serve — the ONE hub server per repo (clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
 import { Command, Option } from 'clipanion'
 
 export class ServeCommand extends Command {

package/src/cli/cmd_Start.ts

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create or enter ~/dev/<name> from anywhere, ready to work in',
+        description: 'create or enter ~/dev/<name>, ready to work in: a private github repo and a push unless --no-github',
         details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],

package/src/cli.ts

@@ -26,7 +26,6 @@ import { KeysCommand } from './cli/cmd_Keys.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { PbCollectionCommand } from './cli/cmd_Pb.ts'
-import { ProseCommand } from './cli/cmd_Prose.ts'
 import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
@@ -91,7 +90,6 @@ export function buildCli(): Cli {
     cli.register(NeedsCommand)
     cli.register(FleetCommand)
     cli.register(PbCollectionCommand)
-    cli.register(ProseCommand)
     cli.register(SmokeCommand)
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
@@ -125,8 +123,8 @@ if (import.meta.main) {
     const argv = aliasArgs(process.argv.slice(2))
     const { handoff } = await import('./home/handoff.ts')
     handoff(argv)
-    const { useOneLib } = await import('./core/one-lib.ts')
-    useOneLib()
+    const { installOneLib } = await import('./core/one-lib.ts')
+    installOneLib()
     const { autostart } = await import('./home/autostart.ts')
     await autostart(argv)
     void buildCli().runExit(argv)

package/src/core/budget.ts

@@ -6,16 +6,14 @@
 import { availableParallelism, loadavg } from 'os'
 import type { MachineLoad } from '../suite/judge-suites.ts'
 
-/** an in process body, a rule or a page check. Read off a run record of 64
- *  such checks: the median rule answers in under 50ms, 55 of them stay under
- *  2s at their 90th percentile, and the few past it shell out to a tool */
-export const IN_PROCESS_BUDGET_MS = 2_000
+/** an in process body, a rule or a page check: the house bar is under 1 s
+ *  (identity/how-we-work.md, Velocity). The median rule answers in under 50ms */
+export const IN_PROCESS_BUDGET_MS = 1_000
 
 /** a subprocess (a build step, a test suite, a `cmd` check) or a world probe
- *  (a `ttl` check, or a `never:` one, whose answer lives outside the repo).
- *  Read off the same record: every typecheck stays under 6s at its 90th
- *  percentile, and the quick test suites under 6s but one */
-export const SUBPROCESS_BUDGET_MS = 10_000
+ *  (a `ttl` check, or a `never:` one, whose answer lives outside the repo):
+ *  the house ceiling is 5 s, and one over it is a defect to fix */
+export const SUBPROCESS_BUDGET_MS = 5_000
 
 /** what a check declares about itself that picks its default. `world`: it
  *  declares `ttl` or `never`, so it reads the world rather than the repo */

package/src/core/bun-builtins.ts

@@ -0,0 +1,36 @@
+// bun's own linter as the default lint slot, and bun's formatter as the
+// manual `bun fmt` (never a gate step). A repo opts in by declaring the tool's
+// section in bunfig.toml: the section is where its config lives.
+//
+// bun before 1.4.4 has neither command, and there `bun lint` falls through to
+// the package.json `lint` script. A script that calls `bun lint` then calls
+// itself forever, so an old bun gets a loud refusal instead of a spawn. The
+// lint slot runs through core/bun-tool-cli.ts, which keeps a same-named script out.
+import { fileURLToPath } from 'url'
+
+export type BunTool = 'lint' | 'fmt'
+
+export const BUN_TOOLS_SINCE = '1.4.4'
+
+/** does the bun running shipkit ship `bun lint` and `bun fmt` */
+export const bunHasTools = (version: string = Bun.version): boolean => Bun.semver.order(version.replace(/-.*$/, ''), BUN_TOOLS_SINCE) >= 0
+
+const header = (tool: BunTool): RegExp => new RegExp(`^\\s*\\[${tool}(?:\\.[^\\]]+)?\\]\\s*(?:#.*)?$`)
+
+/** does this bunfig.toml text declare `[lint]` / `[fmt]` (or a subtable of it) */
+export function bunfigDeclares(bunfig: string | null, tool: BunTool): boolean {
+    return bunfig != null && bunfig.split('\n').some((l) => header(tool).test(l))
+}
+
+/** why this bun cannot run the tool, or null when it can */
+export function bunToolRefusal(tool: BunTool, version: string = Bun.version): string | null {
+    return bunHasTools(version) ? null : `bunfig.toml declares [${tool}] and bun ${version} has no \`bun ${tool}\` (it ships in ${BUN_TOOLS_SINCE}): run \`bun upgrade --canary\``
+}
+
+/** the argv the lint slot runs: the built-in, through the runner that keeps a
+ *  same-named package.json script out of its way. The repo's vendored dirs
+ *  are never walked */
+export function bunLintCmd(vendored: readonly string[] = []): string[] {
+    const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/core/bun-tool-cli.ts'))
+    return [process.execPath, cli, 'lint', '--format', 'unix', ...vendored.map((d) => `--ignore-pattern=${d}/**`)]
+}

package/src/core/bun-tool-cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+// runs `bun lint` as the BUILT-IN, whatever package.json holds.
+// bun runs a script of the same name in its place, flags and all, unless the
+// call says it is that script: `npm_lifecycle_event` names the tool, and
+// `npm_package_json` is absent or names this manifest by its resolved path.
+// A run started under another package's `bun run` inherits that package's
+// path, so it is dropped here (measured, bun 1.4.4).
+import { bunToolRefusal } from './bun-builtins.ts'
+
+const [tool, ...args] = process.argv.slice(2)
+if (tool !== 'lint') {
+    console.error(`bun-tool-cli: expected lint, got ${tool ?? 'nothing'}`)
+    process.exit(2)
+}
+const refused = bunToolRefusal(tool)
+if (refused != null) {
+    console.error(refused)
+    process.exit(1)
+}
+const env: Record<string, string | undefined> = { ...process.env, npm_lifecycle_event: tool }
+delete env.npm_package_json
+const p = Bun.spawnSync([process.execPath, tool, ...args], { stdio: ['inherit', 'inherit', 'inherit'], env })
+process.exit(p.exitCode ?? 1)

package/src/core/canonical-scripts.ts

@@ -36,10 +36,12 @@ export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, strin
 // used to hold moves to `<name>:raw`, which is what shipkit itself runs and
 // what an agent uses to iterate on one repro file.
 //
-// only these three. `imports:check` and `cycles` are shipkit's own vocabulary
-// (nobody reaches for them by reflex) and `fmt` is the slot shipkit's fix pass
-// invokes, so routing it would make the fixer call itself.
-export const ROUTED_SCRIPTS = ['test', 'lint', 'typecheck'] as const
+// only these two. `imports:check` and `cycles` are shipkit's own vocabulary
+// (nobody reaches for them by reflex), `fmt` is a manual tool no gate runs,
+// and `lint` is
+// `bun lint` itself: a `lint` script would shadow the built-in, which lints a
+// whole repo in well under a second, with nothing for a cache to save.
+export const ROUTED_SCRIPTS = ['test', 'typecheck'] as const
 
 export const RAW_SUFFIX = ':raw'
 

package/src/core/check-ctx.ts

@@ -1,7 +1,8 @@
 // CheckCtx — the ONE parameter a check body receives, and its only door to the
 // repo. Four parts:
 //
-//   report  c.ok / note / warn / fail / unreachable, the wire lines (wire.ts)
+//   report  c.ok / note / warn / fail / unreachable, the wire lines (wire.ts),
+//           a finding with its site, which an in-file directive can waive
 //   where   c.root, c.config, c.frozen
 //   reads   c.read / json / exists / isLink / list / entries, each recorded with what it saw, and
 //           c.use(scan) for a scan every check of the pass shares (scan.ts)
@@ -27,7 +28,12 @@ import { normalizeInput, WHOLE_TREE } from '../ledger/git-scan.ts'
 import { shipkitRoot } from './git-root.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Scan } from '../scan.ts'
-import type { Line } from './wire.ts'
+import { siteText, type Line, type Site } from './wire.ts'
+import { DIRECTIVE_MARK, parseDirectives, reaches, spell, type Directive } from './waivers.ts'
+
+/** what `c.warn` and `c.fail` take after the message: the fix pointer alone,
+ *  or the pointer and the site the finding sits at */
+export type FindingMore = string | { fix?: string; at?: Site }
 
 // thrown by t.fetch on 429: no answer, so the body runner (check.ts
 // runCheckBody) reports it as unreachable, never as a FAIL. It knows it by
@@ -56,6 +62,16 @@ export class CheckCtx {
     /** why the reads cannot describe this answer (it reached the world), null
      *  while they can */
     untracked: string | null = null
+    /** the check this context reports for, set by the body runner. A
+     *  directive waives a site only when it names this id */
+    checkId: string | null = null
+    /** the text of every repo file read here that carries a directive mark,
+     *  by path: what a waiver and the unused directive scan parse */
+    readonly marked = new Map<string, string>()
+    private readonly parsed = new Map<string, Directive[]>()
+    private readonly siteFiles = new Set<string>()
+    private readonly waived: { text: string; at: Site; by: string; reason: string }[] = []
+    private readonly usedDirectives = new Set<string>()
 
     constructor(
         /** the runner pass this body runs in. Absent for a context that only
@@ -73,19 +89,94 @@ export class CheckCtx {
     note(msg: string): void { this.lines.push({ kind: 'note', text: msg }) }
     /** a WARN that came back from something we could not reach — no answer, so
      *  nothing to remember */
-    unreachable(msg: string, fix?: string): void {
+    unreachable(msg: string, more?: FindingMore): void {
         this.unmeasured = true
-        this.warn(msg, fix)
+        this.warn(msg, more)
     }
-    warn(msg: string, fix?: string): void {
+    /** a defect that does not stop you. `more` is the fix pointer, or
+     *  `{ fix, at }` with the site, which a directive in that file can waive */
+    warn(msg: string, more?: FindingMore): void {
+        const f = this.finding(msg, more)
+        if (f == null) return
         this.warned = true
-        this.lines.push({ kind: 'warn', text: msg })
-        if (fix != null) this.lines.push({ kind: 'fix-warn', text: fix })
+        this.lines.push({ kind: 'warn', text: f.text, ...(f.at == null ? {} : { at: f.at }) })
+        if (f.fix != null) this.lines.push({ kind: 'fix-warn', text: f.fix })
     }
-    fail(msg: string, fix?: string): void {
+    /** broken. `more` is the fix pointer, or `{ fix, at }` with the site,
+     *  which a directive in that file can waive */
+    fail(msg: string, more?: FindingMore): void {
+        const f = this.finding(msg, more)
+        if (f == null) return
         this.failed = true
-        this.lines.push({ kind: 'fail', text: msg })
-        if (fix != null) this.lines.push({ kind: 'fix-fail', text: fix })
+        this.lines.push({ kind: 'fail', text: f.text, ...(f.at == null ? {} : { at: f.at }) })
+        if (f.fix != null) this.lines.push({ kind: 'fix-fail', text: f.fix })
+    }
+
+    // ── waivers (core/waivers.ts owns the grammar) ────────────────────────
+    /** the finding as it prints, or null when a directive waived its site.
+     *  A message that does not name its file gets the site in front */
+    private finding(msg: string, more: FindingMore | undefined): { text: string; fix?: string; at?: Site } | null {
+        const { fix, at } = typeof more === 'object' ? more : { fix: more, at: undefined }
+        if (at == null) return { text: msg, fix }
+        const text = msg.includes(at.file) ? msg : `${siteText(at)}: ${msg}`
+        const by = this.waiverFor(at)
+        if (by == null) return { text, fix, at }
+        this.waived.push({ text, at, by: `${at.file}:${by.line}`, reason: by.reason ?? '' })
+        return null
+    }
+    /** the directive that waives this site for this check. The file is read
+     *  through `c`, so it joins the answer's key: a directive added or
+     *  removed afterwards asks the question again */
+    private waiverFor(at: Site): Directive | null {
+        if (this.checkId == null || this.pass == null || isAbsolute(at.file)) return null
+        let rel: string
+        try { rel = this.rel(at.file) } catch { return null }
+        this.siteFiles.add(rel)
+        this.read(rel)
+        for (const d of this.directivesIn(rel)) {
+            if (d.reason == null || !d.ids.includes(this.checkId) || !reaches(d, at.line)) continue
+            this.usedDirectives.add(`${rel}:${d.line}`)
+            return d
+        }
+        return null
+    }
+    private directivesIn(file: string): Directive[] {
+        const text = this.marked.get(file)
+        if (text == null) return []
+        let ds = this.parsed.get(file)
+        if (ds == null) this.parsed.set(file, (ds = this.pass?.directives(file, text) ?? parseDirectives(file, text)))
+        return ds
+    }
+    /** after the body, once: count the waived sites, and WARN on every
+     *  directive naming this check, in a file it read, that waived nothing
+     *  or gave no reason. A directive for a retired id, or in a file no
+     *  check reads any more, is nobody's to report */
+    settleWaivers(): void {
+        const id = this.checkId
+        if (id == null) return
+        const loud = (at: Site, text: string, fix: string): void => {
+            this.warned = true
+            this.lines.push({ kind: 'warn', text: `${siteText(at)}: ${text}`, at }, { kind: 'fix-warn', text: fix })
+        }
+        // a site, not a finding: one line can hold several findings
+        const n = new Set(this.waived.map((w) => siteText(w.at))).size
+        if (n > 0) this.lines.push({ kind: 'skip', text: `${n === 1 ? '1 site waived in its file' : `${n} sites waived in their files`} (--verbose lists them)`, waiver: 'count' })
+        for (const w of this.waived) this.lines.push({ kind: 'skip', text: `waived by ${w.by} (${w.reason}): ${w.text}`, at: w.at, waiver: 'site' })
+        for (const file of this.marked.keys())
+            for (const d of this.directivesIn(file)) {
+                if (!d.ids.includes(id)) continue
+                const at = { file, line: d.line }
+                if (d.reason == null) loud(at, `\`${spell(d, id)}\` gives no reason after \` -- \`, so it waives nothing`, `say why the site is fine: \`${spell(d, id)} -- <reason>\``)
+                else if (!this.usedDirectives.has(`${file}:${d.line}`))
+                    loud(at, `\`${spell(d, id)}\` waives nothing ${d.scope === 'file' ? 'in this file' : `on line ${d.scope === 'line' ? d.line : d.line + 1}`}`, 'delete the directive, or move it onto the site it was written for')
+            }
+    }
+    /** every file whose directives this answer depends on: the files of its
+     *  findings, and the files carrying a directive that names it */
+    waiverFiles(): string[] {
+        const id = this.checkId
+        const named = id == null ? [] : [...this.marked.keys()].filter((f) => this.directivesIn(f).some((d) => d.ids.includes(id)))
+        return [...new Set([...this.siteFiles, ...named])].sort()
     }
 
     // ── where ─────────────────────────────────────────────────────────────
@@ -99,6 +190,7 @@ export class CheckCtx {
      *  it and none that did not */
     get config(): RepoConfig {
         const p = this.repo('config')
+        if (!p.recordsConfig) return p.config
         const deps = p.configReads()
         for (const [f, oid] of deps.files) this.reads.file(f, oid)
         if (deps.untracked != null && this.untracked == null) {
@@ -150,6 +242,7 @@ export class CheckCtx {
             return null
         }
         this.reads.file(p, blobOid(bytes))
+        if (!isAbsolute(p) && bytes.includes(DIRECTIVE_MARK)) this.marked.set(p, bytes.toString('utf8'))
         return bytes
     }
     /** a repo-relative json file, parsed. null when absent, and a parse error
@@ -206,6 +299,7 @@ export class CheckCtx {
         const s = pass.scan(scan, () => new CheckCtx(pass))
         const value = await s.value
         this.reads.merge(s.ctx.reads)
+        for (const [f, text] of s.ctx.marked) this.marked.set(f, text)
         if (s.ctx.untracked != null) this.untrack(s.ctx.untracked)
         return value
     }