rvlib-shipkit 1.3.0 → 1.5.0

package/src/cli/cmd_When.ts

@@ -0,0 +1,71 @@
+// shipkit when — what runs when: the legend (every context, every value) and
+// one row per check with its declared value on each axis. The same data the
+// hub's when page draws (core/runs-matrix.ts), so the terminal and the page
+// cannot disagree.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { gateInventory } from '../ledger/gate-checks.ts'
+import { legendMarkdown, MATRIX_AXES, matrixLines, RUNS_LEGEND, runsCellsOf, type MatrixAxis } from '../core/runs-matrix.ts'
+import { spliceMarkedBlock } from '../core/doc-block.ts'
+
+export const LEGEND_BEGIN = '<!-- shipkit:when-legend -->'
+export const LEGEND_END = '<!-- /shipkit:when-legend -->'
+
+export class WhenCommand extends Command {
+    static override paths = [['when']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'what runs when: every check on every context, with the legend',
+        details: 'Every check on every context (commit, ci, full, release, health, save, clock, fix) and how its answer is cached, after the legend of every axis and value. Reports, never gates.',
+        examples: [
+            ['the legend, then every check', 'sk when'],
+            ['only what the quick gate runs', 'sk when --only onCi'],
+            ['the matrix without the legend', 'sk when --no-legend'],
+            ['machine-readable', 'sk when --json'],
+            ['write the legend into a docs page between its markers', 'sk when --out wiki/build/shipkit/runs.md'],
+            ['fail if that page is stale (lint mode)', 'sk when --out wiki/build/shipkit/runs.md --check'],
+        ],
+    })
+
+    only = Option.String('--only', { required: false, description: `only the rows one context runs: ${MATRIX_AXES.join(', ')}` })
+    legend = Option.Boolean('--legend', true, { description: 'print the legend first. Default on, --no-legend drops it' })
+    out = Option.String('--out', { required: false, description: 'host file carrying the shipkit:when-legend markers. The legend between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the legend is stale, write nothing' })
+    json = Option.Boolean('--json', false, { description: 'machine-readable { legend, rows: [{ id, title, from, blocking, build, runs: { cells, cache, off, derivedWhy } }] }' })
+
+    async execute(): Promise<number> {
+        if (this.out != null) return await this.writeLegend(this.out)
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        if (this.only != null && !(MATRIX_AXES as readonly string[]).includes(this.only)) {
+            this.context.stdout.write(`FAIL: --only takes one of ${MATRIX_AXES.join(', ')}, got '${this.only}'\n`)
+            return 1
+        }
+        const rows = (await gateInventory(root, c)).map((r) => ({ id: r.decl.id, title: r.title, from: r.from, blocking: r.blocking, build: r.build, runs: runsCellsOf(r) }))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify({ legend: RUNS_LEGEND, rows })}\n`)
+            return 0
+        }
+        for (const l of matrixLines(rows, { legend: this.legend, only: this.only as MatrixAxis | undefined })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+
+    /** the legend only depends on the binary, never on the repo */
+    private async writeLegend(path: string): Promise<number> {
+        const { existsSync, readFileSync, writeFileSync } = await import('fs')
+        if (!existsSync(path)) { this.context.stdout.write(`FAIL: ${path} does not exist\n`); return 1 }
+        const host = readFileSync(path, 'utf8')
+        const next = spliceMarkedBlock(host, legendMarkdown(), LEGEND_BEGIN, LEGEND_END)
+        if (next == null) { this.context.stdout.write(`FAIL: ${path} has no ${LEGEND_BEGIN} / ${LEGEND_END} markers\n`); return 1 }
+        if (next === host) { this.context.stdout.write(`ok: ${path} legend current\n`); return 0 }
+        if (this.check) {
+            this.context.stdout.write(`FAIL: ${path} legend is STALE, the binary's axes or values differ from the page\n`)
+            this.context.stdout.write(`      fix: shipkit when --out ${path}\n`)
+            return 1
+        }
+        writeFileSync(path, next)
+        this.context.stdout.write(`ok: ${path} legend rewritten\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Wiki.ts

@@ -10,8 +10,8 @@ export class WikiServeCommand extends Command {
         category: 'Wiki',
         description: 'live md link-graph server — reload = rescan',
         examples: [
-            ['serve the cwd wiki', 'shipkit wiki serve'],
-            ['serve a subtree on a port', 'shipkit wiki serve --root agent --index process.md --port 6162'],
+            ['serve the cwd wiki', 'sk wiki serve'],
+            ['serve a subtree on a port', 'sk wiki serve --root agent --index process.md --port 6162'],
         ],
     })
 
@@ -38,8 +38,8 @@ export class WikiLintCommand extends Command {
         category: 'Wiki',
         description: 'fail on orphan pages and dangling refs (exit 1)',
         examples: [
-            ['lint the cwd wiki', 'shipkit wiki lint'],
-            ['lint a subtree', 'shipkit wiki lint --root agent --index process.md'],
+            ['lint the cwd wiki', 'sk wiki lint'],
+            ['lint a subtree', 'sk wiki lint --root agent --index process.md'],
         ],
     })
 

package/src/cli.ts

@@ -11,7 +11,7 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand } from './cli/cmd_GlobalProcesses.ts'
+import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
@@ -29,6 +29,7 @@ import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
 import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
+import { WhenCommand } from './cli/cmd_When.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
@@ -43,7 +44,7 @@ import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 export function buildCli(): Cli {
     const cli = new Cli({
         binaryLabel: 'shipkit — repo toolkit',
-        binaryName: 'shipkit',
+        binaryName: 'sk',
         binaryVersion: LIB_VERSION,
         enableCapture: true, // console output pipes into the command streams (testable)
         enableColors: true,
@@ -91,10 +92,14 @@ export function buildCli(): Cli {
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
     cli.register(GlobalProcessesCommand)
+    cli.register(GlobalProcessStartCommand)
+    cli.register(GlobalProcessStopCommand)
+    cli.register(GlobalProcessRestartCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
+    cli.register(WhenCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
     cli.register(ConfigKeysCommand)

package/src/collections/checks.ts

@@ -20,6 +20,7 @@ import { rawName, routesToShipkit } from '../core/canonical-scripts.ts'
 import { FLOOR_IDS } from '../core/floor.ts'
 import { FOREVER_MS, formatLine, ttlMsOf } from '../core/wire.ts'
 import { gateInventory, type CheckRow } from '../ledger/gate-checks.ts'
+import { runsCellsOf } from '../core/runs-matrix.ts'
 import { readLastLines, readRuns, runsPath, type LastLine, type RunRow } from '../ledger/run-log.ts'
 import { checkStatsFor, type CheckStat } from '../ledger/check-stats.ts'
 import { NEGATIVE_TTL_CAP_MS } from '../ledger/world-cache.ts'
@@ -114,6 +115,7 @@ function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat
         description: row.description,
         lastLines: wireLines,
         gate: row.gate,
+        runs: runsCellsOf(row),
         build: row.build,
         blocking: row.blocking,
         advisory,

package/src/collections/collection-types.ts

@@ -7,6 +7,7 @@
 // the docs wiki this lib ships beside.
 
 import type { WhenAt, WhenSource } from '../core/when.ts'
+import type { RunsCells } from '../core/runs-matrix.ts'
 import type { CheckFrom } from '../ledger/gate-checks.ts'
 
 export type NeedSeverity = 'red' | 'yellow'
@@ -22,14 +23,15 @@ export const RUNS_ID = 'runs'
  *  row, the runs page and the to fix list all open the same page by it */
 export const testId = (file: string): string => `test:${file}`
 
-/** where the tree files the test files no check reaches, in both views */
+/** the path segment of a test file no check reaches, where a check id sits
+ *  for the others, so the filter finds a test file by its check */
 export const NO_CHECK = 'in no check'
 
-/** the resource KIND, never the collection it came from: one folder holds
- *  several kinds, which is what makes the path tree worth having. There is no
+/** the resource KIND, never the collection it came from: it decides the
+ *  section a row lives under (hub-app/tree-build.ts KIND_SECTION). There is no
  *  catch all kind: a row belongs to an owner, and what belongs to the hub
  *  itself is its status (serve/hub-problems.ts), never a row */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 
@@ -53,6 +55,9 @@ export type CheckFacts = {
     lastLines: string[]
     /** does `shipkit ci` run it? false = proactive, `shipkit check` only */
     gate: boolean
+    /** every context it runs in and how it caches, as the when page draws
+     *  it (core/runs-matrix.ts) */
+    runs: RunsCells
     /** a BUILD STEP: the gate runs it, the health pass does not (derived from
      *  a floor slot or the repo's `tasks: []`, never declared by a check) */
     build: boolean
@@ -161,6 +166,19 @@ export type TestRun = {
  *  declaration names a file that is not on disk */
 export type TestStanding = 'runs' | 'ignored' | 'orphan' | 'opaque' | 'missing'
 
+/** an ask as its line on the asks page reads it: the frontmatter of its file */
+export type AskFacts = {
+    kind: string
+    /** `YYYY-MM-DD`, `?` when the file carries none */
+    created: string
+    /** `YYYY-MM-DD` for a done ask, null otherwise or when it was not stamped */
+    closed: string | null
+    /** what it blocks, `-` for nothing named */
+    blocks: string
+    /** the shell probe that closes it once it exits 0, null for a manual ask */
+    probe: string | null
+}
+
 /** one test file, as its row and its page read it */
 export type TestFacts = {
     /** repo relative */
@@ -243,6 +261,8 @@ export type Instance = {
     check?: CheckFacts
     /** test files only: where it runs and what it last cost */
     test?: TestFacts
+    /** asks only: what its frontmatter says */
+    ask?: AskFacts
     /** an open ask owns the action (dedup = acted-on once, never hidden):
      *  the instance stays red HERE but verbs and pings live with the ask */
     askOwned?: boolean

package/src/collections/providers.ts

@@ -17,12 +17,12 @@ import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
 // runtime and the canvas binding, ~400ms of module load, and the hub's
 // collection list is built on every request by callers that mostly never heal
 import type { healIdentity } from '../assets/run-assets.ts'
-import { doneAsks, openAsks } from '../asks/asks-queue.ts'
+import { doneAsks, openAsks, type Ask } from '../asks/asks-queue.ts'
 import { evaluateContracts } from '../contracts/contracts-engine.ts'
 import { CheckCtx } from '../core/check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { activeContracts, contractsConfigFrom } from '../contracts/apply-contracts.ts'
-import type { CheckFacts, Collection, Instance } from './collection-types.ts'
+import type { AskFacts, CheckFacts, Collection, Instance } from './collection-types.ts'
 import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
 import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
@@ -119,6 +119,8 @@ const slug = (t: string): string => t.toLowerCase().replace(/[^a-z0-9]+/g, '-').
 /** wire lines re-rendered as a fenced block for an instance's md */
 const wireMd = (lines: string[]): string => `\`\`\`\n${lines.join('\n')}\n\`\`\``
 
+const askFacts = (a: Ask): AskFacts => ({ kind: a.kind, created: a.created, closed: a.closed, blocks: a.blocks, probe: a.check })
+
 export function asksCollection(root: string, c: RepoConfig): Collection {
     return {
         id: 'asks',
@@ -141,6 +143,7 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
                 file: `${rel}/${a.file}`,
                 md: mdBody(join(root, rel, a.file)),
                 remarks: lastRemarks(join(root, rel, a.file)),
+                ask: askFacts(a),
             }))
             // the done/ archive rides along QUIET (no severity) — past answers
             // stay consultable and remarkable; newest first, after every open ask
@@ -155,6 +158,7 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
                 file: `${rel}/done/${a.file}`,
                 md: mdBody(join(root, rel, 'done', a.file)),
                 remarks: lastRemarks(join(root, rel, 'done', a.file)),
+                ask: askFacts(a),
             }))
             return [...open, ...done]
         },

package/src/contracts/apply-contracts.ts

@@ -10,21 +10,22 @@ import { tagCheckLines } from '../check.ts'
 import { defineScan } from '../scan.ts'
 import { allContracts } from './contract-manifests.ts'
 import type { ContractManifest } from './contract-types.ts'
+import { webDeploys, webRootOf, type WebDisk } from './web-surface.ts'
 import { evaluateContracts, type ContractsConfig, type ContractsResult } from './contracts-engine.ts'
 
-export function contractsConfigFrom(c: RepoConfig, d: Pick<ScanCtx, 'root' | 'exists'>): ContractsConfig {
+export function contractsConfigFrom(c: RepoConfig, d: WebDisk & Pick<ScanCtx, 'root'>): ContractsConfig {
     const venues = c.venues ?? []
     const social = c.social ?? []
-    const declared = [
-        ...venues,
-        ...(social.length > 0 ? ['social'] : []),
-        ...(social.includes('discord') ? ['discord'] : []),
-    ]
+    const declared = [...venues, ...(social.length > 0 ? ['social'] : [])]
+    const deploys = webDeploys(d)
+    // a public repo whose only surface is an npm package has no page to serve an identity on
+    const npmOnly = c.release?.npm === true && deploys.length === 0 && venues.length === 0
     return {
         root: d.root,
         declared,
         social,
-        publicSurface: venues.length > 0 || d.exists('deploy.sh'),
+        publicSurface: venues.length > 0 || deploys.length > 0 || (c.visibility === 'public' && !npmOnly),
+        webRoot: webRootOf(c.contracts?.webRoot, deploys),
         exempt: c.contracts?.exempt,
         docsBase: c.docsBase,
     }
@@ -45,7 +46,7 @@ export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: { id
     for (const l of lines) t.lines.push(l)
     if (r.exitCode === 1) t.failed = true
     if (r.lines.some((l) => l.kind === 'warn')) t.warned = true
-    if (r.lines.length === 0) {
+    if (r.lines.every((l) => l.kind === 'note')) {
         const text = 'no contracts apply (nothing declared, nothing detected)'
         t.ok(tag?.id != null ? `[${tag.id}] ${text}` : text)
     }

package/src/contracts/contract-types.ts

@@ -1,7 +1,8 @@
 // The data language `*.contract.ts` manifest files are written in: a venue
 // contract = folder + artifact rules + detectors. Evaluation engine lands in
 // ./contracts-engine.ts (0.1). All rule paths are REPO-ROOT-relative so a
-// contract can require files outside its own folder (e.g. public/og.png).
+// contract can require files outside its own folder (e.g. {web}/og.png, where
+// `{web}` is the repo's web root, contracts/web-surface.ts).
 // `warnOnly` demotes a rule to WARN — for mandates gated on a later step.
 
 export type RuleOpts = { warnOnly?: boolean }
@@ -25,9 +26,13 @@ export type Detector =
     | { kind: 'script'; pattern: string }
     | { kind: 'fileContains'; path: string; pattern: string }
     | { kind: 'dirExists'; path: string }
+    /** a file matching the glob holds a line matching the (multiline) pattern */
+    | { kind: 'fileMatches'; glob: string; pattern: string }
 
 export type ContractEnv = {
     root: string
+    /** the dir the site serves, what `{web}` in a rule path stands for */
+    webRoot: string
     venues: string[]
     social: string[]
     exists: (relPath: string) => boolean
@@ -47,7 +52,7 @@ export type ContractManifest = {
     owner: string
     /** `declared` = required once the repo names this venue. `always` = every repo, behind `gate` */
     appliesTo: 'declared' | 'always'
-    /** `always` contracts only: FAIL once a public surface exists, WARN before */
+    /** `always` contracts only: applies once a public surface exists, silent before */
     gate?: 'public-surface'
     /** signals that this venue is in play although the repo never declared it, so config cannot lie */
     detect: Detector[]
@@ -65,6 +70,7 @@ export const custom = (id: string, probe: CustomRule['probe'], p?: RuleOpts): Cu
 export const script = (pattern: string): Detector => ({ kind: 'script', pattern })
 export const fileContains = (path: string, pattern: string): Detector => ({ kind: 'fileContains', path, pattern })
 export const dirExists = (path: string): Detector => ({ kind: 'dirExists', path })
+export const fileMatches = (glob: string, pattern: string): Detector => ({ kind: 'fileMatches', glob, pattern })
 
 export function validateManifest(m: ContractManifest): string[] {
     const errs: string[] = []

package/src/contracts/contracts-engine.ts

@@ -4,8 +4,9 @@
 // - undeclared venue whose detectors fire → FAIL (config can't lie,
 //   folders can't rot)
 // - exempt venues skip VISIBLY with their reason; never silence
-// - 'always' contracts with gate 'public-surface': full severity once the
-//   repo has a public surface, everything demoted to WARN before.
+// - 'always' contracts with gate 'public-surface': apply once the repo has a
+//   public surface, silent before (nothing is served yet).
+// - a rule path's `{web}` is the repo's web root (contracts/web-surface.ts).
 // Every FAIL carries a fix: pointer = docsBase + manifest.owner.
 //
 // It reads ONLY through the disk it is handed (a check context), so what a
@@ -23,8 +24,10 @@ export type ContractsConfig = {
     declared: string[]
     /** social channel list — handed to custom rules via ContractEnv */
     social: string[]
-    /** repo has a public surface (deploy script or any declared venue) — gates 'always' contracts */
+    /** repo has a public surface (a deploy, a declared venue, a public repo) — gates 'always' contracts */
     publicSurface: boolean
+    /** the dir the site serves, substituted for `{web}` in rule paths (default 'public') */
+    webRoot?: string
     /** venue → reason; skips the venue VISIBLY */
     exempt?: Record<string, string>
     /** prefix for fix: pointers, e.g. a docs checkout path or URL */
@@ -84,6 +87,14 @@ export function globFiles(pattern: string, d: ContractDisk): string[] {
 /** the text of a file, null when no FILE stands there */
 const textOf = (d: ContractDisk, rel: string): string | null => (d.exists(rel, 'file') ? d.read(rel) : null)
 
+/** a rule with `{web}` replaced by the web root, `.` meaning the repo root */
+export function atWebRoot(rule: ArtifactRule, webRoot: string): ArtifactRule {
+    const sub = (s: string): string => s.replaceAll('{web}/', webRoot === '.' ? '' : `${webRoot}/`)
+    if ('path' in rule) return { ...rule, path: sub(rule.path) }
+    if ('pattern' in rule) return { ...rule, pattern: sub(rule.pattern) }
+    return rule
+}
+
 async function checkRule(rule: ArtifactRule, env: ContractEnv, d: ContractDisk): Promise<string[]> {
     const problems: string[] = []
     switch (rule.kind) {
@@ -145,6 +156,10 @@ function detectorFires(m: ContractManifest, d: ContractDisk): string | null {
     for (const det of m.detect) {
         if (det.kind === 'dirExists') {
             if (d.exists(det.path)) return `${det.path}/ exists`
+        } else if (det.kind === 'fileMatches') {
+            const re = new RegExp(det.pattern, 'm')
+            const hit = globFiles(det.glob, d).find((f) => re.test(textOf(d, f) ?? ''))
+            if (hit != null) return `${hit} matches /${det.pattern}/`
         } else if (det.kind === 'fileContains') {
             const text = textOf(d, det.path)
             if (text != null && new RegExp(det.pattern).test(text)) return `${det.path} matches /${det.pattern}/`
@@ -166,8 +181,10 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
     const lines: Line[] = []
     const outcomes: ContractOutcome[] = []
     let anyFail = false
+    const webRoot = cfg.webRoot ?? 'public'
     const env: ContractEnv = {
         root: cfg.root,
+        webRoot,
         venues: cfg.declared,
         social: cfg.social,
         exists: (rel) => d.exists(rel),
@@ -180,7 +197,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
     for (const m of manifests) {
         const exemptReason = cfg.exempt?.[m.venue]
         if (exemptReason != null) {
-            lines.push({ kind: 'skip', text: `${m.venue}  exempt: "${exemptReason}"` })
+            lines.push({ kind: 'skip', text: `${m.venue}: exempt: "${exemptReason}"` })
             outcomes.push({ venue: m.venue, status: 'exempt', problems: 0 })
             continue
         }
@@ -189,28 +206,32 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
             const signal = detectorFires(m, d)
             if (signal != null) {
                 anyFail = true
-                lines.push({ kind: 'fail', text: `${m.venue}  ships (${signal}) but venue is not declared — declare it or remove the signal` })
+                lines.push({ kind: 'fail', text: `${m.venue}: ships (${signal}) but venue is not declared — declare it or remove the signal` })
                 lines.push(...fix(m, 'declare + fill the contract'))
                 outcomes.push({ venue: m.venue, status: 'fail', problems: 1 })
             } else {
+                // a folder with nothing out yet (local drafts) is work in progress, never a ship
+                if (d.exists(m.dir, 'dir')) lines.push({ kind: 'note', text: `${m.venue}: ${m.dir}/ holds work that is not out yet, nothing to check until the venue is declared` })
                 outcomes.push({ venue: m.venue, status: 'not-applicable', problems: 0 })
             }
             continue
         }
-        // demote everything to WARN on ungated 'always' contracts (no public surface yet)
-        const warnAll = m.appliesTo === 'always' && m.gate === 'public-surface' && !cfg.publicSurface
+        // an 'always' contract gated on a public surface means nothing before one exists
+        if (m.appliesTo === 'always' && m.gate === 'public-surface' && !cfg.publicSurface) {
+            outcomes.push({ venue: m.venue, status: 'not-applicable', problems: 0 })
+            continue
+        }
         let problems = 0
         let warned = 0
         for (const rule of m.artifacts) {
-            const found = await checkRule(rule, env, d)
-            const asWarn = warnAll || rule.warnOnly === true
+            const found = await checkRule(atWebRoot(rule, webRoot), env, d)
             for (const p of found) {
-                if (asWarn) {
+                if (rule.warnOnly === true) {
                     warned++
-                    lines.push({ kind: 'warn', text: `${m.venue}  ${p}${warnAll ? ' (no public surface yet — WARN not FAIL)' : ''}` })
+                    lines.push({ kind: 'warn', text: `${m.venue}: ${p}` })
                 } else {
                     problems++
-                    lines.push({ kind: 'fail', text: `${m.venue}  ${p}` })
+                    lines.push({ kind: 'fail', text: `${m.venue}: ${p}` })
                 }
             }
         }
@@ -224,7 +245,7 @@ export async function evaluateContracts(manifests: ContractManifest[], cfg: Cont
         } else if (warned > 0) {
             outcomes.push({ venue: m.venue, status: 'warn', problems: warned })
         } else {
-            lines.push({ kind: 'ok', text: `${m.venue}  ${m.dir}/ complete (${m.artifacts.length} rule(s))` })
+            lines.push({ kind: 'ok', text: `${m.venue}: ${m.dir}/ complete (${m.artifacts.length} rule(s))` })
             outcomes.push({ venue: m.venue, status: 'ok', problems: 0 })
         }
     }

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

@@ -1,6 +1,7 @@
 // normative WHAT for .shipkit/identity/ — every repo with a public surface owns
-// its brand source + committed favicon/logo/OG outputs. gate: FAIL once a
-// public surface exists (deploy.sh or any declared venue), WARN before.
+// its brand source + committed favicon/logo/OG outputs, at the web root its
+// deploy serves (`{web}`). gate: applies once a public surface exists (a
+// deploy, a declared venue, a public repo that is more than an npm package).
 import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
@@ -12,8 +13,8 @@ export default defineContract({
     detect: [],
     artifacts: [
         file('.shipkit/identity/brand.ts'),
-        png('public/favicon.png', 512, 512),
-        png('public/og.png', 1200, 630, { atLeast: true }),
-        glob('public/logo.*', { min: 1 }),
+        png('{web}/favicon.png', 512, 512),
+        png('{web}/og.png', 1200, 630, { atLeast: true }),
+        glob('{web}/logo.*', { min: 1 }),
     ],
 })

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

@@ -1,13 +1,15 @@
 // normative WHAT for .shipkit/social/ (posts ONLY — the Discord server contract is
 // discord.contract.ts). Declared = the repo config lists social channels.
-import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+// Undeclared, it ships only once a post is out (`status: posted`): a folder
+// of local drafts is work in progress, never a ship.
+import { custom, defineContract, fileMatches } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'social',
     dir: '.shipkit/social',
     owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
-    detect: [dirExists('.shipkit/social')],
+    detect: [fileMatches('.shipkit/social/**/*.md', '^status:\\s*posted\\b')],
     artifacts: [
         custom('declared-channel-dirs', (env) =>
             env.social

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

@@ -1,6 +1,6 @@
 // normative WHAT for .shipkit/steam/ — the WHY + workflow live in the sibling page.
 // Capsule sizes as of 2026-07 — Valve churns them: re-verify at use, bump here.
-import { defineContract, dir, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
+import { custom, defineContract, dirExists, file, fileContains, glob, md, png, script } from 'rvlib-shipkit/src/contracts/contract-types.ts'
 
 export default defineContract({
     venue: 'steam',
@@ -22,7 +22,11 @@ export default defineContract({
         // .ico, dims not png-parseable — presence-checked only
         file('.shipkit/steam/capsules/client-icon.ico'),
         glob('.shipkit/steam/screenshots/*.png', { min: 5, width: 1920, height: 1080 }),
-        // vdf scripts only exist once the appid does — nag, don't block
-        dir('.shipkit/steam/vdf', { warnOnly: true }),
+        // vdf scripts need the Steamworks appid (recorded in steam_appid.txt,
+        // Valve's own file name): before it, the line names that blocker
+        custom('vdf', (env) => {
+            if (!env.exists('.shipkit/steam/steam_appid.txt')) return ['no Steamworks appid yet (.shipkit/steam/steam_appid.txt): the vdf/ build scripts wait on it']
+            return env.exists('.shipkit/steam/vdf') ? [] : ['.shipkit/steam/vdf/ missing: the appid exists, write the app build and depot scripts']
+        }, { warnOnly: true }),
     ],
 })

package/src/contracts/web-surface.ts

@@ -0,0 +1,59 @@
+// What a repo serves on the web, read from how it deploys: a GitHub Pages
+// workflow, a wrangler config, or deploy.sh. The web root is where the
+// identity outputs (favicon, logo, OG image) must land to be served, so it
+// comes from the deploy, never a hardcoded `public/`.
+// pure over the disk it is handed: SK002 is cached on what it reads through it
+import type { ScanCtx } from '../core/check-ctx.ts'
+
+export type WebDisk = Pick<ScanCtx, 'read' | 'exists' | 'entries'>
+/** `source`: the file that says the repo deploys; `root`: the served dir, null when that file does not name one */
+export type WebDeploy = { source: string; root: string | null }
+
+const WORKFLOWS = '.github/workflows'
+const PAGES = /actions\/(?:deploy-pages|upload-pages-artifact)|peaceiris\/actions-gh-pages|cloudflare\/(?:pages|wrangler)-action|wrangler\s+pages\s+deploy/
+const WRANGLER = ['wrangler.toml', 'wrangler.json', 'wrangler.jsonc']
+export const DEFAULT_WEB_ROOT = 'public'
+
+const clean = (dir: string): string => dir.replace(/^["']|["']$/g, '').replace(/^\.\//, '').replace(/\/+$/, '') || '.'
+
+/** the served dir a deploy file names, null when it names none */
+function rootIn(text: string): string | null {
+    const pick = (re: RegExp): string | null => {
+        const m = text.match(re)
+        return m?.[1] != null ? clean(m[1]) : null
+    }
+    return (
+        pick(/upload-pages-artifact@[^\n]*\n(?:[ \t]+[^\n]*\n)*?[ \t]+path:\s*(\S+)/) ??
+        pick(/publish_dir:\s*(\S+)/) ??
+        pick(/wrangler\s+pages\s+deploy\s+([^\s-]\S*)/) ??
+        pick(/pages_build_output_dir["']?\s*[:=]\s*["']([^"']+)["']/) ??
+        pick(/\[assets\][^[]*?directory\s*=\s*["']([^"']+)["']/) ??
+        pick(/"assets"\s*:\s*\{[^}]*"directory"\s*:\s*"([^"]+)"/) ??
+        pick(/\[site\][^[]*?bucket\s*=\s*["']([^"']+)["']/)
+    )
+}
+
+/** every deploy this repo declares, in the order a web root is read from */
+export function webDeploys(d: WebDisk): WebDeploy[] {
+    const out: WebDeploy[] = []
+    for (const e of d.entries(WORKFLOWS)) {
+        if (e.kind !== 'file' || !/\.ya?ml$/.test(e.name)) continue
+        const text = d.read(`${WORKFLOWS}/${e.name}`) ?? ''
+        if (PAGES.test(text)) out.push({ source: `${WORKFLOWS}/${e.name}`, root: rootIn(text) })
+    }
+    for (const f of WRANGLER) {
+        const text = d.exists(f, 'file') ? d.read(f) : null
+        if (text != null) out.push({ source: f, root: rootIn(text) })
+    }
+    const sh = d.exists('deploy.sh', 'file') ? d.read('deploy.sh') : null
+    if (sh != null) out.push({ source: 'deploy.sh', root: rootIn(sh) })
+    return out
+}
+
+/** where the identity outputs go: the config's `contracts.webRoot`, else the
+ *  first dir a deploy names, else `public` */
+export function webRootOf(configured: string | undefined, deploys: WebDeploy[]): string {
+    if (configured != null) return clean(configured)
+    return deploys.find((x) => x.root != null)?.root ?? DEFAULT_WEB_ROOT
+}
+

package/src/core/budget.ts

@@ -11,12 +11,14 @@ import type { MachineLoad } from '../suite/judge-suites.ts'
  *  2s at their 90th percentile, and the few past it shell out to a tool */
 export const IN_PROCESS_BUDGET_MS = 2_000
 
-/** a subprocess (a build step, a test suite, a `cmd` check) or a world probe.
+/** a subprocess (a build step, a test suite, a `cmd` check) or a world probe
+ *  (a `ttl` check, or a `never:` one, whose answer lives outside the repo).
  *  Read off the same record: every typecheck stays under 6s at its 90th
  *  percentile, and the quick test suites under 6s but one */
 export const SUBPROCESS_BUDGET_MS = 10_000
 
-/** what a check declares about itself that picks its default */
+/** what a check declares about itself that picks its default. `world`: it
+ *  declares `ttl` or `never`, so it reads the world rather than the repo */
 export type BudgetKind = { build: boolean; cmd: boolean; world: boolean }
 
 export const defaultBudget = (k: BudgetKind): number => (k.build || k.cmd || k.world ? SUBPROCESS_BUDGET_MS : IN_PROCESS_BUDGET_MS)
@@ -36,7 +38,15 @@ export const unknownBudgetIds = (ids: readonly string[], budgets: Record<string,
 export const budgetValueProblem = (v: unknown): string | null =>
     typeof v === 'number' && Number.isInteger(v) && v > 0 ? null : `must be a whole number of milliseconds above 0, got ${JSON.stringify(v)}`
 
-export const machineLoad = (): MachineLoad => ({ load1: loadavg()[0] ?? 0, cores: availableParallelism() })
+/** `<load1>/<cores>` in this variable pins the reading: a test of a budget
+ *  verdict must not depend on what else the machine runs */
+export const MACHINE_LOAD_ENV = 'SHIPKIT_MACHINE_LOAD'
+
+export const machineLoad = (): MachineLoad => {
+    const pinned = process.env[MACHINE_LOAD_ENV]?.match(/^(\d+(?:\.\d+)?)\/(\d+)$/)
+    if (pinned != null) return { load1: Number(pinned[1]), cores: Number(pinned[2]) }
+    return { load1: loadavg()[0] ?? 0, cores: availableParallelism() }
+}
 
 /** `10s` for a whole second count, `150ms` otherwise */
 export const fmtBudget = (ms: number): string => (ms % 1000 === 0 ? `${ms / 1000}s` : `${ms}ms`)
@@ -49,12 +59,12 @@ export const isBudgetLine = (text: string): boolean => /^\S+ (passed|warned) in
 /** a test check sends the reader to the page that breaks its time down */
 const isTestCheck = (id: string): boolean => id === 'test' || id.startsWith('test:')
 
-/** the WARN a pass over its budget prints, or null inside it. A loaded
- *  machine is named, because wall time is what the reader waits on and load
- *  is the first thing to rule out */
+/** the WARN a pass over its budget prints, or null inside it. Null too with
+ *  the load at or past the core count: the budget judges wall time, and on a
+ *  saturated machine the wall is the machine's, not the check's (a suite's
+ *  own verdict judges CPU instead, suite/judge-suites.ts) */
 export function budgetLine(id: string, ms: number, budgetMs: number, load: MachineLoad, verb: 'passed' | 'warned' = 'passed'): string | null {
-    if (ms <= budgetMs) return null
-    const loaded = load.load1 >= load.cores ? ` under load ${load.load1.toFixed(1)} on ${load.cores} cores,` : ''
+    if (ms <= budgetMs || load.load1 >= load.cores) return null
     const where = isTestCheck(id) ? 'see the tests page for where the time goes' : 'its page in the hub shows every run'
-    return `${id} ${verb} in ${(ms / 1000).toFixed(1)}s,${loaded} over its ${fmtBudget(budgetMs)} budget: ${where}`
+    return `${id} ${verb} in ${(ms / 1000).toFixed(1)}s, over its ${fmtBudget(budgetMs)} budget: ${where}`
 }