rvlib-shipkit 0.11.0 → 0.14.0

package/src/contracts/manifests/identity.contract.ts

@@ -13,7 +13,7 @@ export default defineContract({
     artifacts: [
         file('.rv-identity/brand.ts'),
         png('public/favicon.png', 512, 512),
-        png('public/og.png', 1200, 630),
+        png('public/og.png', 1200, 630, { atLeast: true }),
         glob('public/logo.*', { min: 1 }),
     ],
 })

package/src/contracts/manifests/itch.contract.ts

@@ -1,5 +1,7 @@
 // normative WHAT for .rv-itch/ — the WHY + workflow live in the sibling page.
-import { defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { custom, defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
 
 export default defineContract({
     venue: 'itch',
@@ -10,7 +12,22 @@ export default defineContract({
     artifacts: [
         // one AI-disclosure wording everywhere — page.md is its canonical home
         md('.rv-itch/page.md', { mustContain: ['## AI disclosure'] }),
-        png('.rv-itch/cover.png', 630, 500),
+        // every field of itch's create-project form, answered and ready to
+        // paste — the listing is a browser-only act, so the artifact IS the
+        // handoff (references/listing.template.md is the fill-in copy)
+        md('.rv-itch/listing.md', { mustContain: ['## Title', '## Short description or tagline', '## Classification', '## Genre', '## Tags', '## Visibility'] }),
+        // headings alone would pass the TEMPLATE copied in verbatim, and this
+        // file exists to be pasted with no decision left in it (field
+        // 2026-07-27: a reviewer proved `cp template listing.md` went green)
+        custom('.rv-itch/listing.md answered', (env) => {
+            const p = join(env.root, '.rv-itch/listing.md')
+            if (!existsSync(p)) return []
+            const left = [...readFileSync(p, 'utf8').matchAll(/<[a-z][^<>\n]{2,60}>/g)].map((m) => m[0])
+            return left.length === 0 ? [] : [`.rv-itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`]
+        }),
+        // itch DISPLAYS 630x500 and accepts larger — an exact-size rule would
+        // block a release over a better cover (audit 2026-07-27)
+        png('.rv-itch/cover.png', 630, 500, { atLeast: true }),
         glob('.rv-itch/screenshots/*.png', { min: 3 }),
     ],
 })

package/src/contracts/run-contracts.ts

@@ -1,6 +1,9 @@
 // contract fulfillness alone, fast and filesystem-only. Plain module
 // behind cmd_Contracts; venue deploy scripts run it before any upload.
-import { activeContracts, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { contractsFulfillness } from '../rules/SK002-contracts-fulfillness.ts'
+import { activeContracts, applyContractsResult, contractsConfigFrom } from './apply-contracts.ts'
 import { evaluateContracts } from './contracts-engine.ts'
 import { formatLine } from '../core/wire.ts'
 
@@ -27,7 +30,9 @@ export async function runContracts(root: string, o: ContractsOpts = {}): Promise
         return r.exitCode
     }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
-    for (const l of r.lines) print(formatLine(l, color))
-    if (r.lines.length === 0) print('ok: no contracts apply (nothing declared, nothing detected)')
+    // same SK002-tagged rendering as `shipkit check` and the ci task
+    const t = new CheckCtx(new Map())
+    applyContractsResult(t, r, contractsFulfillness)
+    for (const l of t.lines) print(formatLine(l, color))
     return r.exitCode
 }

package/src/core/canonical-scripts.ts

@@ -0,0 +1,46 @@
+// The canonical package.json script bodies for a shipkit repo — vocabulary
+// owned by meta/rv-conventions/package-json.md. ONE source: `shipkit init`
+// scaffolds from it and rule SK001's autofix repairs from it.
+export type ScriptStyle = {
+    /** in-repo-source consumers: path to shipkit's cli.ts — bodies become `bun <path> <cmd>` */
+    bin?: string
+}
+
+export function canonicalBodies(opts: ScriptStyle = {}): Record<string, string> {
+    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
+    return {
+        ci: run('ci'),
+        check: run('check'),
+        contracts: run('contracts'),
+        tui: run('tui'),
+        mv: run('mv'),
+        // hub runs in WATCH mode (house default 2026-07-23): lib/config edits
+        // restart the server live; the npm shim can't watch, the source path can
+        hub: `bun --watch ${opts.bin ?? 'node_modules/rvlib-shipkit/src/cli.ts'} serve`,
+        // baseline `test` is universal — lint/fmt bodies are stack-specific,
+        // the scaffold pages own those
+        test: 'bun test',
+    }
+}
+
+// conditional canon (bodies stated by the vocabulary page) — keyed by the
+// SK001 requirement name; requirements with no canonical body (assets,
+// comfy:up) are deliberately absent: a fixer must not invent one
+export function conditionalBodies(opts: ScriptStyle = {}): Record<string, string> {
+    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
+    return {
+        'up': './deploy.sh',
+        'asks': run('asks'),
+        'assets:identity': run('assets identity'),
+    }
+}
+
+// recover the consumption style from existing scripts: any shipkit command
+// already running `bun <path>/cli.ts <cmd>` fixes the style for new bodies
+export function inferBin(scripts: Record<string, string>): string | undefined {
+    for (const body of Object.values(scripts)) {
+        const m = body.match(/^bun (?:--watch )?(\S+cli\.ts) /)
+        if (m != null && m[1] !== 'node_modules/rvlib-shipkit/src/cli.ts') return m[1]
+    }
+    return undefined
+}

package/src/core/check-suite.ts

@@ -61,8 +61,8 @@ export class CheckSuite {
         this.onResult = opts.onResult
     }
 
-    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; logic: Logic }): void {
-        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, logic: spec.logic })
+    addCheck(spec: { name: string; remainValidFor?: string | number; version?: number; cacheExtra?: () => string; logic: Logic }): void {
+        this.runners.push({ name: spec.name, ttlMs: spec.remainValidFor != null ? parseDuration(spec.remainValidFor) : 0, version: spec.version ?? 1, prep: spec.cacheExtra != null ? () => ({ cacheExtra: spec.cacheExtra!() }) : undefined, logic: spec.logic })
     }
 
     defineRequiredTool(name: string, opts: { candidates?: string[]; probe?: { args: string[]; expect?: RegExp }; fix: string }): void {
@@ -161,7 +161,10 @@ export class CheckSuite {
             this.onResult?.(r.name, { lines: t.lines, status: t.failed ? 'fail' : t.warned ? 'warn' : 'pass', cached: false })
             if (t.failed) anyFail = true
             if (r.ttlMs > 0) {
-                if (!t.failed && !t.warned) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }
+                // a skip line is an UNKNOWN, not a clean pass — replaying
+                // "registry unreachable" for a TTL asserts a dead network as
+                // fact long after it recovered (review find 2026-07-26)
+                if (!t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }
                 // a WARN/FAIL evicts the stale pass — a later run must re-probe,
                 // not replay an ok recorded before the breakage
                 else if (entry != null) { delete cache[r.name]; cacheDirty = true }

package/src/core/locked-write.ts

@@ -0,0 +1,39 @@
+// ONE file-lock + atomic-write concern (extracted from write-status when
+// motherhome became the second multi-writer): the lock spans a caller's
+// whole read-modify-write, the write lands via tmp + rename so a killed
+// process can never leave a torn file, and the loser of a race SKIPS —
+// never corrupts, never blocks.
+import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { basename, dirname, join } from 'path'
+
+// a writer that died without unlocking must not wedge the file forever
+const LOCK_STALE_MS = 120_000
+
+export type LockOutcome<T> = { ok: true; value: T } | { ok: false; warn: string }
+
+export function withFileLock<T>(path: string, fn: () => T): LockOutcome<T> {
+    const lockPath = `${path}.lock`
+    const grab = (): boolean => {
+        try { writeFileSync(lockPath, String(process.pid), { flag: 'wx' }); return true } catch { return false }
+    }
+    if (!grab()) {
+        let stale = false
+        try { stale = Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS } catch {
+            // lock vanished between grab and stat — the racing writer just
+            // finished; still skip this round rather than fight over it
+        }
+        if (stale) rmSync(lockPath, { force: true })
+        if (!stale || !grab()) return { ok: false, warn: `${path} locked by another writer — skipped this round` }
+    }
+    try {
+        return { ok: true, value: fn() }
+    } finally {
+        rmSync(lockPath, { force: true })
+    }
+}
+
+export function atomicWrite(path: string, content: string): void {
+    const tmpPath = join(dirname(path), `.${basename(path)}.tmp-${process.pid}`)
+    writeFileSync(tmpPath, content)
+    renameSync(tmpPath, path)
+}

package/src/core/motherhome.ts

@@ -0,0 +1,87 @@
+// Report to the motherhome — upsert this repo's row into the docsBase
+// wiki's `build/shipkit/local-projects.md`, when that page ALREADY EXISTS
+// on this disk. The lib NEVER creates the page and never writes into a
+// relative or URL docsBase: the page is a tracked wiki file, so a real
+// docs checkout has it, and a consumer that merely set docsBase as a
+// fix-pointer prefix must never find surprise files in its docs tree.
+// The whole read-modify-write runs under the shared file lock
+// (core/locked-write) — concurrent reporters never lose rows or tear the
+// file; the loser skips and self-heals on its next run. Rows whose repo
+// path no longer exists are pruned on every write. Churn control: a row
+// rewrites only when its DATA changes or its last-seen day is older than
+// 7 days. Never fails the calling command.
+import { existsSync, readFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, resolve } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { atomicWrite, withFileLock } from './locked-write.ts'
+
+const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
+const END = '<!-- <<< shipkit local-projects -->'
+const STALE_DAYS = 7
+
+type Row = { name: string; root: string; version: string; mode: string; seen: string }
+
+const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
+
+const parseRow = (line: string): Row | null => {
+    const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
+    return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
+}
+
+function libVersion(): string {
+    try { return (JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}
+
+// how this repo consumes the lib — `?` on an unreadable package.json (a
+// read failure must never be rendered as the fact 'path')
+function consumptionMode(root: string): string {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        const spec = { ...pkg.dependencies, ...pkg.devDependencies }['rvlib-shipkit']
+        if (spec == null) return 'path'
+        if (spec.startsWith('link:')) return 'link'
+        if (spec.startsWith('file:')) return 'file'
+        return 'npm'
+    } catch { return '?' }
+}
+
+export type MotherhomeOutcome = { wrote: boolean; note?: string }
+
+export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
+    try {
+        if (config.docsBase == null) return { wrote: false }
+        const base = config.docsBase.startsWith('~/') ? join(homedir(), config.docsBase.slice(2)) : config.docsBase
+        // absolute local paths only — a relative docsBase would resolve
+        // against CWD, a URL is a display prefix
+        if (!base.startsWith('/')) return { wrote: false }
+        const page = join(base, 'build/shipkit/local-projects.md')
+        if (!existsSync(page)) return { wrote: false }
+
+        const mode = consumptionMode(root)
+        // source-consumed code is not the published release its version
+        // string names — disclose it
+        const version = mode === 'npm' ? libVersion() : `${libVersion()}+src`
+        const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
+
+        const r = withFileLock(page, (): MotherhomeOutcome => {
+            const lines = readFileSync(page, 'utf8').split('\n')
+            const b = lines.indexOf(BEGIN)
+            const e = lines.indexOf(END)
+            if (b === -1 || e === -1 || e < b) return { wrote: false, note: `WARN motherhome upsert skipped — markers missing/corrupted in ${page}` }
+            const rows = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
+            const cur = rows.find((row) => row.root === me.root)
+            const dataSame = cur != null && cur.name === me.name && cur.version === me.version && cur.mode === me.mode
+            const fresh = cur != null && (Date.parse(today) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
+            if (dataSame && fresh) return { wrote: false }
+            // prune rows for repos that no longer exist at their recorded path
+            const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
+            atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
+            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})` }
+        })
+        // lock lost to a racing reporter — self-heals on the next run
+        return r.ok ? r.value : { wrote: false }
+    } catch (err) {
+        return { wrote: false, note: `WARN motherhome upsert failed (${String(err).slice(0, 120)}) — registry may be stale` }
+    }
+}

package/src/core/run-check.ts

@@ -8,9 +8,10 @@ import { join, relative } from 'path'
 import { CheckSuite, type CheckOutcome } from './check-suite.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
-import { activeContracts, applyContractsResult, contractsConfigFrom, loadRepoConfig } from '../repo-config.ts'
-import { evaluatePackageJson } from './package-json-check.ts'
-import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { reportToMotherhome } from './motherhome.ts'
+import { RULES } from '../rules/rule-registry.ts'
+import { runRuleLint } from '../rules/rule.ts'
 import { formatLine, parseWireOutput } from './wire.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -22,6 +23,8 @@ const CHECK_TIMEOUT_MS = 120_000
 export type CheckOpts = {
     json?: boolean
     fresh?: boolean
+    /** report-only for self-maintaining rules (SK005 never touches package.json) */
+    frozen?: boolean
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
     /** line sink — commands pass their context stream; defaults to console */
@@ -33,20 +36,24 @@ export type CheckOpts = {
 export async function runCheck(root: string, o: CheckOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const c = await loadRepoConfig(root)
+    // env carries the flags to child checks — restored after the run so a
+    // long-lived caller (doctor, TUI, hub) is never poisoned by one
+    // fresh/frozen invocation
+    const prevFresh = process.env.SHIPKIT_FRESH
+    const prevFrozen = process.env.SHIPKIT_FROZEN
     if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
+    if (o.frozen === true) process.env.SHIPKIT_FROZEN = '1'
     const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
-    suite.addCheck({
-        name: 'contracts',
-        logic: async (t) => {
-            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
-        },
-    })
-    // built-in shape probe (meta/rv-conventions/package-json.md) — doctor
-    // surface only, deliberately absent from the ci gate
-    suite.addCheck({
-        name: 'package.json',
-        logic: (t) => evaluatePackageJson(t, root, c),
-    })
+    // built-in SK rules (rules/rule-registry.ts) — id-tagged, crash-safe,
+    // fix-pointer floor (rules/rule.ts runRuleLint owns the semantics);
+    // doctor surface only, deliberately absent from the ci gate
+    for (const rule of RULES)
+        suite.addCheck({
+            name: rule.title,
+            remainValidFor: rule.ttl,
+            cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
+            logic: (t) => runRuleLint(rule, t, { root, config: c }),
+        })
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
         ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
@@ -69,12 +76,18 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
         })
     }
     const r = await suite.execute()
+    if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
+    if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
+    // report to the motherhome (docsBase wiki on this disk) — never fails
+    // the check, notes only when it wrote or broke
+    const mh = reportToMotherhome(root, c)
     const statusOutcome = o.status !== false
         ? writeStatus(root, { name: c.name, command: 'shipkit check', lines: r.lines.map((l) => formatLine(l, false)), exitCode: r.exitCode })
         : null
     if (o.json === true) { print(JSON.stringify(r)); return r.exitCode }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of r.lines) print(formatLine(l, color))
+    if (mh.note != null) print(mh.note)
     if (statusOutcome != null && !statusOutcome.written) print(`WARN ${statusOutcome.warn}`)
     return r.exitCode
 }

package/src/core/run-ci.ts

@@ -5,6 +5,7 @@
 // atomic + lock) unless status:false.
 import { join } from 'path'
 import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { reportToMotherhome } from './motherhome.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -44,6 +45,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         onTaskFinish: o.onTaskFinish,
     })
     const code = summary.ok ? 0 : 1
+    // motherhome row (docsBase wiki on this disk) — never affects the gate
+    const mh = reportToMotherhome(root, c)
+    if (mh.note != null) print(mh.note)
     if (o.status !== false) {
         const st = writeStatus(root, { name: c.name, command: 'shipkit ci', lines: collected, exitCode: code })
         if (!st.written) print(`WARN ${st.warn}`)

package/src/core/write-status.ts

@@ -1,11 +1,11 @@
 // THE STATUS.md writer — every repo gets one (O4, one-runner GO
 // 2026-07-22): timestamp header + verdict + fenced compact render, the
-// shape rv-doctor pioneered. Atomic (tmp file + rename) and lock-guarded:
+// shape rv-doctor pioneered. Atomic + lock-guarded via core/locked-write:
 // concurrent runners never interleave — the loser skips with a WARN
 // outcome, never corrupts the file.
 
-import { renameSync, rmSync, statSync, writeFileSync } from 'fs'
 import { join } from 'path'
+import { atomicWrite, withFileLock } from './locked-write.ts'
 
 export type StatusInput = {
     /** repo name — headline */
@@ -20,25 +20,10 @@ export type StatusInput = {
 export type StatusOutcome = { written: boolean; warn?: string }
 
 const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '')
-// a runner that died without unlocking must not wedge STATUS.md forever
-const LOCK_STALE_MS = 120_000
 
 export function writeStatus(root: string, s: StatusInput): StatusOutcome {
-    const lockPath = join(root, 'STATUS.md.lock')
-    const grab = (): boolean => {
-        try { writeFileSync(lockPath, String(process.pid), { flag: 'wx' }); return true } catch { return false }
-    }
-    if (!grab()) {
-        let stale = false
-        try { stale = Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS } catch {
-            // lock vanished between grab and stat — the racing writer just
-            // finished; still skip this round rather than fight over it
-        }
-        if (stale) rmSync(lockPath, { force: true })
-        if (!stale || !grab())
-            return { written: false, warn: `STATUS.md locked by another runner (${lockPath}) — skipped this write` }
-    }
-    try {
+    const target = join(root, 'STATUS.md')
+    const r = withFileLock(target, () => {
         const clean = s.lines.map(stripAnsi)
         const fails = clean.filter((l) => l.startsWith('FAIL')).length
         const warns = clean.filter((l) => l.startsWith('WARN')).length
@@ -60,11 +45,7 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
 ${clean.join('\n').trim()}
 \`\`\`
 `
-        const tmpPath = join(root, `.STATUS.md.tmp-${process.pid}`)
-        writeFileSync(tmpPath, body)
-        renameSync(tmpPath, join(root, 'STATUS.md'))
-        return { written: true }
-    } finally {
-        rmSync(lockPath, { force: true })
-    }
+        atomicWrite(target, body)
+    })
+    return r.ok ? { written: true } : { written: false, warn: `STATUS.md locked by another runner — skipped this write` }
 }

package/src/init-repo.ts

@@ -7,7 +7,10 @@
 // by path instead of from node_modules.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { defineRepo, resolveFloor } from './repo-config.ts'
+import { canonicalBodies } from './core/canonical-scripts.ts'
+import { reportToMotherhome } from './core/motherhome.ts'
+import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
+import { gitignorePolicy } from './rules/SK004-gitignore-policy.ts'
 
 const CONFIG_TEMPLATE = (name: string): string => `import { defineRepo } from 'rvlib-shipkit'
 
@@ -16,6 +19,9 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // the mandated reviewer agent type (rule SK008) — uncomment with YOUR
+    // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
+    // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
     // health checks: no config — drop a <name>.check.ts file anywhere,
     // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
 })
@@ -28,7 +34,18 @@ export type InitOpts = {
 
 export async function initRepo(root: string, opts: InitOpts = {}): Promise<number> {
     const configPath = join(root, 'repo.config.ts')
-    if (existsSync(configPath)) { console.log(`skip: repo.config.ts already exists`); return 0 }
+    if (existsSync(configPath)) {
+        console.log(`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'}`)
+        const mh = reportToMotherhome(root, cfg)
+        if (mh.note != null) console.log(mh.note)
+        return 0
+    }
     const pkgPath = join(root, 'package.json')
     if (!existsSync(pkgPath)) { console.error('FAIL: no package.json here — run from the repo root'); return 1 }
     const pkgRaw = readFileSync(pkgPath, 'utf8')
@@ -38,23 +55,22 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     console.log('ok: repo.config.ts created')
     const indent = pkgRaw.match(/^(\s+)"/m)?.[1] ?? '  '
     pkg.scripts ??= {}
-    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
     let added = 0
-    // canonical script NAME → shipkit command (hub runs `shipkit serve`) —
-    // vocabulary owned by meta/rv-conventions/package-json.md
-    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve', mv: 'mv' } as const
-    for (const [k, cmd] of Object.entries(CANONICAL)) {
-        const v = run(cmd)
+    // canonical script bodies — ONE source (core/canonical-scripts.ts),
+    // shared with rule SK001's autofix; vocabulary owned by
+    // meta/rv-conventions/package-json.md
+    for (const [k, v] of Object.entries(canonicalBodies({ bin: opts.bin }))) {
         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`)
     }
-    // baseline `test` is universal (bun test) — lint/fmt bodies are
-    // stack-specific, the scaffold pages own those
-    if (pkg.scripts['test'] == null) { pkg.scripts['test'] = 'bun test'; added++ }
     if (added > 0) {
         writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
         console.log(`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'}`)
     // 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)