rvlib-shipkit 0.35.1 → 0.35.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.35.3
+
+- **`shipkit mv` no longer resolves a link that climbs out of the repo.** The cross-directory pass rewrites references by resolving them against the file that carries them, and a target like `../../outside.md` resolves to somewhere on the wider disk, which `existsSync` will happily confirm. A reference that leaves the repo is not this repo's to retarget, so it is left exactly as written.
+
+## 0.35.2
+
+- **A contract folder typed without its dot is repaired, not reported.** `rv-reflections/` instead of `.rv-reflections/` is invisible in every direction at once: the harvest scanner reads the dotted name, the SK004 ignore block covers the dotted name, and the repo filing notes into it gets silence rather than an error. Three notes sat unread for a day that way with nothing red anywhere. It is one character, a machine can be certain, and nobody gets a say in the answer, so the fix pass renames it and lands it through the machine commit path, and no agent is told: a WARN a machine can repair is a design bug. An EMPTY misnamed folder is removed instead, since there is nothing to carry. A rename takes the files OUT of the index, which is the contract rather than a side effect: those folders are gitignored under their real name, so tracking them was the missing dot's doing. The names come from the SK004 policy block itself, so a new always-ignored `.rv-*` folder is covered by declaring it there and nowhere else; the TRACKED contract dirs stay out, because their own contract check already reports them missing. BOTH names present is the one case that reaches a human, and it refuses out loud rather than merging: two folders can hold the same filename, and picking a winner is a decision.
+- The machine commit path is one function, `core/machine-commit`, rather than a copy per caller. Same scoping as before: the working tree version of the named paths only, never the index, so a neighbour's staged work cannot ride along, no commit mid merge or mid rebase or on a detached HEAD, never a push, and `SHIPKIT_NO_AUTOCOMMIT=1` off.
+- **The imports fixer rewrote toward a shape the repo could not resolve, then reported green over it.** It validated its own output by asking the DISK whether the target file existed, which it always did, having just resolved the path from it. Nothing asked whether the REPO could follow the specifier being written. In two repos with no `paths`, no `baseUrl` and no bundler alias, the fix pass turned a building tree into 150 `TS2307`s and a `Rollup failed to resolve import "src/setup.tsx"`, and `imports:check` printed `ok` straight afterwards. A prefix nothing maps is now never a rewrite TARGET: resolution is read from every `tsconfig*.json` at the root (the standard vite shape keeps `paths` in a REFERENCED config), and a prefix counts as mapped by a `paths` key, by a `baseUrl` it sits under, or, for a package name, by a real `node_modules` entry. A refused rewrite is an ERROR naming the mapping to add, so the run is red in every mode. Only the write is refused: a specifier already in canonical form is left alone, because this tool did not put it there and the typechecker owns that verdict.
+
+- **`shipkit mv` moves an md page between directories.** It refused every cross-directory move, and moving a docs folder under the one that owns the router is the commonest structural move there is. It refused for a reason: sweeping path TOKENS cannot fix a reference written RELATIVE to the file that carries it, and on a tail that happens to match (`../doc/bun.md` containing `doc/bun.md`) it corrupts one. So a relative pass now runs FIRST and leaves nothing for the token sweep to hit: it retargets the links other pages aim at the page, AND the links the page carries out, since its own directory moved under it. A url, an absolute path and a bare anchor are never resolved as paths, an anchor survives, the `→` and `@` forms count as references, and the destination directory is created because `git mv` refuses into one that is not there. A move that keeps the BASENAME no longer runs `git mv X X` on the sibling probe, which is fatal and was unreachable while every move was a rename.
+
+- **`shipkit start` called tracked files "committed" on a path where it committed nothing.** Adopting a repo with history correctly leaves that history alone, and then reported `469 file(s) committed` while 36 files sat staged: the reassuring reading, at the one moment it was false. 469 was the `git ls-files` count. The line names the measurement now, `469 file(s) tracked`, and says `36 uncommitted` beside it when there is anything to say.
+
+- **The STATUS.md verdict counted the runner's own tally as a failure**, so N failing tasks always reported as N+1 (`RED — 2 FAIL lines` over one). `FAIL: 1/5 failed: cycles` is a line ABOUT the failures. A red exit with no FAIL line of its own also rendered `1 FAIL lines`, because the plural followed the number counted rather than the number shown. The header no longer asks to be committed either: SK004 ignores AND untracks this file, so the invitation sent readers into the state that fixer exists to undo.
+
+- **`shipkit start` wrote a stale package.json's name into `repo.config.ts`.** An adopted repo usually carries the manifest of whatever it was forked from, so a repo started as `voyager` got `name: 'bun-react-template'` in the one file every agent reads to learn what this repo IS. The name is on the command line and is the directory too, and `start` passes it now. With nothing to go on at all the DIRECTORY answers, rather than the `my-repo` placeholder that was waiting for someone not to notice it.
+
+- **The scaffolded `repo.config.ts` carried dash punctuation into repos that ban it.** It is authored by shipkit and lands as that repo's source, so its comments answer to that repo's comment style, and a scaffold is the one comment nobody rewrites, so it teaches the style of whatever wrote it. A test gates the shape.
+
 ## 0.35.1
 
 - **SK013's green line claimed a replacement that could not be named.** With the guard declared but not yet installed, the rule WARNed correctly and then printed `closes 14/14 raw runner(s), with the replacement named` directly underneath it. Both lines were about the same file and only one of them was true. The summary now reports what the file actually delivers: the guard is `declared, not yet runnable` until its script resolves.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.35.1",
+    "version": "0.35.3",
     "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",

package/src/core/machine-commit.ts

@@ -0,0 +1,60 @@
+// Commit what a machine just wrote, and ONLY those paths.
+//
+// Some files in a repo are written by the tool rather than by a person: a
+// registry row, a folder renamed to the name the contract already uses. Left
+// uncommitted they dirty the tree from a run nobody associates with them, and
+// the dirt then rides into an unrelated commit or blocks a release. Nobody
+// wants to read them either, so the machine that writes them lands them.
+//
+// Scoped hard, because several agents share one checkout:
+// - `git commit -- <path>` takes the WORKING TREE version of those paths and
+//   never reads the index, so a neighbour's staged work cannot ride along.
+// - it refuses mid merge, mid rebase, on a detached HEAD, and before the first
+//   commit, where an automatic commit is never what anyone wants.
+// - it never pushes. Visibility is the human's call.
+// - the hooks run, as they do for any commit.
+//
+// Never throws and never fails the calling command: a machine written path is
+// not worth a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
+import { existsSync } from 'fs'
+import { join, resolve } from 'path'
+
+const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
+    const r = Bun.spawnSync(['git', ...args], { cwd })
+    return { ok: r.exitCode === 0, out: `${r.stdout.toString()}${r.stderr.toString()}`.trim() }
+}
+
+export type MachineCommit = {
+    /** any directory inside the target repo: the git toplevel is read from it */
+    anchor: string
+    message: string
+    /** absolute paths, all inside that repo */
+    paths: string[]
+}
+
+/** true when a commit landed. false means "nothing was committed", never an error */
+export function machineCommit(o: MachineCommit): boolean {
+    if (process.env['SHIPKIT_NO_AUTOCOMMIT'] === '1') return false
+    if (o.paths.length === 0) return false
+    try {
+        const top = git(resolve(o.anchor), ['rev-parse', '--show-toplevel'])
+        if (!top.ok) return false // not a git repo, nothing to land
+        const root = top.out
+        // a detached HEAD or a repo with no commit yet has nowhere sane to land
+        if (!git(root, ['symbolic-ref', '--quiet', 'HEAD']).ok) return false
+        if (!git(root, ['rev-parse', '--verify', 'HEAD']).ok) return false
+        for (const f of ['MERGE_HEAD', 'REBASE_HEAD', 'CHERRY_PICK_HEAD'])
+            if (existsSync(join(root, '.git', f))) return false
+        const rels = o.paths.map((p) => (p.startsWith(`${root}/`) ? p.slice(root.length + 1) : p))
+        // one retry: a neighbour committing right now holds index.lock
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const r = git(root, ['commit', '-m', o.message, '--', ...rels])
+            if (r.ok) return true
+            if (!r.out.includes('index.lock')) return false
+            Bun.sleepSync(300)
+        }
+        return false
+    } catch {
+        return false
+    }
+}

package/src/core/motherhome.ts

@@ -15,6 +15,7 @@ import { homedir } from 'os'
 import { join, resolve } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
+import { machineCommit } from './machine-commit.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
 const END = '<!-- <<< shipkit local-projects -->'
@@ -24,11 +25,6 @@ type Row = { name: string; root: string; version: string; mode: string; seen: st
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
-const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
-    const r = Bun.spawnSync(['git', ...args], { cwd })
-    return { ok: r.exitCode === 0, out: `${r.stdout.toString()}${r.stderr.toString()}`.trim() }
-}
-
 /**
  * Commit the row we just wrote, and ONLY that file.
  *
@@ -38,42 +34,17 @@ const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
  * commit or blocks a release. The row is not worth a human's attention in
  * either direction, so the machine that writes it also lands it.
  *
- * Scoped hard, because several agents share this checkout:
- * - `git commit -- <path>` takes the WORKING TREE version of that one path and
- *   never reads the index, so a neighbour's staged work cannot ride along.
- * - it refuses mid merge, mid rebase, on a detached HEAD, and before the first
- *   commit, where an automatic commit is never what anyone wants.
- * - it never pushes. Visibility is the human's call.
- * - the hooks run, as they do for any commit. They are text checks of about a
- *   second, and this fires only when the row's DATA changed, not every gate.
- *
- * Never throws and never fails the calling command: a registry row is not worth
- * a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
+ * The scoping, the refusals and the escape hatch live in `core/machine-commit`,
+ * which every machine written path commits through. This one fires only when
+ * the row's DATA changed, not on every gate, so the hooks it runs are affordable.
  */
 function autoCommitRow(page: string, name: string): string {
-    if (process.env['SHIPKIT_NO_AUTOCOMMIT'] === '1') return ''
-    try {
-        const dir = resolve(page, '..')
-        const top = git(dir, ['rev-parse', '--show-toplevel'])
-        if (!top.ok) return '' // the docs tree is not a git repo, nothing to land
-        const root = top.out
-        // a detached HEAD or a repo with no commit yet has nowhere sane to land
-        if (!git(root, ['symbolic-ref', '--quiet', 'HEAD']).ok) return ''
-        if (!git(root, ['rev-parse', '--verify', 'HEAD']).ok) return ''
-        for (const f of ['MERGE_HEAD', 'REBASE_HEAD', 'CHERRY_PICK_HEAD'])
-            if (existsSync(join(root, '.git', f))) return ''
-        const rel = page.startsWith(`${root}/`) ? page.slice(root.length + 1) : page
-        // one retry: a neighbour committing right now holds index.lock
-        for (let attempt = 0; attempt < 2; attempt++) {
-            const r = git(root, ['commit', '-m', `chore(machine): refresh local-projects row (${name})`, '--', rel])
-            if (r.ok) return ' + committed'
-            if (!r.out.includes('index.lock')) return ''
-            Bun.sleepSync(300)
-        }
-        return ''
-    } catch {
-        return ''
-    }
+    const landed = machineCommit({
+        anchor: resolve(page, '..'),
+        message: `chore(machine): refresh local-projects row (${name})`,
+        paths: [page],
+    })
+    return landed ? ' + committed' : ''
 }
 
 const parseRow = (line: string): Row | null => {

package/src/core/repair-contract-dirs.ts

@@ -0,0 +1,102 @@
+// A contract folder typed without its leading dot is INVISIBLE, in every
+// direction at once: the scanner that harvests it looks for the dotted name,
+// the gitignore policy covers the dotted name, and the repo that filed
+// something into it gets silence rather than an error. Files sat unread for a
+// day that way, and nothing anywhere was red.
+//
+// One character, no ambiguity, and nothing about it is a decision: it is a
+// typo, so the fix pass renames it and lands it, and no agent is told. A WARN a
+// machine can repair is a design bug, and an attention surface carries only
+// what needs taste or hands.
+//
+// The names come from the SK004 policy block, which is the one table that
+// already lists the always-ignored `.rv-*` contract folders. The TRACKED
+// contract dirs (`.rv-identity`, `.rv-assets`) stay out of it deliberately:
+// their own contract check reports them missing, so those never fail silently,
+// and a rename that untracks a tracked folder is not a repair.
+import { readdirSync, renameSync, rmdirSync } from 'fs'
+import { join } from 'path'
+import { POLICY_LINES } from '../rules/SK004-gitignore-policy.ts'
+import { machineCommit } from './machine-commit.ts'
+
+/** the always-ignored `.rv-*` contract folders, from the policy that owns them */
+export const contractDirNames = (): string[] =>
+    POLICY_LINES.filter((l) => /^\.rv-[a-z-]+\/$/.test(l)).map((l) => l.slice(0, -1))
+
+/** the shape of a name, ignoring the leading dot, the separators, the case and
+ *  a trailing plural. Tight on purpose: `rv-reflections`, `rv_reflection` and
+ *  `RV-Reflections` are the same intent, `reflections` and `docs` are not */
+const shapeOf = (s: string): string => s.toLowerCase().replace(/^\.+/, '').replace(/[-_.]/g, '').replace(/s$/, '')
+
+export type DirRepair = { from: string; to: string }
+export type DirRefusal = { from: string; to: string; reason: string }
+export type DirRepairPlan = { repairs: DirRepair[]; refusals: DirRefusal[] }
+
+/**
+ * PURE: what to rename, given the names sitting in a repo root.
+ *
+ * BOTH names present is the one case worth refusing out loud: two folders can
+ * hold two files of the same name, and merging them is a choice about which
+ * one survives. Nothing else here is a choice.
+ */
+export function planContractDirRepairs(entries: string[], names: string[] = contractDirNames()): DirRepairPlan {
+    const present = new Set(entries)
+    const repairs: DirRepair[] = []
+    const refusals: DirRefusal[] = []
+    for (const dotted of names) {
+        const shape = shapeOf(dotted)
+        for (const entry of entries) {
+            if (entry === dotted || shapeOf(entry) !== shape) continue
+            if (present.has(dotted)) refusals.push({ from: entry, to: dotted, reason: 'both names exist, and merging them decides which file wins' })
+            else repairs.push({ from: entry, to: dotted })
+        }
+    }
+    return { repairs, refusals }
+}
+
+const isEmptyDir = (path: string): boolean => {
+    try { return readdirSync(path).length === 0 } catch { return false }
+}
+
+const dirsIn = (root: string): string[] => {
+    try { return readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) } catch { return [] }
+}
+
+export type DirRepairResult = { renamed: DirRepair[]; removed: string[]; refusals: DirRefusal[] }
+
+/**
+ * Apply the plan. An EMPTY undotted folder is removed rather than renamed:
+ * there is nothing to carry over, git never tracked it, and the dotted name is
+ * created by whoever files the first note.
+ *
+ * A rename UNTRACKS whatever the undotted folder held, and that is the intended
+ * end state rather than a side effect: the dotted name is gitignored by
+ * contract, so the repo was only tracking those files by accident of the
+ * missing dot. Hence a plain rename plus a commit of the OLD path: the commit
+ * records the files leaving the index, the files themselves stay on disk under
+ * the name every scanner reads, and `git commit -- <old>` matches nothing when
+ * git never tracked them, which lands no commit and is the right answer there.
+ */
+export function repairContractDirs(root: string): DirRepairResult {
+    const plan = planContractDirRepairs(dirsIn(root))
+    const renamed: DirRepair[] = []
+    const removed: string[] = []
+    for (const r of plan.repairs) {
+        const from = join(root, r.from)
+        const to = join(root, r.to)
+        try {
+            if (isEmptyDir(from)) {
+                rmdirSync(from)
+                removed.push(r.from)
+                continue
+            }
+            renameSync(from, to)
+            renamed.push(r)
+            machineCommit({ anchor: root, message: `chore(machine): rename ${r.from} to ${r.to}`, paths: [from] })
+        } catch {
+            // a permission error or a race is not worth a red gate: the folder
+            // stays where it is and the next run tries again
+        }
+    }
+    return { renamed, removed, refusals: plan.refusals }
+}

package/src/core/run-fixers.ts

@@ -16,6 +16,7 @@ import type { RepoConfig } from '../repo-config.ts'
 import { runFix } from '../rules/run-fix.ts'
 import { routesToShipkit } from './canonical-scripts.ts'
 import { mutateLease, withMutateLease } from './locked-write.ts'
+import { repairContractDirs } from './repair-contract-dirs.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
@@ -174,6 +175,16 @@ async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, ver
         else if (armed.state === 'foreign' || armed.state === 'not-root') o.print(`skip: hooks (${armed.detail})`)
         else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
+    // a contract folder typed without its dot is a typo a machine can fix with
+    // certainty, so it is repaired and committed rather than reported. Only the
+    // ambiguous case reaches a human. Runs before the tree snapshot: the rename
+    // lands in its own commit and is never counted as a fixer rewrite
+    if (!verify) {
+        for (const r of repairContractDirs(root).refusals) {
+            o.print(`WARN ${r.from}/ and ${r.to}/ both exist — ${r.reason}`)
+            o.print(`      fix: move the files into ${r.to}/ yourself, then delete ${r.from}/`)
+        }
+    }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)
     for (const d of disabled) o.print(`skip: ${d.id} (${d.reason})`)

package/src/core/write-status.ts

@@ -24,11 +24,16 @@ export type StatusOutcome = { written: boolean; warn?: string }
 
 const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '')
 
+/** the task runner's closing tally (`FAIL: 1/5 failed: cycles`) is a line
+ *  ABOUT the failures, not one of them. Counted alongside the task it
+ *  summarised, N failing tasks always reported as N+1. */
+const RUN_SUMMARY = /^FAIL:?\s+\d+\/\d+ failed:/
+
 export function writeStatus(root: string, s: StatusInput): StatusOutcome {
     const target = join(root, 'STATUS.md')
     const r = withFileLock(target, () => {
         const clean = s.lines.map(stripAnsi)
-        const fails = clean.filter((l) => l.startsWith('FAIL')).length
+        const fails = clean.filter((l) => l.startsWith('FAIL') && !RUN_SUMMARY.test(l)).length
         const warns = clean.filter((l) => l.startsWith('WARN')).length
         // only the full gate may say "clear to ship": a checks-only run proves
         // the repo is sound, never that the build passes, and a narrowed gate
@@ -36,8 +41,11 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
         // too, or a narrowed green hides behind a nag nobody reads twice
         const full = s.fullGate === true
         const scope = full ? 'clear to ship' : `${s.command} ran, not the whole gate`
+        // a red exit with no FAIL line of its own still reads RED, and the
+        // plural follows the number SHOWN, not the number counted
+        const shown = Math.max(fails, 1)
         const verdict = s.exitCode !== 0 || fails > 0
-            ? `RED — ${Math.max(fails, 1)} FAIL line${fails === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
+            ? `RED — ${shown} FAIL line${shown === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
             : warns > 0
                 ? `GREEN with nags — ${warns} WARN. ${full ? 'Proceed.' : `${scope}.`}`
                 : `GREEN — ${scope}.`
@@ -45,8 +53,11 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
         const now = new Date()
         const p = (n: number): string => String(n).padStart(2, '0')
         const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${p(now.getHours())}:${p(now.getMinutes())}`
-        const body = `<!-- generated by \`${s.command}\` — commit me to track progress over time -->
-# ${s.name} status — ${stamp}
+        // SK004 ignores AND untracks this file, so the old header, which asked
+        // to be committed, sent readers straight into the state that fixer
+        // exists to undo
+        const body = `<!-- generated by \`${s.command}\`, rewritten on every run, gitignored (SK004) -->
+# ${s.name} status, ${stamp}
 
 **${verdict}**
 

package/src/init-repo.ts

@@ -7,7 +7,7 @@
 // from node_modules. Only bodies shipkit cannot express as a verb are
 // scaffolded: an alias script would be a second name for one capability.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { join } from 'path'
+import { basename, join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
 import { hasTestFiles, packageJsonShape } from './rules/SK001-package-json-shape.ts'
 import { oneWayInPolicy } from './rules/SK013-one-way-in-policy.ts'
@@ -16,24 +16,35 @@ import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
+// This lands as SOURCE in the repo being wired, so its comments answer to that
+// repo's comment style, not to this file's. Dash punctuation is banned there
+// and a scaffold is the one comment nobody rewrites, so it teaches the style
+// of whatever wrote it. `DASH_PUNCTUATION` plus a test gate the shape.
 const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'rvlib-shipkit'
 
 export default defineRepo({
     name: '${name}',
-    venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
-    social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
+    venues: [], // e.g. ['itch', 'steam'], selects which .rv-<venue>/ contracts are REQUIRED
+    social: [], // e.g. ['x', 'discord'], the .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
-    // .comfy-ts/ holds schema dumps naming a private model collection —
+    // .comfy-ts/ holds schema dumps naming a private model collection.
     // gitignore (SK004) is advisory, this pre-commit gate is not
     hooks: { blockedPaths: ['.comfy-ts/'] },
-    // the mandated reviewer agent type (rule SK008) — uncomment with YOUR
+    // the mandated reviewer agent type (rule SK008). Uncomment with YOUR
     // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
     // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
-    // health checks: no config — drop a <name>.check.ts file anywhere,
+    // health checks need no config. Drop a <name>.check.ts file anywhere,
     // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
 })
 `
 
+/** dash punctuation, in any of the three shapes the ban covers */
+export const DASH_PUNCTUATION = /[—–]|(?<=\s)-(?=\s)/
+
+/** the scaffolded config, for a gate that this text stays writable into a repo
+ *  that bans the dash. Exported because the template itself is private. */
+export const scaffoldedConfig = (name: string): string => CONFIG_TEMPLATE(name)
+
 export type InitOpts = {
     /** in-repo-source consumers: path to shipkit's cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>` */
     bin?: string
@@ -47,8 +58,20 @@ export type InitOpts = {
     noPublish?: boolean
     /** how `gh` runs — injected by tests, which never touch a real account */
     gh?: Run | null
+    /** what this repo is CALLED, when the caller already knows. `shipkit start
+     *  <name>` does, and a repo being adopted usually carries a package.json
+     *  from whatever it was forked from, so reading the name out of that file
+     *  writes a template's identity into the config every agent then trusts. */
+    name?: string
 }
 
+/** the repo's name, in decreasing order of how much the caller meant it: what
+ *  was asked for, what the manifest claims, then the directory it lives in.
+ *  The directory is a real answer; `my-repo` was a placeholder waiting to be
+ *  committed by someone who did not notice it. */
+export const repoName = (root: string, asked?: string, fromPkg?: string): string =>
+    [asked, fromPkg, basename(root)].find((n) => n != null && n !== '') ?? 'my-repo'
+
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
     const p = opts.print ?? console.log
     const configPath = join(root, 'repo.config.ts')
@@ -79,7 +102,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // guaranteed by the refusal above: no config means a package.json is here
     const pkgRaw = readFileSync(pkgPath, 'utf8')
     const pkg = JSON.parse(pkgRaw) as { name?: string; scripts?: Record<string, string> }
-    const name = pkg.name ?? 'my-repo'
+    const name = repoName(root, opts.name, pkg.name)
     writeFileSync(configPath, CONFIG_TEMPLATE(name))
     p('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '

package/src/mv/mv-md.ts

@@ -6,20 +6,70 @@
 // script it runs after the moves (repo-specific re-stamps). TS module moves
 // are a different concern (a TS-aware renamer owns import graphs).
 import { execSync } from 'child_process'
-import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { basename, dirname, join } from 'path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { basename, dirname, join, relative } from 'path'
 
 export type MvIo = { print: (l: string) => void; printErr: (l: string) => void }
 export type MvOpts = { write?: boolean; commit?: boolean }
 
 const sh = (cmd: string, cwd: string): string => execSync(cmd, { cwd }).toString()
 
+const posix = (p: string): string => p.replace(/\\/g, '/')
+const dirOf = (p: string): string => { const d = dirname(p); return d === '.' ? '' : d }
+
+// A reference written RELATIVE to the file that carries it survives a same-dir
+// rename untouched, which is why sweeping path TOKENS was enough while moves
+// were confined to one directory. A move between directories invalidates both
+// directions at once: the links the page carries out, and the links other
+// pages aim at it. Sweeping tokens cannot fix either, and on a tail that
+// happens to match ('../doc/bun.md' carrying 'doc/bun.md') it corrupts them,
+// so this pass runs FIRST and leaves nothing for the token sweep to hit.
+const REF_FORMS: { re: RegExp; group: number }[] = [
+    { re: /\]\(([^)\s]+)\)/g, group: 1 }, // [text](target)
+    { re: /(→\s+)([^\s,;)`]+)/g, group: 2 }, // → target
+    { re: /^(@)(\S+)$/gm, group: 2 }, // @target, the include line
+]
+
+/** rewrite every relative reference in one file so it still points at the same
+ *  thing after the move. `moves` is every path this operation relocates; a ref
+ *  that names none of them still moves when the FILE moved under it. */
+export function retargetRelativeRefs(root: string, text: string, fromDir: string, toDir: string, moves: Map<string, string>): string {
+    const fix = (target: string): string | null => {
+        // a url, an absolute path and a bare anchor are not ours to resolve
+        if (target === '' || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('/') || target.startsWith('#')) return null
+        const hash = target.indexOf('#')
+        const path = hash === -1 ? target : target.slice(0, hash)
+        const anchor = hash === -1 ? '' : target.slice(hash)
+        if (path === '') return null
+        const from = posix(join(fromDir, path))
+        // a target that climbs out of the repo is not this repo's to rewrite,
+        // and existsSync would happily confirm something on the wider disk
+        if (from.startsWith('../')) return null
+        const to = moves.get(from)
+        // nothing moved for this reference: neither its target nor its carrier
+        if (to == null && fromDir === toDir) return null
+        // a target that is not a real path is prose, not a link
+        if (to == null && !existsSync(join(root, from))) return null
+        const next = posix(relative(toDir, to ?? from))
+        if (next === '') return null
+        return `${path.startsWith('./') && !next.startsWith('.') ? `./${next}` : next}${anchor}`
+    }
+    let out = text
+    for (const { re, group } of REF_FORMS) {
+        out = out.replace(re, (m, ...rest) => {
+            const target = rest[group - 1] as string
+            const next = fix(target)
+            return next == null ? m : m.replace(target, next)
+        })
+    }
+    return out
+}
+
 export function movePage(root: string, oldRel: string, newRel: string, io: MvIo, o: MvOpts = {}): number {
     const die = (m: string): number => { io.printErr(`FAIL: ${m}`); return 1 }
     if (!oldRel.endsWith('.md') || !newRel.endsWith('.md')) return die('both paths must be .md (TS moves are not this tool\'s job)')
     if (!existsSync(join(root, oldRel))) return die(`${oldRel} does not exist`)
     if (existsSync(join(root, newRel))) return die(`${newRel} already exists`)
-    if (dirname(oldRel) !== dirname(newRel)) return die('cross-directory moves not supported yet, same dir only')
 
     const write = o.write === true || o.commit === true
     const oldName = basename(oldRel, '.md')
@@ -50,12 +100,24 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
 
     const tracked = sh('git ls-files', root).split('\n').filter(Boolean)
         .filter((f) => !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|zip|gz|lockb|lock)$/i.test(f))
+
+    // every path this move relocates, old → new. The sibling dir carries its
+    // whole subtree, and the probe is renamed after the page, so its own entry
+    // is written LAST and wins over the subtree rule.
+    const moves = new Map<string, string>([[oldRel, newRel]])
+    if (existsSync(join(root, oldBase))) {
+        moves.set(oldBase, newBase)
+        for (const f of tracked) if (f.startsWith(`${oldBase}/`)) moves.set(f, `${newBase}${f.slice(oldBase.length)}`)
+        const probe = `${oldBase}/${oldName}.check.ts`
+        if (existsSync(join(root, probe))) moves.set(probe, `${newBase}/${newName}.check.ts`)
+    }
+
     let touched = 0
     for (const f of tracked) {
         const p = join(root, f)
         if (!existsSync(p)) continue
         const before = readFileSync(p, 'utf8')
-        let after = before
+        let after = retargetRelativeRefs(root, before, dirOf(f), dirOf(moves.get(f) ?? f), moves)
         for (const [oldTok, newTok] of pairs) after = after.replace(bound(oldTok), newTok)
         if (after !== before) {
             io.print(`  ${f}`)
@@ -66,12 +128,18 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     io.print(`${write ? 'renamed' : 'DRY RUN'}: ${oldBase} → ${newBase}, refs in ${touched} file(s)`)
     if (!write) { io.print('re-run with --write (or --commit) to apply'); return 0 }
 
-    // moves AFTER the sweep (the sweep rewrote files at their old paths)
+    // moves AFTER the sweep (the sweep rewrote files at their old paths).
+    // git mv refuses into a directory that is not there yet, and a move
+    // between directories is the case where it usually is not
+    mkdirSync(join(root, dirOf(newRel)), { recursive: true })
     sh(`git mv ${JSON.stringify(oldRel)} ${JSON.stringify(newRel)}`, root)
     if (existsSync(join(root, oldBase))) {
         sh(`git mv ${JSON.stringify(oldBase)} ${JSON.stringify(newBase)}`, root)
+        // the probe is named after its page, so it only moves when the NAME
+        // changed. A move that keeps the name and changes the directory takes
+        // the probe along inside the dir, and `git mv X X` is a fatal
         const oldCheck = join(newBase, `${oldName}.check.ts`)
-        if (existsSync(join(root, oldCheck))) sh(`git mv ${JSON.stringify(oldCheck)} ${JSON.stringify(join(newBase, `${newName}.check.ts`))}`, root)
+        if (oldName !== newName && existsSync(join(root, oldCheck))) sh(`git mv ${JSON.stringify(oldCheck)} ${JSON.stringify(join(newBase, `${newName}.check.ts`))}`, root)
     }
 
     // repo-specific re-stamps (e.g. wiki depth frontmatter) — loud on failure

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

@@ -18,7 +18,7 @@ const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit ou
 const END = '# <<< shipkit gitignore policy'
 const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
 
-const POLICY_LINES = [
+export const POLICY_LINES = [
     // the leak guard reads .rv-private/banned-keywords.txt: the file listing
     // what must never be committed cannot itself be committable
     '.rv-private/',

package/src/start-repo.ts

@@ -138,7 +138,10 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         let unscaffolded = false
         if (!existsSync(join(dir, 'repo.config.ts'))) {
             if (existsSync(join(dir, 'package.json'))) {
-                try { await initRepo(dir, { github: opts.github, gh: opts.gh, print, noPublish: true }) }
+                // the name is on the command line and is the directory too, so
+                // an adopted repo never takes its identity from whatever
+                // package.json it was forked with
+                try { await initRepo(dir, { name, github: opts.github, gh: opts.gh, print, noPublish: true }) }
                 catch (e) { console.error(`WARN could not wire ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
             } else unscaffolded = true
         }
@@ -159,19 +162,35 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     return 0
 }
 
+/** what the closing line is allowed to say, all of it measured */
+export type RepoFacts = { tracked: number; uncommitted: number; hasHead: boolean; origin: string | null; pushed: boolean }
+
 /** the one closing fact: what this repo IS now, measured rather than
  *  narrated. Everything a repo still needs is reported by the gate, about a
- *  repo with code in it, on the day it matters */
+ *  repo with code in it, on the day it matters.
+ *
+ *  `tracked` is what git INDEXES, which is not what this run committed. On an
+ *  adopt path the run correctly leaves a pre-existing history alone, and
+ *  calling that count "committed" told the reader their work was safe at the
+ *  exact moment files were sitting staged. So the line names the measurement,
+ *  and anything still uncommitted is said out loud next to it. */
+export function summaryLine(f: RepoFacts): string {
+    const bits = [f.hasHead ? `${f.tracked} file(s) tracked${f.uncommitted > 0 ? `, ${f.uncommitted} uncommitted` : ''}` : 'not committed yet']
+    if (f.origin != null) bits.push(f.pushed ? `pushed to ${f.origin}` : 'remote wired, nothing pushed yet')
+    else bits.push('local only, no remote')
+    return bits.join(', ')
+}
+
+const countLines = (s: string): number => s.trim().split('\n').filter((l) => l !== '').length
+
 async function summarize(dir: string): Promise<string> {
     const git = runner('git', dir, 30_000)
-    const files = (await git(['ls-files'])).out.trim().split('\n').filter((l) => l !== '').length
+    const tracked = countLines((await git(['ls-files'])).out)
+    const uncommitted = countLines((await git(['status', '--porcelain'])).out)
     const head = await git(['log', '-1', '--format=%h'])
     // git merges stderr into stdout, so a missing remote answers with its
     // error text: only a zero exit means that output is a url
     const origin = await git(['remote', 'get-url', 'origin'])
     const pushed = (await git(['rev-parse', '--verify', '@{upstream}'])).code === 0
-    const bits = [head.code === 0 ? `${files} file(s) committed` : 'not committed yet']
-    if (origin.code === 0) bits.push(pushed ? `pushed to ${origin.out.trim()}` : `remote wired, nothing pushed yet`)
-    else bits.push('local only, no remote')
-    return bits.join(', ')
+    return summaryLine({ tracked, uncommitted, hasHead: head.code === 0, origin: origin.code === 0 ? origin.out.trim() : null, pushed })
 }

package/src/ts/imports.ts

@@ -12,7 +12,7 @@
 // bundler suffixes (?raw, ?url), template-literal specifiers, packages.
 import { readdirSync, readFileSync, writeFileSync, existsSync, type Dirent } from 'fs'
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'path'
-import { canonicalSpecifier, isSkipped, loadConfig, resolvePackageSpecifier, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
+import { canonicalSpecifier, isSkipped, loadConfig, parseJsonc, resolvePackageSpecifier, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
 import { templateLineMask } from 'rvlib-shipkit/src/ts/source-mask.ts'
 
 const ASSET_EXTENSIONS = new Set([
@@ -42,7 +42,78 @@ const cachedExists = (p: string): boolean => {
    }
    return r
 }
-export const clearExistsCache = (): void => existsCache.clear()
+export const clearExistsCache = (): void => {
+   existsCache.clear()
+   resolutionCache.clear()
+}
+
+// ─── can the REPO resolve what this tool is about to write? ────────────────
+//
+// The canonical form ('src/foo/Bar.ts', 'rvlib-x/src/foo.ts') is not a path
+// any module resolver follows on its own: the repo MAPS it, through tsconfig
+// `paths`, a `baseUrl` the prefix sits under, or a real package in
+// node_modules. Nothing here validated that, and the tool's own validation
+// asked the DISK whether the target file existed, which it always did. So in
+// a repo with no mapping the rewrite turned a building tree into hundreds of
+// TS2307s, and the check that ran next reported ok over exactly that state.
+//
+// A prefix nothing maps is therefore never a rewrite TARGET. Only the write
+// is refused: a specifier already in canonical form is left alone and
+// reported by nobody, because this tool did not put it there and the
+// typechecker owns that verdict.
+
+type RepoResolution = { prefixes: Set<string>; baseDirs: string[] }
+const resolutionCache = new Map<string, RepoResolution>()
+
+/** every prefix the repo's own tsconfigs map, plus the baseUrls they set.
+ *  Every `tsconfig*.json` at the root, because the standard vite shape keeps
+ *  `paths` in a REFERENCED config and leaves the entry one empty. */
+function repoResolution(root: string): RepoResolution {
+   const hit = resolutionCache.get(root)
+   if (hit != null) return hit
+   const prefixes = new Set<string>()
+   const baseDirs: string[] = []
+   let names: string[] = []
+   try {
+      names = readdirSync(root).filter((n) => /^tsconfig(\..+)?\.json$/.test(n))
+   } catch {
+      // unreadable root: nothing is mapped, and every rewrite refuses loudly
+   }
+   for (const n of names) {
+      let parsed: { compilerOptions?: { paths?: Record<string, unknown>; baseUrl?: unknown } }
+      try {
+         parsed = parseJsonc(readFileSync(join(root, n), 'utf8')) as typeof parsed
+      } catch {
+         continue // an unparseable tsconfig maps nothing, it does not map everything
+      }
+      const co = parsed.compilerOptions
+      for (const k of Object.keys(co?.paths ?? {})) prefixes.add(k.endsWith('/*') ? k.slice(0, -2) : k)
+      if (typeof co?.baseUrl === 'string') baseDirs.push(co.baseUrl)
+   }
+   const r = { prefixes, baseDirs }
+   resolutionCache.set(root, r)
+   return r
+}
+
+/** the prefix a canonical specifier is rooted at: a discovered package's NAME
+ *  (a scoped one carries a slash of its own, so splitting on '/' is wrong),
+ *  else the leading segment */
+const specifierPrefix = (spec: string, cfg: RvtConfig): string =>
+   cfg.packages.find((p) => spec === p.name || spec.startsWith(`${p.name}/`))?.name ?? spec.split('/')[0]!
+
+function repoCanResolve(prefix: string, cfg: RvtConfig): boolean {
+   const { prefixes, baseDirs } = repoResolution(cfg.root)
+   if (prefixes.has(prefix)) return true
+   if (baseDirs.some((b) => cachedExists(join(cfg.root, b, prefix)))) return true
+   // a package name also answers to plain node resolution, which is what an
+   // npm consumer of the published source will use
+   return cachedExists(join(cfg.root, 'node_modules', prefix))
+}
+
+const unresolvableReason = (prefix: string, isPackage: boolean): string =>
+   isPackage
+      ? `nothing resolves '${prefix}': install or link the package, or map "${prefix}/*" in compilerOptions.paths (tsconfig.json). Rewriting first would resolve on disk and nowhere else`
+      : `the repo maps nothing onto '${prefix}/': add "${prefix}/*": ["./${prefix}/*"] to compilerOptions.paths (tsconfig.json), plus the matching bundler alias. Rewriting first would resolve on disk and nowhere else`
 
 function resolveFileExtension(absPath: string): string | null {
    if (/\.(d\.ts|tsx?|json)$/.test(absPath) && cachedExists(absPath)) return absPath
@@ -125,7 +196,13 @@ export function rewriteFile(filePath: string, cfg: RvtConfig, save: boolean): Im
          pushError(lineNum, specifier, `resolved outside allowed roots (${cfg.roots.join(', ')}): ${rel}`)
          return null
       }
-      return next === specifier ? null : next
+      if (next === specifier) return null
+      const prefix = specifierPrefix(next, cfg)
+      if (!repoCanResolve(prefix, cfg)) {
+         pushError(lineNum, specifier, unresolvableReason(prefix, cfg.packages.some((p) => p.name === prefix)))
+         return null
+      }
+      return next
    }
    const sub = (match: string, quote: string, specifier: string, lineNum: number, isRelative: boolean): string => {
       const next = resolveNew(specifier, lineNum, isRelative)