rvlib-shipkit 0.14.0 → 0.17.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/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({

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

@@ -17,16 +17,14 @@ export default defineContract({
         // 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 (field
-        // 2026-07-27: a reviewer proved `cp template listing.md` went green)
+        // 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 — an exact-size rule would
-        // block a release over a better cover (audit 2026-07-27)
+        // 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
 }

package/src/core/run-ci.ts

@@ -1,11 +1,16 @@
-// the ci gate — floor + contracts + repo tasks through the DAG runner.
-// Plain module behind cmd_Ci (logic stays out of command classes) so tests
-// can run the gate in-process. Returns the exit code; json prints the
-// structured summary. Every run refreshes STATUS.md (write-status.ts —
-// atomic + lock) unless status:false.
+// the ci gate — floor + contracts + repo tasks through the DAG runner, THEN
+// every discovered check (core/run-check.ts owns severity). Plain module
+// behind cmd_Ci (logic stays out of command classes) so tests can run the
+// gate in-process. Returns the exit code; json prints the structured summary.
+// Every run refreshes STATUS.md (write-status.ts — atomic + lock) unless
+// status:false, and the fix pass plus some checks WRITE, so a run is not
+// read-only unless frozen is set and --no-fix is passed.
 import { join } from 'path'
-import { allTasks, loadRepoConfig } from '../repo-config.ts'
+import { allTasks, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
+import { collectChecks } from './run-check.ts'
+import { runFixPass } from './run-fixers.ts'
+import { formatLine } from './wire.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
 
@@ -17,17 +22,60 @@ export type CiOpts = {
     onlyIds?: string[]
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
+    /** repair the mechanical slots before gating. default on locally, verify
+     *  mode under CI. core/run-fixers.ts owns the scope. */
+    fix?: boolean
+    /** also apply the structural SK rule fixers during the fix pass */
+    fixRules?: boolean
+    /** bust every check's TTL cache. A release gates with this on: a blocking
+     *  rule replaying a clean pass from hours ago is not a gate. */
+    fresh?: boolean
+    /** report-only for self-maintaining rules and checks (SHIPKIT_FROZEN
+     *  travels to child checks). The release path passes it: a rule that
+     *  rewrites package.json between the gate and `npm publish` packs a tree
+     *  that exists in no commit. */
+    frozen?: boolean
+    /** treat a NON-blocking check failure as fatal too. `release.requireHealthy`
+     *  is the only caller: a repo that wants a missing cred to stop a release
+     *  asks for it, and every other run keeps the declared severity. */
+    failOnAdvisory?: boolean
+    /** run the tasks only. The TUI owns this: it renders the checks in its own
+     *  panel, and running the suite twice per refresh proves nothing twice. */
+    skipChecks?: boolean
     /** line sink — commands pass their context stream; defaults to console */
     print?: (line: string) => void
     /** per-task completion tap — the TUI tasks panel streams results in */
     onTaskFinish?: (r: TaskResult) => void
+    /** the already-resolved config. A caller that holds one MUST pass it: two
+     *  loads of repo.config.ts can disagree, and the release path classifies
+     *  rule-vs-probe severity from the config it holds. */
+    config?: RepoConfig
+}
+
+/** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
+ *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
+ *  a narrowed run that stamps the full gate's verdict is a green nobody
+ *  measured. The label names the invocation either way. */
+function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
+    const narrowing = [
+        ...(o.onlyIds ?? []).map((i) => `--only ${i}`),
+        ...(o.skipGroups ?? []).map((g) => `--skip ${g}`),
+        ...(o.skipChecks === true ? ['(tasks only)'] : []),
+    ]
+    const parts = [...narrowing, ...(o.withIds ?? []).map((i) => `--with ${i}`)]
+    return { command: parts.length === 0 ? 'shipkit ci' : `shipkit ci ${parts.join(' ')}`, fullGate: narrowing.length === 0 }
 }
 
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
-    const c = await loadRepoConfig(root)
+    const c = o.config ?? (await loadRepoConfig(root))
+    // mechanical failures are not information, so they never cost a round trip
+    let fixFailed = false
+    if (o.fix !== false)
+        fixFailed = (await runFixPass(root, c, { rules: o.fixRules !== false, print: sink })).failed
+    else sink('skip: fix pass (--no-fix)')
     const { tasks, disabled, unfilled } = allTasks(c, root)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
@@ -44,12 +92,33 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
-    const code = summary.ok ? 0 : 1
+    // the checks, in the SAME command. there is no second surface: a check
+    // declares whether it blocks, and that is the only question about it.
+    const checks = o.skipChecks === true
+        ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, fresh: o.fresh })
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
+    for (const u of checks.undeclared) {
+        sink(`FAIL: ${u} does not declare whether it blocks`)
+        sink(`      fix: add \`export const blocking = true\` (about this repo) or \`false\` (about the world) to that file`)
+    }
+    let advisoryFatal = false
+    if (checks.advisoryFailures.length > 0) {
+        if (o.failOnAdvisory === true) {
+            advisoryFatal = true
+            sink(`FAIL: ${checks.advisoryFailures.length} non-blocking check(s) failing and release.requireHealthy is on: ${checks.advisoryFailures.join(', ')}`)
+            sink('      fix: shipkit check')
+        } else sink(`WARN ${checks.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${checks.advisoryFailures.join(', ')}`)
+    }
+    const code = summary.ok && !fixFailed && !checks.blocked && !advisoryFatal && checks.undeclared.length === 0 ? 0 : 1
     // motherhome row (docsBase wiki on this disk) — never affects the gate
     const mh = reportToMotherhome(root, c)
     if (mh.note != null) print(mh.note)
     if (o.status !== false) {
-        const st = writeStatus(root, { name: c.name, command: 'shipkit ci', lines: collected, exitCode: code })
+        // scope is named in the file: ci proves the gate, not repo health, and
+        // a bare GREEN here would claim clear-to-ship on a repo with red checks
+        const st = writeStatus(root, { name: c.name, ...ciScope(o), lines: collected, exitCode: code })
         if (!st.written) print(`WARN ${st.warn}`)
     }
     if (o.json === true)