rvlib-shipkit 1.1.1 → 1.3.0

package/src/checks/SK009-commit-ai-tells.check.ts

@@ -8,11 +8,16 @@
 // 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 { createHash } from 'crypto'
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
 import { nestedIn } from '../core/nesting.ts'
-import { check } from '../check.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
+import { check, type CheckEnv } from '../check.ts'
+import { declaredVisibility } from '../core/repo-facts.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
 // empty — the harness then never writes the trailer or the PR footer
@@ -25,20 +30,39 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
+/** what the answer depends on: the declared visibility, and for a public
+ *  repo the commit HEAD names, every ref name and the silencer. So a commit,
+ *  a fetch or a new tag asks again, and nothing else does */
+export function historyKey(env: CheckEnv): string {
+    const declared = declaredVisibility(env.config)
+    const nested = nestedIn(env.root)
+    if (nested != null) return `nested in ${nested}`
+    if (declared !== 'public') return `declared ${declared}`
+    const git = (args: string[]): string => {
+        const p = Bun.spawnSync([gitBin(), ...args], { cwd: env.root, stdout: 'pipe', stderr: 'pipe' })
+        return p.exitCode === 0 ? p.stdout.toString() : `exit ${p.exitCode}`
+    }
+    const refs = git(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/tags', 'refs/heads', 'refs/remotes'])
+    const head = git(['rev-parse', 'HEAD'])
+    const digest = createHash('sha256').update(head).update('\0').update(refs).digest('hex').slice(0, 16)
+    return `public|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
+}
+
 export const commitAiTells = check({
     id: 'SK009',
     blocking: true,
     title: 'commit ai tells',
     description: 'the history of a public repo carries no AI attribution and no dash punctuation',
     owner: 'identity/how-we-commit.md',
-    // it scans the full `git log` and every ref name. History and refs are not
-    // work-tree content, so nothing a scan can produce describes this answer
-    never: 'reads the full commit history and every ref name, neither of which is work-tree content',
+    // it scans the full `git log` and every ref name, which no tree id
+    // describes, so the refs themselves are the key
+    inputs: [CONFIG_FILE],
+    cacheKey: historyKey,
     run: async (c) => {
         const nested = nestedIn(c.root)
         if (nested != null)
             return void c.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
-        const declared = c.config.visibility ?? 'private'
+        const declared = declaredVisibility(c.config)
         if (declared !== 'public')
             return c.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

package/src/checks/SK013-one-way-in-policy.check.ts

@@ -15,6 +15,7 @@
 import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type CheckCtx, type FixResult } from '../check.ts'
 
@@ -95,8 +96,8 @@ async function guardScriptMissing(d: Disk, command: string): Promise<string | nu
     return null // a form this rule cannot resolve is not a form it may condemn
 }
 
-/** the guard the fixer writes: the cli path the scripts run when a guard sits
- *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
+/** the guard the fixer writes: the shipkit cli path the scripts run when a
+ *  guard sits beside it, else the
  *  repo's own dependency, else the copy of shipkit doing the fixing, which is
  *  the one the launcher falls back to in a repo that has none */
 export async function guardCommandFor(d: Disk): Promise<string> {
@@ -109,6 +110,11 @@ export async function guardCommandFor(d: Disk): Promise<string> {
     return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
+/** a package published to npm is worked on by strangers: this file binds
+ *  their agents, and a deny list with a hook would tie them to a toolkit they
+ *  never installed */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${SETTINGS_PATH} belongs to every contributor, so it is never written`
+
 export const oneWayInPolicy = check({
     id: 'SK013',
     blocking: true,
@@ -119,6 +125,7 @@ export const oneWayInPolicy = check({
     // the declared guard script resolves. A guard at an absolute path lives
     // outside the repo, so an answer that probed one is never stored
     run: async (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return c.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
@@ -165,6 +172,7 @@ export const oneWayInPolicy = check({
     // a repo's own allow list and its own hooks, and clobbering those to fix a
     // deny list would cost more than the finding it repairs
     fix: async (c): Promise<FixResult> => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }

package/src/checks/SK015-nested-repo.check.ts

@@ -3,6 +3,7 @@
 // sites that write history refuse on the disk fact either way (core/nesting.ts),
 // so this rule is about the declaration telling the truth to the next reader.
 import { nestedIn } from '../core/nesting.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
 import { check } from '../check.ts'
 
 export const nestedRepo = check({
@@ -11,7 +12,10 @@ export const nestedRepo = check({
     title: 'nested repo',
     description: 'a config inside a larger work tree declares `nested: true`, and only there',
     owner: 'build/shipkit/config-keys.md',
-    never: 'reads where the git work tree root sits, which no content inside the repo describes',
+    // the declaration, and where the git work tree root sits, which no tree
+    // id describes, so its path is the rest of the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `nested=${env.config.nested === true}|top=${nestedIn(env.root) ?? 'root'}`,
     run: (c) => {
         const top = nestedIn(c.root)
         const declared = c.config.nested === true

package/src/checks/SK017-vscode-hub-task.check.ts

@@ -11,6 +11,7 @@ import { basename } from 'path'
 import { check } from '../check.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { whenOfTask } from '../core/when.ts'
 import { hubProblemMatcher } from '../problems/problem-line.ts'
 import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
@@ -165,6 +166,10 @@ function ownTasks(c: CheckCtx): { text: string } | 'none' | 'linked' {
     return text == null ? 'none' : { text }
 }
 
+/** a package published to npm is worked on by strangers, whose editor
+ *  runs these tasks */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${TASKS} belongs to every contributor, so it is never rewritten`
+
 export const vscodeHubTask = check({
     id: 'SK017',
     // a stale editor file is behind, not broken: it warns, and the fix pass
@@ -174,6 +179,7 @@ export const vscodeHubTask = check({
     description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
     owner: 'build/vscode-tasks.md',
     run: (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const own = ownTasks(c)
         if (own === 'none') return c.ok(`no ${TASKS}, so there is no hub task to wire`)
         if (own === 'linked') return c.ok(`.vscode/ is a link to a shared dir, left alone`)
@@ -185,6 +191,7 @@ export const vscodeHubTask = check({
         for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
     },
     fix: (c) => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const own = ownTasks(c)
         if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }
         const r = repairTasks(own.text, { typecheckOn: typecheckOn(c) })

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -0,0 +1,47 @@
+// SK022 machine runs the pin (build/shipkit.md): on a machine with a house
+// every shipkit runs the house copy, whatever a repo installed, so a repo's
+// rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
+// newer than the one this process runs: a rule or an api that pin relies on
+// is absent here until the house copy catches up.
+import { join } from 'path'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { check } from '../check.ts'
+
+type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+const NAME = 'rvlib-shipkit'
+
+/** the lowest version a semver range admits (`^0.30.1` → 0.30.1), null when
+ *  it names no version (link:, workspace:*, a tag) */
+export function pinFloor(spec: string): string | null {
+    const m = /^\s*(?:\^|~|>=|=|v)?\s*(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(spec)
+    return m?.[1] ?? null
+}
+
+export const machineRunsThePin = check({
+    id: 'SK022',
+    blocking: false,
+    title: 'machine runs the pin',
+    description: 'the shipkit this machine runs is at least the version this repo pins',
+    owner: 'build/shipkit.md',
+    // the pin, the install (gitignored) and the version this machine runs,
+    // which is no file of the repo
+    inputs: ['package.json'],
+    cacheKey: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}`,
+    run: (c) => {
+        const pkg = c.json<Pkg>('package.json')
+        const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]
+        if (spec == null) return c.ok(`no ${NAME} pin, this machine runs ${LIB_VERSION}`)
+        const wants: Array<{ v: string; from: string }> = []
+        const floor = pinFloor(spec)
+        if (floor != null) wants.push({ v: floor, from: `package.json pins ${spec}` })
+        const installed = c.json<Pkg>(`node_modules/${NAME}/package.json`)?.version
+        if (installed != null) wants.push({ v: installed, from: `node_modules has ${installed}` })
+        const ahead = wants.filter((w) => Bun.semver.order(w.v, LIB_VERSION) > 0)
+        if (ahead.length === 0) return c.ok(`${NAME} ${spec}: this machine runs ${LIB_VERSION}, at least that`)
+        c.warn(`${NAME}: ${ahead.map((w) => w.from).join(', ')}, newer than the ${LIB_VERSION} this machine runs. Update the house copy (git pull in the repo that hosts the house wiki), or run this repo's own install: bun node_modules/${NAME}/src/cli.ts`)
+    },
+})
+
+export default machineRunsThePin

package/src/checks/SK024-identity-colors.check.ts

@@ -0,0 +1,54 @@
+// SK024 identity colors (core/identity.ts owns the derivation): repo.config.ts
+// declares `identity: { colorLight, colorDark }`, two #rrggbb hex, so every
+// surface that shows the repo (the home page header, its rail tile) draws it
+// in its own colour. The fix derives them from the repo icon, or from a hue
+// hashed from the name, and writes that one key, every other byte kept.
+import { join } from 'path'
+import { check } from '../check.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { configName, CONFIG_FILE, deriveIdentity, identityRefusal, INSTALLED_CONFIG_SRC } from '../core/identity.ts'
+import { declaresIdentity, identityOfText, identityProblem, setIdentityText } from '../core/identity-color.ts'
+
+
+const FIX = 'shipkit check --fix SK024 derives them from the repo icon, or from its name'
+
+export const identityColors = check({
+    id: 'SK024',
+    blocking: false,
+    title: 'identity colors',
+    description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
+    owner: 'build/shipkit/built-in-checks.md',
+    // the config, and the installed lib that says whether it knows the key
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}`,
+    run: (c) => {
+        const text = c.read(CONFIG_FILE)
+        if (text == null) return c.note(`no ${CONFIG_FILE}`)
+        const declared = declaresIdentity(text)
+        const id = identityOfText(text)
+        const why = id == null ? (declared ? 'identity is declared but its two colours cannot be read as #rrggbb hex' : 'no identity colours') : identityProblem(id)
+        const refused = why == null ? null : identityRefusal(c.read(INSTALLED_CONFIG_SRC))
+        if (refused != null) return c.note(`${CONFIG_FILE}: ${why}, and ${refused}`)
+        if (why != null) return c.warn(`${CONFIG_FILE}: ${why}`, FIX)
+        c.ok(`identity ${id!.colorLight} on light, ${id!.colorDark} on dark`)
+    },
+    fix: async (c) => {
+        const text = c.read(CONFIG_FILE)
+        if (text == null) return { changed: false, summary: `no ${CONFIG_FILE}` }
+        const have = identityOfText(text)
+        if (have != null && identityProblem(have) == null) return { changed: false, summary: 'identity colours already declared' }
+        const refused = identityRefusal(c.read(INSTALLED_CONFIG_SRC))
+        if (refused != null) return { changed: false, summary: refused }
+        const { id, from } = await deriveIdentity(c.root, configName(text, c.root), (rel) => c.bytes(rel))
+        let next: string
+        try {
+            next = setIdentityText(text, id)
+        } catch (e) {
+            return { changed: false, summary: (e as Error).message }
+        }
+        c.write(CONFIG_FILE, next)
+        return { changed: true, summary: `identity ${id.colorLight} / ${id.colorDark}, from ${from}` }
+    },
+})
+
+export default identityColors

package/src/checks/SK025-release-drift.check.ts

@@ -0,0 +1,58 @@
+// SK025 release drift (build/shipkit/built-in-checks.md): every unit this repo
+// releases matches what npm serves and what its push remote holds, the same
+// survey `shipkit releases` prints. It replaces a drift copy per page. A repo
+// that releases nothing (a private root with no release config and no units)
+// skips it. A world probe: the registry and the remote move on a publish this
+// tree cannot see, so a clean answer keeps for a day, keyed on every unit's
+// version so a local bump asks again at once.
+import { check, type CheckCtx } from '../check.ts'
+import { parseWireOutput } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { attentionLines, collectReports, type UnitReport } from '../release/run-releases.ts'
+import { resolveUnits, type ReleaseUnit } from '../release/units.ts'
+
+/** the units this repo releases: every declared one, and the root only when
+ *  it publishes to npm or the repo declares a release config */
+export function releasedUnits(root: string, config: RepoConfig): ReleaseUnit[] {
+    return resolveUnits(root, config).units.filter((u) => u.id !== 'root' || u.targets.npm || config.release != null)
+}
+
+/** the survey as check lines: one ok per unit in step, else its attention lines */
+export function reportDrift(c: CheckCtx, reports: UnitReport[]): void {
+    for (const r of reports) {
+        const lines = attentionLines(r)
+        if (lines.length === 0) {
+            // "in sync with npm" only for a unit that HAS an npm target and whose
+            // registry read succeeded (attentionLines warns when it did not)
+            c.ok(r.npmTarget ? `${r.name}@${r.version} in sync with npm` : `${r.name}@${r.version}, no npm target, tag state only`)
+            continue
+        }
+        for (const l of parseWireOutput(lines.join('\n'))) {
+            if (l.kind === 'warn' || l.kind === 'fail') c.warn(l.text)
+            else if (l.kind === 'ok') c.ok(l.text)
+            else c.note(l.text)
+        }
+    }
+}
+
+export const releaseDrift = check({
+    id: 'SK025',
+    blocking: false,
+    title: 'release drift',
+    description: 'every unit this repo releases matches npm and its push remote',
+    owner: 'build/shipkit/built-in-checks.md',
+    when: 'health',
+    ttl: '20h',
+    every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'),
+    planOff: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
+    cacheKey: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(','),
+    run: async (c) => {
+        const ids = new Set(releasedUnits(c.root, c.config).map((u) => u.id))
+        if (ids.size === 0) return void c.lines.push({ kind: 'skip', text: 'this repo releases nothing: no npm root, no release config, no units' })
+        const { reports, errors } = await collectReports(c.root, c.config)
+        for (const e of errors) c.warn(e)
+        reportDrift(c, reports.filter((r) => ids.has(r.id)))
+    },
+})
+
+export default releaseDrift

package/src/checks/SK026-asks-autoclose.check.ts

@@ -0,0 +1,44 @@
+// SK026 asks auto close (build/shipkit/built-in-checks.md): probe every open
+// ask's own `check:` and archive the ones that pass, so an act done in the
+// world leaves the queue without anyone editing a file. An open queue is no
+// warning: the hub and `shipkit needs` show it. A repo with no queue skips.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { checkAsks, listAsks } from '../asks/asks-queue.ts'
+import { check } from '../check.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export const asksAutoclose = check({
+    id: 'SK026',
+    blocking: false,
+    title: 'asks auto close',
+    description: 'no open ask whose own probe passes stays in the queue',
+    owner: 'build/shipkit/built-in-checks.md',
+    when: 'health',
+    never: "runs each open ask's own probe, a shell command that reads the world",
+    every: ['20h', '28h'],
+    // it only probes an ask that carries one, and archives one marked done
+    planOff: (env) => {
+        const dir = join(env.root, env.config.asks?.dir ?? LAYOUT.asks)
+        if (!existsSync(dir)) return 'no asks queue'
+        return listAsks(dir).some((a) => a.check != null || a.status === 'done') ? null : 'no open ask carries a probe'
+    },
+    run: async (c) => {
+        const dir = join(c.root, c.config.asks?.dir ?? LAYOUT.asks)
+        if (!existsSync(dir)) return void c.lines.push({ kind: 'skip', text: 'no asks queue in this repo' })
+        // archiving RENAMES files, and the release path runs the checks between
+        // its clean tree guard and `npm publish`: frozen means report only
+        if (c.frozen) return void c.lines.push({ kind: 'skip', text: 'asks not probed: a frozen run archives nothing' })
+        const events: string[] = []
+        await checkAsks(c.root, dir, (l) => events.push(l))
+        // `closed + archived <file>` / `archived <file>` are the queue's frozen stdout contract
+        for (const l of events) {
+            if (l.startsWith('closed') || l.startsWith('archived')) c.ok(`ask ${l}`)
+            // the queue could not run (another agent holds the write lease)
+            else if (l.startsWith('WARN')) c.warn(l.replace(/^WARN\s*/, ''))
+        }
+        if (!c.lines.some((l) => l.kind === 'ok')) c.ok('no open ask has a probe that passes')
+    },
+})
+
+export default asksAutoclose

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -0,0 +1,28 @@
+// SK027 agent wiki links (build/shipkit/built-in-checks.md): a repo's agent/
+// IS an md wiki (entry index.md, the CLAUDE.md include), so an orphan page or
+// a dangling ref there fails. A cross wiki pointer (into a house wiki) is
+// backticked, never a bare → or @, which reads as an agent local link and
+// dangles. A repo without agent/index.md skips.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { check } from '../check.ts'
+import { lintMd } from '../wiki/lint-md.ts'
+
+export const agentWikiLinks = check({
+    id: 'SK027',
+    blocking: true,
+    title: 'agent wiki links',
+    description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
+    owner: 'meta/agent-folder.md',
+    // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
+    inputs: ['agent'],
+    run: (c) => {
+        if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
+        const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md' })
+        for (const f of lint.orphans) c.fail(`agent/${f}: orphan, unreachable from agent/index.md: link it from a page or delete it`)
+        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found (backtick a cross wiki ref; fix or delete the pointer)`)
+        if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
+    },
+})
+
+export default agentWikiLinks

package/src/checks/SK028-readme.check.ts

@@ -0,0 +1,79 @@
+// SK028 readme (build/shipkit/built-in-checks.md): the README.md a repo's hub
+// page shows exists and carries what makes the repo recognizable at a glance.
+// A list of named requirements, each reporting its own line, so a new
+// mandatory item is one more entry. Read through `c` only, so the answer is
+// keyed on README.md and the images it points to, never on a clock.
+import { posix } from 'path'
+import { check } from '../check.ts'
+import type { CheckCtx } from '../core/check-ctx.ts'
+
+const README = 'README.md'
+
+/** every image source the README shows: markdown `![..](src)` and html
+ *  `<img src>`, code fences and inline code left out, since a sample there
+ *  shows nothing */
+export const imageRefs = (md: string): string[] => {
+    const prose = md.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, '').replace(/`[^`\n]*`/g, '')
+    const refs: { at: number; src: string }[] = []
+    for (const m of prose.matchAll(/!\[[^\]]*\]\(\s*<?([^\s)>]+)>?(?:\s+["'(][^)]*)?\)/g)) refs.push({ at: m.index, src: m[1]! })
+    for (const m of prose.matchAll(/<img\b[^>]*?\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) refs.push({ at: m.index, src: (m[1] ?? m[2] ?? m[3])! })
+    return refs.sort((a, b) => a.at - b.at).map((r) => r.src)
+}
+
+/** a status badge (ci, version, license) shows the repo's state, never what it looks like */
+const isBadge = (src: string): boolean => /(^|[/.])(shields\.io|badgen\.net)\//i.test(src) || /badge[^/]*\.svg([?#]|$)/i.test(src)
+
+/** where an image source lands: an https url, a repo file, or nowhere with why */
+const resolveImage = (c: CheckCtx, src: string): { ok: string } | { bad: string } => {
+    if (isBadge(src)) return { bad: `${src.slice(0, 60)} is a badge` }
+    if (/^https:\/\//i.test(src)) return { ok: src }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith('//')) return { bad: `${src.slice(0, 60)} is neither an https url nor a repo file` }
+    let rel: string
+    try {
+        rel = posix.normalize(decodeURI(src.replace(/[?#].*$/, '')).replace(/^\/+/, ''))
+    } catch {
+        return { bad: `${src} is not a readable path` }
+    }
+    if (rel === '.' || rel.startsWith('../')) return { bad: `${src} points out of the repo` }
+    return c.exists(rel, 'file') ? { ok: rel } : { bad: `${rel} is missing` }
+}
+
+type Finding = { ok: string } | { warn: string; fix: string }
+type Requirement = { name: string; test: (c: CheckCtx, md: string) => Finding }
+
+/** what every README carries, in order. Add an entry to make one more item mandatory */
+const REQUIREMENTS: Requirement[] = [
+    {
+        name: 'screenshot',
+        test: (c, md) => {
+            const found = imageRefs(md).map((src) => resolveImage(c, src))
+            const shown = found.find((f): f is { ok: string } => 'ok' in f)
+            if (shown != null) return { ok: `${README} shows a screenshot: ${shown.ok}` }
+            const why = found.map((f) => (f as { bad: string }).bad)
+            return {
+                warn: `${README}: screenshot: ${why.length === 0 ? 'no image at all' : `no image resolves (${why.join(', ')})`}`,
+                fix: 'add a screenshot to README.md: ![what it looks like](docs/screenshot.png), a file in the repo, or an https url',
+            }
+        },
+    },
+]
+
+export const readme = check({
+    id: 'SK028',
+    blocking: false,
+    title: 'readme',
+    description: 'README.md exists and shows at least one screenshot',
+    owner: 'build/shipkit/built-in-checks.md',
+    run: (c) => {
+        const md = c.read(README)
+        if (md == null) return c.warn(`${README}: exists: no ${README} at the repo root`, 'write README.md: what the repo is, and a screenshot of it')
+        c.ok(`${README} exists`)
+        for (const r of REQUIREMENTS) {
+            const f = r.test(c, md)
+            if ('ok' in f) c.ok(f.ok)
+            else c.warn(f.warn, f.fix)
+        }
+    },
+})
+
+export default readme

package/src/cli/cmd_Assets.ts

@@ -99,7 +99,7 @@ export class AssetsCheckCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Assets',
-        description: 'kit loads, kinds valid, cflow workflows load, drafts present, backend reachable, identity outputs present',
+        description: 'kit loads, kinds valid, cflow workflows load, drafts present, identity outputs present',
         examples: [['health-check the asset pipeline', 'shipkit assets check']],
     })
 

package/src/cli/cmd_Check.ts

@@ -2,6 +2,9 @@
 // autofixes then re-lints. Thin clipanion surface; logic in
 // core/run-check.ts and core/run-fix.ts. ci NEVER fixes.
 import { Command, Option } from 'clipanion'
+import { runViaHub } from '../home/via-hub.ts'
+import { readJobOpts, recordExit } from '../core/jobs.ts'
+import { runJob } from '../core/job-run.ts'
 import { runCheck } from '../core/run-check.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 import { runFix } from '../core/run-fix.ts'
@@ -27,8 +30,25 @@ export class CheckCommand extends Command {
     fix = Option.Boolean('--fix', false, { description: 'apply check autofixes (every fixable check, or only the listed ids), then re-run them' })
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for the self-maintaining checks (SK005 never touches package.json)' })
     fixIds = Option.Rest()
+    job = Option.String('--job', { hidden: true })
 
     async execute(): Promise<number> {
+        // a gate job the daemon started: its options are in the job folder
+        if (this.job != null) {
+            const root = process.cwd()
+            const job = readJobOpts(root, this.job)
+            let code = 1
+            if (job == null) this.context.stderr.write(`FAIL: gate job ${this.job} has no options in its folder\n`)
+            else {
+                try {
+                    code = await runJob(root, this.job, 'check', job, (l) => { this.context.stdout.write(`${l}\n`) })
+                } catch (e) {
+                    this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+                }
+            }
+            recordExit(root, this.job, code)
+            return code
+        }
         // a stale toolkit updates itself and restarts this exact invocation
         // (loop-guarded, skipped under CI/frozen/source consumption)
         await maybeSelfUpdateAndRestart(process.cwd(), { fresh: this.fresh })
@@ -43,7 +63,12 @@ export class CheckCommand extends Command {
             }
             if (this.fix)
                 return await runFix(process.cwd(), { ids: this.fixIds, print: (l) => this.context.stdout.write(`${l}\n`) })
-            return await runCheck(process.cwd(), { json: this.json, fresh: this.fresh, frozen: this.frozen, print: (l) => this.context.stdout.write(`${l}\n`) })
+            const opts = { json: this.json, fresh: this.fresh, frozen: this.frozen }
+            const print = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+            // on a machine with the home, the repo's hub runs it (home/via-hub.ts)
+            const via = await runViaHub(process.cwd(), 'check', opts, { print, printErr: (l) => this.context.stderr.write(`${l}\n`) })
+            if (via != null) return via
+            return await runCheck(process.cwd(), { ...opts, print })
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
             return 1

package/src/cli/cmd_Ci.ts

@@ -2,8 +2,10 @@
 // core/run-ci.ts.
 import { Command, Option } from 'clipanion'
 import { join } from 'path'
-import { recordExit, startDetached } from '../core/jobs.ts'
+import { readJobOpts, recordExit, startDetached } from '../core/jobs.ts'
+import { runJob } from '../core/job-run.ts'
 import { runCi } from '../core/run-ci.ts'
+import { runViaHub } from '../home/via-hub.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
 
 export class CiCommand extends Command {
@@ -22,6 +24,7 @@ export class CiCommand extends Command {
             ['run everything, take nothing from the cache', 'shipkit ci --fresh'],
             ['include an opt in check', 'shipkit ci --with up:itch'],
             ['in the background, read it back with shipkit status', 'shipkit ci --detach'],
+            ['every line, the ones nobody acts on included', 'shipkit ci --verbose'],
         ],
     })
 
@@ -36,6 +39,8 @@ export class CiCommand extends Command {
     fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
+    verbose = Option.Boolean('--verbose', false, { description: 'print every line, the ones nobody acts on included: a clean fix pass, the machine pool, the test tier, the cache declarations, the checks not in this run, the cache counts' })
+
     detach = Option.Boolean('--detach', false, { description: 'start this gate in the background and return at once with a run id. `shipkit status <id>` prints it. The gate is an ordinary one: same cache, same run record' })
     job = Option.String('--job', { hidden: true })
 
@@ -46,7 +51,13 @@ export class CiCommand extends Command {
             for (const l of d.lines) this.context.stdout.write(`${l}\n`)
             return 0
         }
-        const code = await this.gate(root)
+        const job = this.job != null ? readJobOpts(root, this.job) : null
+        let code = 1
+        try {
+            code = this.job != null && job != null ? await runJob(root, this.job, 'ci', job, (l) => { this.context.stdout.write(`${l}\n`) }) : await this.gate(root)
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+        }
         if (this.job != null) recordExit(root, this.job, code)
         return code
     }
@@ -64,6 +75,7 @@ export class CiCommand extends Command {
             ...this.only.flatMap((v) => ['--only', v]),
             ...(this.fresh ? ['--fresh'] : []),
             ...(this.full ? ['--full'] : []),
+            ...(this.verbose ? ['--verbose'] : []),
         ]
     }
 
@@ -72,7 +84,7 @@ export class CiCommand extends Command {
         // (loop-guarded, skipped under CI/frozen/source consumption)
         await maybeSelfUpdateAndRestart(root, { fresh: this.fresh })
         try {
-            return await runCi(root, {
+            const opts = {
                 bail: this.bail,
                 json: this.json,
                 fix: this.fix,
@@ -84,8 +96,14 @@ export class CiCommand extends Command {
                 onlyIds: this.only,
                 fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
-                print: (l) => this.context.stdout.write(`${l}\n`),
-            })
+                ...(this.verbose ? { verbose: true } : {}),
+            }
+            const print = (l: string): void => { this.context.stdout.write(`${l}\n`) }
+            // on a machine with the home, the repo's hub runs it (home/via-hub.ts)
+            // a job is already the run, wherever it was started from
+            const via = this.job != null ? null : await runViaHub(root, 'ci', opts, { print, printErr: (l) => this.context.stderr.write(`${l}\n`) })
+            if (via != null) return via
+            return await runCi(root, { ...opts, print })
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
             return 1