rvlib-shipkit 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.14.0 — 2026-07-27
+
+New rule SK008 — the mandated reviewer agent type. A repo declares
+`reviewer: { name, brief, tools? }` in `repo.config.ts`; the rule then
+requires `.claude/agents/<name>.md` to exist, carry that type name, point at
+the brief file (which must itself exist), and keep `tools:` inside a
+read-only ALLOWLIST (default `Read, Grep, Glob, Bash`; widen it deliberately
+with `reviewer.tools`). A denylist of today's edit-tool names would wave
+through anything that edits by proxy, and an ABSENT `tools:` line is the
+worst case: the harness inherits every tool. Fixable and create-only —
+`shipkit check --fix SK008` writes a valid definition when the file is
+missing and never overwrites an existing one, which may be hand-tuned.
+Undeclared repos skip, and `shipkit init` scaffolds the key commented out.
+`reviewerAgentIssues` is exported so a repo's own linter can enforce the same
+invariants in its pre-commit hook without a second implementation. Note the
+written agent file embeds the brief PATH: a repo that may go public should
+gitignore it and let the fixer regenerate it per machine.
+
+Contract rule `png(path, w, h, { atLeast: true })` — the venue's numbers as a
+MINIMUM at a fixed aspect ratio (relative tolerance), for stores that DISPLAY
+a size but accept larger uploads. Without it an exact-size rule fails a better
+2x asset and blocks the release it was meant to gate. Applied to the itch
+cover and the identity/discord image rules; Steam capsules stay exact, Valve
+mandates those.
+
+Dep: `rvlib-ts-tools` ^0.2.0 → ^0.3.0, so the zero-config `imports:check`
+floor task inherits its honest reporting (a run that scanned zero files now
+fails instead of printing green).
+
+MIGRATION: the itch venue contract gains a required `.rv-itch/listing.md`
+(every store-form field answered, paste-ready). A repo already shipping on itch
+will see one new FAIL until the file exists; the docs that own the itch
+contract carry a fill-in template for it.
+
 ## 0.13.0 — 2026-07-26
 
 Stable rule ids. Every built-in invariant `shipkit check` enforces is now

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.13.0",
+    "version": "0.14.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",
@@ -33,7 +33,7 @@
         "mobx-react-lite": "^4.1.1",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
-        "rvlib-ts-tools": "^0.2.0",
+        "rvlib-ts-tools": "^0.3.0",
         "sanitize-html": "^2.17.6",
         "sharp": "^0.35.3"
     }

package/src/contracts/contract-types.ts

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

package/src/contracts/contracts-engine.ts

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

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

@@ -10,6 +10,6 @@ export default defineContract({
     detect: [dirExists('.rv-discord')],
     artifacts: [
         md('.rv-discord/server.md', { mustContain: ['invite'] }),
-        png('.rv-discord/icon.png', 512, 512),
+        png('.rv-discord/icon.png', 512, 512, { atLeast: true }),
     ],
 })

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

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

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

@@ -1,5 +1,7 @@
 // normative WHAT for .rv-itch/ — the WHY + workflow live in the sibling page.
-import { defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { custom, defineContract, dirExists, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
 
 export default defineContract({
     venue: 'itch',
@@ -10,7 +12,22 @@ export default defineContract({
     artifacts: [
         // one AI-disclosure wording everywhere — page.md is its canonical home
         md('.rv-itch/page.md', { mustContain: ['## AI disclosure'] }),
-        png('.rv-itch/cover.png', 630, 500),
+        // every field of itch's create-project form, answered and ready to
+        // paste — the listing is a browser-only act, so the artifact IS the
+        // handoff (references/listing.template.md is the fill-in copy)
+        md('.rv-itch/listing.md', { mustContain: ['## Title', '## Short description or tagline', '## Classification', '## Genre', '## Tags', '## Visibility'] }),
+        // headings alone would pass the TEMPLATE copied in verbatim, and this
+        // file exists to be pasted with no decision left in it (field
+        // 2026-07-27: a reviewer proved `cp template listing.md` went green)
+        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)
+        png('.rv-itch/cover.png', 630, 500, { atLeast: true }),
         glob('.rv-itch/screenshots/*.png', { min: 3 }),
     ],
 })

package/src/init-repo.ts

@@ -19,6 +19,9 @@ export default defineRepo({
     venues: [], // e.g. ['itch', 'steam'] — selects which .rv-<venue>/ contracts are REQUIRED
     social: [], // e.g. ['x', 'discord'] — .rv-social/<channel>/ post folders (+ .rv-discord/)
     tasks: [],  // repo commit-gate tasks; deps double as race guards
+    // the mandated reviewer agent type (rule SK008) — uncomment with YOUR
+    // standing brief, then \`shipkit check --fix SK008\` writes the agent file:
+    // reviewer: { name: 'my-reviewer', brief: '~/path/to/reviewer-brief.md' },
     // health checks: no config — drop a <name>.check.ts file anywhere,
     // \`shipkit check\` auto-discovers and runs it (wire output, exit code)
 })

package/src/repo-config.ts

@@ -62,6 +62,13 @@ export type RepoConfig = {
     /** declared github visibility INTENT (absent = 'private') — rule SK007
      *  fails loud when `gh repo view` disagrees in either direction */
     visibility?: 'private' | 'public'
+    /** the reviewer agent type this repo mandates: `.claude/agents/<name>.md`,
+     *  whose system prompt points at `brief` (an md file holding the standing
+     *  review framing — one home, shared across repos). `tools` overrides the
+     *  read-only allowlist SK008 enforces (default: Read, Grep, Glob, Bash).
+     *  Rule SK008 lints it, `check --fix SK008` writes it. Absent = no
+     *  mandated reviewer. */
+    reviewer?: { name: string; brief: string; tools?: string[] }
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
     /** the `shipkit serve` hub: port + optional graph hooks */
@@ -69,13 +76,16 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'visibility', 'reviewer', 'tui', 'serve', 'logDir'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
     for (const v of c.venues ?? []) if (!/^[a-z0-9-]+$/.test(v)) throw new Error(`defineRepo: venue '${v}' must be kebab-case`)
     if (c.visibility != null && c.visibility !== 'private' && c.visibility !== 'public')
         throw new Error(`defineRepo: visibility '${String(c.visibility)}' — 'private' or 'public' only`)
+    // a half-declared reviewer would lint a path like `.claude/agents/.md`
+    if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
+        throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))

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

@@ -0,0 +1,98 @@
+// 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',
+    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/rule-registry.ts

@@ -10,6 +10,7 @@ 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'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -19,6 +20,7 @@ export const RULES: readonly Rule[] = [
     rvlibVersions,
     npmPublishSafety,
     githubVisibility,
+    reviewerAgent,
 ]
 
 const seen = new Set<string>()