rvlib-shipkit 0.11.0 → 0.14.0

package/src/rules/SK004-gitignore-policy.ts

@@ -0,0 +1,105 @@
+// SK004 — the .gitignore policy block (meta/contracts.md git policy; tmp/
+// included because shipkit itself writes tmp/.shipkit-cache in every
+// repo). A marker-keyed managed block so the always-gitignored contract
+// surfaces can never silently rot per repo. Ecosystem-specific names the
+// published lib may not carry ride as repo-contributed lines:
+// `defineRepo({ gitignore: [...] })` renders them INSIDE the block, so the
+// whole policy is machine-enforced. A well-formed block is rewritten IN
+// PLACE — lines below it (e.g. a live venue's `!.rv-itch/` override, where
+// last-match-wins) keep their position; everything outside the block is
+// never touched. `shipkit init` writes the same block through this fixer.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit outside only'
+const END = '# <<< shipkit gitignore policy'
+const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
+
+const POLICY_LINES = [
+    '.rv-reflections/',
+    '.rv-social/',
+    '.rv-journal/',
+    '.rv-domain/',
+    '.rv-assets/out/',
+    '# venue folders stay ignored until the listing is live — override below the block',
+    '.rv-itch/',
+    '.rv-steam/',
+    '.rv-discord/',
+    'CLAUDE.local.md',
+    'tmp/',
+]
+
+export function expectedBlock(config: RepoConfig): string {
+    const extra = config.gitignore ?? []
+    return [BEGIN, ...POLICY_LINES, ...(extra.length > 0 ? [CONTRIB, ...extra] : []), END].join('\n')
+}
+
+export function policyPatterns(config: RepoConfig): string[] {
+    return [...POLICY_LINES.filter((l) => !l.startsWith('#')), ...(config.gitignore ?? [])]
+}
+
+type Parsed = { text: string; crlf: boolean; lines: string[]; b: number; e: number }
+
+function parse(root: string): Parsed | null {
+    const p = join(root, '.gitignore')
+    if (!existsSync(p)) return null
+    const text = readFileSync(p, 'utf8')
+    const crlf = text.includes('\r\n')
+    const lines = text.split('\n').map((l) => l.replace(/\r$/, ''))
+    return { text, crlf, lines, b: lines.indexOf(BEGIN), e: lines.indexOf(END) }
+}
+
+type BlockState = 'missing-file' | 'missing-block' | 'corrupted' | 'stale' | 'current'
+
+function blockState(root: string, config: RepoConfig): BlockState {
+    const f = parse(root)
+    if (f == null) return 'missing-file'
+    if (f.b === -1 && f.e === -1) return 'missing-block'
+    if (f.b === -1 || f.e === -1 || f.e < f.b) return 'corrupted'
+    return f.lines.slice(f.b, f.e + 1).join('\n') === expectedBlock(config) ? 'current' : 'stale'
+}
+
+function writeBlock(root: string, config: RuleEnv['config']): void {
+    const p = join(root, '.gitignore')
+    const f = parse(root)
+    const block = expectedBlock(config).split('\n')
+    let out: string[]
+    if (f == null) out = block
+    else if (f.b !== -1 && f.e !== -1 && f.e >= f.b)
+        // well-formed block: rewrite IN PLACE so below-block overrides
+        // (last-match-wins) keep working
+        out = [...f.lines.slice(0, f.b), ...block, ...f.lines.slice(f.e + 1)]
+    else {
+        // absent or corrupted: drop stray markers, keep every repo line
+        // visible, append the canonical block
+        const kept = (f.b === -1 && f.e === -1 ? f.lines : f.lines.filter((l) => l !== BEGIN && l !== END))
+        while (kept.length > 0 && kept.at(-1)!.trim() === '') kept.pop()
+        out = kept.length > 0 ? [...kept, '', ...block] : block
+    }
+    const eol = f?.crlf === true ? '\r\n' : '\n'
+    writeFileSync(p, `${out.join(eol)}${out.at(-1) === '' ? '' : eol}`)
+}
+
+export const gitignorePolicy: Rule = {
+    id: 'SK004',
+    title: '.gitignore',
+    owner: 'meta/contracts.md',
+    lint: (t, env) => {
+        const s = blockState(env.root, env.config)
+        switch (s) {
+            case 'missing-file': return t.fail('.gitignore missing — the contract git policy is unenforced')
+            case 'missing-block': return t.fail('.gitignore has no shipkit policy block — contract surfaces can leak into git')
+            case 'corrupted': return t.fail('.gitignore policy block corrupted (unpaired marker)')
+            case 'stale': return t.fail('.gitignore policy block is stale — the policy or repo-contributed lines moved since it was written')
+            case 'current': return t.ok(`.gitignore policy block current (${policyPatterns(env.config).length} patterns)`)
+        }
+    },
+    fix: (env: RuleEnv): FixResult => {
+        const before = blockState(env.root, env.config)
+        if (before === 'current') return { changed: false, summary: 'policy block already current' }
+        writeBlock(env.root, env.config)
+        return { changed: true, summary: before === 'missing-file' ? '.gitignore created with the policy block' : before === 'missing-block' ? 'policy block appended (repo lines untouched)' : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)' : 'policy block rewritten in place (repo lines untouched)' }
+    },
+}

package/src/rules/SK005-rvlib-versions.ts

@@ -0,0 +1,99 @@
+// SK005 — rvlib-* dependency freshness, and the self-update that keeps
+// every repo converging on the current toolkit (a stale repo silently
+// missing months of rules is the failure; machine-clearable drift clears
+// ITSELF). Per rvlib-* dep:
+//   link:   → the symlink must resolve (a broken link dies cryptically at
+//             import time otherwise) — nothing to update, code is live
+//   semver  → installed vs npm latest; NEWER LIVE → this lint runs
+//             `bun update --latest` itself, loudly, guarded:
+//             - SHIPKIT_FROZEN=1 (`check --frozen`) → WARN, never touch
+//             - package.json/lockfile git-dirty (or no git) → WARN deferred,
+//               a tool must not mix its writes into human-staged work
+//   registry unreachable → loud skip, never red (offline is not a defect)
+// Committing the bump stays with the working agent — shipkit never commits.
+// Clean passes cache 24h (rule ttl), so the registry is fetched at most
+// daily per repo; skip/WARN/FAIL runs are never cached. peerDependencies
+// are NOT scanned: keeping a published lib's peer ranges consistent after
+// a bump stays the agent's job.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { Rule, RuleEnv } from './rule.ts'
+
+type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+const installedVersion = (root: string, name: string): string | null => {
+    const p = join(root, 'node_modules', name, 'package.json')
+    if (!existsSync(p)) return null
+    try { return (JSON.parse(readFileSync(p, 'utf8')) as Pkg).version ?? null } catch { return null }
+}
+
+async function latestVersion(t: CheckCtx, name: string): Promise<string> {
+    const res = await t.fetch(`https://registry.npmjs.org/${name}/latest`)
+    if (!res.ok) throw new Error(`registry ${res.status}`)
+    const v = ((await res.json()) as Pkg).version
+    if (v == null) throw new Error('registry payload has no version')
+    return v
+}
+
+export const rvlibVersions: Rule = {
+    id: 'SK005',
+    title: 'rvlib versions',
+    owner: 'build/shipkit.md',
+    ttl: '24h',
+    lint: async (t, env: RuleEnv) => {
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return t.note('no readable package.json — rvlib versions not applicable') }
+        const deps = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([n]) => n.startsWith('rvlib-'))
+        if (deps.length === 0) return t.ok('no rvlib-* deps')
+
+        const stale: Array<{ name: string; installed: string; latest: string }> = []
+        for (const [name, spec] of deps) {
+            if (spec.startsWith('link:')) {
+                if (installedVersion(env.root, name) == null) t.fail(`${name} is link: but the symlink does not resolve — re-run \`bun link ${name}\` (a broken link dies cryptically at import time)`)
+                else t.ok(`${name} (linked, live)`)
+                continue
+            }
+            const installed = installedVersion(env.root, name)
+            if (installed == null) { t.fail(`${name} declared (${spec}) but not installed — run: bun install`); continue }
+            let latest: string
+            try { latest = await latestVersion(t, name) } catch (e) {
+                t.lines.push({ kind: 'skip', text: `${name} ${installed} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
+                continue
+            }
+            // real semver order, not string difference — a dist-tag pointing
+            // BEHIND the installed version (prerelease, unpublish window)
+            // must never trigger a silent downgrade
+            const cmp = Bun.semver.order(latest, installed)
+            if (cmp === 0) t.ok(`${name} ${installed} (latest)`)
+            else if (cmp < 0) t.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
+            else stale.push({ name, installed, latest })
+        }
+        if (stale.length === 0) return
+
+        const drift = stale.map((s) => `${s.name} ${s.installed} → ${s.latest}`).join(', ')
+        if (process.env['SHIPKIT_FROZEN'] === '1') {
+            t.warn(`newer rvlib live: ${drift} (frozen — apply with: bun update --latest ${stale.map((s) => s.name).join(' ')})`)
+            return
+        }
+        const dirty = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+        if (dirty.code !== 0 || dirty.out.trim() !== '') {
+            t.warn(`newer rvlib live: ${drift} — self-update deferred (${dirty.code !== 0 ? `git says: ${dirty.out.trim().split('\n')[0] ?? `exit ${dirty.code}`}` : 'package.json/lockfile dirty'}); commit first, then re-run check`)
+            return
+        }
+        const names = stale.map((s) => s.name)
+        const up = await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
+        if (up.code !== 0) {
+            t.fail(`self-update failed (bun update --latest ${names.join(' ')} exited ${up.code}${up.timedOut ? ', timed out' : ''}) — package.json/lockfile may be partially written, \`git status\` first: ${up.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}`)
+            return
+        }
+        for (const s of stale) {
+            const now = installedVersion(env.root, s.name)
+            // WARN on purpose: the run MUTATED the repo and a follow-up
+            // (restart watchers, commit) is owed — an ok here would be a
+            // green, cacheable line replaying a past event as current state
+            if (now === s.latest) t.warn(`${s.name} ${s.installed} → ${now} self-updated — restart watchers, commit the bump`)
+            else t.warn(`${s.name} updated but reads ${now ?? 'missing'} (wanted ${s.latest}) — check the lockfile`)
+        }
+    },
+}

package/src/rules/SK006-npm-publish-safety.ts

@@ -0,0 +1,42 @@
+// SK006 — npm publish safety (meta/rv-conventions/package-json.md).
+// `private: true` is npm's own unconditional publish refusal — THE lock
+// (SK001 enforces its presence). This rule closes the contradiction class
+// around it: a private package carrying publish machinery is either a
+// leftover (dead weight that confuses agents) or a loaded gun for the day
+// someone flips `private` — both fail loud. rvlib-* roots publish by
+// design and are exempt. Lint-only: deleting publish machinery is a
+// judgment call (a `publish` script may publish a SITE, not npm).
+// SCOPE, stated: the checked surface is publishConfig + prepublish*/
+// postpublish + a script literally NAMED `publish` running npm/bun
+// publish. Machinery reachable under OTHER names (release scripts,
+// np/release-it deps, a control room publishing its own sub-libs) is
+// deliberately out of scope — `private: true` on the root already refuses,
+// and sanctioned sub-lib publishing must not turn this rule red.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import type { Rule } from './rule.ts'
+
+type Pkg = { name?: string; private?: boolean; publishConfig?: unknown; scripts?: Record<string, string> }
+
+export const npmPublishSafety: Rule = {
+    id: 'SK006',
+    title: 'npm publish safety',
+    owner: 'meta/rv-conventions/package-json.md',
+    lint: (t, env) => {
+        const p = join(env.root, 'package.json')
+        if (!existsSync(p)) return t.ok('no package.json — nothing publishable')
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { return t.note('package.json unreadable — SK001 reports it') }
+        if (pkg.name?.startsWith('rvlib-') === true) return t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+        if (pkg.private !== true) return t.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
+        const machinery: string[] = []
+        if (pkg.publishConfig != null) machinery.push('publishConfig')
+        for (const s of ['prepublishOnly', 'prepublish', 'postpublish'])
+            if (pkg.scripts?.[s] != null) machinery.push(`scripts.${s}`)
+        if (pkg.scripts?.['publish'] != null && /npm publish|bun publish/.test(pkg.scripts['publish']))
+            machinery.push(`scripts.publish (runs npm/bun publish)`)
+        if (machinery.length > 0)
+            t.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
+        else t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root`)
+    },
+}

package/src/rules/SK007-github-visibility.ts

@@ -0,0 +1,63 @@
+// SK007 — github visibility tripwire (meta/contracts.md pre-public gate).
+// `repo.config.ts visibility: 'private' | 'public'` (absent = 'private')
+// states the INTENT; gh states the FACT; a mismatch in either direction is
+// red — public-while-declared-private is the leak case,
+// private-while-declared-public is a stale config lying to agents. The
+// TARGET repo is resolved explicitly from the remote url (preferring
+// `github`, then `origin`, then the first remote) and passed to gh — gh's
+// own base-repo resolution prefers `upstream`, which in a fork-shaped
+// checkout would confidently validate the WRONG repository. Flipping a
+// repo public stays a human act behind the pre-public audit; this rule is
+// the standing tripwire if it ever happens out of band. Clean passes cache
+// 7d, keyed on the declared value (a flip re-probes immediately); every
+// unverifiable path (no git, no remote, non-github remote, gh missing or
+// erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
+// never cached.
+import type { Rule } from './rule.ts'
+
+export const githubVisibility: Rule = {
+    id: 'SK007',
+    title: 'github visibility',
+    owner: 'meta/contracts.md',
+    ttl: '7d',
+    cacheKey: (env) => env.config.visibility ?? 'private',
+    lint: async (t, env) => {
+        const declared = env.config.visibility ?? 'private'
+        const skip = (why: string): void => void t.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
+        const firstLine = (s: string): string => s.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? ''
+
+        const remotes = await t.exec(['git', 'remote'], { cwd: env.root })
+        if (remotes.code !== 0) return skip(`git says: ${firstLine(remotes.out) || `exit ${remotes.code}`}`)
+        const names = remotes.out.trim().split('\n').filter((l) => l !== '')
+        if (names.length === 0) return skip('no git remote')
+        // his repos name it `github`, not `origin` (field catch 2026-07-26)
+        const pick = ['github', 'origin'].find((n) => names.includes(n)) ?? names[0]!
+        const url = await t.exec(['git', 'remote', 'get-url', pick], { cwd: env.root })
+        if (url.code !== 0) return skip(`git says: ${firstLine(url.out)}`)
+        const m = url.out.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\s*$/m)
+        if (m == null) return skip(`remote '${pick}' is not github (${firstLine(url.out)})`)
+        const target = m[1]!
+
+        const r = await t.exec(['gh', 'repo', 'view', target, '--json', 'isPrivate,nameWithOwner'], { cwd: env.root, timeoutMs: 30_000 })
+        if (r.code !== 0) return skip(`gh failed (${firstLine(r.out)})`)
+        // gh mixes stderr chatter (release notices, SSO warnings) into the
+        // captured output — carve the JSON object out before parsing, and an
+        // unreadable answer stays an UNKNOWN, never a FAIL
+        const start = r.out.indexOf('{')
+        const end = r.out.lastIndexOf('}')
+        let parsed: { isPrivate?: boolean; nameWithOwner?: string }
+        try {
+            if (start === -1 || end < start) throw new Error('no JSON object in output')
+            parsed = JSON.parse(r.out.slice(start, end + 1)) as typeof parsed
+        } catch {
+            return skip(`gh answer unreadable (${firstLine(r.out)})`)
+        }
+        const actual = parsed.isPrivate === true ? 'private' : 'public'
+        const who = parsed.nameWithOwner ?? target
+        if (actual === declared) t.ok(`github ${who} is ${actual} — matches repo.config visibility`)
+        else if (actual === 'public')
+            t.fail(`github ${who} is PUBLIC but repo.config declares '${declared}' — the leak case; make it private again or run the pre-public gate and declare visibility: 'public'`)
+        else
+            t.fail(`github ${who} is private but repo.config declares 'public' — stale config lying to agents; fix the declaration`)
+    },
+}

package/src/rules/SK008-reviewer-agent.ts

@@ -0,0 +1,98 @@
+// SK008 — the mandated reviewer agent type. A repo that declares
+// `reviewer: { name, brief }` must carry `.claude/agents/<name>.md`: an agent
+// definition whose system prompt POINTS at the brief file (ONE home for the
+// text, so review framing can never drift per repo) and whose `tools:` line
+// stays inside a read-only ALLOWLIST — a reviewer's product is findings, never
+// fixes, and a denylist of today's edit-tool names would wave through anything
+// that edits by proxy. An absent `tools:` line is the worst case of all: the
+// harness then inherits every tool. The brief itself must exist. No
+// declaration = not a reviewer repo, and the rule passes silently.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, isAbsolute, join } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+/** default read-only toolset — an ALLOWLIST, not a denylist: a tool that can
+ *  edit by proxy (spawning a subagent, an MCP writer) is exactly what a
+ *  denylist of today's edit-tool names would wave through */
+export const REVIEWER_TOOLS = ['Read', 'Grep', 'Glob', 'Bash']
+
+export const reviewerAgentPath = (name: string): string => `.claude/agents/${name}.md`
+
+// the invariants, as a pure function over the file text — the rule below and
+// any repo-local linter call THIS, so there is one definition of "a valid
+// reviewer agent file" and not one per caller
+export function reviewerAgentIssues(text: string, reviewer: NonNullable<RepoConfig['reviewer']>): string[] {
+    const issues: string[] = []
+    const allowed = reviewer.tools ?? REVIEWER_TOOLS
+    const declared = text.match(/^name:\s*(\S+)\s*$/m)?.[1]
+    if (declared !== reviewer.name)
+        issues.push(`frontmatter name is ${declared == null ? 'missing' : `'${declared}'`} — it must be '${reviewer.name}', the type spawners ask for`)
+    if (!text.includes(reviewer.brief))
+        issues.push(`never points at the brief '${reviewer.brief}' — the agent's whole job is to load it before judging anything`)
+    const tools = text.match(/^tools:\s*(.+)$/m)?.[1]
+    if (tools == null) issues.push(`has no inline 'tools:' allowlist — omitting it inherits every tool, edit tools included`)
+    else
+        for (const t of tools.split(',').map((x) => x.trim()).filter(Boolean))
+            if (!allowed.includes(t)) issues.push(`grants '${t}', outside the allowlist (${allowed.join(', ')}) — a reviewer reports findings, it never edits, directly or by proxy`)
+    return issues
+}
+
+/** the brief must EXIST: a reviewer whose mandated first action is reading a
+ *  missing file flounders silently, which is the one thing this rule prevents */
+export function briefMissing(root: string, brief: string): boolean {
+    const p = brief.startsWith('~/') ? join(homedir(), brief.slice(2)) : isAbsolute(brief) ? brief : join(root, brief)
+    return !existsSync(p)
+}
+
+function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
+    return `---
+name: ${reviewer.name}
+description: The mandated critical reviewer for this repo. Use before every commit, and whenever a diff needs judging against what was actually asked for. Judges whether a change should exist at all, not just whether it is correct.
+tools: ${(reviewer.tools ?? REVIEWER_TOOLS).join(', ')}
+model: opus
+---
+
+You are this repo's critical reviewer. You have no Edit or Write tool on
+purpose: your product is findings, never fixes. Bash is for READING the state
+of things (\`git diff\`, the gates, running a claim to check it) — never for
+writing files by another route.
+
+FIRST ACTION, always: read \`${reviewer.brief}\` and follow it exactly. It tells
+you what else to read, when to refuse the job, the order of the questions, and
+the output shape.
+
+That brief overrides any habit of reviewing a diff for correctness alone.
+`
+}
+
+export const reviewerAgent: Rule = {
+    id: 'SK008',
+    title: 'reviewer agent',
+    owner: 'identity/how-we-work.md',
+    lint: (t, env) => {
+        const r = env.config.reviewer
+        if (r == null) return t.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
+        const rel = reviewerAgentPath(r.name)
+        const p = join(env.root, rel)
+        if (briefMissing(env.root, r.brief)) t.fail(`the declared brief '${r.brief}' does not exist — every review's mandated first action would fail`)
+        if (!existsSync(p)) return t.fail(`${rel} missing — the mandated reviewer type is unavailable, so every review runs on whatever framing the spawner improvised`)
+        const issues = reviewerAgentIssues(readFileSync(p, 'utf8'), r)
+        for (const i of issues) t.fail(`${rel}: ${i}`)
+        if (issues.length === 0 && !t.failed) t.ok(`${rel} → ${r.brief}`)
+    },
+    // create-if-missing only: an existing definition may carry a repo's own
+    // tuned prompt, and silently rewriting that would cost more than the
+    // finding it repairs. Violations in a present file stay a loud FAIL.
+    fix: (env: RuleEnv): FixResult => {
+        const r = env.config.reviewer
+        if (r == null) return { changed: false, summary: 'no reviewer declared — nothing to write' }
+        const rel = reviewerAgentPath(r.name)
+        const p = join(env.root, rel)
+        if (existsSync(p)) return { changed: false, summary: `${rel} exists — remaining findings are about its content, fix them by hand` }
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, canonicalAgent(r))
+        return { changed: true, summary: `${rel} written — points at ${r.brief}, no edit tools` }
+    },
+}

package/src/rules/rule-registry.ts

@@ -0,0 +1,34 @@
+// THE rule registry — single source of every SK rule. `shipkit check` runs
+// them, `shipkit rules` lists them, fix pointers and wiki pages name their
+// ids. A duplicate or malformed id throws at import time: every surface
+// that loads rules dies loud rather than run with an ambiguous registry.
+import type { Rule } from './rule.ts'
+import { packageJsonShape } from './SK001-package-json-shape.ts'
+import { contractsFulfillness } from './SK002-contracts-fulfillness.ts'
+import { claudeMdShape } from './SK003-claude-md-shape.ts'
+import { gitignorePolicy } from './SK004-gitignore-policy.ts'
+import { rvlibVersions } from './SK005-rvlib-versions.ts'
+import { npmPublishSafety } from './SK006-npm-publish-safety.ts'
+import { githubVisibility } from './SK007-github-visibility.ts'
+import { reviewerAgent } from './SK008-reviewer-agent.ts'
+
+export const RULES: readonly Rule[] = [
+    packageJsonShape,
+    contractsFulfillness,
+    claudeMdShape,
+    gitignorePolicy,
+    rvlibVersions,
+    npmPublishSafety,
+    githubVisibility,
+    reviewerAgent,
+]
+
+const seen = new Set<string>()
+for (const r of RULES) {
+    if (!/^SK\d{3}$/.test(r.id)) throw new Error(`rule-registry: bad id '${r.id}' — rules are SK### (3 digits, never reused)`)
+    if (seen.has(r.id)) throw new Error(`rule-registry: duplicate id ${r.id}`)
+    if (r.owner === '') throw new Error(`rule-registry: ${r.id} has no owner page`)
+    seen.add(r.id)
+}
+
+export const ruleById = (id: string): Rule | undefined => RULES.find((r) => r.id === id)

package/src/rules/rule.ts

@@ -0,0 +1,62 @@
+// Rule — one machine-enforced invariant with a stable id. One module per
+// rule (`src/rules/SK###-<slug>.ts`), registered in rule-registry.ts; ids
+// are never reused or renumbered. `shipkit check` runs every rule's lint;
+// a rule may also carry an idempotent fix() (the `check --fix` runner).
+// Every wire line a rule emits is tagged `[SK###]` so output is greppable
+// by rule and a fix pointer names the rule that can repair it.
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { Line } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type RuleEnv = { root: string; config: RepoConfig }
+
+export type FixResult = { changed: boolean; summary: string }
+
+export type Rule = {
+    /** stable `SK` + 3 digits — never reused, never renumbered (registry throws) */
+    id: string
+    /** check-suite display name — stable: the check name in STATUS.md, the TUI row, and the suite cache */
+    title: string
+    /** wiki page owning the invariant — the run-check framework appends `docsBase + owner`
+     *  as the fix: pointer whenever a failing/warning lint attached none */
+    owner: string
+    /** clean-pass cache duration (check-suite TTL, e.g. '24h') — for rules that
+     *  probe the network; skip/WARN/FAIL runs are never cached */
+    ttl?: string
+    /** cache-identity contribution for TTL'd rules whose verdict depends on
+     *  config — a changed key busts the cache instantly instead of replaying
+     *  a stale assertion for the TTL */
+    cacheKey?: (env: RuleEnv) => string
+    lint: (t: CheckCtx, env: RuleEnv) => void | Promise<void>
+    /** idempotent auto-repair; `check --fix` applies it then re-lints — never interactive */
+    fix?: (env: RuleEnv) => FixResult | Promise<FixResult>
+}
+
+// THE one way to run a rule's lint (check suite + the --fix runner): a
+// throwing lint still fails with its id, a failing/warning run always
+// carries at least one fix: pointer (the lint's own precise ones win, else
+// docsBase + the rule's owner page), and every line gets tagged.
+export async function runRuleLint(rule: Rule, t: CheckCtx, env: RuleEnv): Promise<void> {
+    try {
+        await rule.lint(t, env)
+    } catch (e) {
+        t.fail(`${rule.title} lint errored (${String(e).slice(0, 200)}) — network down, or a bug in this rule`)
+    }
+    if ((t.failed || t.warned) && !t.lines.some((l) => l.kind === 'fix-fail' || l.kind === 'fix-warn'))
+        t.lines.push({ kind: t.failed ? 'fix-fail' : 'fix-warn', text: `${env.config.docsBase ?? ''}${rule.owner}` })
+    t.lines = tagRuleLines(rule, t.lines)
+}
+
+// tag every severity line with the rule id; fix pointers of a fixable rule
+// advertise the autofix. Idempotent — already-tagged lines pass through
+// (cached suite replays re-enter here).
+export function tagRuleLines(rule: Rule, lines: Line[]): Line[] {
+    return lines.map((l) => {
+        if (l.kind === 'fix-warn' || l.kind === 'fix-fail')
+            return rule.fix == null || l.text.includes('--fix ')
+                ? l
+                : { ...l, text: `${l.text} · autofix: shipkit check --fix ${rule.id}` }
+        if (l.kind === 'note') return l
+        return l.text.startsWith(`[${rule.id}]`) ? l : { ...l, text: `[${rule.id}] ${l.text}` }
+    })
+}

package/src/rules/run-fix.ts

@@ -0,0 +1,57 @@
+// `shipkit check --fix [SK### …]` — apply rule autofixes, then re-lint and
+// show the real end state. Never runs under ci (the gate stays pure), never
+// caches (a fixer must see reality). No ids = every fixable rule; a
+// requested id that is unknown or unfixable fails loud instead of silently
+// narrowing.
+import { CheckCtx } from '../core/check-ctx.ts'
+import { formatLine } from '../core/wire.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { RULES, ruleById } from './rule-registry.ts'
+import { runRuleLint, type RuleEnv } from './rule.ts'
+
+export type FixOpts = {
+    ids?: string[]
+    print?: (line: string) => void
+}
+
+export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const config = await loadRepoConfig(root)
+    const env: RuleEnv = { root, config }
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+
+    let targets = RULES.filter((r) => r.fix != null)
+    if (o.ids != null && o.ids.length > 0) {
+        for (const id of o.ids) {
+            const r = ruleById(id)
+            if (r == null) { print(`FAIL: unknown rule '${id}' — see: shipkit rules`); return 1 }
+            if (r.fix == null) { print(`FAIL: [${id}] has no autofix — fix by hand: ${config.docsBase ?? ''}${r.owner}`); return 1 }
+        }
+        const wanted = new Set(o.ids)
+        targets = targets.filter((r) => wanted.has(r.id))
+    }
+
+    let exit = 0
+    for (const rule of targets) {
+        const before = new CheckCtx(new Map())
+        await runRuleLint(rule, before, env)
+        if (!before.failed && !before.warned) {
+            print(`ok: [${rule.id}] already clean — nothing to fix`)
+            continue
+        }
+        const f = await rule.fix!(env)
+        // an unchanged fix is the DESIGNED outcome for judgment findings —
+        // a note, not a warning
+        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `[${rule.id}] fix changed nothing — ${f.summary}`)
+        const after = new CheckCtx(new Map())
+        await runRuleLint(rule, after, env)
+        // the fix already ran: advertising it again on surviving findings
+        // would send an agent in a loop
+        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix SK\d{3}$/, '') }, color))
+        if (after.failed) exit = 1
+    }
+    const unfixable = RULES.filter((r) => r.fix == null).length
+    if (unfixable > 0 && (o.ids == null || o.ids.length === 0))
+        print(`${unfixable} rule(s) have no autofix — run \`shipkit check\` for the full repo state`)
+    return exit
+}