rvlib-shipkit 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,71 @@
+## 1.5.0
+
+- **Every check declares where it runs and how it caches, with no default.** A check file carries `runs` (`onPreCommit`, `onCi`, `onFull`, `onRelease`, `onHealth`, `onSave`, `onClock`), `cache` (`files`, `reads`, `ttl`, `fact` or `never`, each with its one parameter), `fix` (`none`, `ci` or `manual`, the function itself is now `repair`) and `applies`. `check()` refuses a missing key, a retired key (`when`, `inputs`, `ttl`, `never`, `every`, `cron`, `whenInactive`, `planOff`, `cacheKey`) and the combinations that contradict each other. The gate, the fix pass, the release preflight and the planner read the declared axes; a release never applies a check repair. Every built-in carries its own placement: SK024, SK017 and SK028 run in the health pass only, and SK005, SK006, SK011, SK014, SK016 and SK022 are out of the quick gate. A check file that does not load is one failing row instead of a dead inventory.
+
+- **SK029 ports a check file still in the retired shape.** Its repair writes `runs`, `cache`, `fix` and `applies` with the values the old keys resolved to, so the check runs where it ran, and the fix pass of `sk ci` applies it: a repo is carried across by its first gate.
+
+- **A repo only turns a check off.** `off: { <id>: '<why>' }` in `repo.config.ts` replaces the `when` map; `defineRepo` refuses every `when` word but `off:<why>`, and SK029 ports that and `ruleExempt` into `off`. The hub's switch on a check page writes it.
+
+- **The pre-commit hook runs the checks declaring `onPreCommit`**, in process on the working tree, under a budget of at most 100ms each; a failure refuses the commit. `sk hooks list` names them. The whole hook warns past 1s.
+
+- **`sk when` and the when page show what runs when**: the legend of every context and value, then every check on every context. `--only onCi` keeps what the quick gate runs.
+
+- **The hub tree has four sections where it had checks.** contracts (⌥K), shipkit checks (⌥S), repo checks (⌥C) and secrets (⌥X) are top rows, each with its own red count, and their rows sit straight under them, one indent less. shipkit checks and repo checks open the checks table showing only their own checks (`#page:checks:shipkit`, `#page:checks:repo`).
+
+- **A check page lists where the check runs, one line per context.** Commit, ci, full, release, health, save, clock, fix and cache each show the declared value and what it means, in the words of the `sk when` legend. A context that does not run the check stays dim. The switch that turns the check off in this repo, with its reason, sits under that list.
+
+- **The tree drops the gray ci, release, health word on a check row.** A check declares seven contexts now, which one word could not say. The row's tooltip lists every context that runs it (`runs on ci · full · release · health · save moved`), and the label gets the width back. A check that no context runs reads off.
+
+- **A link button copies the page's url.** At the bottom right of the dock bar, it shows the url on hover and copies it on click. The app window has no url bar.
+
+- **Fix: the repo tree's scrollbar is a thin bar.** In the macOS app it drew a wide dark band beside the tree; it is now a 6px thumb on a transparent track, and the rows sit closer to it.
+
+- **The tree gives its width back to the labels.** A row's duration is a small clock now, tinted by the same tone table, with the figure in its tooltip. The indent per level and the space around the chevrons are a little smaller.
+
+- **The command index is lean.** Every command's `description` is one short line (at most 100 characters, a test holds it), and the long text moved to `details`, which `--help` still prints. `shipkit commands` renders each signature with its flags inline, but no longer a line per flag, and every example uses `sk`, which is also the name `--help` shows. The generated index went from 33 KB to 17 KB.
+
+- **`sk`, the short name.** The package ships a second bin, `sk`, the same cli as `shipkit`.
+
+- **The fix pass is skipped over a tree it already left clean.** When HEAD, every uncommitted file, the toolchain and the fixer commands are the same as at the last pass that rewrote nothing, the formatter and import fixers do not run again. That was the whole wait before the first line of `shipkit ci`. CI never skips.
+
+- **Every gate line says where its answer came from.** A check that ran ends its first line with `(ran 6.4s)`, one replayed from the cache with `(cached, 3h old, 6.4s saved)`, and a world check with `(ran 40ms, kept 1h more)` or `(cached, 2m old, kept 23h more)`. Before, a rule check that ran said nothing and a cached one never said how old its answer was.
+
+- **Fix: a repo that `bun link`s a package replays from the cache.** A package linked outside the repo made every check "never cached", so a repo linking its toolchain re-ran everything on every gate. The link target is now keyed by its content (each file's path, size and bytes, symlinks followed, its own installs), so an edit there still moves the key and an untouched one replays. A linked tree that cannot be read keys nothing.
+
+- **`shipkit gp start|stop|restart <id>`.** The overview's switches for a global process, from a terminal: pm takes the switch, and the command follows pm's status until the probe settles it. It exits 0 once the process is up (down for stop), and 1 with its note and its last log lines when it crashed or stayed down.
+
+- **Widgets are asked for only by a visible overview.** The page polled `/api/home/widgets.json` from every page, hidden tabs and app windows included, so the daemon rendered every widget around the clock. A widget that samples another machine over ssh kept sampling it all day. A repo page or a hidden tab now asks for none, and the daemon stops rendering 30 s after the last read.
+
+- **Removed: `serve.processes`.** A hub no longer supervises processes of its own: declare each one as a global process in a `<name>.shipkit.ts` file (`export default globalProcess({...})`), which pm runs. `defineRepo` refuses the old key and says so. The hub routes `/api/processes.json` and `/api/processes/act`, the header switches and the `process logs` retention store go with it.
+
+- **A repo's plan, git and reflections are sections of its tree.** `plan` (⌥N) lists what the machine runs there and when, with run now. `git` (⌥G) shows the branch against its upstream, what is not committed and the commits of the week, with VS Code and Fork, from a new daemon route `/api/home/git.json?repo=`. `reflections` (⌥F) left the checks section for one of their own, one row each.
+
+- **A repo's global processes are a section of its tree.** `processes` (⌥P) sits after `runs`, one row per process the repo declares, coloured by its state. The section opens a page with one card per process (its actions, its description as markdown, its log), and a row opens its own card, lit. A new resource kind, `process`, and a new address, `#page:processes[:<id>]`.
+
+- **A repo page is not a box, each group is one.** A check, test, admin, runs or item page sits on the page background, and each group it holds (the facts, a titled section, the command, the admin rows, the runs list) is one lighter box.
+
+- **A process menu shows its description as markdown, on the right.** The menu a process chip opens is two panels: its actions on the left, its `description` rendered as markdown on the right with its note and last log line, selectable, so a dev login written there is one click away. A process with nothing to say draws the actions alone.
+
+- **Fix: a search reads every row, and a filtered tree says what it hides.** With the severity group on `needs` or `red`, a repo with few of them showed empty sections with no chevron and a search that found nothing. A search now ignores the group (`TreeSvc.visible`), and while the group hides rows a line under the tree counts them and shows all on a click (`TreeSvc.hidden`).
+
+- **A process chip opens a menu instead of starting or stopping.** A click on a global process chip in the top bar opens its menu: start or stop, restart, open in a browser tab, in Chrome or as an app, its declared actions and take over. The chips sit right after the repo's name, and the spinner and `check…` sit at the right end before the editor icons.
+
+- **The machine not answering is said once.** When the daemon, pm or the web does not answer, one card under the strip says so, with what hangs, what runs it and that the page comes back by itself; the daemon and pm down together share that card. The project list, the dock, a repo's trouble card and every repo pane keep what they last read and add no error line of their own. The bottom right toast is gone. `reach` and `ownTrouble` in `reach.ts` are the one reading of the web's tagged 502 and of a fetch with no answer. A route that fails while the daemon answers still shows its own error. The page stays drawn meanwhile: a repo keeps its last screen, since its hub's state is unknown rather than down, and the overview draws what it last had; a wait panel shows only when nothing was ever read.
+
+- **Fix: pm kills a child that stopped answering, and its agent is never disk throttled.** A child whose pid lives but has not answered its probe for 90 s is hung: pm writes a WARN line to `pm.log`, sends SIGTERM then SIGKILL, and starts it again through the crash backoff (`hangMs` and `say` on a `ProcSpec`, `CHILD_HANG_MS`). A daemon had sat `starting` for an hour with its port open. The LaunchAgent now carries `ProcessType` Interactive: with none, launchd throttles the disk reads of pm and of every child it starts, and under a busy disk the daemon's boot reads of its sqlite store took minutes. Run `shipkit pm install` once to rewrite an installed agent. That install no longer strands the machine without pm: `launchctl bootout` returns before launchd lets go of the label, and the bootstrap right after it could fail with exit 5 once the old agent was gone. It is retried for 5 s (`BOOTSTRAP_TRIES`), and a final failure says pm is not loaded.
+
+- **A readme section, and switching repo keeps the section open.** `readme` is the first row of a repo's left pane (⌥E, `#page:readme`). Selecting another repo opens the section the one you left showed; a repo already on a page of that section keeps it, and one without that section opens its README. `sectionOfSel` and `openSection` in `repo-sections.ts` light the rows and drive the switch, and `HashSel` gains `{ t: 'readme' }`.
+
+- **A repo page's left pane is one tree whose top rows are its sections.** checks, runs, asks, tests, media, wikis and admin keep their icon, count, ⌥ key and lit state; a click opens the section's page, and only the chevron, the right arrow or a search unfolds it. Under them: the check origins with reflections, secrets and contracts under checks, one row per ask with the `done` archive, one row per test file, the assets with the workflow and post groups under media, one row per wiki. `KIND_SECTION` gives every resource kind one home, and a section the repo does not draw still gets a row when a resource lives in it (`buildTree` replaces `buildPathTree` and `buildTypeTree`). The by path and by type tabs, the `(?)` legend and the total are gone: each kind glyph names its kind in its tooltip, and the filter matches paths. The severity group sits beside the filter and narrows the section counts too. A search unfolds every section with a match and hides the rest; clearing it restores the folds. The planning line moved to the top of the checks page. `repo-sections.tsx` is `repo-sections.ts`.
+
+- **The top bar carries no trouble text and no run buttons.** The hub's trouble and the machine's (a crashed child of pm, a crashed global process, a failed poll) are cards floating at the top right, just under the bar, full text, nothing drawn while all is well (`FloatCards`). The running command is a spinner with its words in a tooltip that opens at once, and nothing shows while idle. The health pass and the gate sit behind one small `check…` button, in a popover (`Pop` in floating.tsx) that Escape or a click outside closes. The standalone hub header gets the same.
+
+- **The strip over a repo starts its global processes.** One chip per process the shown repo declares in its `.shipkit.ts` files: its dot and label, a click starts or stops it, and `↗` opens its url while it runs. pm runs them, so the chips show whether the repo's hub answers or not.
+
+- **Fix: SK017 removes a `👁  TSC` watcher that runs `tsgo`.** The rule matched only a `tsc` binary, so a repo whose watcher had moved to tsgo kept it beside the gate's typecheck. A tsgo task under another label is still left alone. A wrapper that started only the TSC task goes with it, since it would open with the folder and start nothing.
+
+- **Fix: a semver pin under a `bun link` moves when a release ships.** SK005 and `shipkit fleet` read the linked source, always the newest, so a repo pinned at 1.3.0 read current and a fresh clone kept installing 1.3.0. A pinned dep whose node_modules entry is a symlink is now judged by the pin's floor (`pinFloor`, `isLinkedInstall`). Behind, SK005 moves the pin through its guarded update, keeps its style, runs `bun link <name>` after it and FAILs when the link does not come back. The fleet row names it `pin 1.3.0 → 1.4.0 (linked, stale pin)`, `FleetDep` gains `linkedInstall` and `at`, and `fleet --update` reads the move off the pin (`judgedVersion`). A `link:` spec is judged as before.
+
 ## 1.4.0
 
 - **Fix: `shipkit gui` wears the house mark from any directory.** The app took its icon from cwd, so a run outside every house repo rebuilt `Shipkit.app` with no icon. The house now comes from cwd, else from the installed pm agent's `WorkingDirectory` (`installedHouseRoot`, `guiRoot`), and never from cwd itself.

package/README.md

@@ -18,7 +18,7 @@ export default defineRepo({
 })
 ```
 
-Everything the gate runs beyond the floor is a CHECK, and a check needs no config at all: drop a `<name>.check.ts` file anywhere and `shipkit ci`, `shipkit check`, `shipkit checks` and the hub discover it.
+Everything the gate runs beyond the floor is a CHECK, and a check needs no config at all: drop a `<name>.check.ts` file anywhere and `sk ci`, `sk check`, `sk checks` and the hub discover it.
 
 ```ts
 // e2e.check.ts
@@ -35,46 +35,46 @@ export default check({
 ## CLI
 
 ```
-shipkit ci        commit gate: floor (lint/typecheck/test/imports/cycles —
+sk ci        commit gate: floor (lint/typecheck/test/imports/cycles —
                   scripts win, imports/cycles/typecheck fill from bundled
                   tools with zero config, gaps print visibly) + contracts
                   + your checks, parallel DAG; refreshes STATUS.md
                   [--bail --skip g --only id --json]
-shipkit contracts release-contract fulfillness alone       [--venue v --json]
-shipkit check     periodic health: the built-in checks + every *.check.ts in
+sk contracts release-contract fulfillness alone       [--venue v --json]
+sk check     periodic health: the built-in checks + every *.check.ts in
                   the repo, auto-discovered + TTL-cached
                   [--json --fresh --frozen --fix [SK### …]]
                   --fix applies check autofixes then re-runs them; --frozen =
                   self-maintaining checks (rvlib self-update) report only
-shipkit checks    the inventory: every check, where it runs, blocks or warns,
+sk checks    the inventory: every check, where it runs, blocks or warns,
                   and how it caches. --fixable = what repairs itself,
                   with its owning doc                     [--json --md --out]
-shipkit tui       live dashboard: build steps + every other check + panels
+sk tui       live dashboard: build steps + every other check + panels
                   the repo injects via repo.config tui.panels
-shipkit asks      human action queue: list · ask "<title>" · asks check (auto-close)
-shipkit needs     everything blocked on a human, red/yellow by collection
+sk asks      human action queue: list · ask "<title>" · asks check (auto-close)
+sk needs     everything blocked on a human, red/yellow by collection
                   report-only, exit 0 always                            [--json]
-shipkit wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
-shipkit mv        rename an md page + its sibling dir, sweeping every ref
-shipkit assets    serve|fill|add|gen|identity|check — the asset atelier
+sk wiki      serve|lint — live md link-graph + orphan/dangling-ref lint
+sk mv        rename an md page + its sibling dir, sweeping every ref
+sk assets    serve|fill|add|gen|identity|check — the asset atelier
                   (declare kinds in .shipkit/assets/kit.ts, roll, curate, ship)
-shipkit pb        collection <name> — scaffold a PocketBase collection's UI
+sk pb        collection <name> — scaffold a PocketBase collection's UI
                   folder (columns/card/grid/form/index) from the app's
                   generated pb types, create-only          [--dry-run]
-shipkit smoke     browser pass over a DEPLOYED web app, read only: login
+sk smoke     browser pass over a DEPLOYED web app, read only: login
                   through the app's own form, every route in repo.config
                   `smoke`, screenshots, console/network problems, the host
                   quota headers, a detail page per `open` link. Exit code =
                   failed routes. Needs playwright in the repo
                                           [--base <url> --routes /a,/b]
-shipkit serve     the repo's ONE server: hub page, wikis, studio, status
-shipkit reflect   your prompts across every Claude Code session of a repo:
+sk serve     the repo's ONE server: hub page, wikis, studio, status
+sk reflect   your prompts across every Claude Code session of a repo:
                   all config roots, queued-mid-run ones included, harness
                   noise out, chronological md corpus for a retrospective
                                          [repo…] [--short --out <dir> --json]
-shipkit init      scaffold config + scripts, print the resolved floor
+sk init      scaffold config + scripts, print the resolved floor
                   [--bin <cli.ts path> for in-repo-source consumers]
-shipkit start     ensure <root>/<name> + its CLAUDE.md include; prints the dir
+sk start     ensure <root>/<name> + its CLAUDE.md include; prints the dir
 ```
 
 Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with indented `fix:` pointers — exit 0/1. Greppable by humans, parseable by agents, `--json` where structure helps.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
@@ -11,7 +11,8 @@
         "CHANGELOG.md"
     ],
     "bin": {
-        "shipkit": "./src/cli.ts"
+        "shipkit": "./src/cli.ts",
+        "sk": "./src/cli.ts"
     },
     "exports": {
         ".": "./src/shipkit.ts",

package/src/check.ts

@@ -14,14 +14,14 @@
 //   `cmd`  argv, a subprocess, exit code is truth
 //
 // What a check declares about ITSELF is what every surface reads: `blocking`
-// (can it stop you), how it is remembered (`ttl` or `never`, else a `run`
-// check is keyed on what it read and a `cmd` check on its `inputs`), `when`
-// (where it runs), `deps` (what must pass first). The file's own path joins
-// its cache key automatically, so nothing declares its own code.
+// (can it stop you), `runs` (every context it runs in), `cache` (how its
+// answer is kept), `fix` (which command applies its repair), `applies` (does
+// this repo give it work), `deps` (what must pass first). Every one of them is
+// explicit, with no default (core/runs.ts). The file's own path joins its
+// cache key automatically, so nothing declares its own code.
 import type { CheckCtx } from './core/check-ctx.ts'
-import { parseWhen } from './core/when.ts'
-import { planDeclProblem, type Every, type WhenInactiveDecl } from './plan/cadence.ts'
-import { FOREVER, parseDuration, type Line } from './core/wire.ts'
+import { cacheProblem, combinationProblem, runsProblem, type Applies, type CacheDecl, type FixWhen, type Runs } from './core/runs.ts'
+import { type Line } from './core/wire.ts'
 import type { RepoConfig } from './repo-config.ts'
 
 export { defineScan, mdPages, packageJson, type MdPage, type PackageJson, type Scan } from './scan.ts'
@@ -77,7 +77,7 @@ export type CheckDef = {
      *  gate asks "is my change good" and builds, `shipkit check` asks "is
      *  this repo healthy" and reports, and a tool chain has no business in
      *  the second question. A floor slot derives it, a file declares it, and
-     *  it takes the 600s ceiling rather than the 120s one. `when` stays about
+     *  it takes the 600s ceiling rather than the 120s one. its `runs` say
      *  TIME (always, release, health, off). A build step on `health` is an
      *  opt in one: the gate parks it and `shipkit ci --with <id>` runs it. */
     build?: boolean
@@ -85,74 +85,34 @@ export type CheckDef = {
      *  so a check naming none is a root of it, and a dep doubles as the race
      *  guard between two checks that touch one file. */
     deps?: string[]
-    /** WHERE it runs: `always`, `release`, `health`, `off:<reason>`. The
-     *  repo's `when: {}` map wins over it, so a config can move a check the
-     *  repo does not own (core/when.ts owns the vocabulary). */
-    when?: string
-    /** CONTENT population: the repo-relative paths this check reads, so a
-     *  cached answer is honest while they do not move. For a `cmd` check,
-     *  whose subprocess reads what it likes. A `run` check that declares none
-     *  of `inputs`, `ttl` and `never` is keyed on what it READ through `c`
-     *  instead, the `reads` population (ledger/git-key.ts). A `cmd` check
-     *  that declares none runs every time, which costs speed and never
-     *  correctness. At most one of the three. */
-    inputs?: string[]
-    /** WORLD population: nothing on disk describes the answer, so a clean
-     *  pass keeps for this long, as in '24h'. `'forever'` for a DECIDED fact
-     *  (a repo's visibility, an account that exists): a clean answer never
-     *  expires, it is keyed on the declared value alone (`cacheKey`), and the
-     *  plan runs it only while no answer exists for that key. */
-    ttl?: string
-    /** a DECIDED never-cacheable, with the reason. Says somebody looked and
-     *  no key can describe this, which takes it off the burn-down list. */
-    never?: string
+    /** WHERE IT RUNS, every context explicit, no default (core/runs.ts owns
+     *  the meaning of each key and each value). A repo moves a check it does
+     *  not own OFF with `off` in repo.config.ts, never elsewhere. */
+    runs: Runs
+    /** HOW ITS ANSWER IS KEPT, one variant, every parameter explicit:
+     *  `files` (keyed on these paths), `reads` (keyed on what the body read),
+     *  `ttl` (a world answer that keeps a span), `fact` (a decided value, once
+     *  per key), `never` (with the reason). The file's own path joins every
+     *  key automatically, so nothing declares its own code. */
+    cache: CacheDecl
+    /** which command applies `repair`: `'none'` (no repair), `'ci'` (the
+     *  gate's fix pass and `shipkit check --fix`), `'manual'` (only
+     *  `shipkit check --fix <id>`) */
+    fix: FixWhen
+    /** whether this repo gives the check anything to do: `'always'`, or a
+     *  pure function of { root, config } returning the reason it does not
+     *  (the row is then n/a in every context), or null */
+    applies: Applies
     /** it REWRITES the repo while it runs (updates a dependency, untracks a
      *  file) unless the run is frozen, so a frozen run asks it a different
      *  question: only a check declaring this carries `frozen` in its cache
-     *  key, and every other check shares one answer between a frozen run and
-     *  a normal one. Declared, never guessed from the body. */
+     *  key. Declared, never guessed from the body. */
     writes?: boolean
-    /** WHEN the planner runs it on its own, beside the save that moved what
-     *  it reads: a span since its last run (`'24h'`), a range (`['10h',
-     *  '12h']`, each repo and check on a stable point inside it, so checks
-     *  spread out), a cron expression (`'0 9 * * 1'`), `'once'` (only while
-     *  no answer exists: what `ttl: 'forever'` reads as), or null for on
-     *  change only. Or a PURE function of its last result (`status`, `at`, `streak`
-     *  of that same status) and whether the repo is active, returning any of
-     *  those: `(last) => (last?.status === 'fail' ? '1h' : '7d')`. A lambda
-     *  that throws is an error row on the planned page, and the check runs on
-     *  change only. Absent: its `ttl`, else a build step or a check keyed on
-     *  its files waits for a save. A repo check nothing can key runs about
-     *  once a day until it declares one, and a built-in never may: `shipkit
-     *  keys --burn-down` names both. */
-    every?: Every
-    /** a time of day or week for the rare check that needs one, as five cron
-     *  fields in local time (`'0 9 * * 1'`, Mondays at 9). Never with `every`. */
-    cron?: string
-    /** what a due check does while its repo is inactive (no agent session in
-     *  it, VS Code does not have it open, it is not flagged active): `'wait'`
-     *  turns it late and runs it once the repo is active again, `'run'` runs
-     *  it on time anyway (a credential probe, an api key that must keep
-     *  working). A pure function of the last result may choose. Default
-     *  `'wait'`. */
-    whenInactive?: WhenInactiveDecl
-    /** why this repo gives the check nothing to do on a clock, or null: the
-     *  plan leaves it out there (no row, no timer), and a gate or a health
-     *  pass still runs it. Read at every reload of the repo's checks, so a
-     *  file that gives it work (an ask with a probe, a release unit) plans it
-     *  again. Cheap and pure over the repo's files and config */
-    planOff?: (env: CheckEnv) => string | null
-    /** cache-identity contribution for a `ttl` check whose verdict depends on
-     *  config: a changed key busts the answer instantly instead of serving
-     *  a stale cached assertion for the rest of the TTL. */
-    cacheKey?: (env: CheckEnv) => string
-    /** idempotent auto-repair, never interactive. `shipkit check --fix <id>`
-     *  applies it, then re-runs the check. It gets the same `c` as the body,
-     *  writes with `c.write` and `c.remove`, and is never cached. An `fs`
-     *  import in the check file would keep an undeclared body off its reads
-     *  (core/raw-access.ts). A repair that needs
-     *  judgement stays a FAIL with a pointer. */
-    fix?: (c: CheckCtx) => FixResult | Promise<FixResult>
+    /** idempotent auto-repair, never interactive, required when `fix` is not
+     *  `'none'`. It gets the same `c` as the body, writes with `c.write` and
+     *  `c.remove`, and is never cached. A repair that needs judgement stays a
+     *  FAIL with a pointer. */
+    repair?: (c: CheckCtx) => FixResult | Promise<FixResult>
     /** wall clock ceiling in ms. A `cmd` check is killed with its whole
      *  process tree at the ceiling. */
     timeoutMs?: number
@@ -160,7 +120,7 @@ export type CheckDef = {
      *  passes over it prints a WARN and reads yellow, and never blocks.
      *  Judged on the wall time of a run that measured, at the quick tier.
      *  Default 2000 for an in process body, 10000 for a build step, a `cmd`
-     *  or a world probe (one that declares `ttl` or `never`, core/budget.ts).
+     *  or a world probe (cache `ttl`, `fact` or `never`, core/budget.ts).
      *  The repo's `budgets` wins over it. */
     budgetMs?: number
     /** a label several checks share, so `--skip <group>` parks all of them
@@ -198,6 +158,19 @@ export function describeFirst(...candidates: (string | null | undefined)[]): str
     throw new Error(`no description candidate passes the shape: ${candidates.map((d) => JSON.stringify(d)).join(', ')}`)
 }
 
+/** the keys the explicit declaration replaced, and what replaces each */
+const RETIRED_KEYS: Record<string, string> = {
+    when: 'runs (every context explicit)',
+    every: 'runs.onClock { every, inactive }',
+    cron: 'runs.onClock { every: <cron>, inactive }',
+    whenInactive: 'runs.onClock.inactive',
+    planOff: 'applies',
+    inputs: "cache { by: 'files', inputs, key }",
+    ttl: "cache { by: 'ttl', span, key } or { by: 'fact', key }",
+    never: "cache { by: 'never', why }",
+    cacheKey: 'cache.key',
+}
+
 /** THE way a check file declares itself. It validates the shape at import
  *  time, so a malformed check dies when discovery loads it and never mid
  *  gate. The id, the title and the owner are filled in by discovery, which
@@ -208,20 +181,21 @@ export function check(d: CheckDef): CheckDef {
     const bad = descriptionProblem(d.description)
     if (bad != null) throw new Error(`check${name}: ${bad}`)
     if (typeof d.blocking !== 'boolean')
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: blocking is required — true (about this repo, it stops you) or false (about the world, it warns)`)
+        throw new Error(`check${name}: blocking is required — true (about this repo, it stops you) or false (about the world, it warns)`)
     if (has('run') === has('cmd'))
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: declare exactly one body, \`run\` (in process) or \`cmd\` (argv)`)
-    const populations = (['inputs', 'ttl', 'never'] as const).filter((k) => has(k))
-    if (populations.length > 1)
-        throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: ${populations.join(' and ')} contradict each other — a check reads files, or the world, or nothing can describe it`)
-    if (d.ttl != null && d.ttl !== FOREVER)
-        try { parseDuration(d.ttl) } catch { throw new Error(`check${name}: ttl '${d.ttl}' is neither a span ('7d') nor 'forever'`) }
-    const planBad = planDeclProblem({ every: d.every, cron: d.cron, whenInactive: d.whenInactive })
-    if (planBad != null) throw new Error(`check${name}: ${planBad}`)
-    if (d.when != null) {
-        const w = parseWhen(d.when)
-        if (typeof w === 'string') throw new Error(`check${d.id == null ? '' : ` ${d.id}`}: when ${w}`)
-    }
+        throw new Error(`check${name}: declare exactly one body, \`run\` (in process) or \`cmd\` (argv)`)
+    const raw = d as unknown as Record<string, unknown>
+    const retired = Object.keys(RETIRED_KEYS).filter((k) => raw[k] !== undefined)
+    if (retired.length > 0) throw new Error(`check${name}: ${retired.map((k) => `\`${k}\` is retired, declare ${RETIRED_KEYS[k]}`).join('; ')} (build/shipkit/runs.md)`)
+    if (typeof raw.fix === 'function') throw new Error(`check${name}: \`fix\` is now the word 'none' | 'ci' | 'manual', and the function is \`repair\` (build/shipkit/runs.md)`)
+    const runs = runsProblem(d.runs)
+    if (runs != null) throw new Error(`check${name}: ${runs}`)
+    const cache = cacheProblem(d.cache)
+    if (cache != null) throw new Error(`check${name}: ${cache}`)
+    if (d.applies !== 'always' && typeof d.applies !== 'function')
+        throw new Error(`check${name}: applies is required: 'always', or a function of { root, config } returning why this repo gives it nothing to do, or null`)
+    const whole = combinationProblem({ runs: d.runs, cache: d.cache, fix: d.fix, repair: d.repair, build: d.build === true, body: has('run') ? 'run' : 'cmd', blocking: d.blocking })
+    if (whole != null) throw new Error(`check${name}: ${whole}`)
     return d
 }
 
@@ -233,7 +207,7 @@ export function check(d: CheckDef): CheckDef {
 
 export type TaskDef = {
     /** the name every surface uses: the gate line, `--only`, `--skip`, a
-     *  `deps` entry, a `when` key and the ledger row. Unique in the repo. */
+     *  `deps` entry, an `off` key and the ledger row. Unique in the repo. */
     id: string
     /** one line stating what must be true (the shape: descriptionProblem).
      *  A floor slot and a unit test check get theirs from the
@@ -255,7 +229,7 @@ export type TaskDef = {
     /** a label several tasks share, so `--skip <group>` parks all of them at
      *  once (a local bench, a slow integration tier). */
     group?: string
-    /** DEPRECATED, read into `when` as `health`: out of the gate until
+    /** DEPRECATED, read as every gate axis false: out of the gate until
      *  `--with <id>` names it. */
     optIn?: boolean
     /** wall clock ceiling in ms, default 600000 for a build step. One that
@@ -333,13 +307,12 @@ export type Rule = {
 
 // ── running a body, and what every line it prints carries ────────────────
 
-/** the config part of a check's cache identity. Where it RUNS is part of it:
- *  moving one off the gate, or editing the reason it is off, has to ask the
- *  question again rather than serve the cached answer from before the move. */
-export function checkCacheExtra(u: { id: string; cacheKey?: (env: CheckEnv) => string }, env: CheckEnv, at: { at: string; reason: string | null; source: string }): string | undefined {
-    const key = u.cacheKey?.(env)
-    if (at.source === 'default') return key
-    return at.at === 'off' ? `${key ?? ''}|exempt:${at.reason ?? ''}` : `${key ?? ''}|when:${at.at}`
+/** the config part of a check's cache identity: its declared key, and the
+ *  reason it is off. Turning a check off, or editing why, asks the question
+ *  again rather than serving the answer from before. Where it runs is not
+ *  part of it: the answer to one question does not depend on who asks. */
+export function checkCacheExtra(key: string | undefined, off: string | null): string | undefined {
+    return off == null ? key : `${key ?? ''}|exempt:${off}`
 }
 
 /** THE one way to run an in-process body (the check suite and the `--fix`

package/src/checks/SK001-package-json-shape.check.ts

@@ -5,7 +5,7 @@
 // what it read: package.json, the probes below, the test file listing, and
 // whatever the floor resolution read.
 //
-// It also enforces the package.json half of ONE WAY IN (build/shipkit.md):
+// It also enforces the package.json half of ONE WAY IN (build/shipkit/one-way-in.md):
 // `test`, `lint` and `typecheck` ROUTE to `shipkit ci --only <id>` and the
 // tool body they used to hold sits at `<id>:raw`. That is what makes a cache
 // worth having: `bun run test` is the reflex, and the reflex has to land in
@@ -197,12 +197,16 @@ export const packageJsonShape = check({
     title: 'package.json',
     description: 'package.json routes lint, typecheck and test through the gate',
     owner: OWNER,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: (c) => evaluatePackageJson(c),
     // mechanical repairs only: field flips + scripts whose canonical body the
     // vocabulary page states. Bodies it does NOT state (assets, comfy:up) are
     // named in the summary, never invented. rvlib-* roots untouched — their
     // license/private are publish decisions.
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         const raw = c.read('package.json')
         if (raw == null) return { changed: false, summary: 'no package.json — nothing to fix' }
         if (rootPublishesNpm(c.config)) return { changed: false, summary: 'published to npm: its package.json is its public contract, never rewritten' }

package/src/checks/SK002-contracts-fulfillness.check.ts

@@ -16,6 +16,10 @@ export const contractsFulfillness = check({
     owner: 'meta/contracts.md',
     // keyed on what the contracts read: each artifact, each detector, and each
     // folder a glob walked through `c.entries`, a gitignored one included
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: async (c) => {
         applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
     },

package/src/checks/SK003-claude-md-shape.check.ts

@@ -20,6 +20,10 @@ export const claudeMdShape = check({
     owner: 'meta/agent-folder.md',
     // keyed on what it reads: CLAUDE.md and whether agent/index.md exists. The
     // gitignore probe runs git, so an answer that took it is never stored
+    runs: { onPreCommit: { budgetMs: 40 }, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         const hasAgent = c.exists('agent/index.md')
         const claude = c.read('CLAUDE.md')
@@ -53,7 +57,7 @@ export const claudeMdShape = check({
     // CLAUDE.md would lint green with the base include forever missing,
     // trading a loud FAIL for a permanent silent gap. Creation and prose
     // relocation stay human/machine-local (`shipkit start --include`).
-    fix: (c): FixResult => {
+    repair: (c): FixResult => {
         if (!c.exists('agent/index.md')) return { changed: false, summary: 'no agent/index.md — nothing mechanical to fix' }
         const cur = c.read('CLAUDE.md')
         if (cur == null) return { changed: false, summary: 'CLAUDE.md missing — creation needs the base include (shipkit start <name> writes it), not autofixable' }

package/src/checks/SK004-gitignore-policy.check.ts

@@ -205,11 +205,14 @@ export const gitignorePolicy = check({
     title: '.gitignore',
     description: 'the managed .gitignore block keeps private contract folders out of git',
     owner: 'meta/contracts.md',
-    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
-    // carries and no read set records (the header says why)
-    inputs: ['.'],
     // it untracks generated files (a commit) unless the run is frozen
     writes: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
+    // carries and no read set records (the header says why)
+    cache: { by: 'files', inputs: ['.'], key: null },
+    fix: 'ci',
+    applies: 'always',
     run: async (c) => {
         // a generated path still in the index is the half-applied state the
         // managed block cannot fix on its own
@@ -278,7 +281,7 @@ export const gitignorePolicy = check({
         }
         c.ok(`.gitignore policy block current, ${claimed.length + backProbes.size} patterns verified against git`)
     },
-    fix: async (c): Promise<FixResult> => {
+    repair: async (c): Promise<FixResult> => {
         // the move first: it writes the new block itself, before any folder moves
         const moved = process.env.SHIPKIT_FROZEN === '1' ? null : migrateLayout(c.root, { config: c.config, renderGitignore: (t, legacy, cfg) => renderPolicy(t, cfg ?? c.config, legacy) })
         const layout = moved == null ? null