rvlib-shipkit 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- A failure to arm prints as a WARN, never as a skip, and a successful arm says to commit the `hooks/` dir.
+
+## 0.20.0
+
+- **Commit gates arm themselves.** An interactive `shipkit ci` run now installs the git hooks whenever the repo has a `repo.config.ts` and `core.hooksPath` is unset or already `hooks`: hook bodies written, leak-guard keyword starter seeded, `core.hooksPath` set, idempotent. The field case: a whole drill session committed with dark gates because init was treated as "create repo.config.ts". A FOREIGN `core.hooksPath` (husky and friends) is respected and named, never taken. Hook bodies prefer the repo's own `node_modules/rvlib-shipkit` copy over the cli that happens to be running, so a repo keeps its pinned version. Scoped to the interactive gate on purpose: CI verify mode, `bump` and `release` gate runs never mutate the tree they are about to ship, and arming reports on its own line, never as a fixer rewrite.
+- **`start` is the from-anywhere bootstrap, `init` says it is cwd-only.** His friction: "no idea what shipkit start does" and init never said where it acts. `shipkit start <name>` now also WIRES the project (runs the init scaffold) when `~/dev/<name>` already has a package.json, so a pre-existing repo goes zero to shipkit'd with one command from any cwd; an empty new dir prints the next step on stderr. stdout stays the dir alone (the cd-alias contract, frozen by test). Both usage texts state their scope and point at each other.
+- **The commit-message gate blocks French.** Git surfaces are English, always. New `language` offense in the shared predicate: an accented letter, or two distinct French function words on one line, trips it. Quoted spans (backticks, double quotes, guillemets) are exempt as product copy under discussion. Single quotes stay in scope because they are French apostrophes. `hooks.languageAllow` in repo.config exempts listed words (proper nouns that carry accents without being a language choice), and `hooks.disable: ['commit-language']` lifts only the French check, never the dash and attribution guards. Write-time only: SK009 history audits still scan attribution and dashes, so no repo retro-fails on old French commits.
+
 ## 0.19.0
 
 - **The attribution tell list covers session trailers and assistant share urls.** `<assistant>-Session:` trailers (claude, chatgpt, copilot, cursor, aider, devin, gemini, codex) and claude.ai/claude.com/chatgpt.com/chat.openai.com urls now trip the shared predicate (commit-msg hook + SK009 history scan). Field case: 162 session links sat in a history both gates called clean.

package/package.json

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

@@ -35,6 +35,7 @@ export class CiCommand extends Command {
                 json: this.json,
                 fix: this.fix,
                 fixRules: this.fixRules,
+                armHooks: true,
                 frozen: this.frozen,
                 skipGroups: this.skip,
                 withIds: this.withIds,

package/src/cli/cmd_Hooks.ts

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

package/src/cli/cmd_Init.ts

@@ -8,9 +8,9 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'scaffold repo.config.ts + ci/check/contracts package.json scripts, then print how the floor resolved',
+        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>`',
         examples: [
-            ['bootstrap the current repo', 'shipkit init'],
+            ['wire the repo you are standing in', 'shipkit init'],
             ['in-repo-source consumer: scripts run the CLI by path', 'shipkit init --bin wiki/build/shipkit/rvlib-shipkit/src/cli.ts'],
         ],
     })

package/src/cli/cmd_Start.ts

@@ -9,10 +9,11 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'ensure <root>/<name> exists, optionally with a CLAUDE.md include line. Prints the dir on stdout so a shell alias can cd there',
+        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`',
         examples: [
-            ['start (or enter) a repo', 'shipkit start pong'],
+            ['create or enter ~/dev/pong, wiring it if it is already a project', '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'],
         ],
     })
 
@@ -20,7 +21,7 @@ export class StartCommand extends Command {
     root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
     include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept. Omitted means only ensure the dir' })
     alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add' })
-    skip = Option.Array('--skip', { description: 'repo names that never get the include' })
+    skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring' })
 
     async execute(): Promise<number> {
         return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip })

package/src/core/run-ci.ts

@@ -27,6 +27,8 @@ export type CiOpts = {
     fix?: boolean
     /** also apply the structural SK rule fixers during the fix pass */
     fixRules?: boolean
+    /** self-arm the git hooks in the fix pass (interactive ci entry only) */
+    armHooks?: boolean
     /** run only the checks that can block (core/run-check onlyBlocking) */
     onlyBlockingChecks?: boolean
     /** task ids the caller does not need. A sub-unit release skips the tasks
@@ -76,7 +78,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
     if (o.fix !== false)
-        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, print: sink })).failed
+        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, armHooks: o.armHooks === true, print: sink })).failed
     else sink('skip: fix pass (--no-fix)')
     const all = allTasks(c, root)
     const { disabled, unfilled } = all

package/src/core/run-fixers.ts

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
+import { armHooks } from '../hooks/run-hooks.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { runFix } from '../rules/run-fix.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
@@ -105,6 +106,10 @@ function treeState(root: string): Map<string, string> | null {
 export type FixPassOpts = {
     /** also apply the structural SK rule fixers (default false) */
     rules?: boolean
+    /** also self-arm the git hooks (default false — ONLY the interactive
+     *  `shipkit ci` entry passes true; bump and release gates must never
+     *  mutate the tree they are about to ship) */
+    armHooks?: boolean
     print: (line: string) => void
 }
 
@@ -120,6 +125,16 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // verify mode: same fixers, but rewriting anything means the COMMIT was
     // not clean, and the gate says so instead of quietly repairing it
     const verify = process.env.CI != null && process.env.CI !== ''
+    // commit gates arm themselves on the interactive gate: a repo.config with
+    // dark hooks is the half-wired state that let a whole drill session
+    // commit ungated (2026-08-04). Runs BEFORE the tree snapshot: arming is
+    // its own reported concern, never counted as a fixer rewrite.
+    if (o.armHooks === true && !verify) {
+        const armed = armHooks(root, config)
+        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the hooks/ dir`)
+        else if (armed.state === 'foreign' || armed.state === 'not-root') o.print(`skip: hooks (${armed.detail})`)
+        else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
+    }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)
     for (const d of disabled) o.print(`skip: ${d.id} (${d.reason})`)

package/src/hooks/commit-message.ts

@@ -4,9 +4,37 @@
 //
 // mechanical text rules only, so this stays publishable.
 
-export type OffenseKind = 'dash' | 'attribution'
+export type OffenseKind = 'dash' | 'attribution' | 'language'
 export type Offense = { line: number; text: string; kind: OffenseKind; why: string }
 
+/** git surfaces are English, always (identity/writing-voice.md). cheap French
+ *  detector: an accented letter, or two distinct French function words on one
+ *  line. quoted spans are exempt: they carry product copy under discussion
+ *  ("Modification refusée"), not the message's own voice. single quotes stay
+ *  in (they are French apostrophes: stripping l'écran would hide the French).
+ *  `languageAllow` (repo.config hooks) exempts listed words, for proper nouns
+ *  that carry accents without being a language choice. */
+const QUOTED_SPANS = /`[^`\n]*`|"[^"\n]*"|“[^”\n]*”|«[^»\n]*»/g
+const FRENCH_ACCENTS = /[àâçéèêëîïôùûœÀÂÇÉÈÊËÎÏÔÙÛŒ]/
+const FRENCH_STOPWORDS =
+    /\b(?:le|la|les|un|une|des|du|au|aux|et|est|sont|avec|pour|dans|sur|pas|que|qui|ne|se|ce|cette|ces|chaque|tout|toute|tous|toutes|jamais|toujours|mais|donc|sans|sous|vers|chez|depuis|encore|aussi|devient|deviennent|nouvelle|ancienne)\b/gi
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+export function frenchHits(line: string, languageAllow: string[] = []): boolean {
+    let prose = line.replace(QUOTED_SPANS, ' ')
+    for (const word of languageAllow) prose = prose.replace(new RegExp(`(?:^|(?<=[^\\p{L}]))${escapeRe(word)}(?:'s)?(?=$|[^\\p{L}])`, 'giu'), ' ')
+    if (FRENCH_ACCENTS.test(prose)) return true
+    const words = new Set<string>()
+    // an ALL-CAPS token is an acronym (UN, EST, CE), not a French word
+    for (const m of prose.matchAll(FRENCH_STOPWORDS)) {
+        const w = m[0]
+        if (w.length > 1 && w === w.toUpperCase()) continue
+        words.add(w.toLowerCase())
+    }
+    return words.size >= 2
+}
+
 /** trailers and footers that name an assistant, assistant session trailers,
  *  assistant share-domain urls (a session link is a louder tell than any
  *  trailer), plus the robot emoji. the session/url family lists every
@@ -25,7 +53,7 @@ export function stripNonMessage(message: string): string {
  *  `#` comment lines never land in the message and are ignored; a `Revert "…"`
  *  title quotes the reverted subject verbatim and is exempt; a line-start
  *  `- ` bullet is a list marker, not punctuation. */
-export function commitMessageOffenses(message: string): Offense[] {
+export function commitMessageOffenses(message: string, opts?: { languageAllow?: string[] }): Offense[] {
     const offenses: Offense[] = []
     stripNonMessage(message).split('\n').forEach((raw, i) => {
         if (raw.startsWith('#')) return
@@ -37,6 +65,8 @@ export function commitMessageOffenses(message: string): Offense[] {
             offenses.push({ line: i + 1, text: raw, kind: 'dash', why: 'inline " - " separator: same fix' })
         if (AI_ATTRIBUTION.test(raw))
             offenses.push({ line: i + 1, text: raw, kind: 'attribution', why: 'AI attribution: no assistant trailer, session trailer, claude.ai/chatgpt.com url, "Generated with" footer, or robot emoji' })
+        if (frenchHits(raw, opts?.languageAllow))
+            offenses.push({ line: i + 1, text: raw, kind: 'language', why: 'French: git surfaces are English, always (identity/writing-voice.md); quote product copy in "…" or `…` to exempt it' })
     })
     return offenses
 }

package/src/hooks/run-hooks.ts

@@ -3,8 +3,9 @@
 // hand-rolled hooks are invisible to `shipkit check`: a repo reports green
 // while its next commit is already doomed, and nothing can enumerate what
 // the hooks enforce. `shipkit hooks list` answers that without reading shell.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
 import { globalKeywordFile, runLeakGuard } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
@@ -23,13 +24,56 @@ export type HooksConfig = {
     /** staged-path prefixes that may never enter git (local state like
      *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
     blockedPaths?: string[]
-    /** disable a built-in gate, visible in `hooks list`, never silent */
-    disable?: ('leak-guard' | 'commit-message' | 'root-identity')[]
+    /** words the commit-message language gate never counts as French
+     *  (proper nouns that carry accents without being a language choice) */
+    languageAllow?: string[]
+    /** disable a built-in gate, visible in `hooks list`, never silent.
+     *  'commit-language' lifts ONLY the French check, keeping the dash and
+     *  AI-attribution guards armed. */
+    disable?: ('leak-guard' | 'commit-message' | 'root-identity' | 'commit-language')[]
 }
 
 const HOOK_DIR = 'hooks'
 const HOOKS = ['pre-commit', 'commit-msg'] as const
 
+/** how a self-written hook body should invoke shipkit in this repo: the
+ *  repo's own node_modules copy when it has one (survives shim churn, pins
+ *  the repo's version), else the cli that is running right now. */
+export function hookBinInvocation(root: string): string {
+    const local = join(root, 'node_modules/rvlib-shipkit/src/cli.ts')
+    if (existsSync(local)) return 'bun node_modules/rvlib-shipkit/src/cli.ts'
+    const running = join(dirname(fileURLToPath(import.meta.url)), '..', 'cli.ts')
+    const prefix = root.endsWith('/') ? root : root + '/'
+    return running.startsWith(prefix) ? `bun ${running.slice(prefix.length)}` : `bun ${running}`
+}
+
+export type ArmHooksResult = { state: 'armed' | 'current' | 'foreign' | 'no-git' | 'not-root' | 'failed'; detail: string }
+
+/** self-arming: a repo.config with dark commit gates is the half-wired state
+ *  that let a whole drill session commit ungated (2026-08-04). 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
+ *  core.hooksPath is respected and named, and only the work-tree ROOT may
+ *  arm (a subdir would set the parent's hooksPath onto a dir that does not
+ *  exist there, disarming the parent's gates). */
+export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
+    const top = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], { cwd: root })
+    if (top.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const topDir = top.stdout.toString().trim()
+    try {
+        if (realpathSync(topDir) !== realpathSync(root)) return { state: 'not-root', detail: `work tree root is ${topDir}, not here` }
+    } catch {
+        return { state: 'no-git', detail: 'work tree root unresolvable' }
+    }
+    const p = Bun.spawnSync(['git', 'config', 'core.hooksPath'], { cwd: root })
+    const current = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+    if (current !== '' && current !== HOOK_DIR) return { state: 'foreign', detail: `core.hooksPath=${current}, foreign, left alone` }
+    if (current === HOOK_DIR && HOOKS.every((h) => existsSync(join(root, HOOK_DIR, h)))) return { state: 'current', detail: 'hooks already armed' }
+    const r = installHooks(root, hookBinInvocation(root), config.hooks?.keywordFile)
+    if (r.note.startsWith('WARN')) return { state: 'failed', detail: r.note }
+    return { state: 'armed', detail: `wrote ${r.written.join(', ') || 'nothing'}, ${r.note}` }
+}
+
 /** wire `core.hooksPath` and write the two hook bodies. Idempotent.
  *  `keywordFile` = the repo's configured leak-guard file, seeding target. */
 export function installHooks(root: string, binInvocation: string, keywordFile?: string): { written: string[]; note: string } {
@@ -149,9 +193,11 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
     const out: GateOutcome[] = []
     const message = readFileSync(messageFile, 'utf8')
     if (!(h.disable ?? []).includes('commit-message')) {
-        const offenses = commitMessageOffenses(message)
+        const languageOff = (h.disable ?? []).includes('commit-language')
+        const offenses = commitMessageOffenses(message, { languageAllow: h.languageAllow })
+            .filter((o) => o.kind !== 'language' || !languageOff)
         out.push(offenses.length === 0
-            ? { id: 'commit-message', ok: true, lines: ['ok: commit message clean (no dash punctuation, no AI attribution)'] }
+            ? { id: 'commit-message', ok: true, lines: [`ok: commit message clean (no dash punctuation, no AI attribution${languageOff ? '' : ', English'})`] }
             : {
                 id: 'commit-message',
                 ok: false,
@@ -192,7 +238,7 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
-        `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution`,
+        `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution + French${off.has('commit-language') ? ' (commit-language DISABLED by config)' : ''}`,
         `commit-msg  leak-guard${leakState} — the message text`,
         ...(h.commitMsg ?? []).map((c) => `commit-msg  ${c.id} — ${c.cmd.join(' ')}`),
     ]

package/src/init-repo.ts

@@ -35,20 +35,24 @@ export default defineRepo({
 export type InitOpts = {
     /** in-repo-source consumers: path to shipkit's cli.ts — scripts become `bun <path> <cmd>` instead of `shipkit <cmd>` */
     bin?: string
+    /** report sink, default console.log (startRepo passes console.error: its
+     *  stdout contract is the resolved dir alone) */
+    print?: (line: string) => void
 }
 
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
+    const p = opts.print ?? console.log
     const configPath = join(root, 'repo.config.ts')
     if (existsSync(configPath)) {
-        console.log(`skip: repo.config.ts already exists`)
+        p(`skip: repo.config.ts already exists`)
         // adoption path: re-running init on an existing repo still converges
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
         const g = await gitignorePolicy.fix!({ root, config: cfg })
-        console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+        p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         const mh = reportToMotherhome(root, cfg)
-        if (mh.note != null) console.log(mh.note)
+        if (mh.note != null) p(mh.note)
         return 0
     }
     const pkgPath = join(root, 'package.json')
@@ -57,7 +61,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const pkg = JSON.parse(pkgRaw) as { name?: string; scripts?: Record<string, string> }
     const name = pkg.name ?? 'my-repo'
     writeFileSync(configPath, CONFIG_TEMPLATE(name))
-    console.log('ok: repo.config.ts created')
+    p('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
     pkg.scripts ??= {}
     let added = 0
@@ -69,32 +73,32 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
         if (k === 'test' && !hasTestFiles(root)) continue
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
-        else if (pkg.scripts[k] !== v) console.log(`skip: package.json script '${k}' exists — left untouched`)
+        else if (pkg.scripts[k] !== v) p(`skip: package.json script '${k}' exists — left untouched`)
     }
     if (added > 0) {
         writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
-        console.log(`ok: ${added} package.json script(s) added`)
+        p(`ok: ${added} package.json script(s) added`)
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
     const g = await gitignorePolicy.fix!({ root, config: defineRepo({ name }) })
-    console.log(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
+    p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     // show what the gate actually is — a thin floor must be seen at init
     // time, not discovered after a bad commit slipped through
     const floor = resolveFloor(defineRepo({ name }), root)
-    for (const t of floor.tasks) console.log(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
-    for (const u of floor.unfilled) console.log(`skip: ${u.id} (${u.reason})`)
+    for (const t of floor.tasks) p(`ok: floor ${t.id} ← ${floor.sources[t.id] ?? 'unknown'}`)
+    for (const u of floor.unfilled) p(`skip: ${u.id} (${u.reason})`)
     // every verb comes from the `shipkit` bin — dead on arrival unless the
     // package is actually installed (bunx runs without adding the dep)
     if (opts.bin == null) {
         try {
             Bun.resolveSync('rvlib-shipkit', root)
         } catch {
-            console.log('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
-            console.log('      fix: bun add -d rvlib-shipkit')
+            p('WARN rvlib-shipkit not installed here — the scripts above call its bin and will exit 127')
+            p('      fix: bun add -d rvlib-shipkit')
         }
     }
-    console.log('next: fill venues/social in repo.config.ts, then `shipkit ci`')
-    console.log('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
+    p('next: fill venues/social in repo.config.ts, then `shipkit ci`')
+    p('next: identity+assets — mint .rv-identity/brand.ts + .rv-assets/kit.ts, `shipkit assets identity` (the identity contract expects public/ favicon+og+logo)')
     return 0
 }

package/src/start-repo.ts

@@ -7,6 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
+import { initRepo } from './init-repo.ts'
 
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
@@ -19,7 +20,7 @@ export type StartOpts = {
     skip?: string[]
 }
 
-export function startRepo(name: string, opts: StartOpts = {}): number {
+export async function startRepo(name: string, opts: StartOpts = {}): Promise<number> {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
         console.error(`FAIL: bad repo name '${name}' — letters/digits/._- only, no leading dot, no slashes`)
         return 2
@@ -55,6 +56,21 @@ export function startRepo(name: string, opts: StartOpts = {}): number {
             }
         }
     }
+    // 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.
+    // --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`)
+        }
+    }
     console.log(dir)
     return 0
 }