rvlib-shipkit 1.4.0 → 1.6.0

package/src/repo-config.ts

@@ -59,29 +59,11 @@ export type ServeConfig = {
      *  prints beside localhost and rides on every ping message, because a
      *  phone cannot resolve localhost */
     publicHost?: string
-    /** the long running processes this repo needs (a dev server, a watcher).
-     *  The hub supervises them: a switch each on its page, a crash restarts,
-     *  and they outlive a hub restart */
-    processes?: ProcessDecl[]
     /** the ids of the global processes this repo needs (any house repo's
      *  `globalProcess` unit files). The home rail marks the repo while one is off */
     uses?: string[]
 }
 
-/** one long running process a repo needs, supervised by its hub */
-export type ProcessDecl = {
-    /** kebab-case, unique in this repo */
-    id: string
-    /** the command as a list of words, run from the repo root */
-    cmd: string[]
-    /** where it runs, repo-relative (default the repo root) */
-    cwd?: string
-    /** the url it serves, probed for up and shown as a link */
-    url?: string
-    /** starts with the hub. Default false: it starts from its switch */
-    auto?: boolean
-}
-
 export type RepoConfig = {
     /** the repo name, as every surface prints it: the gate header, the hub
      *  title, the motherhome row, the default hub port hash. The pre-commit
@@ -161,6 +143,15 @@ export type RepoConfig = {
     /** repo-contributed .gitignore lines, rendered INSIDE rule SK004's managed
      *  block — for ecosystem-specific names the published lib may not carry */
     gitignore?: string[]
+    /** gitignored paths a task READS, by task id (`'*'` for every task),
+     *  repo-relative: a path joins that task's key by content (generated
+     *  types, a local fixture), and `dir/**` by the names under the dir (an
+     *  output folder a suite lists). A task keyed on the whole work tree sees
+     *  no gitignored file, and a declared list names none either, so both
+     *  carry these. The traced audit (SK031) finds the missing ones and the
+     *  fix pass writes them into their own managed block; an entry written
+     *  outside it stops that repair */
+    ignoredInputs?: Record<string, string[]>
     /** untrack the paths shipkit generates on every run (STATUS.md and
      *  friends) the first time it sees them tracked, in one commit. Default
      *  ON: a generated file left in the index dirties every tree forever and
@@ -171,21 +162,25 @@ export type RepoConfig = {
      *  folder only: it never commits, untracks, tags or pushes on the parent's
      *  history. Rule SK015 fails when this and the disk disagree (core/nesting.ts) */
     nested?: boolean
-    /** WHERE EACH CHECK RUNS, keyed by check id. One declaration for a
-     *  question that used to have three: `'always'` every gate and every
-     *  health pass, `'release'` only at `--full` and on the release path,
-     *  `'health'` only in the health pass, `'off:<reason>'` not at all.
-     *  `defineRepo` throws on a value it cannot parse, on an `off` with no
-     *  reason, and on an id no check carries. The hub writes this
-     *  map through the managed block in this file (core/when-block.ts). */
+    /** THE CHECKS THIS REPO TURNS OFF, check id → why. The one thing a repo
+     *  says about a check it does not own: where a check runs is its own
+     *  declaration (build/shipkit/runs.md), and an off check runs in no
+     *  context. `defineRepo` throws on a blank reason and on a rule id no
+     *  check carries. The hub writes this map through the managed block in
+     *  this file (core/when-block.ts). */
+    off?: Record<string, string>
+    /** RETIRED, read only while SK029 ports it into `off`: an `'off:<why>'`
+     *  value reads as `off`, and any other word is refused, because a repo
+     *  no longer places a check. Dies once `shipkit fleet` shows no repo
+     *  carrying it */
     when?: Record<string, string>
     /** WHAT A HEALTHY RUN OF EACH CHECK TAKES, in ms, keyed by check id. A
      *  check that passes over its budget prints a WARN and reads yellow, and
      *  never blocks. It wins over the check's own `budgetMs` and the default
      *  for its kind (core/budget.ts). An id no check carries fails the run,
-     *  the same as a `when` entry. */
+     *  the same as an `off` entry. */
     budgets?: Record<string, number>
-    /** DEPRECATED, read into `when` as `off:<reason>`: rule id → the reason
+    /** RETIRED, read as `off` while SK029 ports it there: rule id → the reason
      *  this repo breaks that invariant on purpose. An exempted rule does not
      *  lint and prints a skip line carrying the reason. `defineRepo` throws on
      *  an unknown id or a blank reason */
@@ -215,7 +210,7 @@ export type RepoConfig = {
         /** widens the read-only tool allowlist SK008 enforces (default Read, Grep, Glob, Bash) */
         tools?: string[]
     }
-    /** ONE WAY IN escape hatch (build/shipkit.md): governed script names this
+    /** ONE WAY IN escape hatch (build/shipkit/one-way-in.md): governed script names this
      *  repo keeps as a direct tool call. Declared per NAME, never as a list of
      *  banned binaries: the invariant is about which VERBS an agent reaches
      *  for, and a binary blocklist goes stale the day a repo changes runner.
@@ -300,18 +295,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
-
-const KEBAB = /^[a-z0-9][a-z0-9-]*$/
-const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
-
-/** why a process declaration cannot run, or null */
-export function processProblem(d: ProcessDecl): string | null {
-    if (!KEBAB.test(d.id ?? '')) return `serve.processes: id '${String(d.id)}' must be kebab-case`
-    if (!words(d.cmd)) return `serve.processes['${d.id}'] needs cmd: a list of words`
-    if (d.url != null && !/^https?:\/\//.test(d.url)) return `serve.processes['${d.id}'].url must be an http url`
-    return null
-}
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'ignoredInputs', 'untrackGenerated', 'nested', 'off', 'when', 'budgets', 'ruleExempt', 'visibility', 'archived', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -321,12 +305,15 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // a half-declared reviewer would lint a path like `.claude/agents/.md`
     if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
         throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
-    const pids = new Set<string>()
-    for (const d of c.serve?.processes ?? []) {
-        const why = processProblem(d)
-        if (why != null) throw new Error(`defineRepo: ${why}`)
-        if (pids.has(d.id)) throw new Error(`defineRepo: serve.processes declares '${d.id}' twice`)
-        pids.add(d.id)
+    if (c.serve != null && 'processes' in c.serve)
+        throw new Error(`defineRepo: serve.processes was removed; declare each process in a <name>.shipkit.ts file as \`export default globalProcess({...})\``)
+    if (c.ignoredInputs != null && (typeof c.ignoredInputs !== 'object' || Array.isArray(c.ignoredInputs)))
+        throw new Error(`defineRepo: ignoredInputs is { <task id or '*'>: [paths] }`)
+    for (const [task, paths] of Object.entries(c.ignoredInputs ?? {})) {
+        if (task === '' || !Array.isArray(paths)) throw new Error(`defineRepo: ignoredInputs '${task}' must name a task (or '*') and list paths`)
+        for (const p of paths)
+            if (typeof p !== 'string' || p === '' || p.startsWith('/') || p.split('/').includes('..'))
+                throw new Error(`defineRepo: ignoredInputs '${String(p)}' must be a repo-relative path inside the repo`)
     }
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
@@ -384,17 +371,22 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // repo rules are validated against the built-ins, so a bad id, a duplicate,
     // or an SK squatter dies at config load, not silently mid-check
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: builtinCheckIds() })
-    // a `when` moves a check off the gate, so a value it cannot act on dies
-    // here. The RULE namespace is the one this file can check: a task is
-    // resolved from the floor and a check is discovered on disk, so those two
-    // are caught by the gate against the real inventory (core/when.ts
-    // unknownWhenIds)
+    // `off` silences a check, so it names one that exists and says why. The
+    // RULE namespace is the one this file can check: a task is resolved from
+    // the floor and a check is discovered on disk, so those two are caught by
+    // the gate against the real inventory (core/when.ts unknownOffIds)
+    for (const [id, reason] of Object.entries(c.off ?? {})) {
+        if (id.trim() === '') throw new Error(`defineRepo: off has an entry with no check id`)
+        if (typeof reason !== 'string' || reason.trim() === '') throw new Error(`defineRepo: off.${id} needs a reason: a check nobody can explain is a silenced gate`)
+        if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
+            throw new Error(`defineRepo: off.${id} names no rule, the ids are in \`shipkit checks\``)
+    }
+    // the retired `when`: only its `off:<why>` word still means something
     for (const [id, raw] of Object.entries(c.when ?? {})) {
-        if (id.trim() === '') throw new Error(`defineRepo: when has an entry with no check id`)
         const w = parseWhen(raw)
         if (typeof w === 'string') throw new Error(`defineRepo: when.${id} ${w}`)
-        if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
-            throw new Error(`defineRepo: when.${id} names no rule, the ids are in \`shipkit checks\``)
+        if (w.at !== 'off')
+            throw new Error(`defineRepo: when.${id} '${raw}' no longer places a check: every check declares where it runs (build/shipkit/runs.md). A repo can only turn one off: off: { ${id}: '<why>' }`)
     }
     // a budget turns a slow pass yellow, so a value it cannot compare with dies here
     for (const [id, v] of Object.entries(c.budgets ?? {})) {

package/src/rules/rule.ts

@@ -6,14 +6,14 @@
 //
 // A new invariant is a `<name>.check.ts` file: `check({ blocking, run })`,
 // dropped anywhere in the repo, discovered with no config edit.
-import { whenOfRule } from '../core/when.ts'
+import { repoOff } from '../core/when.ts'
 import { tagCheckLines, checkCacheExtra, type Rule, type RuleEnv } from '../check.ts'
 
 export type { FixResult, Rule, RuleEnv } from '../check.ts'
 
 /** the config part of a rule's cache identity, including where it runs */
 export function ruleCacheExtra(rule: Rule, env: RuleEnv): string | undefined {
-    return checkCacheExtra(rule, env, whenOfRule(env.config, rule.id))
+    return checkCacheExtra(rule.cacheKey?.(env), repoOff(env.config, rule.id)?.reason ?? null)
 }
 
 /** tag every severity line with the rule id (check.ts owns the rendering) */

package/src/scaffold/files/agent-coding.md

@@ -7,7 +7,7 @@ always-loaded one, and route the rest by surface.
 ## Gates
 
 - **Spec-first**: the `agent/` page changes BEFORE the code it describes.
-- **`shipkit ci` is the verification.** Run it, not the linter, the
+- **`sk ci` is the verification.** Run it, not the linter, the
   typechecker and the tests one at a time.
 - **Repro before fix**: write the failing test, then fix, then re-run it.
 - One code path per concern. Delete the redundant mechanism rather than

package/src/scaffold/files/agent-index.md

@@ -5,7 +5,7 @@
 ## Quick start
 
 - `bun run hub` → the repo toolbox at http://localhost:{{PORT}}
-- `shipkit ci` → THE gate: run it to check your work, never the parts
+- `sk ci` → THE gate: run it to check your work, never the parts
 
 This folder is the project's internal wiki and its SPEC. Update the page
 BEFORE the change it describes.

package/src/scaffold/files/verify-skill.md

@@ -11,12 +11,12 @@ description: Prove a change in THIS project actually works — drive the real fl
 
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
-- Logic → fast headless bun tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
+- Logic → fast headless bun tests, run through `sk ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
 - Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 
 ## This project
-- Full gate: `shipkit ci` — THE command, never the linter, the typechecker
+- Full gate: `sk ci` — THE command, never the linter, the typechecker
   and the tests one at a time.
 - TODO, fill these in once the stack exists: the dev server command and its
   port (check it is not already running: `curl -s localhost:PORT >/dev/null

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

@@ -9,6 +9,7 @@ import { clampCap, DEFAULT_CAP, DEFAULT_MINUTES, idleRow, WINDOW_MINUTES, type A
 // the words the page and `shipkit cross-repo-activity` share live beside the shapes
 export { ageShort, CAP_MAX, CAP_MIN, clampCap, DEFAULT_CAP, dirtWords, filesWords, upstreamWords, windowWords } from '../../home/activity-shape.ts'
 import type { HomeSt } from './home-st.ts'
+import { ownTrouble, reach } from './reach.ts'
 
 export const ACTIVITY_POLL_MS = 60_000
 const MINUTES_KEY = 'home:activity:minutes'
@@ -105,11 +106,11 @@ export class ActivitySt {
     /** the repo in Fork, the git client: the daemon opens it by name */
     async openFork(name: string): Promise<void> {
         try {
-            const r = await fetch('/api/projects/fork', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name }) })
+            const r = await reach('/api/projects/fork', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name }) })
             if (!r.ok) throw new Error(await r.text())
             runInAction(() => { this.error = '' })
         } catch (e) {
-            runInAction(() => { this.error = `open ${name} in Fork: ${(e as Error).message}` })
+            runInAction(() => { this.error = ownTrouble(e, this.st.machine, (m) => `open ${name} in Fork: ${m}`) })
         }
     }
 
@@ -128,12 +129,12 @@ export class ActivitySt {
         const id = ++this.gen
         runInAction(() => { this.loading = true; this.nextAt = Date.now() + ACTIVITY_POLL_MS })
         try {
-            const r = await fetch(`/api/home/activity.json?m=${this.minutes}${fresh ? '&fresh=1' : ''}`, { signal: AbortSignal.timeout(30_000) })
+            const r = await reach(`/api/home/activity.json?m=${this.minutes}${fresh ? '&fresh=1' : ''}`, { signal: AbortSignal.timeout(30_000) })
             if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
             const j = (await r.json()) as ActivityAnswer
             runInAction(() => { if (id === this.gen) { this.data = j; this.error = '' } })
         } catch (e) {
-            runInAction(() => { if (id === this.gen) this.error = (e as Error).message })
+            runInAction(() => { if (id === this.gen) this.error = ownTrouble(e, this.st.machine) })
         } finally {
             // the countdown starts when the answer lands, so reads never overlap
             runInAction(() => { if (id === this.gen) { this.loading = false; this.nextAt = Date.now() + ACTIVITY_POLL_MS } })

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

@@ -52,7 +52,7 @@ const Next = observer(({ app }: { app: HomeSt }) => {
 })
 
 /** one commit's cells; `old` is the last one, from before the window */
-const Commit = ({ c, now, old }: { c: ActivityCommit; now: number; old: boolean }) => (
+export const Commit = ({ c, now, old }: { c: ActivityCommit; now: number; old: boolean }) => (
     <>
         <td className="acsha">{c.sha}</td>
         <td className="acwhen" title={stampWords(c.at)}>{ageShort(c.at, now)}</td>

package/src/serve/hub-app/admin-svc.ts

@@ -1,17 +1,50 @@
 // A repo's admin page, as state: what administers the repo rather than works
-// in it. Archive asks first (the confirmation is this state, so it survives a
+// in it. Its identity colours, with the app icon they give it. Archive asks first (the confirmation is this state, so it survives a
 // re-render and a test drives it headless), reload and keep active go to the
 // machine by the repo's key. On a hub of its own there is no machine, and no
 // admin page.
-import { makeAutoObservable } from 'mobx'
+import { makeAutoObservable, runInAction } from 'mobx'
+import type { Identity } from '../../core/identity-color.ts'
 import type { RepoSt } from './repo-st.ts'
 
+/** how long a picker rests before the preview draws its colours */
+export const PREVIEW_REST_MS = 150
+
 export class AdminSvc {
     /** the archive button was pressed: its confirmation shows in its place */
     confirming = false
+    /** the colours the preview keeps while a picker moves, so a drag draws a
+     *  few icons, not one per frame; null follows the repo's colours */
+    held: Identity | null = null
+    /** the repo has no png mark, or it would not draw: the app wears the default icon */
+    noIcon = false
+    private rest: ReturnType<typeof setTimeout> | null = null
 
     constructor(private st: RepoSt) {
-        makeAutoObservable<this, 'st'>(this, { st: false })
+        makeAutoObservable<this, 'st' | 'rest'>(this, { st: false, rest: false })
+    }
+
+    /** by key: the project list and the icon route know a repo by its
+     *  folder, and its config can name it otherwise */
+    get identity(): Identity {
+        return this.st.home.projects.identityOf(this.st.key)
+    }
+    /** one colour, shown at once and saved to repo.config.ts once it rests */
+    setColour(patch: Partial<Identity>): void {
+        this.held ??= this.identity
+        this.st.home.projects.setIdentity(this.st.key, patch)
+        if (this.rest != null) clearTimeout(this.rest)
+        this.rest = setTimeout(() => runInAction(() => { this.held = null }), PREVIEW_REST_MS)
+    }
+    get previewSrc(): string {
+        const id = this.held ?? this.identity
+        return `/api/projects/app-icon/${encodeURIComponent(this.st.key)}?light=${encodeURIComponent(id.colorLight)}&dark=${encodeURIComponent(id.colorDark)}`
+    }
+    previewFailed(): void {
+        this.noIcon = true
+    }
+    previewLoaded(): void {
+        this.noIcon = false
     }
 
     askArchive(): void {

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

@@ -1,5 +1,6 @@
 // THE ADMIN PAGE of a repo (`#page:admin`): what administers the repo rather
-// than works in it, one row per control, each with the one sentence that says
+// than works in it. Its identity first (the colours, and the app icon they
+// draw, core/app-icon.ts), then one row per control, each with the one sentence that says
 // what it does. State in admin-svc.ts. Only on the home: a hub of its own has
 // no machine to administer it.
 import { observer } from 'mobx-react-lite'
@@ -16,6 +17,36 @@ const Row = ({ title, says, children }: { title: string; says: string; children:
     </div>
 )
 
+/** the repo's two colours, and what they look like: its app icon and its name on both pages */
+const IdentityBox = observer(({ app }: { app: RepoSt }) => {
+    const a = app.admin
+    const id = a.identity
+    const name = app.name
+    return (
+        <div className="adbox adid">
+            <div className="adicon">
+                <img src={a.previewSrc} alt={`${name} app icon`} width={128} height={128} hidden={a.noIcon}
+                    onLoad={() => a.previewLoaded()} onError={() => a.previewFailed()} />
+                {a.noIcon ? <span className="dim">no png mark (.shipkit/identity/icon.png, public/logo.png or public/favicon.png): its app wears the default icon</span> : null}
+            </div>
+            <div className="adtext">
+                <b>identity</b>
+                <span className="dim">the repo's two colours, written to repo.config.ts as identity. The app icon sets the mark on the one it stands out on most, and each app redraws it at its next open.</span>
+                <label className="adpick">
+                    <input type="color" value={id.colorDark} onChange={(e) => a.setColour({ colorDark: e.currentTarget.value })} />
+                    <span className="adsample dark" style={{ color: id.colorDark }}>{name}</span>
+                    <span className="dim">on a dark page, colorDark {id.colorDark}</span>
+                </label>
+                <label className="adpick">
+                    <input type="color" value={id.colorLight} onChange={(e) => a.setColour({ colorLight: e.currentTarget.value })} />
+                    <span className="adsample light" style={{ color: id.colorLight }}>{name}</span>
+                    <span className="dim">on a light page, colorLight {id.colorLight}</span>
+                </label>
+            </div>
+        </div>
+    )
+})
+
 export const AdminPage = observer(({ app }: { app: RepoSt }) => {
     const a = app.admin
     const w = app.home.machine?.worker(app.key)
@@ -26,17 +57,20 @@ export const AdminPage = observer(({ app }: { app: RepoSt }) => {
                 <span className="tid">admin</span>
                 <h3 className="ctitle">{name}</h3>
             </div>
-            <Row title="reload the hub" says={`stops ${name}'s hub in the daemon and loads it again, its repo.config.ts read fresh and its processes started again. The daemon already does it on its own when repo.config.ts changes: this is for a hub that is stuck.${w == null ? '' : ` Its hub is ${w.status} now.`}`}>
-                <button className="ghost" onClick={() => void a.reload()}>reload</button>
-            </Row>
-            <Row title="keep active" says="an active repo runs the checks the plan holds for it and gets its red pings. It is active on its own while an agent works in it or VS Code has it open: this keeps it active without either.">
-                <label className="adflag"><input type="checkbox" checked={a.active} onChange={(e) => void a.setActive(e.currentTarget.checked)} />active</label>
-            </Row>
-            <Row title="archive" says="it leaves the project list for the archived page, and nothing runs there: no hub, no watch, no plan rows, no processes, no widgets. Written to repo.config.ts as archived: true, and undone from the archived page.">
-                {a.confirming
-                    ? <span className="adconfirm"><span>archive {name}?</span><button className="primary" onClick={() => a.archive()}>archive it</button><button className="ghost" onClick={() => a.cancel()}>cancel</button></span>
-                    : <button className="ghost" onClick={() => a.askArchive()}>archive</button>}
-            </Row>
+            <IdentityBox app={app} />
+            <div className="adbox">
+                <Row title="reload the hub" says={`stops ${name}'s hub in the daemon and loads it again, its repo.config.ts read fresh and its processes started again. The daemon already does it on its own when repo.config.ts changes: this is for a hub that is stuck.${w == null ? '' : ` Its hub is ${w.status} now.`}`}>
+                    <button className="ghost" onClick={() => void a.reload()}>reload</button>
+                </Row>
+                <Row title="keep active" says="an active repo runs the checks the plan holds for it and gets its red pings. It is active on its own while an agent works in it or VS Code has it open: this keeps it active without either.">
+                    <label className="adflag"><input type="checkbox" checked={a.active} onChange={(e) => void a.setActive(e.currentTarget.checked)} />active</label>
+                </Row>
+                <Row title="archive" says="it leaves the project list for the archived page, and nothing runs there: no hub, no watch, no plan rows, no processes, no widgets. Written to repo.config.ts as archived: true, and undone from the archived page.">
+                    {a.confirming
+                        ? <span className="adconfirm"><span>archive {name}?</span><button className="primary" onClick={() => a.archive()}>archive it</button><button className="ghost" onClick={() => a.cancel()}>cancel</button></span>
+                        : <button className="ghost" onClick={() => a.askArchive()}>archive</button>}
+                </Row>
+            </div>
         </div>
     )
 })

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

@@ -1,45 +1,42 @@
 // ONE GATE CHECK, on its own page, as ONE compact block: the id as a tag, the
 // title, the sentence it wrote about itself, the exact command it runs, then
 // one grid of facts, each a dim label and a short value whose explanation is
-// the row's `(?)`. No box holds a single field. Navigation is the tree on the
+// the row's `(?)`, then where it runs: one line per context. No box holds a single field. Navigation is the tree on the
 // left, so there is no back link.
 import { observer } from 'mobx-react-lite'
 import { useEffect, useRef } from 'react'
 import { CACHED } from '../../core/outcome-words.ts'
+import { cellMeaning, MATRIX_AXES, RUNS_LEGEND } from '../../core/runs-matrix.ts'
 import { durationTone, fmtMs } from './dur.ts'
 import { Help, TERMS } from './help.tsx'
 import type { RepoSt } from './repo-st.ts'
-import type { SlowSuite, CheckFacts, RecentRun, WhenAt } from './hub-types.ts'
+import type { SlowSuite, CheckFacts, RecentRun } from './hub-types.ts'
 import { renderMd, renderMdInline } from './md.ts'
 import { nextRun } from './next-run.ts'
 import { ProseHits } from './prose-hits-view.tsx'
 import { stampWords, TimeAgo, TimeAhead } from './time-ago.tsx'
-import { checkName, commandOf, docPath, editorHref, lastRun, rememberedFact, repoPath, whatFacts, WHEN_OPTION, type ShortPath } from './check-words.ts'
+import { checkName, commandOf, docPath, editorHref, lastRun, rememberedFact, repoPath, whatFacts, type ShortPath } from './check-words.ts'
 
 /** which declaration is answering, so the switch never looks like it wrote
  *  something it did not. The CHIP is the short one, its help is the sentence */
 const SOURCE_CHIP: Record<CheckFacts['whenSource'], string> = {
-    when: 'repo.config.ts',
+    off: 'repo.config.ts',
+    when: 'when (retired)',
+    ruleExempt: 'ruleExempt (retired)',
     'check-file': 'the check file',
-    ruleExempt: 'ruleExempt',
-    optIn: 'optIn',
-    'gate-export': 'gate = false',
     defaults: 'defaults',
-    default: 'default',
+    default: 'derived',
 }
 
 const SOURCE_WORD: Record<CheckFacts['whenSource'], string> = {
-    when: 'set in the `when` block of `repo.config.ts`, which this switch writes',
-    'check-file': 'declared by the check file itself, and the `when` block overrides it',
-    ruleExempt: 'from the older `ruleExempt`, which reads as off',
-    optIn: 'from the older `optIn` key, which reads as health',
-    'gate-export': 'from `export const gate = false` in its own file',
+    off: 'turned off in the `off` block of `repo.config.ts`, which this switch writes',
+    when: 'turned off by the retired `when` key, which `shipkit ci` ports to `off` (SK029)',
+    ruleExempt: 'turned off by the retired `ruleExempt` key, which `shipkit ci` ports to `off` (SK029)',
+    'check-file': 'declared by the check file itself: every context it runs in, no default',
     defaults: 'from the `defaults` block, which removes the floor slot entirely',
-    default: 'nobody declared where this check runs, so it takes the default',
+    default: 'a row with no file of its own: the code that derives it writes every context',
 }
 
-const WHEN_VALUES: WhenAt[] = ['always', 'release', 'health', 'off']
-
 const VERDICT_WORD: Record<'pass' | 'warn' | 'fail' | 'skip', string> = {
     pass: 'passed', warn: 'warned', fail: 'failed', skip: 'skipped',
 }
@@ -126,44 +123,67 @@ export const CommandLine = ({ app, u }: { app: RepoSt; u: CheckFacts }) => {
     )
 }
 
-// ── the switch ───────────────────────────────────────────────────────────
+// ── where it runs ────────────────────────────────────────────────────────
+
+/** every context, one line each: the value the check declared and what it
+ *  means in the legend's words. The cache closes it, the off switch ends it */
+const WhereItRuns = observer(({ app, u }: { app: RepoSt; u: CheckFacts }) => {
+    const r = u.runs
+    return (
+        <Section title="where it runs" help="every context a check declares, with no default. The when page of this repo shows every check at once, and `sk when` prints the same">
+            {r.off != null
+                ? <div className="wline">runs nowhere: {r.off}</div>
+                : <div className="cruns">
+                    {MATRIX_AXES.map((k) => {
+                        const c = r.cells[k]
+                        const a = RUNS_LEGEND.find((x) => x.axis === k)!
+                        return (
+                            <div key={k} className={`crun${c.on ? ' on' : ''}`}>
+                                <span className="ck" title={`${k}: ${a.context.replace(/`/g, '')}. From ${c.source}`}>{a.short}</span>
+                                <span className="crv">{c.on ? c.text : 'no'}</span>
+                                <span className="crm">{cellMeaning(k, c.text)}</span>
+                            </div>
+                        )
+                    })}
+                    <div className="crun cache">
+                        <span className="ck" title={`cache: how an answer is kept. ${r.cache}`}>cache</span>
+                        <span className="crv">{r.cache.split(/[\s:]/)[0]}</span>
+                        <span className="crm">{cellMeaning('cache', r.cache)}</span>
+                    </div>
+                </div>}
+            {r.derivedWhy == null ? null : <div className="note">no file declares this row: {r.derivedWhy}</div>}
+            <div className="cfacts"><OffSwitch app={app} u={u} /></div>
+        </Section>
+    )
+})
 
-/** RUN WHEN, one select named by effect. It writes `repo.config.ts` itself,
- *  through the managed block, and leaves the file dirty: a change of place is
- *  a change its owner reviews in a git client, never a commit made on their
- *  behalf. Choosing never asks for the reason before it writes. */
-const RunWhen = observer(({ app, u }: { app: RepoSt; u: CheckFacts }) => {
+// ── the off switch ───────────────────────────────────────────────────────
+
+/** the one thing this repo says about a check: that it is OFF here, with the
+ *  reason. It writes `repo.config.ts` through the managed block and leaves the
+ *  file dirty for its owner to review */
+const OffSwitch = observer(({ app, u }: { app: RepoSt; u: CheckFacts }) => {
     const s = app.checks
     const g = s.gate
-    const shown = s.whenShown(u)
     const reason = s.reasonFor(u.checkId)
+    const off = u.runs.off
     return (
-        <Row k="run when" help="where this check runs. Changing it writes repo.config.ts and leaves the file for you to commit">
+        <Row k="off in this repo" wide help="where this check runs is its own declaration; the one thing this repo says is that it is OFF here, with why. The switch writes the `off` block of repo.config.ts and leaves the file for you to commit">
             <span className="cwhen">
-                <select className="wsel" value={shown} disabled={s.gateBusy} onChange={(e) => s.chooseWhen(u.checkId, e.target.value as WhenAt)}>
-                    {WHEN_VALUES.map((v) => <option key={v} value={v}>{WHEN_OPTION[v]}</option>)}
-                </select>
-                <Help text={
-                    <span className="legend">
-                        {WHEN_VALUES.map((v) => <span key={v} className="lrow"><b>{WHEN_OPTION[v]}</b> ({v}): {TERMS[v]}</span>)}
-                    </span>
-                } />
+                {off != null ? <span className="tl red">off: {off}</span> : <span className="dim">runs where it declares</span>}
                 <span className="stchip">{SOURCE_CHIP[u.whenSource]}</span>
                 <MdHelp text={SOURCE_WORD[u.whenSource]} />
-                {u.whenSource === 'when'
-                    ? <button className="wclear" disabled={s.gateBusy} onClick={() => void s.clearWhen(u.checkId)}>drop the entry</button>
-                    : null}
+                <a href="#" onClick={(e) => { e.preventDefault(); app.showWhen() }}>what runs when</a>
             </span>
-            {shown === 'off'
-                ? <span className="cblock">
-                    <input className="wreason" placeholder="why it is off (required, and it rides in the config)"
-                        value={reason} onChange={(e) => s.setReason(u.checkId, e.target.value)} />
-                    {u.when === 'off' && u.whenReason != null ? <span className="note">reason today: {u.whenReason}</span> : null}
-                    <button disabled={s.gateBusy || reason.trim() === ''} onClick={() => void s.setWhen(u.checkId, 'off')}>
-                        {u.when === 'off' ? 'change the reason' : 'turn it off'}
-                    </button>
-                </span>
-                : null}
+            {off != null && u.whenSource === 'off'
+                ? <span className="cblock"><button disabled={s.gateBusy} onClick={() => void s.turnOn(u.checkId)}>turn it back on</button></span>
+                : off == null
+                    ? <span className="cblock">
+                        <input className="wreason" placeholder="why this repo turns it off (required, it rides in the config)"
+                            value={reason} onChange={(e) => s.setReason(u.checkId, e.target.value)} />
+                        <button disabled={s.gateBusy || reason.trim() === ''} onClick={() => void s.setOff(u.checkId)}>turn it off here</button>
+                    </span>
+                    : null}
             {g != null && g.state === 'stale'
                 ? <span className="cblock warnline">the managed block in {g.path} was hand edited: reconcile it, then the switch works again</span>
                 : null}
@@ -321,7 +341,6 @@ export const CheckCard = observer(({ app, id }: { app: RepoSt; id: string }) =>
                 {whatFacts(u).map((f) => (
                     <Row key={f.k} k={f.k} help={f.help}>{f.tone == null ? f.v : <span className={`tl ${f.tone}`}>{f.v}</span>}</Row>
                 ))}
-                <RunWhen app={app} u={u} />
                 <Remembered u={u} />
                 {/* the help never depends on the second, so it reads the wall
                     clock and the row does not repaint on every tick */}
@@ -338,6 +357,7 @@ export const CheckCard = observer(({ app, id }: { app: RepoSt; id: string }) =>
                 {u.group == null ? null : <Row k="group" help="a label several checks share, so `--skip <group>` parks all of them at once">{u.group}</Row>}
                 <Timings u={u} />
             </div>
+            <WhereItRuns app={app} u={u} />
             {u.build && u.checkId === 'test' ? <SlowSuites app={app} /> : null}
             {u.checkId === 'SK014' ? <ProseHits app={app} /> : null}
             <LastOutput app={app} lines={u.lastLines} />

package/src/serve/hub-app/check-words.ts

@@ -49,17 +49,7 @@ export function rememberedFact(u: CachePop): RememberedFact {
     const cadence = CADENCE[u.when ?? 'always']
     if (u.never != null)
         return { v: 'never', inputs: [], help: `never cached, so it runs ${cadence}${u.never === '' ? '' : `: ${u.never}`}` }
-    return { v: 'never', inputs: [], help: `nothing declared, so it runs ${cadence}. \`inputs\`, \`ttl\` or \`never\` in the check says otherwise` }
-}
-
-/** the four places a check runs, named by what they do. The config keeps its
- *  own words (`always`, `release`, `health`, `off`), and these are only what
- *  the select under `run when` shows */
-export const WHEN_OPTION: Record<WhenAt, string> = {
-    always: 'always',
-    release: 'before a release',
-    health: 'health pass only',
-    off: 'never',
+    return { v: 'never', inputs: [], help: `nothing keys it, so it runs ${cadence}. A check file keys it with \`cache: { by: 'files' | 'reads' | 'ttl' | 'fact' }\`` }
 }
 
 /** what a check IS: three FACTS, each a short value a reader scans, with the