rvlib-shipkit 0.13.0 → 0.16.0

package/src/rules/SK008-reviewer-agent.ts

@@ -0,0 +1,99 @@
+// SK008 — the mandated reviewer agent type. A repo that declares
+// `reviewer: { name, brief }` must carry `.claude/agents/<name>.md`: an agent
+// definition whose system prompt POINTS at the brief file (ONE home for the
+// text, so review framing can never drift per repo) and whose `tools:` line
+// stays inside a read-only ALLOWLIST — a reviewer's product is findings, never
+// fixes, and a denylist of today's edit-tool names would wave through anything
+// that edits by proxy. An absent `tools:` line is the worst case of all: the
+// harness then inherits every tool. The brief itself must exist. No
+// declaration = not a reviewer repo, and the rule passes silently.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, isAbsolute, join } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+
+/** default read-only toolset — an ALLOWLIST, not a denylist: a tool that can
+ *  edit by proxy (spawning a subagent, an MCP writer) is exactly what a
+ *  denylist of today's edit-tool names would wave through */
+export const REVIEWER_TOOLS = ['Read', 'Grep', 'Glob', 'Bash']
+
+export const reviewerAgentPath = (name: string): string => `.claude/agents/${name}.md`
+
+// the invariants, as a pure function over the file text — the rule below and
+// any repo-local linter call THIS, so there is one definition of "a valid
+// reviewer agent file" and not one per caller
+export function reviewerAgentIssues(text: string, reviewer: NonNullable<RepoConfig['reviewer']>): string[] {
+    const issues: string[] = []
+    const allowed = reviewer.tools ?? REVIEWER_TOOLS
+    const declared = text.match(/^name:\s*(\S+)\s*$/m)?.[1]
+    if (declared !== reviewer.name)
+        issues.push(`frontmatter name is ${declared == null ? 'missing' : `'${declared}'`} — it must be '${reviewer.name}', the type spawners ask for`)
+    if (!text.includes(reviewer.brief))
+        issues.push(`never points at the brief '${reviewer.brief}' — the agent's whole job is to load it before judging anything`)
+    const tools = text.match(/^tools:\s*(.+)$/m)?.[1]
+    if (tools == null) issues.push(`has no inline 'tools:' allowlist — omitting it inherits every tool, edit tools included`)
+    else
+        for (const t of tools.split(',').map((x) => x.trim()).filter(Boolean))
+            if (!allowed.includes(t)) issues.push(`grants '${t}', outside the allowlist (${allowed.join(', ')}) — a reviewer reports findings, it never edits, directly or by proxy`)
+    return issues
+}
+
+/** the brief must EXIST: a reviewer whose mandated first action is reading a
+ *  missing file flounders silently, which is the one thing this rule prevents */
+export function briefMissing(root: string, brief: string): boolean {
+    const p = brief.startsWith('~/') ? join(homedir(), brief.slice(2)) : isAbsolute(brief) ? brief : join(root, brief)
+    return !existsSync(p)
+}
+
+function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
+    return `---
+name: ${reviewer.name}
+description: The mandated critical reviewer for this repo. Use before every commit, and whenever a diff needs judging against what was actually asked for. Judges whether a change should exist at all, not just whether it is correct.
+tools: ${(reviewer.tools ?? REVIEWER_TOOLS).join(', ')}
+model: opus
+---
+
+You are this repo's critical reviewer. You have no Edit or Write tool on
+purpose: your product is findings, never fixes. Bash is for READING the state
+of things (\`git diff\`, the gates, running a claim to check it) — never for
+writing files by another route.
+
+FIRST ACTION, always: read \`${reviewer.brief}\` and follow it exactly. It tells
+you what else to read, when to refuse the job, the order of the questions, and
+the output shape.
+
+That brief overrides any habit of reviewing a diff for correctness alone.
+`
+}
+
+export const reviewerAgent: Rule = {
+    id: 'SK008',
+    blocking: true,
+    title: 'reviewer agent',
+    owner: 'identity/how-we-work.md',
+    lint: (t, env) => {
+        const r = env.config.reviewer
+        if (r == null) return t.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
+        const rel = reviewerAgentPath(r.name)
+        const p = join(env.root, rel)
+        if (briefMissing(env.root, r.brief)) t.fail(`the declared brief '${r.brief}' does not exist — every review's mandated first action would fail`)
+        if (!existsSync(p)) return t.fail(`${rel} missing — the mandated reviewer type is unavailable, so every review runs on whatever framing the spawner improvised`)
+        const issues = reviewerAgentIssues(readFileSync(p, 'utf8'), r)
+        for (const i of issues) t.fail(`${rel}: ${i}`)
+        if (issues.length === 0 && !t.failed) t.ok(`${rel} → ${r.brief}`)
+    },
+    // create-if-missing only: an existing definition may carry a repo's own
+    // tuned prompt, and silently rewriting that would cost more than the
+    // finding it repairs. Violations in a present file stay a loud FAIL.
+    fix: (env: RuleEnv): FixResult => {
+        const r = env.config.reviewer
+        if (r == null) return { changed: false, summary: 'no reviewer declared — nothing to write' }
+        const rel = reviewerAgentPath(r.name)
+        const p = join(env.root, rel)
+        if (existsSync(p)) return { changed: false, summary: `${rel} exists — remaining findings are about its content, fix them by hand` }
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, canonicalAgent(r))
+        return { changed: true, summary: `${rel} written — points at ${r.brief}, no edit tools` }
+    },
+}

package/src/rules/SK009-commit-ai-tells.ts

@@ -0,0 +1,66 @@
+// SK009 — commit AI tells (identity/how-we-commit.md): a repo that will be
+// seen must not read as AI-driven. Prevention lives at the source (the
+// attribution setting + the standing from-commit-one ban, which binds every
+// repo because history follows a repo public and is never rewritten); this
+// rule is the declared-public tripwire: the FULL git log scanned for AI
+// attribution and dash punctuation, plus the tracked settings file that
+// silences attribution. Declared-private repos idle with an ok that RESTATES
+// the ban — a green line must never teach the wrong rule. The remedy for
+// pushed history is the owner's decision, never an automatic rewrite; only
+// an unpushed tip commit may be amended, and the fails say so.
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
+import type { Rule } from './rule.ts'
+
+// the documented silencer: .claude/settings.json attribution.commit/.pr both
+// empty — the harness then never writes the trailer or the PR footer
+const attributionSilenced = (root: string): boolean => {
+    try {
+        const s = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf8')) as { attribution?: { commit?: string; pr?: string } }
+        return s.attribution != null && s.attribution.commit === '' && s.attribution.pr === ''
+    } catch {
+        return false
+    }
+}
+
+export const commitAiTells: Rule = {
+    id: 'SK009',
+    blocking: true,
+    title: 'commit ai tells',
+    owner: 'identity/how-we-commit.md',
+    lint: async (t, env) => {
+        const declared = env.config.visibility ?? 'private'
+        if (declared !== 'public')
+            return t.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
+        // %x1f separates hash from body, %x1e terminates the record — commit
+        // bodies are free text, so only unprintable separators are safe
+        const log = await t.exec(['git', 'log', '--format=%h%x1f%B%x1e'], { cwd: env.root, timeoutMs: 30_000 })
+        if (log.code !== 0) {
+            const first = log.out.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? `exit ${log.code}`
+            return void t.lines.push({ kind: 'skip', text: `commit history unverifiable — git says: ${first}` })
+        }
+        const commits = log.out
+            .split('\x1e')
+            .map((r) => r.trim())
+            .filter((r) => r !== '')
+            .map((r) => {
+                const cut = r.indexOf('\x1f')
+                return { hash: r.slice(0, cut), body: r.slice(cut + 1) }
+            })
+        if (commits.length === 0) return void t.lines.push({ kind: 'skip', text: 'commit history unverifiable — no commits yet' })
+        const remedy = 'an unpushed TIP commit may be amended; anything deeper is the owner\'s decision (history is never rewritten as a side effect)'
+        const sample = (hits: { hash: string }[]): string => hits.slice(0, 5).map((h) => h.hash).join(' ') + (hits.length > 5 ? ' …' : '')
+        const attributed = commits.filter((c) => hasAiAttribution(c.body))
+        const dashed = commits.filter((c) => hasDashPunctuation(c.body))
+        if (attributed.length > 0)
+            t.fail(`${attributed.length}/${commits.length} commits carry AI attribution (a trailer naming an assistant / "Generated with" / 🤖) in a declared-public repo — e.g. ${sample(attributed)}; ${remedy}`)
+        if (dashed.length > 0)
+            t.fail(`${dashed.length}/${commits.length} commit messages carry dash punctuation (em/en dash or inline " - ") in a declared-public repo — e.g. ${sample(dashed)}; ${remedy} (identity/writing-voice.md owns the punctuation rule)`)
+        const silenced = attributionSilenced(env.root)
+        if (!silenced)
+            t.fail(`.claude/settings.json does not silence AI attribution — track it with {"attribution": {"commit": "", "pr": ""}} so no agent's harness ever writes the trailer or the PR footer`)
+        if (attributed.length === 0 && dashed.length === 0 && silenced)
+            t.ok(`${commits.length} commits scanned, attribution silenced in .claude/settings.json — no AI tells`)
+    },
+}

package/src/rules/SK010-undeclared-release-unit.ts

@@ -0,0 +1,114 @@
+// SK010 — undeclared release unit (build/shipkit.md). Release units are
+// DECLARED, never inferred, so resolution is deterministic. This rule is the
+// other half of that deal: a package.json sitting in the repo that no unit
+// claims would be invisible to every release surface, and its version would
+// drift forever with nothing reporting it. Two declarations clear it, so the
+// green is always reachable: `units: [{ dir }]` for a releasable package,
+// `notReleasable: [dir]` for one that ships inside something else. That second
+// escape has teeth on purpose, because it is the one an agent staring at a red
+// gate reaches for: an entry must cover at least one real package and never the
+// whole repo, and the green counts the PACKAGES it excused, so a wide entry
+// cannot read as a narrow one.
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { resolveUnits } from '../release/units.ts'
+import type { Rule } from './rule.ts'
+
+const SKIP = new Set(['node_modules', 'references', 'tmp', 'stats', 'dist', 'build'])
+
+/** package dirs git knows about (tracked + untracked-not-ignored), so a
+ *  gitignored vendor tree or a python venv never trips the gate. Null when
+ *  git cannot answer, and the caller falls back to walking. */
+function gitPackageDirs(root: string): string[] | null {
+    const p = Bun.spawnSync(['git', 'ls-files', '--cached', '--others', '--exclude-standard', '-z'], { cwd: root })
+    if (p.exitCode !== 0) return null
+    return p.stdout.toString().split('\0')
+        .filter((f) => f === 'package.json' || f.endsWith('/package.json'))
+        .map((f) => join(root, f, '..'))
+}
+
+/** the fs fallback: an unreadable entry (a dangling symlink, an unmounted
+ *  volume) is skipped, never thrown — a broken link is not a release fact */
+function walkPackageDirs(root: string): string[] {
+    const out: string[] = [root]
+    const walk = (dir: string): void => {
+        let entries: string[]
+        try { entries = readdirSync(dir) } catch { return }
+        for (const e of entries) {
+            if (SKIP.has(e) || e.startsWith('.')) continue
+            const p = join(dir, e)
+            try { if (!statSync(p).isDirectory()) continue } catch { continue }
+            if (existsSync(join(p, 'package.json'))) out.push(p)
+            walk(p)
+        }
+    }
+    walk(root)
+    return out
+}
+
+/** every package.json below the root that carries a name, root excluded */
+export function packageDirs(root: string): string[] {
+    const dirs = gitPackageDirs(root) ?? walkPackageDirs(root)
+    const named = dirs.filter((d) => {
+        if (d === root) return false
+        if (relative(root, d).split('/').some((seg) => SKIP.has(seg) || seg.startsWith('.'))) return false
+        try {
+            const pkg = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')) as { name?: string }
+            return typeof pkg.name === 'string' && pkg.name !== ''
+        } catch { return false } // a broken package.json is SK001's story, not this rule's
+    })
+    return [...new Set(named)].sort()
+}
+
+export const undeclaredReleaseUnit: Rule = {
+    id: 'SK010',
+    blocking: true,
+    title: 'release units declared',
+    owner: 'build/shipkit.md',
+    lint: (t, env) => {
+        const { units, errors } = resolveUnits(env.root, env.config)
+        // a DECLARED unit that does not resolve is a declaration bug and
+        // belongs here. A root package that is not release-shaped (no version
+        // yet) is not: the release path refuses on its own, the day it matters.
+        const declared = errors.filter((e) => e.id !== 'root')
+        if (declared.length > 0) {
+            for (const e of declared) t.fail(`declared unit '${e.id}' does not resolve: ${e.message}`, 'repo.config units[]')
+            return
+        }
+        // an entry is a PREFIX over the packages under it, so `examples/` can
+        // excuse examples/a and examples/b without enumerating them. Two shapes
+        // are refused, both being the kill switch this rule exists to prevent:
+        // an entry covering the whole repo, and one covering nothing today that
+        // stands ready to excuse whatever lands there tomorrow. defineRepo
+        // refuses the root too, and a repo.config.ts that never calls it is
+        // exactly why the check also lives in the blocking rule.
+        const decls = env.config.notReleasable ?? []
+        const covered = (list: string[], d: string): boolean => list.some((c) => d === c || d.startsWith(`${c}/`))
+        const pkgs = packageDirs(env.root)
+        const wide = decls.filter((d) => join(env.root, d) === env.root)
+        if (wide.length > 0) {
+            for (const d of wide)
+                t.fail(`notReleasable '${d}' resolves to the repo root, so it excuses every package at once`, `repo.config notReleasable: name one package dir (or one container dir) per entry`)
+            return
+        }
+        const empty = decls.filter((d) => !pkgs.some((p) => covered([join(env.root, d)], p)))
+        if (empty.length > 0) {
+            for (const d of empty)
+                t.fail(`notReleasable '${d}' covers no package.json, so it excuses no package today and every package that lands there tomorrow`, `repo.config notReleasable: point it at a package dir (or a dir holding some), or drop the entry`)
+            return
+        }
+        const excused = decls.map((d) => join(env.root, d))
+        const claimed = [...units.filter((u) => u.rel !== '').map((u) => u.dir), ...excused]
+        const orphans = pkgs.filter((d) => !covered(claimed, d))
+        if (orphans.length === 0) {
+            // PACKAGES, not entries: one entry over a nested tree excuses more
+            // than one, and the count is the only place that shows it
+            const n = pkgs.filter((d) => covered(excused, d)).length
+            return t.ok(`${units.length} release unit(s) declared${units.length === 1 ? ' (the repo root)' : ''}${n > 0 ? ` + ${n} package(s) declared not releasable` : ''} — no package hides from a release`)
+        }
+        for (const d of orphans) {
+            const rel = relative(env.root, d)
+            t.fail(`${rel}/package.json is claimed by nothing — declare what it is, or its version drifts with nothing watching`, `repo.config units: [{ dir: '${rel}' }] if it releases, else notReleasable: ['${rel}']`)
+        }
+    },
+}

package/src/rules/rule-registry.ts

@@ -10,6 +10,9 @@ import { gitignorePolicy } from './SK004-gitignore-policy.ts'
 import { rvlibVersions } from './SK005-rvlib-versions.ts'
 import { npmPublishSafety } from './SK006-npm-publish-safety.ts'
 import { githubVisibility } from './SK007-github-visibility.ts'
+import { reviewerAgent } from './SK008-reviewer-agent.ts'
+import { commitAiTells } from './SK009-commit-ai-tells.ts'
+import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -19,14 +22,33 @@ export const RULES: readonly Rule[] = [
     rvlibVersions,
     npmPublishSafety,
     githubVisibility,
+    reviewerAgent,
+    commitAiTells,
+    undeclaredReleaseUnit,
 ]
 
-const seen = new Set<string>()
-for (const r of RULES) {
-    if (!/^SK\d{3}$/.test(r.id)) throw new Error(`rule-registry: bad id '${r.id}' — rules are SK### (3 digits, never reused)`)
-    if (seen.has(r.id)) throw new Error(`rule-registry: duplicate id ${r.id}`)
-    if (r.owner === '') throw new Error(`rule-registry: ${r.id} has no owner page`)
-    seen.add(r.id)
+// THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is
+// reserved for the built-ins above so a repo rule can never shadow one.
+export const RULE_ID_RE = /^[A-Z]{2,4}\d{3}$/
+
+/** validate a rule set and its ids against everything already registered.
+ *  Throws on a malformed id, a duplicate, a missing owner page, or a repo
+ *  rule squatting the reserved SK prefix. Shared by the built-in registry
+ *  and by `defineRepo`, so both die loud at import time. */
+export function validateRules(rules: readonly Rule[], o: { label: string; builtin?: boolean; taken?: Iterable<string> } = { label: 'rule-registry' }): 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 (o.builtin !== true && 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)
+    }
 }
 
+validateRules(RULES, { label: 'rule-registry', builtin: true })
+
+export const BUILTIN_RULE_IDS: readonly string[] = RULES.map((r) => r.id)
+
 export const ruleById = (id: string): Rule | undefined => RULES.find((r) => r.id === id)

package/src/rules/rule.ts

@@ -13,10 +13,17 @@ export type RuleEnv = { root: string; config: RepoConfig }
 export type FixResult = { changed: boolean; summary: string }
 
 export type Rule = {
-    /** stable `SK` + 3 digits — never reused, never renumbered (registry throws) */
+    /** 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

package/src/rules/run-fix.ts

@@ -6,11 +6,14 @@
 import { CheckCtx } from '../core/check-ctx.ts'
 import { formatLine } from '../core/wire.ts'
 import { loadRepoConfig } from '../repo-config.ts'
-import { RULES, ruleById } from './rule-registry.ts'
+import { RULES } from './rule-registry.ts'
 import { runRuleLint, type RuleEnv } from './rule.ts'
 
 export type FixOpts = {
     ids?: string[]
+    /** drop the closing advisory: inside the ci fix pass it is noise, and it is
+     *  not wire-shaped, which the frozen output contract forbids */
+    quiet?: boolean
     print?: (line: string) => void
 }
 
@@ -19,11 +22,13 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
     const config = await loadRepoConfig(root)
     const env: RuleEnv = { root, config }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
+    // the repo's own rules fix exactly like the built-ins, one code path
+    const all = [...RULES, ...(config.rules ?? [])]
 
-    let targets = RULES.filter((r) => r.fix != null)
+    let targets = all.filter((r) => r.fix != null)
     if (o.ids != null && o.ids.length > 0) {
         for (const id of o.ids) {
-            const r = ruleById(id)
+            const r = all.find((x) => x.id === id)
             if (r == null) { print(`FAIL: unknown rule '${id}' — see: shipkit rules`); return 1 }
             if (r.fix == null) { print(`FAIL: [${id}] has no autofix — fix by hand: ${config.docsBase ?? ''}${r.owner}`); return 1 }
         }
@@ -36,7 +41,9 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
         const before = new CheckCtx(new Map())
         await runRuleLint(rule, before, env)
         if (!before.failed && !before.warned) {
-            print(`ok: [${rule.id}] already clean — nothing to fix`)
+            // inside the ci fix pass, a line per already-clean rule is a wall of
+            // nothing above the run that reports those same rules for real
+            if (o.quiet !== true) print(`ok: [${rule.id}] already clean — nothing to fix`)
             continue
         }
         const f = await rule.fix!(env)
@@ -47,11 +54,11 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
         await runRuleLint(rule, after, env)
         // the fix already ran: advertising it again on surviving findings
         // would send an agent in a loop
-        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix SK\d{3}$/, '') }, color))
+        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix [A-Z]{2,4}\d{3}$/, '') }, color))
         if (after.failed) exit = 1
     }
-    const unfixable = RULES.filter((r) => r.fix == null).length
-    if (unfixable > 0 && (o.ids == null || o.ids.length === 0))
-        print(`${unfixable} rule(s) have no autofix — run \`shipkit check\` for the full repo state`)
+    const unfixable = all.filter((r) => r.fix == null).length
+    if (unfixable > 0 && o.quiet !== true && (o.ids == null || o.ids.length === 0))
+        print(`${unfixable} rule(s) have no autofix — they report in the run below`)
     return exit
 }

package/src/serve/hub-app/col-card.tsx

@@ -104,7 +104,7 @@ export const ColCard = observer(({ app, col, id }: { app: HubSt; col: string; id
 })
 
 // collection view — one card per visible instance, the stage-side twin of a
-// sidebar section (his rule 2026-07-23: every section gets both views)
+// sidebar section (every section gets both views)
 export const ColGrid = observer(({ app, id }: { app: HubSt; id: string }) => {
     const c = app.cols
     const col = c.sidebarCols.find((x) => x.id === id)
@@ -145,8 +145,7 @@ export const ColGrid = observer(({ app, id }: { app: HubSt; id: string }) => {
     )
 })
 
-// graph item view — the graph ITSELF fills the stage (his order 2026-07-23:
-// "if I select a graph, I want to see it"), lint line as a slim header
+// graph item view — the graph ITSELF fills the stage, lint line as a slim header
 export const GraphView = observer(({ app, id }: { app: HubSt; id: string }) => {
     const c = app.cols
     const i = c.find('graphs', id)

package/src/serve/hub-app/hub-app.tsx

@@ -1,8 +1,7 @@
 // THE page (Bun.serve HTML import — no vite, no build step). One surface
-// per repo (his rules 2026-07-23): media atelier + asks + creds + posts +
-// health + graphs as foldable sections, one severity filter persisted at
-// /?f=needs · /?f=red (legacy /?needs=1 reads as needs). Section title =
-// collection view (grid of cards), row = item view. mobx+react per
+// per repo: media atelier + asks + creds + posts + health + graphs as
+// foldable sections, one severity filter persisted at /?f=needs · /?f=red.
+// Section title = collection view (grid of cards), row = item view. mobx+react per
 // build/app-state-tree: HubSt is the single root (window.app), services
 // own state, components read and call.
 import { runInAction } from 'mobx'
@@ -66,8 +65,7 @@ const ColSections = observer(() => {
             {c.sidebarCols.map((col) => {
                 const items = c.visibleInstances(col)
                 // every section header ALWAYS renders, 0 items included — a
-                // quiet section must stay reachable (his order 2026-07-23:
-                // done asks, present secrets)
+                // quiet section must stay reachable (done asks, present secrets)
                 const open = c.isOpen(col)
                 const health = col.id === 'health'
                 return (
@@ -121,8 +119,8 @@ const Sidebar = observer(() => (
     </aside>
 ))
 
-// ── the icon rail: quick jump to a section header (his order 2026-07-23:
-// scroll + unfold, NEVER a navigation) — red dot = the section holds a red ──
+// ── the icon rail: quick jump to a section header (scroll + unfold,
+// NEVER a navigation) — red dot = the section holds a red ──
 const RAIL_ICON: Record<string, string> = { asks: '🙋', creds: '🔑', posts: '📣', health: '📊', graphs: '🕸' }
 const Rail = observer(() => {
     const c = app.cols

package/src/serve/hub-app/hub-st.ts

@@ -1,8 +1,8 @@
 // HubSt — the ONE root store (build/app-state-tree: one central tree,
 // instantiated once at boot, services with backrefs, exposed as
 // window.app). Owns cross-service state: selection, the severity filter
-// (an ADDRESS: /?f=needs · /?f=red; legacy /?needs=1 reads as needs),
-// hash deep-links (#<asset-id> · #cat-<Category>).
+// (an ADDRESS: /?f=needs · /?f=red), hash deep-links (#<asset-id> ·
+// #cat-<Category>).
 import { makeAutoObservable } from 'mobx'
 import { ColsSvc } from './cols-svc.ts'
 import { HealthSvc } from './health-svc.ts'
@@ -22,10 +22,8 @@ export type Jump = { id: string; label: string; section: string; run: () => void
 /** all · needs (yellow+red) · red — one severity ladder for every section */
 export type Filter = 'all' | 'needs' | 'red'
 const parseFilter = (search: string): Filter => {
-    const sp = new URLSearchParams(search)
-    const f = sp.get('f')
-    if (f === 'needs' || f === 'red') return f
-    return sp.get('needs') === '1' ? 'needs' : 'all' // legacy address keeps working
+    const f = new URLSearchParams(search).get('f')
+    return f === 'needs' || f === 'red' ? f : 'all'
 }
 
 export class HubSt {
@@ -64,7 +62,6 @@ export class HubSt {
     setFilter(v: Filter): void {
         this.filter = v
         const u = new URL(location.href)
-        u.searchParams.delete('needs') // legacy param never survives a click
         v === 'all' ? u.searchParams.delete('f') : u.searchParams.set('f', v)
         history.replaceState(null, '', u)
     }

package/src/serve/hub-app/media-view.tsx

@@ -197,8 +197,8 @@ export const CatGrid = observer(({ app }: { app: HubSt }) => {
                 {m.catRows.map((row) => {
                     const fl = row.rect?.flip === true
                     return (
-                        // the WHOLE card jumps into the asset (his order
-                        // 2026-07-23) — inner controls stopPropagation
+                        // the WHOLE card jumps into the asset —
+                        // inner controls stopPropagation
                         <div className="card" key={row.id} onClick={() => app.selectAsset(row.id)}>
                             {isAud(row.name)
                                 ? <div className="aud">🔊<audio controls src={rollUrl(row.id, row.name)} onClick={(e) => e.stopPropagation()} />{m.pending.includes(row.id) ? <div className="spin" /> : null}</div>

package/src/serve/run-serve.ts

@@ -34,7 +34,7 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     const agentGraph = existsSync(agentRoot)
         ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
         : null
-    // ONE page for every repo (his rule 2026-07-23): the studio ALWAYS
+    // ONE page for every repo: the studio ALWAYS
     // mounts — kit-less repos get an empty media section, never a second
     // page. A broken kit degrades to the same empty kit, loudly.
     let kit: ResolvedKit | null = null
@@ -86,8 +86,8 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
     }
 }
 
-// the hub must KNOW when it is outdated (field bug 2026-07-22: a morning
-// process served stale code all day, picks looked broken): version read at
+// the hub must KNOW when it is outdated — a stale morning
+// process serves broken-looking picks all day: version read at
 // boot vs on disk per attention load; mismatch = red line telling him to
 // restart the task
 const libVersion = (): string => {
@@ -96,8 +96,7 @@ const libVersion = (): string => {
 const BOOT_VERSION = libVersion()
 
 // the / dashboard's data now comes from the collection providers
-// (src/collections/providers.ts) — the old attentionCollector was DELETED
-// when they landed; never reintroduce a parallel projection.
+// (src/collections/providers.ts) — never a parallel projection.
 
 export async function runServe(root: string, io: ServeIo, o?: { port?: number }): Promise<number> {
     const c = await loadRepoConfig(root)

package/src/serve/serve-hub.ts

@@ -1,5 +1,4 @@
-// shipkit serve — the repo's ONE Bun.serve, serving the ONE page (his
-// rules 2026-07-23: one server per repo, one surface, mobx+react). `/` is
+// shipkit serve — the repo's ONE Bun.serve, serving the ONE page (one server per repo, one surface, mobx+react). `/` is
 // the hub app (Bun HTML import — media studio + asks + creds + posts +
 // health + graphs as sections); the studio route table mounts as the media
 // API under /media/*; graph canvases stay as drill-down pages. Route logic
@@ -32,7 +31,7 @@ export type HubDeps = {
      *  collection providers (run-serve builds it) */
     needs: () => Promise<NeedItem[]>
     /** BROWSE-ALL: the collections with every instance incl. healthy —
-     *  the page shows everything that exists (his trust rule) */
+     *  the page shows everything that exists, dimmed never hidden */
     collections: () => Collection[]
     /** asks dir (repo-root-relative) for the act-in-place ask verbs */
     asksDir: string

package/src/shipkit.ts

@@ -11,6 +11,14 @@ export { projectNeeds, redCount } from './collections/collection-types.ts'
 export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
 export { buildCollections } from './collections/providers.ts'
 export { socialPostsCollection, listPosts } from './collections/posts.ts'
+// release units — the ONE discovery every release surface reads (drift
+// probes, per-unit tests, per-unit typecheck, the stranded-tag probe)
+export { resolveUnits, releaseOrder, unitById, renderTag, tagGlobs, prepublishScripts, unitPrepublishScripts } from './release/units.ts'
+export type { ReleaseUnit, ReleaseUnitDecl, UnitResolution } from './release/units.ts'
+export { deriveRemote, dirtyPaths, remoteTags, strandedTags, tagExistsLocally } from './release/git-facts.ts'
+export { collectReports, renderReports, attentionLines } from './release/run-releases.ts'
+export { extractChangelogSection, promoteUnreleased, hasUnreleasedNotes, hasVersionSection } from './release/changelog.ts'
+export type { UnitReport } from './release/run-releases.ts'
 export { discoverChecks } from './core/discover-checks.ts'
 export type { DiscoveredCheck } from './core/discover-checks.ts'
 export { runTasks, selectTasks } from './core/task-runner.ts'
@@ -50,7 +58,7 @@ export { studioRoutes } from './assets/server/studio-server.ts'
 export type { StudioDeps, StudioRoutes } from './assets/server/studio-server.ts'
 export { StudioQueue } from './assets/server/studio-queue.ts'
 export type { Job, QueueState } from './assets/server/studio-queue.ts'
-export { cleanRect, liveRect, defaultLegs, migrateCircle } from './assets/panels/geometry-rects.ts'
+export { cleanRect, liveRect, defaultLegs } from './assets/panels/geometry-rects.ts'
 export type { GroundRect, LegRect } from './assets/panels/geometry-rects.ts'
 export { generate, submit, waitFor, applyInputs, expectNode, randomSeed, batchFolderName } from './assets/gen/comfy-gen.ts'
 export type { ComfyOpts } from './assets/gen/comfy-gen.ts'

package/src/tui/checks-panel.ts

@@ -1,6 +1,6 @@
 // built-in panel: contracts + every discovered *.check.ts through runCheck
 // (both TTL cache layers intact) — per-check results stream in via the
-// onResult tap. status:false: the tasks panel owns STATUS.md in a TUI run.
+// onResult tap. status:false: no TUI panel writes STATUS.md (tasks-panel.ts).
 import { discoverChecks } from '../core/discover-checks.ts'
 import { runCheck } from '../core/run-check.ts'
 import { formatLine } from '../core/wire.ts'

package/src/tui/run-tui.ts

@@ -1,7 +1,6 @@
 // The tui command body — a separate module so cli.ts NEVER loads
-// react/ink/mobx for non-tui commands (a fresh consumer running `shipkit ci`
-// must not touch the react dependency chain; field bug 2026-07-22: 0.3.0
-// crashed every command on repos without react-dom).
+// react/ink/mobx for non-tui commands: a fresh consumer running `shipkit ci`
+// must not touch the react dependency chain.
 import React from 'react'
 import { render } from 'ink'
 import { configure } from 'mobx'

package/src/tui/tasks-panel.ts

@@ -1,7 +1,10 @@
-// built-in panel: the ci gate (floor + contracts + repo tasks) through
-// runCi — results stream in via the onTaskFinish tap. STATUS.md refreshes
-// exactly like a terminal `shipkit ci`; the checks panel writes nothing
-// (one STATUS writer per TUI session).
+// built-in panel: the ci gate's TASKS (floor + contracts + repo tasks)
+// through runCi — results stream in via the onTaskFinish tap. The checks are
+// skipped here on purpose: the Checks panel runs the same suite and renders
+// it, and running it twice per refresh costs twice and proves the same thing.
+// no panel writes STATUS.md: a dashboard refresh runs the tasks alone, so
+// stamping a verdict from it would overwrite what a real gate proved with a
+// narrower claim, just by looking at the repo.
 import type { RepoConfig } from '../repo-config.ts'
 import { allTasks } from '../repo-config.ts'
 import { runCi } from '../core/run-ci.ts'
@@ -38,6 +41,9 @@ export function tasksPanel(root: string, config: RepoConfig): TuiPanelDef {
             const byKey = new Map(rows.map((r, i) => [r.key, i]))
             update()
             await runCi(root, {
+                config,
+                skipChecks: true,
+                status: false,
                 print: () => {}, // rows carry everything the wire lines would
                 onTaskFinish: (r) => {
                     const i = byKey.get(r.id)