rvlib-shipkit 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.21.0
+
+- **shipkit updates ITSELF and restarts.** An interactive `ci`/`check` on an npm consumer probes the registry (24h per-machine cache), and a behind-latest `rvlib-shipkit` runs `bun update --latest` on itself, then RE-EXECS the same invocation on the new version (loop-guarded by env). A dirty package.json/lockfile defers with a WARN (a tool never mixes its writes into staged work), CI/frozen/source-path consumption never fire it, offline is a silent skip. Version drift stops being anyone's job.
+- **The bump preflight commits machine rows itself.** STATUS.md and the motherhome local-projects row re-dirty on every gate run, and three releases in a row bounced on exactly that dirt. When they are the ONLY dirty paths, bump commits them ("machine rows refresh before release") and proceeds. Any human dirt still refuses.
+- **`init` and `start` wire git and github, not just the shipkit scaffold.** A dir with no `.git` gets `git init -b main`; a repo with no remote gets a PRIVATE github repo (created when missing, adopted when the name is already taken) wired as `origin` through gh's own `git_protocol`. Nothing is committed, nothing is pushed. ON by default, including for an EMPTY new dir, because starting a repo means wanting it private on github.
+- The github half fires for a repo being STARTED, not for a folder being entered: a dir the run just created, or one holding a package.json. An existing folder with no project gets git and a line naming `--github` to force the repo, so the everyday `ship <name>` cd (and a typo) cannot mint an account artifact. `--no-github` wires local git only, `SHIPKIT_NO_GITHUB=1` does it for every run on a machine, and `--skip` names stay untouched, git included.
+- The github half never guesses: only a repo github reports as MISSING is created, so a network or permission error can never answer "does it exist?" with a new repository. No gh, no auth, a login gh did not actually answer, an unreadable answer or a failed create are each a WARN that leaves local git wired and names the next command. A create that succeeds but cannot be read back says exactly that, never "creating failed". An ADOPTED repo is a WARN with no push instruction, because a name match is not proof of identity. A dir INSIDE another work tree is never initialized, and `init` refuses a cwd that is no project before wiring anything. An adopted repo that is already PUBLIC prints the SK007 mismatch on the spot.
+
+## 0.20.1
+
+- **Fix: `start --skip` means shipkit never touches the repo.** 0.20.0's adoption block ran after the skip branch, so `ship <job-repo>` would have scaffolded `repo.config.ts` into a repo on the never-wire list (caught by review in a sandbox). The whole wiring block sits behind the skip list now, frozen by test.
+- **Fix: a failed adoption never breaks the cd contract.** A broken `package.json` in the target repo downgrades wiring to a WARN on stderr, and `start` still prints the dir. `initRepo` gained a `print` sink, so `start` reports on stderr without touching the console global.
+- **Fix: arming only ever happens at the work-tree ROOT.** `armHooks` in a subdirectory used to set the PARENT repo's `core.hooksPath` onto a dir that does not exist there, disarming the parent's gates. It compares `git rev-parse --show-toplevel` now and declines with a named state.
+- **Fix: arming never rewrites hook bodies already present.** A repo with `core.hooksPath=hooks` and both hook files present is `current`, whatever its bodies say: arming means making dark gates live, not normalizing another repo's `--bin` choice. `hooks install` with no `--bin` now defaults to the same resolution as arming (the repo's own node_modules copy first), one invocation policy instead of two.
+- A failure to arm prints as a WARN, never as a skip, and a successful arm says to commit the `hooks/` dir.
+
 ## 0.20.0
 
 - **Commit gates arm themselves.** An interactive `shipkit ci` run now installs the git hooks whenever the repo has a `repo.config.ts` and `core.hooksPath` is unset or already `hooks`: hook bodies written, leak-guard keyword starter seeded, `core.hooksPath` set, idempotent. The field case: a whole drill session committed with dark gates because init was treated as "create repo.config.ts". A FOREIGN `core.hooksPath` (husky and friends) is respected and named, never taken. Hook bodies prefer the repo's own `node_modules/rvlib-shipkit` copy over the cli that happens to be running, so a repo keeps its pinned version. Scoped to the interactive gate on purpose: CI verify mode, `bump` and `release` gate runs never mutate the tree they are about to ship, and arming reports on its own line, never as a fixer rewrite.

package/package.json

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

package/src/cli/cmd_Check.ts

@@ -3,6 +3,7 @@
 // core/run-check.ts and rules/run-fix.ts. ci NEVER fixes.
 import { Command, Option } from 'clipanion'
 import { runCheck } from '../core/run-check.ts'
+import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 import { runFix } from '../rules/run-fix.ts'
 
 export class CheckCommand extends Command {
@@ -28,6 +29,9 @@ export class CheckCommand extends Command {
     fixIds = Option.Rest()
 
     async execute(): Promise<number> {
+        // a stale toolkit updates itself and restarts this exact invocation
+        // (loop-guarded, skipped under CI/frozen/source consumption)
+        await maybeSelfUpdateAndRestart(process.cwd())
         try {
             if (this.fixIds.length > 0 && !this.fix) {
                 this.context.stderr.write(`FAIL: rule ids need --fix (shipkit check --fix ${this.fixIds.join(' ')})\n`)

package/src/cli/cmd_Ci.ts

@@ -2,6 +2,7 @@
 // core/run-ci.ts.
 import { Command, Option } from 'clipanion'
 import { runCi } from '../core/run-ci.ts'
+import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 
 export class CiCommand extends Command {
     static override paths = [['ci']]
@@ -29,6 +30,9 @@ export class CiCommand extends Command {
     only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })
 
     async execute(): Promise<number> {
+        // a stale toolkit updates itself and restarts this exact invocation
+        // (loop-guarded, skipped under CI/frozen/source consumption)
+        await maybeSelfUpdateAndRestart(process.cwd())
         try {
             return await runCi(process.cwd(), {
                 bail: this.bail,

package/src/cli/cmd_Hooks.ts

@@ -1,7 +1,7 @@
 // shipkit hooks, install the git hooks, run their gates, or list what
 // blocks a commit. Thin clipanion surface; logic in hooks/run-hooks.ts.
 import { Command, Option } from 'clipanion'
-import { installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
+import { hookBinInvocation, installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
 const report = (out: GateOutcome[], write: (s: string) => void): number => {
@@ -17,11 +17,11 @@ export class HooksInstallCommand extends Command {
         examples: [['wire the hooks', 'shipkit hooks install']],
     })
 
-    bin = Option.String('--bin', 'bunx rvlib-shipkit', { description: 'how the hook body invokes shipkit (in-repo consumers pass `bun <path to cli.ts>`)' })
+    bin = Option.String('--bin', { description: 'how the hook body invokes shipkit (default: the repo\'s own node_modules copy, else the running cli — in-repo consumers pass `bun <path to cli.ts>`)' })
 
     async execute(): Promise<number> {
         const config = await loadRepoConfig(process.cwd()).catch(() => null)
-        const r = installHooks(process.cwd(), this.bin, config?.hooks?.keywordFile)
+        const r = installHooks(process.cwd(), this.bin ?? hookBinInvocation(process.cwd()), config?.hooks?.keywordFile)
         for (const w of r.written) this.context.stdout.write(`ok: wrote ${w}\n`)
         if (r.written.length === 0) this.context.stdout.write('ok: hook bodies already current\n')
         this.context.stdout.write(`${r.note.startsWith('WARN') ? r.note : `ok: ${r.note}`}\n`)

package/src/cli/cmd_Init.ts

@@ -8,18 +8,20 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. Scaffolds repo.config.ts + ci/check/contracts package.json scripts, then prints how the floor resolved. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
+        description: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. `git init` + a PRIVATE github repo and its origin remote when either is missing, then scaffolds repo.config.ts + ci/check/contracts package.json scripts and prints how the floor resolved. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
         examples: [
             ['wire the repo you are standing in', 'shipkit init'],
+            ['local git only, never touch github', 'shipkit init --no-github'],
             ['in-repo-source consumer: scripts run the CLI by path', 'shipkit init --bin wiki/build/shipkit/rvlib-shipkit/src/cli.ts'],
         ],
     })
 
     bin = Option.String('--bin', { description: 'path to shipkit cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>`' })
+    github = Option.Boolean('--github', { description: 'ON by default: a repo with no remote gets a PRIVATE github repo wired as origin. --no-github wires local git only (SHIPKIT_NO_GITHUB=1 does it for every run)' })
 
     async execute(): Promise<number> {
         try {
-            return await initRepo(process.cwd(), { bin: this.bin })
+            return await initRepo(process.cwd(), { bin: this.bin, github: this.github })
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
             return 1

package/src/cli/cmd_Start.ts

@@ -9,11 +9,13 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd: ensures the dir, seeds CLAUDE.md include lines, and wires shipkit on the spot (repo.config.ts via init) when the project already has a package.json. An empty new dir prints the next step instead. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create (or enter) ~/dev/<name> from ANY cwd: ensures the dir, seeds CLAUDE.md include lines, git-inits it with a PRIVATE github repo on origin, and wires shipkit on the spot (repo.config.ts via init) when the project already has a package.json. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
-            ['create or enter ~/dev/pong, wiring it if it is already a project', 'shipkit start pong'],
+            ['create or enter ~/dev/pong: dir, git, private github repo, wiring', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
             ['adopt a pre-existing repo from anywhere', 'shipkit start my-old-project'],
+            ['force the private github repo for a folder that was already there', 'shipkit start old-notes --github'],
+            ['local git only, never touch github', 'shipkit start pong --no-github'],
         ],
     })
 
@@ -21,9 +23,10 @@ export class StartCommand extends Command {
     root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
     include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept. Omitted means only ensure the dir' })
     alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add' })
-    skip = Option.Array('--skip', { description: 'repo names that never get the include' })
+    skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring' })
+    github = Option.Boolean('--github', { description: 'ON by default when a repo is being STARTED (a dir this run created, or one with a package.json): it gets a PRIVATE github repo wired as origin. Pass --github to force it for a pre-existing folder, --no-github to wire local git only (SHIPKIT_NO_GITHUB=1 does it for every run)' })
 
     async execute(): Promise<number> {
-        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip })
+        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip, github: this.github })
     }
 }

package/src/core/run-fixers.ts

@@ -131,8 +131,9 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // its own reported concern, never counted as a fixer rewrite.
     if (o.armHooks === true && !verify) {
         const armed = armHooks(root, config)
-        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail})`)
-        else if (armed.state === 'foreign') o.print(`skip: hooks (${armed.detail})`)
+        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the hooks/ dir`)
+        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}`)
     }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)

package/src/core/self-update.ts

@@ -0,0 +1,118 @@
+// zero-friction self-update: an interactive ci/check run on an npm consumer
+// checks the registry (24h cache on disk), updates rvlib-shipkit when it is
+// behind, and RE-EXECS the same invocation so the run continues on the new
+// version. a stale toolkit must never wait for a human to police versions.
+//
+// never fires: running from source (not under node_modules), CI env, frozen,
+// re-exec guard set, dirty package.json/lockfile (a tool must not mix its
+// writes into human-staged work), registry unreachable (offline is not a
+// defect). every skip is silent except the actionable ones, which WARN.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const PKG = 'rvlib-shipkit'
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+export type SelfUpdatePlan =
+    | { action: 'skip'; reason: string }
+    | { action: 'warn'; reason: string }
+    | { action: 'update'; installed: string; latest: string }
+
+/** pure decision, testable without network or filesystem */
+export function planSelfUpdate(o: {
+    installed: string | null
+    latest: string | null
+    runningFromNodeModules: boolean
+    reexecGuard: boolean
+    ci: boolean
+    frozen: boolean
+    manifestDirty: boolean
+}): SelfUpdatePlan {
+    if (o.reexecGuard) return { action: 'skip', reason: 'already re-executed once' }
+    if (o.ci) return { action: 'skip', reason: 'CI env' }
+    if (o.frozen) return { action: 'skip', reason: 'frozen' }
+    if (!o.runningFromNodeModules) return { action: 'skip', reason: 'running from source' }
+    if (o.installed == null) return { action: 'skip', reason: 'not an npm consumer here' }
+    if (o.latest == null) return { action: 'skip', reason: 'registry unreachable' }
+    if (o.installed === o.latest) return { action: 'skip', reason: 'current' }
+    if (newerThan(o.installed, o.latest)) return { action: 'skip', reason: 'ahead of the registry' }
+    if (o.manifestDirty) return { action: 'warn', reason: `rvlib-shipkit ${o.installed} is behind ${o.latest}, package.json or lockfile dirty, not touching — commit, then rerun` }
+    return { action: 'update', installed: o.installed, latest: o.latest }
+}
+
+/** true when a is strictly newer than b (plain x.y.z compare, prerelease ignored) */
+const newerThan = (a: string, b: string): boolean => {
+    const pa = a.split('.').map(Number)
+    const pb = b.split('.').map(Number)
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true
+        if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false
+    }
+    return false
+}
+
+const cachePath = (): string => join(homedir(), '.cache', 'shipkit', 'self-update.json')
+
+/** npm latest with a per-machine 24h cache, null when unreachable */
+async function latestCached(): Promise<string | null> {
+    const p = cachePath()
+    try {
+        const c = JSON.parse(readFileSync(p, 'utf8')) as { at: number; version: string }
+        if (Date.now() - c.at < CACHE_TTL_MS) return c.version
+    } catch { /* no cache yet */ }
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(5000) })
+        if (!res.ok) return null
+        const v = ((await res.json()) as { version?: string }).version ?? null
+        if (v != null) {
+            mkdirSync(dirname(p), { recursive: true })
+            writeFileSync(p, JSON.stringify({ at: Date.now(), version: v }))
+        }
+        return v
+    } catch {
+        return null
+    }
+}
+
+const manifestDirty = (root: string): boolean => {
+    const p = Bun.spawnSync(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb', 'package-lock.json'], { cwd: root })
+    if (p.exitCode !== 0) return true // no git = no safe write
+    return p.stdout.toString().trim() !== ''
+}
+
+/** run before dispatching an interactive ci/check. On update: re-exec the
+ *  SAME argv with a loop guard and exit with the child's code (never
+ *  returns). Otherwise returns after at most one cached registry probe. */
+export async function maybeSelfUpdateAndRestart(root: string): Promise<void> {
+    const here = fileURLToPath(import.meta.url)
+    const base = {
+        installed: installedVersion(root),
+        runningFromNodeModules: here.includes(`${join('node_modules', PKG)}/`),
+        reexecGuard: process.env.SHIPKIT_SELF_UPDATED === '1',
+        ci: process.env.CI != null && process.env.CI !== '',
+        frozen: process.env.SHIPKIT_FROZEN === '1',
+    }
+    // cheap gates first: no network unless an update is even possible
+    if (base.reexecGuard || base.ci || base.frozen || !base.runningFromNodeModules || base.installed == null) return
+    const plan = planSelfUpdate({ ...base, latest: await latestCached(), manifestDirty: manifestDirty(root) })
+    if (plan.action === 'warn') { console.error(`WARN self-update: ${plan.reason}`); return }
+    if (plan.action !== 'update') return
+    console.error(`ok: rvlib-shipkit ${plan.installed} → ${plan.latest}, self-updating (bun update --latest ${PKG})`)
+    const up = Bun.spawnSync(['bun', 'update', '--latest', PKG], { cwd: root, stdout: 'inherit', stderr: 'inherit' })
+    if (up.exitCode !== 0) { console.error(`WARN self-update failed (exit ${up.exitCode}), continuing on ${plan.installed}`) ; return }
+    console.error(`ok: restarting on ${plan.latest} — commit package.json + lockfile with your work`)
+    const child = Bun.spawnSync([process.execPath, ...process.argv.slice(1)], {
+        cwd: process.cwd(),
+        stdout: 'inherit', stderr: 'inherit', stdin: 'inherit',
+        env: { ...process.env, SHIPKIT_SELF_UPDATED: '1' },
+    })
+    process.exit(child.exitCode ?? 1)
+}
+
+const installedVersion = (root: string): string | null => {
+    const p = join(root, 'node_modules', PKG, 'package.json')
+    if (!existsSync(p)) return null
+    try { return (JSON.parse(readFileSync(p, 'utf8')) as { version?: string }).version ?? null } catch { return null }
+}

package/src/git-bootstrap.ts

@@ -0,0 +1,165 @@
+// git wiring for a fresh or adopted repo: a project with no .git, or with no
+// remote, exists on ONE disk. `shipkit init` and `shipkit start` both run
+// this, so a repo is versioned and backed up from its first minute. Every
+// step is idempotent and SILENT when it has nothing to do, which is what
+// lets both verbs call it without printing the same lines twice.
+//
+// The github half is ON by default, because starting a repo means wanting it
+// private on github. It is timid about everything else: it only ever creates
+// PRIVATE repositories (flipping one public is a human act behind the
+// pre-public audit), it never pushes and never commits, it creates only what
+// github reports as MISSING, and every 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 { basename, join } from 'path'
+import { spawnWithTimeout } from './core/spawn-timeout.ts'
+
+export type Run = (cmd: string[]) => Promise<{ code: number; out: string }>
+
+export type GitWiringOpts = {
+    /** github repository name — default the directory's basename */
+    name?: string
+    /** true forces the github half, false refuses it. undefined (the default)
+     *  runs it when this really is a repo being STARTED: see `justCreated` */
+    github?: boolean
+    /** this run created the dir, so the intent was to start a project. Left
+     *  false, a dir that already existed needs a package.json to earn a
+     *  remote, which is what keeps `ship <old-folder>` from minting repos */
+    justCreated?: boolean
+    /** report sink, default console.log */
+    print?: (line: string) => void
+    /** how `gh` runs. Injected by tests, which never touch a real account:
+     *  a runner (fake account) or an explicit null (no gh on this machine).
+     *  Undefined resolves the real binary, which is why no test may leave it
+     *  undefined and no test may lift SHIPKIT_NO_GITHUB */
+    gh?: Run | null
+}
+
+/** github repo names, and the same shape `shipkit start` accepts for a dir */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+/** the one line of gh or git output worth reporting — both merge stderr into
+ *  stdout, so the first non-empty line is the message and the rest is chatter */
+export const firstGhLine = (s: string): string => s.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 160) ?? ''
+
+/** gh mixes stderr chatter (upgrade notices, SSO warnings) into its output, so
+ *  the JSON object is carved out rather than parsed whole */
+export function carveGhJson<T>(out: string): T | null {
+    const start = out.indexOf('{')
+    const end = out.lastIndexOf('}')
+    if (start === -1 || end < start) return null
+    try {
+        return JSON.parse(out.slice(start, end + 1)) as T
+    } catch {
+        return null
+    }
+}
+
+const runner = (bin: string, root: string, timeoutMs: number): Run => async (cmd) => {
+    const r = await spawnWithTimeout([bin, ...cmd], { cwd: root, timeoutMs })
+    return { code: r.code, out: r.timedOut ? `${r.out}\n${bin} timed out after ${timeoutMs}ms` : r.out }
+}
+
+const samePath = (a: string, b: string): boolean => {
+    try {
+        return realpathSync(a) === realpathSync(b)
+    } catch {
+        return a === b
+    }
+}
+
+type RepoView = { nameWithOwner?: string; isPrivate?: boolean; url?: string; sshUrl?: string }
+
+export async function ensureGitWiring(root: string, opts: GitWiringOpts = {}): Promise<void> {
+    const p = opts.print ?? console.log
+    const git = runner('git', root, 60_000)
+
+    const top = await git(['rev-parse', '--show-toplevel'])
+    if (top.code === 0) {
+        // a dir INSIDE another work tree is a subdirectory, not a repo waiting
+        // to be born: initializing there would shadow the parent's history
+        if (!samePath(top.out.trim(), root)) return p(`skip: git — ${root} sits inside the repo at ${top.out.trim()}`)
+    } else {
+        let init = await git(['init', '-b', 'main'])
+        // -b landed in git 2.28; older gits get the same result in two steps
+        if (init.code !== 0) {
+            init = await git(['init'])
+            if (init.code === 0) await git(['symbolic-ref', 'HEAD', 'refs/heads/main'])
+        }
+        if (init.code !== 0) return p(`WARN git init failed: ${firstGhLine(init.out)}`)
+        p('ok: git repo initialized (branch main)')
+    }
+
+    const remotes = await git(['remote'])
+    if (remotes.out.trim() !== '') return
+
+    if (opts.github === false) return p('skip: github — --no-github')
+    const name = opts.name ?? basename(root)
+    if (!NAME_RE.test(name)) return p(`skip: github — '${name}' is not a usable repository name`)
+    // starting a repo means a remote. ENTERING a dir that was already there
+    // and is not a project does not: `ship <name>` is also the everyday cd,
+    // and a typo must never mint an account artifact nobody asked for
+    if (opts.github !== true && opts.justCreated !== true && !existsSync(join(root, 'package.json'))) {
+        p(`skip: github — ${root} already existed without a package.json`)
+        return p('      fix: pass --github to create the private repo anyway (`shipkit init` wires it once the project exists)')
+    }
+    // an injected runner wins (a test with its own account), then the env
+    // switch a machine sets to turn the whole half off, then the real binary
+    let gh: Run | null
+    if (opts.gh !== undefined) gh = opts.gh
+    else if ((process.env.SHIPKIT_NO_GITHUB ?? '') !== '') return p('skip: github — SHIPKIT_NO_GITHUB is set')
+    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 p('      fix: install gh, `gh auth login`, then re-run this command')
+    }
+
+    const user = await gh(['api', 'user', '--jq', '.login'])
+    if (user.code !== 0) {
+        p(`WARN no remote wired: gh is not usable here (${firstGhLine(user.out)})`)
+        return p('      fix: `gh auth login` (or reconnect), then re-run this command')
+    }
+    // stdout and stderr arrive merged, so an SSO or upgrade notice would
+    // otherwise become the owner and every call after it would address a
+    // repository that cannot exist
+    const login = firstGhLine(user.out)
+    if (!NAME_RE.test(login)) return p(`WARN no remote wired: gh did not answer with a login (${login})`)
+    const target = `${login}/${name}`
+    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,url,sshUrl']
+
+    let view = await gh(viewArgs)
+    let adopted = false
+    if (view.code === 0) {
+        // a name match is not proof of identity: an unrelated `api` or `docs`
+        // in the same account matches too, and pushing into it mixes projects
+        adopted = true
+        p(`WARN github ${target} already exists — wiring it as origin, confirm it is THIS project before you push`)
+    } else {
+        // only a MISSING repo means "create it". a network or permission error
+        // must never be answered by creating something
+        if (!/not found|could not resolve|404/i.test(view.out)) return p(`WARN no remote wired: gh could not read ${target} (${firstGhLine(view.out)})`)
+        const created = await gh(['repo', 'create', target, '--private'])
+        if (created.code !== 0) return p(`WARN no remote wired: creating ${target} failed (${firstGhLine(created.out)})`)
+        view = await gh(viewArgs)
+        // the repo EXISTS at this point, so the line must never read as a
+        // failed creation: only the wiring is missing
+        if (view.code !== 0) return p(`WARN created PRIVATE github repo ${target}, but could not read it back to wire origin (${firstGhLine(view.out)}) — re-run to finish`)
+        p(`ok: created PRIVATE github repo ${target}`)
+    }
+
+    const info = carveGhJson<RepoView>(view.out)
+    const proto = await gh(['config', 'get', 'git_protocol'])
+    const url = (firstGhLine(proto.out) === 'ssh' ? info?.sshUrl : info?.url) ?? info?.url ?? info?.sshUrl
+    if (url == null) return p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+
+    const add = await git(['remote', 'add', 'origin', url])
+    if (add.code !== 0) return p(`WARN no remote wired: git remote add failed (${firstGhLine(add.out)})`)
+    p(`ok: remote origin → ${url}`)
+    // the declared-visibility rule (SK007) reads this same fact later, but it
+    // only runs once the repo has a config: say it here, at the wiring
+    if (info?.isPrivate === false) p(`WARN ${target} is PUBLIC — declare visibility: 'public' in repo.config.ts, or make it private (rule SK007)`)
+    // never on the adopt path: the line above says to check WHAT that repo is
+    // first, and a push into an empty unrelated repo succeeds
+    if (!adopted) p('next: first commit, then `git push -u origin main`')
+}

package/src/hooks/run-hooks.ts

@@ -3,7 +3,7 @@
 // hand-rolled hooks are invisible to `shipkit check`: a repo reports green
 // while its next commit is already doomed, and nothing can enumerate what
 // the hooks enforce. `shipkit hooks list` answers that without reading shell.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
@@ -47,20 +47,31 @@ export function hookBinInvocation(root: string): string {
     return running.startsWith(prefix) ? `bun ${running.slice(prefix.length)}` : `bun ${running}`
 }
 
-export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git'; detail: string }
+export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git' | 'not-root' | 'failed'; detail: string }
 
 /** self-arming: a repo.config with dark commit gates is the half-wired state
- *  that let a whole drill session commit ungated (2026-08-04). Idempotent,
- *  and a FOREIGN core.hooksPath is respected and named, never taken. */
+ *  that let a whole drill session commit ungated (2026-08-04). Arming means
+ *  making DARK gates live: with BOTH hook files present under an armed
+ *  hooksPath nothing is rewritten (the repo's own --bin choice stands; a
+ *  missing file still triggers install, which overwrites a stale sibling). A FOREIGN
+ *  core.hooksPath is respected and named, and only the work-tree ROOT may
+ *  arm (a subdir would set the parent's hooksPath onto a dir that does not
+ *  exist there, disarming the parent's gates). */
 export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
-    const inRepo = Bun.spawnSync(['git', 'rev-parse', '--is-inside-work-tree'], { cwd: root })
-    if (inRepo.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const top = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], { cwd: root })
+    if (top.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const topDir = top.stdout.toString().trim()
+    try {
+        if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `work tree root is ${topDir}, not here` }
+    } catch {
+        return { state: 'no-git', detail: 'work tree root unresolvable' }
+    }
     const p = Bun.spawnSync(['git', 'config', 'core.hooksPath'], { cwd: root })
     const current = p.exitCode === 0 ? p.stdout.toString().trim() : ''
     if (current !== '' && current !== HOOK_DIR) return { state: 'foreign', detail: `core.hooksPath=${current}, foreign, left alone` }
+    if (current === HOOK_DIR && HOOKS.every((h) => existsSync(join(root, HOOK_DIR, h)))) return { state: 'current', detail: 'hooks already armed' }
     const r = installHooks(root, hookBinInvocation(root), config.hooks?.keywordFile)
-    if (r.note.startsWith('WARN')) return { state: 'foreign', detail: r.note }
-    if (r.written.length === 0 && current === HOOK_DIR) return { state: 'current', detail: 'hooks already armed' }
+    if (r.note.startsWith('WARN')) return { state: 'failed', detail: r.note }
     return { state: 'armed', detail: `wrote ${r.written.join(', ') || 'nothing'}, ${r.note}` }
 }
 

package/src/init-repo.ts

@@ -11,6 +11,7 @@ import { join } from 'path'
 import { canonicalBodies } from './core/canonical-scripts.ts'
 import { hasTestFiles } from './rules/SK001-package-json-shape.ts'
 import { reportToMotherhome } from './core/motherhome.ts'
+import { ensureGitWiring, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
@@ -35,29 +36,43 @@ export default defineRepo({
 export type InitOpts = {
     /** in-repo-source consumers: path to shipkit's cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>` */
     bin?: string
+    /** report sink, default console.log (startRepo passes console.error: its
+     *  stdout contract is the resolved dir alone) */
+    print?: (line: string) => void
+    /** false wires git only, never github. undefined keeps the default (on) */
+    github?: boolean
+    /** how `gh` runs — injected by tests, which never touch a real account */
+    gh?: Run | null
 }
 
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
+    const p = opts.print ?? console.log
     const configPath = join(root, 'repo.config.ts')
+    const pkgPath = join(root, 'package.json')
+    // the wrong-cwd refusal comes FIRST: a dir that is no project of any kind
+    // must not be left holding a git repo, let alone a github one, by a
+    // command whose next line says the cwd was wrong
+    if (!existsSync(pkgPath) && !existsSync(configPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
+    // versioned + backed up before it is gated, on the adoption re-run too
+    await ensureGitWiring(root, { github: opts.github, gh: opts.gh, print: p })
     if (existsSync(configPath)) {
-        console.log(`skip: repo.config.ts already exists`)
+        p(`skip: repo.config.ts already exists`)
         // adoption path: re-running init on an existing repo still converges
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
         const g = await gitignorePolicy.fix!({ root, config: cfg })
-        console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         const mh = reportToMotherhome(root, cfg)
-        if (mh.note != null) console.log(mh.note)
+        if (mh.note != null) p(mh.note)
         return 0
     }
-    const pkgPath = join(root, 'package.json')
-    if (!existsSync(pkgPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
+    // 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'
     writeFileSync(configPath, CONFIG_TEMPLATE(name))
-    console.log('ok: repo.config.ts created')
+    p('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
     pkg.scripts ??= {}
     let added = 0
@@ -69,32 +84,32 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
         if (k === 'test' && !hasTestFiles(root)) continue
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
-        else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
+        else if (pkg.scripts[k] !== v) p(`skip: package.json script '${k}' exists — left untouched`)
     }
     if (added > 0) {
         writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
-        console.log(`ok: ${added} package.json script(s) added`)
+        p(`ok: ${added} package.json script(s) added`)
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
-    console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+    p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     // show what the gate actually is — a thin floor must be seen at init
     // time, not discovered after a bad commit slipped through
     const floor = resolveFloor(defineRepo({ name }), root)
-    for (const t of floor.tasks) console.log(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
-    for (const u of floor.unfilled) console.log(`skip: ${u.id} (${u.reason})`)
+    for (const t of floor.tasks) p(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
+    for (const u of floor.unfilled) p(`skip: ${u.id} (${u.reason})`)
     // every verb comes from the `shipkit` bin — dead on arrival unless the
     // package is actually installed (bunx runs without adding the dep)
     if (opts.bin == null) {
         try {
             Bun.resolveSync('rvlib-shipkit', root)
         } catch {
-            console.log('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
-            console.log('      fix: bun add -d rvlib-shipkit')
+            p('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
+            p('      fix: bun add -d rvlib-shipkit')
         }
     }
-    console.log('next: fill venues/social in repo.config.ts, then `shipkit ci`')
-    console.log('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
+    p('next: fill venues/social in repo.config.ts, then `shipkit ci`')
+    p('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
     return 0
 }

package/src/release/run-bump.ts

@@ -27,7 +27,8 @@
 // RESUMABLE instead, because an npm publish cannot be undone and a rollback
 // that cannot roll back is a lie.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { relative } from 'path'
+import { homedir } from 'os'
+import { join, relative } from 'path'
 import { declaredKind, hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
 import { deriveRemote, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
 import { unitBlockers } from './unit-gate.ts'
@@ -206,8 +207,33 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
             return 1
         }
     }
+    // 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'])
+        if (c.docsBase != null) {
+            const base = c.docsBase.startsWith('~/') ? join(homedir(), c.docsBase.slice(2)) : c.docsBase
+            const page = join(base, 'build/shipkit/local-projects.md')
+            const prefix = r.endsWith('/') ? r : `${r}/`
+            if (page.startsWith(prefix)) s.add(relative(r, page))
+        }
+        return s
+    }
     // the tree must be clean BEFORE any branch move, or a checkout carries
-    // uncommitted work across branches
+    // uncommitted work across branches. Machine-written surfaces (STATUS.md,
+    // 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)
+    if (preDirty !== '') {
+        const machine = machineWrittenPaths(root, config)
+        const paths = preDirty.split('\n').map((l) => l.slice(3).trim().replace(/^"|"$/g, ''))
+        if (paths.every((p) => machine.has(p))) {
+            gitAt(root, ['add', '--', ...paths])
+            const c = gitAt(root, ['commit', '-m', 'machine rows refresh before release'])
+            if (c.code === 0) print('ok: machine-written rows committed (they re-dirty on every gate run)')
+            else print(`WARN machine-row auto-commit failed (exit ${c.code}), the refusal below says what to do:\n${c.out.split('\n').slice(-6).join('\n')}`)
+        }
+    }
     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 }
 

package/src/rules/SK007-github-visibility.ts

@@ -13,6 +13,7 @@
 // unverifiable path (no git, no remote, non-github remote, gh missing or
 // erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
 // never cached.
+import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
 import type { Rule } from './rule.ts'
 
 export const githubVisibility: Rule = {
@@ -28,7 +29,7 @@ export const githubVisibility: Rule = {
     lint: async (t, env) => {
         const declared = env.config.visibility ?? 'private'
         const skip = (why: string): void => void t.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
-        const firstLine = (s: string): string => s.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? ''
+        const firstLine = firstGhLine
 
         const remotes = await t.exec(['git', 'remote'], { cwd: env.root })
         if (remotes.code !== 0) return skip(`git says: ${firstLine(remotes.out) || `exit ${remotes.code}`}`)
@@ -44,18 +45,9 @@ export const githubVisibility: Rule = {
 
         const r = await t.exec(['gh', 'repo', 'view', target, '--json', 'isPrivate,nameWithOwner'], { cwd: env.root, timeoutMs: 30_000 })
         if (r.code !== 0) return skip(`gh failed (${firstLine(r.out)})`)
-        // gh mixes stderr chatter (release notices, SSO warnings) into the
-        // captured output — carve the JSON object out before parsing, and an
-        // unreadable answer stays an UNKNOWN, never a FAIL
-        const start = r.out.indexOf('{')
-        const end = r.out.lastIndexOf('}')
-        let parsed: { isPrivate?: boolean; nameWithOwner?: string }
-        try {
-            if (start === -1 || end < start) throw new Error('no JSON object in output')
-            parsed = JSON.parse(r.out.slice(start, end + 1)) as typeof parsed
-        } catch {
-            return skip(`gh answer unreadable (${firstLine(r.out)})`)
-        }
+        // an unreadable answer stays an UNKNOWN, never a FAIL
+        const parsed = carveGhJson<{ isPrivate?: boolean; nameWithOwner?: string }>(r.out)
+        if (parsed == null) return skip(`gh answer unreadable (${firstLine(r.out)})`)
         const actual = parsed.isPrivate === true ? 'private' : 'public'
         const who = parsed.nameWithOwner ?? target
         if (actual === declared) t.ok(`github ${who} is ${actual} — matches repo.config visibility`)

package/src/start-repo.ts

@@ -7,6 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
+import { ensureGitWiring, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 
 export type StartOpts = {
@@ -18,6 +19,11 @@ export type StartOpts = {
     alsoOk?: string[]
     /** repo names that never get includes */
     skip?: string[]
+    /** true forces the github half, false refuses it. undefined = the default:
+     *  a dir this run created, or an existing project, gets its private repo */
+    github?: boolean
+    /** how `gh` runs — injected by tests, which never touch a real account */
+    gh?: Run | null
 }
 
 export async function startRepo(name: string, opts: StartOpts = {}): Promise<number> {
@@ -26,7 +32,11 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         return 2
     }
     const dir = join(opts.root ?? join(homedir(), 'dev'), name)
-    if (!existsSync(dir)) {
+    // this run creating the dir IS the signal that a repo is being started,
+    // which is what the github half keys on: `ship <name>` is also the
+    // everyday cd into a folder that already exists
+    const justCreated = !existsSync(dir)
+    if (justCreated) {
         mkdirSync(dir, { recursive: true })
         console.error(`ok: created ${dir}`)
     }
@@ -59,16 +69,25 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     // start is the from-anywhere verb: a dir that is already a real project
     // (package.json) gets wired on the spot, so a pre-existing repo goes
     // 0 → shipkit'd with the one command. init itself stays cwd-only, like
-    // git init. A brand-new empty dir cannot be wired yet, say what is next.
-    if (!existsSync(join(dir, 'repo.config.ts'))) {
-        if (existsSync(join(dir, 'package.json'))) {
-            // initRepo reports on stdout, but start's stdout contract is THE
-            // DIR ONLY (a sourced alias cd's to it) — reroute to stderr here
-            const realLog = console.log
-            console.log = ((...a: unknown[]) => console.error(...a)) as typeof console.log
-            try { await initRepo(dir, {}) } finally { console.log = realLog }
-        } else {
-            console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
+    // git init. A brand-new empty dir gets git + its remote all the same, and
+    // is told what is next, because the shipkit scaffold needs a package.json.
+    // --skip means shipkit NEVER TOUCHES that repo (his job repo lives on
+    // this list), not just no CLAUDE.md. And the cd contract survives a
+    // failed adoption: the dir always prints, wiring trouble is a WARN.
+    if (!(opts.skip ?? []).includes(name)) {
+        // git BEFORE the shipkit scaffold, and whether or not the dir is a
+        // project yet: an empty new dir is still work that must not live on
+        // one disk. initRepo runs the same wiring, which is silent once done
+        const print = (l: string): void => console.error(l)
+        try { await ensureGitWiring(dir, { name, github: opts.github, justCreated, gh: opts.gh, print }) }
+        catch (e) { console.error(`WARN could not wire git in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+        if (!existsSync(join(dir, 'repo.config.ts'))) {
+            if (existsSync(join(dir, 'package.json'))) {
+                try { await initRepo(dir, { github: opts.github, gh: opts.gh, print }) }
+                catch (e) { console.error(`WARN could not wire ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+            } else {
+                console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
+            }
         }
     }
     console.log(dir)