rvlib-shipkit 0.10.0 → 0.13.0

package/src/collections/providers.ts

@@ -0,0 +1,275 @@
+// The built-in collection providers — each one REPLACED an attentionCollector
+// guard (the collector is gone; never reintroduce a parallel projection).
+// Behaviors preserved by name: per-source failure isolation (projectNeeds
+// guards per collection), the identity self-heal before surfacing, and the
+// asks READ path never minting asks/ on a repo without one. Dedup doctrine
+// (his correction 2026-07-23): dedup = acted-on once, NEVER hidden — an
+// ask-covered missing cred still shows RED in secrets with a pointer to the
+// ask; verbs and pings stay with the ask. Each wire line of STATUS.md lives
+// in exactly ONE collection: cred probe lines in secrets, everything else
+// in repo health.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { isStale } from '../assets/gen/derived.ts'
+import { allAssets, mediaOf, type ResolvedKit } from '../assets/kit-config.ts'
+import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
+import { healIdentity } from '../assets/run-assets.ts'
+import { doneAsks, openAsks } from '../asks/asks-queue.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { parseWireOutput } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { activeContracts, contractsConfigFrom } from '../contracts/apply-contracts.ts'
+import type { Collection, Instance } from './collection-types.ts'
+import { socialPostsCollection } from './posts.ts'
+
+const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? 'asks')
+// read path must not mint an asks/ dir (listAsks mkdirs on read)
+const openAsksSafe = (root: string, c: RepoConfig): ReturnType<typeof openAsks> => {
+    const dir = askDirOf(root, c)
+    return existsSync(dir) ? openAsks(dir) : []
+}
+
+const CRED_LINE = /cred ([a-z0-9-]+\/[a-z0-9-]+\/[a-z0-9-]+) missing/
+
+/** STATUS.md's check output, regrouped: one item per ok/WARN/FAIL wire line
+ *  with its indented fix: pointers riding along. The writer's markdown
+ *  wrapper (comment, title, verdict, fences) parses as notes and drops out. */
+type WireItem = { kind: 'ok' | 'warn' | 'fail'; text: string; fixes: string[] }
+const statusWire = (root: string): WireItem[] => {
+    const p = join(root, 'STATUS.md')
+    if (!existsSync(p)) return []
+    const items: WireItem[] = []
+    for (const l of parseWireOutput(readFileSync(p, 'utf8'))) {
+        if (l.kind === 'ok' || l.kind === 'warn' || l.kind === 'fail') items.push({ kind: l.kind, text: l.text, fixes: [] })
+        else if ((l.kind === 'fix-warn' || l.kind === 'fix-fail') && items.length > 0) items[items.length - 1]!.fixes.push(l.text)
+    }
+    return items
+}
+
+/** wire lines re-rendered as a fenced block for an instance's md */
+const wireMd = (lines: string[]): string => `\`\`\`\n${lines.join('\n')}\n\`\`\``
+
+export function asksCollection(root: string, c: RepoConfig): Collection {
+    return {
+        id: 'asks',
+        title: 'asks',
+        media: 'text',
+        list: async () => {
+            const rel = c.asks?.dir ?? 'asks'
+            const open = openAsksSafe(root, c).map((a): Instance => ({
+                id: `ask:${a.file}`,
+                text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                severity: 'red' as const,
+                verbs: ['done' as const, 'paste-proof' as const],
+                file: `${rel}/${a.file}`,
+                md: askMd(join(root, rel, a.file)),
+                remarks: lastRemarks(join(root, rel, a.file)),
+            }))
+            // the done/ archive rides along QUIET (no severity) — past answers
+            // stay consultable and remarkable; newest first, after every open ask
+            const done = doneAsks(askDirOf(root, c)).map((a): Instance => ({
+                id: `ask:done/${a.file}`,
+                text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                file: `${rel}/done/${a.file}`,
+                md: askMd(join(root, rel, 'done', a.file)),
+                remarks: lastRemarks(join(root, rel, 'done', a.file)),
+            }))
+            return [...open, ...done]
+        },
+    }
+}
+
+// a card, not a document dump — the cut is loud (…) so a clamped card never
+// passes for the whole truth file
+const MD_CAP = 4000
+
+/** the ask file's markdown body: frontmatter stripped, trimmed, capped */
+const askMd = (path: string): string | undefined => {
+    if (!existsSync(path)) return undefined
+    const body = readFileSync(path, 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '').trim()
+    if (body === '') return undefined
+    // code-point slice — a UTF-16 cut can strand half a surrogate pair
+    return body.length > MD_CAP ? `${[...body].slice(0, MD_CAP).join('')}…` : body
+}
+
+/** his latest dated remark lines from a file's tail — the boot briefing */
+const lastRemarks = (path: string, max = 3): string[] | undefined => {
+    if (!existsSync(path)) return undefined
+    const lines = readFileSync(path, 'utf8').split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2}: /.test(l))
+    return lines.length > 0 ? lines.slice(-max) : undefined
+}
+
+/** repo-declared secrets (repo.config `creds:`) + cred FAIL lines from
+ *  STATUS.md — the tile carries the mint artifact as data. EVERY declared
+ *  cred is listed. Missing + unclaimed = red with the set verb + artifact;
+ *  missing + ask-covered = STILL red (never hidden), no verbs — the text
+ *  points at the ask that owns the action. The probe FAIL line (+ its fix:
+ *  pointers) rides the instance's md, never a health line.
+ *  Declared-and-present creds show QUIET, the vault is consultable. */
+export function credsCollection(root: string, c: RepoConfig): Collection {
+    return {
+        id: 'creds',
+        title: 'secrets',
+        media: 'pointer',
+        list: async () => {
+            const rel = c.asks?.dir ?? 'asks'
+            const asks = openAsksSafe(root, c)
+            const coveringAsk = (name: string): { file: string } | undefined =>
+                asks.find((a) => a.title.toLowerCase().includes(name.split('/')[1] ?? name))
+            // only a FAIL probe proves missing — a WARN/narrative mention never reds
+            const probes = new Map<string, WireItem>()
+            for (const i of statusWire(root)) {
+                if (i.kind !== 'fail') continue
+                const name = i.text.match(CRED_LINE)?.[1]
+                if (name != null && !probes.has(name)) probes.set(name, i)
+            }
+            const out: Instance[] = []
+            for (const [name, probe] of probes) {
+                const decl = (c.creds ?? []).find((d) => d.name === name)
+                const md = wireMd([`FAIL: ${probe.text}`, ...probe.fixes.map((f) => `fix: ${f}`)])
+                const ask = coveringAsk(name)
+                if (ask != null)
+                    // dedup = acted-on once, never hidden: the ask keeps the
+                    // verbs and the ping; the cred still shows RED here
+                    out.push({
+                        id: `cred:${name}`,
+                        text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''} — ask ${rel}/${ask.file} owns this`,
+                        severity: 'red',
+                        md,
+                        askOwned: true,
+                    })
+                else out.push({ ...credInstance(name, c.credsCommand, decl), md })
+            }
+            // every declared cred not proven missing is a quiet instance —
+            // present secrets carry no severity and no copy command (nothing
+            // to run), just the mint pointer when one is declared
+            for (const d of c.creds ?? []) {
+                if (probes.has(d.name)) continue
+                out.push({
+                    id: `cred:${d.name}`,
+                    text: `${d.name}${d.service != null ? ` — ${d.service}` : ''}`,
+                    artifact: d.mintUrl != null ? { url: d.mintUrl } : undefined,
+                })
+            }
+            return out
+        },
+    }
+}
+
+// the store command is repo config DATA (`credsCommand` template) — the lib
+// never names any particular secret manager
+const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { service?: string; mintUrl?: string; steps?: string[] }): Instance => ({
+    id: `cred:${name}`,
+    text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''}`,
+    severity: 'red',
+    artifact: { copy: cmdTemplate?.replaceAll('{name}', name), url: decl?.mintUrl, steps: decl?.steps },
+    verbs: ['set'],
+})
+
+/** media kit instances — BROWSE-ALL: every kit asset is an instance (the
+ *  page shows everything that exists; healthy = no severity, dim tile).
+ *  Identity self-heals BEFORE surfacing; manual with nothing uploaded =
+ *  red (provide); rolls with no pick = yellow (a default exists, taste
+ *  pending — auto-pick-first is blessed); stale = yellow. */
+export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal: typeof healIdentity = healIdentity): Collection {
+    return {
+        id: 'media',
+        title: 'assets',
+        media: 'image',
+        list: async () => {
+            const idn = await heal(root)
+            const out: Instance[] = []
+            if (idn.state === 'blocked')
+                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, severity: 'red', href: '/#identity-logo', verbs: ['pick'] })
+            if (kit == null) return out
+            const notes = assetNotes(root)
+            for (const f of allAssets(kit)) {
+                const dir = assetDir(join(root, kit.workspace), f.asset.id)
+                const rolls = listRolls(dir)
+                const manual = f.kind.generate.backend === 'manual'
+                const base: Instance = {
+                    id: `media:${f.asset.id}`,
+                    text: f.asset.id,
+                    href: `/#${f.asset.id}`,
+                    // image kinds only — /api/thumb serves raw roll bytes, and
+                    // an mp3 inside an <img> is a broken glyph on every tile
+                    img: rolls.length > 0 && mediaOf(f.kind) === 'image' ? `/media/api/thumb?id=${encodeURIComponent(f.asset.id)}` : undefined,
+                    file: '.rv-assets/kit.ts',
+                    remarks: notes.get(f.asset.id),
+                }
+                if (manual && rolls.length === 0)
+                    // the brief IS the paste-ready artifact ("I don't even
+                    // know what to paste" — the tile hands him the prompt)
+                    out.push({ ...base, text: `${f.asset.id} — manual, nothing uploaded`, severity: 'red', verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined })
+                else if (rolls.length > 0 && (await readPick(dir)).pick == null)
+                    out.push({ ...base, text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, severity: 'yellow', verbs: ['pick'] })
+                else if (await isStale(kit, join(root, kit.workspace), f))
+                    out.push({ ...base, text: `${f.asset.id} — stale (a parent was re-picked)`, severity: 'yellow', verbs: ['pick'] })
+                else out.push(base) // healthy — visible, dim, never in needs
+            }
+            return out
+        },
+    }
+}
+
+/** `.rv-assets/notes.md` — his dated asset remarks, one git-tracked file:
+ *  `- YYYY-MM-DD [asset-id]: text` */
+const assetNotes = (root: string): Map<string, string[]> => {
+    const p = join(root, '.rv-assets', 'notes.md')
+    const map = new Map<string, string[]>()
+    if (!existsSync(p)) return map
+    for (const m of readFileSync(p, 'utf8').matchAll(/^- (\d{4}-\d{2}-\d{2}) \[([^\]]+)\]: (.+)$/gm)) {
+        const key = m[2]!
+        map.set(key, [...(map.get(key) ?? []).slice(-2), `- ${m[1]}: ${m[3]}`])
+    }
+    return map
+}
+
+/** repo health — NON-curatable feed items: EVERY wire line of STATUS.md's
+ *  check output (ok = quiet, WARN = yellow, FAIL = red; the passing lines
+ *  ARE listed — the page shows the whole check run), plus contract
+ *  FAIL/WARN and hub process staleness. fix: pointers ride the owning
+ *  instance's md as a code block. Cred probe FAIL lines (+ their fixes) are
+ *  routed to the secrets collection, never duplicated here. */
+export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVersion?: string; libVersion?: () => string }): Collection {
+    return {
+        id: 'health',
+        title: 'repo health',
+        media: 'health',
+        list: async () => {
+            const out: Instance[] = []
+            if (o?.bootVersion != null && o.libVersion != null) {
+                const now = o.libVersion()
+                if (now !== o.bootVersion)
+                    out.push({ id: 'health:stale-hub', severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
+            }
+            for (const i of statusWire(root)) {
+                if (i.kind === 'fail' && CRED_LINE.test(i.text)) continue // secrets own the cred probe + its fix lines
+                // the feed line carries severity already — a raw FAIL:/WARN marker would stack the signal
+                // id = full text (never sliced: a shared 60-char prefix must not collide two items — pings dedup on ids)
+                out.push({
+                    id: `health:${i.text}`,
+                    text: i.text,
+                    severity: i.kind === 'fail' ? 'red' : i.kind === 'warn' ? 'yellow' : undefined,
+                    md: i.fixes.length > 0 ? wireMd(i.fixes.map((f) => `fix: ${f}`)) : undefined,
+                })
+            }
+            const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
+            for (const l of r.lines) {
+                if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, severity: 'red', text: l.text })
+                else if (l.kind === 'warn') out.push({ id: `health:contractwarn:${l.text}`, severity: 'yellow', text: l.text })
+            }
+            return out
+        },
+    }
+}
+
+export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit | null, o?: { bootVersion?: string; libVersion?: () => string }): Collection[] {
+    return [
+        repoHealthCollection(root, c, o),
+        asksCollection(root, c),
+        credsCollection(root, c),
+        mediaKitCollection(root, kit),
+        socialPostsCollection(root),
+    ]
+}

package/src/contracts/apply-contracts.ts

@@ -0,0 +1,47 @@
+// The ONE bridge from the contracts engine into wire output — every surface
+// that reports contract fulfillness (`shipkit check` via rule SK002, the ci
+// `contracts` task, `shipkit contracts`) goes through applyContractsResult,
+// so tags, the empty-repo sentence, and severity plumbing exist exactly
+// once. Kinds pass through raw so fix pointers and visible exempts survive
+// every printer.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { tagRuleLines, type Rule } from '../rules/rule.ts'
+import { allContracts } from './contract-manifests.ts'
+import type { ContractManifest } from './contract-types.ts'
+import type { ContractsConfig, ContractsResult } from './contracts-engine.ts'
+
+export function contractsConfigFrom(c: RepoConfig, root: string): ContractsConfig {
+    const venues = c.venues ?? []
+    const social = c.social ?? []
+    const declared = [
+        ...venues,
+        ...(social.length > 0 ? ['social'] : []),
+        ...(social.includes('discord') ? ['discord'] : []),
+    ]
+    return {
+        root,
+        declared,
+        social,
+        publicSurface: venues.length > 0 || existsSync(join(root, 'deploy.sh')),
+        exempt: c.contracts?.exempt,
+        docsBase: c.docsBase,
+    }
+}
+
+export function activeContracts(c: RepoConfig): ContractManifest[] {
+    return [...allContracts, ...(c.contracts?.extra ?? [])]
+}
+
+export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: Rule): void {
+    const lines = tag != null ? tagRuleLines(tag, r.lines) : r.lines
+    for (const l of lines) t.lines.push(l)
+    if (r.exitCode === 1) t.failed = true
+    if (r.lines.some((l) => l.kind === 'warn')) t.warned = true
+    if (r.lines.length === 0) {
+        const text = 'no contracts apply (nothing declared, nothing detected)'
+        t.ok(tag != null ? `[${tag.id}] ${text}` : text)
+    }
+}

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}`)