rvlib-shipkit 0.32.0 → 0.34.0

package/src/ledger/git-scan.ts

@@ -0,0 +1,314 @@
+// WHAT IS ON DISK RIGHT NOW, as git object ids, using git's own index.
+//
+// A cache key needs the identity of the files a unit reads, INCLUDING files
+// that are untracked or modified. `git hash-object` per file is O(files) and
+// re-reads everything; git's index already carries a stat cache that answers
+// "unchanged" without reading the blob. So: a scratch index of our own, per
+// path adds, one `write-tree`, one `cat-file --batch-check`.
+//
+// FOUR THINGS THIS FILE EXISTS TO GET RIGHT, each reproduced before it was
+// written:
+//
+//  1. PER PATH ADDS, EXIT CODE CHECKED. `git add -A -- a.txt missing/` exits
+//     128, stages NOTHING, and `write-tree` then hands back the tree of the
+//     LAST successful write. Measured on a scratch repo: the batched form
+//     returned HEAD's tree while a.txt was modified on disk, so every key
+//     derived from it described a file nobody had. One add per path turns that
+//     into one loud failure on one path.
+//  2. A MISSING DECLARED PATH IS NOT A GIT ERROR. A repo without `tests/` is
+//     normal, and hard-failing the gate on it would be wrong, so a path that
+//     does not exist never reaches `git add`: it comes back in `missing` and
+//     the caller refuses to cache that unit. That keeps rule 1's hard failure
+//     for what it is actually about, git going wrong on a path that IS there.
+//  3. ONLY AN IGNORED PATH IS FORCE ADDED. `git add -Af` on a broad path force
+//     adds node_modules and costs 17.7s; the ignored paths that genuinely hold
+//     declared inputs here (.rv-social/patreon/, .rv-assets/out/) cost 76ms.
+//     One `ls-files --others -i --directory` names them, and node_modules is
+//     refused force-add at any depth.
+//  4. THE SCRATCH INDEX IS SHARED, SO IT IS CONTENDED. Measured: 10 parallel
+//     `git add` on one index file, 9 fail with `Unable to create …lock`. Three
+//     agents in one checkout is the normal case here, so lock contention is
+//     retried and only a NON lock failure is fatal.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { isAbsolute, join, normalize } from 'path'
+
+/** what a scan measured. Every OID is a git object id of the CURRENT disk
+ *  content, tracked or not. */
+export type ScanResult = {
+    /** root tree of the scratch index after the adds */
+    treeOid: string
+    /** repo-relative path → git object id (tree for a dir, blob for a file) */
+    oidByPath: Map<string, string>
+    /** declared paths that are not on disk — the caller must not cache them */
+    missing: string[]
+    /** repo-relative path → ignored content under it that is NOT in the key
+     *  (node_modules only, by policy: toolchain-identity.ts owns installs) */
+    excluded: Map<string, string[]>
+    /** wall time of the whole scan */
+    ms: number
+}
+
+export class GitScanError extends Error {}
+
+/** the scratch index FORMAT. Bump it whenever what the scan stages changes.
+ *  The index is persistent, and anything staged into it stays there until
+ *  something stages over it: a run that force-added a path a later version no
+ *  longer touches would keep serving that path's content forever, frozen at
+ *  the moment of the bad run. A version stamp beside the file turns that into
+ *  one discarded index instead of a permanently wrong key. */
+export const SCAN_INDEX_VERSION = 2
+
+const LOCK_RE = /Unable to create '.*\.lock'|index\.lock/i
+const RETRIES = 12
+
+const git = (root: string, args: string[], indexFile: string): { code: number; out: string } => {
+    const p = Bun.spawnSync(['git', ...args], {
+        cwd: root,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { ...process.env, GIT_INDEX_FILE: indexFile },
+    })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}` }
+}
+
+/** one git call that MUST succeed. Lock contention is retried (three agents in
+ *  one checkout is normal); anything else throws with git's own words. */
+function gitOrThrow(root: string, args: string[], indexFile: string): string {
+    let last = { code: -1, out: '' }
+    for (let attempt = 0; attempt < RETRIES; attempt++) {
+        last = git(root, args, indexFile)
+        if (last.code === 0) return last.out
+        if (!LOCK_RE.test(last.out)) break
+        Bun.sleepSync(10 + attempt * 10)
+    }
+    throw new GitScanError(`git ${args.join(' ')} exited ${last.code}: ${last.out.trim().split('\n').slice(0, 3).join(' / ')}`)
+}
+
+/** the THREE index files a scan uses, and why it is three and not one.
+ *
+ *  SCRATCH is where the plain adds go, and it is COPIED FRESH from the repo's
+ *  real index on every scan. Keeping it across runs was the obvious design and
+ *  it was wrong twice, both measured. Anything staged into an index stays
+ *  staged, so a path force-added by one run rode in every later run's tree,
+ *  which made the whole-tree id a function of this machine's scan history and
+ *  reproducible on no other checkout. And a file that stopped being tracked
+ *  (`git rm --cached`) stayed in the scratch index, so the tree still carried
+ *  it and a rule keyed on tracked-ness saw nothing change. The copy costs
+ *  about 1ms and the real index is already warm, so the whole reset plus
+ *  `git add -- .` plus `write-tree` measures 30 to 40ms, FASTER than the
+ *  persistent index it replaces.
+ *
+ *  IGNORED is a separate index for the force-adds, so a path one unit named
+ *  can never leak into the whole-tree id another unit is keyed on. Without the
+ *  split, one unit's key changed depending on which OTHER units were in the
+ *  run, which is exactly the silently narrowed key the excluded list exists to
+ *  prevent. It stays warm across runs: an entry left in it can only affect the
+ *  path it belongs to, never the root tree.
+ *
+ *  REAL is read, never written, and only to answer "does git ignore this".
+ *  `ls-files --others` means UNTRACKED, so asking an index we force-add into
+ *  reports a force-added path as no longer ignored, and the next run then
+ *  plain-adds it, which exits 1 and takes the scan down. */
+export function indexPaths(root: string): { scratch: string; ignored: string; real: string } {
+    const p = Bun.spawnSync(['git', 'rev-parse', '--absolute-git-dir'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    if (p.exitCode !== 0) throw new GitScanError(`not a git repository: ${root} (${p.stderr.toString().trim()})`)
+    const gitDir = p.stdout.toString().trim()
+    const dir = join(gitDir, 'shipkit')
+    mkdirSync(dir, { recursive: true })
+    const real = join(gitDir, 'index')
+    const ignored = join(dir, 'scan-ignored.idx')
+    const stamp = join(dir, 'scan.idx.version')
+    const seen = ((): string => { try { return readFileSync(stamp, 'utf8').trim() } catch { return '' } })()
+    if (seen !== String(SCAN_INDEX_VERSION)) {
+        try { rmSync(ignored, { force: true }) } catch {}
+        try { writeFileSync(stamp, `${SCAN_INDEX_VERSION}\n`) } catch {}
+    }
+    // per-process scratch: it is rewritten from `real` every scan anyway, so
+    // sharing one file across concurrent runners buys no warmth and only adds
+    // lock contention
+    const scratch = join(dir, `scan-${process.pid}.idx`)
+    // a run that was killed leaves its file behind, and pids are reused, so
+    // sweep anything an hour old rather than trusting the pid to be free
+    try {
+        const cutoff = Date.now() - 3_600_000
+        for (const f of readdirSync(dir))
+            if (/^scan-\d+\.idx(\.tmp)?$/.test(f) && statSync(join(dir, f)).mtimeMs < cutoff) rmSync(join(dir, f), { force: true })
+    } catch {}
+    // tmp + rename: a half-copied index is a corrupt index, and git's error
+    // for that is not the one the retry loop is meant to absorb
+    try {
+        rmSync(scratch, { force: true })
+        if (existsSync(real)) {
+            const tmp = `${scratch}.tmp`
+            copyFileSync(real, tmp)
+            renameSync(tmp, scratch)
+        }
+    } catch {
+        // no seed is survivable: the adds are just colder
+    }
+    return { scratch, ignored, real }
+}
+
+/** the whole work tree as one input. A rule that walks the repo (SK001's test
+ *  file probe, SK010's `git ls-files`) genuinely reads all of it, and saying so
+ *  is more honest than naming three of the files it happens to open. Its object
+ *  id is the scan's root tree, so it moves on any edit anywhere. */
+export const WHOLE_TREE = '.'
+
+/** repo-relative posix, no './', no trailing slash. Throws on anything that
+ *  escapes the repo — a key component outside the tree is a key nobody else
+ *  can reproduce. */
+export function normalizeInput(p: string): string {
+    const n = normalize(p).replace(/\\/g, '/').replace(/\/+$/, '').replace(/^\.\//, '')
+    if (n === '.' || n === '') return WHOLE_TREE
+    if (isAbsolute(p) || n === '..' || n.startsWith('../'))
+        throw new GitScanError(`input path '${p}' is outside the repo — declare a path inside it, or '.' for the whole work tree`)
+    return n
+}
+
+/** drop paths already covered by an ancestor in the same set: adding `wiki`
+ *  stages `wiki/build/...` too, and a second add of the child is pure cost. */
+export function dropCovered(paths: string[]): string[] {
+    if (paths.includes(WHOLE_TREE)) return [WHOLE_TREE]
+    const sorted = [...new Set(paths)].sort()
+    const kept: string[] = []
+    for (const p of sorted) if (!kept.some((k) => p === k || p.startsWith(`${k}/`))) kept.push(p)
+    return kept
+}
+
+const underNodeModules = (p: string): boolean => p.split('/').includes('node_modules')
+
+/**
+ * stage `paths` into the scratch index and read back one git object id each.
+ *
+ * Throws `GitScanError` on any git failure that is not lock contention. The
+ * caller's contract on a throw is absolute: produce NO key. A tree that may be
+ * stale describes files nobody has, and a key built on it is a false green
+ * waiting for its first hit.
+ */
+export function scanPaths(root: string, rawPaths: string[]): ScanResult {
+    const started = performance.now()
+    const { scratch: indexFile, ignored: ignoredIndex, real: realIndex } = indexPaths(root)
+    const wanted = [...new Set(rawPaths.map(normalizeInput))].sort()
+    const missing = wanted.filter((p) => !existsSync(join(root, p)))
+    const present = wanted.filter((p) => existsSync(join(root, p)))
+    const toAdd = dropCovered(present)
+    const named = wanted.filter((p) => p !== WHOLE_TREE)
+
+    // ignored content under what we are about to stage. One call, and it also
+    // answers "is this declared path itself ignored": `--directory` collapses
+    // a dir whose ENTIRE content is ignored, so the answer comes back as the
+    // dir with a trailing slash.
+    const ignored = toAdd.length === 0
+        ? []
+        : gitOrThrow(root, ['ls-files', '--others', '-i', '--exclude-standard', '--directory', '--', ...toAdd], realIndex)
+            .split('\n')
+            .map((l) => l.trim().replace(/\/+$/, ''))
+            .filter((l) => l !== '')
+    // ONLY a path a declaration NAMES is force-added. Ignored content that
+    // merely sits under a declared path is reported and left out.
+    //
+    // This is the whole of defense 3, and the wide reading of it is a disaster
+    // measured twice: with `.` declared (which every repo-walking rule
+    // declares), "ignored content under a declared path" is every ignored path
+    // in the repo, so one run force-staged two entire worktrees, the log dir,
+    // the private model dumps and the prompt corpora, for 680ms. Naming the
+    // path is what makes it an input.
+    //
+    // Installs are refused on top of that, at any depth AND as an ancestor:
+    // `--directory` collapses a dir whose entire content is ignored, so
+    // force-adding that one entry stages the node_modules inside it.
+    const declared = new Set(wanted)
+    const denied = ignored.filter(underNodeModules)
+    const forceAdd = ignored.filter((p) => declared.has(p) && !underNodeModules(p) && !denied.some((d) => d.startsWith(`${p}/`)))
+    // a path git itself calls ignored must NOT get the plain add: `git add --
+    // <ignored>` exits 1 and takes the whole scan down with it
+    const ignoredSet = new Set(ignored)
+    for (const p of toAdd) if (!ignoredSet.has(p)) gitOrThrow(root, ['add', '--', p], indexFile)
+    // force-adds land in their OWN index, so a path one unit named can never
+    // ride inside the whole-tree id another unit is keyed on
+    for (const p of forceAdd) gitOrThrow(root, ['add', '-Af', '--', p], ignoredIndex)
+
+    const treeOid = gitOrThrow(root, ['write-tree'], indexFile).trim()
+    const oidByPath = new Map<string, string>()
+    // the work tree's own id IS the tree the adds just produced — there is no
+    // `<tree>:` path to ask git for
+    if (wanted.includes(WHOLE_TREE)) oidByPath.set(WHOLE_TREE, treeOid)
+    const forceSet = new Set(forceAdd)
+    const plain = named.filter((p) => !forceSet.has(p))
+    for (const [tree, paths, index] of [[treeOid, plain, indexFile], [null, forceAdd, ignoredIndex]] as const) {
+        if (paths.length === 0) continue
+        const root_ = tree ?? gitOrThrow(root, ['write-tree'], index).trim()
+        const query = paths.map((p) => `${root_}:${p}`).join('\n')
+        const p = Bun.spawnSync(['git', 'cat-file', '--batch-check'], {
+            cwd: root,
+            stdin: Buffer.from(`${query}\n`),
+            stdout: 'pipe',
+            stderr: 'pipe',
+            env: { ...process.env, GIT_INDEX_FILE: index },
+        })
+        if (p.exitCode !== 0) throw new GitScanError(`git cat-file --batch-check exited ${p.exitCode}: ${p.stderr.toString().trim()}`)
+        const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
+        if (lines.length !== paths.length)
+            throw new GitScanError(`git cat-file --batch-check answered ${lines.length} of ${paths.length} paths`)
+        paths.forEach((path, i) => {
+            const oid = lines[i]!.split(' ')[0] ?? ''
+            // 'missing' / 'ambiguous' come back in place of an id — a path git
+            // cannot name is a path we cannot key on
+            if (/^[0-9a-f]{40}$/.test(oid)) oidByPath.set(path, oid)
+            else if (!missing.includes(path)) missing.push(path)
+        })
+    }
+
+    const excluded = new Map<string, string[]>()
+    for (const d of ignored) {
+        // EVERY owner that covers it, not the first one found, and membership
+        // must not depend on what OTHER units declared. `.` sorts first and
+        // covers everything, so a `find` here handed the whole exclusion list
+        // to the whole-tree unit and left every narrower unit claiming it was
+        // blind to nothing. Filtering force-added paths out globally had the
+        // same shape: one unit naming `ign` deleted `excluded=ign` from a
+        // whole-tree unit that is still blind to it. Measured both ways, one
+        // unit producing two keys for one unchanged tree, and the component
+        // that vanished is the one that exists to stop a silently narrowed key.
+        for (const w of wanted) {
+            if (!(w === WHOLE_TREE || d === w || d.startsWith(`${w}/`))) continue
+            // the one owner that is NOT blind: it named the path itself, so it
+            // got the content through the force-add
+            if (d === w && forceSet.has(d)) continue
+            excluded.set(w, [...(excluded.get(w) ?? []), d])
+        }
+    }
+    return { treeOid, oidByPath, missing: [...new Set(missing)].sort(), excluded, ms: performance.now() - started }
+}
+
+/**
+ * blob ids for a list of FILES, one process, no index, no lock.
+ *
+ * The scratch index is the right tool for a declared input, which is usually a
+ * directory and usually unchanged (git's stat cache answers without reading).
+ * It is the wrong tool for the module-graph closure: those are individual
+ * files, they belong to no declared path, and staging each one would cost a
+ * `git add` spawn per file. `hash-object --stdin-paths` reads them all in one
+ * call and returns exactly what a blob of that content would be.
+ *
+ * A file that is not on disk is skipped and reported, never guessed at.
+ */
+export function hashFiles(root: string, files: string[]): { oids: Map<string, string>; missing: string[] } {
+    const oids = new Map<string, string>()
+    const wanted = [...new Set(files.map(normalizeInput))].sort()
+    const missing = wanted.filter((f) => !existsSync(join(root, f)))
+    const present = wanted.filter((f) => existsSync(join(root, f)))
+    if (present.length === 0) return { oids, missing }
+    const p = Bun.spawnSync(['git', 'hash-object', '--stdin-paths'], {
+        cwd: root,
+        stdin: Buffer.from(`${present.join('\n')}\n`),
+        stdout: 'pipe',
+        stderr: 'pipe',
+    })
+    if (p.exitCode !== 0) throw new GitScanError(`git hash-object exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n').slice(0, 3).join(' / ')}`)
+    const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
+    if (lines.length !== present.length) throw new GitScanError(`git hash-object answered ${lines.length} of ${present.length} files`)
+    present.forEach((f, i) => oids.set(f, lines[i]!.trim()))
+    return { oids, missing }
+}

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,12 +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, type RepoConfig } from '../repo-config.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> }
 
@@ -165,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
@@ -229,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