rvlib-shipkit 0.22.2 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.23.0
+
+- **Release order is a TOPOSORT of the units' own dependency graph.** It was "sub-units first, root last", so a `--all` run published in declaration order and a dependent could ship naming a version the registry did not have yet. Kahn's algorithm now, stable (ties keep declaration order, root always last), and a cycle degrades to declaration order rather than dropping a unit: a release that silently skips a package is worse than one in a bad order.
+
+- **The source-graph toolbelt lives IN shipkit** (`src/ts/`): rename, imports, cycles, and the shared config. `rvlib-ts-tools` is gone as a dependency. A gate that REQUIRES a tool must never be a published version behind the repo it gates, which is exactly how `shipkit mv` renamed a file and rewrote zero references while reporting success.
+- **Fix: `shipkit mv` was blind to whole trees.** The default skip list matched a bare name against ANY path segment, so a package under a dir named `build` (or `dist`, `out`, `cjs`) was invisible to every scan. Those names now match only where output actually lands: the repo root, or a package root. `node_modules` and `.git` still match at any depth.
+- **Fix: `shipkit mv` derives the package-qualified specifier by walking UP from the file**, not from the configured roots. The content scan was always repo-wide, so the specifier derivation had to be too: a repo whose packages sit outside `roots` renamed the file and rewrote nothing.
+- **`shipkit mv` reports what it CANNOT rewrite.** A file naming the moved file's stem without a rewritable path (a regex-escaped path in a test, a doc line, a specifier built from parts) is listed as a near-miss instead of being silently skipped. It is never rewritten, because guessing there is how a rename corrupts a repo.
+
+- **A bump moves its dependents' ranges forward, in the same commit**, including between units bumped in the SAME  run: skipping selected units left every sibling range naming the version its dependency had just left. Bumping a unit used to leave every sibling naming the OLD version, so the tree published packages that install the wrong code or nothing at all. `shipkit bump` now rewrites the caret/tilde/exact range in every other unit that names a bumped one, and stages it with the version commit. Local protocols are left alone.
+- **New rule SK011: a sibling range must be satisfied by the version that sibling carries.** The complement of the above, for a hand-edited range or an interrupted bump. It found real drift the day it landed: a peer range of `^0.1.2` on a lib that had moved to `0.2.0`, which a caret on `0.x` genuinely excludes, so consumers were installing the wrong major of it.
+
+- **SK006 refuses a local dependency protocol in anything publishable.** `link:`, `file:`, `portal:` or `workspace:` in `dependencies`, `peerDependencies` or `optionalDependencies` cannot resolve on a consumer's machine: publishing that ships a package which fails at INSTALL, for a stranger, never for you. It scans every release UNIT, not just the repo root, because the root is usually private and the units are what publish. devDependencies are exempt (npm never installs them for a consumer), and the working shape is the future version range in the dependency plus the local wiring in `overrides`.
+
+- **A leak hit reports a mask, never the matched string** (`kre…v1 (23 chars)`). The pattern is private by construction, and a gate that prints it verbatim leaks it into the terminal, the CI log and any paste of either.
+
+- **A temp dir never mints a github repository.** A root under any system temp path (`TMPDIR`, `/tmp`, `/var/tmp`, either spelling of each) skips the github half with a line naming `--github` to force it. An agent rehearsing `shipkit init`/`start` in a scratch dir created three real repositories on the account, and deleting one needs a token scope the machine does not carry. Only the real account is guarded: an injected `gh` runner is a test with an account of its own.
+
+- **MobX 7 + mobx-react-lite 5** for the TUI. It is the ONE lib still on `mobx-react-lite`, so the one still pinned to a single major: consuming rvlib-mobx's seam by `link:` makes the TUI resolve React from that lib's own node_modules, two React copies, invalid hook call. That is a `link:`-only artifact, gone once the seam is published and installed as a tarball, so the swap rides the release that picks it up. RELEASE ORDER MATTERS: this version must not ship before `comfy-ts` accepts MobX 7, and its dep range must move to that version in the same release. A comfy-ts that declares `mobx@^6` alone gets a nested copy beside our 7, the observables go invisible across the boundary, and a bare `import 'rvlib-shipkit'` throws "There are multiple, different versions of MobX active" in a consumer's tree. The `overrides` block in this package.json fixes the LOCAL tree only: overrides are honored in the install root, never through a published dependency.
+- **SK005's clean-pass cache is keyed on the INSTALLED rvlib versions.** Keyed on the repo alone, a manual `bun add -d rvlib-x@N` left every run replaying `ok: rvlib-x 0.16.0 (latest) (cached 3h ago)` for 24h, naming a version the tree no longer carried and calling it latest.
+- **`shipkit releases` stops calling a clean root unit edited.** `treeAt` compared what `git rev-parse <ref>` returns, the COMMIT for `HEAD` and the TAG OBJECT for an annotated tag, so a tag sitting exactly on HEAD with an empty diff warned "names contents this branch does not carry". It compares `<ref>^{tree}` now.
+- **`release.after`: the step that makes a release LIVE.** `repo.config.ts release: { after: ['bun', 'run', 'up'] }` runs after the tag, the push and the GitHub release, for the ROOT unit only. Prepublish scripts cannot fill this slot: they run BEFORE the version commit, so they are build steps. It runs LAST, so a failed deploy unwinds nothing already published. It is not resumable by re-running `release` (a fully released unit refuses), so re-run the command it prints.
+
+- **The hub banner reads like a banner.** No wire prefixes, no route-per-line checklist: one clickable line (`<repo> hub → http://localhost:<port>`), an indented `also:` line listing the real routes, and the `phone:` line when a public host is configured. Wire prefixes stay reserved for problems.
+
 ## 0.22.2
 
 - **Frozen gates never write the motherhome row.** The bump preflight ate the machine dirt, then the gate INSIDE the bump re-wrote the local-projects row and the post-gate cleanliness check refused, the same wart's second head. A frozen run is release-shaped: it reports nothing to the motherhome, so the tree it proves clean stays clean. Interactive ci/check keep reporting.
@@ -7,12 +32,12 @@
 
 ## 0.22.1
 
-- **Fix: the cache stamp is baked in at RUN time, replays print it verbatim.** 0.22.0 annotated only the REPLAY, so a fresh run and a cache hit rendered different strings and STATUS.md still diffed on every alternation (his catch, the second one on this line). A TTL clean pass now writes "(cached at <stamp> until <stamp>)" into the line once, live output and every replay are byte-identical, and the line changes only when a re-validation happens. Proven: fresh-then-cached runs produce a zero-diff STATUS body.
+- **Fix: the cache stamp is baked in at RUN time, replays print it verbatim.** 0.22.0 annotated only the REPLAY, so a fresh run and a cache hit rendered different strings and STATUS.md still diffed on every alternation. A TTL clean pass now writes "(cached at <stamp> until <stamp>)" into the line once, live output and every replay are byte-identical, and the line changes only when a re-validation happens. Proven: fresh-then-cached runs produce a zero-diff STATUS body.
 
 ## 0.22.0
 
 - **Fix: the machine-row auto-commit could not see STATUS.md.** The git helper trims its whole output, so the FIRST porcelain line loses its leading space and the old column-3 slice read "TATUS.md", making the preflight silently decline the exact dirt it was built to eat. `dirtyPathList` parses status prefixes robustly now (renames and quoted paths included, regression-tested on the trimmed-first-line case), and a decline is never silent: the preflight names the non-machine paths it refused.
-- **Cached check lines carry an absolute stamp** (`cached 2026-08-05 09:12:34`), never a relative age: "cached 34m ago" re-rendered on every run and turned committed STATUS.md checkpoints into noise diffs that startled agents (his call 2026-08-05). The line now changes only when the cache actually refreshes.
+- **Cached check lines carry an absolute stamp** (`cached 2026-08-05 09:12:34`), never a relative age: "cached 34m ago" re-rendered on every run and turned committed STATUS.md checkpoints into noise diffs. The line now changes only when the cache actually refreshes.
 
 - **The pre-commit gate times itself.** Past ~1.5s it WARNs naming the fix (move slow preCommit commands to ci tasks), because "a commit takes ~1s" was a stated rule with no tripwire, and a repo drifting back to 40-second commits would have told nobody.
 - **The bootstrap is a CHAIN, and it ends at a push.** `shipkit start` and `shipkit init` now run git init → **first commit** → PRIVATE github repo → **push**, in that order. A repo wired but never pushed had backed up nothing, which was the whole point. The chain runs in two phases around whatever the verb scaffolds, so `CLAUDE.md`, `repo.config.ts` and the package.json scripts ride INSIDE the first commit instead of trailing it as dirt.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.22.2",
+    "version": "0.23.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",
@@ -24,17 +24,20 @@
         "@types/react-dom": "^19.2.3",
         "@types/sanitize-html": "^2.16.1"
     },
+    "overrides": {
+        "mobx": "^7.0.0",
+        "mobx-react-lite": "^5.0.0"
+    },
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",
         "comfy-ts": "^2.4.2",
         "ink": "^7.1.1",
         "marked": "^18.0.7",
-        "mobx": "^6.16.1",
-        "mobx-react-lite": "^4.1.1",
+        "mobx": "^7.0.0",
+        "mobx-react-lite": "^5.0.0",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
-        "rvlib-ts-tools": "^0.3.0",
         "sanitize-html": "^2.17.6",
         "sharp": "^0.35.3"
     }

package/src/cli/cmd_Asks.ts

@@ -67,7 +67,7 @@ export class AskNewCommand extends Command {
     kind = Option.String('--kind', { required: false, description: 'ask kind: action | credential | decision | purchase' })
     blocks = Option.String('--blocks', { required: false, description: 'what this ask blocks (task id, page, plain words)' })
     check = Option.String('--check', { required: false, description: 'shell probe that exits 0 once the ask is done (enables auto-close)' })
-    why = Option.String('--why', { required: false, description: 'one line of context — why this is worth his time' })
+    why = Option.String('--why', { required: false, description: 'one line of context: why this is worth a human interrupt' })
 
     async execute(): Promise<number> {
         try {

package/src/cli/cmd_Mv.ts

@@ -1,12 +1,11 @@
 // shipkit mv, ONE rename command for the whole repo. An md page routes to
 // mv/mv-md.ts (page + sibling asset dir + check.ts + every tracked ref);
-// anything else routes to rvlib-ts-tools' rename, which rewrites every path
+// anything else runs shipkit's own rename, which rewrites every path
 // reference in the code. Renaming used to mean knowing WHICH tool applied,
 // and knowing that is exactly the kind of doubt the toolkit exists to remove.
 import { Command, Option } from 'clipanion'
-import { fileURLToPath } from 'url'
 import { movePage } from '../mv/mv-md.ts'
-import { spawnWithTimeout } from '../core/spawn-timeout.ts'
+import { renameCli } from '../ts/rename.ts'
 
 export class MvCommand extends Command {
     static override paths = [['mv']]
@@ -37,13 +36,11 @@ export class MvCommand extends Command {
                     this.context.stderr.write('FAIL: --commit is md-only for now — run with --write, then commit\n')
                     return 1
                 }
-                let cli: string
-                try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) }
-                catch { this.context.stderr.write('FAIL: rvlib-ts-tools is unresolvable — reinstall shipkit deps\n'); return 1 }
-                const r = await spawnWithTimeout(['bun', cli, 'rename', this.oldPath, this.newPath, ...(write ? ['--apply'] : [])], { cwd: process.cwd(), timeoutMs: 120_000 })
-                this.context.stdout.write(r.out)
-                if (!write && r.code === 0) this.context.stdout.write('note: dry run — pass --write to apply\n')
-                return r.code
+                // in-process: the rename lives HERE now, so `shipkit mv` can
+                // never be a version behind the tool it delegates to
+                const code = renameCli([this.oldPath, this.newPath, ...(write ? ['--apply'] : [])])
+                if (!write && code === 0) this.context.stdout.write('note: dry run — pass --write to apply\n')
+                return code
             }
             return movePage(process.cwd(), this.oldPath, this.newPath, {
                 print: (l) => this.context.stdout.write(`${l}\n`),

package/src/collections/actions.ts

@@ -55,16 +55,16 @@ export function appendPostFeedback(root: string, channel: string, file: string,
     writeFileSync(p, /^## Feedback\s*$/m.test(md) ? `${md.trimEnd()}\n${line}\n` : `${md.trimEnd()}\n\n## Feedback\n${line}\n`)
 }
 
-/** his asset remark → `.rv-assets/notes.md` (git-tracked; the studio
+/** an asset remark → `.rv-assets/notes.md` (git-tracked; the studio
  *  workspace is gitignored, so notes live beside kit.ts) */
 export function appendAssetNote(root: string, assetId: string, text: string): void {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assetId)) throw new Error('bad asset id')
     const p = join(root, '.rv-assets', 'notes.md')
     const line = `- ${today()} [${assetId}]: ${text.replace(/\n+/g, ' ').trim()}`
-    writeFileSync(p, existsSync(p) ? `${readFileSync(p, 'utf8').trimEnd()}\n${line}\n` : `# asset notes — his remarks, read by agents at boot\n\n${line}\n`)
+    writeFileSync(p, existsSync(p) ? `${readFileSync(p, 'utf8').trimEnd()}\n${line}\n` : `# asset notes, read by agents at boot\n\n${line}\n`)
 }
 
-/** his remark on an ask → appended to the ask file, dated, non-destructive.
+/** a remark on an ask → appended to the ask file, dated, non-destructive.
  *  Accepts exactly one optional `done/` prefix (archived asks stay
  *  annotatable); any other slash or traversal is a bad path. */
 export function appendAskRemark(root: string, asksDir: string, file: string, text: string): void {

package/src/collections/collection-types.ts

@@ -28,7 +28,7 @@ export type Instance = {
     file?: string
     /** thumbnail URL for media tiles */
     img?: string
-    /** his latest remarks from the item's own file — agents boot on these */
+    /** the latest remarks from the item's own file, agents boot on these */
     remarks?: string[]
     /** the truth file's markdown BODY (frontmatter stripped) — clamped card
      *  in the grid, full in the item view; capped server-side, never a dump */

package/src/collections/providers.ts

@@ -92,7 +92,7 @@ const askMd = (path: string): string | undefined => {
     return body.length > MD_CAP ? `${[...body].slice(0, MD_CAP).join('')}…` : body
 }
 
-/** his latest dated remark lines from a file's tail — the boot briefing */
+/** the latest dated remark lines from a file's tail, the boot briefing */
 const lastRemarks = (path: string, max = 3): string[] | undefined => {
     if (!existsSync(path)) return undefined
     const lines = readFileSync(path, 'utf8').split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2}: /.test(l))
@@ -212,7 +212,7 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
     }
 }
 
-/** `.rv-assets/notes.md` — his dated asset remarks, one git-tracked file:
+/** `.rv-assets/notes.md`, dated asset remarks in one git-tracked file:
  *  `- YYYY-MM-DD [asset-id]: text` */
 const assetNotes = (root: string): Map<string, string[]> => {
     const p = join(root, '.rv-assets', 'notes.md')

package/src/core/check-suite.ts

@@ -146,9 +146,9 @@ export class CheckSuite {
                 // the stamp was baked in when the check RAN (below): a replay
                 // prints the stored lines VERBATIM, so the live run and every
                 // later replay render the same string, and the line changes
-                // only when a re-validation happens (his call 2026-08-05,
-                // second round: annotating replays but not live runs still
-                // diffed on every fresh-vs-cached alternation)
+                // only when a re-validation happens. Annotating replays but
+                // not live runs still diffed on every fresh-vs-cached
+                // alternation, so neither side annotates
                 out.push(...entry.lines)
                 this.onResult?.(r.name, { lines: entry.lines, status: 'pass', cached: true }) // only clean passes are cached
                 continue

package/src/core/run-fixers.ts

@@ -21,7 +21,7 @@ const FIXER_TIMEOUT_MS = 120_000
 export type FixerSlot = {
     id: string
     cmd: string[]
-    source: 'package.json script' | 'built-in (rvlib-ts-tools)'
+    source: 'package.json script' | 'built-in (shipkit)'
 }
 
 export type FixerResolution = {
@@ -68,9 +68,8 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
     else if (scripts['imports:fix'] != null) slots.push({ id: 'imports:fix', cmd: ['bun', 'run', 'imports:fix'], source: 'package.json script' })
     else {
         let cli: string | null = null
-        try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) } catch { cli = null }
-        if (cli == null) unfilled.push({ id: 'imports:fix', reason: `no 'imports:fix' script and rvlib-ts-tools is unresolvable` })
-        else slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (rvlib-ts-tools)' })
+        cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
+        slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (shipkit)' })
     }
     return { slots, unfilled, disabled }
 }

package/src/git-bootstrap.ts

@@ -15,6 +15,7 @@
 // unverifiable path (no gh, not authenticated, offline) is a WARN that
 // leaves the local repo wired and names the next move.
 import { existsSync, realpathSync } from 'fs'
+import { tmpdir } from 'os'
 import { basename, join } from 'path'
 import { spawnWithTimeout } from './core/spawn-timeout.ts'
 
@@ -76,6 +77,20 @@ const runner = (bin: string, root: string, timeoutMs: number): Run => async (cmd
 
 const gitIn = (root: string): Run => runner('git', root, 120_000)
 
+/** the system temp tree, resolved through the symlink macOS puts in front of
+ *  it. A repo under here is a rehearsal by construction */
+export const isScratch = (root: string): boolean => {
+    const real = (p: string): string => { try { return realpathSync(p) } catch { return p } }
+    // every temp root, not just the one TMPDIR names: macOS answers
+    // /var/folders there while agents and harnesses scratch under /tmp, and a
+    // repo minted from /private/tmp is exactly as unwanted. Both spellings of
+    // both sides too, since /var resolves to /private/var and a path that
+    // does not exist yet cannot be resolved at all
+    const tmps = [tmpdir(), real(tmpdir()), '/tmp', '/private/tmp', '/var/tmp', '/private/var/tmp']
+    const roots = [root, real(root)]
+    return tmps.some((t) => roots.some((r) => `${r}/`.startsWith(`${t}/`)))
+}
+
 const samePath = (a: string, b: string): boolean => {
     try {
         return realpathSync(a) === realpathSync(b)
@@ -152,7 +167,15 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     let gh: Run | null
     if (opts.gh !== undefined) gh = opts.gh
     else if ((process.env.SHIPKIT_NO_GITHUB ?? '') !== '') return void p('skip: github — SHIPKIT_NO_GITHUB is set')
-    else gh = Bun.which('gh') == null ? null : runner('gh', root, 60_000)
+    else if (opts.github !== true && isScratch(root)) {
+        // a scratch dir is somebody TRYING the verb, never starting a project.
+        // Two repositories were minted exactly that way, and deleting one
+        // needs a token scope this machine does not carry, so the cost of
+        // guessing wrong is not symmetric. Only the REAL account is guarded:
+        // an injected runner is a test with an account of its own
+        p(`skip: github — ${root} is a temp dir, not a project`)
+        return void p('      fix: pass --github if you really want a repo for it')
+    } else gh = Bun.which('gh') == null ? null : runner('gh', root, 60_000)
     if (gh == null) {
         p('WARN no remote wired: gh cli not found')
         return void p('      fix: install gh, `gh auth login`, then re-run this command')

package/src/hooks/leak-guard.ts

@@ -9,6 +9,12 @@ import { join } from 'path'
 
 export type LeakHit = { where: string; pattern: string }
 
+/** what a hit REPORTS. The matched string is private by construction, and a
+ *  gate that prints it verbatim puts it in a terminal, a CI log and any paste
+ *  of either. Enough to recognize, not enough to be quotable. */
+export const maskPattern = (p: string): string =>
+    p.startsWith('re:') || p.length <= 6 ? p : `${p.slice(0, 3)}…${p.slice(-2)} (${p.length} chars)`
+
 export type LeakGuardResult =
     | { status: 'skipped'; reason: string }
     | { status: 'clean'; patterns: number }

package/src/hooks/run-hooks.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
-import { globalKeywordFile, runLeakGuard } from './leak-guard.ts'
+import { globalKeywordFile, maskPattern, runLeakGuard } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -143,7 +143,7 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             ok: false,
             lines: [
                 `FAIL: leak-guard matched ${r.hits.length} banned pattern(s) — this commit would leak private content`,
-                ...r.hits.map((x) => `      ${x.where}: ${x.pattern}`),
+                ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`),
                 `      fix: remove the content, or edit the keyword file if the pattern is wrong`,
             ],
         })
@@ -223,7 +223,7 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
     if (!(h.disable ?? []).includes('leak-guard')) {
         const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, text: [{ label: 'commit message', content: message }] })
         if (r.status === 'hit')
-            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${x.pattern}`)] })
+            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`)] })
     }
     for (const c of h.commitMsg ?? []) {
         const r = await spawnWithTimeout([...c.cmd, messageFile], { cwd: root, timeoutMs: 60_000 })

package/src/reflect/prompt-corpus.ts

@@ -90,7 +90,7 @@ type RawEntry = {
     message?: { role?: unknown; content?: unknown }
 }
 
-/** His words out of one transcript line, or null when the line is not a prompt
+/** the typed prompt out of one transcript line, or null when the line is not one
  * he typed. isSidechain = a subagent prompt the AGENT wrote; isMeta and
  * isCompactSummary = harness-generated. Content is a string for a plain prompt,
  * an array of blocks when the message carried pastes or attachments (the text

package/src/release/run-bump.ts

@@ -430,6 +430,35 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
         print(`ok: ${pkgRel} ${s.version}, ${s.changelogRel} section promoted`)
     }
 
+    // every OTHER unit that depends on a bumped one moves its range forward, in
+    // the SAME commit. A sibling left naming the old version is a package that
+    // installs the wrong code, or nothing at all, and rule SK011 fails on it.
+    const bumpedNames = new Map(selected.map((s) => [s.unit.name, s.version]))
+    for (const u of all) {
+        // every unit, INCLUDING the bumped ones: with --all they are all
+        // selected, and skipping them left each sibling range naming the
+        // version its dependency just left. Only the self-reference is skipped
+        if (u.name != null && bumpedNames.has(u.name) && bumpedNames.size === 1) continue
+        const rel = u.rel === '' ? 'package.json' : `${u.rel}/package.json`
+        const before = readFileSync(`${root}/${rel}`, 'utf8')
+        if (!/"rvlib-[^"]*"\s*:\s*"[\^~]?\d/.test(before) && !selected.some((x) => x.unit.id === u.id)) continue
+        let after = before
+        const moved: string[] = []
+        for (const [name, version] of bumpedNames) {
+            if (name === u.name) continue
+            // the RANGE VALUE only, and only a caret/tilde/exact one: a local
+            // protocol is a working-copy choice (SK006) and stays untouched
+            const re = new RegExp(`("${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"\\s*:\\s*")([\\^~]?)\\d+\\.\\d+\\.\\d+(")`, 'g')
+            const next = after.replace(re, (_m, head: string, op: string, tail: string) => `${head}${op === '' ? '' : op}${version}${tail}`)
+            if (next !== after) { moved.push(`${name} → ${version}`); after = next }
+        }
+        if (after !== before) {
+            writeFileSync(`${root}/${rel}`, after)
+            files.push(rel)
+            print(`ok: ${rel} follows the bump (${moved.join(', ')})`)
+        }
+    }
+
     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(', ')

package/src/release/run-release.ts

@@ -50,6 +50,14 @@ export type ReleaseConfig = {
      *  branch first, with a merge commit. Default true. A branch is a GATE, so
      *  this is deliberately reachable ONLY by running bump by hand. */
     mergeFromBranch?: boolean
+    /** what makes the release LIVE, run after the tag, the push and the
+     *  GitHub release, for the ROOT unit only (`['bun', 'run', 'up']` for a
+     *  repo that deploys). A released web app that never deployed is not
+     *  shipped, and prepublish scripts cannot do this: they run BEFORE the
+     *  version commit, so they are build steps, not deploys. It is the last
+     *  thing that happens, so a failure here loses nothing that was already
+     *  published: it prints how to re-run the deploy alone. */
+    after?: string[]
 }
 
 /** the parts of the release preflight that do not depend on the new version
@@ -198,6 +206,7 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
         ...(tagExists() ? [] : [`git tag ${tag}`]),
         `git push + push tag ${tag}`,
         ...(wantGh ? [`gh release create ${tag}`] : []),
+        ...(unit.rel === '' && (rc.after?.length ?? 0) > 0 ? [`post-release: ${rc.after!.join(' ')}`] : []),
     ]
 
     print(`note: ${unit.id} · ${name}@${version} → tag ${tag} · ${wantNpm ? 'npm' : unit.isPrivate ? 'PRIVATE (no npm)' : 'no npm target'} · ${notes === '' ? 'no notes' : `${notes.split('\n').length} line(s) of notes`}`)
@@ -273,6 +282,19 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
             print(`ok: GitHub release ${tag} live`)
         }
         print(`ok: ${name}@${version} released${wantNpm ? ' (npm + tag' : ' (tag'}${wantGh ? ' + github release)' : ')'}`)
+        // LAST, and root-unit only: everything above is already published, so
+        // a failed deploy is reported without unwinding any of it
+        const after = unit.rel === '' ? config.release?.after : undefined
+        if (after != null && after.length > 0) {
+            print(`ok: running the post-release step — ${after.join(' ')}`)
+            const a = Bun.spawnSync(after, { cwd: root, stdout: 'inherit', stderr: 'inherit' })
+            if (a.exitCode !== 0) {
+                print(`FAIL: post-release step failed (exit ${a.exitCode}) — ${name}@${version} IS released, it is not live`)
+                print(`      fix: ${after.join(' ')}`)
+                return 1
+            }
+            print(`ok: post-release step done — ${name}@${version} is live`)
+        }
         return 0
     } finally {
         rmSync(work, { recursive: true, force: true })

package/src/release/run-releases.ts

@@ -61,9 +61,13 @@ export function notesAnchor(root: string, changelogRel: string, version: string)
  *  counts: a folder rename must not read as a content change. A tag can
  *  predate the move, so a miss falls back to finding the directory by name
  *  inside that ref's tree, or drift goes silently unassessed. */
+/** the TREE a ref names for this unit, which is what "same contents" means.
+ *  `^{tree}` is load-bearing on the root unit: a bare rev-parse yields the
+ *  COMMIT for HEAD and the TAG OBJECT for an annotated tag, two oids that
+ *  never match, so a tag sitting exactly on HEAD reported as edited. */
 function treeAt(root: string, u: ReleaseUnit, ref: string): string | null {
     const rev = (path: string): string | null => {
-        const r = git(root, ['rev-parse', path === '' ? ref : `${ref}:${path}`])
+        const r = git(root, ['rev-parse', path === '' ? `${ref}^{tree}` : `${ref}:${path}`])
         return r.code === 0 ? r.out : null
     }
     const direct = rev(u.rel)

package/src/release/units.ts

@@ -79,7 +79,15 @@ const SUB_TAG = '{name}@{version}'
 const render = (template: string, p: { name: string; version: string }): string =>
     template.replaceAll('{name}', p.name).replaceAll('{version}', p.version)
 
-type Pkg = { name?: string; version?: string; private?: boolean; scripts?: Record<string, string> }
+type Pkg = {
+    name?: string
+    version?: string
+    private?: boolean
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+}
 
 function readPkg(dir: string): { pkg: Pkg } | { error: string } {
     const p = join(dir, 'package.json')
@@ -216,8 +224,46 @@ function build(p: {
 /** publish order: sub-units first, the root last. The root depends on what
  *  ships inside it, so a consumer that sees the root tag can already resolve
  *  every sub-unit it names. */
+/** publish order: a unit ships AFTER every sibling it depends on, because a
+ *  dependent published first names a version the registry does not have yet.
+ *  Declaration order is not that order, and when it happens to be, it is luck.
+ *  Kahn's algorithm, stable: ties keep declaration order, the root is always
+ *  last, and a CYCLE degrades to declaration order rather than dropping units
+ *  (a release that silently skips a package is worse than one in a bad order). */
 export function releaseOrder(units: ReleaseUnit[]): ReleaseUnit[] {
-    return [...units.filter((u) => u.id !== 'root'), ...units.filter((u) => u.id === 'root')]
+    const subs = units.filter((u) => u.id !== 'root')
+    const root = units.filter((u) => u.id === 'root')
+    const byName = new Map(subs.filter((u) => u.name != null).map((u) => [u.name, u]))
+    const deps = new Map<string, Set<string>>()
+    for (const u of subs) {
+        const need = new Set<string>()
+        const read = readPkg(u.dir)
+        const manifest: Pkg = 'error' in read ? {} : read.pkg
+        for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
+            for (const dep of Object.keys(manifest[block] ?? {})) {
+                const sib = byName.get(dep)
+                if (sib != null && sib.id !== u.id) need.add(sib.id)
+            }
+        deps.set(u.id, need)
+    }
+    const out: ReleaseUnit[] = []
+    const placed = new Set<string>()
+    let progress = true
+    while (progress && out.length < subs.length) {
+        progress = false
+        for (const u of subs) {
+            if (placed.has(u.id)) continue
+            const need = deps.get(u.id) ?? new Set()
+            if ([...need].every((d) => placed.has(d))) {
+                out.push(u)
+                placed.add(u.id)
+                progress = true
+            }
+        }
+    }
+    // a dependency cycle between units: keep every unit, in declaration order
+    for (const u of subs) if (!placed.has(u.id)) out.push(u)
+    return [...out, ...root]
 }
 
 export const unitById = (units: ReleaseUnit[], id: string): ReleaseUnit | undefined => units.find((u) => u.id === id)

package/src/repo-config.ts

@@ -173,7 +173,7 @@ export function contractsTask(c: RepoConfig, root: string): TaskDef {
 
 const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
 
-export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (rvlib-ts-tools)' | 'built-in (tsc)'
+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 */
@@ -190,11 +190,12 @@ export type FloorResolution = {
 function builtinFloorTask(id: string, root: string): { task: TaskDef; source: FloorSource } | string {
     if (id === 'imports:check' || id === 'cycles') {
         let cli: string
-        try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) }
-        catch { return `no '${id}' script and rvlib-ts-tools is unresolvable — reinstall shipkit's deps` }
+        // 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 (rvlib-ts-tools)',
+            source: 'built-in (shipkit)',
         }
     }
     if (id === 'typecheck') {

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

@@ -22,7 +22,10 @@
 //   registry unreachable → loud skip, never red (offline is not a defect)
 // Committing the bump stays with the working agent — shipkit never commits.
 // Clean passes cache 24h (rule ttl), so the registry is fetched at most
-// daily per repo; skip/WARN/FAIL runs are never cached. peerDependencies
+// daily per repo; skip/WARN/FAIL runs are never cached. The key carries the
+// INSTALLED versions, so a manual `bun add -d rvlib-x@N` busts it: keyed on
+// the repo alone, the replayed ok: line named a version the tree no longer
+// carried and called it latest. peerDependencies
 // are NOT scanned: keeping a published lib's peer ranges consistent after
 // a bump stays the agent's job.
 import { existsSync, readFileSync } from 'fs'
@@ -52,6 +55,15 @@ export const rvlibVersions: Rule = {
     title: 'rvlib versions',
     owner: 'build/shipkit.md',
     ttl: '24h',
+    cacheKey: (env) => {
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })
+            .filter((n) => n.startsWith('rvlib-'))
+            .sort()
+            .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
+            .join(',')
+    },
     lint: async (t, env: RuleEnv) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return t.note('no readable package.json — rvlib versions not applicable') }

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

@@ -14,9 +14,23 @@
 // and sanctioned sub-lib publishing must not turn this rule red.
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { resolveUnits } from '../release/units.ts'
 import type { Rule } from './rule.ts'
 
-type Pkg = { name?: string; private?: boolean; publishConfig?: unknown; scripts?: Record<string, string> }
+type Pkg = {
+    name?: string
+    private?: boolean
+    publishConfig?: unknown
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+}
+
+/** protocols that resolve to a path on THIS machine. In a block a consumer
+ *  installs, they are unresolvable: the published package is broken on
+ *  arrival, and it fails at install time for a stranger, never here. */
+const LOCAL_PROTOCOL = /^(link|file|portal|workspace):/
 
 export const npmPublishSafety: Rule = {
     id: 'SK006',
@@ -28,7 +42,27 @@ export const npmPublishSafety: Rule = {
         if (!existsSync(p)) return t.ok('no package.json — nothing publishable')
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { return t.note('package.json unreadable — SK001 reports it') }
-        if (pkg.name?.startsWith('rvlib-') === true) return t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+        // every block a CONSUMER resolves, for every unit that can publish:
+        // the ROOT is usually private, so scanning it alone guards nothing
+        const localHits: string[] = []
+        for (const u of [{ dir: env.root, id: 'root' }, ...resolveUnits(env.root, env.config).units.filter((x) => x.rel !== '')]) {
+            const up = join(u.dir, 'package.json')
+            if (!existsSync(up)) continue
+            let upkg: Pkg
+            try { upkg = JSON.parse(readFileSync(up, 'utf8')) as Pkg } catch { continue }
+            if (upkg.private === true) continue
+            for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
+                for (const [dep, range] of Object.entries(upkg[block] ?? {}))
+                    if (LOCAL_PROTOCOL.test(range)) localHits.push(`${u.id}: ${block}.${dep} = ${range}`)
+        }
+        if (localHits.length > 0)
+            t.fail(
+                `${localHits.join(', ')} — a local protocol cannot resolve on a consumer's machine, so publishing that ships a package which fails at install. Declare the version it WILL be, and keep the local wiring in overrides (npm ignores those from a dependency) or in devDependencies`,
+            )
+        if (pkg.name?.startsWith('rvlib-') === true) {
+            if (localHits.length === 0) t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+            return
+        }
         if (pkg.private !== true) return t.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')
@@ -38,6 +72,6 @@ export const npmPublishSafety: Rule = {
             machinery.push(`scripts.publish (runs npm/bun publish)`)
         if (machinery.length > 0)
             t.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
-        else t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root`)
+        else if (localHits.length === 0) t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root, no local dependency protocol in any unit`)
     },
 }