rvlib-shipkit 0.38.1 → 1.0.0

package/src/{rules/SK007-github-visibility.ts → checks/SK007-github-visibility.check.ts}

@@ -14,50 +14,56 @@
 // erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
 // never cached.
 import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
+import { probeGitRoot } from '../core/git-root.ts'
 import { nestedIn } from '../core/nesting.ts'
-import type { Rule } from './rule.ts'
+import { check } from '../check.ts'
 
-export const githubVisibility: Rule = {
+export const githubVisibility = check({
     id: 'SK007',
     // blocking despite being measured over the network: the fact is about THIS
     // REPO (it is public while it declares itself private), and every
     // unverifiable path above is a skip, so an offline machine never goes red
     blocking: true,
     title: 'github visibility',
+    description: 'the github visibility of this repo matches the one it declares',
     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})` })
+    run: async (c) => {
+        const declared = c.config.visibility ?? 'private'
+        const skip = (why: string): void => void c.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
         const firstLine = firstGhLine
-        const nested = nestedIn(env.root)
+        const repo = probeGitRoot(c.root)
+        if (repo.root == null) return skip(`git says: ${firstLine(repo.error)}`)
+        const nested = nestedIn(c.root)
         if (nested != null)
-            return void t.lines.push({ kind: 'skip', text: `github visibility unverified, nested in ${nested}: the remote belongs to the parent repo (declared: ${declared})` })
+            return void c.lines.push({ kind: 'skip', text: `github visibility unverified, nested in ${nested}: the remote belongs to the parent repo (declared: ${declared})` })
 
-        const remotes = await t.exec(['git', 'remote'], { cwd: env.root })
+        const remotes = await c.exec(['git', 'remote'], { cwd: c.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')
         // prefer a `github`-named remote over `origin` when both exist
         const pick = ['github', 'origin'].find((n) => names.includes(n)) ?? names[0]!
-        const url = await t.exec(['git', 'remote', 'get-url', pick], { cwd: env.root })
+        const url = await c.exec(['git', 'remote', 'get-url', pick], { cwd: c.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 })
+        const r = await c.exec(['gh', 'repo', 'view', target, '--json', 'isPrivate,nameWithOwner'], { cwd: c.root, timeoutMs: 30_000 })
         if (r.code !== 0) return skip(`gh failed (${firstLine(r.out)})`)
         // an unreadable answer stays an UNKNOWN, never a FAIL
         const parsed = carveGhJson<{ isPrivate?: boolean; nameWithOwner?: string }>(r.out)
         if (parsed == null) 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`)
+        if (actual === declared) c.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'`)
+            c.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`)
+            c.fail(`github ${who} is private but repo.config declares 'public' — stale config lying to agents; fix the declaration`)
     },
-}
+})
+
+export default githubVisibility

package/src/{rules/SK008-reviewer-agent.ts → checks/SK008-reviewer-agent.check.ts}

@@ -11,9 +11,14 @@ import { existsSync, mkdirSync, readFileSync } 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'
+import { check, type FixResult, type CheckEnv } from '../check.ts'
+import { LAYOUT } from '../core/layout.ts'
 import { atomicWrite } from '../core/locked-write.ts'
 
+/** where a review lands when its caller named no output file:
+ *  `YYYYMMDD-HHMMSS-<review-name>.md`, local time, gitignored */
+export const REVIEWS_DIR = LAYOUT.reviews
+
 /** 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 */
@@ -60,6 +65,13 @@ 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.
 
+ONE exception: your review itself. Unless the caller named an output file,
+write it with one Bash heredoc to
+\`${REVIEWS_DIR}/YYYYMMDD-HHMMSS-<review-name>.md\` (local time, 24h, a
+kebab name for what you reviewed; \`mkdir -p\` first), then return the same
+findings to the caller. The file is the copy that outlives the conversation,
+gitignored.
+
 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.
@@ -68,36 +80,39 @@ That brief overrides any habit of reviewing a diff for correctness alone.
 `
 }
 
-export const reviewerAgent: Rule = {
+export const reviewerAgent = check({
     id: 'SK008',
     blocking: true,
     title: 'reviewer agent',
+    description: 'the declared reviewer agent has its brief, its definition and read only tools',
     owner: 'identity/how-we-work.md',
     // the brief is a CONFIG path, and a `~/...` or absolute one puts it
     // outside the repo, where no tree id can see whether it still exists
     never: 'the reviewer brief may live outside the repo, where no tree id reaches it',
-    lint: (t, env) => {
-        const r = env.config.reviewer
-        if (r == null) return t.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
+    run: (c) => {
+        const r = c.config.reviewer
+        if (r == null) return c.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 declared reviewer type is unavailable, so any review runs on whatever framing the spawner improvised`)
+        const p = join(c.root, rel)
+        if (briefMissing(c.root, r.brief)) c.fail(`the declared brief '${r.brief}' does not exist — every review's mandated first action would fail`)
+        if (!existsSync(p)) return c.fail(`${rel} missing — the declared reviewer type is unavailable, so any 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}`)
+        for (const i of issues) c.fail(`${rel}: ${i}`)
+        if (issues.length === 0 && !c.failed) c.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
+    fix: (c): FixResult => {
+        const r = c.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)
+        const p = join(c.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 })
         atomicWrite(p, canonicalAgent(r))
         return { changed: true, summary: `${rel} written — points at ${r.brief}, no edit tools` }
     },
-}
+})
+
+export default reviewerAgent

package/src/{rules/SK009-commit-ai-tells.ts → checks/SK009-commit-ai-tells.check.ts}

@@ -12,7 +12,7 @@ import { readFileSync } from 'fs'
 import { join } from 'path'
 import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
 import { nestedIn } from '../core/nesting.ts'
-import type { Rule } from './rule.ts'
+import { check } from '../check.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
 // empty — the harness then never writes the trailer or the PR footer
@@ -25,27 +25,28 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
-export const commitAiTells: Rule = {
+export const commitAiTells = check({
     id: 'SK009',
     blocking: true,
     title: 'commit ai tells',
+    description: 'the history of a public repo carries no AI attribution and no dash punctuation',
     owner: 'identity/how-we-commit.md',
     // it scans the full `git log` and every ref name. History and refs are not
     // work-tree content, so nothing a scan can produce describes this answer
     never: 'reads the full commit history and every ref name, neither of which is work-tree content',
-    lint: async (t, env) => {
-        const nested = nestedIn(env.root)
+    run: async (c) => {
+        const nested = nestedIn(c.root)
         if (nested != null)
-            return void t.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
-        const declared = env.config.visibility ?? 'private'
+            return void c.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
+        const declared = c.config.visibility ?? 'private'
         if (declared !== 'public')
-            return t.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
+            return c.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
         // %x1f separates hash from body, %x1e terminates the record — commit
         // bodies are free text, so only unprintable separators are safe
-        const log = await t.exec(['git', 'log', '--format=%h%x1f%B%x1e'], { cwd: env.root, timeoutMs: 30_000 })
+        const log = await c.exec(['git', 'log', '--format=%h%x1f%B%x1e'], { cwd: c.root, timeoutMs: 30_000 })
         if (log.code !== 0) {
             const first = log.out.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? `exit ${log.code}`
-            return void t.lines.push({ kind: 'skip', text: `commit history unverifiable — git says: ${first}` })
+            return void c.lines.push({ kind: 'skip', text: `commit history unverifiable — git says: ${first}` })
         }
         const commits = log.out
             .split('\x1e')
@@ -55,30 +56,32 @@ export const commitAiTells: Rule = {
                 const cut = r.indexOf('\x1f')
                 return { hash: r.slice(0, cut), body: r.slice(cut + 1) }
             })
-        if (commits.length === 0) return void t.lines.push({ kind: 'skip', text: 'commit history unverifiable — no commits yet' })
+        if (commits.length === 0) return void c.lines.push({ kind: 'skip', text: 'commit history unverifiable — no commits yet' })
         const remedy = 'an unpushed TIP commit may be amended; anything deeper is the owner\'s decision (history is never rewritten as a side effect)'
         const sample = (hits: { hash: string }[]): string => hits.slice(0, 5).map((h) => h.hash).join(' ') + (hits.length > 5 ? ' …' : '')
-        const attributed = commits.filter((c) => hasAiAttribution(c.body))
-        const dashed = commits.filter((c) => hasDashPunctuation(c.body))
+        const attributed = commits.filter((m) => hasAiAttribution(m.body))
+        const dashed = commits.filter((m) => hasDashPunctuation(m.body))
         // ref NAMES tell too (a FABLE-checkpoint-3 tag outs the agent as
         // loudly as a trailer). bare match only for names with no other
         // meaning; vendor and codename words (cursor, openai, gemini, opus,
         // fable, …) name legitimate branches and features, they only match in
         // a checkpoint/session shape
         const refTell = /\b(?:claude|chatgpt|copilot|aider|devin)\b|(?:^|[-_/])(?:fable|sonnet|haiku|opus|gemini|codex)[-_](?:checkpoint|session|ckpt)/i
-        const refs = await t.exec(['git', 'for-each-ref', '--format=%(refname:short)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: env.root, timeoutMs: 30_000 })
-        if (refs.code !== 0) t.lines.push({ kind: 'skip', text: `ref names unverifiable — git for-each-ref exit ${refs.code}` })
+        const refs = await c.exec(['git', 'for-each-ref', '--format=%(refname:short)', 'refs/tags', 'refs/heads', 'refs/remotes'], { cwd: c.root, timeoutMs: 30_000 })
+        if (refs.code !== 0) c.lines.push({ kind: 'skip', text: `ref names unverifiable — git for-each-ref exit ${refs.code}` })
         const tellRefs = refs.code === 0 ? refs.out.split('\n').map((r) => r.trim()).filter((r) => r !== '' && refTell.test(r)) : []
         if (tellRefs.length > 0)
-            t.fail(`${tellRefs.length} ref name(s) carry an AI tell in a declared-public repo (${tellRefs.slice(0, 5).join(' ')}${tellRefs.length > 5 ? ' …' : ''}) — rename or delete the refs before the flip; a pushed tag also needs the remote delete`)
+            c.fail(`${tellRefs.length} ref name(s) carry an AI tell in a declared-public repo (${tellRefs.slice(0, 5).join(' ')}${tellRefs.length > 5 ? ' …' : ''}) — rename or delete the refs before the flip; a pushed tag also needs the remote delete`)
         if (attributed.length > 0)
-            t.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / a session trailer or claude.ai url / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
+            c.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / a session trailer or claude.ai url / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
         if (dashed.length > 0)
-            t.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
-        const silenced = attributionSilenced(env.root)
+            c.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
+        const silenced = attributionSilenced(c.root)
         if (!silenced)
-            t.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
+            c.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
         if (attributed.length === 0 && dashed.length === 0 && tellRefs.length === 0 && silenced)
-            t.ok(`${commits.length} commits + ${refs.code === 0 ? refs.out.split('\n').filter((r) => r.trim() !== '').length : 0} ref names scanned, attribution silenced in .claude/settings.json — no AI tells`)
+            c.ok(`${commits.length} commits + ${refs.code === 0 ? refs.out.split('\n').filter((r) => r.trim() !== '').length : 0} ref names scanned, attribution silenced in .claude/settings.json — no AI tells`)
     },
-}
+})
+
+export default commitAiTells

package/src/checks/SK010-undeclared-unit.check.ts

@@ -0,0 +1,111 @@
+// SK010 — undeclared unit (build/shipkit/units.md). 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. Three declarations clear it, so the
+// green is always reachable: `units: [{ dir }]` for a releasable package,
+// `units: [{ dir, release: false }]` for one whose tests run in their own
+// check, `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 { dirname, join, relative } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import { checkUnitReader, resolveUnits } from '../release/unit-resolve.ts'
+import { check } from '../check.ts'
+
+const SKIP = new Set(['node_modules', 'references', 'tmp', 'stats', 'dist', 'build'])
+
+/** every package.json below the root that carries a name, root excluded, as
+ *  absolute dirs. The files git sees, so a gitignored vendor tree or a python
+ *  venv never trips the gate */
+export function packageDirs(c: CheckCtx): string[] {
+    const named = c.list('**/package.json').filter((f) => {
+        if (f === 'package.json') return false
+        if (dirname(f).split('/').some((seg) => SKIP.has(seg) || seg.startsWith('.'))) return false
+        try {
+            const pkg = c.json<{ name?: string }>(f)
+            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.map((f) => join(c.root, dirname(f))))].sort()
+}
+
+export const undeclaredUnit = check({
+    id: 'SK010',
+    blocking: true,
+    title: 'units declared',
+    description: 'every package.json is a declared unit or declared not releasable',
+    owner: 'build/shipkit/units.md',
+    // keyed on what it reads: the listing of every package.json, each one it
+    // opens, and the declared units' package.json
+    run: (c) => {
+        const { units, errors, testOnly } = resolveUnits(c.root, c.config, checkUnitReader(c))
+        // 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) c.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 = c.config.notReleasable ?? []
+        const covered = (list: string[], d: string): boolean => list.some((x) => d === x || d.startsWith(`${x}/`))
+        const pkgs = packageDirs(c)
+        const wide = decls.filter((d) => join(c.root, d) === c.root)
+        if (wide.length > 0) {
+            for (const d of wide)
+                c.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(c.root, d)], p)))
+        if (empty.length > 0) {
+            for (const d of empty)
+                c.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(c.root, d))
+        const declaredDirs = units.filter((u) => u.rel !== '').map((u) => u.dir)
+        // an excuse that also covers a declared 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(c.root, d) || u.startsWith(`${join(c.root, d)}/`)))
+        if (overlapping.length > 0) {
+            for (const d of overlapping)
+                c.fail(`notReleasable '${d}' also covers a declared unit, so it excuses every package under it while reading as green`, `repo.config notReleasable: name the dirs that are NOT units, never a container holding one`)
+            return
+        }
+        // a `release: false` unit already says what its dir is, so an excuse
+        // naming it too is a second statement of one fact, and the two drift
+        const doubled = decls.filter((d) => testOnly.some((u) => u.dir === join(c.root, d) || u.dir.startsWith(`${join(c.root, d)}/`)))
+        if (doubled.length > 0) {
+            for (const d of doubled)
+                c.fail(`notReleasable '${d}' also covers a unit declared release: false, which already claims its dir`, `repo.config notReleasable: drop '${d}', the units[] entry says it`)
+            return
+        }
+        const claimed = [...declaredDirs, ...testOnly.map((u) => u.dir), ...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
+            const t = testOnly.length
+            return c.ok(`${units.length} releasing unit(s) declared${units.length === 1 ? ' (the repo root)' : ''}${t > 0 ? ` + ${t} test only unit(s)` : ''}${n > 0 ? ` + ${n} package(s) declared not releasable` : ''} — no package hides from a release`)
+        }
+        for (const d of orphans) {
+            const rel = relative(c.root, d)
+            c.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, units: [{ dir: '${rel}', release: false }] if only its tests run, else notReleasable: ['${rel}']`)
+        }
+    },
+})
+
+export default undeclaredUnit

package/src/{rules/SK011-sibling-unit-ranges.ts → checks/SK011-sibling-unit-ranges.check.ts}

@@ -1,5 +1,5 @@
-// SK011 — a dependency range on a SIBLING release unit must be satisfied by
-// the version that sibling actually carries (build/shipkit.md, release units).
+// SK011 — a dependency range on a SIBLING unit must be satisfied by
+// the version that sibling actually carries (build/shipkit/units.md).
 //
 // The failure it exists for: one unit is edited and its dependents keep a
 // range that names a version nobody published, or an older one that lacks the
@@ -9,10 +9,9 @@
 // interrupted.
 //
 // Local protocols (link:, file:) are SK006's story, not this rule's.
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
-import { resolveUnits } from '../release/units.ts'
-import type { Rule } from './rule.ts'
+import { join, relative } from 'path'
+import { checkUnitReader, resolveUnits } from '../release/unit-resolve.ts'
+import { check } from '../check.ts'
 
 type Pkg = {
     dependencies?: Record<string, string>
@@ -54,24 +53,24 @@ export function satisfiesSimple(version: string, range: string): boolean | null
     return va === ra && vi === ri && vp === rp
 }
 
-export const siblingUnitRanges: Rule = {
+export const siblingUnitRanges = check({
     id: 'SK011',
     blocking: true,
     title: 'sibling unit ranges',
-    owner: 'build/shipkit.md',
-    // every declared unit's package.json, at dirs the config picks
-    inputs: ['.'],
-    lint: (t, env) => {
-        const { units } = resolveUnits(env.root, env.config)
+    description: 'every range on a sibling unit floors at the version that sibling carries',
+    owner: 'build/shipkit/built-in-checks.md',
+    // keyed on what it reads: every declared unit's package.json, at the dirs
+    // the config picks
+    run: (c) => {
+        const { units } = resolveUnits(c.root, c.config, checkUnitReader(c))
         const version = new Map(units.map((u) => [u.name, u.version]))
-        if (units.length < 2) return t.ok('one release unit — no sibling ranges to keep honest')
+        if (units.length < 2) return c.ok('one releasing unit — no sibling ranges to keep honest')
         const bad: string[] = []
         let checked = 0
         for (const u of units) {
-            const p = join(u.dir, 'package.json')
-            if (!existsSync(p)) continue
-            let pkg: Pkg
-            try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { continue }
+            let pkg: Pkg | null
+            try { pkg = c.json<Pkg>(relative(c.root, join(u.dir, 'package.json'))) } catch { continue }
+            if (pkg == null) continue
             for (const block of BLOCKS)
                 for (const [dep, range] of Object.entries(pkg[block] ?? {})) {
                     const actual = version.get(dep)
@@ -87,7 +86,9 @@ export const siblingUnitRanges: Rule = {
                 }
         }
         if (bad.length > 0)
-            t.fail(`${bad.join(' · ')} — a sibling range FLOORS at the version it names, so a stale floor lets a consumer keep an older copy and miss the release. \`shipkit bump\` moves every floor forward in the version commit, so a red here is a bump nobody propagated`)
-        else t.ok(`${checked} sibling range(s) floor at exactly the version each unit carries`)
+            c.fail(`${bad.join(' · ')} — a sibling range FLOORS at the version it names, so a stale floor lets a consumer keep an older copy and miss the release. \`shipkit bump\` moves every floor forward in the version commit, so a red here is a bump nobody propagated`)
+        else c.ok(`${checked} sibling range(s) floor at exactly the version each unit carries`)
     },
-}
+})
+
+export default siblingUnitRanges

package/src/{rules/SK012-config-barrel-import.ts → checks/SK012-config-barrel-import.check.ts}

@@ -10,10 +10,7 @@
 // A barrel is a fine PUBLIC surface and a terrible one to import from a config
 // file that exists to be read before anything else happens. This rule is
 // narrow on purpose: it is about repo.config.ts, not about barrels in general.
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
-import type { FixResult, Rule, RuleEnv } from './rule.ts'
-import { atomicWrite } from '../core/locked-write.ts'
+import { check, type FixResult } from '../check.ts'
 
 const CONFIG = 'repo.config.ts'
 const BARREL = /(^|\n)(\s*import\s+(?:type\s+)?\{[^}]*\}\s+from\s+)['"]rvlib-shipkit['"]/
@@ -27,38 +24,36 @@ const CONFIG_SYMBOLS = new Set(['defineRepo', 'RepoConfig', 'TaskDef', 'ServeCon
 const importedSymbols = (line: string): string[] =>
     (/\{([^}]*)\}/.exec(line)?.[1] ?? '').split(',').map((s) => s.replace(/^\s*type\s+/, '').trim()).filter((s) => s !== '')
 
-export const configBarrelImport: Rule = {
+export const configBarrelImport = check({
     id: 'SK012',
     blocking: true,
     title: 'config import path',
-    owner: 'build/shipkit.md',
-    // ONE file, and the one file shipkit guarantees exists: loadRepoConfig
-    // refuses a repo without it
-    inputs: ['repo.config.ts'],
-    lint: (t, env) => {
-        const p = join(env.root, CONFIG)
-        if (!existsSync(p)) return void t.ok(`${CONFIG} absent — nothing to narrow`)
-        const src = readFileSync(p, 'utf8')
-        if (!BARREL.test(src)) return void t.ok(`${CONFIG} imports the narrow config module`)
+    description: 'repo.config.ts imports `defineRepo` from the narrow module, never the barrel',
+    owner: 'build/shipkit/config-keys.md',
+    run: (c) => {
+        const src = c.read(CONFIG)
+        if (src == null) return void c.ok(`${CONFIG} absent — nothing to narrow`)
+        if (!BARREL.test(src)) return void c.ok(`${CONFIG} imports the narrow config module`)
         const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
         const symbols = importedSymbols(line)
         const strays = symbols.filter((s) => !CONFIG_SYMBOLS.has(s))
         if (strays.length > 0) {
-            t.fail(`${CONFIG} imports ${strays.join(', ')} from the package barrel, which costs ~400ms of module load on every shipkit run`)
-            return void t.lines.push({ kind: 'fix-fail', text: `move ${strays.join(', ')} to their own module, then import from ${NARROW}` })
+            c.fail(`${CONFIG} imports ${strays.join(', ')} from the package barrel, which costs ~400ms of module load on every shipkit run`)
+            return void c.lines.push({ kind: 'fix-fail', text: `move ${strays.join(', ')} to their own module, then import from ${NARROW}` })
         }
-        t.fail(`${CONFIG} imports from the package barrel (~400ms of module load on every shipkit run, the pre-commit hook included)`)
+        c.fail(`${CONFIG} imports from the package barrel (~400ms of module load on every shipkit run, the pre-commit hook included)`)
     },
-    fix: (env: RuleEnv): FixResult => {
-        const p = join(env.root, CONFIG)
-        if (!existsSync(p)) return { changed: false, summary: `${CONFIG} absent` }
-        const src = readFileSync(p, 'utf8')
+    fix: (c): FixResult => {
+        const src = c.read(CONFIG)
+        if (src == null) return { changed: false, summary: `${CONFIG} absent` }
         if (!BARREL.test(src)) return { changed: false, summary: 'already narrow' }
         const line = src.split('\n').find((l) => /from\s+['"]rvlib-shipkit['"]/.test(l)) ?? ''
         // only rewrite what the narrow module actually exports: silently
         // repointing an import it cannot serve turns a slow gate into a broken one
         if (importedSymbols(line).some((s) => !CONFIG_SYMBOLS.has(s))) return { changed: false, summary: 'imports symbols the narrow module does not export — move them by hand' }
-        atomicWrite(p, src.replace(BARREL, `$1$2'${NARROW}'`))
+        c.write(CONFIG, src.replace(BARREL, `$1$2'${NARROW}'`))
         return { changed: true, summary: `${CONFIG} now imports ${NARROW} (~400ms saved per run)` }
     },
-}
+})
+
+export default configBarrelImport