rvlib-shipkit 1.3.0 → 1.4.0

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

@@ -1,10 +1,10 @@
 // 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'
+// a dangling ref there fails. A link that leaves agent/ but stays in the repo
+// is checked on disk; a pointer out of the repo (a house wiki) is backticked,
+// never a bare → or @. A repo without agent/index.md skips.
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
 import { check } from '../check.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
@@ -18,11 +18,33 @@ export const agentWikiLinks = check({
     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)`)
+        const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
+        const linked = lint.pages.filter((p) => !lint.orphans.includes(p))
+        for (const f of lint.orphans) {
+            const by = namingPage(c.root, f, linked)
+            const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
+            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)
+        }
+        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`)
         if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
     },
 })
 
+/** the linked page whose text already names an orphan (its path, its file
+ *  name, or a glob its file name matches), the one to turn into a link */
+function namingPage(root: string, orphan: string, pages: string[]): string | null {
+    const name = basename(orphan)
+    const stem = name.replace(/\.md$/, '')
+    for (const p of pages) {
+        const text = readFileSync(join(root, 'agent', p), 'utf8')
+        if (text.includes(orphan) || text.includes(name) || text.includes(`${stem}.`) || text.includes(`${stem} `)) return `agent/${p}`
+        for (const m of text.matchAll(/[\w.-]*\*[\w.*-]*/g)) {
+            const g = m[0]
+            if (g.replace(/[*.]/g, '').length < 3) continue
+            if (new Bun.Glob(g).match(name) || new Bun.Glob(`${g}.md`).match(name)) return `agent/${p}`
+        }
+    }
+    return null
+}
+
 export default agentWikiLinks

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

@@ -52,12 +52,16 @@ const REQUIREMENTS: Requirement[] = [
             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',
+                fix: `add a screenshot to README.md: ![what it looks like](docs/screenshot.png), a file in the repo, or an https url; ${OFF}`,
             }
         },
     },
 ]
 
+/** the other way out, for a repo that cannot show one: the rule off, with the
+ *  reason `defineRepo` requires (core/when.ts) */
+const OFF = `or, when this repo cannot show one, turn the rule off with the reason: when: { SK028: 'off:<why this repo shows no screenshot>' } in repo.config.ts, inside its shipkit gate block`
+
 export const readme = check({
     id: 'SK028',
     blocking: false,
@@ -66,7 +70,7 @@ export const readme = check({
     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')
+        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; ${OFF}`)
         c.ok(`${README} exists`)
         for (const r of REQUIREMENTS) {
             const f = r.test(c, md)

package/src/cli/cmd_CrossRepoActivity.ts

@@ -60,7 +60,10 @@ export function renderActivity(a: ActivityAnswer, cap: number): string[] {
     for (const r of [...busy, ...quiet]) {
         const branch = r.branch ?? (r.detached == null ? '' : `detached ${r.detached}`)
         out.push(`${r.name}  ${dot(r)}  ${branch}  (${upstreamWords(r)})`)
-        if (r.status != null && r.status.reds.length > 0) out.push(`    failing: ${r.status.reds.map((id) => (r.status!.since[id] == null ? id : `${id} (${ageShort(r.status!.since[id]!, a.now)})`)).join(', ')}`)
+        for (const c of r.failing ?? []) {
+            out.push(`    ${c.status === 'fail' ? '✗' : '!'} ${c.id}${c.at == null ? '' : ` (${ageShort(c.at, a.now)})`}`)
+            for (const l of c.lines) out.push(`        ${l}`)
+        }
         if (r.error != null) out.push(`    git failed: ${r.error}`)
         const dirt = r.error == null ? dirtWords(r) : ''
         if (dirt !== '') {

package/src/collections/collection-types.ts

@@ -161,6 +161,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 +256,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}`
 }

package/src/core/check-runner.ts

@@ -56,6 +56,10 @@ import { feedsProblemsPane, type Population, type Problem } from '../problems/pr
  *  about the world. */
 export const CHECK_TIMEOUT_MS = 120_000
 
+/** the most findings a failed build step keeps beside its headline: a tool
+ *  that prints a wall of them is read in its log */
+const MAX_EXTRA = 20
+
 /** epoch ms that never goes backwards inside one process, whole numbers so a
  *  row's `at - ms` is its start exactly: the wall clock can step back (an NTP
  *  correction), and a check stamped before an earlier one ended makes the
@@ -431,6 +435,9 @@ type Live = RunnableCheck & CheckResult & {
     /** what the headline carries after the id: a failure's last line, or the
      *  reason it never ran */
     tail: string
+    /** a failed build step's other findings, the wire lines its tool printed
+     *  beside the one the headline carries */
+    extra: Line[]
 }
 
 export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
@@ -454,8 +461,11 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             blocking: u.blocking, advisory: r.advisory, lines: r.lines, problems: r.problems, logPath: r.logPath, lastLine: r.lastLine, note: r.note, attached,
         })
         // an attached check is filed as a replay: it measured nothing, and a
-        // row carrying its wait would read as a check running in this process
-        o.log?.add({ id: u.id, status: r.status, ms: r.ms, replayed: r.replayed || attached, lines: r.lines, at })
+        // row carrying its wait would read as a check running in this process.
+        // A non-blocking failure is filed as the warning the gate printed, so
+        // no surface reading the record paints red what the gate called orange
+        const filed = r.status === 'fail' && r.advisory ? 'warn' : r.status
+        o.log?.add({ id: u.id, status: filed, ms: r.ms, replayed: r.replayed || attached, lines: r.lines, at })
     }
 
     // OFF, in ONE place: skipped by name, never run, never stored, and the
@@ -476,7 +486,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const runDir = openRunDir(o.logDir)
     const checks: Live[] = sel.selected.map((u) => ({
         ...u,
-        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, synthetic: false, tail: '',
+        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, synthetic: false, tail: '', extra: [],
         logPath: u.body.cmd != null ? join(runDir, `${u.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
     }))
     const selectedIds = new Set(checks.map((u) => u.id))
@@ -670,14 +680,25 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         u.problems = findings(u, u.lines, r.out)
         const lastFail = u.lines.filter((l) => l.kind === 'fail').at(-1)
         if (lastFail != null) u.lastLine = lastFail.text.slice(0, 200)
+        // a tool that speaks the wire (the suite runner) ends on its FAIL
+        // lines, and the headline carries only the last one. Only that closing
+        // block is its report: a wire line earlier in the log is some test's
+        // own output
+        if (u.build && u.status === 'fail') {
+            const parsed = parseWireOutput(r.out)
+            let i = parsed.length
+            while (i > 0 && (parsed[i - 1]!.kind === 'fail' || parsed[i - 1]!.kind === 'fix-fail')) i--
+            u.extra = parsed.slice(i).filter((l) => !(l.kind === 'fail' && `FAIL: ${l.text}` === u.lastLine)).slice(-MAX_EXTRA)
+        }
     }
 
     /** a check that printed nothing of its own still has to report that it
      *  ran: the verdict, its name, and (at print time) what it cost */
     const headlineOf = (u: Live): void => {
         u.synthetic = true
-        u.tail = u.status === 'fail' ? (u.lastLine === '' ? '' : ` — ${u.lastLine}`) : u.status === 'skip' ? (u.note === '' ? '' : ` (${u.note})`) : ''
-        u.lines = [{ kind: u.status === 'fail' ? 'fail' : u.status === 'skip' ? 'skip' : 'ok', text: `${u.id}${u.tail}` }]
+        const more = u.extra.filter((l) => l.kind === 'fail').length
+        u.tail = u.status === 'fail' ? (u.lastLine === '' ? '' : ` — ${u.lastLine}${more > 0 ? ` (+${more} more below)` : ''}`) : u.status === 'skip' ? (u.note === '' ? '' : ` (${u.note})`) : ''
+        u.lines = [{ kind: u.status === 'fail' ? 'fail' : u.status === 'skip' ? 'skip' : 'ok', text: `${u.id}${u.tail}` }, ...u.extra]
     }
 
     /** what an attached asker adopts: the verdict and the lines BEFORE this