rvlib-shipkit 0.10.0 → 0.13.0

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` }
+    },
+}

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/rule-registry.ts

@@ -0,0 +1,32 @@
+// 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'
+
+export const RULES: readonly Rule[] = [
+    packageJsonShape,
+    contractsFulfillness,
+    claudeMdShape,
+    gitignorePolicy,
+    rvlibVersions,
+    npmPublishSafety,
+    githubVisibility,
+]
+
+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}` }
+    })
+}