rvlib-shipkit 0.30.0 → 0.32.0

package/src/pb/run-pb.ts

@@ -0,0 +1,157 @@
+// `shipkit pb collection <name>` — the fs half. Runs in the CONSUMING app's
+// cwd, reads its generated pb types, writes src/collections/<name>/ and
+// registers the folder in src/collections/index.ts.
+//
+// Writes are CREATE-ONLY for the folder: a path that exists is reported and
+// left byte for byte as it is, so re-running after a schema change can never
+// eat hand-written UI. What that costs is that a stale file is never
+// refreshed, which is the trade a scaffold has to make. The registration
+// index is the one ADDITIVE write: a folder nothing imports is dead code, and
+// the failure mode is a runtime throw rather than a compile error.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { scaffoldCollectionUI, type ScaffoldedFile } from './collection-scaffold.ts'
+import { isSystemCollection, parsePbTypes, type PbCollection } from './pb-types.ts'
+
+export type PbIo = { print: (line: string) => void; printErr: (line: string) => void }
+
+/** where an app keeps pocketbase-typegen output, in the order we look */
+export const TYPES_CANDIDATES = ['src/pb.types.ts', 'src/pb.types.tsx', 'src/pb.types.d.ts', 'pb.types.ts'] as const
+
+export function findTypesFile(root: string): string | null {
+    for (const rel of TYPES_CANDIDATES) if (existsSync(join(root, rel))) return rel
+    return null
+}
+
+const TYPEGEN_HINT = 'npx pocketbase-typegen --url <instance-url> --email <admin> --password <pw> --out src/pb.types.ts'
+
+const REGISTRY = 'src/collections/index.ts'
+const REGISTRY_HEADER = [
+    '// ONE import wires every collection\'s UI. main.tsx imports this file and',
+    '// nothing else, so a collection that is not registered here is a missing',
+    '// import rather than a blank table at runtime.',
+    '//',
+    '// `shipkit pb collection <name>` creates a folder here from pb.types.ts.',
+    '',
+].join('\n')
+
+/** names close enough to be the one that was meant */
+function nearest(want: string, have: string[]): string[] {
+    const w = want.toLowerCase().replace(/[_-]/g, '')
+    return have.filter((n) => {
+        const h = n.toLowerCase().replace(/[_-]/g, '')
+        return h === w || h.startsWith(w) || w.startsWith(h)
+    })
+}
+
+export type PbCollectionOpts = { dryRun: boolean }
+
+export function runPbCollection(root: string, name: string, io: PbIo, opts: PbCollectionOpts): number {
+    const typesRel = findTypesFile(root)
+    if (typesRel == null) {
+        io.printErr(`FAIL: no ${TYPES_CANDIDATES[0]} here — this command runs in the root of a PocketBase app`)
+        io.printErr(`      fix: generate the types first: ${TYPEGEN_HINT}`)
+        return 1
+    }
+    let collections: PbCollection[]
+    try {
+        collections = parsePbTypes(readFileSync(join(root, typesRel), 'utf8'))
+    } catch (e) {
+        io.printErr(`FAIL: ${typesRel} could not be read: ${e instanceof Error ? e.message : String(e)}`)
+        return 1
+    }
+    if (collections.length === 0) {
+        io.printErr(`FAIL: ${typesRel} describes no collection — it does not look like pocketbase-typegen output`)
+        io.printErr(`      fix: regenerate it: ${TYPEGEN_HINT}`)
+        return 1
+    }
+    const col = collections.find((c) => c.name === name)
+    if (col == null) {
+        // pocketbase's own `_`-prefixed collections are never an app surface, so
+        // offering them as choices sends the reader somewhere they cannot go
+        const names = collections.filter((c) => !isSystemCollection(c.name)).map((c) => c.name)
+        const close = nearest(name, names)
+        io.printErr(`FAIL: no collection '${name}' in ${typesRel}`)
+        if (close.length > 0) io.printErr(`      fix: did you mean ${close.join(', ')} ?`)
+        io.printErr(`      fix: known collections: ${names.join(', ')}`)
+        return 1
+    }
+    if (isSystemCollection(col.name)) {
+        io.printErr(`FAIL: '${col.name}' is one of pocketbase's internal collections, not an app surface`)
+        io.printErr('      fix: scaffold one of your own collections instead')
+        return 1
+    }
+    if (!col.readable) {
+        io.printErr(`FAIL: ${typesRel} names '${col.name}' but its ${col.prefix}Record block is missing or unreadable`)
+        io.printErr(`      fix: regenerate the types: ${TYPEGEN_HINT}`)
+        return 1
+    }
+    // a field the parser could not read is a column the developer never sees,
+    // so it is named rather than dropped
+    for (const line of col.unparsed) io.print(`WARN ${typesRel}: unread field line in ${col.prefix}Record: ${line}`)
+    const unknown = col.fields.filter((f) => f.kind === 'unknown')
+    // every DECLARED field unrecognised is a PARSE failure wearing a schema's
+    // clothes: the folder it would write is entirely commented out and useless.
+    // The response fields we append ourselves cannot vouch for the parse
+    const declared = col.fields.filter((f) => !f.system)
+    if (declared.length > 0 && unknown.length === declared.length) {
+        io.printErr(`FAIL: not one field of ${col.prefix}Record parsed — ${typesRel} is not in a shape this reads`)
+        io.printErr(`      fix: regenerate it unformatted: ${TYPEGEN_HINT}`)
+        return 1
+    }
+    for (const f of unknown) io.print(`WARN ${col.prefix}Record.${f.name}: unrecognised type '${f.type}', its column is commented out`)
+
+    return report(scaffoldCollectionUI(col), io, col, root, opts.dryRun)
+}
+
+/** the `import "./<name>"` line the registry needs, added without touching
+ *  anything already in the file. Returns what happened. */
+function registerInIndex(root: string, name: string, dry: boolean): 'added' | 'present' | 'created' {
+    const abs = join(root, REGISTRY)
+    const line = `import "./${name}"`
+    if (!existsSync(abs)) {
+        if (!dry) {
+            mkdirSync(dirname(abs), { recursive: true })
+            writeFileSync(abs, `${REGISTRY_HEADER}${line}\n`)
+        }
+        return 'created'
+    }
+    const cur = readFileSync(abs, 'utf8')
+    if (cur.includes(line)) return 'present'
+    if (!dry) writeFileSync(abs, `${cur.replace(/\n*$/, '')}\n${line}\n`)
+    return 'added'
+}
+
+function report(files: ScaffoldedFile[], io: PbIo, col: PbCollection, root: string, dry: boolean): number {
+    const written: string[] = []
+    const kept: string[] = []
+    for (const f of files) {
+        const abs = join(root, f.rel)
+        if (existsSync(abs)) {
+            kept.push(f.rel)
+            io.print(`skip: ${f.rel} (exists, left as is)`)
+            continue
+        }
+        written.push(f.rel)
+        io.print(`ok: ${dry ? 'would write' : 'wrote'} ${f.rel} (${f.body.split('\n').length - 1} lines)`)
+        if (dry) continue
+        mkdirSync(dirname(abs), { recursive: true })
+        writeFileSync(abs, f.body)
+    }
+    const reg = registerInIndex(root, col.name, dry)
+    const reword = { added: dry ? 'would register' : 'registered', created: dry ? 'would create' : 'created', present: 'already registers' } as const
+    io.print(`${reg === 'present' ? 'skip' : 'ok'}: ${REGISTRY} ${reword[reg]} ./${col.name}`)
+
+    if (dry) {
+        for (const f of files) {
+            if (kept.includes(f.rel)) continue
+            io.print(`=== ${f.rel}`)
+            for (const line of f.body.replace(/\n$/, '').split('\n')) io.print(line)
+        }
+        io.print(`ok: ${col.name} — dry run, ${written.length} file(s) would be written, ${kept.length} left as is`)
+        return 0
+    }
+    io.print(`ok: ${col.name} — ${written.length} file(s) written, ${kept.length} left as is`)
+    if (written.length > 0) io.print(`ok: prune what you do not need, then render <${col.prefix}Grid list={list} /> from a page`)
+    return 0
+}

package/src/release/git-facts.ts

@@ -30,9 +30,10 @@ export function deriveRemote(root: string): { remote: string } | { error: string
 /** the worktree's dirty paths, minus the runner's own log dir. running the
  *  gate creates that dir, so counting it would make every gated release refuse
  *  in any repo that does not gitignore it. */
-export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string): string {
+export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string | string[]): string {
     const logRoot = (config.logDir ?? 'tmp/shipkit-ci').replace(/^\.\//, '').split('/')[0]!
-    const args = pathspec != null && pathspec !== '' ? ['status', '--porcelain', '--', pathspec] : ['status', '--porcelain']
+    const specs = (typeof pathspec === 'string' ? [pathspec] : (pathspec ?? [])).filter((p) => p !== '')
+    const args = specs.length > 0 ? ['status', '--porcelain', '--', ...specs] : ['status', '--porcelain']
     return git(root, args).out
         .split('\n')
         .filter((l) => l.trim() !== '' && !l.slice(3).trim().replace(/^"|"$/g, '').startsWith(`${logRoot}/`) && l.slice(3).trim() !== `${logRoot}/`)

package/src/release/release-scope.ts

@@ -0,0 +1,52 @@
+// WHAT DIRT ACTUALLY BLOCKS A RELEASE.
+//
+// The clean-tree rule exists so a release is REPRODUCIBLE from a commit: the
+// tag must describe exactly what shipped. That argument covers the paths the
+// release writes or packs, and nothing else. It was implemented as "the whole
+// worktree", which is the same one-checkout-one-agent assumption that used to
+// live in the launcher: with several agents in one repo, a sub-unit bump got
+// refused three times in a row for uncommitted files in OTHER units, none of
+// which can reach its tarball and none of which the tag would contain either
+// way. Correctness across the repo is the GATE's job, and the gate runs.
+//
+// So a SUB-UNIT bump refuses on dirt it could actually be wrong about:
+//   - the unit's own directory, and its changelog wherever it is declared
+//   - every unit's package.json, because a bump rewrites dependents' rvlib
+//     ranges (SK011) and that write lands in the version commit
+//   - the lockfiles, which a version change can move
+// A ROOT bump keeps the whole-tree rule, because the root unit IS the repo.
+import { relative } from 'path'
+
+import type { ReleaseUnit } from './units.ts'
+
+/** lockfiles a version write can move, at the repo root */
+const LOCKFILES = ['bun.lock', 'bun.lockb', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']
+
+export type ReleaseScope = {
+    /** pathspecs to test for dirt, or null for the whole worktree */
+    specs: string[] | null
+    /** one line saying what was examined, for the refusal and the note */
+    describe: string
+}
+
+/**
+ * the paths a bump of `targets` may write. `null` specs means "the whole
+ * tree", which is the honest answer for a root bump.
+ */
+export function releaseScope(root: string, allUnits: ReleaseUnit[], targets: ReleaseUnit[]): ReleaseScope {
+    // the root unit is the repo: nothing in the tree is outside its release
+    if (targets.length === 0 || targets.some((u) => u.rel === '')) return { specs: null, describe: 'the whole worktree (a root release ships the repo)' }
+    const specs = new Set<string>()
+    for (const u of targets) {
+        specs.add(u.rel)
+        // a unit can declare its changelog outside its own directory
+        specs.add(relative(root, u.changelog))
+    }
+    // a bump rewrites the rvlib range in every dependent's package.json
+    for (const u of allUnits) specs.add(u.rel === '' ? 'package.json' : `${u.rel}/package.json`)
+    for (const f of LOCKFILES) specs.add(f)
+    return {
+        specs: [...specs].sort(),
+        describe: `${targets.map((u) => u.rel).join(', ')} plus every package.json and lockfile the version commit can touch`,
+    }
+}

package/src/release/releases-share.ts

@@ -0,0 +1,85 @@
+// ONE release survey per gate run, shared across processes.
+//
+// WHY A FILE AND NOT A MEMO: `collectReports` costs ~3.9s (a registry fetch
+// and a `gh release view` per unit, now concurrent) and FIVE discovered checks
+// call it. Those checks each run in their own `bun <path>` subprocess, so an
+// in-process memo cannot see the other four: the run paid for the same survey
+// five times. The parent hands children a path through the environment, the
+// first one to arrive computes and writes it, the rest read it.
+//
+// It is a RUN scope, never a TTL: the path is created per gate run and the
+// data is never reused across runs. A survey that outlived its run would let a
+// stale green describe a repo that has since published, which is exactly the
+// class of lie a release gate must not tell.
+import { existsSync, mkdirSync, openSync, readFileSync, writeSync, closeSync, unlinkSync } from 'fs'
+import { dirname } from 'path'
+
+/** the env var the parent sets and children read */
+export const SHARE_ENV = 'SHIPKIT_RELEASES_SHARE'
+
+const LOCK_SUFFIX = '.lock'
+/** how long a reader waits for the writer before doing the work itself. Well
+ *  past the ~4s survey, and a timeout costs a duplicate survey, never a wrong
+ *  answer, so it is deliberately generous. */
+const WAIT_MS = 30_000
+const POLL_MS = 50
+
+const read = <T,>(path: string): T | null => {
+    try {
+        const raw = readFileSync(path, 'utf8')
+        return raw === '' ? null : (JSON.parse(raw) as T)
+    } catch { return null }
+}
+
+/** claim the right to compute. Atomic: `wx` fails if anyone else holds it. */
+const claim = (lock: string): number | null => {
+    try {
+        mkdirSync(dirname(lock), { recursive: true })
+        return openSync(lock, 'wx')
+    } catch { return null }
+}
+
+/**
+ * run `compute` at most once per gate run, across every process in it.
+ *
+ * With no share path set (a direct `shipkit releases`, a test, any single
+ * process) this is just `compute()`, so the sharing is invisible to callers.
+ */
+export async function shared<T>(compute: () => Promise<T>): Promise<T> {
+    const path = process.env[SHARE_ENV]
+    if (path == null || path === '') return await compute()
+    const hit = read<T>(path)
+    if (hit != null) return hit
+
+    const lock = `${path}${LOCK_SUFFIX}`
+    const fd = claim(lock)
+    if (fd == null) {
+        // someone else is surveying: wait for their answer rather than
+        // duplicating a network round trip per unit
+        const until = Date.now() + WAIT_MS
+        while (Date.now() < until) {
+            await Bun.sleep(POLL_MS)
+            const late = read<T>(path)
+            if (late != null) return late
+            // the writer died without writing: the lock is gone and so is the
+            // answer, so stop waiting for it
+            if (!existsSync(lock)) break
+        }
+        return await compute()
+    }
+    try {
+        const value = await compute()
+        // written through the lock fd's sibling path, then the lock released,
+        // so a reader never sees a half-written file
+        const tmp = `${path}.tmp-${process.pid}`
+        const t = openSync(tmp, 'w')
+        writeSync(t, JSON.stringify(value))
+        closeSync(t)
+        await Bun.write(path, Bun.file(tmp))
+        try { unlinkSync(tmp) } catch {}
+        return value
+    } finally {
+        closeSync(fd)
+        try { unlinkSync(lock) } catch {}
+    }
+}

package/src/release/run-bump.ts

@@ -32,6 +32,7 @@ import { join, relative } from 'path'
 import { declaredKind, hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
 import { deriveRemote, dirtyPathList, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
 import { unitBlockers } from './unit-gate.ts'
+import { releaseScope } from './release-scope.ts'
 import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
 import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -62,6 +63,10 @@ export type BumpOpts = {
     unit?: string
     /** bump every unit whose changelog carries non-empty Unreleased notes */
     all?: boolean
+    /** proceed even with dirt inside the release scope. The scoping below
+     *  already ignores dirt that cannot reach this release; this is the
+     *  documented way through when it judges wrong, and matches `release`. */
+    allowDirty?: boolean
     print?: (line: string) => void
 }
 
@@ -207,6 +212,14 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
             return 1
         }
     }
+    // WHICH dirt can actually reach this release. A sub-unit bump writes its
+    // own directory, its changelog, every dependent's package.json (SK011
+    // range rewrites land in the version commit) and the lockfiles; nothing
+    // else in the worktree can enter its tarball or its tag. Refusing on the
+    // rest stalls three agents in one repo for work that cannot affect them.
+    const targets = o.all === true ? onDisk.units : [unitById(onDisk.units, o.unit ?? 'root')!]
+    const scope = releaseScope(root, onDisk.units, targets)
+
     // surfaces the toolkit itself rewrites on gate runs, safe to auto-commit
     const machineWrittenPaths = (r: string, c: RepoConfig): Set<string> => {
         const s = new Set(['STATUS.md'])
@@ -223,7 +236,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     // the motherhome row) re-dirty on every gate run, so when they are the
     // ONLY dirt the preflight commits them itself instead of bouncing the
     // release back to a human (field wart 2026-08-04: three refusals in a row)
-    const preDirty = dirtyPaths(root, config)
+    const preDirty = dirtyPaths(root, config, scope.specs ?? undefined)
     if (preDirty !== '') {
         const machine = machineWrittenPaths(root, config)
         const paths = dirtyPathList(preDirty)
@@ -238,8 +251,15 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
             print(`note: dirt beyond the machine rows (${paths.filter((p) => !machine.has(p)).join(', ')}), not auto-committing`)
         }
     }
-    const dirty = dirtyPaths(root, config)
-    if (dirty !== '') { print(`FAIL: working tree not clean, commit your work first:\n${dirty.split('\n').slice(0, 10).join('\n')}`); return 1 }
+    const dirty = dirtyPaths(root, config, scope.specs ?? undefined)
+    if (dirty !== '' && o.allowDirty !== true) {
+        print(`FAIL: uncommitted changes inside what this release writes:\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+        print(`      fix: commit them, or re-run with --allow-dirty (examined ${scope.describe})`)
+        if (scope.specs != null) print('      note: dirt elsewhere in the worktree is deliberately ignored, it cannot reach this tarball or this tag')
+        return 1
+    }
+    if (dirty !== '') print(`WARN --allow-dirty: releasing with uncommitted changes inside the release scope, the tag will not contain them:\n${dirty.split('\n').slice(0, 6).join('\n')}`)
+    if (scope.specs != null) print(`note: dirt checked in ${scope.describe}`)
 
     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 }
@@ -369,13 +389,16 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     // the gate's fix pass can rewrite files. writing a version on top of that
     // produces a version commit that excludes the rewrite and a release that
     // then refuses on a dirty tree, which is a half-released repo.
-    const afterGate = dirtyPaths(root, config)
-    if (afterGate !== '')
+    // scoped like the preflight, and for the same reason: this exists to catch
+    // a FIXER rewriting what is about to ship, not to notice that another
+    // agent saved a file in an unrelated unit while the gate ran
+    const afterGate = dirtyPaths(root, config, scope.specs ?? undefined)
+    if (afterGate !== '' && o.allowDirty !== true)
         return fail(
-            `the gate rewrote files, so the tree is no longer clean:\n${afterGate.split('\n').slice(0, 10).join('\n')}`,
+            `the gate rewrote files this release writes, so what would ship is no longer what was gated:\n${afterGate.split('\n').slice(0, 10).join('\n')}`,
             rollback != null
-                ? 'the rollback below discards them. run `shipkit ci` on your branch, commit what it rewrites, then bump again'
-                : 'run `shipkit ci`, commit what it rewrites, then bump again',
+                ? 'the rollback below discards them. run `shipkit ci` on your branch, commit what it rewrites, then bump again — or --allow-dirty to ship anyway'
+                : 'run `shipkit ci`, commit what it rewrites, then bump again — or --allow-dirty to ship anyway',
         )
     print('ok: ci gate green')
 

package/src/release/run-release.ts

@@ -101,13 +101,20 @@ export type ReleaseOpts = {
  *  check, and a check's own `blocking` declaration is the only severity axis.
  *
  *  the config travels INTO the gate: classifying severity from one config
- *  while the rules ran from another downgrades a blocking failure to a warning. */
+ *  while the rules ran from another downgrades a blocking failure to a warning.
+ *
+ *  it also runs the FULL test tier, which `shipkit ci` skips while you work. */
 export async function runReleaseGate(root: string, config: RepoConfig, print: (l: string) => void, o: { fix?: boolean } = {}): Promise<number> {
     return await runCi(root, {
         fix: o.fix ?? false,
         frozen: true,
         status: false,
         config,
+        // 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
+        // about. Publishing behind a partial suite is a green nobody measured.
+        tests: 'full',
         // a check that cannot block cannot change the outcome, so a release
         // never probes the world: publishing a lib does not depend on whether
         // a DNS provider answers, and asking spends an API call per publish.

package/src/release/run-releases.ts

@@ -12,6 +12,7 @@ import { hasUnreleasedHeading, hasVersionSection } from './changelog.ts'
 import { deriveRemote, git, remoteTags } from './git-facts.ts'
 import { formatUnitError, resolveUnits, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { shared } from './releases-share.ts'
 
 export type UnitReport = {
     id: string
@@ -79,7 +80,16 @@ function treeAt(root: string, u: ReleaseUnit, ref: string): string | null {
     return hit != null ? rev(hit) : null
 }
 
-export async function collectReports(root: string, config: RepoConfig, o: { offline?: boolean } = {}): Promise<{ reports: UnitReport[]; errors: string[]; remote: string | null; remoteError: string | null }> {
+export type ReleaseSurvey = { reports: UnitReport[]; errors: string[]; remote: string | null; remoteError: string | null }
+
+/** the survey, at most ONCE per gate run across every process in it (see
+ *  releases-share.ts). An `offline` survey is never shared: it answers a
+ *  different question than the networked one and must not satisfy it. */
+export async function collectReports(root: string, config: RepoConfig, o: { offline?: boolean } = {}): Promise<ReleaseSurvey> {
+    return o.offline === true ? await surveyUnits(root, config, o) : await shared(() => surveyUnits(root, config, o))
+}
+
+async function surveyUnits(root: string, config: RepoConfig, o: { offline?: boolean } = {}): Promise<ReleaseSurvey> {
     // a unit that does not resolve is still news: it is named, and everything
     // that DID resolve is still reported beside it
     const { units, errors } = resolveUnits(root, config)
@@ -93,8 +103,12 @@ export async function collectReports(root: string, config: RepoConfig, o: { offl
         else remoteError = `git ls-remote ${remote} unreachable (${r.error})`
     }
 
-    const reports: UnitReport[] = []
-    for (const u of units) {
+    // CONCURRENT per unit, and the reason is measured: each unit does a
+    // registry fetch and a `gh release view`, both network, and in series
+    // seven units cost 13.9s. This function runs inside five separate check
+    // subprocesses on every gate, so that was the single largest cost in the
+    // whole run. Order is preserved by mapping rather than pushing.
+    const reports: UnitReport[] = await Promise.all(units.map(async (u): Promise<UnitReport> => {
         const tagLocal = git(root, ['rev-parse', '--quiet', '--verify', `refs/tags/${u.tag}`]).code === 0
         const changelog = existsSync(u.changelog) ? readFileSync(u.changelog, 'utf8') : ''
         const hasSection = hasVersionSection(changelog, u.version)
@@ -126,7 +140,7 @@ export async function collectReports(root: string, config: RepoConfig, o: { offl
             ? Bun.spawnSync(['gh', 'release', 'view', u.tag], { cwd: root }).exitCode === 0
             : null
 
-        reports.push({
+        return {
             id: u.id,
             rel: u.rel === '' ? '.' : u.rel,
             name: u.name,
@@ -145,8 +159,8 @@ export async function collectReports(root: string, config: RepoConfig, o: { offl
             hasSection,
             commitsAfterNotes,
             hasUnreleased: hasUnreleasedHeading(changelog),
-        })
-    }
+        }
+    }))
     return { reports, errors: errors.map(formatUnitError), remote, remoteError }
 }
 

package/src/repo-config.ts

@@ -12,7 +12,10 @@ import { existsSync, readFileSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
 import { fileURLToPath } from 'url'
 import { activeContracts, applyContractsResult, contractsConfigFrom } from './contracts/apply-contracts.ts'
-import { evaluateContracts } from './contracts/contracts-engine.ts'
+import { ROUTED_SCRIPTS } from './core/canonical-scripts.ts'
+import { FLOOR_IDS, resolveFloor, type FloorResolution } from './core/floor.ts'
+export { resolveFloor, type FloorResolution, type FloorSource } from './core/floor.ts'
+import { evaluateContractsOnce } from './contracts/contracts-once.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
 import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
 import { BUILTIN_RULE_IDS, validateRules } from './rules/rule-registry.ts'
@@ -64,6 +67,12 @@ export type RepoConfig = {
     /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
      *  block — for ecosystem-specific names the published lib may not carry */
     gitignore?: string[]
+    /** untrack the paths shipkit generates on every run (STATUS.md and
+     *  friends) the first time it sees them tracked, in one commit. Default
+     *  ON: a generated file left in the index dirties every tree forever and
+     *  rides into unrelated commits. `false` opts a repo out entirely, and
+     *  `--frozen` suppresses it for one run the way it suppresses SK005. */
+    untrackGenerated?: boolean
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
     visibility?: 'private' | 'public'
@@ -74,6 +83,13 @@ export type RepoConfig = {
      *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
      *  mandated reviewer. */
     reviewer?: { name: string; brief: string; tools?: string[] }
+    /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
+     *  repo keeps as a direct tool call. Declared per NAME, never as a list of
+     *  banned binaries: the invariant is about which VERBS an agent reaches
+     *  for, and a binary blocklist goes stale the day a repo changes runner.
+     *  A name outside ROUTED_SCRIPTS throws here, so a typo can never silently
+     *  un-govern a script. Rule SK001 reads it. */
+    oneWayIn?: { exempt?: string[] }
     /** repo-local rules, run by `shipkit check` beside the built-in SK ones and
      *  listed by `shipkit rules`. Same shape, same id-tagging, same fix pointers;
      *  the repo picks its own id prefix (SK is reserved). This is how a repo's
@@ -115,7 +131,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'reviewer', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -145,6 +161,9 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     for (const k of Object.keys(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(', ')})`)
+    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(', ')})`)
     // repo rules are validated against the built-ins, so a bad id, a duplicate,
     // or an SK squatter dies at config load, not silently mid-check
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
@@ -166,73 +185,11 @@ export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',
         logic: async (t) => {
-            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)), contractsFulfillness)
+            applyContractsResult(t, await evaluateContractsOnce(activeContracts(c), contractsConfigFrom(c, root)), contractsFulfillness)
         },
     }
 }
 
-const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
-
-export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)'
-export type FloorResolution = {
-    tasks: TaskDef[]
-    /** slots disabled by `defaults: { x: false }` — always printed */
-    disabled: string[]
-    /** slots nothing could fill — always printed, never silent */
-    unfilled: { id: string; reason: string }[]
-    /** where each registered slot came from (init prints this) */
-    sources: Record<string, FloorSource>
-}
-
-// zero-config floor (O6): with no script, imports:check/cycles resolve to
-// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc. Returns
-// the task, or the reason the slot stays empty.
-function builtinFloorTask(id: string, root: string): { task: TaskDef; source: FloorSource } | string {
-    if (id === 'imports:check' || id === 'cycles') {
-        let cli: string
-        // shipkit's OWN module, resolved from this file: no dependency to be
-        // out of date with, and no resolution that can fail in a consumer tree
-        cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
-        return {
-            task: { id, cmd: id === 'cycles' ? ['bun', cli, 'cycles'] : ['bun', cli, 'imports', '--check'] },
-            source: 'built-in (shipkit)',
-        }
-    }
-    if (id === 'typecheck') {
-        if (!existsSync(join(root, 'tsconfig.json'))) return `no 'typecheck' script and no tsconfig.json`
-        const local = join(root, 'node_modules/.bin/tsc')
-        const tsc = existsSync(local) ? local : Bun.which('tsc')
-        if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
-        return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
-    }
-    return `no package.json '${id}' script`
-}
-
-export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
-    const pkgPath = join(root, 'package.json')
-    let scripts: Record<string, string> = {}
-    if (existsSync(pkgPath)) {
-        // unparseable package.json must NOT silently empty the floor — the
-        // gate would run only `contracts` and report green
-        try { scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
-        catch (e) { throw new Error(`package.json unparseable — floor tasks cannot register: ${String(e).slice(0, 120)}`) }
-    }
-    const tasks: TaskDef[] = []
-    const disabled: string[] = []
-    const unfilled: { id: string; reason: string }[] = []
-    const sources: Record<string, FloorSource> = {}
-    for (const id of FLOOR_IDS) {
-        const override = c.defaults?.[id]
-        if (override === false) { disabled.push(id); continue }
-        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
-        if (scripts[id] != null) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
-        const b = builtinFloorTask(id, root)
-        if (typeof b === 'string') unfilled.push({ id, reason: b })
-        else { tasks.push(b.task); sources[id] = b.source }
-    }
-    return { tasks, disabled, unfilled, sources }
-}
-
 export function allTasks(c: RepoConfig, root: string): FloorResolution {
     const floor = resolveFloor(c, root)
     return { ...floor, tasks: [...floor.tasks, contractsTask(c, root), ...(c.tasks ?? [])] }