rvlib-shipkit 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,117 @@
+## 1.6.0
+
+- **lint, typecheck, test and every task that declares nothing are cached now.** Such a task is keyed on the whole work tree, plus the gitignored paths the new `ignoredInputs` lists for it (`{ test: ['dist/**'] }`, `'*'` for every task; a path by content, `dir/**` by the names under it), and the lockfile, the installed packages, the bun and node versions and the toolkit code behind it. `sk trace-audit` runs each gate task once under a file tracer and names the gitignored paths it reads that its key misses. Tracing is on wherever it can run (Apple silicon macOS): SK031 audits about daily, `sk trace-audit --disable` opts a machine out and `SHIPKIT_TRACE=0` one run, and each finding joins the key of the task that read it at once, in every worktree of the repo. SK032 and the fix pass of `sk ci` then write the findings into their own block of `repo.config.ts`, once the repo pins 1.6.0 or later. The tracer never decides a verdict. It needs Apple silicon macOS: on Linux and in CI nothing audits, and SK030's daily sample is the only net there.
+
+- **Every check that did not replay says why**, one line per reason: `ran: src/a.ts changed (lint, typecheck)`, `ran: nothing stored for it yet`, `ran, not kept: it reached the world through …`. A check its author declared never cached says so only under `--verbose`.
+
+- **A cache key carries the code behind the answer, not the whole toolkit.** A check is keyed on its own module graph and the runner's, and a repo task on the toolkit modules the repo's config imports, so a toolkit edit re-runs only the checks it can change.
+
+- **A command loads the image and comfy libraries only when it runs**: `sk --help` went from 540 ms to 220 ms.
+
+- **SK030 audits the cache.** About once a day, while somebody works in the repo, it re-runs a sample of the checks the cache would answer right now, fresh, and compares. A cached green that a fresh run disagrees with fails, naming the check whose key misses a path its body reads, and the stale answer is dropped so it is never served again. `sk cache-audit` is the same audit on demand (`--sample <n>`, `--only <id>`, `--json`).
+
+## Unreleased (patch)
+
+- **The hub tree groups assets by kit category.** Under media, each category is a row that folds, and its label opens the category page. An asset row reads by its kit label (`mon/brindon/front`), never its file id.
+
+- **SK001 no longer asks a comfy repo for a `comfy:up` script.** The box is a global process that `sk gp start comfyui` starts from any repo, so a per-repo script only copied that command. A `.shipkit/comfy/` folder now asks for nothing, and SK001 no longer probes it.
+
+- **Every repo's tree has the same top rows.** A section the repo has nothing in (no process, no contract, no secret, no asks, no reflections, no tests, no media, no wiki) stays in the list, greyed, its title saying why. The processes row still opens its page, which says the repo declares none. The others open nothing, and the arrows step over them. Plan, git and admin still exist only on the home.
+
+- **Every command starts faster.** A command that draws images or talks to ComfyUI loads canvas, sharp and comfy-ts when it runs, instead of every command loading them at startup (canvas alone read the system fonts). A fully cached `sk ci` drops from about 1.2s to 0.7s, `sk --help` from 540ms to 220ms.
+
+- **Every check that did not come from the cache says why.** Above the verdict, one line per reason: `ran: src changed (lint, test)` names what moved since the last stored answer, `ran: nothing stored for it yet`, `ran, not kept: it reached the world through \`git check-ignore -q\`` for an answer that can never be stored, and `never cached: <reason>` for a check no key describes. A check that can never be kept was counted like a key that moved.
+
+- **Every repo's media page loads its comfy workflows, not only the first one's.** comfy-ts keeps one instance per process, rooted at one repo, and the daemon serves every repo from one process: the second repo to load its workflows got "conflicts with the existing instance". The instance is now the first repo's, holding only the host caches every repo on that host shares, and each repo's drafts resolve under its own `.comfy-ts/drafts/`.
+
+- **Editing shipkit no longer re-runs every check in every repo.** The cache key hashed the toolkit's whole source, and a repo that links it hashed the linked package again, tests included, so a css tweak of the hub or a new test re-ran every cached check everywhere. A key now carries the runner (the modules that run a check and store its answer, and the templates a check reads), the check's own module closure (modules it runs by path included), and for a check running the repo's code, the toolkit modules the repo imports. An edit no answer depends on moves no key, and `sk keys --why` lists the toolkit files behind a key.
+
+- **⌘↑ and ⌘↓ open the repo above or below in the project list**, from any page, round both ends. In a text field they still move the caret. The list's foot hints them, and its sort button now just says sort, the order it is in moving to its title.
+
+- **An app icon fills its tile, on the repo's colour.** The shipkit app and every process app drew the repo's mark as it was, transparent margin included, so a small mark was a dot on the dock. The icon now cuts the mark to its own box (faint alpha noise, which generated images carry over the whole canvas, counts as margin) and sets it on a rounded plate in the identity colour it stands out on most, on the macOS icon grid. A mark that already fills its box, a photo or a tile, becomes the plate. New colours rebuild the app at its next open.
+
+- **The identity colours moved to the admin page, with a preview of the app icon.** The two pickers left the strip. The admin page opens on an identity card: the app icon drawn in the colours being picked (`/api/projects/app-icon/<repo>`, the same drawing the app build uses), and the repo name on a dark and on a light page. The card reads a repo by the name the project list knows, so a repo whose config names it otherwise (screenplay, named screenplay-shed) shows its own colours and icon.
+
+- **A broken comfy setup no longer takes the whole media page down.** The workflows load only when a kind generates with comfy. When they fail to load, the media API still mounts: the rolls, the picks and every other kind stay served, and the reason shows in the page errors and in every comfy roll that fails.
+
+- **`@napi-rs/canvas` and `comfy-ts` are one copy per process, like the toolkit.** A repo file that imports its own install gets the host copy. A brand that loaded an image with its own canvas copy and drew it on the toolkit's canvas failed ("Value is not one of these types"), and workflows written against an older comfy-ts failed to load.
+
+- **A failing test no longer paints the last test file red.** Bun repeats every failure in a recap after the last file of its report, and the hub read those lines as failures of that file: the tests page and the problems pane blamed an innocent suite. The recap now closes the report.
+
+- **The arrows walk the repo tree from anywhere on the page.** Up and down move to the next row and open its page at once, with no need to click the tree first. Left and right fold, unfold and climb as before. In the filter box, up and down walk the rows the filter keeps, and left and right stay the text caret's. With no cursor yet, they start from the section of the page shown. A branch with no page of its own only takes the cursor. A walk with the arrows is one history entry, so a held arrow never floods the browser history and back returns to where the walk started. While an asset is open, left and right stay the atelier's roll keys.
+
+- **No repo page is a card grid.** Every collection without a table of its own (contracts, reflections, posts, workflows) is now a list, one line per item, red first. The processes page is the overview's process table for that repo, with the opened process's description and log under it. The tables sit on a panel box for contrast, and the page title and group headers are larger and in plain ink.
+
+- **The secrets page is a list.** One line per secret, never a card: a dot, the name, missing, minor or present, and its sentence. Missing ones come first.
+
+## 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.6.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/assets/gen/comfyts-gen.ts

@@ -12,7 +12,8 @@ import { ComfyTS, type AnyVar, type ComfyExecution, type DefinedWorkflow, type M
 export type GenProgress = { value: number; max: number; node: string | null }
 export type OnProgress = (p: GenProgress) => void
 
-export type LoadedWorkflow = { id: string; file: string; wf: DefinedWorkflow }
+/** root: the repo the workflow belongs to, which holds its drafts */
+export type LoadedWorkflow = { id: string; root: string; file: string; wf: DefinedWorkflow }
 export type ComfyTsRuntime = { workflows: Map<string, LoadedWorkflow>; heal?: string }
 
 // function declaration, not const — TS only narrows on never-calls to
@@ -47,9 +48,11 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
     // explicit COMFY_TS_QUIET=0 from the caller.
     process.env.COMFY_TS_QUIET ??= '1'
     // before the first module import: a bare ComfyTS.create() inside the
-    // module then returns this same instance. A pre-existing instance with a
-    // different root throws loud — a real misconfiguration.
-    ComfyTS.create({ rootPath: root })
+    // module then returns this same instance. comfy-ts keeps ONE instance per
+    // process, and the daemon serves every repo from one process, so only the
+    // first repo roots it. What it roots is the host caches, shared by every
+    // repo on the same host; each repo's drafts resolve from its own root
+    if ((globalThis as { comfyts?: unknown }).comfyts == null) ComfyTS.create({ rootPath: root })
     if (!existsSync(dir)) fail(`${dir}/ missing — ship at least one <id>.cflow.ts comfy-ts workflow module (copy from the rv-comfy template)`)
     const out = new Map<string, LoadedWorkflow>()
     for (const f of readdirSync(dir).filter((x) => x.endsWith('.cflow.ts')).sort()) {
@@ -65,7 +68,7 @@ export async function loadCflowWorkflows(root: string, dir: string): Promise<Map
         const vars = varsOf(wf)
         if (vars.prompt?.kind !== 'prompt' || vars.seed?.kind !== 'seed')
             fail(`workflow '${id}' must declare vars.prompt (v.prompt) and vars.seed (v.seed) — shipkit drives both`)
-        out.set(id, { id, file, wf })
+        out.set(id, { id, root, file, wf })
     }
     if (out.size === 0) fail(`${dir}/ has no *.cflow.ts workflow modules — seed one from the rv-comfy template`)
     return out
@@ -96,8 +99,9 @@ export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown
     }
 }
 
-// ── drafts — comfy-ts disk format, path rule taken from the ComfyTS instance
-// so it cannot drift: .comfy-ts/drafts/<wfId>/<draftId>.json.
+// ── drafts — comfy-ts disk format, .comfy-ts/drafts/<wfId>/<draftId>.json
+// under the workflow's own repo, never the process instance's root (which is
+// the first repo's in the daemon).
 //
 // The draft id is the KIND, never the asset: ONE `creature` draft behind all
 // 107 creatures, so tuning the loras once tunes them for the whole kind. The
@@ -107,7 +111,7 @@ export function applyVarValues(wf: DefinedWorkflow, vars: Record<string, unknown
 //
 // Shipkit does its own IO here because comfy-ts exports no drafts API yet;
 // swap when it lands.
-const draftDir = (lw: LoadedWorkflow): string => ComfyTS.create().resolveFromDrafts(lw.id)
+const draftDir = (lw: LoadedWorkflow): string => join(lw.root, '.comfy-ts', 'drafts', lw.id)
 export const draftPath = (lw: LoadedWorkflow, name: string): string => join(draftDir(lw), `${name}.json`)
 
 export function readAssetDraft(lw: LoadedWorkflow, draftId: string): Record<string, unknown> | null {

package/src/assets/server/studio-server.ts

@@ -49,7 +49,18 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     const workspace = join(root, kit.workspace)
     const dirOf = (id: string): string => assetDir(workspace, id)
     let workflows: Map<string, LoadedWorkflow> | null = null
-    if (kit.comfy != null) workflows = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
+    // only a comfy kind needs them, and a broken load costs only comfy
+    // generation: the rolls, the picks and every other kind stay served, and
+    // the reason rides in /api/state errors and in every comfy roll that fails
+    let comfyErr: string | null = null
+    if (kit.comfy != null && kit.kinds.some((k) => k.generate.backend === 'comfy')) {
+        try {
+            workflows = await loadCflowWorkflows(root, join(root, kit.comfy.workflows))
+        } catch (e) {
+            comfyErr = `comfy workflows not loaded: ${(e as Error).message}`
+            console.log(`WARN ${comfyErr}`)
+        }
+    }
 
     // custom panel scripts fail-fast here too (tests/embedders may bypass loadKit)
     const missingPanels = missingPanelScripts(kit, root)
@@ -111,6 +122,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
     // workflows are pre-loaded above (fail-fast for a comfy studio); the
     // resolver just hands the shared roll generator the ready runtime.
     const resolveComfy = async (): Promise<ComfyTsRuntime> => {
+        if (comfyErr != null) throw new Error(comfyErr)
         if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
         return { workflows, heal: kit.comfy.heal }
     }
@@ -243,7 +255,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                     derived: parentIdsOf(f).length > 0, stale: await isStale(kit, workspace, f),
                 }
             }))
-            return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: queue.errors.slice(-5), assets })
+            return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: [...(comfyErr == null ? [] : [comfyErr]), ...queue.errors.slice(-5)], assets })
         }
 
         if (pathname === '/api/asset') {

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
@@ -264,14 +238,11 @@ export type TaskDef = {
     timeoutMs?: number
     /** CONTENT population: the repo-relative paths this task reads. Declaring
      *  them is what makes it keyable (ledger/git-key.ts). Undeclared is the
-     *  DEFAULT and means never cached, so forgetting one costs speed and
-     *  never correctness. A list MISSING a path the command reads is the one
-     *  that costs correctness: the key cannot move when that path changes, so
-     *  a cached answer comes back over a tree it no longer describes. `['.']` is the
-     *  whole TRACKED tree, and it is NOT a catch-all: an ignored path enters a
-     *  key by name and never by content, so a task reading a gitignored
-     *  fixture, a built dir or a .env under declares with `['.']` exactly as
-     *  it would with a narrow list. */
+     *  DEFAULT: the task is keyed on the whole work tree plus the repo's
+     *  `ignoredInputs` (build/shipkit/cache.md). A list MISSING a path
+     *  the command reads is the one that costs correctness: the key cannot
+     *  move when that path changes, so a cached answer comes back over a tree
+     *  it no longer describes. */
     inputs?: string[]
     /** WORLD population: it reads the network, a keychain, $PATH or the clock,
      *  so nothing on disk describes its answer and a clean pass is remembered
@@ -333,13 +304,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`