rvlib-shipkit 0.33.0 → 0.34.0

package/src/ledger/toolchain-identity.ts

@@ -56,8 +56,8 @@ function installedNames(nm: string): string[] {
     return names.sort()
 }
 
-/** the gate binary's own source, content-hashed. Only reached when the cli
- *  lives OUTSIDE the repo, where the git tree key cannot see it. */
+/** the gate binary's own source, content-hashed. This is what makes editing
+ *  shipkit invalidate every key in every repo, in-repo copy or dependency. */
 function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
     const srcRoot = resolve(cli, '..')
     const files: string[] = []
@@ -94,12 +94,19 @@ export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain
     // the runtime. Free, and a bun upgrade genuinely changes behaviour
     h.update(`bun=${Bun.version}\n`)
 
-    // the gate binary. In-repo, the git tree key already covers every byte of
-    // it, so the literal is enough and the walk is skipped
-    const cli = realpathSync(cliEntry)
-    const cliInRepo = inRepo(root, cli)
-    h.update(`cli=${cliInRepo ? 'in-repo' : cli}\n`)
-    if (!cliInRepo) hashCliTree(h, cli)
+    // the gate binary, ALWAYS content-hashed, and its path never folded in.
+    //
+    // The earlier shape wrote `cli=in-repo` for a binary inside the repo and
+    // leaned on the git tree key to cover it. Both halves were wrong, and both
+    // were measured. In a CONSUMER repo the binary sits in `node_modules`,
+    // which is path-inside the root and inside no git tree, so the tree key
+    // covered none of it. And between a checkout that HOSTS the binary and a
+    // worktree that runs the same one through the global shim, one wrote
+    // `in-repo` and the other wrote an absolute path, so two checkouts running
+    // one identical program could never agree on a key. Content-hashing costs
+    // 3.5 to 9.2ms on a 163-file tree, and it is the only form that is the
+    // same value wherever the caller stands.
+    hashCliTree(h, realpathSync(cliEntry))
 
     // what is installed. The lockfile states the intent; the tree states the fact
     const lock = join(root, 'bun.lock')

package/src/release/run-bump.ts

@@ -26,7 +26,7 @@
 // every selected unit's package.json and changelog. The publish part is
 // RESUMABLE instead, because an npm publish cannot be undone and a rollback
 // that cannot roll back is a lie.
-import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, relative } from 'path'
 import { declaredKind, hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
@@ -136,6 +136,26 @@ function mergeIntoReleaseBranch(
     }
 }
 
+/** where a branch is checked out, or null. `git worktree list` is the only
+ *  source that sees the OTHER checkouts: a linked worktree and its main
+ *  checkout share one object store and one branch namespace, and git refuses
+ *  to check a branch out twice. Three agents in one checkout, one of them in a
+ *  worktree, is the normal case here, so this is asked before any ref moves. */
+function branchCheckedOutAt(root: string, git: Git, branch: string): string | null {
+    const r = git(['worktree', 'list', '--porcelain'])
+    if (r.code !== 0) return null
+    let path: string | null = null
+    for (const line of r.out.split('\n')) {
+        if (line.startsWith('worktree ')) path = line.slice('worktree '.length).trim()
+        else if (line.trim() === `branch refs/heads/${branch}`) {
+            if (path == null) continue
+            try { if (realpathSync(path) === realpathSync(root)) return null } catch { /* a stale worktree entry: treat it as foreign */ }
+            return path
+        }
+    }
+    return null
+}
+
 /** the rehearsal's answer to the same two questions, from the object database:
  *  has the release branch diverged from its remote, and would the merge
  *  conflict. Nothing is checked out and no ref moves, which is the whole point
@@ -189,6 +209,10 @@ function probeMergeIntoReleaseBranch(
     return { refuse: false, inconclusive: stale }
 }
 
+/** a rehearsal moves no ref and checks nothing out, so a branch held by
+ *  another worktree cannot stop it */
+const rehearsalOnly = (o: BumpOpts): boolean => o.dryRun === true
+
 type Selected = { unit: ReleaseUnit; version: string; changelogRel: string; kind: BumpKind }
 
 export async function runBump(root: string, config: RepoConfig, kind: BumpKind | null, o: BumpOpts = {}): Promise<number> {
@@ -242,7 +266,11 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
         const paths = dirtyPathList(preDirty)
         if (paths.every((p) => machine.has(p))) {
             gitAt(root, ['add', '--', ...paths])
-            const c = gitAt(root, ['commit', '-m', 'machine rows refresh before release'])
+            // PATHSPEC on the commit too, not just the add. Three agents in
+            // one checkout share one index, so a bare `git commit` here takes
+            // whatever a neighbour staged a second ago and ships it under a
+            // message about machine rows.
+            const c = gitAt(root, ['commit', '-m', 'machine rows refresh before release', '--', ...paths])
             if (c.code === 0) print('ok: machine-written rows committed (they re-dirty on every gate run)')
             else print(`WARN machine-row auto-commit failed (exit ${c.code}), the refusal below says what to do:\n${c.out.split('\n').slice(-6).join('\n')}`)
         } else {
@@ -263,6 +291,20 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
 
     const wantMerge = cur !== branch && o.noMerge !== true && (config.release?.mergeFromBranch ?? true)
     if (cur !== branch && !wantMerge) { print(`FAIL: releases ship from '${branch}', HEAD is on '${cur}'`); return 1 }
+    // the merge CHECKS OUT the release branch here, and git refuses to have
+    // one branch checked out in two worktrees. Left to git the run dies on a
+    // raw `fatal: 'main' is already used by worktree at …`, which reads like a
+    // shipkit bug. Worse, in the other direction, a bump run in the checkout
+    // that DOES hold the branch moves the HEAD of an agent working in it.
+    // Refuse by name, and say which checkout owns the branch.
+    if (wantMerge && !rehearsalOnly(o)) {
+        const held = branchCheckedOutAt(root, git, branch)
+        if (held != null) {
+            print(`FAIL: '${branch}' is checked out at ${held}, so this worktree cannot merge into it`)
+            print(`      fix: bump from ${held}, or \`shipkit bump --no-merge\` after merging '${cur}' into '${branch}' by hand there`)
+            return 1
+        }
+    }
     const remote = deriveRemote(root)
     if ('error' in remote) { print(`FAIL: ${remote.error}`); return 1 }
     if (wantMerge) print(`note: on '${cur}', so '${cur}' merges into '${branch}' first`)
@@ -482,12 +524,15 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
         }
     }
 
-    const add = git(['add', ...files])
+    const add = git(['add', '--', ...files])
     if (add.code !== 0) return failKeep('git add failed', 'the version files are written but unstaged. git status, then commit them')
     const label = selected.map((s) => (s.unit.id === 'root' ? s.version : `${s.unit.id}@${s.version}`)).join(', ')
     // the hooks already ran through the gate above; --no-verify is NOT used,
-    // so the repo's own commit gates still apply to this commit
-    const commit = git(['commit', '-m', `release ${label}`])
+    // so the repo's own commit gates still apply to this commit.
+    // PATHSPEC, because the index is shared with every other agent in this
+    // checkout: a bare commit here tags whatever a neighbour happened to have
+    // staged, and the tag then describes a tree nobody gated.
+    const commit = git(['commit', '-m', `release ${label}`, '--', ...files])
     if (commit.code !== 0)
         return failKeep(`commit failed — ${commit.out}`, 'the version files are written but uncommitted. fix the gate, commit, then `shipkit release`')
     print(`ok: committed release ${label}`)

package/src/release/unit-gate.ts

@@ -6,6 +6,7 @@
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { dirtyPaths } from './git-facts.ts'
+import { resolveTypecheckProjects } from '../ts/tsconfig-projects.ts'
 import type { ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
@@ -56,10 +57,22 @@ export function unitBlockers(root: string, config: RepoConfig, unit: ReleaseUnit
         const tsc = resolveTsc(root, unit)
         if (tsc == null) out.push(`unit '${unit.id}': tsc not resolvable — bun add -d typescript at the repo root`)
         else {
-            const r = Bun.spawnSync([tsc, '--noEmit', '-p', unit.tsconfig], { cwd: root })
-            if (r.exitCode !== 0) {
-                const lines = `${r.stdout.toString()}${r.stderr.toString()}`.trim().split('\n').slice(0, 8).join('\n')
-                out.push(`unit '${unit.id}': does not typecheck under its own tsconfig — it cannot be published\n${lines}`)
+            // a solution-style tsconfig (`files: []` plus `references`) makes
+            // tsc compile ZERO files and exit 0, which would publish a package
+            // whose only proof of soundness was that nobody looked
+            let projects: ReturnType<typeof resolveTypecheckProjects> | null = null
+            try { projects = resolveTypecheckProjects(unit.tsconfig) }
+            catch (e) { out.push(`unit '${unit.id}': ${String((e as Error)?.message ?? e)}`) }
+            for (const m of projects?.missing ?? [])
+                out.push(`unit '${unit.id}': its tsconfig references '${m}', which does not exist, so whatever that project covered is unchecked`)
+            if (projects != null && projects.vacuous)
+                out.push(`unit '${unit.id}': its tsconfig compiles no files of its own and reaches no project that does, so a typecheck over it proves nothing — it cannot be published`)
+            for (const p of projects?.projects ?? []) {
+                const r = Bun.spawnSync([tsc, '--noEmit', '-p', p], { cwd: root })
+                if (r.exitCode !== 0) {
+                    const lines = `${r.stdout.toString()}${r.stderr.toString()}`.trim().split('\n').slice(0, 8).join('\n')
+                    out.push(`unit '${unit.id}': does not typecheck under ${p} — it cannot be published\n${lines}`)
+                }
             }
         }
     }

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

@@ -8,13 +8,14 @@
 // 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 { existsSync, readdirSync, readFileSync } from 'fs'
 import { join } from 'path'
 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'
+import { atomicWrite } from '../core/locked-write.ts'
 
 type Pkg = { name?: string; private?: boolean; license?: string; scripts?: Record<string, string> }
 
@@ -166,6 +167,11 @@ export const packageJsonShape: Rule = {
     blocking: true,
     title: 'package.json',
     owner: OWNER,
+    // the whole tree: package.json is most of it, but the baseline-script
+    // check also walks the repo for a `*.test.ts` and probes `.rv-comfy`
+    // and `deploy.sh`, so naming three files would key it on less than it
+    // reads
+    inputs: ['.'],
     lint: (t: CheckCtx, env: RuleEnv) => evaluatePackageJson(t, env.root, env.config),
     // mechanical repairs only: field flips + scripts whose canonical body the
     // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
@@ -230,7 +236,7 @@ export const packageJsonShape: Rule = {
         }
         if (changes.length > 0) {
             const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
-            writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
+            atomicWrite(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
         }
         const summary = [
             changes.length > 0 ? changes.join(', ') : 'nothing mechanical to change',

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

@@ -14,6 +14,10 @@ export const contractsFulfillness: Rule = {
     blocking: true,
     title: 'contracts',
     owner: 'meta/contracts.md',
+    // the contract engine is pure filesystem (no fetch, no spawn anywhere in
+    // contracts/), and WHICH folders it reads depends on the venues declared,
+    // so the honest input is the work tree
+    inputs: ['.'],
     lint: async (t, env) => {
         applyContractsResult(t, await evaluateContractsOnce(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
     },

package/src/rules/SK003-claude-md-shape.ts

@@ -7,10 +7,11 @@
 // start --include` flags own which base include a machine wires in. A repo
 // with neither CLAUDE.md nor agent/ is not a two-line-contract repo and
 // passes.
-import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
 
 const AGENT_LINE = '@./agent/index.md'
 const LOCAL_LINE = '@./CLAUDE.local.md'
@@ -20,6 +21,10 @@ export const claudeMdShape: Rule = {
     blocking: true,
     title: 'CLAUDE.md',
     owner: 'meta/agent-folder.md',
+    // CLAUDE.md plus whether agent/index.md exists — and a repo that has
+    // neither is the case this rule exists for, so the tree rather than two
+    // paths that may not be there
+    inputs: ['.'],
     lint: async (t, env) => {
         const claudePath = join(env.root, 'CLAUDE.md')
         const hasAgent = existsSync(join(env.root, 'agent/index.md'))
@@ -59,7 +64,7 @@ export const claudeMdShape: Rule = {
         if (!existsSync(claudePath)) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start --include), not autofixable' }
         const cur = readFileSync(claudePath, 'utf8')
         if (cur.split('\n').includes(AGENT_LINE)) return { changed: false, summary: `${AGENT_LINE} already routed — remaining findings need a human` }
-        writeFileSync(claudePath, `${cur.endsWith('\n') || cur === '' ? cur : `${cur}\n`}${AGENT_LINE}\n`)
+        atomicWrite(claudePath, `${cur.endsWith('\n') || cur === '' ? cur : `${cur}\n`}${AGENT_LINE}\n`)
         return { changed: true, summary: `${AGENT_LINE} appended as the last line` }
     },
 }

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

@@ -8,11 +8,12 @@
 // 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 { existsSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync } 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'
+import { atomicWrite } from '../core/locked-write.ts'
 
 const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit outside only'
 const END = '# <<< shipkit gitignore policy'
@@ -33,6 +34,11 @@ const POLICY_LINES = [
     '.rv-discord/',
     'CLAUDE.local.md',
     'tmp/',
+    // atomicWrite lands every file via `.<name>.tmp-<pid>` next to its target,
+    // so a run killed mid write leaves one behind ANYWHERE in the tree, and an
+    // agent finds untracked debris it did not create. The ignore row ships in
+    // the same policy that started writing them.
+    '.*.tmp-*',
     // comfy-ts state (schema dumps, drafts) and per-workflow lora tags name a
     // private model collection; shipkit itself writes .comfy-ts/ at hub boot,
     // so every consumer repo needs both ignored before its first commit
@@ -92,7 +98,7 @@ function writeBlock(root: string, config: RuleEnv['config']): void {
         out = kept.length > 0 ? [...kept, '', ...block] : block
     }
     const eol = f?.crlf === true ? '\r\n' : '\n'
-    writeFileSync(p, `${out.join(eol)}${out.at(-1) === '' ? '' : eol}`)
+    atomicWrite(p, `${out.join(eol)}${out.at(-1) === '' ? '' : eol}`)
 }
 
 export const gitignorePolicy: Rule = {
@@ -100,6 +106,9 @@ export const gitignorePolicy: Rule = {
     blocking: true,
     title: '.gitignore',
     owner: 'meta/contracts.md',
+    // .gitignore plus what git currently TRACKS, which the tree carries and a
+    // single path does not
+    inputs: ['.'],
     lint: (t, env) => {
         // a generated path still in the index is the half-applied state the
         // managed block cannot fix on its own

package/src/rules/SK005-rvlib-versions.ts

@@ -16,6 +16,12 @@
 //               never touch
 //             - package.json/lockfile git-dirty (or no git) → WARN deferred,
 //               a tool must not mix its writes into human-staged work
+//             - another run already holds the repo's mutate lease → the rule
+//               WAITS for it, re-reads the dirty probe inside the lease, and
+//               defers with a WARN if that run already did the work. Two
+//               `bun update --latest` calls against one node_modules is how a
+//               tree ends up half installed, and demoting the rule to report
+//               only instead would break "machine clearable red clears ITSELF" 
 //             - the update itself failing splits by what it LEFT: a half-
 //               written package.json/lockfile is this repo and FAILs, an
 //               untouched tree is the registry and only WARNs
@@ -31,6 +37,7 @@
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
+import { mutateLease, withMutateLease } from '../core/locked-write.ts'
 import type { Rule, RuleEnv } from './rule.ts'
 
 type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -105,7 +112,27 @@ export const rvlibVersions: Rule = {
             return
         }
         const names = stale.map((s) => s.name)
-        const up = await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
+        // this rule WRITES, and three agents in one checkout is the normal
+        // case: two `bun update --latest` runs against one node_modules and
+        // one lockfile is how a tree ends up half installed. The lease is what
+        // lets the rule keep repairing itself instead of being demoted to
+        // report only, which would break "machine clearable red clears ITSELF".
+        // The dirty probe above is re-run INSIDE the lease, because the holder
+        // we waited for may have just done this exact update.
+        const leased = await withMutateLease(mutateLease(env.root, 'fix'), { label: 'self-update', print: () => {}, escape: 'SHIPKIT_FROZEN=1' }, async () => {
+            const again = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+            if (again.code === 0 && again.out.trim() !== '') return null
+            return await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
+        })
+        if (!leased.ok) {
+            t.warn(`newer rvlib live: ${drift} — self-update deferred (${leased.warn}); re-run check once that run finishes`)
+            return
+        }
+        if (leased.value == null) {
+            t.warn(`newer rvlib live: ${drift} — self-update deferred (package.json/lockfile went dirty while waiting for the write lease); commit first, then re-run check`)
+            return
+        }
+        const up = leased.value
         if (up.code !== 0) {
             // which axis the failure sits on is measurable, so measure it: the
             // tree is either half-written (this repo, blocks) or untouched, and

package/src/rules/SK006-npm-publish-safety.ts

@@ -37,6 +37,9 @@ export const npmPublishSafety: Rule = {
     blocking: true,
     title: 'npm publish safety',
     owner: 'meta/rv-conventions/package-json.md',
+    // pure filesystem: the root package.json plus every declared unit's, at
+    // dirs the config picks, so the tree rather than a list of paths
+    inputs: ['.'],
     lint: (t, env) => {
         const p = join(env.root, 'package.json')
         if (!existsSync(p)) return t.ok('no package.json — nothing publishable')

package/src/rules/SK008-reviewer-agent.ts

@@ -7,11 +7,12 @@
 // that edits by proxy. An absent `tools:` line is the worst case of all: the
 // harness then inherits every tool. The brief itself must exist. No
 // declaration = not a reviewer repo, and the rule passes silently.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, isAbsolute, join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
 
 /** default read-only toolset — an ALLOWLIST, not a denylist: a tool that can
  *  edit by proxy (spawning a subagent, an MCP writer) is exactly what a
@@ -72,6 +73,9 @@ export const reviewerAgent: Rule = {
     blocking: true,
     title: 'reviewer agent',
     owner: 'identity/how-we-work.md',
+    // the brief is a CONFIG path, and a `~/...` or absolute one puts it
+    // outside the repo, where no tree id can see whether it still exists
+    never: 'the reviewer brief may live outside the repo, where no tree id reaches it',
     lint: (t, env) => {
         const r = env.config.reviewer
         if (r == null) return t.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
@@ -93,7 +97,7 @@ export const reviewerAgent: Rule = {
         const p = join(env.root, rel)
         if (existsSync(p)) return { changed: false, summary: `${rel} exists — remaining findings are about its content, fix them by hand` }
         mkdirSync(dirname(p), { recursive: true })
-        writeFileSync(p, canonicalAgent(r))
+        atomicWrite(p, canonicalAgent(r))
         return { changed: true, summary: `${rel} written — points at ${r.brief}, no edit tools` }
     },
 }

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

@@ -29,6 +29,9 @@ export const commitAiTells: Rule = {
     blocking: true,
     title: 'commit ai tells',
     owner: 'identity/how-we-commit.md',
+    // it scans the full `git log` and every ref name. History and refs are not
+    // 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 declared = env.config.visibility ?? 'private'
         if (declared !== 'public')

package/src/rules/SK010-undeclared-release-unit.ts

@@ -65,6 +65,8 @@ export const undeclaredReleaseUnit: Rule = {
     blocking: true,
     title: 'release units declared',
     owner: 'build/shipkit.md',
+    // `git ls-files` plus a walk for every package.json in the repo
+    inputs: ['.'],
     lint: (t, env) => {
         const { units, errors } = resolveUnits(env.root, env.config)
         // a DECLARED unit that does not resolve is a declaration bug and

package/src/rules/SK011-sibling-unit-ranges.ts

@@ -59,6 +59,8 @@ export const siblingUnitRanges: Rule = {
     blocking: true,
     title: 'sibling unit ranges',
     owner: 'build/shipkit.md',
+    // every declared unit's package.json, at dirs the config picks
+    inputs: ['.'],
     lint: (t, env) => {
         const { units } = resolveUnits(env.root, env.config)
         const version = new Map(units.map((u) => [u.name, u.version]))

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

@@ -10,9 +10,10 @@
 // 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 { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
 
 const CONFIG = 'repo.config.ts'
 const BARREL = /(^|\n)(\s*import\s+(?:type\s+)?\{[^}]*\}\s+from\s+)['"]rvlib-shipkit['"]/
@@ -31,6 +32,9 @@ export const configBarrelImport: Rule = {
     blocking: true,
     title: 'config import path',
     owner: 'build/shipkit.md',
+    // ONE file, and the one file shipkit guarantees exists: loadRepoConfig
+    // refuses a repo without it
+    inputs: ['repo.config.ts'],
     lint: (t, env) => {
         const p = join(env.root, CONFIG)
         if (!existsSync(p)) return void t.ok(`${CONFIG} absent — nothing to narrow`)
@@ -54,7 +58,7 @@ export const configBarrelImport: Rule = {
         // 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}'`))
+        atomicWrite(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

@@ -12,12 +12,13 @@
 // 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 { existsSync, mkdirSync, readFileSync } 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'
+import { atomicWrite } from '../core/locked-write.ts'
 
 const OWNER = 'build/shipkit.md'
 export const SETTINGS_PATH = '.claude/settings.json'
@@ -44,6 +45,11 @@ export function guardCommand(bin?: string): string {
     return `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 readSettings = (root: string): Settings | null => {
     const p = join(root, SETTINGS_PATH)
     if (!existsSync(p)) return null
@@ -81,6 +87,9 @@ export const oneWayInPolicy: Rule = {
     blocking: true,
     title: 'one way in policy',
     owner: OWNER,
+    // .claude/settings.json, package.json, and whether the declared guard
+    // script resolves — the last one is a config-chosen path
+    inputs: ['.'],
     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')
@@ -98,10 +107,21 @@ export const oneWayInPolicy: Rule = {
             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)
+            // the hook is DECLARED either way, so it starts working the moment
+            // the dependency lands: no second fix run, nothing to remember. An
+            // uninstalled dependency is therefore a WARN naming the command
+            // 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))
+                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)`,
+                )
+            else 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)`,
+                    `point it at this repo's own copy of hooks/one-way-in-guard.ts, or delete the hook and let the deny list stand alone`,
                 )
         }
         if (!t.failed) t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s), with the replacement named`)
@@ -130,7 +150,7 @@ export const oneWayInPolicy: Rule = {
         }
         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')
+        atomicWrite(p, JSON.stringify(s, null, 2) + '\n')
         return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
     },
 }

package/src/rules/rule.ts

@@ -28,8 +28,29 @@ export type Rule = {
      *  as the fix: pointer whenever a failing/warning lint attached none */
     owner: string
     /** clean-pass cache duration (check-suite TTL, e.g. '24h') — for rules that
-     *  probe the network; skip/WARN/FAIL runs are never cached */
+     *  probe the network; skip/WARN/FAIL runs are never cached. Declares the
+     *  WORLD population (ledger/git-key.ts). */
     ttl?: string
+    /** CONTENT population: the repo-relative paths this rule reads. A rule with
+     *  neither `inputs` nor `ttl` is never cached, which is the safe default.
+     *  A rule declared by a REPO rather than by shipkit must list the dir its
+     *  own code lives in too: shipkit's `src` tree id covers the built-ins and
+     *  cannot see a repo's. Declaring both `inputs` and `ttl` is a registration
+     *  failure — a rule reads files or it reads the world, never both. */
+    inputs?: string[]
+    /** repo-relative entry file(s) of this rule's OWN code, walked through the
+     *  module graph so a shared helper the rule imports is in its key too. A
+     *  built-in SK rule needs none: the toolchain identity content-hashes
+     *  shipkit's whole source, so editing any of it moves every key. A rule a
+     *  REPO declares is invisible to that, so it names its module here, or
+     *  includes the dir holding it in `inputs`. Without either, fixing a bug
+     *  in the rule does not move its key. */
+    code?: string[]
+    /** a DECIDED never-cacheable, with the reason: this rule reads git history,
+     *  a path that may live outside the repo, or the wall clock, so no key can
+     *  describe it. Says somebody looked, which is what takes it off the
+     *  burn-down list. */
+    never?: string
     /** cache-identity contribution for TTL'd rules whose verdict depends on
      *  config — a changed key busts the cache instantly instead of replaying
      *  a stale assertion for the TTL */

package/src/rules/run-fix.ts

@@ -47,9 +47,11 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
             continue
         }
         const f = await rule.fix!(env)
-        // an unchanged fix is the DESIGNED outcome for judgment findings —
-        // a note, not a warning
-        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `[${rule.id}] fix changed nothing — ${f.summary}`)
+        // an unchanged fix is the DESIGNED outcome for judgment findings, so
+        // it is an ok, not a warning. It carries a frozen wire prefix like
+        // every other line the fix pass emits: `shipkit ci` promises its whole
+        // output is parseable, and a bare line breaks that for every reader.
+        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `ok: [${rule.id}] fix changed nothing — ${f.summary}`)
         const after = new CheckCtx(new Map())
         await runRuleLint(rule, after, env)
         // the fix already ran: advertising it again on surviving findings

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 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.
+- 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 <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
 - 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.