rvlib-shipkit 0.13.0 → 0.16.0

package/src/cli/cmd_Release.ts

@@ -0,0 +1,41 @@
+// shipkit release, the one release path, public or private. Thin clipanion
+// surface; logic in release/run-release.ts.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { runRelease } from '../release/run-release.ts'
+
+export class ReleaseCommand extends Command {
+    static override paths = [['release']]
+
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'cut a release for ONE unit (default the repo root): ci gate → npm publish (non-private only) → git tag → push → GitHub release, notes from that unit CHANGELOG section. Resumable after a partial failure, which is why it takes no --all.',
+        examples: [
+            ['rehearse — touches nothing', 'shipkit release --dry-run'],
+            ['release the version in package.json', 'shipkit release'],
+            ['finish a sub-unit bump stopped part way (ids: shipkit releases)', 'shipkit release rvlib-shipkit'],
+            ['release with dirt elsewhere in the worktree', 'shipkit release --allow-dirty'],
+        ],
+    })
+
+    unit = Option.String({ required: false })
+    dryRun = Option.Boolean('--dry-run', false, { description: 'run every preflight and print the plan, change nothing' })
+    allowDirty = Option.Boolean('--allow-dirty', false, { description: 'release from an unclean tree (the tag will not contain it). A SUB-unit still refuses on dirt inside its own path' })
+    skipGate = Option.Boolean('--skip-gate', false, { description: 'skip the ci gate preflight — publishes unverified, use only to recover a stuck release' })
+
+    async execute(): Promise<number> {
+        try {
+            const config = await loadRepoConfig(process.cwd())
+            return await runRelease(process.cwd(), config, {
+                dryRun: this.dryRun,
+                allowDirty: this.allowDirty,
+                skipGate: this.skipGate,
+                unit: this.unit,
+                print: (l) => this.context.stdout.write(`${l}\n`),
+            })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Releases.ts

@@ -0,0 +1,42 @@
+// shipkit releases — every release unit and where it actually stands. Thin
+// clipanion surface; logic in release/run-releases.ts.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { collectReports, renderReports } from '../release/run-releases.ts'
+
+export class ReleasesCommand extends Command {
+    static override paths = [['releases']]
+
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'every release unit and where it stands: version, npm, tag local and remote, GitHub release, drift. Reports, never gates (only an unresolvable config exits non-zero)',
+        examples: [
+            ['what is published and what is not', 'shipkit releases'],
+            ['filesystem + local git only, no network', 'shipkit releases --offline'],
+            ['machine-readable', 'shipkit releases --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'emit { units: UnitReport[], errors: string[] } JSON' })
+    offline = Option.Boolean('--offline', false, { description: 'skip npm, the remote and gh — local facts only' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        try {
+            const config = await loadRepoConfig(root)
+            const { reports, errors, remoteError } = await collectReports(root, config, { offline: this.offline })
+            if (this.json) {
+                this.context.stdout.write(`${JSON.stringify({ units: reports, errors }, null, 2)}\n`)
+                return errors.length > 0 ? 1 : 0
+            }
+            for (const l of renderReports(reports, { remoteError, offline: this.offline })) this.context.stdout.write(`${l}\n`)
+            // a unit nobody can describe is a repo bug, not a world fact: the
+            // listing still prints, and the exit code still says something broke
+            for (const e of errors) this.context.stderr.write(`FAIL: ${e}\n`)
+            return errors.length > 0 ? 1 : 0
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Rules.ts

@@ -1,24 +1,36 @@
-// shipkit rules — render the SK rule registry. Agents read ids HERE (or
-// --json), never guess or mint one: the registry is the single source.
+// shipkit rules, render the rule registry: shipkit's built-in SK rules
+// plus whatever the repo registered through `repo.config.ts rules: []`.
+// Agents read ids HERE (or --json), never guess or mint one: the registry
+// is the single source, and a repo whose own invariants are absent from it
+// is a repo whose agents cannot know what binds them.
 import { Command, Option } from 'clipanion'
 import { RULES } from '../rules/rule-registry.ts'
+import { loadRepoConfig } from '../repo-config.ts'
 
 export class RulesCommand extends Command {
     static override paths = [['rules']]
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'list every built-in SK rule: id, what it lints, owning doc, whether check --fix can repair it',
+        description: 'every rule that runs here: whether it BLOCKS or only warns, what it lints, the owning doc, and whether --fix can repair it. Built-in SK rules plus the repo\'s own.',
         examples: [
             ['list rules', 'shipkit rules'],
             ['machine-readable', 'shipkit rules --json'],
         ],
     })
 
-    json = Option.Boolean('--json', false, { description: 'machine-readable [{id, title, owner, fixable}]' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable [{id, title, owner, blocking, fixable, source}]' })
 
     async execute(): Promise<number> {
-        const rows = RULES.map((r) => ({ id: r.id, title: r.title, owner: r.owner, fixable: r.fix != null }))
+        // a repo without repo.config.ts still gets the built-in catalog: this
+        // command must answer "what rules exist" from anywhere
+        const repoRules = await loadRepoConfig(process.cwd())
+            .then((c) => c.rules ?? [])
+            .catch(() => [])
+        const rows = [
+            ...RULES.map((r) => ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source: 'shipkit' as const })),
+            ...repoRules.map((r) => ({ id: r.id, title: r.title, owner: r.owner, blocking: r.blocking, fixable: r.fix != null, source: 'repo' as const })),
+        ]
         if (this.json) {
             this.context.stdout.write(`${JSON.stringify(rows)}\n`)
             return 0
@@ -26,7 +38,9 @@ export class RulesCommand extends Command {
         // a catalog, not a health run — no wire prefixes (`ok:` would assert
         // a passing check into anything that parses wire output)
         for (const r of rows)
-            this.context.stdout.write(`${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}\n`)
+            this.context.stdout.write(`${r.blocking ? 'BLOCKS ' : 'warns  '}${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}\n`)
+        if (repoRules.length > 0)
+            this.context.stdout.write(`\n${RULES.length} built-in · ${repoRules.length} repo-local (repo.config.ts rules)\n`)
         return 0
     }
 }

package/src/cli/cmd_Start.ts

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'ensure <root>/<name> exists, optionally with a CLAUDE.md include line; prints the dir on stdout so a shell alias can cd there',
+        description: 'ensure <root>/<name> exists, optionally with a CLAUDE.md include line. Prints the dir on stdout so a shell alias can cd there',
         examples: [
             ['start (or enter) a repo', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
@@ -18,7 +18,7 @@ export class StartCommand extends Command {
 
     name = Option.String()
     root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
-    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept; omitted = only ensure the dir' })
+    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept. Omitted means only ensure the dir' })
     alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add' })
     skip = Option.Array('--skip', { description: 'repo names that never get the include' })
 

package/src/cli.ts

@@ -1,18 +1,23 @@
 #!/usr/bin/env bun
-// shipkit — clipanion entry: one command per file in cli/ (cmd_<Name>.ts),
+// shipkit — clipanion entry: one command FAMILY per file in cli/ (cmd_<Name>.ts),
 // logic in plain modules the commands call. runExit sets the exit code
 // without force-exiting, so serve commands keep the process alive.
 import { readFileSync } from 'fs'
 import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
 import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
+import { BumpCommand } from './cli/cmd_Bump.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
+import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
+import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cli/cmd_Hooks.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { ReflectCommand } from './cli/cmd_Reflect.ts'
+import { ReleaseCommand } from './cli/cmd_Release.ts'
+import { ReleasesCommand } from './cli/cmd_Releases.ts'
 import { RulesCommand } from './cli/cmd_Rules.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
@@ -32,6 +37,13 @@ const cli = new Cli({
 cli.register(Builtins.HelpCommand)
 cli.register(Builtins.VersionCommand)
 cli.register(CiCommand)
+cli.register(BumpCommand)
+cli.register(ReleaseCommand)
+cli.register(ReleasesCommand)
+cli.register(HooksInstallCommand)
+cli.register(HooksPreCommitCommand)
+cli.register(HooksCommitMsgCommand)
+cli.register(HooksListCommand)
 cli.register(MvCommand)
 cli.register(CheckCommand)
 cli.register(TuiCommand)
@@ -52,5 +64,6 @@ cli.register(StartCommand)
 cli.register(NeedsCommand)
 cli.register(ReflectCommand)
 cli.register(RulesCommand)
+cli.register(CommandsCommand)
 
 cli.runExit(process.argv.slice(2))

package/src/collections/posts.ts

@@ -4,7 +4,7 @@
 // variants are sibling files `<slug>.a.md`, `<slug>.b.md`; picking one flips
 // it to picked and the others to rejected (files KEPT). Severities:
 //   any file missing `status:` → red (metadata with no inventable default)
-//   drafts awaiting a pick     → yellow (his taste)
+//   drafts awaiting a pick     → yellow (a pick is a taste act)
 //   picked but not posted      → red (paste-from-elsewhere: post + URL proof)
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'

package/src/collections/providers.ts

@@ -3,7 +3,7 @@
 // Behaviors preserved by name: per-source failure isolation (projectNeeds
 // guards per collection), the identity self-heal before surfacing, and the
 // asks READ path never minting asks/ on a repo without one. Dedup doctrine
-// (his correction 2026-07-23): dedup = acted-on once, NEVER hidden — an
+// : dedup = acted-on once, NEVER hidden — an
 // ask-covered missing cred still shows RED in secrets with a pointer to the
 // ask; verbs and pings stay with the ask. Each wire line of STATUS.md lives
 // in exactly ONE collection: cred probe lines in secrets, everything else

package/src/contracts/contract-types.ts

@@ -6,7 +6,10 @@
 
 export type RuleOpts = { warnOnly?: boolean }
 export type FileRule = RuleOpts & { kind: 'file'; path: string; nonEmpty: boolean }
-export type PngRule = RuleOpts & { kind: 'png'; path: string; width: number; height: number }
+/** `atLeast`: the venue's numbers are a MINIMUM at a fixed aspect ratio (itch
+ *  displays a 630x500 cover but accepts larger, and a 2x asset is better) —
+ *  without it an exact-size rule blocks the release over a better file */
+export type PngRule = RuleOpts & { kind: 'png'; path: string; width: number; height: number; atLeast?: boolean }
 export type GlobRule = RuleOpts & { kind: 'glob'; pattern: string; min: number; width?: number; height?: number }
 export type MdRule = RuleOpts & { kind: 'md'; path: string; mustContain: string[] }
 export type DirRule = RuleOpts & { kind: 'dir'; path: string }
@@ -41,7 +44,7 @@ export type ContractManifest = {
 }
 
 export const file = (path: string, p?: RuleOpts & { nonEmpty?: boolean }): FileRule => ({ kind: 'file', path, nonEmpty: p?.nonEmpty ?? true, warnOnly: p?.warnOnly })
-export const png = (path: string, width: number, height: number, p?: RuleOpts): PngRule => ({ kind: 'png', path, width, height, warnOnly: p?.warnOnly })
+export const png = (path: string, width: number, height: number, p?: RuleOpts & { atLeast?: boolean }): PngRule => ({ kind: 'png', path, width, height, atLeast: p?.atLeast, warnOnly: p?.warnOnly })
 export const glob = (pattern: string, p: RuleOpts & { min: number; width?: number; height?: number }): GlobRule => ({ kind: 'glob', pattern, min: p.min, width: p.width, height: p.height, warnOnly: p.warnOnly })
 export const md = (path: string, p?: RuleOpts & { mustContain?: string[] }): MdRule => ({ kind: 'md', path, mustContain: p?.mustContain ?? [], warnOnly: p?.warnOnly })
 export const dir = (path: string, p?: RuleOpts): DirRule => ({ kind: 'dir', path, warnOnly: p?.warnOnly })

package/src/contracts/contracts-engine.ts

@@ -57,11 +57,21 @@ async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]
         }
         case 'png': {
             const p = abs(env.root, rule.path)
-            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${rule.width}x${rule.height}`); break }
+            const need = rule.atLeast === true ? `>= ${rule.width}x${rule.height} at ${rule.width}:${rule.height}` : `${rule.width}x${rule.height}`
+            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${need}`); break }
             const dims = pngDims(p)
             if (dims == null) problems.push(`${rule.path} is not a readable png`)
-            else if (dims.width !== rule.width || dims.height !== rule.height)
-                problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${rule.width}x${rule.height}`)
+            else if (rule.atLeast !== true) {
+                if (dims.width !== rule.width || dims.height !== rule.height) problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${need}`)
+            } else {
+                const want = rule.width / rule.height
+                // RELATIVE tolerance: an absolute one is 0.8% at 630:500 and
+                // 3% at a tall ratio, i.e. a different rule per venue
+                const ratioOff = Math.abs(dims.width / dims.height - want) / want > 0.01
+                const tooSmall = dims.width < rule.width || dims.height < rule.height
+                if (tooSmall || ratioOff)
+                    problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${need}${ratioOff ? ' (the ratio is off; a bigger asset at the same ratio is fine)' : ' (bigger is fine, smaller is not)'}`)
+            }
             break
         }
         case 'glob': {

package/src/contracts/manifests/discord.contract.ts

@@ -1,5 +1,5 @@
 // normative WHAT for .rv-discord/ — a project's public Discord server
-// contract (promoted out of .rv-social/discord/ 2026-07-21; posts stay there).
+// contract. Posts stay in .rv-social/.
 import { defineContract, dirExists, md, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
@@ -10,6 +10,6 @@ export default defineContract({
     detect: [dirExists('.rv-discord')],
     artifacts: [
         md('.rv-discord/server.md', { mustContain: ['invite'] }),
-        png('.rv-discord/icon.png', 512, 512),
+        png('.rv-discord/icon.png', 512, 512, { atLeast: true }),
     ],
 })

package/src/contracts/manifests/identity.contract.ts

@@ -13,7 +13,7 @@ export default defineContract({
     artifacts: [
         file('.rv-identity/brand.ts'),
         png('public/favicon.png', 512, 512),
-        png('public/og.png', 1200, 630),
+        png('public/og.png', 1200, 630, { atLeast: true }),
         glob('public/logo.*', { min: 1 }),
     ],
 })

package/src/contracts/manifests/itch.contract.ts

@@ -1,5 +1,7 @@
 // normative WHAT for .rv-itch/ — the WHY + workflow live in the sibling page.
-import { defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { custom, defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
 
 export default defineContract({
     venue: 'itch',
@@ -10,7 +12,20 @@ export default defineContract({
     artifacts: [
         // one AI-disclosure wording everywhere — page.md is its canonical home
         md('.rv-itch/page.md', { mustContain: ['## AI disclosure'] }),
-        png('.rv-itch/cover.png', 630, 500),
+        // every field of itch's create-project form, answered and ready to
+        // paste — the listing is a browser-only act, so the artifact IS the
+        // handoff (references/listing.template.md is the fill-in copy)
+        md('.rv-itch/listing.md', { mustContain: ['## Title', '## Short description or tagline', '## Classification', '## Genre', '## Tags', '## Visibility'] }),
+        // headings alone would pass the TEMPLATE copied in verbatim, and this
+        // file exists to be pasted with no decision left in it
+        custom('.rv-itch/listing.md answered', (env) => {
+            const p = join(env.root, '.rv-itch/listing.md')
+            if (!existsSync(p)) return []
+            const left = [...readFileSync(p, 'utf8').matchAll(/<[a-z][^<>\n]{2,60}>/g)].map((m) => m[0])
+            return left.length === 0 ? [] : [`.rv-itch/listing.md still holds ${left.length} unanswered placeholder(s): ${[...new Set(left)].slice(0, 3).join(' ')} — it is pasted into the store form as-is`]
+        }),
+        // itch DISPLAYS 630x500 and accepts larger — atLeast, never exact-size
+        png('.rv-itch/cover.png', 630, 500, { atLeast: true }),
         glob('.rv-itch/screenshots/*.png', { min: 3 }),
     ],
 })

package/src/core/canonical-scripts.ts

@@ -1,21 +1,19 @@
 // The canonical package.json script bodies for a shipkit repo — vocabulary
 // owned by meta/rv-conventions/package-json.md. ONE source: `shipkit init`
 // scaffolds from it and rule SK001's autofix repairs from it.
+//
+// a script that only forwards to a shipkit verb is NOT canon: the verb is the
+// vocabulary, and the alias is one more name to keep in sync. only a body
+// shipkit cannot express itself earns a script.
 export type ScriptStyle = {
     /** in-repo-source consumers: path to shipkit's cli.ts — bodies become `bun <path> <cmd>` */
     bin?: string
 }
 
 export function canonicalBodies(opts: ScriptStyle = {}): Record<string, string> {
-    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
     return {
-        ci: run('ci'),
-        check: run('check'),
-        contracts: run('contracts'),
-        tui: run('tui'),
-        mv: run('mv'),
-        // hub runs in WATCH mode (house default 2026-07-23): lib/config edits
-        // restart the server live; the npm shim can't watch, the source path can
+        // hub runs in WATCH mode: lib/config edits restart the server live.
+        // `shipkit serve` alone cannot watch, so this one is not an alias
         hub: `bun --watch ${opts.bin ?? 'node_modules/rvlib-shipkit/src/cli.ts'} serve`,
         // baseline `test` is universal — lint/fmt bodies are stack-specific,
         // the scaffold pages own those
@@ -24,14 +22,11 @@ export function canonicalBodies(opts: ScriptStyle = {}): Record<string, string>
 }
 
 // conditional canon (bodies stated by the vocabulary page) — keyed by the
-// SK001 requirement name; requirements with no canonical body (assets,
-// comfy:up) are deliberately absent: a fixer must not invent one
-export function conditionalBodies(opts: ScriptStyle = {}): Record<string, string> {
-    const run = (cmd: string): string => (opts.bin != null ? `bun ${opts.bin} ${cmd}` : `shipkit ${cmd}`)
+// SK001 requirement name; a requirement with no canonical body (comfy:up) is
+// deliberately absent: a fixer must not invent one
+export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, string> {
     return {
         'up': './deploy.sh',
-        'asks': run('asks'),
-        'assets:identity': run('assets identity'),
     }
 }
 

package/src/core/check-suite.ts

@@ -163,7 +163,7 @@ export class CheckSuite {
             if (r.ttlMs > 0) {
                 // a skip line is an UNKNOWN, not a clean pass — replaying
                 // "registry unreachable" for a TTL asserts a dead network as
-                // fact long after it recovered (review find 2026-07-26)
+                // fact long after it recovered
                 if (!t.failed && !t.warned && !t.lines.some((l) => l.kind === 'skip')) { cache[r.name] = { version: r.version, key, at: this.now(), lines: t.lines }; cacheDirty = true }
                 // a WARN/FAIL evicts the stale pass — a later run must re-probe,
                 // not replay an ok recorded before the breakage

package/src/core/discover-checks.ts

@@ -1,6 +1,7 @@
-// *.check.ts auto-discovery — THE way health checks register (repo.config
-// `checks:[]` is dead, one-runner GO 2026-07-22): drop a `<name>.check.ts`
-// anywhere in the repo and `shipkit check` runs it as a subprocess — wire
+// *.check.ts auto-discovery — THE way a repo registers its OWN checks
+// (built-in SK rules come from rules/rule-registry.ts): drop a
+// `<name>.check.ts` anywhere in the repo and `shipkit check` runs it as a
+// subprocess — wire
 // output parsed back, exit code is truth. Skipped dirs: node_modules, dist,
 // tmp, references (templates for other repos), and every dot-dir (.git,
 // caches, .rv-* contract folders).
@@ -18,8 +19,16 @@ export type DiscoveredCheck = {
     name: string
     /** file runs its own CheckSuite (own TTL cache) — the orchestrator must not double-cache it */
     selfCached: boolean
+    /** `export const blocking = true | false`, read statically. null = the file
+     *  never said, which is an error: a check that silently does not block is
+     *  the failure nobody sees. */
+    blocking: boolean | null
 }
 
+// read without importing: checks run as subprocesses, and discovery must stay
+// pure-fs. `export const blocking = true` (or false), nothing cleverer.
+const BLOCKING_RE = /^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)\s*$/m
+
 export function discoverChecks(root: string): DiscoveredCheck[] {
     const files: string[] = []
     const walk = (dir: string): void => {
@@ -39,10 +48,16 @@ export function discoverChecks(root: string): DiscoveredCheck[] {
     return files.map((f) => {
         const base = baseOf(f)
         const name = (seen.get(base) ?? 0) > 1 ? relative(root, f).slice(0, -SUFFIX.length) : base
-        // a check built on CheckSuite/SkillValidator replays from its OWN
+        // a check built on CheckSuite/PageValidator replays from its OWN
         // TTL cache — caching it again up here would double the staleness
         let selfCached = false
-        try { selfCached = /SkillValidator|CheckSuite/.test(readFileSync(f, 'utf8')) } catch {}
-        return { path: f, name, selfCached }
+        let blocking: boolean | null = null
+        try {
+            const src = readFileSync(f, 'utf8')
+            selfCached = /PageValidator|CheckSuite/.test(src)
+            const m = src.match(BLOCKING_RE)
+            blocking = m == null ? null : m[1] === 'true'
+        } catch {}
+        return { path: f, name, selfCached, blocking }
     })
 }

package/src/core/run-check.ts

@@ -6,13 +6,14 @@
 // layers (SHIPKIT_FRESH=1 + RV_CHECK_FRESH=1 travel to children).
 import { join, relative } from 'path'
 import { CheckSuite, type CheckOutcome } from './check-suite.ts'
+import { CheckCtx } from './check-ctx.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
-import { loadRepoConfig } from '../repo-config.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { RULES } from '../rules/rule-registry.ts'
 import { runRuleLint } from '../rules/rule.ts'
-import { formatLine, parseWireOutput } from './wire.ts'
+import { formatLine, parseWireOutput, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
 
 // orchestrator cache for checks WITHOUT their own suite — short on purpose:
@@ -31,11 +32,27 @@ export type CheckOpts = {
     print?: (line: string) => void
     /** per-check completion tap — the TUI checks panel streams results in */
     onResult?: (name: string, r: CheckOutcome) => void
+    /** the already-resolved config, same contract as runCi: the caller that
+     *  decides severity and the engine that runs the rules must read the same
+     *  object, or a blocking rule failure silently reclassifies as a probe */
+    config?: RepoConfig
 }
 
-export async function runCheck(root: string, o: CheckOpts = {}): Promise<number> {
-    const print = o.print ?? ((l: string) => console.log(l))
-    const c = await loadRepoConfig(root)
+export type CheckRun = {
+    /** wire lines, with non-blocking failures already downgraded to warnings */
+    lines: Line[]
+    /** a BLOCKING check failed */
+    blocked: boolean
+    /** names of non-blocking checks that failed — reported, never fatal */
+    advisoryFailures: string[]
+    /** checks that never declared `blocking` — always fatal */
+    undeclared: string[]
+}
+
+/** run every check and classify by what it declared. This is the whole engine;
+ *  runCi wraps it with the task DAG, and nothing else decides severity. */
+export async function collectChecks(root: string, o: CheckOpts = {}): Promise<CheckRun> {
+    const c = o.config ?? (await loadRepoConfig(root))
     // env carries the flags to child checks — restored after the run so a
     // long-lived caller (doctor, TUI, hub) is never poisoned by one
     // fresh/frozen invocation
@@ -44,15 +61,29 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
     if (o.fresh === true) process.env.SHIPKIT_FRESH = '1'
     if (o.frozen === true) process.env.SHIPKIT_FROZEN = '1'
     const suite = new CheckSuite({ name: c.name, cacheDir: join(root, 'tmp/.shipkit-cache'), onResult: o.onResult })
-    // built-in SK rules (rules/rule-registry.ts) — id-tagged, crash-safe,
-    // fix-pointer floor (rules/rule.ts runRuleLint owns the semantics);
-    // doctor surface only, deliberately absent from the ci gate
-    for (const rule of RULES)
+    // built-in SK rules (rules/rule-registry.ts) THEN the repo's own
+    // (repo.config rules: []), id-tagged, crash-safe, fix-pointer floor
+    // (rules/rule.ts runRuleLint owns the semantics). `shipkit ci` runs this
+    // same engine, so a blocking rule blocks a commit as well as a doctor run
+    const undeclared: string[] = []
+    const advisoryFailures: string[] = []
+    // a non-blocking failure becomes a WARNING here, at the source. printing
+    // FAIL and exiting 0 would be the tool lying about its own severity, and
+    // demoting in the check means the suite's exit code already means exactly
+    // "something that blocks you failed".
+    const demote = (t: CheckCtx, blocking: boolean, name: string): void => {
+        if (blocking || !t.failed) return
+        if (!advisoryFailures.includes(name)) advisoryFailures.push(name)
+        t.lines = t.lines.map((l) => (l.kind === 'fail' ? { ...l, kind: 'warn' as const } : l.kind === 'fix-fail' ? { ...l, kind: 'fix-warn' as const } : l))
+        t.failed = false
+        t.warned = true
+    }
+    for (const rule of [...RULES, ...(c.rules ?? [])])
         suite.addCheck({
             name: rule.title,
             remainValidFor: rule.ttl,
             cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
-            logic: (t) => runRuleLint(rule, t, { root, config: c }),
+            logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
@@ -60,6 +91,10 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path)
+        // file wins, then the repo default, then nothing: an unclassified
+        // check is an error, never a guess
+        const blocking = d.blocking ?? c.checkDefaults?.blocking
+        if (blocking == null) undeclared.push(rel)
         suite.addCheck({
             name: d.name,
             remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
@@ -72,22 +107,35 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
                 // (crash, non-wire output, timeout) must still fail loud
                 if (r.code !== 0 && !t.failed)
                     t.fail(`${d.name} exited ${r.code}${r.timedOut ? ` (timeout after ${CHECK_TIMEOUT_MS}ms)` : ''} — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}`, `bun ${rel}`)
+                demote(t, blocking ?? true, d.name)
             },
         })
     }
     const r = await suite.execute()
     if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
-    // report to the motherhome (docsBase wiki on this disk) — never fails
-    // the check, notes only when it wrote or broke
-    const mh = reportToMotherhome(root, c)
-    const statusOutcome = o.status !== false
-        ? writeStatus(root, { name: c.name, command: 'shipkit check', lines: r.lines.map((l) => formatLine(l, false)), exitCode: r.exitCode })
-        : null
-    if (o.json === true) { print(JSON.stringify(r)); return r.exitCode }
+    reportToMotherhome(root, c)
+    return { lines: r.lines, blocked: r.exitCode !== 0, advisoryFailures, undeclared }
+}
+
+/** `shipkit check` as a standalone command: the same engine, printed. */
+export async function runCheck(root: string, o: CheckOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const c = o.config ?? (await loadRepoConfig(root))
+    const run = await collectChecks(root, { ...o, config: c })
+    const code = run.blocked || run.undeclared.length > 0 ? 1 : 0
+    if (o.json === true) { print(JSON.stringify(run)); return code }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
-    for (const l of r.lines) print(formatLine(l, color))
-    if (mh.note != null) print(mh.note)
-    if (statusOutcome != null && !statusOutcome.written) print(`WARN ${statusOutcome.warn}`)
-    return r.exitCode
+    for (const l of run.lines) print(formatLine(l, color))
+    for (const u of run.undeclared) {
+        print(`FAIL: ${u} does not declare whether it blocks`)
+        print(`      fix: add \`export const blocking = true\` (about this repo) or \`false\` (about the world) to that file`)
+    }
+    if (o.status !== false) {
+        // the producing command is named honestly: a checks-only run must not
+        // overwrite the gate verdict with a green nobody gated
+        const st = writeStatus(root, { name: c.name, command: 'shipkit check', lines: run.lines.map((l) => formatLine(l, false)), exitCode: code })
+        if (!st.written) print(`WARN ${st.warn}`)
+    }
+    return code
 }