rvlib-shipkit 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

package/package.json

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

@@ -8,16 +8,16 @@ 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. `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>`',
+        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 only, never touch github', 'shipkit init --no-github'],
+            ['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. --no-github wires local git only (SHIPKIT_NO_GITHUB=1 does it for every run)' })
+    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 {

package/src/cli/cmd_Start.ts

@@ -9,13 +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, 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`',
+        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: dir, git, private github repo, wiring', '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 only, never touch github', 'shipkit start pong --no-github'],
+            ['local git and the first commit, never touch github', 'shipkit start pong --no-github'],
         ],
     })
 
@@ -24,7 +24,7 @@ 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. 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)' })
+    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, 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/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

@@ -1,31 +1,36 @@
-// 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 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 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.
+// 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 GitWiringOpts = {
+export type PublishOpts = {
     /** 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` */
+    /** 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
-     *  remote, which is what keeps `ship <old-folder>` from minting repos */
+     *  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
@@ -39,6 +44,12 @@ export type GitWiringOpts = {
 /** 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) ?? ''
@@ -57,10 +68,14 @@ export function carveGhJson<T>(out: string): T | null {
 }
 
 const runner = (bin: string, root: string, timeoutMs: number): Run => async (cmd) => {
-    const r = await spawnWithTimeout([bin, ...cmd], { cwd: root, timeoutMs })
+    // 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)
@@ -71,95 +86,199 @@ const samePath = (a: string, b: string): boolean => {
 
 type RepoView = { nameWithOwner?: string; isPrivate?: boolean; url?: string; sshUrl?: string }
 
-export async function ensureGitWiring(root: string, opts: GitWiringOpts = {}): Promise<void> {
+/** 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 = runner('git', root, 60_000)
-
+    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 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)')
+        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
+}
 
-    const remotes = await git(['remote'])
-    if (remotes.out.trim() !== '') return
+/** 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
 
-    if (opts.github === false) return p('skip: github — --no-github')
+    // 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)
-    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'))) {
+
+    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 p('      fix: pass --github to create the private repo anyway (`shipkit init` wires it once the project exists)')
+        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 p('skip: github — SHIPKIT_NO_GITHUB is set')
+    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 p('      fix: install gh, `gh auth login`, then re-run this command')
+        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 p('      fix: `gh auth login` (or reconnect), then re-run this command')
+        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 p(`WARN no remote wired: gh did not answer with a login (${login})`)
+    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 adopted = false
+    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
-        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)})`)
+        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 p(`WARN created PRIVATE github repo ${target}, but could not read it back to wire origin (${firstGhLine(view.out)}) — re-run to finish`)
+        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 p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+    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 p(`WARN no remote wired: git remote add failed (${firstGhLine(add.out)})`)
+    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 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`')
+
+    // 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

@@ -127,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')) {
@@ -185,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,7 +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 { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
@@ -41,6 +41,9 @@ export type InitOpts = {
     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
 }
@@ -53,8 +56,9 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     // 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 })
+    // 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
@@ -65,6 +69,7 @@ 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
     }
     // guaranteed by the refusal above: no config means a package.json is here
@@ -109,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

@@ -30,7 +30,7 @@ import { existsSync, readFileSync, writeFileSync } from 'fs'
 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'
@@ -226,12 +226,16 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     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, ''))
+        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)

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,7 +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 { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 
 export type StartOpts = {
@@ -77,18 +77,25 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     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
+        // 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)
-        try { await ensureGitWiring(dir, { name, github: opts.github, justCreated, gh: opts.gh, print }) }
+        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 }) }
+                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 {
-                console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
-            }
+            } 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