rvlib-shipkit 0.38.0 → 1.0.0

package/src/repo-config.ts

@@ -1,7 +1,7 @@
 // defineRepo — the ONE import a repo needs: repo.config.ts at the root
-// declares venues/social/tasks, and the toolkit derives everything else.
-// Health checks are NOT declared here: drop a `<name>.check.ts` file and
-// `shipkit check` discovers it (core/discover-checks.ts). The FLOOR
+// declares venues/social, and the toolkit derives everything else.
+// Checks are NOT declared here: drop a `<name>.check.ts` file and every
+// surface discovers it (core/discover-checks.ts). The FLOOR
 // (lint/typecheck/test/imports:check/cycles): a package.json script wins;
 // with no script, imports:check/cycles fill from shipkit's own
 // rvlib-ts-tools dep and typecheck from the repo's tsc (O6 zero-config);
@@ -11,22 +11,22 @@
 import { existsSync, readFileSync } from 'fs'
 import { isAbsolute, join, normalize } from 'path'
 import { fileURLToPath } from 'url'
-import { activeContracts, applyContractsResult, contractsConfigFrom } from './contracts/apply-contracts.ts'
 import { ROUTED_SCRIPTS } from './core/canonical-scripts.ts'
 import { FLOOR_IDS, resolveFloor, type FloorResolution } from './core/floor.ts'
 export { resolveFloor, type FloorResolution, type FloorSource } from './core/floor.ts'
-import { evaluateContractsOnce } from './contracts/contracts-once.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
 import type { ProseConfig } from './prose/run-prose.ts'
+import { proseWordsProblems } from './prose/ste.ts'
 import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.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 { RULE_ID_RE, validateRules } from './rules/rule.ts'
+import { builtinCheckIds } from './core/discover-checks.ts'
+import { parseWhen } from './core/when.ts'
+import type { Rule } from './check.ts'
 import { leakAllowProblems } from './hooks/leak-guard.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 { TASK_DEF_KEYS, type TaskDef } from './core/task-runner.ts'
+import { TEST_ONLY_UNIT_KEYS, UNIT_DECL_KEYS, type UnitDecl } from './release/unit-resolve.ts'
+import { TASK_DEF_KEYS, type TaskDef } from './check.ts'
 import { testsConfigProblems, type TestsConfig } from './suite/judge-suites.ts'
 import type { TuiPanelDef } from './tui/tui-panel.ts'
 import type { MdGraph } from './wiki/md-graph.ts'
@@ -35,23 +35,40 @@ import type { MdGraph } from './wiki/md-graph.ts'
 // rest by convention: agent/ graph when the dir exists, studio when the
 // kit loads)
 export type ServeConfig = {
-    /** hub port — house range 4800+; default hashes the repo name into 4800-4979 */
+    /** hub port, house range 4800+. The default hashes the repo name into 4800-4979 */
     port?: number
-    /** custom wiki-graph provider for repos with their own link semantics; default: generic md scan of the repo root */
-    wikiGraph?: { title?: string; load: () => MdGraph }
+    /** the comfy-ts panel the comfy section embeds runs as its own process on
+     *  its own port — house range 5800+, default = the hub port plus 1000
+     *  (build/comfyui.md owns that surface) */
+    comfyPort?: number
+    /** custom wiki-graph provider for repos with their own link semantics.
+     *  Default: a generic md scan of the repo root. */
+    wikiGraph?: {
+        /** the graph header title (default: the repo name) */
+        title?: string
+        /** builds the graph, called on every page load so a wiki edit shows up */
+        load: () => MdGraph
+        /** the check ids whose last verdicts are this wiki's verdict: red when
+         *  one failed, green when all passed. Default: the built-in md lint
+         *  (orphans and dangling refs) over the repo root */
+        lint?: string[]
+    }
     /** agent/ graph entrypoint (default: index.md AND README.md) */
     agentIndex?: string
-    /** off-machine hostname for the hub (e.g. a tailnet MagicDNS name) —
-     *  printed beside localhost and appended to ping messages (phones
-     *  can't resolve localhost) */
+    /** off-machine hostname for the hub, as in a tailnet MagicDNS name. It
+     *  prints beside localhost and rides on every ping message, because a
+     *  phone cannot resolve localhost */
     publicHost?: string
 }
 
 export type RepoConfig = {
+    /** the repo name, as every surface prints it: the gate header, the hub
+     *  title, the motherhome row, the default hub port hash. The pre-commit
+     *  root-identity gate compares it to the package.json name. */
     name: string
     /** venue ids this repo ships on — selects which contracts are REQUIRED */
     venues?: string[]
-    /** social channels with a .rv-social/<channel>/ post folder */
+    /** social channels with a .shipkit/social/<channel>/ post folder */
     social?: string[]
     /** prefix for contract fix: pointers (docs checkout or URL) — written by init, never baked in */
     docsBase?: string
@@ -62,13 +79,34 @@ export type RepoConfig = {
      *  restating the command: the read set is repo knowledge, the command is
      *  already in package.json, and restating it is a second source of truth. */
     defaults?: Record<string, Partial<TaskDef> | false>
-    /** repo-specific commit-gate tasks; deps double as race guards */
+    /** DEPRECATED, read through 0.40 and rewritten by `shipkit check --fix
+     *  SK016`: a build step is a `<name>.check.ts` file with `build: true` */
     tasks?: TaskDef[]
-    /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
-    asks?: { dir?: string; emptyText?: string }
-    /** secrets this repo needs; mint artifact rides as data (needs feed tile) */
-    creds?: { name: string; service?: string; mintUrl?: string; steps?: string[] }[]
-    /** store-command template for a missing secret tile, `{name}` substituted (e.g. your secret manager's set command) */
+    /** the human action queue: the folder it lives in, and the line the
+     *  all-clear prints (`shipkit asks`). */
+    asks?: {
+        /** the queue folder, repo-relative (default '.shipkit/asks') */
+        dir?: string
+        /** the `shipkit asks` all-clear line, in the repo's own voice */
+        emptyText?: string
+    }
+    /** the secrets this repo needs. The mint artifact rides as data, so a
+     *  missing one becomes a tile that says where to get it. */
+    creds?: {
+        /** the secret name the repo asks for, as `credsCommand` spells it */
+        name: string
+        /** which service issues it, shown as the tile description */
+        service?: string
+        /** where a human mints it, shown as the tile link */
+        mintUrl?: string
+        /** the steps to mint it, one line each */
+        steps?: string[]
+        /** the id of the check that proves it works (the id `--only` takes).
+         *  Its last recorded run, from a gate or a health pass, is the secret's
+         *  verdict. Absent: no check probes it, and the row says so */
+        probedBy?: string
+    }[]
+    /** store-command template for a missing secret tile, `{name}` substituted, as in your secret manager's set command */
     credsCommand?: string
     /** READ-command template, the twin of `credsCommand`: prints one field of
      *  a secret, `{name}` and `{field}` (get = the value, account = the
@@ -76,9 +114,16 @@ export type RepoConfig = {
      *  way a value reaches a command (`shipkit smoke` login), so it never sits
      *  in config, argv or env. Required when `smoke.login` is declared. */
     credsReadCommand?: string
-    /** notify command for new RED needs while the hub serves, `{message}` substituted (e.g. a push-notification CLI) */
+    /** notify command for new RED needs while the hub serves, `{message}` substituted, as in a push-notification CLI */
     notifyCommand?: string
-    contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
+    /** the `.shipkit/<venue>/` release contracts: which ones this repo is excused
+     *  from, and any manifest the published toolkit does not carry. */
+    contracts?: {
+        /** venue id to the reason it is waived. The only bypass, and it always prints */
+        exempt?: Record<string, string>
+        /** manifests declared by this repo, beside the built-in venues */
+        extra?: ContractManifest[]
+    }
     /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
      *  block — for ecosystem-specific names the published lib may not carry */
     gitignore?: string[]
@@ -92,9 +137,18 @@ export type RepoConfig = {
      *  folder only: it never commits, untracks, tags or pushes on the parent's
      *  history. Rule SK015 fails when this and the disk disagree (core/nesting.ts) */
     nested?: boolean
-    /** rule id → the reason this repo breaks that invariant on purpose. An
-     *  exempted rule does not lint and prints a skip line carrying the reason.
-     *  `defineRepo` throws on an unknown id or a blank reason */
+    /** WHERE EACH CHECK RUNS, keyed by check id. One declaration for a
+     *  question that used to have three: `'always'` every gate and every
+     *  health pass, `'release'` only at `--full` and on the release path,
+     *  `'health'` only in the health pass, `'off:<reason>'` not at all.
+     *  `defineRepo` throws on a value it cannot parse, on an `off` with no
+     *  reason, and on an id no check carries. The hub writes this
+     *  map through the managed block in this file (core/when-block.ts). */
+    when?: Record<string, string>
+    /** DEPRECATED, read into `when` as `off:<reason>`: rule id → the reason
+     *  this repo breaks that invariant on purpose. An exempted rule does not
+     *  lint and prints a skip line carrying the reason. `defineRepo` throws on
+     *  an unknown id or a blank reason */
     ruleExempt?: Record<string, string>
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
@@ -105,33 +159,45 @@ export type RepoConfig = {
      *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
      *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
      *  declared reviewer. */
-    reviewer?: { name: string; brief: string; tools?: string[] }
+    reviewer?: {
+        /** the agent type, kebab-case: `.claude/agents/<name>.md` */
+        name: string
+        /** path to the standing brief the agent reads first. It can sit outside the repo */
+        brief: string
+        /** widens the read-only tool allowlist SK008 enforces (default Read, Grep, Glob, Bash) */
+        tools?: string[]
+    }
     /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
      *  repo keeps as a direct tool call. Declared per NAME, never as a list of
      *  banned binaries: the invariant is about which VERBS an agent reaches
      *  for, and a binary blocklist goes stale the day a repo changes runner.
      *  A name outside ROUTED_SCRIPTS throws here, so a typo can never silently
      *  un-govern a script. Rule SK001 reads it. */
-    oneWayIn?: { exempt?: 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. */
+    oneWayIn?: {
+        /** governed script names this repo calls directly: the package.json
+         *  route and the shell deny both drop for each one named */
+        exempt?: string[]
+    }
+    /** DEPRECATED, read through 0.40: a repo invariant is a `<name>.check.ts`
+     *  file whose `run` is the old `lint`. SK016 names each entry, and moving
+     *  one is a hand pass because it holds a function */
     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[]
+    /** the units this repo is cut into, beside the mandatory root unit. Each
+     *  one scopes its own checks (`test:<unit id>` run in its dir, and
+     *  `typecheck:<unit id>` when it has a tsconfig) and, unless
+     *  it says `release: false`, is a releasable package with its own version,
+     *  tag and changelog. 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?: UnitDecl[]
     /** 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
+     *  cannot release 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
@@ -141,12 +207,14 @@ export type RepoConfig = {
      *  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 }
+    /** DEPRECATED, read through 0.40: what a legacy `*.check.ts` with no
+     *  `export const blocking` means. `shipkit check --fix SK016` names the
+     *  value in each script's port, where `blocking` is required, and drops
+     *  the key once no script leans on it */
+    checkDefaults?: {
+        /** what a `*.check.ts` with no `export const blocking` means here */
+        blocking?: boolean
+    }
     /** house prose in STE (identity/writing-voice.md), gated by rule SK014.
      *  `include` is what makes the rule run at all: a repo that declares no
      *  scope is skipped rather than failed, because STE binds the prose an
@@ -161,14 +229,20 @@ export type RepoConfig = {
      *  slow suites the quick tier leaves out, and the suites that cannot run in
      *  parallel, each with its reason. suite/judge-suites.ts */
     tests?: TestsConfig
-    /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
-    tui?: { panels?: TuiPanelDef[] }
+    /** the live dashboard, `shipkit tui`. */
+    tui?: {
+        /** extra dashboard panels, appended after the built-in build steps and checks panels (`shipkit tui`) */
+        panels?: TuiPanelDef[]
+    }
     /** the `shipkit serve` hub: port + optional graph hooks */
     serve?: ServeConfig
+    /** where a gate run writes its per task logs, repo-relative (default
+     *  '.shipkit/tmp/shipkit-ci'). Each run owns a subdir of it, so several agents in
+     *  one checkout never overwrite each other. Keep it gitignored. */
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -190,6 +264,13 @@ export function defineRepo(c: RepoConfig): RepoConfig {
             if (!UNIT_DECL_KEYS.includes(k)) throw new Error(`defineRepo: units['${u.dir}'] unknown key '${k}' (known: ${UNIT_DECL_KEYS.join(', ')})`)
         const problems = u.tests != null ? testsConfigProblems(u.tests) : []
         if (problems.length > 0) throw new Error(`defineRepo: units['${u.dir}'] ${problems[0]}`)
+        if ('release' in u && u.release !== false) throw new Error(`defineRepo: units['${u.dir}'].release takes only false (a unit that never releases)`)
+        if (u.release === false) {
+            const idle = Object.keys(u).filter((k) => !TEST_ONLY_UNIT_KEYS.includes(k))
+            if (idle.length > 0) throw new Error(`defineRepo: units['${u.dir}'] is release: false, so ${idle.join(', ')} describe(s) a release that never happens (it reads ${TEST_ONLY_UNIT_KEYS.join(', ')})`)
+        }
+        if (u.deps != null && (!Array.isArray(u.deps) || u.deps.some((d) => typeof d !== 'string' || d === '')))
+            throw new Error(`defineRepo: units['${u.dir}'].deps is a list of check ids`)
     }
     for (const d of c.notReleasable ?? []) {
         if (typeof d !== 'string' || d === '') throw new Error(`defineRepo: every notReleasable entry is a repo-relative dir path`)
@@ -226,14 +307,30 @@ export function defineRepo(c: RepoConfig): RepoConfig {
             throw new Error(`defineRepo: oneWayIn.exempt '${n}' is not a governed script name (governed: ${ROUTED_SCRIPTS.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 })
+    if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: builtinCheckIds() })
+    // a `when` moves a check off the gate, so a value it cannot act on dies
+    // here. The RULE namespace is the one this file can check: a task is
+    // resolved from the floor and a check is discovered on disk, so those two
+    // are caught by the gate against the real inventory (core/when.ts
+    // unknownWhenIds)
+    for (const [id, raw] of Object.entries(c.when ?? {})) {
+        if (id.trim() === '') throw new Error(`defineRepo: when has an entry with no check id`)
+        const w = parseWhen(raw)
+        if (typeof w === 'string') throw new Error(`defineRepo: when.${id} ${w}`)
+        if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
+            throw new Error(`defineRepo: when.${id} names no rule, the ids are in \`shipkit checks\``)
+    }
     // an exemption silences a gate, so it names a rule that exists and says why
     for (const [id, reason] of Object.entries(c.ruleExempt ?? {})) {
-        if (!BUILTIN_RULE_IDS.includes(id) && !(c.rules ?? []).some((r) => r.id === id))
-            throw new Error(`defineRepo: ruleExempt.${id} names no rule, the ids are in \`shipkit rules\``)
+        if (!builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
+            throw new Error(`defineRepo: ruleExempt.${id} names no rule, the ids are in \`shipkit checks\``)
         if (typeof reason !== 'string' || reason.trim() === '')
             throw new Error(`defineRepo: ruleExempt.${id} needs a reason, an exemption nobody can explain is a silenced gate`)
     }
+    // a word list entry silences or adds gate hits, so a malformed one dies
+    // here rather than matching nothing
+    const words = proseWordsProblems(c.prose?.words)
+    if (words.length > 0) throw new Error(`defineRepo: ${words[0]}`)
     // a smoke typo would land as a run that visits nothing and exits 0
     if (c.smoke != null) validateSmokeConfig(c.smoke)
     // a leak-guard waiver is the one config row that can make a gate quieter,
@@ -253,40 +350,13 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     return c
 }
 
-export async function loadRepoConfig(root: string): Promise<RepoConfig> {
+/** `fresh` busts the module cache: a process that WROTE the config (the hub's
+ *  toggle) must read the bytes it just wrote, and an ES module import is
+ *  cached by path for the life of the process */
+export async function loadRepoConfig(root: string, o: { fresh?: boolean } = {}): Promise<RepoConfig> {
     const path = join(root, 'repo.config.ts')
     if (!existsSync(path)) throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
-    const mod = (await import(path)) as { default?: RepoConfig }
+    const mod = (await import(o.fresh === true ? `${path}?v=${Date.now()}-${Math.random().toString(36).slice(2)}` : path)) as { default?: RepoConfig }
     if (mod.default == null) throw new Error(`${path}: must default-export defineRepo({...})`)
     return mod.default
 }
-
-// the contracts commit-gate task — venue deploy tasks should dep on it.
-// Same SK002-tagged rendering as `shipkit check` and `shipkit contracts`
-// (contracts/apply-contracts.ts is the one bridge).
-//
-// DELIBERATELY UNDECLARED for the ledger, and this is where that decision
-// lives rather than in a commit message. It runs in process, shares one
-// evaluation with rule SK002 through `withContractsScope`, and measures 0.0s,
-// so a key would be risk against no reward. It is not `never:` either: the
-// contract dirs describe it perfectly well, so claiming nothing can is false,
-// and `never` has to keep meaning "somebody looked and no key exists".
-//
-// Declaring `inputs: ['.']` to clear its burn-down row was TRIED and reverted:
-// a keyable contracts task writes a ledger entry inside every fixture repo,
-// which is six ledger tests asserting an entry count that is really about the
-// task under test. The row it leaves behind is the honest cost of the model
-// having no third state between "nobody looked" and "no key can exist".
-export function contractsTask(c: RepoConfig, root: string): TaskDef {
-    return {
-        id: 'contracts',
-        logic: async (t) => {
-            applyContractsResult(t, await evaluateContractsOnce(activeContracts(c), contractsConfigFrom(c, root)), contractsFulfillness)
-        },
-    }
-}
-
-export function allTasks(c: RepoConfig, root: string): FloorResolution {
-    const floor = resolveFloor(c, root)
-    return { ...floor, tasks: [...floor.tasks, contractsTask(c, root), ...(c.tasks ?? [])] }
-}

package/src/rules/rule.ts

@@ -1,103 +1,43 @@
-// Rule — one machine-enforced invariant with a stable id. One module per
-// rule (`src/rules/SK###-<slug>.ts`), registered in rule-registry.ts; ids
-// are never reused or renumbered. `shipkit check` runs every rule's lint;
-// a rule may also carry an idempotent fix() (the `check --fix` runner).
-// Every wire line a rule emits is tagged `[SK###]` so output is greppable
-// by rule and a fix pointer names the rule that can repair it.
-import type { CheckCtx } from '../core/check-ctx.ts'
-import type { Line } from '../core/wire.ts'
-import type { RepoConfig } from '../repo-config.ts'
+// The LEGACY rule shape, kept for the compatibility window. A repo that
+// still registers invariants through `repo.config.ts rules: []` imports
+// `Rule` from here, and the engine reads each one as a check whose body is
+// `lint` (check.ts owns the shape now). Both die together, at the first
+// release after `shipkit fleet` shows no repo below 0.40.
+//
+// A new invariant is a `<name>.check.ts` file: `check({ blocking, run })`,
+// dropped anywhere in the repo, discovered with no config edit.
+import { whenOfRule } from '../core/when.ts'
+import { tagCheckLines, checkCacheExtra, type Rule, type RuleEnv } from '../check.ts'
 
-export type RuleEnv = { root: string; config: RepoConfig }
+export type { FixResult, Rule, RuleEnv } from '../check.ts'
 
-export type FixResult = { changed: boolean; summary: string }
-
-export type Rule = {
-    /** stable PREFIX + 3 digits, never reused or renumbered (the registry throws).
-     *  `SK###` is reserved for shipkit's built-ins; a repo registering its own
-     *  rules through `repo.config.ts rules: []` picks its own prefix (`RV###`). */
-    id: string
-    /** check-suite display name — stable: the check name in STATUS.md, the TUI row, and the suite cache */
-    title: string
-    /** can this stop you? REQUIRED, no default. true = a failure is about THIS
-     *  repo and blocks. false = it reports the world (a box that is off, a cred
-     *  nobody minted), so a failure prints as a warning and never blocks.
-     *  The only question worth asking about a check, asked once, in one place. */
-    blocking: boolean
-    /** wiki page owning the invariant — the run-check framework appends `docsBase + owner`
-     *  as the fix: pointer whenever a failing/warning lint attached none */
-    owner: string
-    /** clean-pass cache duration (check-suite TTL, e.g. '24h') — for rules that
-     *  probe the network; skip/WARN/FAIL runs are never cached. Declares the
-     *  WORLD population (ledger/git-key.ts). */
-    ttl?: string
-    /** CONTENT population: the repo-relative paths this rule reads. A rule with
-     *  neither `inputs` nor `ttl` is never cached, which is the safe default.
-     *  A rule declared by a REPO rather than by shipkit must list the dir its
-     *  own code lives in too: shipkit's `src` tree id covers the built-ins and
-     *  cannot see a repo's. Declaring both `inputs` and `ttl` is a registration
-     *  failure — a rule reads files or it reads the world, never both. */
-    inputs?: string[]
-    /** repo-relative entry file(s) of this rule's OWN code, walked through the
-     *  module graph so a shared helper the rule imports is in its key too. A
-     *  built-in SK rule needs none: the toolchain identity content-hashes
-     *  shipkit's whole source, so editing any of it moves every key. A rule a
-     *  REPO declares is invisible to that, so it names its module here, or
-     *  includes the dir holding it in `inputs`. Without either, fixing a bug
-     *  in the rule does not move its key. */
-    code?: string[]
-    /** a DECIDED never-cacheable, with the reason: this rule reads git history,
-     *  a path that may live outside the repo, or the wall clock, so no key can
-     *  describe it. Says somebody looked, which is what takes it off the
-     *  burn-down list. */
-    never?: string
-    /** cache-identity contribution for TTL'd rules whose verdict depends on
-     *  config — a changed key busts the cache instantly instead of replaying
-     *  a stale assertion for the TTL */
-    cacheKey?: (env: RuleEnv) => string
-    lint: (t: CheckCtx, env: RuleEnv) => void | Promise<void>
-    /** idempotent auto-repair; `check --fix` applies it then re-lints — never interactive */
-    fix?: (env: RuleEnv) => FixResult | Promise<FixResult>
-}
-
-/** the config part of a rule's cache identity */
+/** the config part of a rule's cache identity, including where it runs */
 export function ruleCacheExtra(rule: Rule, env: RuleEnv): string | undefined {
-    const key = rule.cacheKey?.(env)
-    const exempt = env.config.ruleExempt?.[rule.id]
-    return exempt == null ? key : `${key ?? ''}|exempt:${exempt}`
+    return checkCacheExtra(rule, env, whenOfRule(env.config, rule.id))
 }
 
-// THE one way to run a rule's lint (check suite + the --fix runner): a
-// throwing lint still fails with its id, a failing/warning run always
-// carries at least one fix: pointer (the lint's own precise ones win, else
-// docsBase + the rule's owner page), and every line gets tagged.
-export async function runRuleLint(rule: Rule, t: CheckCtx, env: RuleEnv): Promise<void> {
-    const exempt = env.config.ruleExempt?.[rule.id]
-    if (exempt != null) {
-        t.lines.push({ kind: 'skip', text: `${rule.id} exempt: ${exempt}` })
-        t.lines = tagRuleLines(rule, t.lines)
-        return
-    }
-    try {
-        await rule.lint(t, env)
-    } catch (e) {
-        t.fail(`${rule.title} lint errored (${String(e).slice(0, 200)}) — network down, or a bug in this rule`)
-    }
-    if ((t.failed || t.warned) && !t.lines.some((l) => l.kind === 'fix-fail' || l.kind === 'fix-warn'))
-        t.lines.push({ kind: t.failed ? 'fix-fail' : 'fix-warn', text: `${env.config.docsBase ?? ''}${rule.owner}` })
-    t.lines = tagRuleLines(rule, t.lines)
-}
+/** tag every severity line with the rule id (check.ts owns the rendering) */
+export const tagRuleLines = tagCheckLines
+
+// ── the legacy id namespace ──────────────────────────────────────────────
+// A rule id is PREFIX plus exactly 3 digits, and `SK` is reserved for the
+// toolkit's own checks so a repo rule can never shadow one. A `*.check.ts`
+// file takes its id from its NAME and may use plain words, so this shape
+// binds the `rules: []` key only.
 
-// tag every severity line with the rule id; fix pointers of a fixable rule
-// advertise the autofix. Idempotent — already-tagged lines pass through
-// (cached suite replays re-enter here).
-export function tagRuleLines(rule: Rule, lines: Line[]): Line[] {
-    return lines.map((l) => {
-        if (l.kind === 'fix-warn' || l.kind === 'fix-fail')
-            return rule.fix == null || l.text.includes('--fix ')
-                ? l
-                : { ...l, text: `${l.text} · autofix: shipkit check --fix ${rule.id}` }
-        if (l.kind === 'note') return l
-        return l.text.startsWith(`[${rule.id}]`) ? l : { ...l, text: `[${rule.id}] ${l.text}` }
-    })
+export const RULE_ID_RE = /^[A-Z]{2,4}\d{3}$/
+
+/** validate the rules a repo registers. Throws on a malformed id, a
+ *  duplicate, a missing owner page, or one squatting the reserved SK
+ *  prefix, so a bad registration dies at config load and never mid gate. */
+export function validateRules(rules: readonly Rule[], o: { label: string; taken?: Iterable<string> } = { label: 'rules' }): void {
+    const seen = new Set<string>(o.taken ?? [])
+    for (const r of rules) {
+        if (!RULE_ID_RE.test(r.id)) throw new Error(`${o.label}: bad id '${r.id}' — rules are PREFIX+3 digits (e.g. SK001, RV001)`)
+        if (r.id.startsWith('SK'))
+            throw new Error(`${o.label}: id '${r.id}' uses the reserved SK prefix — repo rules pick their own (e.g. RV${r.id.slice(-3)})`)
+        if (seen.has(r.id)) throw new Error(`${o.label}: duplicate id ${r.id}`)
+        if (r.owner === '') throw new Error(`${o.label}: ${r.id} has no owner page`)
+        seen.add(r.id)
+    }
 }

package/src/rules/untrack-generated.ts

@@ -23,9 +23,10 @@
 // it could surprise someone.
 import { existsSync } from 'fs'
 import { join } from 'path'
+import { gitBin } from '../core/git-bin.ts'
 
-/** rendered into the SK004 managed block. A glob is fine HERE: ignoring is
- *  not destructive. */
+/** rendered into the SK004 managed block, by basename so they match wherever
+ *  they sit. A glob is fine HERE: ignoring is not destructive. */
 export const GENERATED_IGNORE_LINES = [
     '# shipkit writes these on every run — ignored AND untracked (untrack-generated.ts)',
     'STATUS.md',
@@ -40,7 +41,7 @@ export const GENERATED_IGNORE_LINES = [
  *  never derived from a pattern: `git rm --cached` driven by a wildcard is how
  *  a fixer eats source it was never pointed at. A future entry is added HERE,
  *  by hand, spelled out. */
-export const GENERATED_TRACKED_PATHS = ['STATUS.md', 'STATUS.md.lock', 'STATUS.full.md', 'STATUS.full.md.lock'] as const
+export const GENERATED_TRACKED_PATHS = ['.shipkit/STATUS.md', '.shipkit/STATUS.md.lock', '.shipkit/STATUS.full.md', '.shipkit/STATUS.full.md.lock'] as const
 
 export type UntrackOutcome =
     | { did: 'nothing' }
@@ -48,7 +49,7 @@ export type UntrackOutcome =
     | { did: 'untracked'; paths: string[]; commit: string }
 
 const git = (root: string, args: string[]): { code: number; out: string } => {
-    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    const p = Bun.spawnSync([gitBin(), ...args], { cwd: root })
     return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
 }
 

package/src/scaffold/files/vscode-tasks.json

@@ -1,45 +1,24 @@
 {
-   // one master task with runOn folderOpen, every dev process as a subtask.
-   // Opening the folder in vscode starts them all. Add a subtask per
-   // long-running watcher the stack earns (dev server, css, tests), never
-   // for a one-off script.
+   // the hub is the one process every wired repo starts, so it opens with the
+   // folder itself. It runs every check after each save and its problem
+   // matcher fills the problems pane, so there is no type checker task. A
+   // stack that earns more long-running watchers (dev server, css) adds a
+   // master task with runOn folderOpen whose dependsOn lists them all, the hub
+   // included, and moves runOn off the hub.
    "version": "2.0.0",
    "tasks": [
-      {
-         "label": "starts everything",
-         "dependsOn": ["👁  TSC", "🚀  shipkit"],
-         "group": { "kind": "build", "isDefault": true },
-         "runOptions": { "runOn": "folderOpen", "instanceLimit": 1 },
-         "problemMatcher": []
-      },
-      {
-         "label": "👁  TSC",
-         "detail": "Get all typescript errors in problems pane",
-         "type": "process",
-         "command": "${workspaceFolder}/node_modules/.bin/tsc",
-         "args": ["--noEmit", "--incremental", "--watch", "--project", "tsconfig.json"],
-         "options": {
-            "cwd": "${workspaceFolder}",
-            "env": { "NODE_OPTIONS": "--max-old-space-size=8192" }
-         },
-         "isBackground": true,
-         "presentation": { "reveal": "never", "clear": true },
-         "group": "build",
-         "runOptions": { "instanceLimit": 1 },
-         "problemMatcher": []
-      },
       {
          "label": "🚀  shipkit",
-         "detail": "The shipkit hub at http://localhost:{{PORT}} — clickable URLs: the page, /graph/wiki, /graph/agent",
+         "detail": "The shipkit hub at http://localhost:{{PORT}}, and every check's findings in the problems pane — clickable URLs: the page, /graph/wiki, /graph/agent",
          "type": "process",
          "command": "bun",
          "args": ["run", "hub"],
          "options": { "cwd": "${workspaceFolder}" },
          "isBackground": true,
          "presentation": { "reveal": "always", "close": false },
-         "group": "build",
-         "runOptions": { "instanceLimit": 1 },
-         "problemMatcher": []
+         "group": { "kind": "build", "isDefault": true },
+         "runOptions": { "runOn": "folderOpen", "instanceLimit": 1 },
+         "problemMatcher": {{HUB_PROBLEM_MATCHER}}
       }
    ]
 }