rvlib-shipkit 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -1,11 +1,30 @@
 # Changelog
 
+## 0.22.0
+
+- **Fix: the machine-row auto-commit could not see STATUS.md.** The git helper trims its whole output, so the FIRST porcelain line loses its leading space and the old column-3 slice read "TATUS.md", making the preflight silently decline the exact dirt it was built to eat. `dirtyPathList` parses status prefixes robustly now (renames and quoted paths included, regression-tested on the trimmed-first-line case), and a decline is never silent: the preflight names the non-machine paths it refused.
+- **Cached check lines carry an absolute stamp** (`cached 2026-08-05 09:12:34`), never a relative age: "cached 34m ago" re-rendered on every run and turned committed STATUS.md checkpoints into noise diffs that startled agents (his call 2026-08-05). The line now changes only when the cache actually refreshes.
+
+- **The pre-commit gate times itself.** Past ~1.5s it WARNs naming the fix (move slow preCommit commands to ci tasks), because "a commit takes ~1s" was a stated rule with no tripwire, and a repo drifting back to 40-second commits would have told nobody.
+- **The bootstrap is a CHAIN, and it ends at a push.** `shipkit start` and `shipkit init` now run git init → **first commit** → PRIVATE github repo → **push**, in that order. A repo wired but never pushed had backed up nothing, which was the whole point. The chain runs in two phases around whatever the verb scaffolds, so `CLAUDE.md`, `repo.config.ts` and the package.json scripts ride INSIDE the first commit instead of trailing it as dirt.
+- The first commit (`chore: initial commit`) is made only when the history has NONE: an existing history belongs to whoever wrote it, and their uncommitted work stays theirs to stage. A repo with no `.gitignore` at all gets a baseline (`node_modules/`, `.env*` while keeping `.env.example`, `.DS_Store`). A repo that HAS one keeps its own answer, and if a `node_modules` or a `.env` is still staged ANYWHERE in the tree the commit REFUSES and names them. The scan is `-uall`, because plain `git status --porcelain` collapses an untracked dir to its top entry and a nested `.env` reads as `?? packages/`. Rule SK004 stays the only writer of its managed block: `firstCommit` no longer rewrites it from a synthetic config, which deleted the lines `repo.config.ts` contributed right before staging what they covered.
+- The push goes only into a repo this run CREATED, carrying a history this run WROTE. Never into an adopted one (pushing into an empty unrelated repo of the same name succeeds and mixes two projects), and never a pre-existing local history (a one way door over content nobody reviewed for that purpose). Both get a `next:` line naming the push instead.
+- `--no-github` says what it does: everything stays local, the first commit included.
+
+## 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 existing hook bodies.** 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.
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.20.1",
+    "version": "0.22.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_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. scaffolds repo.config.ts + ci/check/contracts package.json scripts, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. 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 and the first commit, 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, and the first commit is pushed to it. --no-github keeps everything local, the first commit included (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, wires shipkit on the spot (repo.config.ts via init) when the project already has a package.json, then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. 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, wiring, git, first commit, private github repo, push', '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 and the first commit, never touch github', 'shipkit start pong --no-github'],
         ],
     })
 
@@ -22,8 +24,9 @@ export class StartCommand extends Command {
     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 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, and the first commit is pushed to it. Pass --github to force it for a pre-existing folder, --no-github to keep everything local, the first commit included (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/check-suite.ts

@@ -11,7 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { CheckCtx, RateLimited, ToolUnresolved } from './check-ctx.ts'
-import { fmtAge, formatLine, parseDuration, type Line } from './wire.ts'
+import { fmtStamp, formatLine, parseDuration, type Line } from './wire.ts'
 
 type Logic = (t: CheckCtx) => unknown
 type Prep = { skip?: string; cacheExtra?: string }
@@ -143,8 +143,11 @@ export class CheckSuite {
                 && entry != null && entry.version === r.version && entry.key === key
                 && this.now() - entry.at < r.ttlMs && this.now() >= entry.at
             if (fresh) {
-                const age = fmtAge(this.now() - entry.at)
-                const lines = entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${age} ago)` } : l))
+                // absolute stamp, never "Xm ago": a relative age re-renders on
+                // every run and turns committed STATUS.md checkpoints into
+                // noise diffs (his call 2026-08-05). The line now changes only
+                // when the cache actually refreshes.
+                const lines = entry.lines.map((l, i): Line => (i === 0 ? { ...l, text: `${l.text} (cached ${fmtStamp(entry.at)})` } : l))
                 out.push(...lines)
                 this.onResult?.(r.name, { lines, status: 'pass', cached: true }) // only clean passes are cached
                 continue

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/core/wire.ts

@@ -49,8 +49,11 @@ export function parseDuration(d: string | number): number {
     return Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3600_000, d: 86400_000 }[m[2] as 'ms' | 's' | 'm' | 'h' | 'd']
 }
 
-export const fmtAge = (ms: number): string =>
-    ms < 60_000 ? `${Math.round(ms / 1000)}s`
-    : ms < 3600_000 ? `${Math.round(ms / 60_000)}m`
-    : ms < 86400_000 ? `${Math.round(ms / 3600_000)}h`
-    : `${Math.round(ms / 86400_000)}d`
+/** absolute local stamp (2026-08-05 09:12:34), never a relative age: a
+ *  relative render changes every run and turns committed STATUS.md
+ *  checkpoints into noise diffs */
+export const fmtStamp = (epochMs: number): string => {
+    const d = new Date(epochMs)
+    const p = (n: number): string => String(n).padStart(2, '0')
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}

package/src/git-bootstrap.ts

@@ -0,0 +1,284 @@
+// the bootstrap chain a started repo gets, in this order: git init, first
+// commit, PRIVATE github repo, push. A project that stops before the push is
+// still one disk away from gone, so the chain only counts when it completes.
+// `shipkit init` and `shipkit start` both run it, in two phases: the repo
+// first (cheap, local), then the publish LAST, so whatever those verbs
+// scaffold rides inside the first commit instead of trailing it. Every step
+// is idempotent and SILENT when it has nothing to do.
+//
+// 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 creates only what github reports as MISSING, it
+// pushes only into a repo it created THIS RUN (a name match is not proof of
+// identity), it never touches a history that already has commits, 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 PublishOpts = {
+    /** github repository name — default the directory's basename */
+    name?: string
+    /** true forces the publish chain, false refuses the github half.
+     *  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
+     *  commit and a remote, which is what keeps `ship <old-folder>` from
+     *  committing someone's photos and minting a repo nobody asked for */
+    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._-]*$/
+
+/** what a repo with NO .gitignore at all gets before its first commit. Not a
+ *  policy (rule SK004 owns that one), just the three things nobody ever meant
+ *  to publish. A repo that already has a .gitignore keeps its own answer, and
+ *  the commit refuses instead when that answer misses these */
+const IGNORE_BASELINE = ['node_modules/', '.env', '.env.*', '!.env.example', '.DS_Store']
+
+/** 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) => {
+    // a credential prompt would hang a bootstrap forever: git fails instead
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    const r = await spawnWithTimeout([bin, ...cmd], { cwd: root, timeoutMs, env })
+    return { code: r.code, out: r.timedOut ? `${r.out}\n${bin} timed out after ${timeoutMs}ms` : r.out }
+}
+
+const gitIn = (root: string): Run => runner('git', root, 120_000)
+
+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 }
+
+/** phase one: this dir IS a git work tree root. false means the caller must
+ *  not publish anything (a subdirectory of another repo, or git refused), and
+ *  both callers honor it. */
+export async function ensureGitRepo(root: string, opts: { print?: (line: string) => void } = {}): Promise<boolean> {
+    const p = opts.print ?? console.log
+    const git = gitIn(root)
+    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 true
+        p(`skip: git — ${root} sits inside the repo at ${top.out.trim()}`)
+        return false
+    }
+    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) {
+        p(`WARN git init failed: ${firstGhLine(init.out)}`)
+        return false
+    }
+    p('ok: git repo initialized (branch main)')
+    return true
+}
+
+/** phase two, run LAST: first commit → private github repo → push. */
+export async function publishRepo(root: string, opts: PublishOpts = {}): Promise<void> {
+    const p = opts.print ?? console.log
+    const git = gitIn(root)
+
+    const top = await git(['rev-parse', '--show-toplevel'])
+    if (top.code !== 0 || !samePath(top.out.trim(), root)) return
+
+    // starting a repo means a commit and a remote. ENTERING a dir that was
+    // already there and is not a project means neither: `ship <name>` is also
+    // the everyday cd, and a typo must never commit a stranger's folder or
+    // mint an account artifact nobody asked for
+    const starting = opts.github === true || opts.justCreated === true || existsSync(join(root, 'package.json'))
+    const name = opts.name ?? basename(root)
+
+    const had = (await git(['rev-parse', '--verify', 'HEAD'])).code === 0
+    const commits = had || (starting && (await firstCommit(root, git, p)))
+
+    // a repo that already has a remote is published somewhere: nothing here
+    // gets to decide where its code goes. A first commit made just now still
+    // has to reach it, and that stays the caller's move
+    const remotes = await git(['remote'])
+    if (remotes.out.trim() !== '') {
+        if (!had && commits) p(`next: git push -u ${remotes.out.trim().split('\n')[0]} ${(await git(['branch', '--show-current'])).out.trim() || 'main'}`)
+        return
+    }
+
+    if (opts.github === false) return void p('skip: github — --no-github')
+    if (!NAME_RE.test(name)) return void p(`skip: github — '${name}' is not a usable repository name`)
+    if (!starting) {
+        p(`skip: github — ${root} already existed without a package.json`)
+        return void p('      fix: pass --github to commit and create the private repo anyway')
+    }
+    // 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 void 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 void 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 void 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 void 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 created = 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
+        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 void p(`WARN no remote wired: gh could not read ${target} (${firstGhLine(view.out)})`)
+        const create = await gh(['repo', 'create', target, '--private'])
+        if (create.code !== 0) return void p(`WARN no remote wired: creating ${target} failed (${firstGhLine(create.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 void p(`WARN created PRIVATE github repo ${target}, but could not read it back to wire origin (${firstGhLine(view.out)}) — re-run to finish`)
+        created = true
+        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 void p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+
+    const add = await git(['remote', 'add', 'origin', url])
+    if (add.code !== 0) return void 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 into an ADOPTED repo: the warning above says to check what that
+    // repo is first, and a push into an empty unrelated one succeeds
+    if (!created) return
+    const branch = (await git(['branch', '--show-current'])).out.trim() || 'main'
+    if (!commits) return void p(`next: first commit, then \`git push -u origin ${branch}\``)
+    // and never a history this run did not write: publishing an existing
+    // local-only history is a one-way door over content nobody reviewed for
+    // this purpose (deleted secrets stay reachable in old objects)
+    if (had) return void p(`next: review what this history contains, then \`git push -u origin ${branch}\``)
+    const push = await git(['push', '-u', 'origin', branch])
+    if (push.code !== 0) {
+        p(`WARN nothing pushed yet: ${firstGhLine(push.out)}`)
+        return void p(`      fix: git push -u origin ${branch}`)
+    }
+    p(`ok: pushed ${branch} → origin, the repo exists somewhere other than this disk`)
+}
+
+/** the first commit, and only ever the FIRST: a history that already has one
+ *  belongs to whoever wrote it, and their uncommitted work is theirs to
+ *  stage. Returns whether the repo now has a commit. */
+async function firstCommit(root: string, git: Run, p: (line: string) => void): Promise<boolean> {
+    // -uall, never the default: `git status --porcelain` collapses an
+    // untracked dir to its topmost entry, so a nested .env reads as `?? src/`
+    // and every check below it looks at a path that is not the file
+    const before = await git(['status', '--porcelain', '-uall'])
+    if (before.code !== 0) {
+        p(`WARN no first commit: ${firstGhLine(before.out)}`)
+        return false
+    }
+    if (before.out.trim() === '') {
+        p('skip: first commit — nothing in this dir yet')
+        return false
+    }
+    // a repo with no .gitignore at all gets the baseline: the very first
+    // commit is the one nobody reviews, and it is the one that ships a .env
+    // to github. A repo that HAS one keeps its own answer, whatever it says.
+    // rule SK004 stays the only writer of its managed block, with the repo's
+    // real config: rewriting it from a synthetic one here DELETED the lines
+    // repo.config.ts contributed, seconds before staging what they covered
+    if (!existsSync(join(root, '.gitignore'))) await Bun.write(join(root, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+    const status = await git(['status', '--porcelain', '-uall'])
+    if (status.code !== 0) {
+        p(`WARN no first commit: ${firstGhLine(status.out)}`)
+        return false
+    }
+    const paths = status.out.split('\n').filter((l) => l.trim() !== '').map((l) => l.slice(3).trim().replace(/^"|"$/g, ''))
+    // the .gitignore in this repo does not cover these, at any depth: the
+    // commit is not ours to make, and a PRIVATE github repo is still a leak
+    const risky = paths.filter(isRisky)
+    if (risky.length > 0) {
+        p(`WARN no first commit: ${risky.slice(0, 3).join(', ')}${risky.length > 3 ? ` and ${risky.length - 3} more` : ''} would be committed`)
+        p('      fix: gitignore those, then commit by hand')
+        return false
+    }
+    const add = await git(['add', '-A'])
+    if (add.code !== 0) {
+        p(`WARN no first commit: ${firstGhLine(add.out)}`)
+        return false
+    }
+    const commit = await git(['commit', '-m', 'chore: initial commit'])
+    if (commit.code !== 0) {
+        p(`WARN no first commit: ${firstGhLine(commit.out)}`)
+        // a hook, a locked index and an unset identity all land here: only
+        // the last one is fixed by setting an identity
+        if (/user\.email|user\.name|tell me who you are/i.test(commit.out)) p('      fix: git config user.email + user.name, then re-run')
+        else p('      fix: resolve that, then commit by hand')
+        return false
+    }
+    p(`ok: initial commit (${paths.length} file${paths.length === 1 ? '' : 's'})`)
+    return true
+}
+
+/** never in a first commit, wherever it sits in the tree. `.env.example` and
+ *  friends are documentation and belong in the repo */
+function isRisky(f: string): boolean {
+    if (f.split('/').includes('node_modules')) return true
+    const base = basename(f)
+    return base.startsWith('.env') && !/^\.env\.(example|sample|template|dist)$/.test(base)
+}

package/src/hooks/run-hooks.ts

@@ -51,8 +51,9 @@ export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git'
 
 /** 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). Arming means
- *  making DARK gates live: hooks that already exist under an armed hooksPath
- *  are never rewritten (the repo's own --bin choice stands). A FOREIGN
+ *  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). */
@@ -126,8 +127,11 @@ function seedKeywordFile(root: string, keywordFile?: string): string | null {
 
 export type GateOutcome = { id: string; ok: boolean; lines: string[] }
 
-/** the pre-commit gate: built-in leak guard, then the repo's own commands. */
+/** the pre-commit gate: built-in leak guard, then the repo's own commands.
+ *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
+ *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
 export async function runPreCommit(root: string, config: RepoConfig): Promise<GateOutcome[]> {
+    const started = performance.now()
     const h = config.hooks ?? {}
     const out: GateOutcome[] = []
     if (!(h.disable ?? []).includes('leak-guard')) {
@@ -184,6 +188,13 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             lines: r.code === 0 ? [`ok: ${c.id}`] : [`FAIL: ${c.id} (exit ${r.code})`, ...r.out.trim().split('\n').slice(-30).map((l) => `      ${l}`)],
         })
     }
+    const elapsed = performance.now() - started
+    if (elapsed > 1500)
+        out.push({
+            id: 'hook-budget',
+            ok: true,
+            lines: [`WARN pre-commit took ${(elapsed / 1000).toFixed(1)}s (budget ~1s) — move slow preCommit commands to ci tasks (build/shipkit.md)`],
+        })
     return out
 }
 

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 { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
@@ -38,11 +39,26 @@ export type InitOpts = {
     /** 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
+    /** the caller already ran the publish chain (startRepo does, after this
+     *  scaffold, so the first commit carries repo.config.ts) */
+    noPublish?: 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 }
+    // the repo exists before anything is scaffolded, the PUBLISH comes last
+    // (bottom of this function) so the first commit carries the scaffold
+    const wired = await ensureGitRepo(root, { print: p })
     if (existsSync(configPath)) {
         p(`skip: repo.config.ts already exists`)
         // adoption path: re-running init on an existing repo still converges
@@ -53,10 +69,10 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
+        if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
         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'
@@ -98,6 +114,8 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
             p('      fix: bun add -d rvlib-shipkit')
         }
     }
+    // last, so the first commit carries repo.config.ts and the scripts above
+    if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
     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/git-facts.ts

@@ -39,6 +39,18 @@ export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string):
         .join('\n')
 }
 
+/** porcelain lines → bare paths. Column math is a trap here: the git()
+ *  helper trims the WHOLE output, so the FIRST line loses its leading
+ *  status space and a fixed slice eats the path's first letter (field bug
+ *  2026-08-05: "STATUS.md" parsed as "TATUS.md" and the machine-row
+ *  auto-commit silently declined). Renames keep only the NEW path. */
+export const dirtyPathList = (dirty: string): string[] =>
+    dirty
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '')
+        .map((l) => (l.split(' -> ').at(-1) ?? l).replace(/^[MTADRCU?!]{1,2}\s+/, '').replace(/^"|"$/g, ''))
+
 export const tagExistsLocally = (root: string, tag: string): boolean =>
     git(root, ['rev-parse', '--quiet', '--verify', `refs/tags/${tag}`]).code === 0
 

package/src/release/run-bump.ts

@@ -27,9 +27,10 @@
 // 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 { deriveRemote, dirtyPathList, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
 import { unitBlockers } from './unit-gate.ts'
 import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
 import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
@@ -206,8 +207,37 @@ 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 = dirtyPathList(preDirty)
+        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')}`)
+        } else {
+            // never decline in silence: name the human dirt so the refusal
+            // below reads as a decision, not a mystery
+            print(`note: dirt beyond the machine rows (${paths.filter((p) => !machine.has(p)).join(', ')}), not auto-committing`)
+        }
+    }
     const dirty = dirtyPaths(root, config)
     if (dirty !== '') { print(`FAIL: working tree not clean, commit your work first:\n${dirty.split('\n').slice(0, 10).join('\n')}`); return 1 }
 

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/shipkit.ts

@@ -33,7 +33,7 @@ export { spawnWithTimeout } from './core/spawn-timeout.ts'
 export type { SpawnOutcome, SpawnTimeoutOpts } from './core/spawn-timeout.ts'
 export { writeStatus } from './core/write-status.ts'
 export type { StatusInput, StatusOutcome } from './core/write-status.ts'
-export { formatLine, parseDuration, fmtAge, parseWireOutput } from './core/wire.ts'
+export { formatLine, parseDuration, fmtStamp, parseWireOutput } from './core/wire.ts'
 export type { Line } from './core/wire.ts'
 // the SK rule registry — stable-id invariants `shipkit check` enforces;
 // consumers (e.g. a wiki lint verifying mentioned ids exist) read RULES

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 { ensureGitRepo, publishRepo, 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,17 +69,33 @@ 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.
+    // 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) && !existsSync(join(dir, 'repo.config.ts'))) {
-        if (existsSync(join(dir, 'package.json'))) {
-            try { await initRepo(dir, { print: (l) => console.error(l) }) }
-            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`)
+    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. The PUBLISH (first commit → private repo → push) is the
+        // last thing that happens, so it carries CLAUDE.md and the scaffold
+        const print = (l: string): void => console.error(l)
+        let wired = false
+        try { wired = await ensureGitRepo(dir, { print }) }
+        catch (e) { console.error(`WARN could not wire git in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+        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 }) }
+                catch (e) { console.error(`WARN could not wire ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+            } else unscaffolded = true
+        }
+        if (wired) {
+            try { await publishRepo(dir, { name, github: opts.github, justCreated, gh: opts.gh, print }) }
+            catch (e) { console.error(`WARN could not publish ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
         }
+        // last line, so what to do next is the last thing read
+        if (unscaffolded) 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)
     return 0