rvlib-shipkit 0.38.0 → 1.0.0

package/src/ledger/unit-table.ts

@@ -1,105 +0,0 @@
-// THE inventory render — every gate unit as one markdown row, so the question
-// "what runs here, does it block me, and how often does it really run" has a
-// surface that is read rather than reconstructed from three commands.
-//
-// Deliberately carries NO live run state: no timestamps, no key hashes, no
-// last verdict. Everything here is what a unit DECLARED about itself, so two
-// runs a week apart over an unchanged repo write identical bytes and the file
-// never churns. It is still generated, gitignored AND untracked like STATUS.md
-// (rules/untrack-generated.ts), so it is read on disk, never in git history.
-// Live keys are `shipkit keys`, live verdicts are STATUS.md.
-import { join } from 'path'
-import { atomicWrite, withFileLock } from '../core/locked-write.ts'
-import { classify } from './git-key.ts'
-import type { UnitRow } from './gate-units.ts'
-
-/** the sidecar every gate run refreshes beside STATUS.md */
-export const UNIT_TABLE_FILE = 'STATUS.full.md'
-
-/** a cell can never break the table it sits in */
-const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ')
-
-export type UnitTableInput = {
-    /** repo name, for the headline */
-    name: string
-    rows: UnitRow[]
-}
-
-/** what a unit's cache declaration means for how often it actually runs */
-function cacheOf(r: UnitRow): { population: string; ttl: string; reads: string; why: string } {
-    const c = classify(r.decl)
-    const inputs = r.decl.inputs ?? []
-    if (c.error != null) return { population: 'BROKEN', ttl: '', reads: '', why: c.error }
-    if (c.population === 'content') return { population: 'content', ttl: '', reads: inputs.join(', '), why: '' }
-    // no `reads` for these two: the cache column already says "world"/"never",
-    // and restating it on every such row is a column of noise
-    if (c.population === 'world') return { population: 'world', ttl: r.decl.ttl ?? '', reads: '', why: '' }
-    if (c.decided === true) return { population: 'never', ttl: '', reads: '', why: r.decl.never ?? '' }
-    return { population: 'UNDECLARED', ttl: '', reads: '', why: 'nobody has declared what this reads, so it re-runs every single time' }
-}
-
-export function renderUnitTable(input: UnitTableInput): string {
-    const { name, rows } = input
-    const counts = { task: 0, rule: 0, check: 0 }
-    for (const r of rows) counts[r.decl.kind]++
-
-    const body: string[] = []
-    body.push(`<!-- generated by \`shipkit units\`, refreshed by every gate run, gitignored (SK004) -->`)
-    body.push(`# ${name} units — ${rows.length} total`)
-    body.push('')
-    body.push(`Everything \`shipkit ci\` and \`shipkit check\` know how to run: ${counts.task} task(s), ${counts.rule} rule(s), ${counts.check} discovered check(s).`)
-    body.push('')
-    body.push('- **runs in** — `gate` means `shipkit ci` runs it, so a red one says THIS change is broken. `proactive` means only `shipkit check` runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit.')
-    body.push('- **on failure** — `blocks` stops the run. `warns` prints and carries on. `UNDECLARED` is a defect, not a setting: the unit never said and the repo set no default, so the runner treats it as fatal by guess.')
-    body.push('- **cache** — `content` replays while the files it reads are untouched. `world` replays for its TTL, and a measured RED replays too, capped at one hour so the run after a fix sees the fix. `never` re-runs every time and somebody wrote down why. `UNDECLARED` re-runs every time and nobody has looked yet, which is the burn-down (`shipkit keys --burn-down`). `SHIPKIT_FRESH=1` busts all of it.')
-    const proactive = rows.filter((r) => !r.gate && !r.optIn).length
-    const warns = rows.filter((r) => r.blocking === false).length
-    const neverSaid = rows.filter((r) => r.blocking == null).length
-    const undeclared = rows.filter((r) => cacheOf(r).population === 'UNDECLARED')
-    body.push('')
-    // the most useful line in the file, so it sits ABOVE the 68 rows rather
-    // than under them
-    body.push(
-        `**${rows.length - proactive} in the gate, ${proactive} proactive · ${warns} warn instead of blocking${neverSaid > 0 ? `, ${neverSaid} never said` : ''} · ${undeclared.length} uncacheable with nobody having looked.**`,
-    )
-    body.push('')
-    body.push('| unit | kind | runs in | on failure | cache | ttl | reads | owner |')
-    body.push('|---|---|---|---|---|---|---|---|')
-    for (const r of rows) {
-        const c = cacheOf(r)
-        const blocking = r.blocking == null ? '**UNDECLARED**' : r.blocking ? 'blocks' : 'warns'
-        const runsIn = r.optIn ? 'opt-in' : r.gate ? 'gate' : 'proactive'
-        const population = c.population === 'UNDECLARED' ? '**UNDECLARED**' : c.population
-        body.push(
-            `| \`${cell(r.decl.id)}\` | ${r.decl.kind} | ${runsIn} | ${blocking} | ${population} | ${cell(c.ttl)} | ${cell(c.reads)} | ${r.owner == null ? '' : `\`${cell(r.owner)}\``} |`,
-        )
-    }
-    body.push('')
-
-    const decided = rows.filter((r) => cacheOf(r).population === 'never')
-    if (undeclared.length > 0) {
-        body.push(`## ${undeclared.length} unit(s) nothing can cache yet`)
-        body.push('')
-        body.push('Each of these runs on every single pass. Declaring `inputs` (it reads files), `ttl` (it reads the world) or `never` (nothing can describe it) is the fix, and the last one counts: a written reason is a decision, not a hole.')
-        body.push('')
-        for (const r of undeclared) body.push(`- \`${cell(r.decl.id)}\` (${r.decl.kind})${r.owner == null ? '' : ` — \`${cell(r.owner)}\``}`)
-        body.push('')
-    }
-    if (decided.length > 0) {
-        body.push(`## ${decided.length} unit(s) decided uncacheable`)
-        body.push('')
-        for (const r of decided) body.push(`- \`${cell(r.decl.id)}\` — ${cell(r.decl.never ?? '')}`)
-        body.push('')
-    }
-
-    return body.join('\n')
-}
-
-/** refresh the sidecar beside STATUS.md. Lock-guarded exactly like STATUS.md:
- *  several runners in one checkout is the normal case, and the loser skipping
- *  a render it would have written identically costs nothing. */
-export function writeUnitTable(root: string, input: UnitTableInput): { written: boolean; warn?: string } {
-    const target = join(root, UNIT_TABLE_FILE)
-    const r = withFileLock(target, () => { atomicWrite(target, `${renderUnitTable(input).trimEnd()}\n`) })
-    return r.ok ? { written: true } : { written: false, warn: `${UNIT_TABLE_FILE} locked by another runner — skipped this write` }
-}

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

@@ -1,24 +0,0 @@
-// 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 { evaluateContractsOnce } from '../contracts/contracts-once.ts'
-import type { Rule } from './rule.ts'
-
-export const contractsFulfillness: Rule = {
-    id: 'SK002',
-    blocking: true,
-    title: 'contracts',
-    owner: 'meta/contracts.md',
-    // the contract engine is pure filesystem (no fetch, no spawn anywhere in
-    // contracts/), and WHICH folders it reads depends on the venues declared,
-    // so the honest input is the work tree
-    inputs: ['.'],
-    lint: async (t, env) => {
-        applyContractsResult(t, await evaluateContractsOnce(activeContracts(env.config), contractsConfigFrom(env.config, env.root)), contractsFulfillness)
-    },
-}

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

@@ -1,70 +0,0 @@
-// 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
-// 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 } from 'fs'
-import { join } from 'path'
-import { spawnWithTimeout } from '../core/spawn-timeout.ts'
-import type { FixResult, Rule, RuleEnv } from './rule.ts'
-import { atomicWrite } from '../core/locked-write.ts'
-
-const AGENT_LINE = '@./agent/index.md'
-const LOCAL_LINE = '@./CLAUDE.local.md'
-
-export const claudeMdShape: Rule = {
-    id: 'SK003',
-    blocking: true,
-    title: 'CLAUDE.md',
-    owner: 'meta/agent-folder.md',
-    // CLAUDE.md plus whether agent/index.md exists — and a repo that has
-    // neither is the case this rule exists for, so the tree rather than two
-    // paths that may not be there
-    inputs: ['.'],
-    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` }
-        atomicWrite(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

@@ -1,238 +0,0 @@
-// SK004 — the .gitignore policy block (meta/contracts.md git policy; tmp/
-// included because shipkit writes its per-run logs there 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 { execFileSync } from 'child_process'
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
-import type { RepoConfig } from '../repo-config.ts'
-import { GENERATED_IGNORE_LINES, trackedGeneratedPaths, untrackGenerated } from './untrack-generated.ts'
-import type { FixResult, Rule, RuleEnv } from './rule.ts'
-import { atomicWrite } from '../core/locked-write.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:)'
-
-export const POLICY_LINES = [
-    // the leak guard reads .rv-private/banned-keywords.txt: the file listing
-    // what must never be committed cannot itself be committable
-    '.rv-private/',
-    '.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/',
-    // atomicWrite lands every file via `.<name>.tmp-<pid>` next to its target,
-    // so a run killed mid write leaves one behind ANYWHERE in the tree, and an
-    // agent finds untracked debris it did not create. The ignore row ships in
-    // the same policy that started writing them.
-    '.*.tmp-*',
-    // comfy-ts state (schema dumps, drafts) and per-workflow lora tags name a
-    // private model collection; shipkit itself writes .comfy-ts/ at hub boot,
-    // so every consumer repo needs both ignored before its first commit
-    '.comfy-ts/',
-    '*.loras.local.txt',
-    // shipkit's own per-run output. Ignoring is only half of it: the fixer
-    // also removes these from the index, because .gitignore does nothing to a
-    // file already tracked (untrack-generated.ts owns the pair)
-    ...GENERATED_IGNORE_LINES,
-]
-
-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 ?? [])]
-}
-
-// the three venue folders are DESIGNED to be unignored below the block once a
-// listing is live (last-match-wins, the comment inside POLICY_LINES says so),
-// so an override on one of them is the mechanism working. Every other policy
-// path is a claim the block makes, and a claim git contradicts is a bug.
-function endsWithNewline(root: string): boolean {
-    const p = join(root, '.gitignore')
-    if (!existsSync(p)) return true
-    const text = readFileSync(p, 'utf8')
-    return text === '' || text.endsWith('\n')
-}
-
-const OVERRIDABLE = new Set(['.rv-itch/', '.rv-steam/', '.rv-discord/'])
-
-/** a path git can be asked about, for a pattern that may be a glob or a dir */
-function probePath(pattern: string): string {
-    if (pattern.endsWith('/')) return `${pattern}probe`
-    // `.*.tmp-*` and `*.loras.local.txt`: a literal standing in for the glob
-    return pattern.includes('*') ? pattern.replace(/\*/g, 'probe') : pattern
-}
-
-/** which of `paths` git does NOT ignore. null when this is not a git repo, so
- *  a rule can say it did not measure rather than report a green it invented */
-export function notIgnored(root: string, paths: string[]): string[] | null {
-    if (paths.length === 0) return []
-    try {
-        // --stdin -z -n: one call, every path, and `-n` makes git print a row
-        // for the MISSES too, which is the answer we want
-        const out = execFileSync('git', ['check-ignore', '--stdin', '-z', '-n', '-v'], {
-            cwd: root, input: paths.join('\0'), encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
-        })
-        // -v -z rows are source\0line\0pattern\0path; an unignored path has an
-        // empty source and an empty pattern
-        const f = out.split('\0')
-        const miss: string[] = []
-        for (let i = 0; i + 3 < f.length + 1; i += 4) {
-            if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
-        }
-        return miss
-    } catch (e) {
-        // exit 1 means "none of them are ignored", which is an ANSWER, and git
-        // still wrote the rows we parse. Anything else (no repo, no git) is not
-        const err = e as { status?: number; stdout?: string }
-        if (err.status === 1 && typeof err.stdout === 'string') {
-            const f = err.stdout.split('\0')
-            const miss: string[] = []
-            for (let i = 0; i + 3 < f.length + 1; i += 4) {
-                if (f[i] === '' && f[i + 2] === '' && f[i + 3] != null && f[i + 3] !== '') miss.push(f[i + 3]!)
-            }
-            return miss
-        }
-        return null
-    }
-}
-
-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'
-    atomicWrite(p, `${out.join(eol)}${out.at(-1) === '' ? '' : eol}`)
-}
-
-export const gitignorePolicy: Rule = {
-    id: 'SK004',
-    blocking: true,
-    title: '.gitignore',
-    owner: 'meta/contracts.md',
-    // .gitignore plus what git currently TRACKS, which the tree carries and a
-    // single path does not
-    inputs: ['.'],
-    lint: (t, env) => {
-        // a generated path still in the index is the half-applied state the
-        // managed block cannot fix on its own
-        const tracked = trackedGeneratedPaths(env.root)
-        if (tracked.length > 0) {
-            t.fail(`${tracked.join(', ')} generated on every run but TRACKED — gitignore does not apply to a tracked file, so it dirties every tree`)
-            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) untracks it in one commit, the file stays on disk' })
-        }
-        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')
-        }
-        // an unterminated last line is a TRAP, not a cosmetic defect: the next
-        // `>> .gitignore` fuses onto it and the result is one pattern that
-        // ignores neither path, with the file ending in a newline afterwards
-        // so nothing textual looks wrong
-        if (!endsWithNewline(env.root)) {
-            t.fail('.gitignore does not end with a newline — the next append fuses onto its last line and ignores neither path')
-            t.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) terminates it' })
-            return
-        }
-        // the block states what must be ignored. git is the only thing that
-        // knows whether it IS: a stray negation below the block, or a line
-        // fused into another, leaves the text current over a broken repo
-        const claimed = policyPatterns(env.config).filter((p) => !OVERRIDABLE.has(p))
-        const probes = new Map(claimed.map((p) => [probePath(p), p]))
-        const miss = notIgnored(env.root, [...probes.keys()])
-        if (miss == null) {
-            // not a git repo (a fixture, or a dir before `git init`). Say the
-            // verification did not run rather than reporting a green nothing
-            // measured, and stay quiet: there is nothing wrong here to fix
-            t.ok(`.gitignore policy block current (${claimed.length} patterns)`)
-            t.lines.push({ kind: 'skip', text: 'not a git repo here, so nothing verified the block against what git actually ignores' })
-            return
-        }
-        if (miss.length > 0) {
-            const names = [...new Set(miss.map((m) => probes.get(m) ?? m))]
-            t.fail(`.gitignore block claims ${names.join(', ')} ignored, git says otherwise — a negation below the block, or a line fused into its neighbour`)
-            t.lines.push({ kind: 'fix-fail', text: `git check-ignore -v ${miss[0]} names the line that wins` })
-            return
-        }
-        t.ok(`.gitignore policy block current, ${claimed.length} patterns verified against git`)
-    },
-    fix: (env: RuleEnv): FixResult => {
-        const before = blockState(env.root, env.config)
-        // terminate an unterminated file even when the block itself is current:
-        // that missing byte is what the next append fuses onto
-        let terminated: string | null = null
-        if (before === 'current' && !endsWithNewline(env.root)) {
-            const p = join(env.root, '.gitignore')
-            atomicWrite(p, `${readFileSync(p, 'utf8')}\n`)
-            terminated = '.gitignore terminated with a newline (the next append would have fused onto its last line)'
-        }
-        const blockSummary = before === 'current'
-            ? null
-            : 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)'
-        if (blockSummary != null) writeBlock(env.root, env.config)
-        // the block must be written FIRST: untracking a path the ignore list
-        // does not yet carry leaves it staged for re-add on the next `git add`
-        const un = untrackGenerated(env.root, { enabled: env.config.untrackGenerated })
-        const parts = [blockSummary, terminated]
-        if (un.did === 'untracked') parts.push(`untracked ${un.paths.join(', ')} (generated, now gitignored, committed as ${un.commit})`)
-        if (un.did === 'refused') parts.push(`left ${trackedGeneratedPaths(env.root).join(', ')} tracked: ${un.why}`)
-        const summary = parts.filter((x): x is string => x != null).join(' · ')
-        return { changed: blockSummary != null || terminated != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
-    },
-}

package/src/rules/SK010-undeclared-release-unit.ts

@@ -1,127 +0,0 @@
-// SK010 — undeclared release unit (build/shipkit.md). Release units are
-// DECLARED, never inferred, so resolution is deterministic. This rule is the
-// other half of that deal: a package.json sitting in the repo that no unit
-// claims would be invisible to every release surface, and its version would
-// drift forever with nothing reporting it. Two declarations clear it, so the
-// green is always reachable: `units: [{ dir }]` for a releasable package,
-// `notReleasable: [dir]` for one that ships inside something else. That second
-// escape has teeth on purpose, because it is the one an agent staring at a red
-// gate reaches for: an entry must cover at least one real package and never the
-// whole repo, and the green counts the PACKAGES it excused, so a wide entry
-// cannot read as a narrow one.
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
-import { join, relative } from 'path'
-import { resolveUnits } from '../release/units.ts'
-import type { Rule } from './rule.ts'
-
-const SKIP = new Set(['node_modules', 'references', 'tmp', 'stats', 'dist', 'build'])
-
-/** package dirs git knows about (tracked + untracked-not-ignored), so a
- *  gitignored vendor tree or a python venv never trips the gate. Null when
- *  git cannot answer, and the caller falls back to walking. */
-function gitPackageDirs(root: string): string[] | null {
-    const p = Bun.spawnSync(['git', 'ls-files', '--cached', '--others', '--exclude-standard', '-z'], { cwd: root })
-    if (p.exitCode !== 0) return null
-    return p.stdout.toString().split('\0')
-        .filter((f) => f === 'package.json' || f.endsWith('/package.json'))
-        .map((f) => join(root, f, '..'))
-}
-
-/** the fs fallback: an unreadable entry (a dangling symlink, an unmounted
- *  volume) is skipped, never thrown — a broken link is not a release fact */
-function walkPackageDirs(root: string): string[] {
-    const out: string[] = [root]
-    const walk = (dir: string): void => {
-        let entries: string[]
-        try { entries = readdirSync(dir) } catch { return }
-        for (const e of entries) {
-            if (SKIP.has(e) || e.startsWith('.')) continue
-            const p = join(dir, e)
-            try { if (!statSync(p).isDirectory()) continue } catch { continue }
-            if (existsSync(join(p, 'package.json'))) out.push(p)
-            walk(p)
-        }
-    }
-    walk(root)
-    return out
-}
-
-/** every package.json below the root that carries a name, root excluded */
-export function packageDirs(root: string): string[] {
-    const dirs = gitPackageDirs(root) ?? walkPackageDirs(root)
-    const named = dirs.filter((d) => {
-        if (d === root) return false
-        if (relative(root, d).split('/').some((seg) => SKIP.has(seg) || seg.startsWith('.'))) return false
-        try {
-            const pkg = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')) as { name?: string }
-            return typeof pkg.name === 'string' && pkg.name !== ''
-        } catch { return false } // a broken package.json is SK001's story, not this rule's
-    })
-    return [...new Set(named)].sort()
-}
-
-export const undeclaredReleaseUnit: Rule = {
-    id: 'SK010',
-    blocking: true,
-    title: 'release units declared',
-    owner: 'build/shipkit.md',
-    // `git ls-files` plus a walk for every package.json in the repo
-    inputs: ['.'],
-    lint: (t, env) => {
-        const { units, errors } = resolveUnits(env.root, env.config)
-        // a DECLARED unit that does not resolve is a declaration bug and
-        // belongs here. A root package that is not release-shaped (no version
-        // yet) is not: the release path refuses on its own, the day it matters.
-        const declared = errors.filter((e) => e.id !== 'root')
-        if (declared.length > 0) {
-            for (const e of declared) t.fail(`declared unit '${e.id}' does not resolve: ${e.message}`, 'repo.config units[]')
-            return
-        }
-        // an entry is a PREFIX over the packages under it, so `examples/` can
-        // excuse examples/a and examples/b without enumerating them. Two shapes
-        // are refused, both being the kill switch this rule exists to prevent:
-        // an entry covering the whole repo, and one covering nothing today that
-        // stands ready to excuse whatever lands there tomorrow. defineRepo
-        // refuses the root too, and a repo.config.ts that never calls it is
-        // exactly why the check also lives in the blocking rule.
-        const decls = env.config.notReleasable ?? []
-        const covered = (list: string[], d: string): boolean => list.some((c) => d === c || d.startsWith(`${c}/`))
-        const pkgs = packageDirs(env.root)
-        const wide = decls.filter((d) => join(env.root, d) === env.root)
-        if (wide.length > 0) {
-            for (const d of wide)
-                t.fail(`notReleasable '${d}' resolves to the repo root, so it excuses every package at once`, `repo.config notReleasable: name one package dir (or one container dir) per entry`)
-            return
-        }
-        const empty = decls.filter((d) => !pkgs.some((p) => covered([join(env.root, d)], p)))
-        if (empty.length > 0) {
-            for (const d of empty)
-                t.fail(`notReleasable '${d}' covers no package.json, so it excuses no package today and every package that lands there tomorrow`, `repo.config notReleasable: point it at a package dir (or a dir holding some), or drop the entry`)
-            return
-        }
-        const excused = decls.map((d) => join(env.root, d))
-        const declaredDirs = units.filter((u) => u.rel !== '').map((u) => u.dir)
-        // an excuse that also covers a RELEASE UNIT is the kill switch one
-        // level down: `notReleasable: ['libs']` beside `units: [libs/a]` reads
-        // as green while every new package under libs/ hides. The two lists
-        // describe opposite intents, so they must not overlap.
-        const overlapping = decls.filter((d) => declaredDirs.some((u) => u === join(env.root, d) || u.startsWith(`${join(env.root, d)}/`)))
-        if (overlapping.length > 0) {
-            for (const d of overlapping)
-                t.fail(`notReleasable '${d}' also covers a declared release unit, so it excuses every package under it while reading as green`, `repo.config notReleasable: name the dirs that are NOT release units, never a container holding one`)
-            return
-        }
-        const claimed = [...declaredDirs, ...excused]
-        const orphans = pkgs.filter((d) => !covered(claimed, d))
-        if (orphans.length === 0) {
-            // PACKAGES, not entries: one entry over a nested tree excuses more
-            // than one, and the count is the only place that shows it
-            const n = pkgs.filter((d) => covered(excused, d)).length
-            return t.ok(`${units.length} release unit(s) declared${units.length === 1 ? ' (the repo root)' : ''}${n > 0 ? ` + ${n} package(s) declared not releasable` : ''} — no package hides from a release`)
-        }
-        for (const d of orphans) {
-            const rel = relative(env.root, d)
-            t.fail(`${rel}/package.json is claimed by nothing — declare what it is, or its version drifts with nothing watching`, `repo.config units: [{ dir: '${rel}' }] if it releases, else notReleasable: ['${rel}']`)
-        }
-    },
-}

package/src/rules/rule-registry.ts

@@ -1,64 +0,0 @@
-// 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'
-import { commitAiTells } from './SK009-commit-ai-tells.ts'
-import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
-import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
-import { configBarrelImport } from './SK012-config-barrel-import.ts'
-import { oneWayInPolicy } from './SK013-one-way-in-policy.ts'
-import { proseSte } from './SK014-prose-ste.ts'
-import { nestedRepo } from './SK015-nested-repo.ts'
-
-export const RULES: readonly Rule[] = [
-    packageJsonShape,
-    contractsFulfillness,
-    claudeMdShape,
-    gitignorePolicy,
-    rvlibVersions,
-    npmPublishSafety,
-    githubVisibility,
-    reviewerAgent,
-    commitAiTells,
-    undeclaredReleaseUnit,
-    siblingUnitRanges,
-    configBarrelImport,
-    oneWayInPolicy,
-    proseSte,
-    nestedRepo,
-]
-
-// THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is
-// reserved for the built-ins above so a repo rule can never shadow one.
-export const RULE_ID_RE = /^[A-Z]{2,4}\d{3}$/
-
-/** validate a rule set and its ids against everything already registered.
- *  Throws on a malformed id, a duplicate, a missing owner page, or a repo
- *  rule squatting the reserved SK prefix. Shared by the built-in registry
- *  and by `defineRepo`, so both die loud at import time. */
-export function validateRules(rules: readonly Rule[], o: { label: string; builtin?: boolean; taken?: Iterable<string> } = { label: 'rule-registry' }): void {
-    const seen = new Set<string>(o.taken ?? [])
-    for (const r of rules) {
-        if (!RULE_ID_RE.test(r.id)) throw new Error(`${o.label}: bad id '${r.id}' — rules are PREFIX+3 digits (e.g. SK001, RV001)`)
-        if (o.builtin !== true && r.id.startsWith('SK'))
-            throw new Error(`${o.label}: id '${r.id}' uses the reserved SK prefix — repo rules pick their own (e.g. RV${r.id.slice(-3)})`)
-        if (seen.has(r.id)) throw new Error(`${o.label}: duplicate id ${r.id}`)
-        if (r.owner === '') throw new Error(`${o.label}: ${r.id} has no owner page`)
-        seen.add(r.id)
-    }
-}
-
-validateRules(RULES, { label: 'rule-registry', builtin: true })
-
-export const BUILTIN_RULE_IDS: readonly string[] = RULES.map((r) => r.id)
-
-export const ruleById = (id: string): Rule | undefined => RULES.find((r) => r.id === id)