rvlib-shipkit 0.31.0 → 0.33.0

package/src/rules/SK001-package-json-shape.ts

@@ -2,10 +2,17 @@
 // private:true, no license, capability-required script names FAIL, banned
 // aliases + missing baseline scripts WARN. Blocking, so it runs in `shipkit
 // ci` like every other rule. Pure local fs, no TTL.
+//
+// It also enforces the package.json half of ONE WAY IN (build/shipkit.md):
+// `test`, `lint` and `typecheck` ROUTE to `shipkit ci --only <id>` and the
+// tool body they used to hold sits at `<id>:raw`. That is what makes a cache
+// worth having: `bun run test` is the reflex, and the reflex has to land in
+// shipkit rather than beside it.
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { canonicalBodies, conditionalBodies, inferBin } from '../core/canonical-scripts.ts'
+import { canonicalBodies, conditionalBodies, inferBin, ROUTED_SCRIPTS, rawName, routedBody, routesToShipkit } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
+import { resolveFloor } from '../core/floor.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
 
@@ -68,6 +75,23 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
     const missing = required.filter((r) => !has(r.name))
     for (const m of missing) t.fail(`package.json: missing script '${m.name}' (${m.why})`)
 
+    // ONE WAY IN — a governed script that runs the tool directly is the whole
+    // reason a cache gets bypassed: an agent types `bun run test` and shipkit
+    // never hears about it. A slot the repo turned off has no shipkit task to
+    // route to, so it is not governed.
+    const floor = resolveFloor(c, root)
+    for (const id of ROUTED_SCRIPTS) {
+        if (routedExempt(c).has(id) || c.defaults?.[id] === false) continue
+        const body = scripts[id]
+        if (body == null) continue
+        if (!routesToShipkit(body)) {
+            t.fail(`package.json: script '${id}' runs the tool directly — route it to \`${routedBody(id, { bin: inferBin(scripts) })}\` and move the body to '${rawName(id)}', so \`bun run ${id}\` gets the cache instead of bypassing it`)
+            continue
+        }
+        const gap = floor.unfilled.find((u) => u.id === id)
+        if (gap != null) t.fail(`package.json: ${gap.reason} — \`bun run ${id}\` would measure nothing`)
+    }
+
     // `test` is asked for only once the repo HAS tests: the fixer deliberately
     // refuses to scaffold it before that (a fixer never manufactures a
     // failure), so nagging for it would be a WARN no machine may clear
@@ -96,6 +120,29 @@ function requiredScripts(root: string, _c: RepoConfig): Array<{ name: string; wh
     return required
 }
 
+/** rebuild the script map with `key` inserted directly after `after`, so a
+ *  routed pair reads as two adjacent lines instead of the tool body landing at
+ *  the bottom of the file, far from the name it belongs to */
+function insertAfter(scripts: Record<string, string>, after: string, key: string, value: string): Record<string, string> {
+    const out: Record<string, string> = {}
+    for (const [k, v] of Object.entries(scripts)) {
+        if (k === key) continue
+        out[k] = v
+        if (k === after) out[key] = value
+    }
+    if (out[key] == null) out[key] = value
+    return out
+}
+
+/** governed names this repo keeps as a direct tool call. Declared per NAME in
+ *  repo.config, never as a list of banned binaries: the invariant is about
+ *  which VERBS an agent reaches for, and a binary blocklist goes stale the day
+ *  a repo changes runner. `defineRepo` rejects a name outside ROUTED_SCRIPTS,
+ *  so a typo can never silently un-govern a script. */
+function routedExempt(c: RepoConfig): Set<string> {
+    return new Set(c.oneWayIn?.exempt ?? [])
+}
+
 const TEST_SKIP = new Set(['node_modules', 'dist', 'tmp', 'references', 'coverage'])
 
 /** any `*.test.ts` in the repo, so the test script is only scaffolded once it
@@ -164,6 +211,23 @@ export const packageJsonShape: Rule = {
         // none, so scaffolding this into a repo without any turns the gate red
         // on work the fixer itself did. a fixer must never manufacture a failure.
         if (pkg.scripts['test'] == null && hasTestFiles(env.root)) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        // ONE WAY IN, last so it also routes whatever this pass just added:
+        // the tool body slides to `<id>:raw` and `<id>` becomes the shipkit
+        // call. Both keys keep their place in the file, so the diff a human
+        // reads is the two lines that changed and not a reordered block
+        for (const id of ROUTED_SCRIPTS) {
+            if (routedExempt(env.config).has(id) || env.config.defaults?.[id] === false) continue
+            const body = pkg.scripts[id]
+            if (body == null || routesToShipkit(body)) continue
+            const raw = rawName(id)
+            const held = pkg.scripts[raw]
+            // a `<id>:raw` that already says something else is a repo's own
+            // answer, and overwriting it would delete a body nobody can recover
+            if (held != null && held !== body) { notes.push(`'${id}' left as it is — '${raw}' already holds a different body`); continue }
+            pkg.scripts = insertAfter(pkg.scripts, id, raw, body)
+            pkg.scripts[id] = routedBody(id, { bin })
+            changes.push(`script '${id}' routed through shipkit ('${raw}' holds the tool)`)
+        }
         if (changes.length > 0) {
             const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
             writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')

package/src/rules/SK002-contracts-fulfillness.ts

@@ -6,7 +6,7 @@
 // `shipkit contracts`, the ci `contracts` task) tags with this id via
 // contracts/apply-contracts.ts.
 import { activeContracts, applyContractsResult, contractsConfigFrom } from '../contracts/apply-contracts.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { evaluateContractsOnce } from '../contracts/contracts-once.ts'
 import type { Rule } from './rule.ts'
 
 export const contractsFulfillness: Rule = {
@@ -15,6 +15,6 @@ export const contractsFulfillness: Rule = {
     title: 'contracts',
     owner: 'meta/contracts.md',
     lint: async (t, env) => {
-        applyContractsResult(t, await evaluateContracts(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
+        applyContractsResult(t, await evaluateContractsOnce(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
     },
 }

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

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
+import { GENERATED_IGNORE_LINES, trackedGeneratedPaths, untrackGenerated } from './untrack-generated.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
 
 const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit outside only'
@@ -37,6 +38,10 @@ const POLICY_LINES = [
     // so every consumer repo needs both ignored before its first commit
     '.comfy-ts/',
     '*.loras.local.txt',
+    // shipkit's own per-run output. Ignoring is only half of it: the fixer
+    // also removes these from the index, because .gitignore does nothing to a
+    // file already tracked (untrack-generated.ts owns the pair)
+    ...GENERATED_IGNORE_LINES,
 ]
 
 export function expectedBlock(config: RepoConfig): string {
@@ -96,6 +101,13 @@ export const gitignorePolicy: Rule = {
     title: '.gitignore',
     owner: 'meta/contracts.md',
     lint: (t, env) => {
+        // a generated path still in the index is the half-applied state the
+        // managed block cannot fix on its own
+        const tracked = trackedGeneratedPaths(env.root)
+        if (tracked.length > 0) {
+            t.fail(`${tracked.join(', ')} generated on every run but TRACKED — gitignore does not apply to a tracked file, so it dirties every tree`)
+            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) untracks it in one commit, the file stays on disk' })
+        }
         const s = blockState(env.root, env.config)
         switch (s) {
             case 'missing-file': return t.fail('.gitignore missing — the contract git policy is unenforced')
@@ -107,8 +119,20 @@ export const gitignorePolicy: Rule = {
     },
     fix: (env: RuleEnv): FixResult => {
         const before = blockState(env.root, env.config)
-        if (before === 'current') return { changed: false, summary: 'policy block already current' }
-        writeBlock(env.root, env.config)
-        return { changed: true, summary: before === 'missing-file' ? '.gitignore created with the policy block' : before === 'missing-block' ? 'policy block appended (repo lines untouched)' : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)' : 'policy block rewritten in place (repo lines untouched)' }
+        const blockSummary = before === 'current'
+            ? null
+            : before === 'missing-file' ? '.gitignore created with the policy block'
+            : before === 'missing-block' ? 'policy block appended (repo lines untouched)'
+            : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)'
+            : 'policy block rewritten in place (repo lines untouched)'
+        if (blockSummary != null) writeBlock(env.root, env.config)
+        // 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]
+        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 }
     },
 }

package/src/rules/SK012-config-barrel-import.ts

@@ -0,0 +1,60 @@
+// SK012 — `repo.config.ts` must import from the NARROW module, never from the
+// package barrel.
+//
+// THE COST, measured on this tree: `import { defineRepo } from 'rvlib-shipkit'`
+// pulls the whole toolkit, 405ms of module load. The same symbol from
+// `rvlib-shipkit/src/repo-config.ts` is 7ms. Every shipkit invocation in every
+// repo loads this file first, the ~1s pre-commit hook included, so the barrel
+// is a fixed tax on every gate run, every hook, every hub boot.
+//
+// A barrel is a fine PUBLIC surface and a terrible one to import from a config
+// file that exists to be read before anything else happens. This rule is
+// narrow on purpose: it is about repo.config.ts, not about barrels in general.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const CONFIG = 'repo.config.ts'
+const BARREL = /(^|\n)(\s*import\s+(?:type\s+)?\{[^}]*\}\s+from\s+)['"]rvlib-shipkit['"]/
+const NARROW = 'rvlib-shipkit/src/repo-config.ts'
+
+/** the symbols a config file can legitimately want, all of which the narrow
+ *  module already exports. A config reaching for anything else is asking the
+ *  barrel for a reason, and the rule says so rather than rewriting it. */
+const CONFIG_SYMBOLS = new Set(['defineRepo', 'RepoConfig', 'TaskDef', 'ServeConfig', 'FloorSource', 'FloorResolution', 'loadRepoConfig', 'resolveFloor', 'allTasks'])
+
+const importedSymbols = (line: string): string[] =>
+    (/\{([^}]*)\}/.exec(line)?.[1] ?? '').split(',').map((s) => s.replace(/^\s*type\s+/, '').trim()).filter((s) => s !== '')
+
+export const configBarrelImport: Rule = {
+    id: 'SK012',
+    blocking: true,
+    title: 'config import path',
+    owner: 'build/shipkit.md',
+    lint: (t, env) => {
+        const p = join(env.root, CONFIG)
+        if (!existsSync(p)) return void t.ok(`${CONFIG} absent — nothing to narrow`)
+        const src = readFileSync(p, 'utf8')
+        if (!BARREL.test(src)) return void t.ok(`${CONFIG} imports the narrow config module`)
+        const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
+        const symbols = importedSymbols(line)
+        const strays = symbols.filter((s) => !CONFIG_SYMBOLS.has(s))
+        if (strays.length > 0) {
+            t.fail(`${CONFIG} imports ${strays.join(', ')} from the package barrel, which costs ~400ms of module load on every shipkit run`)
+            return void t.lines.push({ kind: 'fix-fail', text: `move ${strays.join(', ')} to their own module, then import from ${NARROW}` })
+        }
+        t.fail(`${CONFIG} imports from the package barrel (~400ms of module load on every shipkit run, the pre-commit hook included)`)
+    },
+    fix: (env: RuleEnv): FixResult => {
+        const p = join(env.root, CONFIG)
+        if (!existsSync(p)) return { changed: false, summary: `${CONFIG} absent` }
+        const src = readFileSync(p, 'utf8')
+        if (!BARREL.test(src)) return { changed: false, summary: 'already narrow' }
+        const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
+        // only rewrite what the narrow module actually exports: silently
+        // repointing an import it cannot serve turns a slow gate into a broken one
+        if (importedSymbols(line).some((s) => !CONFIG_SYMBOLS.has(s))) return { changed: false, summary: 'imports symbols the narrow module does not export — move them by hand' }
+        writeFileSync(p, src.replace(BARREL, `$1$2'${NARROW}'`))
+        return { changed: true, summary: `${CONFIG} now imports ${NARROW} (~400ms saved per run)` }
+    },
+}

package/src/rules/SK013-one-way-in-policy.ts

@@ -0,0 +1,136 @@
+// SK013 — the harness half of ONE WAY IN (build/shipkit.md). Rule SK001 routes
+// the package.json scripts, and that alone is not enough: `bun test` is a bun
+// BUILTIN, so no script can intercept it and the reflex stays open. This rule
+// makes the repo carry the two things that CAN close it, and repairs them:
+//
+//   - `permissions.deny` — declarative and unbypassable (deny beats allow at
+//     every settings level, and bypassPermissions does not lift it)
+//   - a PreToolUse hook — the only way to put a REASON in front of the model.
+//     A bare deny says only that the call was denied, and a refusal with no
+//     replacement sends the agent looking for another runner.
+//
+// Both are generated from ONE table (core/one-way-in-policy.ts). The file is
+// 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, writeFileSync } from 'fs'
+import { dirname, 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'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const OWNER = 'build/shipkit.md'
+export const SETTINGS_PATH = '.claude/settings.json'
+
+type Settings = {
+    permissions?: { deny?: string[] }
+    hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<{ type?: string; command?: string }> }>>
+}
+
+/** slots this repo does not route, so it must not be refused the shell command
+ *  either: ONE declaration governs the script name and the raw call together */
+export function exemptSlots(c: RepoConfig): Set<string> {
+    const off = new Set(c.oneWayIn?.exempt ?? [])
+    for (const [slot, def] of Object.entries(c.defaults ?? {})) if (def === false) off.add(slot)
+    return off
+}
+
+/** how the hook invokes the guard. `$CLAUDE_PROJECT_DIR` because a hook's cwd
+ *  is not promised to be the repo root */
+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}"`
+}
+
+const readSettings = (root: string): Settings | null => {
+    const p = join(root, SETTINGS_PATH)
+    if (!existsSync(p)) return null
+    try { return JSON.parse(readFileSync(p, 'utf8')) as Settings } catch { return null }
+}
+
+const guardHookCommand = (s: Settings): string | null => {
+    for (const m of s.hooks?.['PreToolUse'] ?? [])
+        for (const h of m.hooks ?? [])
+            if (h.command?.includes('one-way-in-guard') === true) return h.command
+    return null
+}
+
+const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
+
+/** the guard file the hook command points at, resolved against the repo root.
+ *  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 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 }
+}
+
+export const oneWayInPolicy: Rule = {
+    id: 'SK013',
+    blocking: true,
+    title: 'one way in policy',
+    owner: OWNER,
+    lint: (t, env) => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return t.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
+        const s = readSettings(env.root)
+        if (s == null) {
+            t.fail(`${SETTINGS_PATH} ${existsSync(join(env.root, SETTINGS_PATH)) ? 'is unparseable' : 'missing'} — nothing stops an agent typing \`bun test\`, and a package.json script cannot intercept a bun builtin`)
+            return
+        }
+        const have = new Set(s.permissions?.deny ?? [])
+        const missing = want.filter((r) => !have.has(r))
+        if (missing.length > 0)
+            t.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
+        const guard = guardHookCommand(s)
+        if (guard == null)
+            t.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
+        else {
+            const missing = guardScriptMissing(env.root, guard)
+            if (missing != null)
+                t.fail(
+                    `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which does not exist — every Bash call errors and no refusal ever names the shipkit command`,
+                    `bun install (or bun add -d rvlib-shipkit)`,
+                )
+        }
+        if (!t.failed) t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s), with the replacement named`)
+    },
+    // MERGES, never rewrites: this file also carries the attribution silencer,
+    // a repo's own allow list and its own hooks, and clobbering those to fix a
+    // deny list would cost more than the finding it repairs
+    fix: (env: RuleEnv): FixResult => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }
+        const p = join(env.root, SETTINGS_PATH)
+        const existing = readSettings(env.root)
+        if (existing == null && existsSync(p)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
+        const s: Settings = existing ?? {}
+        const changes: string[] = []
+        const deny = s.permissions?.deny ?? []
+        const added = want.filter((r) => !deny.includes(r))
+        if (added.length > 0) {
+            s.permissions = { ...s.permissions, deny: [...deny, ...added] }
+            changes.push(`${added.length} raw runner(s) denied`)
+        }
+        if (!hasGuardHook(s)) {
+            const pre = s.hooks?.['PreToolUse'] ?? []
+            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: guardCommand(readBin(env.root)) }] }] }
+            changes.push('PreToolUse guard wired (every refusal names the shipkit command)')
+        }
+        if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, JSON.stringify(s, null, 2) + '\n')
+        return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
+    },
+}

package/src/rules/rule-registry.ts

@@ -14,6 +14,8 @@ import { reviewerAgent } from './SK008-reviewer-agent.ts'
 import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 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'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -27,6 +29,8 @@ export const RULES: readonly Rule[] = [
     commitAiTells,
     undeclaredReleaseUnit,
     siblingUnitRanges,
+    configBarrelImport,
+    oneWayInPolicy,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/rules/untrack-generated.ts

@@ -0,0 +1,117 @@
+// paths shipkit GENERATES on every run, and the one operation that makes a
+// declaration like that actually hold.
+//
+// THE CONTRADICTION THIS RESOLVES: `.gitignore` does not apply to a file that
+// is already tracked. So a path shipkit ignores but leaves in the index keeps
+// dirtying every tree forever, and rides into unrelated commits as a mystery
+// diff. Ignoring and untracking are therefore ONE operation, never two, and
+// any path declared machine-generated gets both.
+//
+// STATUS.md is the first customer and the reason: 141 of this repo's 625
+// commits carried it, 125 of them as an unrelated rider inside someone else's
+// diff, in a repo whose commits ARE the session-resume mechanism. It is
+// nondeterministic by construction (minute-resolution header, task lines in
+// DAG completion order, per-worktree cache stamps that move backwards), and
+// nothing on this disk ever reads a past version: the hub reads it off disk,
+// the TUI renders live, the tests assert the writer.
+//
+// WHY THIS ONE FIXER COMMITS, when shipkit otherwise never does: `git rm
+// --cached` leaves a STAGED DELETION in the index, which the next agent's
+// unrelated commit sweeps up as an unexplained deletion. That is strictly
+// worse than the disease. The commit is a one-time migration per path, it
+// goes through the hooks like any other, and it refuses in every state where
+// it could surprise someone.
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+/** rendered into the SK004 managed block. A glob is fine HERE: ignoring is
+ *  not destructive. */
+export const GENERATED_IGNORE_LINES = [
+    '# shipkit writes these on every run — ignored AND untracked (untrack-generated.ts)',
+    'STATUS.md',
+    'STATUS.md.lock',
+    '.STATUS.md.tmp-*',
+]
+
+/** the LITERAL subset an autofix may remove from the index. Never a glob and
+ *  never derived from a pattern: `git rm --cached` driven by a wildcard is how
+ *  a fixer eats source it was never pointed at. A future entry is added HERE,
+ *  by hand, spelled out. */
+export const GENERATED_TRACKED_PATHS = ['STATUS.md', 'STATUS.md.lock'] as const
+
+export type UntrackOutcome =
+    | { did: 'nothing' }
+    | { did: 'refused'; why: string }
+    | { did: 'untracked'; paths: string[]; commit: string }
+
+const git = (root: string, args: string[]): { code: number; out: string } => {
+    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
+}
+
+/** every declared path this repo still carries in its index. ONE git spawn,
+ *  not one per path: this runs inside the SK004 lint, which runs on every
+ *  `shipkit check` in every repo, and a process start is ~10ms of it. */
+export function trackedGeneratedPaths(root: string): string[] {
+    if (!existsSync(join(root, '.git'))) return []
+    const r = git(root, ['ls-files', '-z', '--', ...GENERATED_TRACKED_PATHS])
+    if (r.code !== 0) return []
+    const listed = new Set(r.out.split('\0').filter((l) => l !== ''))
+    return GENERATED_TRACKED_PATHS.filter((p) => listed.has(p))
+}
+
+/** a state where an automated commit would surprise someone, or land on the
+ *  wrong ref. Named rather than boolean so the refusal says which one. */
+function unsafeState(root: string): string | null {
+    const gitDir = git(root, ['rev-parse', '--git-dir'])
+    if (gitDir.code !== 0) return 'not a git work tree'
+    const d = join(root, gitDir.out)
+    if (existsSync(join(d, 'MERGE_HEAD'))) return 'a merge is in progress'
+    if (existsSync(join(d, 'rebase-merge')) || existsSync(join(d, 'rebase-apply'))) return 'a rebase is in progress'
+    if (git(root, ['symbolic-ref', '-q', 'HEAD']).code !== 0) return 'HEAD is detached'
+    if (git(root, ['rev-parse', '--verify', '-q', 'HEAD']).code !== 0) return 'the repo has no commit yet'
+    // the commit below stages nothing but our own removal, so ANY other staged
+    // change would ride along in it. A one-time migration can wait for a run
+    // where the index is the fixer's alone
+    const staged = git(root, ['diff', '--cached', '--name-only'])
+    if (staged.code === 0 && staged.out !== '') return `something else is already staged (${staged.out.split('\n')[0]})`
+    return null
+}
+
+const message = (paths: string[]): string =>
+    [
+        `chore(machine): untrack ${paths.join(', ')}`,
+        '',
+        `shipkit rewrites ${paths.length === 1 ? 'this path' : 'these paths'} on every run, so ${paths.length === 1 ? 'it was' : 'they were'} never source.`,
+        'Tracked, it dirtied every tree and rode into unrelated commits as a',
+        'mystery diff. Gitignore alone cannot fix that: it does not apply to a',
+        'file already in the index, so the two halves land together.',
+        '',
+        'The file stays on disk. Nothing reads a past version of it.',
+    ].join('\n')
+
+/**
+ * ignore AND untrack, in one operation. Loud when it acts, loud when it
+ * refuses, silent when there is nothing to do.
+ *
+ * `frozen` is the release-shaped run: report only, touch nothing.
+ */
+export function untrackGenerated(root: string, o: { frozen?: boolean; enabled?: boolean } = {}): UntrackOutcome {
+    if (o.enabled === false) return { did: 'nothing' }
+    if (o.frozen === true || process.env.SHIPKIT_FROZEN === '1') return { did: 'nothing' }
+    const paths = trackedGeneratedPaths(root)
+    if (paths.length === 0) return { did: 'nothing' }
+    const unsafe = unsafeState(root)
+    if (unsafe != null) return { did: 'refused', why: unsafe }
+
+    const rm = git(root, ['rm', '--cached', '--quiet', '--', ...paths])
+    if (rm.code !== 0) return { did: 'refused', why: `git rm --cached failed: ${rm.out.slice(0, 120)}` }
+    // through the hooks, never --no-verify. A rejected commit must not leave
+    // the staged deletion behind: that IS the failure mode this exists to stop
+    const commit = git(root, ['commit', '-m', message(paths)])
+    if (commit.code !== 0) {
+        git(root, ['reset', '--quiet', '--', ...paths])
+        return { did: 'refused', why: `the commit was rejected, index restored: ${commit.out.slice(0, 160)}` }
+    }
+    return { did: 'untracked', paths, commit: git(root, ['rev-parse', '--short', 'HEAD']).out }
+}

package/src/scaffold/files/claude-settings-local.json

@@ -3,10 +3,8 @@
     "allow": [
       "Bash(shipkit *)",
       "Bash(bun run *)",
-      "Bash(bun test*)",
       "Bash(bun install*)",
       "Bash(bun add *)",
-      "Bash(bunx tsc*)",
       "Bash(bunx wrangler*)",
       "Bash(git status*)",
       "Bash(git diff*)",
@@ -15,7 +13,6 @@
       "Bash(git commit*)",
       "Bash(git push*)",
       "Bash(curl *)",
-      "Bash(oxlint*)",
       "Bash(./deploy.sh)"
     ],
     "deny": []

package/src/scaffold/files/verify-skill.md

@@ -11,7 +11,7 @@ description: Prove a change in THIS project actually works — drive the real fl
 
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
-- Logic → fast headless `bun test` (tiny ~10-line test files reusing fixtures).
+- Logic → fast headless bun tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <name filter>` is the narrow way in.
 - Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 

package/src/scaffold/project-scaffold.ts

@@ -12,7 +12,7 @@
 // none of them may name a machine-local tool or a private path.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
-import { defaultHubPort } from '../serve/run-serve.ts'
+import { defaultHubPort } from '../serve/hub-port.ts'
 
 const FILES = join(import.meta.dir, 'files')
 

package/src/serve/hub-port.ts

@@ -0,0 +1,17 @@
+// the hub's default port, alone in its own module ON PURPOSE.
+//
+// It is four lines of arithmetic that several places need BEFORE any server
+// exists: the repo scaffold writes it into .vscode/tasks.json, `init` prints
+// it, the config resolver defaults to it. Importing it from run-serve.ts drags
+// the whole hub (react, the markdown renderer, the sanitiser, every panel)
+// into a caller that only wanted a number, which measured 393ms of module
+// load in the scaffold alone.
+//
+// A port derived from the repo NAME rather than assigned means two repos open
+// side by side almost never collide, and the same repo always reopens on the
+// same port, which is what makes a folder-open task able to advertise a URL.
+export function defaultHubPort(name: string): number {
+    let h = 0
+    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
+    return 4800 + (h % 180)
+}

package/src/serve/run-serve.ts

@@ -20,14 +20,11 @@ import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import type { GraphMount } from '../wiki/graph-mount.ts'
 import { scanMdGraph } from '../wiki/scan-md.ts'
 import { serveHub, type HubDeps } from './serve-hub.ts'
+import { defaultHubPort } from './hub-port.ts'
+export { defaultHubPort }
 
 export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
 
-export function defaultHubPort(name: string): number {
-    let h = 0
-    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
-    return 4800 + (h % 180)
-}
 
 // the BASE-CONTEXT wiki: the shared wiki this repo's CLAUDE.md include chain
 // points at (`@~/dev/<other-repo>/wiki/index.md`). It lives in ANOTHER repo and

package/src/wiki/run-wiki.ts

@@ -6,7 +6,15 @@ import { lintMd } from './lint-md.ts'
 import { scanMdGraph } from './scan-md.ts'
 import { serveMdGraph } from './serve-graph.ts'
 
-export type WikiScanOpts = { root: string; index?: string; skip?: string }
+export type WikiScanOpts = {
+    root: string
+    index?: string
+    skip?: string
+    /** where the verdict goes. The command passes its own stream, so the
+     *  output is capturable: a console.log inside a command bypasses the
+     *  stream clipanion hands it, and nothing downstream can read it */
+    print?: (line: string) => void
+}
 
 const scanConfig = (o: WikiScanOpts): { root: string; index?: string; skipDirs?: string[] } => ({
     root: resolve(process.cwd(), o.root),
@@ -15,18 +23,19 @@ const scanConfig = (o: WikiScanOpts): { root: string; index?: string; skipDirs?:
 })
 
 export async function runWikiServe(o: WikiScanOpts & { port: number; title?: string }): Promise<number> {
+    const say = o.print ?? console.log
     const cfg = scanConfig(o)
     const rel = relative(process.cwd(), cfg.root)
     const title = o.title ?? (rel === '' ? basename(cfg.root) : `${basename(process.cwd())} ${rel}`)
     try {
         serveMdGraph({ port: o.port, title, load: () => scanMdGraph(cfg) })
-        console.log(`wiki graph → http://localhost:${o.port} (open in browser, or VSCode "Simple Browser: Show")`)
+        say(`wiki graph → http://localhost:${o.port} (open in browser, or VSCode "Simple Browser: Show")`)
         // keep the server alive — the command must not resolve
         await new Promise(() => {})
         return 0
     } catch (e) {
         if (e instanceof Error && e.message.includes('in use')) {
-            console.log(`wiki graph already served → http://localhost:${o.port} (another window owns it)`)
+            say(`wiki graph already served → http://localhost:${o.port} (another window owns it)`)
             return 0
         }
         throw e
@@ -34,17 +43,18 @@ export async function runWikiServe(o: WikiScanOpts & { port: number; title?: str
 }
 
 export function runWikiLint(o: WikiScanOpts): number {
+    const say = o.print ?? console.log
     const cfg = scanConfig(o)
     const r = lintMd(cfg)
     if (r.index == null) {
-        console.log(o.index != null
+        say(o.index != null
             ? `FAIL entrypoint '${o.index}' not found in ${cfg.root}`
             : `FAIL no entrypoint: neither index.md nor README.md in ${cfg.root} — pass --index <entry.md>`)
         return 1
     }
-    for (const f of r.orphans) console.log(`FAIL orphan: ${f} — unreachable from ${r.index}; link it or delete it`)
-    for (const d of r.dangling) console.log(`FAIL dangling: ${d.from} → ${d.token} — target not found`)
-    if (!r.ok) { console.log(`FAIL mdwiki lint: ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s) in ${cfg.root}`); return 1 }
-    console.log(`ok mdwiki lint: ${r.files} files, all reachable from ${r.index}, no dangling refs`)
+    for (const f of r.orphans) say(`FAIL orphan: ${f} — unreachable from ${r.index}; link it or delete it`)
+    for (const d of r.dangling) say(`FAIL dangling: ${d.from} → ${d.token} — target not found`)
+    if (!r.ok) { say(`FAIL mdwiki lint: ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s) in ${cfg.root}`); return 1 }
+    say(`ok mdwiki lint: ${r.files} files, all reachable from ${r.index}, no dangling refs`)
     return 0
 }