rvlib-shipkit 0.33.0 → 0.35.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[] = []
@@ -75,6 +75,36 @@ function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
     h.update(`clifiles=${files.length}\n`)
 }
 
+/**
+ * what ONE install holds, as a hash: every top-level package's name, version
+ * and link target.
+ *
+ * Exported because a repo's own install is not the only one a gate can run
+ * against. Sub-packages carry their own `node_modules`, gitignored like every
+ * other, so no git key can see them and the root toolchain does not describe
+ * them either. A unit whose declared inputs COVER such a directory folds this
+ * in beside the path, or the toolchain component stops at the repo root while
+ * the task it is meant to describe does not.
+ *
+ * ~2ms per install, and only for a path a scan already reported as ignored.
+ */
+export function installIdentity(nodeModules: string): string {
+    if (!existsSync(nodeModules)) return 'install=absent'
+    const h = createHash('sha256')
+    let names: string[] = []
+    try { names = installedNames(nodeModules) } catch { return 'install=unreadable' }
+    for (const n of names) {
+        const dir = join(nodeModules, n)
+        let version = 'MISSING'
+        try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
+        let link = ''
+        try { if (lstatSync(dir).isSymbolicLink()) link = `->${realpathSync(dir)}` } catch {}
+        h.update(`${n}@${version}${link}\n`)
+    }
+    h.update(`n=${names.length}\n`)
+    return `install=${h.digest('hex').slice(0, 16)}`
+}
+
 /**
  * the identity of the program about to run, for `repoRoot`, driven by `cliEntry`.
  *
@@ -94,12 +124,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/pb/collection-scaffold.ts

@@ -101,7 +101,7 @@ function columnsFile(col: PbCollection): string {
     lines.push('// means the cell is derived and the database cannot order by it.')
     lines.push('// labels are plain text, swap them for i18n.t.<collection>.<field> when the')
     lines.push('// app carries a dict.')
-    lines.push(`import type { Column } from "rvlib-pb-shell"`)
+    lines.push(`import type { Column } from "rvlib-pb/ui"`)
     lines.push(`import type { ${col.prefix}Response } from "${TYPES}"`)
     lines.push('')
     lines.push(`export const columns: Column<${col.prefix}Response>[] = [`)
@@ -144,8 +144,8 @@ function gridFile(col: PbCollection): string {
     return [
         `// the default grid for \`${col.name}\`. A page that wants the plain table renders`,
         '// this; a page that wants extra columns passes its own to LiveGrid directly.',
-        `import type { LiveList } from "rvlib-pb-mobx"`,
-        `import { LiveGrid } from "rvlib-pb-shell"`,
+        `import type { LiveList } from "rvlib-pb"`,
+        `import { LiveGrid } from "rvlib-pb/ui"`,
         `import type { ${col.prefix}Response } from "${TYPES}"`,
         `import { columns } from "./columns"`,
         '',
@@ -247,7 +247,7 @@ function indexFile(col: PbCollection, hasForm: boolean): string {
     lines.push('// registration: after this import, a LiveGrid or LiveCards over')
     lines.push(`// \`${col.name}\` with no columns of its own knows what to render, and any`)
     lines.push('// relation cell pointing AT one knows how to name it.')
-    lines.push(`import { defineCollectionUI } from "rvlib-pb-shell"`)
+    lines.push(`import { defineCollectionUI } from "rvlib-pb/ui"`)
     lines.push(`import { db } from "${PB}"`)
     lines.push(`import { ${col.prefix}Card } from "./card"`)
     lines.push(`import { columns } from "./columns"`)

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/run-release.ts

@@ -110,6 +110,11 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         frozen: true,
         status: false,
         config,
+        // THE CAP ON EVERY REMAINING HOLE IN THE KEY. Not a flag, not a config
+        // field: a release re-measures every unit, so the worst a wrong key
+        // can ever produce is an agent looking at a stale local green, never a
+        // stale green that authorised a publish (ledger/ledger.ts rule 4).
+        ledgerRead: false,
         // the FULL tier, always. A release runs on a clean tree with time to
         // spare, and the suites the working gate skips (the ones that build
         // real repositories) are exactly the ones a publish must not be wrong

package/src/release/run-releases.ts

@@ -204,7 +204,13 @@ export function attentionLines(r: UnitReport): string[] {
     // shape of a command
     const KIND = '<patch|minor|major>'
 
-    if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
+    if (r.npmTarget && r.npmLatest === 'unpublished') {
+        // NO version of this name is on the registry, which every drift branch
+        // below reads as "a bit behind" and none of them says. Every `bun add
+        // <name>` in a doc, a seed or a scaffold answers 404 while this holds,
+        // and that is the one state where the docs are not stale but dead
+        out.push(`WARN ${r.id}: nothing is published under the name ${r.name} — every "bun add ${r.name}" 404s until ${notesClause}shipkit bump ${KIND} ${r.id}`)
+    } else if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
         // the trap: a version stamped into package.json while work kept
         // landing. Publishing it ships that work under notes describing none
         // of it, so the answer is a NEW version, never this one.

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

@@ -23,7 +23,7 @@ import type { Rule } from './rules/rule.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
-import type { TaskDef } from './core/task-runner.ts'
+import { TASK_DEF_KEYS, type TaskDef } from './core/task-runner.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
 
@@ -51,8 +51,13 @@ export type RepoConfig = {
     social?: string[]
     /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
     docsBase?: string
-    /** override a floor task's def, or `false` to disable (always visible) */
-    defaults?: Record<string, TaskDef | false>
+    /** a floor slot: `false` disables it (always visible), a def with a
+     *  `cmd` or `logic` REPLACES it, and a def with neither DECORATES whatever
+     *  fills it. The decoration is how a repo declares what its own `test`
+     *  script reads (`{ test: { inputs: ['tests', 'src'] } }`) without
+     *  restating the command: the read set is repo knowledge, the command is
+     *  already in package.json, and restating it is a second source of truth. */
+    defaults?: Record<string, Partial<TaskDef> | false>
     /** repo-specific commit-gate tasks; deps double as race guards */
     tasks?: TaskDef[]
     /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
@@ -158,9 +163,19 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (isAbsolute(d) || rel === '.' || rel === '' || rel === '..' || rel.startsWith('../'))
             throw new Error(`defineRepo: notReleasable '${d}' is the repo root or outside it, and would excuse every package at once — name one package dir per entry`)
     }
-    for (const k of Object.keys(c.defaults ?? {}))
+    for (const [k, slot] of Object.entries(c.defaults ?? {})) {
         if (!(FLOOR_IDS as readonly string[]).includes(k))
             throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
+        // the slot's own FIELDS, not just its name. A slot with no cmd or logic
+        // decorates the resolved task, so a typo there (`input` for `inputs`)
+        // is not a type error at any call site and lands as a task that is
+        // simply never cached, silently, which is the one direction this file
+        // promises a typo cannot go.
+        if (slot === false || slot == null) continue
+        for (const f of Object.keys(slot))
+            if (!(TASK_DEF_KEYS as readonly string[]).includes(f))
+                throw new Error(`defineRepo: defaults.${k}.${f} is not a task field (fields: ${TASK_DEF_KEYS.join(', ')})`)
+    }
     for (const n of c.oneWayIn?.exempt ?? [])
         if (!(ROUTED_SCRIPTS as readonly string[]).includes(n))
             throw new Error(`defineRepo: oneWayIn.exempt '${n}' is not a governed script name (governed: ${ROUTED_SCRIPTS.join(', ')})`)
@@ -181,6 +196,13 @@ export async function loadRepoConfig(root: string): Promise<RepoConfig> {
 // the contracts commit-gate task — venue deploy tasks should dep on it.
 // Same SK002-tagged rendering as `shipkit check` and `shipkit contracts`
 // (contracts/apply-contracts.ts is the one bridge).
+//
+// DELIBERATELY UNDECLARED for the ledger, and this is where that decision
+// lives rather than in a commit message. It runs in process, shares one
+// evaluation with rule SK002 through `withContractsScope`, and measures 0.0s,
+// so a key would be risk against no reward. It is not `never:` either: the
+// contract dirs describe it perfectly well, so claiming nothing can is false,
+// and `never` has to keep meaning "somebody looked and no key exists".
 export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',

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

@@ -1,6 +1,5 @@
 // SK004 — the .gitignore policy block (meta/contracts.md git policy; tmp/
-// included because shipkit itself writes tmp/.shipkit-cache in every
-// repo). A marker-keyed managed block so the always-gitignored contract
+// included because shipkit writes its per-run logs there in every repo). A marker-keyed managed block so the always-gitignored contract
 // surfaces can never silently rot per repo. Ecosystem-specific names the
 // published lib may not carry ride as repo-contributed lines:
 // `defineRepo({ gitignore: [...] })` renders them INSIDE the block, so the
@@ -8,11 +7,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 +33,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 +97,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 +105,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)` }
     },
 }