rvlib-shipkit 0.38.1 → 1.0.0

package/src/check.ts

@@ -0,0 +1,343 @@
+// THE CHECK — one shape for everything a gate runs, and one way to add one.
+//
+// A repo drops `<name>.check.ts` anywhere, default-exports `check({...})`, and
+// it shows up in `shipkit ci`, `shipkit check`, `shipkit checks` and the hub
+// with no config edit. Whether it is a build step, a repo guard or a world
+// probe is what the FIELDS say, never which registry it was put in. The
+// toolkit's own built-ins are the same files under `src/checks/`, walked by
+// the same code (core/discover-checks.ts).
+//
+// Two bodies, one object:
+//   `run`  in process, ONE parameter `c` (core/check-ctx.ts): it reports
+//          through `c.ok/warn/fail` and reads the repo through `c.read`,
+//          `c.list`, `c.use(scan)`, which records what it read
+//   `cmd`  argv, a subprocess, exit code is truth
+//
+// What a check declares about ITSELF is what every surface reads: `blocking`
+// (can it stop you), how it is remembered (`ttl` or `never`, else a `run`
+// check is keyed on what it read and a `cmd` check on its `inputs`), `when`
+// (where it runs), `deps` (what must pass first). The file's own path joins
+// its cache key automatically, so nothing declares its own code.
+import type { CheckCtx } from './core/check-ctx.ts'
+import { parseWhen } from './core/when.ts'
+import type { Line } from './core/wire.ts'
+import type { RepoConfig } from './repo-config.ts'
+
+export { defineScan, mdPages, packageJson, type MdPage, type PackageJson, type Scan } from './scan.ts'
+export type { CheckCtx, ScanCtx } from './core/check-ctx.ts'
+
+/** where a check runs, for the hooks that run BEFORE its body (`cacheKey`) and
+ *  for the legacy shapes. A body gets `c`, which carries both. */
+export type CheckEnv = { root: string; config: RepoConfig }
+
+/** whose check it is: the toolkit ships it, or this repo declared it */
+export type CheckFrom = 'shipkit' | 'repo'
+
+export type FixResult = { changed: boolean; summary: string }
+
+export type CheckDef = {
+    /** the name every surface uses. Default: the file basename without
+     *  `.check.ts`. A built-in carries `SK###`, stable forever, and a repo
+     *  picks its own prefix or plain words. */
+    id?: string
+    /** display sugar, kept because `SK004` alone is unreadable on a row.
+     *  Default: the id. */
+    title?: string
+    /** what MUST BE TRUE, in the present tense: ONE line, at most 90
+     *  characters, as in `package.json routes lint, typecheck and test
+     *  through the gate`. Never what red means, red is its negation. It
+     *  renders at the top of the check page and as the tree row's tooltip.
+     *  A title names the check, this states the invariant it holds. */
+    description: string
+    /** where the answer is OWNED: a wiki page for a built-in, the file itself
+     *  for a repo check. It is the fix pointer floor whenever a failing body
+     *  attached no precise pointer of its own: a file of this repo as it
+     *  stands, a docs page after `docsBase`. Default: the file's
+     *  repo-relative path. */
+    owner?: string
+    /** can this stop you? REQUIRED, no default. true = the failure is about
+     *  THIS repo and blocks. false = it reports the WORLD (a box that is off,
+     *  a cred nobody minted), so the failure prints as a warning and never
+     *  blocks. The only question worth asking about a check, asked once. */
+    blocking: boolean
+    /** the body, in process. `c` is the one parameter: it reports (`c.ok`,
+     *  `c.warn`, `c.fail`), says where (`c.root`, `c.config`, `c.frozen`),
+     *  reads the repo with every read recorded (`c.read`, `c.json`,
+     *  `c.exists`, `c.list`, `c.use(scan)`), and reaches the world (`c.exec`,
+     *  `c.fetch`, `c.tool`). With no `inputs`, `ttl` or `never`, the answer is
+     *  cached on what it read. One of `run` or `cmd`, never both. */
+    run?: (c: CheckCtx) => void | Promise<void>
+    /** a TOOL run as the body: argv without a shell, the repo root as the
+     *  working directory (`bun run build`, `tsc`). The exit code is truth: a
+     *  non-zero exit with no `FAIL:` line still fails loud. It never names the
+     *  check file itself: a body of the file's own is `run` (SK020). */
+    cmd?: string[]
+    /** a BUILD STEP: `shipkit ci` runs it, the health pass never does. The
+     *  gate asks "is my change good" and builds, `shipkit check` asks "is
+     *  this repo healthy" and reports, and a tool chain has no business in
+     *  the second question. A floor slot derives it, a file declares it, and
+     *  it takes the 600s ceiling rather than the 120s one. `when` stays about
+     *  TIME (always, release, health, off). A build step on `health` is an
+     *  opt in one: the gate parks it and `shipkit ci --with <id>` runs it. */
+    build?: boolean
+    /** check ids that must pass first. One runner runs every check as one DAG,
+     *  so a check naming none is a root of it, and a dep doubles as the race
+     *  guard between two checks that touch one file. */
+    deps?: string[]
+    /** WHERE it runs: `always`, `release`, `health`, `off:<reason>`. The
+     *  repo's `when: {}` map wins over it, so a config can move a check the
+     *  repo does not own (core/when.ts owns the vocabulary). */
+    when?: string
+    /** CONTENT population: the repo-relative paths this check reads, so a
+     *  cached answer is honest while they do not move. For a `cmd` check,
+     *  whose subprocess reads what it likes. A `run` check that declares none
+     *  of `inputs`, `ttl` and `never` is keyed on what it READ through `c`
+     *  instead, the `reads` population (ledger/git-key.ts). A `cmd` check
+     *  that declares none runs every time, which costs speed and never
+     *  correctness. At most one of the three. */
+    inputs?: string[]
+    /** WORLD population: nothing on disk describes the answer, so a clean
+     *  pass keeps for this long, as in '24h'. */
+    ttl?: string
+    /** a DECIDED never-cacheable, with the reason. Says somebody looked and
+     *  no key can describe this, which takes it off the burn-down list. */
+    never?: string
+    /** it REWRITES the repo while it runs (updates a dependency, untracks a
+     *  file) unless the run is frozen, so a frozen run asks it a different
+     *  question: only a check declaring this carries `frozen` in its cache
+     *  key, and every other check shares one answer between a frozen run and
+     *  a normal one. Declared, never guessed from the body. */
+    writes?: boolean
+    /** cache-identity contribution for a `ttl` check whose verdict depends on
+     *  config: a changed key busts the answer instantly instead of serving
+     *  a stale cached assertion for the rest of the TTL. */
+    cacheKey?: (env: CheckEnv) => string
+    /** idempotent auto-repair, never interactive. `shipkit check --fix <id>`
+     *  applies it, then re-runs the check. It gets the same `c` as the body,
+     *  writes with `c.write` and `c.remove`, and is never cached. An `fs`
+     *  import in the check file would keep an undeclared body off its reads
+     *  (core/raw-access.ts). A repair that needs
+     *  judgement stays a FAIL with a pointer. */
+    fix?: (c: CheckCtx) => FixResult | Promise<FixResult>
+    /** wall clock ceiling in ms. A `cmd` check is killed with its whole
+     *  process tree at the ceiling. */
+    timeoutMs?: number
+    /** a label several checks share, so `--skip <group>` parks all of them
+     *  and `--only <group>` runs all of them. */
+    group?: string
+    /** extra environment for a `cmd` check, merged over the run's own. */
+    env?: Record<string, string>
+    /** working directory for a `cmd` check (default: the repo root). */
+    cwd?: string
+}
+
+/** the longest description a row can show whole */
+export const DESCRIPTION_MAX = 90
+
+/** what is wrong with a description, or null when it states an invariant
+ *  the way every surface expects: one line, short, the fact that must hold.
+ *  A red-means clause is refused because red is always the negation. */
+export function descriptionProblem(description: unknown): string | null {
+    if (typeof description !== 'string' || description.trim() === '')
+        return 'description is required: ONE line stating what must be true'
+    const d = description.trim()
+    if (/[\r\n]/.test(d)) return 'description must be ONE line'
+    if (d.length > DESCRIPTION_MAX) return `description is ${d.length} characters, the limit is ${DESCRIPTION_MAX}: state only what must be true`
+    if (/^this checks\b/i.test(d)) return `description states what must be true, with no 'this checks' opener`
+    if (/\b(red|yellow|green|a warning|warn)( one)? means\b|\ba red one\b/i.test(d))
+        return 'description states what must be true, never what red means (red is its negation)'
+    return null
+}
+
+/** the first candidate the shape accepts. A generated row states its
+ *  invariant from what it knows, and falls back to a shorter spelling when a
+ *  long path or argv would break the line limit */
+export function describeFirst(...candidates: (string | null | undefined)[]): string {
+    for (const d of candidates) if (d != null && descriptionProblem(d) == null) return d.trim()
+    throw new Error(`no description candidate passes the shape: ${candidates.map((d) => JSON.stringify(d)).join(', ')}`)
+}
+
+/** THE way a check file declares itself. It validates the shape at import
+ *  time, so a malformed check dies when discovery loads it and never mid
+ *  gate. The id, the title and the owner are filled in by discovery, which
+ *  is the only thing that knows the file's name and place. */
+export function check(d: CheckDef): CheckDef {
+    const has = (k: keyof CheckDef): boolean => d[k] != null
+    const name = d.id == null ? '' : ` ${d.id}`
+    const bad = descriptionProblem(d.description)
+    if (bad != null) throw new Error(`check${name}: ${bad}`)
+    if (typeof d.blocking !== 'boolean')
+        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: blocking is required — true (about this repo, it stops you) or false (about the world, it warns)`)
+    if (has('run') === has('cmd'))
+        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: declare exactly one body, \`run\` (in process) or \`cmd\` (argv)`)
+    const populations = (['inputs', 'ttl', 'never'] as const).filter((k) => has(k))
+    if (populations.length > 1)
+        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: ${populations.join(' and ')} contradict each other — a check reads files, or the world, or nothing can describe it`)
+    if (d.when != null) {
+        const w = parseWhen(d.when)
+        if (typeof w === 'string') throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: when ${w}`)
+    }
+    return d
+}
+
+// ── the legacy TASK shape, for the compatibility window ──────────────────
+// A repo still declaring build steps through `repo.config.ts tasks: []`, and
+// every repo decorating a floor slot through `defaults`, writes this one. It
+// is read as a check whose body is its `cmd` or its `logic`, and it dies with
+// those keys once `shipkit fleet` shows no repo below 0.40.
+
+export type TaskDef = {
+    /** the name every surface uses: the gate line, `--only`, `--skip`, a
+     *  `deps` entry, a `when` key and the ledger row. Unique in the repo. */
+    id: string
+    /** one line stating what must be true (the shape: descriptionProblem).
+     *  A floor slot and a unit test check get theirs from the
+     *  generator, a task that names none reads as its command exiting 0 */
+    description?: string
+    /** argv, run without a shell. One of `cmd` or `logic` per task. */
+    cmd?: string[]
+    /** the body as a function, for work that is already TypeScript. It gets
+     *  the wire context, so it reports `ok:` / `WARN` / `FAIL:` lines the way
+     *  a subprocess does. The legacy spelling of a check's `run`. */
+    logic?: (t: CheckCtx) => unknown
+    /** ids that must pass first. The DAG runs everything else in parallel, so
+     *  a dep doubles as the race guard between two that touch one file. */
+    deps?: string[]
+    /** extra environment for a `cmd` task, merged over the run's own */
+    env?: Record<string, string>
+    /** working directory for a `cmd` task (default: the repo root) */
+    cwd?: string
+    /** a label several tasks share, so `--skip <group>` parks all of them at
+     *  once (a local bench, a slow integration tier). */
+    group?: string
+    /** DEPRECATED, read into `when` as `health`: out of the gate until
+     *  `--with <id>` names it. */
+    optIn?: boolean
+    /** wall clock ceiling in ms, default 600000 for a build step. One that
+     *  hits it is killed with its whole process tree, because the cmd is
+     *  usually a wrapper. */
+    timeoutMs?: number
+    /** CONTENT population: the repo-relative paths this task reads. Declaring
+     *  them is what makes it keyable (ledger/git-key.ts). Undeclared is the
+     *  DEFAULT and means never cached, so forgetting one costs speed and
+     *  never correctness. A list MISSING a path the command reads is the one
+     *  that costs correctness: the key cannot move when that path changes, so
+     *  a cached answer comes back over a tree it no longer describes. `['.']` is the
+     *  whole TRACKED tree, and it is NOT a catch-all: an ignored path enters a
+     *  key by name and never by content, so a task reading a gitignored
+     *  fixture, a built dir or a .env under declares with `['.']` exactly as
+     *  it would with a narrow list. */
+    inputs?: string[]
+    /** WORLD population: it reads the network, a keychain, $PATH or the clock,
+     *  so nothing on disk describes its answer and a clean pass is remembered
+     *  for this long, as in '24h'. */
+    ttl?: string
+    /** a DECIDED never-cacheable, with the reason. */
+    never?: string
+}
+
+/** every field a `TaskDef` may carry. Declared as a value so `defineRepo` can
+ *  refuse a typo inside a `defaults` slot: a slot with no `cmd` DECORATES the
+ *  resolved task, so a misspelled field is not a type error at the call site
+ *  and would land as a task that is quietly never cached. Add a field above,
+ *  add it here. */
+export const TASK_DEF_KEYS = ['id', 'cmd', 'logic', 'deps', 'env', 'cwd', 'group', 'optIn', 'timeoutMs', 'inputs', 'ttl', 'never'] as const
+
+// ── the legacy rule shape, for the compatibility window ──────────────────
+// A repo still registering through `repo.config.ts rules: []` writes this
+// one. It is read as a check whose body is `lint`, and it dies with that key
+// once `shipkit fleet` shows no repo below 0.40.
+
+export type RuleEnv = CheckEnv
+
+export type Rule = {
+    /** stable PREFIX + 3 digits, never reused or renumbered. `SK###` is
+     *  reserved for the toolkit, so a repo picks its own (`RV###`). A check
+     *  FILE takes its id from its name and may use plain words instead. */
+    id: string
+    /** display name, stable: the row in STATUS.md, the TUI, the suite cache */
+    title: string
+    /** can this stop you? REQUIRED, no default, exactly as a check declares it */
+    blocking: boolean
+    /** wiki page owning the invariant — the body runner appends
+     *  `docsBase + owner` as the fix: pointer whenever a failing lint
+     *  attached none. A check file defaults this to its own path. */
+    owner: string
+    /** WORLD population: clean-pass cache duration for a rule that probes the
+     *  network, as in '24h'. A skip, a WARN and a FAIL are never cached. */
+    ttl?: string
+    /** CONTENT population: the repo-relative paths this rule reads. Neither
+     *  `inputs` nor `ttl` means never cached, which is the safe default, and
+     *  declaring both is a registration failure. */
+    inputs?: string[]
+    /** repo-relative entry file(s) of this rule's OWN code, so fixing a bug in
+     *  the rule moves its key. A check FILE needs none: its own path is its
+     *  closure, which is the field this shape exists without. */
+    code?: string[]
+    /** a DECIDED never-cacheable, with the reason: it reads git history, a
+     *  path outside the repo, or the wall clock, so no key can describe it. */
+    never?: string
+    /** cache-identity contribution for a TTL'd rule whose verdict depends on
+     *  config: a changed key busts the answer instead of serving it cached */
+    cacheKey?: (env: RuleEnv) => string
+    /** the invariant itself, the legacy spelling of a check's `run` */
+    lint: (t: CheckCtx, env: RuleEnv) => void | Promise<void>
+    /** idempotent auto-repair, never interactive. `check --fix` applies it */
+    fix?: (env: RuleEnv) => FixResult | Promise<FixResult>
+}
+
+// ── running a body, and what every line it prints carries ────────────────
+
+/** the config part of a check's cache identity. Where it RUNS is part of it:
+ *  moving one off the gate, or editing the reason it is off, has to ask the
+ *  question again rather than serve the cached answer from before the move. */
+export function checkCacheExtra(u: { id: string; cacheKey?: (env: CheckEnv) => string }, env: CheckEnv, at: { at: string; reason: string | null; source: string }): string | undefined {
+    const key = u.cacheKey?.(env)
+    if (at.source === 'default') return key
+    return at.at === 'off' ? `${key ?? ''}|exempt:${at.reason ?? ''}` : `${key ?? ''}|when:${at.at}`
+}
+
+/** THE one way to run an in-process body (the check suite and the `--fix`
+ *  runner both come through here): a throwing body still fails with its id,
+ *  a failing or warning run always carries at least one `fix:` pointer (the
+ *  body's own precise ones win, else `docsBase` plus the check's owner), and
+ *  every line gets tagged. */
+export async function runCheckBody(
+    u: { id: string; title: string; owner: string; run?: CheckDef['run']; fix?: unknown },
+    c: CheckCtx,
+    /** the check is OFF: it still enters the suite, so the reason stays
+     *  visible in every output instead of the row disappearing from the list */
+    off?: { reason: string | null },
+): Promise<void> {
+    if (off != null) {
+        c.lines.push({ kind: 'skip', text: `${u.id} exempt: ${off.reason ?? ''}` })
+        c.lines = tagCheckLines(u, c.lines)
+        return
+    }
+    try {
+        await u.run?.(c)
+    } catch (e) {
+        // a 429 is no answer at all, so it warns and nothing remembers it
+        if (e instanceof Error && e.name === 'RateLimited') c.unreachable(`${u.title} not checked this run (${e.message}), retry later`)
+        else c.fail(`${u.title} body errored (${String(e).slice(0, 200)}) — network down, or a bug in this check`)
+    }
+    // the pass's config, never `c.config`: the pointer is the runner's line,
+    // and it must not enter the body's read set
+    if ((c.failed || c.warned) && !c.lines.some((l) => l.kind === 'fix-fail' || l.kind === 'fix-warn'))
+        c.lines.push({ kind: c.failed ? 'fix-fail' : 'fix-warn', text: c.ownerPointer(u.owner) })
+    c.lines = tagCheckLines(u, c.lines)
+}
+
+/** tag every severity line with the check id; a fix pointer of a fixable check
+ *  advertises the autofix. Idempotent, since an already-tagged line passes
+ *  back through here on a cached suite replay. */
+export function tagCheckLines(u: { id: string; fix?: unknown }, lines: Line[]): Line[] {
+    return lines.map((l) => {
+        if (l.kind === 'fix-warn' || l.kind === 'fix-fail')
+            return u.fix == null || l.text.includes('--fix ')
+                ? l
+                : { ...l, text: `${l.text} · autofix: shipkit check --fix ${u.id}` }
+        if (l.kind === 'note') return l
+        return l.text.startsWith(`[${u.id}]`) ? l : { ...l, text: `[${u.id}] ${l.text}` }
+    })
+}

package/src/{rules/SK001-package-json-shape.ts → checks/SK001-package-json-shape.check.ts}

@@ -1,21 +1,20 @@
 // SK001 — canonical package.json shape (meta/rv-conventions/package-json.md):
 // private:true, no license, capability-required script names FAIL, banned
 // aliases + missing baseline scripts WARN. Blocking, so it runs in `shipkit
-// ci` like every other rule. Pure local fs, no TTL.
+// ci` like every other rule. It reads only through `c`, so it is cached on
+// what it read: package.json, the probes below, the test file listing, and
+// whatever the floor resolution read.
 //
 // It also enforces the package.json half of ONE WAY IN (build/shipkit.md):
 // `test`, `lint` and `typecheck` ROUTE to `shipkit ci --only <id>` and the
 // tool body they used to hold sits at `<id>:raw`. That is what makes a cache
 // worth having: `bun run test` is the reflex, and the reflex has to land in
 // shipkit rather than beside it.
-import { existsSync, readdirSync, readFileSync } from 'fs'
-import { join } from 'path'
 import { canonicalBodies, conditionalBodies, inferBin, ROUTED_SCRIPTS, rawName, routedBody, routesToShipkit } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
-import { resolveFloor } from '../core/floor.ts'
+import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
 import type { RepoConfig } from '../repo-config.ts'
-import type { FixResult, Rule, RuleEnv } from './rule.ts'
-import { atomicWrite } from '../core/locked-write.ts'
+import { check, type FixResult } from '../check.ts'
 
 type Pkg = { name?: string; private?: boolean; license?: string; scripts?: Record<string, string> }
 
@@ -35,10 +34,13 @@ 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> {
+export function evaluatePackageJson(t: CheckCtx): void {
+    const c = t.config
     let pkg: Pkg
     try {
-        pkg = (await Bun.file(join(root, 'package.json')).json()) as Pkg
+        const read = t.json<Pkg>('package.json')
+        if (read == null) throw new Error('no package.json')
+        pkg = read
     } catch (e) {
         t.fail(`package.json unreadable (${String(e).slice(0, 120)})`)
         return
@@ -72,7 +74,7 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
 
     const has = (name: string): boolean => scripts[name] != null || aliased.has(name)
 
-    const required = requiredScripts(root, c)
+    const required = requiredScripts(t)
     const missing = required.filter((r) => !has(r.name))
     for (const m of missing) t.fail(`package.json: missing script '${m.name}' (${m.why})`)
 
@@ -80,7 +82,7 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
     // reason a cache gets bypassed: an agent types `bun run test` and shipkit
     // never hears about it. A slot the repo turned off has no shipkit task to
     // route to, so it is not governed.
-    const floor = resolveFloor(c, root)
+    const floor = resolveFloor(c, t.root, checkFloorReader(t))
     for (const id of ROUTED_SCRIPTS) {
         if (routedExempt(c).has(id) || c.defaults?.[id] === false) continue
         const body = scripts[id]
@@ -90,13 +92,13 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
             continue
         }
         const gap = floor.unfilled.find((u) => u.id === id)
-        if (gap != null) t.fail(`package.json: ${gap.reason} — \`bun run ${id}\` would measure nothing`)
+        if (gap != null) t.fail(`package.json: ${gap.reason} — \`bun run ${id}\` would run nothing`)
     }
 
     // `test` is asked for only once the repo HAS tests: the fixer deliberately
     // refuses to scaffold it before that (a fixer never manufactures a
     // failure), so nagging for it would be a WARN no machine may clear
-    const baseline = BASELINE.filter((n) => n !== 'test' || hasTestFiles(root))
+    const baseline = BASELINE.filter((n) => n !== 'test' || hasTestFiles(testFiles(t)))
     const missingBaseline = baseline.filter((n) => !has(n))
     if (missingBaseline.length > 0)
         t.warn(`package.json: missing baseline script(s): ${missingBaseline.join(', ')}`)
@@ -111,13 +113,13 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
 // a shipkit verb is never on this list. `shipkit ci`, `check`, `contracts`,
 // `tui`, `mv`, `assets`, `asks` are typed as themselves, and a package.json
 // row that only forwards to one is a second name for one capability
-function requiredScripts(root: string, _c: RepoConfig): Array<{ name: string; why: string }> {
+function requiredScripts(c: CheckCtx): Array<{ name: string; why: string }> {
     const required: Array<{ name: string; why: string }> = [
         // watch-mode serve — the ONE shipkit surface the bare verb cannot give
         { name: 'hub', why: 'shipkit repo' },
     ]
-    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 (c.exists('.shipkit/comfy')) required.push({ name: 'comfy:up', why: '.shipkit/comfy/ exists' })
+    if (c.exists('deploy.sh')) required.push({ name: 'up', why: 'deploy.sh exists' })
     return required
 }
 
@@ -145,42 +147,36 @@ function routedExempt(c: RepoConfig): Set<string> {
 }
 
 const TEST_SKIP = new Set(['node_modules', 'dist', 'tmp', 'references', 'coverage'])
-
-/** any `*.test.ts` in the repo, so the test script is only scaffolded once it
- *  has something to run */
-export function hasTestFiles(root: string): boolean {
-    const walk = (dir: string, depth: number): boolean => {
-        if (depth > 4) return false
-        let entries
-        try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return false }
-        for (const e of entries) {
-            if (e.isDirectory()) { if (!TEST_SKIP.has(e.name) && !e.name.startsWith('.') && walk(join(dir, e.name), depth + 1)) return true }
-            else if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(e.name)) return true
-        }
-        return false
-    }
-    return walk(root, 0)
+const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/
+
+/** the repo's test file candidates as git sees them, one recorded listing:
+ *  a new test file reruns the check, an edit anywhere else does not */
+const testFiles = (c: CheckCtx): string[] => c.list('**/*.{test,spec}.*')
+
+/** any `*.test.ts` among these repo-relative paths, outside installs, build
+ *  output and dot dirs, so the test script is only scaffolded once it has
+ *  something to run */
+export function hasTestFiles(paths: readonly string[]): boolean {
+    return paths.some((f) => {
+        const parts = f.split('/')
+        return TEST_FILE.test(parts.at(-1)!) && parts.slice(0, -1).every((d) => !TEST_SKIP.has(d) && !d.startsWith('.'))
+    })
 }
 
-export const packageJsonShape: Rule = {
+export const packageJsonShape = check({
     id: 'SK001',
     blocking: true,
     title: 'package.json',
+    description: 'package.json routes lint, typecheck and test through the gate',
     owner: OWNER,
-    // the whole tree: package.json is most of it, but the baseline-script
-    // check also walks the repo for a `*.test.ts` and probes `.rv-comfy`
-    // and `deploy.sh`, so naming three files would key it on less than it
-    // reads
-    inputs: ['.'],
-    lint: (t: CheckCtx, env: RuleEnv) => evaluatePackageJson(t, env.root, env.config),
+    run: (c) => evaluatePackageJson(c),
     // 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')
+    fix: (c): FixResult => {
+        const raw = c.read('package.json')
+        if (raw == null) return { changed: false, summary: 'no package.json — nothing to fix' }
         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' }
@@ -207,7 +203,7 @@ export const packageJsonShape: Rule = {
         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))) {
+        for (const m of requiredScripts(c).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
@@ -216,13 +212,13 @@ export const packageJsonShape: Rule = {
         // only once the repo HAS tests. `bun test` exits non-zero when it finds
         // none, so scaffolding this into a repo without any turns the gate red
         // on work the fixer itself did. a fixer must never manufacture a failure.
-        if (pkg.scripts['test'] == null && hasTestFiles(env.root)) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        if (pkg.scripts['test'] == null && hasTestFiles(testFiles(c))) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
         // ONE WAY IN, last so it also routes whatever this pass just added:
         // the tool body slides to `<id>:raw` and `<id>` becomes the shipkit
         // call. Both keys keep their place in the file, so the diff a human
         // reads is the two lines that changed and not a reordered block
         for (const id of ROUTED_SCRIPTS) {
-            if (routedExempt(env.config).has(id) || env.config.defaults?.[id] === false) continue
+            if (routedExempt(c.config).has(id) || c.config.defaults?.[id] === false) continue
             const body = pkg.scripts[id]
             if (body == null || routesToShipkit(body)) continue
             const raw = rawName(id)
@@ -236,7 +232,7 @@ export const packageJsonShape: Rule = {
         }
         if (changes.length > 0) {
             const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
-            atomicWrite(pkgPath, JSON.stringify(pkg, null, indent) + '\n')
+            c.write('package.json', JSON.stringify(pkg, null, indent) + '\n')
         }
         const summary = [
             changes.length > 0 ? changes.join(', ') : 'nothing mechanical to change',
@@ -245,4 +241,6 @@ export const packageJsonShape: Rule = {
         ].join(' · ')
         return { changed: changes.length > 0, summary }
     },
-}
+})
+
+export default packageJsonShape

package/src/checks/SK002-contracts-fulfillness.check.ts

@@ -0,0 +1,24 @@
+// SK002 — .shipkit/* 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` check) tags with this id via
+// contracts/apply-contracts.ts.
+import { applyContractsResult, contractsResult } from '../contracts/apply-contracts.ts'
+import { check } from '../check.ts'
+
+export const contractsFulfillness = check({
+    id: 'SK002',
+    blocking: true,
+    title: 'contracts',
+    description: 'every declared venue has a complete contract folder',
+    owner: 'meta/contracts.md',
+    // keyed on what the contracts read: each artifact, each detector, and each
+    // folder a glob walked through `c.entries`, a gitignored one included
+    run: async (c) => {
+        applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
+    },
+})
+
+export default contractsFulfillness

package/src/checks/SK003-claude-md-shape.check.ts

@@ -0,0 +1,66 @@
+// 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 rule asserts no base include path of its own: `shipkit start` owns
+// which one lands (its house template, or `--include`). A repo with neither
+// CLAUDE.md nor agent/ is not a two-line-contract repo and passes.
+import { check, type FixResult } from '../check.ts'
+
+/** the repo router line, always LAST: start writes it whenever agent/index.md exists */
+export const AGENT_LINE = '@./agent/index.md'
+const LOCAL_LINE = '@./CLAUDE.local.md'
+
+export const claudeMdShape = check({
+    id: 'SK003',
+    blocking: true,
+    title: 'CLAUDE.md',
+    description: 'CLAUDE.md loads the house wiki into every session',
+    owner: 'meta/agent-folder.md',
+    // keyed on what it reads: CLAUDE.md and whether agent/index.md exists. The
+    // gitignore probe runs git, so an answer that took it is never stored
+    run: async (c) => {
+        const hasAgent = c.exists('agent/index.md')
+        const claude = c.read('CLAUDE.md')
+        if (claude == null) {
+            if (hasAgent) c.fail(`agent/index.md exists but there is no CLAUDE.md routing it — the two-line contract wants ${AGENT_LINE}`)
+            else c.ok('no CLAUDE.md / agent — not a two-line-contract repo')
+            return
+        }
+        const lines = claude.split('\n').filter((l) => l.trim() !== '')
+        const includes = lines.filter((l) => l.startsWith('@'))
+        const prose = lines.length - includes.length
+        if (prose > 0)
+            c.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)
+            c.fail(`CLAUDE.md has ${includes.length} include lines — the contract is 2: base context, then ${AGENT_LINE}`)
+        if (hasAgent && !lines.includes(AGENT_LINE))
+            c.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)
+            c.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 c.exec(['git', 'check-ignore', '-q', 'CLAUDE.local.md'], { cwd: c.root, timeoutMs: 5_000 })
+            if (r.code === 1)
+                c.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)
+                c.note(`CLAUDE.local.md gitignore not verifiable (git says: ${r.out.trim().split('\n')[0] ?? `exit ${r.code}`})`)
+        }
+        if (!c.failed) c.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: (c): FixResult => {
+        if (!c.exists('agent/index.md')) return { changed: false, summary: 'no agent/index.md — nothing mechanical to fix' }
+        const cur = c.read('CLAUDE.md')
+        if (cur == null) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start <name> writes it), not autofixable' }
+        if (cur.split('\n').includes(AGENT_LINE)) return { changed: false, summary: `${AGENT_LINE} already routed — remaining findings need a human` }
+        c.write('CLAUDE.md', `${cur.endsWith('\n') || cur === '' ? cur : `${cur}\n`}${AGENT_LINE}\n`)
+        return { changed: true, summary: `${AGENT_LINE} appended as the last line` }
+    },
+})
+
+export default claudeMdShape