rvlib-shipkit 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.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_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_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'],
         ],
     })
 

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,15 @@ 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})`)
+        else if (armed.state === 'foreign') o.print(`skip: hooks (${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

@@ -5,6 +5,7 @@
 // the hooks enforce. `shipkit hooks list` answers that without reading shell.
 import { existsSync, mkdirSync, readFileSync, 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,46 @@ 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'; detail: string }
+
+/** self-arming: a repo.config with dark commit gates is the half-wired state
+ *  that let a whole drill session commit ungated (2026-08-04). Idempotent,
+ *  and a FOREIGN core.hooksPath is respected and named, never taken. */
+export function armHooks(root: string, config: RepoConfig): ArmHooksResult {
+    const inRepo = Bun.spawnSync(['git', 'rev-parse', '--is-inside-work-tree'], { cwd: root })
+    if (inRepo.exitCode !== 0) return { state: 'no-git', detail: 'not a git repo' }
+    const 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` }
+    const r = installHooks(root, hookBinInvocation(root), config.hooks?.keywordFile)
+    if (r.note.startsWith('WARN')) return { state: 'foreign', detail: r.note }
+    if (r.written.length === 0 && current === HOOK_DIR) return { state: 'current', detail: 'hooks already armed' }
+    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 +183,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 +228,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/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.
+    if (!existsSync(join(dir, 'repo.config.ts'))) {
+        if (existsSync(join(dir, 'package.json'))) {
+            // initRepo reports on stdout, but start's stdout contract is THE
+            // DIR ONLY (a sourced alias cd's to it) — reroute to stderr here
+            const realLog = console.log
+            console.log = ((...a: unknown[]) => console.error(...a)) as typeof console.log
+            try { await initRepo(dir, {}) } finally { console.log = realLog }
+        } else {
+            console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
+        }
+    }
     console.log(dir)
     return 0
 }