rvlib-shipkit 0.13.0 → 0.16.0

package/src/release/units.ts

@@ -0,0 +1,246 @@
+// a repo is N releasable units. The ROOT unit is mandatory, never declared,
+// and configured by `release`. Sub-units are optional, exist only as entries
+// in `units[]`, and are configured by their own entry. Nothing is scanned
+// into existence: an undeclared package is caught by rule SK010, so
+// resolution stays deterministic and a forgotten package still cannot hide.
+//
+// This module is THE source of unit facts. Every surface that used to
+// rediscover packages (drift probes, per-lib tests, per-lib typecheck, the
+// stranded-tag probe) reads it instead of walking the tree with its own rules.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { basename, join, relative } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type ReleaseUnitDecl = {
+    /** repo-relative directory holding the unit's package.json — the only required key */
+    dir: string
+    /** default: basename(dir) */
+    id?: string
+    /** tag template, `{name}` and `{version}` substituted (default '{name}@{version}') */
+    tag?: string
+    /** repo-relative changelog (default '<dir>/CHANGELOG.md') */
+    changelog?: string
+    /** publish this sub-unit to npm. REQUIRED unless its package.json says
+     *  `private: true`: the npm target is declared, never inferred, and the
+     *  ambiguous package REFUSES rather than defaulting to the quiet answer.
+     *  `true` on a private package.json is a resolution FAILURE */
+    npm?: boolean
+    /** cut a GitHub release for this unit's tag (default false for sub-units) */
+    githubRelease?: boolean
+    /** repo-relative tsconfig for the unit's own typecheck (default '<dir>/tsconfig.json' when it exists) */
+    tsconfig?: string
+}
+
+export const UNIT_DECL_KEYS: readonly string[] = ['dir', 'id', 'tag', 'changelog', 'npm', 'githubRelease', 'tsconfig']
+
+/** a unit, fully resolved: no optionals, no defaults left to re-apply downstream */
+export type ReleaseUnit = {
+    id: string
+    /** absolute */
+    dir: string
+    /** repo-relative git pathspec, '' for the root */
+    rel: string
+    name: string
+    /** package.json version — THE only version source */
+    version: string
+    /** absolute path to the versioned changelog */
+    changelog: string
+    /** tag template, `{name}` and `{version}` unsubstituted — bump renders the NEXT tag from it */
+    tagTemplate: string
+    /** rendered tag for the current version */
+    tag: string
+    /** the tag template with `{version}` replaced by `*` — feeds the stranded-tag probe */
+    tagGlob: string
+    targets: { npm: boolean; tag: boolean; githubRelease: boolean }
+    /** the unit's OWN package.json `private: true`, never the repo's visibility */
+    isPrivate: boolean
+    /** absolute path, or null when the unit has no tsconfig of its own */
+    tsconfig: string | null
+}
+
+/** a unit that could not be described, and why. Scoped by id because the two
+ *  cases differ: a broken DECLARED unit is a repo-wide declaration bug (rule
+ *  SK010), while a root package that is not release-shaped only matters the
+ *  day someone releases it. */
+export type UnitError = { id: string; message: string }
+
+export type UnitResolution = {
+    /** every unit that resolved — a broken sibling never hides the working ones */
+    units: ReleaseUnit[]
+    /** non-empty means no release of the named unit may proceed */
+    errors: UnitError[]
+}
+
+export const formatUnitError = (e: UnitError): string => `unit '${e.id}': ${e.message}`
+
+const ROOT_TAG = 'v{version}'
+const SUB_TAG = '{name}@{version}'
+
+const render = (template: string, p: { name: string; version: string }): string =>
+    template.replaceAll('{name}', p.name).replaceAll('{version}', p.version)
+
+type Pkg = { name?: string; version?: string; private?: boolean; scripts?: Record<string, string> }
+
+function readPkg(dir: string): { pkg: Pkg } | { error: string } {
+    const p = join(dir, 'package.json')
+    if (!existsSync(p)) return { error: `no package.json in ${dir}` }
+    try { return { pkg: JSON.parse(readFileSync(p, 'utf8')) as Pkg } }
+    catch (e) { return { error: `${p} is unparseable (${String(e).slice(0, 120)})` } }
+}
+
+/** every releasable unit, root first then the declared sub-units in declared
+ *  order. Release ORDER is different (releaseOrder below) — the root ships
+ *  last because it depends on its sub-units, never the reverse. */
+export function resolveUnits(root: string, config: RepoConfig): UnitResolution {
+    const errors: UnitError[] = []
+    const units: ReleaseUnit[] = []
+    const rc = config.release ?? {}
+
+    const rootPkg = readPkg(root)
+    if ('error' in rootPkg) errors.push({ id: 'root', message: `${rootPkg.error} — release reads name and version from it` })
+    else {
+        const u = build({
+            root,
+            id: 'root',
+            dir: root,
+            pkg: rootPkg.pkg,
+            tagTemplate: rc.tag ?? ROOT_TAG,
+            changelogRel: rc.changelog ?? 'CHANGELOG.md',
+            npm: rc.npm,
+            // the root IS the repo: its package.json private flag is the whole
+            // declaration, and a public root package publishes by default
+            npmWhenUndeclared: 'from-private-flag',
+            githubRelease: rc.githubRelease ?? true,
+            tsconfigRel: rc.tsconfig,
+            checkFolderName: false,
+        })
+        if ('error' in u) errors.push(...u.error)
+        else units.push(u.unit)
+    }
+
+    const seen = new Set<string>(['root'])
+    for (const decl of config.units ?? []) {
+        const id = decl.id ?? (typeof decl.dir === 'string' ? basename(decl.dir) : '?')
+        const bad = Object.keys(decl).filter((k) => !UNIT_DECL_KEYS.includes(k))
+        if (bad.length > 0) { errors.push({ id, message: `unknown key(s) ${bad.join(', ')} (known: ${UNIT_DECL_KEYS.join(', ')})` }); continue }
+        if (typeof decl.dir !== 'string' || decl.dir === '') { errors.push({ id, message: 'every units[] entry needs a `dir`' }); continue }
+        const dir = join(root, decl.dir)
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) { errors.push({ id, message: `'${decl.dir}' is not a directory` }); continue }
+        if (seen.has(id)) { errors.push({ id, message: `duplicate unit id — give '${decl.dir}' an explicit id` }); continue }
+        seen.add(id)
+        const pkg = readPkg(dir)
+        if ('error' in pkg) { errors.push({ id, message: pkg.error }); continue }
+        const u = build({
+            root,
+            id,
+            dir,
+            pkg: pkg.pkg,
+            tagTemplate: decl.tag ?? SUB_TAG,
+            changelogRel: decl.changelog ?? `${decl.dir}/CHANGELOG.md`,
+            npm: decl.npm,
+            npmWhenUndeclared: 'refuse',
+            githubRelease: decl.githubRelease ?? false,
+            tsconfigRel: decl.tsconfig,
+            // only the DEFAULT tag renders the package name into a git tag, so
+            // only there does the folder have to agree with it
+            checkFolderName: decl.tag == null,
+        })
+        if ('error' in u) errors.push(...u.error)
+        else units.push(u.unit)
+    }
+    return { units, errors }
+}
+
+function build(p: {
+    root: string
+    id: string
+    dir: string
+    pkg: Pkg
+    tagTemplate: string
+    changelogRel: string
+    npm: boolean | undefined
+    /** how an UNDECLARED npm target resolves. The root IS the repo, so its
+     *  package.json private flag is the whole declaration. A sub-unit has no
+     *  such declaration, so a non-private package with no `npm` key is
+     *  ambiguous and REFUSES. */
+    npmWhenUndeclared: 'from-private-flag' | 'refuse'
+    githubRelease: boolean
+    tsconfigRel: string | undefined
+    checkFolderName: boolean
+}): { unit: ReleaseUnit } | { error: UnitError[] } {
+    const errors: UnitError[] = []
+    const at = (message: string): UnitError => ({ id: p.id, message })
+    const name = p.pkg.name ?? ''
+    const version = p.pkg.version ?? ''
+    if (name === '' || version === '') errors.push(at('package.json needs both name and version'))
+    // under the default template the package NAME becomes the git tag, so the
+    // folder it lives in must be findable from that tag. A scope satisfies it
+    // (`@acme/thing` in `thing/`), and an explicit `tag` opts out entirely.
+    const base = basename(p.dir)
+    if (p.checkFolderName && name !== '' && name !== base && !name.endsWith(`/${base}`))
+        errors.push(at(`package name '${name}' must equal the folder name '${base}' (a scope is fine: '@scope/${base}') — or declare an explicit \`tag\` for this unit`))
+    const isPrivate = p.pkg.private === true
+    // npm's own unconditional refusal. Declaring npm:true on top of it is a
+    // contradiction, not a preference — surface it instead of silently winning
+    if (p.npm === true && isPrivate)
+        errors.push(at('npm: true but package.json says private: true — drop one, npm refuses the publish either way'))
+    // "declared, never inferred" cuts BOTH ways: the package nobody decided
+    // about must refuse, not quietly resolve to no-publish. A silent false
+    // here is a lib that bumps, tags and cuts a release while publishing
+    // nothing, and the only trace is one note line in a long log.
+    if (p.npm == null && !isPrivate && p.npmWhenUndeclared === 'refuse')
+        errors.push(at('package.json is not private and this units[] entry does not say `npm` — add `npm: true` to publish it, or `private: true` to its package.json to keep it internal'))
+    if (errors.length > 0) return { error: errors }
+    const declaredNpm = p.npm ?? (p.npmWhenUndeclared === 'from-private-flag' && !isPrivate)
+    const tsconfig = p.tsconfigRel != null ? join(p.root, p.tsconfigRel) : join(p.dir, 'tsconfig.json')
+    return {
+        unit: {
+            id: p.id,
+            dir: p.dir,
+            rel: relative(p.root, p.dir),
+            name,
+            version,
+            changelog: join(p.root, p.changelogRel),
+            tagTemplate: p.tagTemplate,
+            tag: render(p.tagTemplate, { name, version }),
+            tagGlob: render(p.tagTemplate, { name, version: '*' }),
+            // the `!isPrivate` is a belt over the declaration: a private
+            // package never publishes, whatever anything else says
+            targets: { npm: declaredNpm && !isPrivate, tag: true, githubRelease: p.githubRelease },
+            isPrivate,
+            tsconfig: existsSync(tsconfig) ? tsconfig : null,
+        },
+    }
+}
+
+/** publish order: sub-units first, the root last. The root depends on what
+ *  ships inside it, so a consumer that sees the root tag can already resolve
+ *  every sub-unit it names. */
+export function releaseOrder(units: ReleaseUnit[]): ReleaseUnit[] {
+    return [...units.filter((u) => u.id !== 'root'), ...units.filter((u) => u.id === 'root')]
+}
+
+export const unitById = (units: ReleaseUnit[], id: string): ReleaseUnit | undefined => units.find((u) => u.id === id)
+
+/** the tag this unit WOULD carry at another version — bump needs it before it
+ *  writes, to refuse on a tag that already exists */
+export const renderTag = (unit: ReleaseUnit, version: string): string => render(unit.tagTemplate, { name: unit.name, version })
+
+/** every tag shape this repo produces, as git globs — the stranded-tag probe
+ *  reads this instead of hardcoding one prefix and going blind to the others */
+export const tagGlobs = (units: ReleaseUnit[]): string[] => [...new Set(units.map((u) => u.tagGlob))]
+
+/** scripts that must pass before a version is tagged: npm's own lifecycle
+ *  hooks plus any `prepublish:<name>` the unit defines. */
+export function prepublishScripts(scripts: Record<string, string>): string[] {
+    return Object.keys(scripts)
+        .filter((k) => k === 'prepublishOnly' || k === 'prepublish' || k.startsWith('prepublish:'))
+        .sort()
+}
+
+/** the unit's own prepublish hooks, read from ITS package.json (a sub-unit's
+ *  hooks are invisible to the root's) */
+export function unitPrepublishScripts(unit: ReleaseUnit): string[] {
+    const p = readPkg(unit.dir)
+    return 'error' in p ? [] : prepublishScripts(p.pkg.scripts ?? {})
+}

package/src/repo-config.ts

@@ -9,12 +9,17 @@
 // `defaults: { x: false }` prints a skipped-by-config line — never silence.
 // The `contracts` task is always present when any contract applies.
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { isAbsolute, join, normalize } from 'path'
 import { fileURLToPath } from 'url'
 import { activeContracts, applyContractsResult, contractsConfigFrom } from './contracts/apply-contracts.ts'
 import { evaluateContracts } from './contracts/contracts-engine.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
 import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
+import { BUILTIN_RULE_IDS, validateRules } from './rules/rule-registry.ts'
+import type { Rule } from './rules/rule.ts'
+import type { HooksConfig } from './hooks/run-hooks.ts'
+import type { ReleaseConfig } from './release/run-release.ts'
+import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
 import type { TaskDef } from './core/task-runner.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
@@ -62,6 +67,47 @@ export type RepoConfig = {
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
     visibility?: 'private' | 'public'
+    /** the reviewer agent type this repo mandates: `.claude/agents/<name>.md`,
+     *  whose system prompt points at `brief` (an md file holding the standing
+     *  review framing — one home, shared across repos). `tools` overrides the
+     *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
+     *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
+     *  mandated reviewer. */
+    reviewer?: { name: string; brief: string; tools?: string[] }
+    /** repo-local rules, run by `shipkit check` beside the built-in SK ones and
+     *  listed by `shipkit rules`. Same shape, same id-tagging, same fix pointers;
+     *  the repo picks its own id prefix (SK is reserved). This is how a repo's
+     *  own invariants become DISCOVERABLE instead of living as anonymous
+     *  failures inside a hand-rolled lint script. */
+    rules?: Rule[]
+    /** `shipkit release`, branch, tag shape, changelog, npm + GitHub release.
+     *  Absent is fine: the defaults (main, `v{version}`, CHANGELOG.md, npm only
+     *  when public, GitHub release on) fit most repos. release/run-release.ts */
+    release?: ReleaseConfig
+    /** releasable packages INSIDE this repo, beside the mandatory root unit.
+     *  Most repos have none and declare nothing. Nothing is scanned into
+     *  existence: a package nobody declared fails rule SK010 with the entry to
+     *  paste. release/units.ts */
+    units?: ReleaseUnitDecl[]
+    /** repo-relative dirs whose `package.json` is deliberately NOT releasable
+     *  (an electron shell, a cloudflare worker, a fixture, an examples app).
+     *  Rule SK010 needs an achievable green: without this, a package that
+     *  cannot be a release unit leaves the gate permanently red. Declaring it
+     *  here is a statement, so the package still cannot hide. One entry names
+     *  ONE package dir (SK010 fails an entry with no package.json), and the
+     *  repo root is refused outright: a single line that excuses everything
+     *  would turn a blocking rule into a false green. */
+    notReleasable?: string[]
+    /** git-hook gates: built-in leak guard + commit-message predicate, plus the
+     *  repo's own commands. `shipkit hooks list` enumerates them, so what blocks
+     *  a commit is answerable without reading shell. hooks/run-hooks.ts */
+    hooks?: HooksConfig
+    /** what a discovered `*.check.ts` means when the FILE does not say.
+     *  Most repos are uniform (every probe reports the world), and repeating
+     *  the same line in every file is one fact written N times. Declare it
+     *  once here; a file that differs overrides with its own
+     *  `export const blocking = true`. With neither, the check fails loud. */
+    checkDefaults?: { blocking?: boolean }
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
     /** the `shipkit serve` hub: port + optional graph hooks */
@@ -69,21 +115,39 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'reviewer', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
     for (const v of c.venues ?? []) if (!/^[a-z0-9-]+$/.test(v)) throw new Error(`defineRepo: venue '${v}' must be kebab-case`)
     if (c.visibility != null && c.visibility !== 'private' && c.visibility !== 'public')
         throw new Error(`defineRepo: visibility '${String(c.visibility)}' — 'private' or 'public' only`)
+    // a half-declared reviewer would lint a path like `.claude/agents/.md`
+    if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
+        throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))
         if (!KNOWN_KEYS.has(k))
             throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : ''}`)
+    // a typo'd unit key would silently drop a target and release the wrong shape
+    for (const u of c.units ?? []) {
+        if (typeof u.dir !== 'string' || u.dir === '') throw new Error(`defineRepo: every units[] entry needs a 'dir'`)
+        for (const k of Object.keys(u))
+            if (!UNIT_DECL_KEYS.includes(k)) throw new Error(`defineRepo: units['${u.dir}'] unknown key '${k}' (known: ${UNIT_DECL_KEYS.join(', ')})`)
+    }
+    for (const d of c.notReleasable ?? []) {
+        if (typeof d !== 'string' || d === '') throw new Error(`defineRepo: every notReleasable entry is a repo-relative dir path`)
+        const rel = normalize(d).replace(/\/+$/, '')
+        if (isAbsolute(d) || rel === '.' || rel === '' || rel === '..' || rel.startsWith('../'))
+            throw new Error(`defineRepo: notReleasable '${d}' is the repo root or outside it, and would excuse every package at once — name one package dir per entry`)
+    }
     for (const k of Object.keys(c.defaults ?? {}))
         if (!(FLOOR_IDS as readonly string[]).includes(k))
             throw new Error(`defineRepo: defaults.${k} is not a floor task (floor: ${FLOOR_IDS.join(', ')})`)
+    // repo rules are validated against the built-ins, so a bad id, a duplicate,
+    // or an SK squatter dies at config load, not silently mid-check
+    if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
     return c
 }
 

package/src/rules/SK001-package-json-shape.ts

@@ -1,8 +1,8 @@
 // SK001 — canonical package.json shape (meta/rv-conventions/package-json.md):
 // private:true, no license, capability-required script names FAIL, banned
-// aliases + missing baseline trio WARN. Doctor surface only — never wired
-// into the ci gate. Pure local fs, no TTL.
-import { existsSync, readFileSync, writeFileSync } from 'fs'
+// aliases + missing baseline scripts WARN. Blocking, so it runs in `shipkit
+// ci` like every other rule. Pure local fs, no TTL.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { canonicalBodies, conditionalBodies, inferBin } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
@@ -18,7 +18,6 @@ const OWNER = 'meta/rv-conventions/package-json.md'
 // folder must not be told to rename)
 const ALIASES: Record<string, { canonical: string; bodyMatch: RegExp }> = {
     'serve': { canonical: 'hub', bodyMatch: /(shipkit|cli\.ts) serve\b/ },
-    'identity': { canonical: 'assets:identity', bodyMatch: /assets(:| )identity\b/ },
     'pretty': { canonical: 'fmt', bodyMatch: /./ },
     'check-types': { canonical: 'typecheck', bodyMatch: /./ },
 }
@@ -69,35 +68,55 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
     const missing = required.filter((r) => !has(r.name))
     for (const m of missing) t.fail(`package.json: missing script '${m.name}' (${m.why})`)
 
-    const missingBaseline = BASELINE.filter((n) => !has(n))
+    // `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 missingBaseline = baseline.filter((n) => !has(n))
     if (missingBaseline.length > 0)
         t.warn(`package.json: missing baseline script(s): ${missingBaseline.join(', ')}`)
 
     if (!t.failed && !t.warned)
-        t.ok(`package.json shape ok (private, no license, ${required.length} required scripts present)`)
+        t.ok(`package.json shape ok (private, no license, ${required.length} required script(s) present)`)
 }
 
 // capability → required script names (FAIL); repo.config.ts existence is
-// implied — this rule only runs under `shipkit check`
-function requiredScripts(root: string, c: RepoConfig): Array<{ name: string; why: string }> {
+// implied — this rule only runs under `shipkit check`.
+//
+// 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 }> {
     const required: Array<{ name: string; why: string }> = [
-        { name: 'ci', why: 'shipkit repo' },
-        { name: 'check', why: 'shipkit repo' },
-        { name: 'contracts', why: 'shipkit repo' },
-        { name: 'tui', why: 'shipkit repo' },
+        // watch-mode serve — the ONE shipkit surface the bare verb cannot give
         { name: 'hub', why: 'shipkit repo' },
-        { name: 'mv', why: 'shipkit repo' },
     ]
-    if (existsSync(join(root, '.rv-assets/kit.ts'))) required.push({ name: 'assets', why: '.rv-assets/kit.ts exists' })
-    if (existsSync(join(root, '.rv-identity/brand.ts'))) required.push({ name: 'assets:identity', why: '.rv-identity/brand.ts exists' })
     if (existsSync(join(root, '.rv-comfy'))) required.push({ name: 'comfy:up', why: '.rv-comfy/ exists' })
     if (existsSync(join(root, 'deploy.sh'))) required.push({ name: 'up', why: 'deploy.sh exists' })
-    if (existsSync(join(root, c.asks?.dir ?? 'asks'))) required.push({ name: 'asks', why: 'ask queue exists' })
     return required
 }
 
+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)
+}
+
 export const packageJsonShape: Rule = {
     id: 'SK001',
+    blocking: true,
     title: 'package.json',
     owner: OWNER,
     lint: (t: CheckCtx, env: RuleEnv) => evaluatePackageJson(t, env.root, env.config),
@@ -141,7 +160,10 @@ export const packageJsonShape: Rule = {
             pkg.scripts[m.name] = body
             changes.push(`script '${m.name}' added`)
         }
-        if (pkg.scripts['test'] == null) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        // 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 (changes.length > 0) {
             const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
             writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n')

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

@@ -11,6 +11,7 @@ import type { Rule } from './rule.ts'
 
 export const contractsFulfillness: Rule = {
     id: 'SK002',
+    blocking: true,
     title: 'contracts',
     owner: 'meta/contracts.md',
     lint: async (t, env) => {

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

@@ -1,7 +1,7 @@
 // SK003 — the CLAUDE.md two-line contract (meta/agent-folder.md): CLAUDE.md
 // is an include index, never a doc; `@./agent/index.md` comes LAST (include
 // order is SEMANTIC — base context first, repo docs after so they
-// override; a field bug moved the local include line and inverted it); a
+// 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
@@ -17,6 +17,7 @@ const LOCAL_LINE = '@./CLAUDE.local.md'
 
 export const claudeMdShape: Rule = {
     id: 'SK003',
+    blocking: true,
     title: 'CLAUDE.md',
     owner: 'meta/agent-folder.md',
     lint: async (t, env) => {

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

@@ -84,6 +84,7 @@ function writeBlock(root: string, config: RuleEnv['config']): void {
 
 export const gitignorePolicy: Rule = {
     id: 'SK004',
+    blocking: true,
     title: '.gitignore',
     owner: 'meta/contracts.md',
     lint: (t, env) => {

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

@@ -1,14 +1,24 @@
 // SK005 — rvlib-* dependency freshness, and the self-update that keeps
 // every repo converging on the current toolkit (a stale repo silently
 // missing months of rules is the failure; machine-clearable drift clears
-// ITSELF). Per rvlib-* dep:
+// ITSELF).
+//
+// BLOCKING, and the two axes do not fight: every FAIL branch here is about
+// THIS repo (a dep the tree cannot import, a half-written package.json), so
+// it stops you. Everything about the WORLD leaves by another door — version
+// drift WARNs, an unreachable registry SKIPs — and a warning never blocks.
+// Per rvlib-* dep:
 //   link:   → the symlink must resolve (a broken link dies cryptically at
 //             import time otherwise) — nothing to update, code is live
 //   semver  → installed vs npm latest; NEWER LIVE → this lint runs
 //             `bun update --latest` itself, loudly, guarded:
-//             - SHIPKIT_FROZEN=1 (`check --frozen`) → WARN, never touch
+//             - SHIPKIT_FROZEN=1 (`check --frozen`, `ci --frozen`) → WARN,
+//               never touch
 //             - package.json/lockfile git-dirty (or no git) → WARN deferred,
 //               a tool must not mix its writes into human-staged work
+//             - the update itself failing splits by what it LEFT: a half-
+//               written package.json/lockfile is this repo and FAILs, an
+//               untouched tree is the registry and only WARNs
 //   registry unreachable → loud skip, never red (offline is not a defect)
 // Committing the bump stays with the working agent — shipkit never commits.
 // Clean passes cache 24h (rule ttl), so the registry is fetched at most
@@ -38,6 +48,7 @@ async function latestVersion(t: CheckCtx, name: string): Promise<string> {
 
 export const rvlibVersions: Rule = {
     id: 'SK005',
+    blocking: true,
     title: 'rvlib versions',
     owner: 'build/shipkit.md',
     ttl: '24h',
@@ -84,7 +95,15 @@ export const rvlibVersions: Rule = {
         const names = stale.map((s) => s.name)
         const up = await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
         if (up.code !== 0) {
-            t.fail(`self-update failed (bun update --latest ${names.join(' ')} exited ${up.code}${up.timedOut ? ', timed out' : ''}) — package.json/lockfile may be partially written, \`git status\` first: ${up.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}`)
+            // which axis the failure sits on is measurable, so measure it: the
+            // tree is either half-written (this repo, blocks) or untouched, and
+            // a registry drop mid-download must never hard-red a healthy repo
+            const after = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+            const half = after.code !== 0 || after.out.trim() !== ''
+            const why = `bun update --latest ${names.join(' ')} exited ${up.code}${up.timedOut ? ', timed out' : ''}`
+            const tail = up.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''
+            if (half) t.fail(`self-update failed (${why}) and package.json/lockfile are half-written — \`git status\`, then restore or finish it by hand: ${tail}`)
+            else t.warn(`self-update failed (${why}) and nothing was written — the registry or the network, not this repo. Retry with: bun update --latest ${names.join(' ')}: ${tail}`)
             return
         }
         for (const s of stale) {

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

@@ -20,6 +20,7 @@ type Pkg = { name?: string; private?: boolean; publishConfig?: unknown; scripts?
 
 export const npmPublishSafety: Rule = {
     id: 'SK006',
+    blocking: true,
     title: 'npm publish safety',
     owner: 'meta/rv-conventions/package-json.md',
     lint: (t, env) => {

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

@@ -17,6 +17,10 @@ import type { Rule } from './rule.ts'
 
 export const githubVisibility: Rule = {
     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',
     owner: 'meta/contracts.md',
     ttl: '7d',
@@ -30,7 +34,7 @@ export const githubVisibility: Rule = {
         if (remotes.code !== 0) return skip(`git says: ${firstLine(remotes.out) || `exit ${remotes.code}`}`)
         const names = remotes.out.trim().split('\n').filter((l) => l !== '')
         if (names.length === 0) return skip('no git remote')
-        // his repos name it `github`, not `origin` (field catch 2026-07-26)
+        // 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 })
         if (url.code !== 0) return skip(`git says: ${firstLine(url.out)}`)