rvlib-shipkit 0.11.0 → 0.14.0

package/src/reflect/prompt-corpus.ts

@@ -0,0 +1,305 @@
+// shipkit reflect — mine the user's TYPED prompts out of Claude Code transcripts.
+// Transcripts live at <configRoot>/projects/<slug>/*.jsonl where <slug> is the
+// repo's absolute path with EVERY non-alphanumeric char replaced by '-'.
+//
+// A corpus is only as good as what it excludes: the harness writes many
+// user-role entries the human never typed (tool results, command wrappers,
+// compaction summaries, subagent prompts). Every filter below exists because
+// one of them polluted a real extraction pass.
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { homedir } from 'os'
+import { basename, join, resolve } from 'path'
+
+export type PromptEntry = {
+    uuid: string
+    timestamp: string
+    sessionId: string
+    /** config root the prompt came from, e.g. `.claude` */
+    account: string
+    text: string
+    /** 'queued' = typed WHILE the agent was working (a `queue-operation` entry).
+     * Same human, higher signal: corrections and standing conventions land there. */
+    origin: 'typed' | 'queued'
+}
+
+export type ConfigRoot = { account: string; projects: string }
+
+const siblingConfigDirs = (home: string): string[] => {
+    if (!existsSync(home)) return []
+    return readdirSync(home)
+        .filter((d) => d.startsWith('.claude-'))
+        .map((d) => join(home, d))
+}
+
+/** EVERY Claude Code config root on this machine, unioned: $CLAUDE_CONFIG_DIR
+ * (`:` or `,` separated) PLUS ~/.claude PLUS any sibling ~/.claude-<name>
+ * holding a projects/ dir. Additive on purpose — a second local account keeps
+ * its own transcripts, and the env var only names the account running RIGHT
+ * NOW, so honoring it alone hides every session of the other one (field bug
+ * 2026-07-24: a corpus mined that way lost a third of his prompts). */
+export function discoverConfigRoots(home: string = homedir()): ConfigRoot[] {
+    const fromEnv = (process.env.CLAUDE_CONFIG_DIR ?? '')
+        .split(/[:,]/)
+        .map((p) => p.trim())
+        .filter((p) => p !== '')
+    const seen = new Set<string>()
+    const roots: ConfigRoot[] = []
+    for (const dir of [...fromEnv, join(home, '.claude'), ...siblingConfigDirs(home)]) {
+        const projects = join(resolve(dir), 'projects')
+        if (seen.has(projects) || !existsSync(projects)) continue
+        seen.add(projects)
+        roots.push({ account: basename(resolve(dir)), projects })
+    }
+    return roots
+}
+
+/** Claude Code slugs EVERY non-alphanumeric char to '-', not just '/' */
+export const projectSlug = (repoPath: string): string => resolve(repoPath).replace(/[^a-zA-Z0-9]/g, '-')
+
+// wrappers the harness injects as user-role entries — none of them are typed
+const NOISE_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+    '<system-reminder>',
+    '<task-notification>',
+    'Caveat: The messages below',
+    '[Request interrupted',
+    'This session is being continued from a previous conversation',
+]
+
+export function isTypedPrompt(text: string): boolean {
+    const trimmed = text.trim()
+    if (trimmed === '') return false
+    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
+}
+
+type RawEntry = {
+    type?: unknown
+    entrypoint?: unknown
+    uuid?: unknown
+    timestamp?: unknown
+    sessionId?: unknown
+    isMeta?: unknown
+    isSidechain?: unknown
+    isCompactSummary?: unknown
+    /** queue-operation entries only */
+    operation?: unknown
+    content?: unknown
+    message?: { role?: unknown; content?: unknown }
+}
+
+/** His words out of one transcript line, or null when the line is not a prompt
+ * he typed. isSidechain = a subagent prompt the AGENT wrote; isMeta and
+ * isCompactSummary = harness-generated. Content is a string for a plain prompt,
+ * an array of blocks when the message carried pastes or attachments (the text
+ * blocks in there are still his). */
+export function promptTextOf(line: string): { text: string; entry: RawEntry } | null {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return null // truncated tail line of a live session
+    }
+    if (parsed == null || typeof parsed !== 'object') return null
+    const entry = parsed as RawEntry
+    if (entry.type !== 'user') return null
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
+    if (entry.entrypoint === 'sdk-cli') return null // a script drove this session, nobody typed it
+    if (entry.message?.role !== 'user') return null
+    const content = entry.message.content
+    let text: string
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+        const parts = content
+            .filter((b): b is { type: string; text: string } => b?.type === 'text' && typeof b?.text === 'string')
+            .map((b) => b.text)
+        if (parts.length === 0) return null // pure tool_result turn
+        text = parts.join('\n')
+    } else return null
+    // the harness appends reminder blocks INSIDE real prompts — strip, keep the text
+    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+    // a slash-command entry is a harness WRAPPER around typed text:
+    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
+    // Dropping the whole entry throws away real instructions and repro pastes.
+    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
+    if (args?.[1] != null) {
+        const body = args[1].trim()
+        if (body === '') return null // bare invocation, nothing typed
+        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
+        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
+    }
+    if (!isTypedPrompt(text)) return null
+    return { text, entry }
+}
+
+/** A prompt he typed while the agent was still working: the harness parks it as
+ * `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
+ * first, it may NEVER become a user message. Skipping these loses exactly the
+ * mid-flight corrections and standing conventions a retrospective is for
+ * (measured 2026-07-26: 72 such texts invisible in this repo alone). */
+export function queuedTextOf(line: string): { text: string; entry: RawEntry } | null {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return null
+    }
+    if (parsed == null || typeof parsed !== 'object') return null
+    const entry = parsed as RawEntry
+    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
+    if (typeof entry.content !== 'string') return null
+    const text = entry.content.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+    if (!isTypedPrompt(text)) return null
+    return { text, entry }
+}
+
+export function extractPrompts(jsonl: string, ctx: { sessionId: string; account: string }): PromptEntry[] {
+    const out: PromptEntry[] = []
+    for (const line of jsonl.split('\n')) {
+        if (line.trim() === '') continue
+        const queued = queuedTextOf(line)
+        const hit = queued ?? promptTextOf(line)
+        if (hit == null) continue
+        const timestamp = typeof hit.entry.timestamp === 'string' ? hit.entry.timestamp : ''
+        const fallbackId = `${queued == null ? 'typed' : 'queue'}:${ctx.sessionId}:${timestamp}`
+        out.push({
+            uuid: typeof hit.entry.uuid === 'string' ? hit.entry.uuid : fallbackId,
+            timestamp,
+            sessionId: typeof hit.entry.sessionId === 'string' ? hit.entry.sessionId : ctx.sessionId,
+            account: ctx.account,
+            text: hit.text,
+            origin: queued == null ? 'typed' : 'queued',
+        })
+    }
+    return out
+}
+
+/** Genuine repetition is SIGNAL (saying it twice raises priority), so dedupe
+ * must remove only mechanical copies:
+ *   - a resumed/forked session replaying an entry (same uuid, or same text at
+ *     the same instant),
+ *   - a queued prompt that later became a user message (same text, any gap —
+ *     one keystroke, two records).
+ * Anything else repeated is kept, so the corpus never manufactures a priority
+ * he did not give. Input must be chronological. */
+const REPEAT_WINDOW_MS = 5 * 60 * 1000
+
+const normalize = (text: string): string => text.replace(/\s+/g, ' ').trim().toLowerCase()
+
+export function dedupePrompts(prompts: PromptEntry[]): PromptEntry[] {
+    const seenUuid = new Set<string>()
+    const lastSeenAt = new Map<string, number>()
+    /** queued texts not yet matched by their user-message twin — consumption is
+     * ONE-time, so a genuine re-ask of the same words later still counts */
+    const awaitingConsume = new Set<string>()
+    const out: PromptEntry[] = []
+    for (const p of prompts) {
+        if (seenUuid.has(p.uuid)) continue
+        seenUuid.add(p.uuid)
+        const key = normalize(p.text)
+        const at = Number.isNaN(Date.parse(p.timestamp)) ? 0 : Date.parse(p.timestamp)
+        const prev = lastSeenAt.get(key)
+        if (prev != null) {
+            if (awaitingConsume.has(key) && p.origin === 'typed') {
+                awaitingConsume.delete(key) // the queued keystroke arriving as a message
+                lastSeenAt.set(key, at)
+                continue
+            }
+            if (at - prev < REPEAT_WINDOW_MS) continue // replay, or a resend seconds apart
+        }
+        lastSeenAt.set(key, at)
+        if (p.origin === 'queued') awaitingConsume.add(key)
+        out.push(p)
+    }
+    return out
+}
+
+/** Sessions whose transcript was pruned by retention survive only as a
+ * truncated firstPrompt in the per-project sessions-index.json. */
+function indexFallbackPrompts(dir: string, account: string, have: Set<string>): PromptEntry[] {
+    const indexPath = join(dir, 'sessions-index.json')
+    if (!existsSync(indexPath)) return []
+    let index: { entries?: unknown }
+    try {
+        index = JSON.parse(readFileSync(indexPath, 'utf8')) as { entries?: unknown }
+    } catch {
+        return []
+    }
+    const entries = Array.isArray(index.entries) ? index.entries : []
+    const out: PromptEntry[] = []
+    for (const raw of entries) {
+        const e = raw as { sessionId?: string; firstPrompt?: string; created?: string; fullPath?: string }
+        if (typeof e.sessionId !== 'string' || have.has(e.sessionId)) continue
+        if (typeof e.fullPath === 'string' && existsSync(e.fullPath)) continue
+        if (typeof e.firstPrompt !== 'string' || !isTypedPrompt(e.firstPrompt)) continue
+        out.push({
+            uuid: `index:${e.sessionId}`,
+            timestamp: typeof e.created === 'string' ? e.created : '',
+            sessionId: e.sessionId,
+            account,
+            text: `${e.firstPrompt}\n\n[transcript pruned — first prompt only, truncated]`,
+            origin: 'typed',
+        })
+    }
+    return out
+}
+
+export type RepoCorpus = {
+    /** project dirs actually scanned, across every config root */
+    dirs: string[]
+    /** config roots searched — printed when nothing was found */
+    roots: string[]
+    prompts: PromptEntry[]
+}
+
+/** Every prompt he typed in a repo: all config roots, the repo's project dir
+ * PLUS its worktree dirs (`<slug>--claude-worktrees-*`), deduped, chronological. */
+export function collectRepoPrompts(repoPath: string, roots: ConfigRoot[] = discoverConfigRoots()): RepoCorpus {
+    const slug = projectSlug(repoPath)
+    const dirs: string[] = []
+    const prompts: PromptEntry[] = []
+    for (const root of roots) {
+        const projectDirs = readdirSync(root.projects).filter(
+            (d) => d === slug || d.startsWith(`${slug}--claude-worktrees-`),
+        )
+        for (const projectDir of projectDirs) {
+            const dir = join(root.projects, projectDir)
+            dirs.push(dir)
+            const sessions = new Set<string>()
+            for (const file of readdirSync(dir)) {
+                if (!file.endsWith('.jsonl')) continue
+                const sessionId = file.replace(/\.jsonl$/, '')
+                sessions.add(sessionId)
+                prompts.push(
+                    ...extractPrompts(readFileSync(join(dir, file), 'utf8'), { sessionId, account: root.account }),
+                )
+            }
+            prompts.push(...indexFallbackPrompts(dir, root.account, sessions))
+        }
+    }
+    prompts.sort((a, b) => a.timestamp.localeCompare(b.timestamp))
+    return { dirs, roots: roots.map((r) => r.projects), prompts: dedupePrompts(prompts) }
+}
+
+/** Fence a prompt so its own backticks and markdown cannot break the document */
+function fenced(text: string): string {
+    const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map((m) => m[0].length))
+    const fence = '`'.repeat(Math.max(3, longest + 1))
+    return `${fence}text\n${text}\n${fence}`
+}
+
+/** Chronological corpus, one numbered section per prompt — meant to be read as
+ * a corpus, not as a task list. */
+export function corpusMarkdown(repoPath: string, prompts: PromptEntry[]): string {
+    const queued = prompts.filter((p) => p.origin === 'queued').length
+    const count = queued === 0 ? `${prompts.length}` : `${prompts.length}, ${queued} queued mid-run`
+    const lines: string[] = [`# prompt corpus — ${resolve(repoPath)} (${count})`, '']
+    prompts.forEach((p, i) => {
+        const when = p.timestamp.replace('T', ' ').slice(0, 16)
+        const tag = p.origin === 'queued' ? ' · queued' : ''
+        lines.push(`## ${i + 1} · ${when} · ${p.account} · ${p.sessionId.slice(0, 8)}${tag}`, '', fenced(p.text), '')
+    })
+    return `${lines.join('\n')}\n`
+}

package/src/repo-config.ts

@@ -11,11 +11,11 @@
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
-import { allContracts } from './contracts/contract-manifests.ts'
-import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts/contracts-engine.ts'
+import { activeContracts, applyContractsResult, contractsConfigFrom } from './contracts/apply-contracts.ts'
+import { evaluateContracts } from './contracts/contracts-engine.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
+import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
 import type { TaskDef } from './core/task-runner.ts'
-import type { CheckCtx } from './core/check-ctx.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
 
@@ -29,6 +29,10 @@ export type ServeConfig = {
     wikiGraph?: { title?: string; load: () => MdGraph }
     /** agent/ graph entrypoint (default: index.md AND README.md) */
     agentIndex?: string
+    /** off-machine hostname for the hub (e.g. a tailnet MagicDNS name) —
+     *  printed beside localhost and appended to ping messages (phones
+     *  can't resolve localhost) */
+    publicHost?: string
 }
 
 export type RepoConfig = {
@@ -52,6 +56,19 @@ export type RepoConfig = {
     /** notify command for new RED needs while the hub serves, `{message}` substituted (e.g. a push-notification CLI) */
     notifyCommand?: string
     contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
+    /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
+     *  block — for ecosystem-specific names the published lib may not carry */
+    gitignore?: string[]
+    /** declared github visibility INTENT (absent = 'private') — rule SK007
+     *  fails loud when `gh repo view` disagrees in either direction */
+    visibility?: 'private' | 'public'
+    /** the reviewer agent type this repo mandates: `.claude/agents/<name>.md`,
+     *  whose system prompt points at `brief` (an md file holding the standing
+     *  review framing — one home, shared across repos). `tools` overrides the
+     *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
+     *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
+     *  mandated reviewer. */
+    reviewer?: { name: string; brief: string; tools?: string[] }
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
     /** the `shipkit serve` hub: port + optional graph hooks */
@@ -59,11 +76,16 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'reviewer', 'tui', 'serve', 'logDir'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
     for (const v of c.venues ?? []) if (!/^[a-z0-9-]+$/.test(v)) throw new Error(`defineRepo: venue '${v}' must be kebab-case`)
+    if (c.visibility != null && c.visibility !== 'private' && c.visibility !== 'public')
+        throw new Error(`defineRepo: visibility '${String(c.visibility)}' — 'private' or 'public' only`)
+    // a half-declared reviewer would lint a path like `.claude/agents/.md`
+    if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
+        throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))
@@ -83,44 +105,14 @@ export async function loadRepoConfig(root: string): Promise<RepoConfig> {
     return mod.default
 }
 
-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 ?? [])]
-}
-
-// ONE mapping from an engine result into a CheckCtx — used by BOTH the ci
-// task and `shipkit check`; kinds pass through raw so fix pointers and
-// visible exempts survive every printer
-export function applyContractsResult(t: CheckCtx, r: ContractsResult): void {
-    for (const l of r.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) t.ok('no contracts apply (nothing declared, nothing detected)')
-}
-
-// the contracts commit-gate task — venue deploy tasks should dep on it
+// the contracts commit-gate task — venue deploy tasks should dep on it.
+// Same SK002-tagged rendering as `shipkit check` and `shipkit contracts`
+// (contracts/apply-contracts.ts is the one bridge).
 export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',
         logic: async (t) => {
-            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)))
+            applyContractsResult(t, await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root)), contractsFulfillness)
         },
     }
 }

package/src/rules/SK001-package-json-shape.ts

@@ -0,0 +1,156 @@
+// SK001 — canonical package.json shape (meta/rv-conventions/package-json.md):
+// private:true, no license, capability-required script names FAIL, banned
+// aliases + missing baseline trio WARN. Doctor surface only — never wired
+// into the ci gate. Pure local fs, no TTL.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { canonicalBodies, conditionalBodies, inferBin } from '../core/canonical-scripts.ts'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+type Pkg = { name?: string; private?: boolean; license?: string; scripts?: Record<string, string> }
+
+const OWNER = 'meta/rv-conventions/package-json.md'
+
+// alias → { canonical, bodyMatch } — WARN only when the body proves the
+// alias really is the canonical capability (a `serve` that serves a dist/
+// folder must not be told to rename)
+const ALIASES: Record<string, { canonical: string; bodyMatch: RegExp }> = {
+    'serve': { canonical: 'hub', bodyMatch: /(shipkit|cli\.ts) serve\b/ },
+    'identity': { canonical: 'assets:identity', bodyMatch: /assets(:| )identity\b/ },
+    'pretty': { canonical: 'fmt', bodyMatch: /./ },
+    'check-types': { canonical: 'typecheck', bodyMatch: /./ },
+}
+
+const BASELINE = ['test', 'lint', 'fmt'] as const
+
+// no per-line fix pointers here — the rule framework appends ONE pointer
+// (docsBase + OWNER) to a failing/warning run, the same one-per-severity
+// doctrine the contracts engine follows
+export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConfig): Promise<void> {
+    let pkg: Pkg
+    try {
+        pkg = (await Bun.file(join(root, 'package.json')).json()) as Pkg
+    } catch (e) {
+        t.fail(`package.json unreadable (${String(e).slice(0, 120)})`)
+        return
+    }
+    const scripts = pkg.scripts ?? {}
+    // rvlib-* as a probe ROOT is theoretical (libs live as sub-packages and
+    // the probe only runs where repo.config.ts loads) — field inversion is
+    // still handled so a future lib-root repo fails correctly, not absurdly
+    const isLib = pkg.name?.startsWith('rvlib-') === true
+
+    // published rvlib-* roots invert the field rules (distribute/npm owns them)
+    if (isLib) {
+        if (pkg.license !== 'MIT') t.fail(`package.json: rvlib-* package must carry license MIT`)
+        if (pkg.private === true) t.fail(`package.json: rvlib-* package must not be private`)
+    } else {
+        if (pkg.private !== true) t.fail(`package.json: "private": true is required`)
+        if (pkg.license != null) t.fail(`package.json: license field is banned on project repos (rvlib-* sub-packages excepted)`)
+    }
+
+    // aliases first — an alias satisfies the requirement but earns a WARN,
+    // never a double report (alias WARN + missing-canonical FAIL). A banned
+    // alias lingering NEXT TO its canonical still WARNs (sweep on sight),
+    // it just doesn't satisfy anything.
+    const aliased = new Set<string>()
+    for (const [name, a] of Object.entries(ALIASES)) {
+        const body = scripts[name]
+        if (body == null || !a.bodyMatch.test(body)) continue
+        if (scripts[a.canonical] == null) aliased.add(a.canonical)
+        t.warn(`package.json: script '${name}' is the house '${a.canonical}' — ${scripts[a.canonical] == null ? 'rename it' : `delete it ('${a.canonical}' exists)`}`)
+    }
+
+    const has = (name: string): boolean => scripts[name] != null || aliased.has(name)
+
+    const required = requiredScripts(root, c)
+    const missing = required.filter((r) => !has(r.name))
+    for (const m of missing) t.fail(`package.json: missing script '${m.name}' (${m.why})`)
+
+    const missingBaseline = BASELINE.filter((n) => !has(n))
+    if (missingBaseline.length > 0)
+        t.warn(`package.json: missing baseline script(s): ${missingBaseline.join(', ')}`)
+
+    if (!t.failed && !t.warned)
+        t.ok(`package.json shape ok (private, no license, ${required.length} required scripts present)`)
+}
+
+// capability → required script names (FAIL); repo.config.ts existence is
+// implied — this rule only runs under `shipkit check`
+function requiredScripts(root: string, c: RepoConfig): Array<{ name: string; why: string }> {
+    const required: Array<{ name: string; why: string }> = [
+        { name: 'ci', why: 'shipkit repo' },
+        { name: 'check', why: 'shipkit repo' },
+        { name: 'contracts', why: 'shipkit repo' },
+        { name: 'tui', why: 'shipkit repo' },
+        { name: 'hub', why: 'shipkit repo' },
+        { name: 'mv', why: 'shipkit repo' },
+    ]
+    if (existsSync(join(root, '.rv-assets/kit.ts'))) required.push({ name: 'assets', why: '.rv-assets/kit.ts exists' })
+    if (existsSync(join(root, '.rv-identity/brand.ts'))) required.push({ name: 'assets:identity', why: '.rv-identity/brand.ts exists' })
+    if (existsSync(join(root, '.rv-comfy'))) required.push({ name: 'comfy:up', why: '.rv-comfy/ exists' })
+    if (existsSync(join(root, 'deploy.sh'))) required.push({ name: 'up', why: 'deploy.sh exists' })
+    if (existsSync(join(root, c.asks?.dir ?? 'asks'))) required.push({ name: 'asks', why: 'ask queue exists' })
+    return required
+}
+
+export const packageJsonShape: Rule = {
+    id: 'SK001',
+    title: 'package.json',
+    owner: OWNER,
+    lint: (t: CheckCtx, env: RuleEnv) => evaluatePackageJson(t, env.root, env.config),
+    // mechanical repairs only: field flips + scripts whose canonical body the
+    // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
+    // named in the summary, never invented. rvlib-* roots untouched — their
+    // license/private are publish decisions.
+    fix: (env: RuleEnv): FixResult => {
+        const pkgPath = join(env.root, 'package.json')
+        if (!existsSync(pkgPath)) return { changed: false, summary: 'no package.json — nothing to fix' }
+        const raw = readFileSync(pkgPath, 'utf8')
+        let pkg: Pkg & { scripts?: Record<string, string> }
+        try { pkg = JSON.parse(raw) as Pkg } catch { return { changed: false, summary: 'package.json unparseable — repair it by hand first' } }
+        if (pkg.name?.startsWith('rvlib-') === true) return { changed: false, summary: 'rvlib-* package — license/private are publish decisions, not autofixable' }
+        const changes: string[] = []
+        const notes: string[] = []
+        // any "I am published" marker → the field flips are a publish
+        // decision, not a mechanical repair (the LIBRARY-profile gap in
+        // meta/gaps.md is still open)
+        const publishMarkers: string[] = ['files', 'exports', 'publishConfig'].filter((k) => (pkg as Record<string, unknown>)[k] != null)
+        if (pkg.scripts?.['prepublishOnly'] != null) publishMarkers.push('prepublishOnly')
+        if (publishMarkers.length > 0) {
+            notes.push(`publishable package (${publishMarkers.join(', ')}) — private/license left for a human`)
+        } else {
+            if (pkg.private !== true) { pkg.private = true; changes.push('private:true set') }
+            if (pkg.license != null) { delete pkg.license; changes.push('license removed') }
+        }
+        pkg.scripts ??= {}
+        const bin = inferBin(pkg.scripts)
+        const bodies: Record<string, string> = { ...canonicalBodies({ bin }), ...conditionalBodies({ bin }) }
+        const skipped: string[] = []
+        // a banned alias satisfies a requirement for the lint — adding its
+        // canonical beside it would create the exact duplicate the lint then
+        // tells a human to delete
+        const aliasSatisfied = new Set<string>()
+        for (const [name, a] of Object.entries(ALIASES))
+            if (pkg.scripts[name] != null && a.bodyMatch.test(pkg.scripts[name]!)) aliasSatisfied.add(a.canonical)
+        for (const m of requiredScripts(env.root, env.config).filter((r) => pkg.scripts![r.name] == null && !aliasSatisfied.has(r.name))) {
+            const body = bodies[m.name]
+            if (body == null) { skipped.push(m.name); continue }
+            pkg.scripts[m.name] = body
+            changes.push(`script '${m.name}' added`)
+        }
+        if (pkg.scripts['test'] == null) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        if (changes.length > 0) {
+            const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
+            writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
+        }
+        const summary = [
+            changes.length > 0 ? changes.join(', ') : 'nothing mechanical to change',
+            ...notes,
+            ...(skipped.length > 0 ? [`left for a human (no canonical body): ${skipped.join(', ')}`] : []),
+        ].join(' · ')
+        return { changed: changes.length > 0, summary }
+    },
+}

package/src/rules/SK002-contracts-fulfillness.ts

@@ -0,0 +1,19 @@
+// SK002 — .rv-* contract fulfillness (meta/contracts.md). The rule is the
+// registration point; the evaluation machinery stays in
+// contracts/contracts-engine.ts (venue manifests are DATA rows, not rules —
+// one SK id covers the invariant "declared contracts are fulfilled, folders
+// can't rot undeclared"). Every surface reporting fulfillness (`check`,
+// `shipkit contracts`, the ci `contracts` task) tags with this id via
+// contracts/apply-contracts.ts.
+import { activeContracts, applyContractsResult, contractsConfigFrom } from '../contracts/apply-contracts.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import type { Rule } from './rule.ts'
+
+export const contractsFulfillness: Rule = {
+    id: 'SK002',
+    title: 'contracts',
+    owner: 'meta/contracts.md',
+    lint: async (t, env) => {
+        applyContractsResult(t, await evaluateContracts(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
+    },
+}

package/src/rules/SK003-claude-md-shape.ts

@@ -0,0 +1,64 @@
+// SK003 — the CLAUDE.md two-line contract (meta/agent-folder.md): CLAUDE.md
+// is an include index, never a doc; `@./agent/index.md` comes LAST (include
+// order is SEMANTIC — base context first, repo docs after so they
+// override; a field bug moved the local include line and inverted it); a
+// public repo's `@./CLAUDE.local.md` line-1 indirection must be gitignored.
+// The lib stays generic: no personal include path is asserted — `shipkit
+// start --include` flags own which base include a machine wires in. A repo
+// with neither CLAUDE.md nor agent/ is not a two-line-contract repo and
+// passes.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { spawnWithTimeout } from '../core/spawn-timeout.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const AGENT_LINE = '@./agent/index.md'
+const LOCAL_LINE = '@./CLAUDE.local.md'
+
+export const claudeMdShape: Rule = {
+    id: 'SK003',
+    title: 'CLAUDE.md',
+    owner: 'meta/agent-folder.md',
+    lint: async (t, env) => {
+        const claudePath = join(env.root, 'CLAUDE.md')
+        const hasAgent = existsSync(join(env.root, 'agent/index.md'))
+        if (!existsSync(claudePath)) {
+            if (hasAgent) t.fail(`agent/index.md exists but there is no CLAUDE.md routing it — the two-line contract wants ${AGENT_LINE}`)
+            else t.ok('no CLAUDE.md / agent — not a two-line-contract repo')
+            return
+        }
+        const lines = readFileSync(claudePath, 'utf8').split('\n').filter((l) => l.trim() !== '')
+        const includes = lines.filter((l) => l.startsWith('@'))
+        const prose = lines.length - includes.length
+        if (prose > 0)
+            t.fail(`CLAUDE.md carries ${prose} non-include line(s) — it is a tiny include index, content belongs in agent/index.md`)
+        if (includes.length > 2)
+            t.fail(`CLAUDE.md has ${includes.length} include lines — the contract is 2: base context, then ${AGENT_LINE}`)
+        if (hasAgent && !lines.includes(AGENT_LINE))
+            t.fail(`agent/index.md exists but CLAUDE.md does not import it — add ${AGENT_LINE} as the LAST line`)
+        if (lines.includes(AGENT_LINE) && lines.at(-1) !== AGENT_LINE)
+            t.fail(`include order inverted — base context first, ${AGENT_LINE} LAST (order is semantic: repo docs override the base)`)
+        if (lines.includes(LOCAL_LINE)) {
+            const r = await spawnWithTimeout(['git', 'check-ignore', '-q', 'CLAUDE.local.md'], { cwd: env.root, timeoutMs: 5_000 })
+            if (r.code === 1)
+                t.fail(`${LOCAL_LINE} is imported but CLAUDE.local.md is not gitignored — the machine-local include must never be tracked`)
+            else if (r.code !== 0)
+                t.note(`CLAUDE.local.md gitignore not verifiable (git says: ${r.out.trim().split('\n')[0] ?? `exit ${r.code}`})`)
+        }
+        if (!t.failed) t.ok(`CLAUDE.md include-index ok (${lines.length} line(s))`)
+    },
+    // the one mechanical repair: the missing agent/index.md route, appended
+    // to an EXISTING CLAUDE.md. Never creates the file — a created one-line
+    // CLAUDE.md would lint green with the base include forever missing,
+    // trading a loud FAIL for a permanent silent gap. Creation and prose
+    // relocation stay human/machine-local (`shipkit start --include`).
+    fix: (env: RuleEnv): FixResult => {
+        const claudePath = join(env.root, 'CLAUDE.md')
+        if (!existsSync(join(env.root, 'agent/index.md'))) return { changed: false, summary: 'no agent/index.md — nothing mechanical to fix' }
+        if (!existsSync(claudePath)) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start --include), not autofixable' }
+        const cur = readFileSync(claudePath, 'utf8')
+        if (cur.split('\n').includes(AGENT_LINE)) return { changed: false, summary: `${AGENT_LINE} already routed — remaining findings need a human` }
+        writeFileSync(claudePath, `${cur.endsWith('\n') || cur === '' ? cur : `${cur}\n`}${AGENT_LINE}\n`)
+        return { changed: true, summary: `${AGENT_LINE} appended as the last line` }
+    },
+}