rvlib-shipkit 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,133 @@
+## 1.3.0
+
+- **`shipkit ci` prints what the reader acts on, and nothing else.** A green run is one line per check that ran and one verdict line: `ok: test 920 tests (1.4s)` then `ok: 1 check green`, where it used to print nine. A test check carries its count on its own line. The whole gate folds its tier and cache counts into the verdict (`ok: 31 checks green; quick tier; 25 cached, 5 ran, 1 never cached`). A fix pass prints only when it rewrote files, and names them. A green check prints one line, a warned one only its warnings and their `fix:` pointers, a failure prints whole. `--only` says nothing about checks outside its selection (floor gaps, `off` checks, parked checks). `--verbose` restores every line the default leaves out: the clean fix pass, the machine pool, the tier, the cache declarations, the parked checks, the old summary and the cache counts. STATUS.md keeps them all, a release or bump gate still prints them all, and `--json` is unchanged.
+- **Compact monitor cards.** A widget's leading `<header>` joins its card's title line, dim (`splitWidgetHead`), and `shipkit overview` prints it on the title line the same way. A card is as wide as its content, the owner repo moves to the hover, the `.wbar` meter is 56px, and `<table class="wmeters">` lays meters out two to a row, label, bar and value.
+- **Fix: the planned page lists only what is actually planned.** A check waiting for its repo to be active is no longer listed as late: the page folds all of them into one line at the end (`waiting for their repo to be active: 24 checks in 9 repos`) that opens on a click, and `shipkit planned` prints the same line, listing them with `--all`. A check can declare `planOff: (env) => reason | null`, and the plan leaves it out of a repo where it has nothing to do: SK026 without an ask that carries a probe, SK025 without a unit that releases, SK005 without an rvlib dependency. A decided fact (`ttl: 'forever'`) with no answer under its key adopts, once, the newest clean answer stored under its older timed key for the same declared value, so SK007 stays known where it already answered.
+- **Every section of a repo page has a key: ⌥ and its first letter.** ⌥C checks, ⌥R runs, ⌥A asks, ⌥T tests, ⌥M media, ⌥W wikis, ⌥D admin, read from the physical key so macOS's option characters and AZERTY keep them, printed as a badge at the end of each section line and on each section's entry in the ⌘K picker.
+- **The open in VS Code button wears the VS Code mark, and it and open in Fork close the top bar at its far right end.**
+- **The dock header: a cycling size button and small status pills.** The size is one button showing the current size, a dot per size and `⌘B`; a click or the key moves to the next (`CycleButton`, reusable). `runs, every repo`, the `(?)`, the in flight count and the size switch are gone. The status is a row of dim pills that never wraps: idle or running, queued, a warn pill when the plan holds, the last check with its repo icon, verdict, short id and age, the settling repos as one pill listing them on hover, and the window at slim and open; what does not fit folds into `+N`.
+- **A repo page's sections are the top of its left pane, its runs are in the top bar, and the bar under the strip is gone.** Checks, runs, asks, tests, media, wikis and admin are one line each over the tree, in the project list's line style (icon, label, a count where it says something: red checks, open asks, red test files), the current one lit; the `resources` title is gone. The home strip carries the repo's run state (`idle`, or a spinner and what runs, cut, whole on hover) and two compact buttons, `health pass` and `gate`, each with a tooltip naming what it runs; at its right the repo's processes, its hub's trouble, `modernize` while behind, and two icons, open in VS Code and open in Fork. The bar never wraps: below a width the labels shrink to their icons, then the run state to its spinner. A hub of its own draws the same pieces in its own header, with its name.
+- **An admin page per repo (`#page:admin`).** Reload the hub (the old `restart`: stops it in the daemon and loads it again, its config read fresh), keep active (the old `active` checkbox: the plan's hand set active flag) and archive, which now asks for a confirmation first, each with the sentence that says what it does. The three left the bar.
+- **The tree's filter is quieter.** Its placeholder is `filter`, its key `/` sits in a small badge at its right the way the project list prints its keys, and the severity filter sits beside it.
+- **The tests page leads with every test file, slowest first.** One list of every file of every test check: its check, its last duration against its budget, its status and its age, the never ran ones last, then the test checks and the failing files. The `tests` section line opens it. `/api/tests.json` carries it as `files`, merged from each check's own list.
+- **The dock slides between its sizes.** `⌘B` and the size switch ease the boundary over 180ms instead of jumping; a drag, a window resize and the first paint stay instant, and `prefers-reduced-motion` turns the slide off.
+- **The list's foot: a sort menu that names each sort, and an archived button beside it.** The sort button no longer sorts on a click: it names the order the list is in and opens a small menu of labeled sorts, `last activity`, `last commit`, `name` and `open asks`, the current one checked, and a pick sorts once and closes it. `manual order` is the state after a drag, never a pick. The `▸ archived (N)` fold became a small button with the archived count beside the sort button: a click shows the archived repos just above the foot, which never moves, and a second click hides them, kept per browser. `/api/projects.json` rows carry `commit`, the last commit time, for the new sort.
+- **Fix: a daemon restart in place no longer loses a save burst, resets the catch up window, or retries a decided fact.** When a repo joins the plan, a file the owner wrote after its last run on record counts as a save, so the burst settles and runs. The catch up window's start lives in the machine db, and a boot within 10 minutes of the plan's last beat keeps it. A decided fact whose probe skipped retries 1 hour after that skip, doubled per skip in a row up to 24 hours, from the run record. What holds the plan (`held: load 9.2 on 8 cores`, `settling: my-app, 42s`) shows on the planned page, first in `shipkit planned`, in its `--json` as `held`, and at the end of the dock's thin line.
+- **The dock never shows nothing, and the regions read apart.** `⌘B` cycles a one row line (`2 running · 5 queued · last: my-app typecheck ✓ 12s ago`, or `idle`), the slim chart and the open panel; a browser that kept the old hidden size gets the line. The project list, the top bars and the dock each wear a surface token a small step from the page (`--bg-side`, `--bg-top`, `--bg-dock`).
+- **The dock: what shipkit runs in every repo, under the whole page, on every page.** One run chart docked at the bottom of the window, below the rail and the page, one group of lanes per house repo that ran something in the window, the repo's icon and name on the left. `⌘B` (Ctrl+B) cycles its sizes: slim, the last two minutes in thin lanes; open, the last ten with the run bands, the axis and the concurrency band against the cap, its height dragged and kept. The size is read from the browser before the first paint, so a reload moves nothing. It reads ONE route for every repo, `GET /api/house-runs.json`, read only from each repo's record and only when that record moved, asked every 2s while the dock shows and the tab is in front.
+- **A repo's whole run record moved to the chart over its runs page.** The live strip under the header is gone, and so are its fold key `l` and the other repos' collapsed lanes in `/api/live.json`, which the dock replaces.
+- **The overview's processes table reads tighter.** The version has its own column (empty when unknown), the process label column is narrow and cut with the whole label on hover, and each kind of button has its own column (declared actions, take over, restart, start or stop, open), so every start sits under every start and a line without a button keeps the space. A pid copies on a click and says `copied` for a moment (a refused clipboard is said in the strip). A url is a link, opened the way the pick says. The section titles are gone: the open pick and `new window` sit at the right of the table's header row. The widget cards are as wide as what they hold, from 260px, with tighter padding.
+- **The overview is the monitor, then one processes table, shipkit's own group first.** pm, the daemon and the web are lines of the table in the same line UI as the global processes, under a `shipkit` group: dot, label with a `core` tag and the shipkit version, port, pid, uptime from the pid's start (a pm reload no longer resets the daemon's or the web's uptime), and the log on hover. Their stop is disabled (always on), the daemon and the web restart through pm, and pm has none: it is the LaunchAgent, its tooltip says so. The separate shipkit card is gone, the monitor widgets come first, and each group's name sits at the top of its group. pm's status carries `ports` and its own log `tail`, and every child's log tail. `shipkit gp` prints the same core group first, with versions (it asks the daemon's `/hub.json` too), and `shipkit overview` prints the monitor then the processes, as the page.
+- **The daemon or pm down is said on a line at the bottom of the page, never over it.** The line is reserved whether or not it says anything, so an alert moves nothing, and it stays empty until a probe has actually failed.
+- **Fix: the plan no longer keeps the machine busy.** A save burst is asked about once the repo has been quiet for 60 s (every 10 minutes at most for a repo never quiet), where it was every 250 ms pause. A check a save moved waits 20 times its last measured run after that run, so a heavy suite runs at most a few times an hour. Above a load average of 1 per core the plan starts nothing on its own (`Planner.held()` says why), and a click still runs at once. A check nothing can key that has a cadence (its `every`, its `cron`, or the default range) runs on that cadence only, never on every save. Measured on the house repo before the fix: 342 background gates in 2 hours, `test:rvlib-shipkit` 188 times, `pb-playground` 716 runs in a row under a rule that read every 20h..28h.
+- **The home's console commands read as one family.** `shipkit activity` is the activity page's command, `shipkit cross-repo-activity` stays as its long name. `shipkit overview`, `shipkit activity`, `shipkit planned` and `shipkit global-processes` (`gp`) sit together under a `Home` group in `shipkit --help` and the command page. The activity page names its command in a dim footer line, as the overview and the plan do.
+- **`shipkit overview`: the overview page in the console.** Its three sections from the answers the page reads: pm, the daemon and the web with pid, uptime and version (pm's status, the daemon's `/hub.json`), the global processes as `shipkit gp` prints them (one `globalProcessesAnswer`), and every monitor widget as text from the html the daemon last rendered (`/api/home/widgets.json`): tags stripped, a table's cells aligned, a `.wbar` meter drawn as `██████░░░░ 62%` (`src/home/widget-text.ts`). When pm or the daemon does not answer it says which and prints what is still known (the declared processes, their state unknown), and exits 0. `--json` gives `{ now, pm, daemon, processes, widgets }`, widgets the route's exact payload. pm's status carries `since`, so its own uptime shows. The overview names the command in a dim footer line.
+- **The global pages are four lines on top of the project list.** Overview, jump to…, activity and planned each get a line in the repo rows' style, an icon, the label and the shortcut at the line's end, then a thin divider before the repos. The page shown is lit, and the jump to line while the picker is open. At the list's narrowest the labels truncate and the shortcuts stay.
+- **`shipkit planned`: the planned page in the console.** It asks the daemon's `/api/home/planned.json`, the route the page polls, and draws the page's one list (now, late, next) with the page's own functions, now in `src/plan/plan-timeline.ts`: per row when (`in 4m`, `late 2h`), repo, check, its mark, its last result, then its title and the rule that planned it (`every 7d`, `on change (keyed on its files)`). The checks only a save runs are counted, `--all` lists them, `--repo <name>` keeps one repo, `--json` prints the route's exact payload. With the daemon down it says so and exits 0: the plan (its marks, the running batch) lives only there, so nothing is rebuilt from disk. A plan row carries its check's `title`. The planned page names the command in a dim footer line.
+- **A global process's uptime survives a pm reload.** While a process is up with a pid, its uptime counts from when that pid started, as the OS says (`ps -o lstart=`), not from pm's last observed state change. The start is kept per pid: a pid pm spawned needs no `ps` at all, an adopted pid costs one `ps` at adoption, and a new pid (a restart) is read again. A process without a pid keeps `since` as before.
+- **Fix: opening the overview, the picker, the activity or the plan no longer resets the selected repo to the house repo.** The repo list keeps marking the repo you were in, dimmer while a global page is up, and on the home no row is marked before a repo is picked. On a global page the ⌘K picker lists that repo too, since it is not on screen.
+- **The open in Fork button leads each repo's commit list on the activity page.** It left the repo name cell for a narrow column of its own right before the commits, on the same line as the first commit (or the red uncommitted line), still dim until its row is hovered.
+- **The ⌘K picker shows icons.** Every repo entry wears its repo icon (its letter tile when it has none), as the project list shows it, and home, planned, activity and archived wear the icons of their buttons. The order is unchanged. `bun run activity:check` checks it in headless Chrome, with the activity status dot.
+- **The activity page names what is wrong behind each status dot.** A red or orange dot is a button: hovering it floats the failing and warning checks at once, failing first, each with its id, its title, how old that outcome is and the first line it printed about the problem. A click lists the same checks under the repo's row, so they read without hover (the macOS app shows no native tooltip), and a second click hides them. Each id links to that repo's check page. The daemon's activity answer carries them as `failing` on each row, titles from the plan (`Planner.titles`).
+- **Fix: `bun run home:check` reported screenplay's tree as taking 20s on its first visit.** It loads in about 40ms from what was read ahead. The walk waited for a title starting with the home's key (`screenplay ·`), but the title carries the name the repo's own config declares (`screenplay-shed · hub`), so the wait ran to its timeout and the timeout was then reported as a load time. The walk now matches the shown repo by its home key, and reports a load time only for a tree that showed.
+- **Fix: `bun run home:check` read the four buttons on top of the project list as missing.** Its probe quoted `⌘'` inside a single quoted string, the page could not parse it, and the walk's wait read the parse error as "not yet" for 20s. The expected labels are now quoted by `JSON.stringify`, and a probe that does not parse now throws instead of timing out.
+- **A private repo commits its comfy drafts through a `.comfy-ts/` block.** The `blocked-paths` pre-commit gate lets `.comfy-ts/drafts/` through when the repo declares `visibility: 'private'`; `hosts/`, `cache/`, `outputs/` and every other `.comfy-ts/` path stay blocked. A public repo and a repo with no declared visibility keep the full block, and a prefix naming the drafts folder itself still blocks it. Before, a `.comfy-ts/` block contradicted the SK004 `!.comfy-ts/drafts/` re-include, and drafts stayed uncommitted forever. `blockedStaged` is exported from `hooks/run-hooks.ts`, and `shipkit hooks list` names the exemption.
+- **A public repo and an npm unit keep their own files.** Two declared facts, each on its owner. The root unit's `release: { npm: true }` says a package strangers install and work on: SK001 asks only that it can publish (no `"private": true`, a `license`), never routes or renames its scripts, and its fixer writes nothing; SK005 names an rvlib bump and its command and never runs it; SK006 reads it as publishing by design; SK013 and SK017 report green and never write its `.claude/settings.json` or `.vscode/tasks.json`. The repo's `visibility: 'public'` says strangers read its tree: SK004 keeps `.comfy-ts/drafts/` ignored, and SK007 and SK009 read the declared visibility only (absent is private). A public repo with no npm target, like a site, keeps SK013 and SK017. A `shipkit ci` over a public fixture whose root unit declares npm, with its own cli, leaves package.json, `.claude/settings.json` and `.vscode/tasks.json` byte for byte (`tests/public-npm-repo.test.ts`, with a private app control that is rewritten).
+- **The root unit's npm target is declared, never inferred.** A root whose package.json is not private and whose config says neither `release: { npm: true }` nor `npm: false` no longer publishes by default: resolution refuses and names both edits, the same rule sub units follow. So the release path and the checks read one fact.
+- **`shipkit global-processes` (short: `shipkit gp`).** The overview's global processes table in the console, from pm's own answer: per repo, one line per process with its state (`up 2h`, `crashed 3m ago`, `stopped`), label, url, pid, note and last log line. `--json` gives the rows the overview draws. When pm is down it says so, lists the declared processes with their state unknown, and exits 0.
+- **The global processes are one table, a line per process.** The overview's cards are gone: a row group per declaring repo (its icon and name in the first column, as on the activity page), then one line per process with its state dot, icon, label (its log on hover), url, `up 2h` or `crashed 3m ago`, and start or stop and open at the right. Restart, take over and declared actions stay small, shown only when they exist. A running line is tinted green, a crashed one red, and nothing scrolls sideways at phone width. pm's resource view carries `pid` and `since` (the last status change). The rows come from `src/home/process-rows.ts`, one model for the page and the console.
+- **Fix: a link with no class of its own was the browser's dark blue on the dark page**, like `5 archived repos` on the overview. Every such link now takes the accent colour.
+- **Fix: a repo's own cli is never taken for shipkit.** SK001 read any `bun <path>cli.ts` script as the in repo shipkit, so in a repo with its own cli (`bun src/cli/comfy-ts-cli.ts tui`) its fixer rerouted `test`, `lint` and `typecheck` to `bun src/cli/comfy-ts-cli.ts ci --only …`, a command that cli does not have, and SK013 pointed its guard beside it. Only a file named `cli.ts` under a directory whose name says shipkit counts now (`isShipkitCli`), and the `serve` alias WARN reads the same test.
+- **Open a repo in Fork from the activity page.** A small button beside each repo name opens it in the Fork git client (macOS). The daemon takes a house repo name only, refuses an archived one, and says so when Fork is not installed.
+- **`shipkit cross-repo-activity`.** The activity page in the console, from the same computation: every house repo's checks, branch, upstream, uncommitted work and commits in a window (`--max-age 30m`, `--max-commit 3`), or the route's exact payload with `--json`. Local git only, no daemon needed.
+- **Fix: the activity page and the status dot read what is true now.** An activity answer older than 30s is never served (a page opened hours later showed hours old rows), a tab coming back no longer forces a git pass, and a repo's status dot counts only the checks it declares today, so a renamed or deleted check no longer holds it red. The hover says how long each check has been red.
+- **The activity page reads faster.** Six repos at a time, and the git asks inside a repo start together: 0.5s to 0.22s for 19 repos on an idle machine, with a larger gain while the daemon is busy.
+- **The activity page has a status column before the branch.** One dot per repo from its own run record: red with the number of failing checks, orange with the number of warnings, green when every check passed, grey when shipkit never ran there. The check ids show on hover. The project rows carry it as `checks`.
+- **The activity page shows only `main` green.** A repo on `master` is orange like any other branch, so a repo still to rename stands out.
+- **New built-in SK028 readme, non-blocking.** A repo's `README.md` exists and shows at least one screenshot: a markdown or html image whose source is a file in the repo or an https url (a status badge does not count). Each requirement reports its own line, so a new mandatory README item is one more entry. Keyed on the README and the images it names, so it runs on change only.
+- **No built-in rides the daily default range any more.** SK008, SK009, SK015, SK022 and SK024 each declare what their answer depends on and run only when it moves: SK008 on repo.config.ts, the agent definition and the brief (by content, inside the repo or not), SK009 on HEAD, every ref and the settings file (a commit, a fetch or a tag re-asks it, since the save watch now hears a ref move inside `.git`), SK015 on the config and where the work tree root sits, SK022 on package.json, the installed copy and the running version, SK024 on the config and the installed config source. The 20h..28h range is now for a REPO check that declares nothing, and `shipkit keys --burn-down` WARNs on each one (a built-in there is a FAIL line). A guard test fails the toolkit on any built-in without a key, a `ttl` or an `every`.
+- **SK008 is titled "reviewer definition".** It lints the agent definition file and never starts an agent, so the planned page no longer reads as a scheduled review.
+- **A sweep guard: nothing starts an agent on its own.** `agentSpawnIn` (`src/core/agent-spawn.ts`) finds a spawn or exec of `claude`, `claude -p`, or an import of the agent sdk, comments skipped. A test runs it over every source file, beside the samples it must catch and the lookalikes it must let through (a url, `~/.claude/projects`, a help line naming the product).
+- **A repo page with no row picked shows its README, images included.** The first of `README.md`, `readme.md`, `Readme.md`, `README.markdown` or `README` at the repo root, rendered as markdown. A relative image loads through the new `GET /api/readme-file/<path>`, which serves only an image file inside the repo. An http(s) image such as a badge loads as written. A repo without a README keeps the hint.
+- **An archived repo is processed by nothing but its own page.** `houseRepos()` now splits `archived: true` repos out, so the rail, the daemon (hub, watch, plan rows, gates, processes, widgets, identity fill, store sweep), the activity page, pm's global processes and `shipkit fleet` never see one. The project list's folded archived group is gone. `/archived` (the picker's `archived`, and a link at the foot of the overview while one exists) lists them, each with `unarchive`. `/api/projects.json` answers `archived: [{ name, icon }]` beside `projects`, and a row no longer carries `archived`.
+- **Archive a repo: `archived: true` in repo.config.ts.** It stays known and listed (dimmed, in a folded group at the bottom of the project list, out of the ⌘ numbering), and nothing runs there: the daemon never loads its hub, so no file watch, no plan rows, no automatic gate, no repo process, no widget or global process, no identity fill, no store sweep. The `archive` button in the repo header toggles it and moves only that key (`POST /api/projects/archived`, `src/core/archived.ts`). Archiving a loaded repo stops it on the next tick; unarchiving loads it again.
+- **Global process cards: start and open, grouped by repo, tinted by state.** A card has two buttons, `start` (`stop` while it runs) and `open`; restart, take over and declared actions stay as small controls where they apply. Cards group under their declaring repo (its icon, its identity colour) in the project list's order, are smaller, and an up card is tinted green, a crashed one red. Where `open` opens is one icon pick in the section's title row, the default browser or a shipkit app window, kept per browser. New `globalProcess({ icon })`: an emoji or a repo-relative image path, served by pm at `/api/pm/icon/<id>`; without one the card wears its repo's icon. Breaking: `app: true` is removed, since the app window opens any url; pm's `act: 'app'` works for every process with a url.
+- **New built-ins SK026 asks auto close and SK027 agent wiki links.** Every repo with a `.shipkit/asks/` queue now archives the asks whose own `check:` probe passes (an open queue is no warning; a frozen run archives nothing). Every repo with `agent/index.md` fails an orphan page or a dangling ref there. A repo without the queue or the wiki skips.
+- **Retired check ids are listed** (`src/core/retired-checks.ts`), and discovery refuses a built-in that takes one again.
+- **Breaking: the `contracts` check is gone, SK002 is the one row for the release contracts.** Both ran the same scan, so every repo showed one invariant twice. A venue deploy step declares `deps: ['SK002']` instead of `deps: ['contracts']`.
+- **New built-in SK025 release drift.** Every unit a repo releases matches npm and its push remote, the survey `shipkit releases` prints, as warnings. A repo that releases nothing (a private root with no release config and no units) skips it. A clean answer keeps 20h, keyed on every unit's version. It replaces the drift check a repo kept per published lib.
+- **Breaking: SK021 (github login) and SK023 (stores under cap) are no longer built-ins.** Both ask about the machine, never the repo, so every repo re-asked one fact. The gh probe and its `core` credential row stay in the lib as `src/core/gh-login.ts` (`probeGhLogin`, `GH_LOGIN_CHECK`): a house repo declares the one check that runs it. The store caps keep their measure and sweep in `src/core/retention.ts` (`capWords` joins them), for a house check that measures every repo in one pass.
+- **`shipkit assets check` no longer probes the comfy backend.** Whether a box answers is a machine fact, never a question about a repo's kit.
+- **An activity page (`/activity`, ⌘L).** One table of every house repo: its branch (green on main, orange elsewhere) and a red line of what it holds uncommitted (the paths on hover). Beside them, its commits in a window you pick (10m to 7d, 30m by default), newest first, each with a green ✓ once pushed or an orange ↑ until then. A number sets how many commits a repo shows (1 to 15, 3 by default). It reads again every minute while shown, and the countdown is a button that reads at once. The counts beside it are pills. A repo with nothing in the window still shows its last commit, in grey, and quiet repos sit below the busy ones. The daemon reads it with local git only while the page is open and visible, never with a fetch.
+- **New keys, and a picker button.** ⌘J the overview, ⌘K the picker, ⌘L the activity, ⌘' the plan, four buttons on top of the project list in that order. The sort by last activity moves to the foot of the list, and above it a fold lists the archived repos by name, each a link to the archived page.
+- **The house repo is active whenever any house repo is.** Its checks serve every repo, so a `wait` check there no longer turns late while you work elsewhere.
+- **`ttl: 'forever'` for a decided fact.** A fact that moves only when someone decides to move it (a repo's visibility, an account that exists) keeps its clean answer for good, keyed on its declared value alone (`cacheKey`), so a new shipkit asks nothing again, and the store sweep never drops it. The plan reads it as the new `every: 'once'`: it runs only while no answer exists for its current key (first time, a declaration edit, a lost db), never on a clock.
+- **SK007 is a decided fact and no longer blocks.** Its clean answer is kept until `visibility` changes, and a mismatch warns: a gate block does not un-leak a repo.
+- **A check keyed on its files runs on change only.** With no `every` declared, a check with `inputs`, or one keyed on what it read through `c`, no longer runs on the daily default range: its answer replays until a file moves. Only a check nothing can key keeps that range, and a `ttl` still reads as `every`.
+
+## 1.2.0
+
+- **Fix: SK024 read back only an `identity` key that starts a line.** On a one line config its own fix wrote the key inline, the check kept warning, and every fix pass added the key again, so a release gate always rewrote `repo.config.ts`. The key is now found at the top level of `defineRepo({…})` wherever it sits, bare or quoted, and a nested `identity` (an SK002 exemption) or one in a string or comment is not it.
+
+- **A filled bar for widgets.** `<span class="wbar" style="--p:51%"><i></i></span>` draws a bar in the page's state colours (`mid`, `hi`); widget rows stay on one line; the overview's shipkit section is a card.
+
+- **The planned page is one list ordered by time.** Three small labels inside it (now, late, next) and three columns per row: when (`now`, `late 2h`, `in 4m`), project · check (the project in its identity colour opens its repo, the check opens its own page), and one mark (a spinner while it runs, an orange dot and `waits: repo inactive` when late, a hollow circle when upcoming, a red ✕ `last failed`). A check that only runs on change is not listed. The rule, the reason, the last result, the inactive policy, an error and `run now` sit in a card that floats over the row on hover. One text filter matches the project or the check, and `/planned?q=` carries it. `Tip` takes `fallbacks`, the sides it tries when its placement does not fit. `bun tests/browser/planned-check.ts` measures it against a running home.
+- **A project list replaces the icon rail.** One row per repo, an 18px icon and the name beside it, the shown repo marked in its identity colour, in a panel whose width is dragged with a separator and kept per browser (`react-resizable-panels`). A repo's resource sidebar is resizable the same way. The rail's three sizes and their button are gone.
+- **Everything that floats is placed by `@floating-ui/react`.** The hover card, the help `(?)`, a process log on hover and the chart tooltip open after a short delay beside their trigger, flipped and shifted into the window, in a portal (`src/serve/hub-app/floating.tsx`).
+- **Command keys.** ⌘1 to ⌘9 select the nth repo of the list (by physical key, any layout), ⌘J the overview, ⌘P the plan, ⌘K the picker. The overview and the plan are two buttons on top of the list, each with its shortcut in its corner.
+- **Fix: a hub serving on its own showed an empty page beside its list.**
+- **Fix: a dark band between the list and the page in the macOS app.** A panel's own scrollbar, which WebKit draws; no panel scrolls itself now.
+
+- **The whole home page paints at once on a refresh.** Each repo's first screen is kept per browser in IndexedDB and read before the first paint, the machine is kept for the overview, and every region holds its size from the first paint, so a refresh measures a cumulative layout shift of 0.
+- **One quiet top strip, the places in the rail and the picker.** The strip holds the shown repo (or the page's name) and machine trouble only, no link and no button. A house at the top of the rail opens the overview, and `home` and `planned` lead the `⌘K`/`⌘J` picker.
+- **The overview: shipkit, then one card per global process, then the monitor.** `shipkit` (pm, daemon, web; was `machine`) and the processes under headers with a line icon; each process a card with its switch, state, declaring file, url and buttons. No repo list: the project list is it.
+- **Take over a global process started elsewhere.** One click: pm stops the process group listening on the process's local port (SIGTERM, then SIGKILL after 5 s) and starts its own supervised copy. Not offered without a local url or probe port, and the row says why. `POST /api/pm/resource` takes `act: 'takeover'`.
+- **`open` opens a global process's url in the default browser.** `open as app` is its own button, only for `app: true` (`act: 'app'`).
+
+- **A refresh of the home moves nothing.** The rail frame renders from the first paint at the size the browser keeps, and the last rail list (`localStorage` `hub:rail-list`) paints at once while the daemon is asked again, so the page no longer jumps right when the list arrives. `bun run home:shift` measures the cumulative layout shift of a first load and a refresh in headless Chrome.
+
+- **`<name>.shipkit.ts` unit files: checks, global processes and widgets.** A repo drops one anywhere and default-exports `check({...})`, `globalProcess({...})` or `widget({...})` (`rvlib-shipkit/src/shipkit-files.ts`). Discovery reads a `check` there beside the `.check.ts` files. A `globalProcess` is a long running process for the whole machine, supervised by pm whichever house repo declares it: pm reads the files at boot and every 15 s, and the overview shows a switch each, its log on hover, restart, one button per declared action (argv, or a function of the file run in its own bun process), and for `app: true` with a `url` an `open` that opens a shipkit app window, or `start and open` in one go on a process that is down. A `widget` returns html the daemon renders on its own clock (`everyMs`, default 5 s, bounded at 5 s) and serves at `/api/home/widgets.json`, and the overview mounts each in its monitor area. BREAKING: the `home.resources` key is removed; `defineRepo` refuses `home` and names the unit file that replaces it. pm's `/api/pm/resource` takes `act`: start, stop, restart, open or action.
+
+- **Switching repos on the home is instant.** Each hub keeps its rows (`/api/resources.json`), its runs page (`/api/timeline.json`) and its wiki graphs warm in memory (`WarmCell`, `src/serve/warm-cell.ts`): computed when the hub loads, one hub after another, recomputed in the background after a save burst settles, when the config or the run record stamp moves, or past `WARM_MAX_AGE_MS` (2 minutes), and served from memory, so a request never walks the repo. `?fresh=1` waits on a walk that includes a change the page just made, and the page asks it after an act, a run that ended and a config write. The page reads ahead the first screen of every other repo whose hub is up, one repo and one step at a time, once the shown repo has its own, and a repo read ahead mounts nothing until it shows. The tree, the page links, the runs page, the wiki frame and the wait line show a spinner where they will be. `HubHandler` gains `invalidate()` and `warm()`, `HubDeps` gains `stamp`. Measured on the live home: a first visit went from 80 to 380ms to 38 to 80ms, the runs page from 1.6 to 3.0s to under 110ms.
+
+- **Every repo has identity colours, and the home strip holds only what it should.** `repo.config.ts` declares `identity: { colorLight, colorDark }`, one `#rrggbb` each. New rule SK024 (`identity colors`, non-blocking) warns when they are missing or malformed; `shipkit check --fix SK024` derives them from the dominant hue of the repo icon, else from a hue hashed from the name, and writes that one key as one line, every other byte kept. The daemon fills each repo it loads the same way and never commits. A repo whose installed copy does not know the key is never written into. The home strip now holds `home` and `planned` (always there, the current one marked), the shown repo's icon and its name in its colour with two swatches that write the colours back (`POST /api/projects/identity`), and on its right only machine trouble: pm or the daemon down, a child or a resource crashed. Restart, the active flag, VS Code and modernize moved to the repo's own header, the resource switches and `new window` to the overview. The rail frames the shown repo's tile in its colour. `⌘K` opens the same picker as `⌘J`, which now lists the shown repo's targets, then `home`, `planned` and every other house repo.
+
+- **The home page is one app over one state tree.** A rail click shows another repo in place: no page load, the rail and the strip stay mounted, and a repo you come back to shows the page, filter, search and scroll it had. `HomeSt` is the root (`window.app`) for `/`, `/planned` and `/r/<repo>/`, with one `RepoSt` per repo visited, and only the shown repo polls. Every request of a repo goes through `RepoSt.url()`. The web serves one page at all three routes (`serveWeb({ page })`), and a hub of its own renders the same app with one repo and no machine.
+
+- **`shipkit gui` is its own macOS app.** Built once with swiftc into `~/Applications/Shipkit.app`, with the house repo's mark as its icon, so the dock and cmd-tab show shipkit instead of a second Chrome. Chrome's app mode stays the fallback.
+
+- **A boot never fires everything at once.** Work overdue when the plan starts is spread over the next 2 hours, and a check with no cadence runs at a stable point of 20h to 28h.
+
+- **The json answer import proves every file against its own hash.** Two check ids that slug alike can no longer share one row, and the import never overwrites a fresher row.
+
+- **Machine state lives in one machine database.** The repos flagged active and the pid records pm, the resources and a repo's dev servers are adopted from now live in `~/.config/shipkit/shipkit.sqlite` (beside `SHIPKIT_HOME_DIR` when it is set, or at `SHIPKIT_MACHINE_DB`). The json and pid files an older version wrote are read once and deleted, so a running pm adopts its children across the update. `ProcSpec.pidFile` is renamed `pidKey`.
+- **Nothing shipkit writes grows unbound.** Every store has a declared cap: the answers and the run record in the repo db, the attach slots, the run logs (40 runs, 6 hours), the job folders (100, 7 days), the scratch git indexes, the dev server logs, and on a machine with a home its logs and the gui window's Chrome profile. The daemon sweeps them all on boot and hourly, and a gate still sweeps what it writes. New rule SK023 (`stores under cap`, health) fails when a store is past its cap plus one sweep's drift; `shipkit check --fix SK023` runs the sweep. The old json answers are imported once (the last day's) and deleted.
+- **Cached answers live in the repo's database.** The one json file per cached answer under `.git/shipkit/store` is replaced by an `answers` table in the same `shipkit.sqlite` as the run record. Anything that makes the table unreadable (a corrupt or locked file, a missing row) means the check runs, never a replay and never a red. Answers nobody used for 14 days are dropped, and a repo keeps at most 5,000. The run record keeps 30 days and at most 200,000 rows per table.
+- **A repo's installed copy hands the command to the house source.** `node_modules/.bin/shipkit` and the `.shipkit/hooks` run a repo's own `rvlib-shipkit` cli directly, past the machine launcher. That cli now replaces itself (same pid, same argv) with the house cli the launcher runs, so every repo runs one version. A house checkout runs its own source, and CI, `SHIPKIT_NO_HOME` or a machine with no house run the installed copy. The page no longer says "daily pass": a health check runs each time the plan runs it.
+- **One shipkit version per machine, and any command starts pm.** The cli routes every `rvlib-shipkit` import a repo config makes to the copy that runs, so a repo's own install is never loaded beside it, and new rule SK022 warns when a repo pins or installed a version newer than the running one: the pin is a minimum. Before any command the cli probes pm on its port and, when it is down, kicks its LaunchAgent, or installs it from the house repo the first time. Skipped under CI, `SHIPKIT_NO_HOME=1`, inside a process pm started, off macOS, and after `shipkit pm uninstall`, which stays in force until `shipkit pm install`. `SHIPKIT_LAUNCH_AGENTS_DIR` moves where the agent is written.
+- **The plan replaces the daily pass and the save trigger.** A check declares when it runs beside what it reads: `every: '24h'`, a range `every: ['10h', '12h']` (each repo and check lands on a stable point inside it, so checks spread out), `cron: '0 9 * * 1'`, null for on change only, or a pure function of its last result (`status`, `at`, `streak`) and whether the repo is active, returning any of those. `whenInactive: 'run' | 'wait'` (default wait, also a lambda) says what a due check does while its repo is inactive: wait turns it late and runs it once an agent works in the repo, VS Code has it open, or it is flagged active. With nothing declared, a `ttl` reads as its `every`, a build step runs on change only, and any other check runs every 24h. A bad value dies when the check file loads; a lambda that throws is an error on its row, and the check runs on change only. The daemon keeps ONE plan for the machine: every repo and check pair with its next due time and why (`changed`, `scheduled`, `late`, `asked`), and runs what is due as one background batch per repo through the gate jobs. A save makes due only the checks whose cached answer would not replay. The page `/planned` (the `planned` link in the header strip) shows the whole plan, filterable by repo: running, due, late, next with its time, each row with its reason and the rule that planned it (for a lambda, the value it returned and the state that chose it); a click runs it now. The check page's `next run` reads the same row. `HealthSchedule`, `GateTrigger` and `lastHealthPassAt` are deleted; the save watch lives in `serve/tracked-watch.ts`.
+- **Every gate in the daemon is a detached job, so a daemon reload never kills one.** A terminal `shipkit ci` or `shipkit check`, a save trigger, the daily pass and a button on the page each start `shipkit ci --job <id>` (or `check --job <id>`) in the background, the same mechanism as `--detach`, with its options in the job folder. The daemon runs one job at a time per repo, a background one takes the machine's one background turn inside the job, and it follows the job's `out.log` and `checks.ndjson` into the terminal, the page and the problems pane. A new daemon image follows the jobs still running when it boots, and queues behind them. A terminal whose stream the daemon cut (a reload, `kill -9`) reads the rest from the job folder and exits with the gate's own code; a cut before the job started sends the run again once the daemon is back. The daemon now reloads on its own code at once, gates or not. `SHIPKIT_DAEMON_ONLY=a,b` loads only those house repos.
+- **A hub that crashed on a broken `repo.config.ts` loads again once the file is edited**, as a working hub reloads on an edit. It stayed crashed until a restart by hand.
+- **`shipkit pm`, the machine's process manager.** It runs `shipkit daemon` and `shipkit web` as detached children with pid files, starts one again when it dies (backoff, left down after 5 crashes in 5 minutes), and owns the machine resources (`home.resources`), which moved out of the daemon. Its api answers on port 4797 (`SHIPKIT_PM_PORT`): the status of each child and resource, start, stop and restart of a child, the resource switches. The web proxies `/api/pm/*` to it, and the overview shows pm, the daemon and the web with a restart button each. pm killed or restarted leaves its children running, and the next pm adopts them; a stop asked of pm (SIGTERM, `shipkit pm uninstall`) stops them. `shipkit pm install` writes the LaunchAgent `com.shipkit.pm`, which runs `bun <cli> pm` and replaces the `com.shipkit.home` agent. `shipkit home`, `home install` and `home uninstall` stay as names of the pm commands. `shipkit gui` starts pm when the web does not answer and waits for the web.
+- **pm, the daemon and the web each reload alone.** None runs under a bun watch, which follows every command through `cli.ts`. Each watches the lib files its own runner imports and restarts in place, same pid, on an edit of one of them: a page edit restarts the web, a runner edit the daemon (a gate in flight keeps running, see gate jobs), a supervisor edit pm, which adopts its children.
+- **pm stays small.** It reads the house repo's `home.resources` in a child process and never loads the repo config, and `shipkit pm` replaces its own image with pm's entry file, so pm runs in about 35 MB and reloads only on its own few files. Its boot lines say `adopted` for a child it took from a pid file. A stop or restart of the web asked from the page answers before the web goes down, so the page no longer shows a fetch error for a restart that worked.
+- **A supervised process is started through a shell that exits at once**, so it belongs to init from its start, in its own process group. A process started before its supervisor restarted in place stayed a zombie of the new image and read alive forever, so a crash was never restarted. A pid file whose pid a process started after the record now holds is no longer adopted.
+- **A daemon that hangs reads as down on the page: the web waits 5s for the home api and 30s for a repo request, runs excepted, and the page's poll gives up at 8s. The web learns the repo pages once the daemon first answers, and follows the list after that. A failed poll with the daemon up shows its error and no longer reloads the page.
+- **One app for every repo on the machine: `shipkit daemon` and `shipkit web`.** Run from the repo that hosts the house wiki. `shipkit daemon` loads every repo's hub and answers every api on an internal port (4798, `SHIPKIT_DAEMON_PORT`); `shipkit web` serves the page on port 4799 (`SHIPKIT_HOME_PORT`) and proxies every `/api/*` and `/r/<repo>/…` request to the daemon, run streams included, so a browser only ever sees one origin. `shipkit pm` runs both. A daemon that is down reads as a clear error on the page, which reloads itself once the daemon answers again. A terminal gate talks to the daemon directly, so it never depends on the web. The daemon loads every house repo's hub at boot, one after the other, and serves each under `/r/<repo>/` of its one server: the page, `/api/*`, `/graph/*`, `/media/*` and `/hub.json`. A boot runs no gate: a repo's background gate starts on a save in it, and the daily pass and the RED pings run for ACTIVE repos only (an agent works in it, or it is flagged active). A repo whose config fails to load reads crashed with its error while the others serve. The page has no frames: `/` is the overview of every resource and repo with its state, and `/r/<repo>/` is that repo's own hub page carrying the rail (read from the machine wide `/api/projects.json`) and a home strip over its header, with the resource switches and, for the shown repo, restart, the active flag, VS Code and modernize. A rail click goes to that repo's page, a double click opens VS Code. A repo whose hub cannot load shows why and the fix in place of its page. The home repo declares the machine resources in `home.resources`. `shipkit pm install` adds a macOS LaunchAgent that keeps it alive. Resources and repo processes run detached with a pid file, so the next pm or daemon adopts them.
+- **`shipkit serve` attaches to a running home.** It hands the hub to the home and streams its log, the last problem frame first, so a VS Code folder-open task keeps its problems pane with no change to `tasks.json`. A worktree, `--port` and `SHIPKIT_NO_HOME=1` serve in process as before.
+- **`serve.processes`: a repo's dev servers, supervised by its hub.** One switch each in the hub header, crash restart with backoff, adopted across a hub restart. **`serve.uses`** names the machine resources a repo needs, and the home rail marks it while one is off.
+- **`shipkit gui [repo|.]`: the home in its own window.** A Chrome app window on its own profile (the default browser when Chrome is absent), one more per call and per `new window` in the header. It starts the home when none runs, installing its LaunchAgent the first time from the house repo.
+- **On a machine with the home, no hub runs outside it.** `shipkit serve` hands off, starting an installed home that is down, and never serves in process there. A process the home started, linked worktrees, machines without a home and `SHIPKIT_NO_HOME=1` serve as before. `SHIPKIT_USE_HOME=1` sends hubs and gates to the home on `SHIPKIT_HOME_PORT` on a machine with no LaunchAgent.
+- **The daemon reloads one repo at a time.** An edit of a repo's `repo.config.ts` reloads that hub alone, once its gate is done, its processes kept. The daemon warns while it runs under a bun watch.
+- **A hub stopped by hand stays down** until a restart: its page no longer loads it again, and a stop during a load wins over the load. `/r/<name>/` answers 404 for a name that is not a house repo, never a page whose every call fails. The home's view of a hub drops its dead `external` and `restarts` fields.
+- **One copy of the lib in the home.** Before any repo config loads, a Bun resolver hook routes every `rvlib-shipkit` import (the bare name, an export alias, a subpath) to the home's own copy, so a repo's own install is never loaded and each lib module has one instance.
+- **The hub page works under a base path.** Every request it makes goes through one helper that reads `/r/<repo>` from its own address, so the same page serves standalone at `/` and in the home.
+- **On a machine with the home, `shipkit ci` and `shipkit check` run in the repo's hub, in the home.** They POST to `/r/<repo>/api/run`, and the terminal streams the hub's lines and takes its exit code, so every gate of a repo runs in one process and feeds one problems pane. What runs in process: a process the home started (a check's child, a script calling shipkit), CI, a linked worktree, `SHIPKIT_NO_HOME=1`, a machine without the home, a repo the home cannot load, and `check --fix`, `bump`, `release`. An unreachable home is a loud failure, never a quiet local run.
+- **Background gates take turns on the whole machine.** The save trigger and the daily pass of every hub wait for one shared turn, so several hubs never gate at once. A gate someone asks for never waits for it. A hub start feeds the same quiet window as a save, so a burst of restarts is one run.
+- **The rail: a single click selects, a double click opens VS Code.** On a hub serving on its own, a click opens that repo's page on the home when one serves.
+
+- **The project rail has three sizes.** A button pinned to the foot of the rail shows three dots, the current size lit, and a click cycles small (44px rail, 24px icons), medium (76px, 56px) and large (132px, 112px). The browser keeps the choice in `localStorage` `hub:rail`. Every size is a literal of the rail's class in `project-gutter.css`, never an inline value, and each icon carries its size as `width` and `height` attributes with `object-fit: contain`, so a 512px icon file never draws at its natural size, even when the sheet does not apply. `tests/browser/hub-layout-check.ts` measures all of it in headless Chrome.
+
 ## 1.1.1
 
 - **The project rail reads `.shipkit/identity/icon.png` first.** A repo with no public surface has no favicon, so the rail showed its initial. `ICON_FILES` now starts with `.shipkit/identity/icon.png`, ahead of `public/favicon.png`, so a repo can carry a rail icon without shipping a public folder.

package/README.md

@@ -81,7 +81,7 @@ Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with ind
 
 ## Release contracts
 
-A venue contract is data: required files, exact PNG dimensions (header-parsed, no image dependency), glob minimums, required markdown sections. Enforcement is both ways — a declared venue with an incomplete folder fails, and an undeclared venue whose signals fire (deploy scripts, folders) fails too. `exempt: { steam: "reason" }` skips visibly. Wire venue deploys as `deps: ['contracts']` and an incomplete folder physically blocks the upload.
+A venue contract is data: required files, exact PNG dimensions (header-parsed, no image dependency), glob minimums, required markdown sections. Enforcement is both ways — a declared venue with an incomplete folder fails, and an undeclared venue whose signals fire (deploy scripts, folders) fails too. `exempt: { steam: "reason" }` skips visibly. Wire venue deploys as `deps: ['SK002']` and an incomplete folder physically blocks the upload.
 
 Ship your own contracts via `contracts: { extra: [defineContract({...})] }` — see `rvlib-shipkit/contracts` for the rule vocabulary.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.1.1",
+    "version": "1.3.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",
@@ -33,6 +33,7 @@
         "test:raw": "bun test"
     },
     "dependencies": {
+        "@floating-ui/react": "^0.27.20",
         "@napi-rs/canvas": "^1.0.2",
         "clipanion": "^4.0.0-rc.4",
         "comfy-ts": "^2.9.0",
@@ -42,6 +43,7 @@
         "mobx-react-lite": "^5.0.0",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
+        "react-resizable-panels": "^4.13.3",
         "sanitize-html": "^2.17.6",
         "sharp": "^0.35.3"
     }

package/src/assets/run-assets.ts

@@ -236,14 +236,9 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
                         io.print(`WARN no schema cache for host '${lw.wf.host.data.id}' — bunx comfy-ts gen --id ${lw.wf.host.data.id} --host ${lw.wf.host.getServerHostHTTP()}`)
                     }
                 }
-                try {
-                    for (const url of new Set([...wfs.values()].map((lw) => lw.wf.host.getServerHostHTTP()))) {
-                        const up = await fetch(`${url}/system_stats`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok).catch(() => false)
-                        io.print(up ? `ok: comfy backend reachable (${url})` : `WARN comfy backend unreachable (${url})${kit.comfy.heal != null ? ` — ${kit.comfy.heal}` : ''}`)
-                    }
-                } finally {
-                    disconnectAll({ workflows: wfs })
-                }
+                // whether the backend answers is a machine fact the house repo's
+                // box check owns, never a question about this repo's kit
+                disconnectAll({ workflows: wfs })
             }
         }
         // machine-clearable red clears itself: drifted/missing identity

package/src/check.ts

@@ -20,7 +20,8 @@
 // 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 type { Line } from './core/wire.ts'
+import { planDeclProblem, type Every, type WhenInactiveDecl } from './plan/cadence.ts'
+import { FOREVER, parseDuration, 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'
@@ -97,7 +98,10 @@ export type CheckDef = {
      *  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'. */
+     *  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. */
@@ -108,6 +112,36 @@ export type CheckDef = {
      *  key, and every other check shares one answer between a frozen run and
      *  a normal one. 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. */
@@ -179,6 +213,10 @@ export function check(d: CheckDef): CheckDef {
     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}`)

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

@@ -13,6 +13,7 @@
 import { canonicalBodies, conditionalBodies, inferBin, ROUTED_SCRIPTS, rawName, routedBody, routesToShipkit } from '../core/canonical-scripts.ts'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type FixResult } from '../check.ts'
 
@@ -24,7 +25,7 @@ const OWNER = 'meta/rv-conventions/package-json.md'
 // alias really is the canonical capability (a `serve` that serves a dist/
 // folder must not be told to rename)
 const ALIASES: Record<string, { canonical: string; bodyMatch: RegExp }> = {
-    'serve': { canonical: 'hub', bodyMatch: /(shipkit|cli\.ts) serve\b/ },
+    'serve': { canonical: 'hub', bodyMatch: /(?:^|\s)(?:shipkit|\S*shipkit\S*\/cli\.ts) serve\b/ },
     'pretty': { canonical: 'fmt', bodyMatch: /./ },
     'check-types': { canonical: 'typecheck', bodyMatch: /./ },
 }
@@ -46,6 +47,15 @@ export function evaluatePackageJson(t: CheckCtx): void {
         return
     }
     const scripts = pkg.scripts ?? {}
+    // a package whose root unit declares npm is a public contract: it
+    // publishes, so the app field rules invert, and its script names are its
+    // own vocabulary, which no house name or route may rewrite
+    if (rootPublishesNpm(c)) {
+        if (pkg.private === true) t.fail(`package.json: the root unit declares release.npm, and "private": true makes npm refuse the publish`)
+        if (pkg.license == null) t.fail(`package.json: a package published to npm declares its license`)
+        if (!t.failed) t.ok(`package.json shape ok (published to npm: publishable, license ${pkg.license})`)
+        return
+    }
     // rvlib-* as a probe ROOT is theoretical (libs live as sub-packages and
     // the probe only runs where repo.config.ts loads) — field inversion is
     // still handled so a future lib-root repo fails correctly, not absurdly
@@ -177,14 +187,15 @@ export const packageJsonShape = check({
     fix: (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' }
         let pkg: Pkg & { scripts?: Record<string, string> }
         try { pkg = JSON.parse(raw) as Pkg } catch { return { changed: false, summary: 'package.json unparseable — repair it by hand first' } }
         if (pkg.name?.startsWith('rvlib-') === true) return { changed: false, summary: 'rvlib-* package — license/private are publish decisions, not autofixable' }
         const changes: string[] = []
         const notes: string[] = []
         // any "I am published" marker → the field flips are a publish
-        // decision, not a mechanical repair (the LIBRARY-profile gap in
-        // meta/gaps.md is still open)
+        // decision, not a mechanical repair (a package that publishes says so
+        // with release.npm, which skips this fixer outright)
         const publishMarkers: string[] = ['files', 'exports', 'publishConfig'].filter((k) => (pkg as Record<string, unknown>)[k] != null)
         if (pkg.scripts?.['prepublishOnly'] != null) publishMarkers.push('prepublishOnly')
         if (publishMarkers.length > 0) {

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

@@ -2,9 +2,9 @@
 // registration point; the evaluation machinery stays in
 // contracts/contracts-engine.ts (venue manifests are DATA rows, not rules —
 // one SK id covers the invariant "declared contracts are fulfilled, folders
-// can't rot undeclared"). Every surface reporting fulfillness (`check`,
-// `shipkit contracts`, the ci `contracts` check) tags with this id via
-// contracts/apply-contracts.ts.
+// can't rot undeclared"). Every surface reporting fulfillness (`check`, `ci`,
+// `shipkit contracts`) tags with this id via contracts/apply-contracts.ts. A
+// venue deploy step deps on it BY ID (`deps: ['SK002']`).
 import { applyContractsResult, contractsResult } from '../contracts/apply-contracts.ts'
 import { check } from '../check.ts'
 

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

@@ -16,6 +16,7 @@
 // `c.exec` is never stored on its reads.
 import { readdirSync } from 'fs'
 import type { RepoConfig } from '../repo-config.ts'
+import { declaredPublic } from '../core/repo-facts.ts'
 import { GENERATED_IGNORE_LINES, GENERATED_TRACKED_PATHS, untrackGenerated } from '../rules/untrack-generated.ts'
 import { check, type CheckCtx, type FixResult } from '../check.ts'
 import { gitBin } from '../core/git-bin.ts'
@@ -29,6 +30,8 @@ const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit ou
 const END = '# <<< shipkit gitignore policy'
 const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
 
+const DRAFTS_BACK = '!.comfy-ts/drafts/'
+
 export const POLICY_LINES = [
     // everything shipkit keeps lives under .shipkit/ (core/layout.ts). Local
     // by default: the private notes, drafts, venue listings and caches, and the
@@ -62,7 +65,7 @@ export const POLICY_LINES = [
     // steps and cfg, so it is authored state and belongs in the repo, unlike the
     // schema dump, the lora previews and the raw run outputs beside it
     '.comfy-ts/*',
-    '!.comfy-ts/drafts/',
+    DRAFTS_BACK,
     '*.loras.local.txt',
     // shipkit's own per-run output. Ignoring is only half of it: the fixer
     // also removes these from the index, because .gitignore does nothing to a
@@ -70,6 +73,11 @@ export const POLICY_LINES = [
     ...GENERATED_IGNORE_LINES,
 ]
 
+/** the policy one repo carries. A declared public tree ships to strangers,
+ *  so the drafts stay ignored there: a draft holds the prompts and values
+ *  behind generated assets, authored state in a private repo */
+const policyLines = (config: RepoConfig): string[] => declaredPublic(config) ? POLICY_LINES.filter((l) => l !== DRAFTS_BACK) : POLICY_LINES
+
 const LEGACY = '# the old root layout, ignored until the fix pass moves it under .shipkit/'
 
 /** `legacy`: the repo still carries contract folders at its root from before `.shipkit/`. Their names
@@ -77,11 +85,11 @@ const LEGACY = '# the old root layout, ignored until the fix pass moves it under
  *  that is newer than the tree it guards */
 export function expectedBlock(config: RepoConfig, legacy = false): string {
     const extra = config.gitignore ?? []
-    return [BEGIN, ...POLICY_LINES, ...(legacy ? [LEGACY, ...LEGACY_IGNORED] : []), ...(extra.length > 0 ? [CONTRIB, ...extra] : []), END].join('\n')
+    return [BEGIN, ...policyLines(config), ...(legacy ? [LEGACY, ...LEGACY_IGNORED] : []), ...(extra.length > 0 ? [CONTRIB, ...extra] : []), END].join('\n')
 }
 
 export function policyPatterns(config: RepoConfig, legacy = false): string[] {
-    return [...POLICY_LINES.filter((l) => !l.startsWith('#')), ...(legacy ? LEGACY_IGNORED : []), ...(config.gitignore ?? [])]
+    return [...policyLines(config).filter((l) => !l.startsWith('#')), ...(legacy ? LEGACY_IGNORED : []), ...(config.gitignore ?? [])]
 }
 
 /** does the root still hold a contract folder from before `.shipkit/` */

package/src/checks/SK005-rvlib-versions.check.ts

@@ -48,6 +48,7 @@ import { basename, join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { allowMajor, breakingAdvice, isBreaking } from '../core/update-policy.ts'
 import { isRunningCopy, rememberLatest } from '../core/self-update.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import { mutateLease, withMutateLease } from '../core/locked-write.ts'
 import { detectPackageManager, isRefusal, LOCK_FILES } from '../core/package-manager.ts'
 import { check, type CheckEnv } from '../check.ts'
@@ -77,6 +78,11 @@ export const rvlibVersions = check({
     ttl: '24h',
     // it updates the rvlib deps unless the run is frozen
     writes: true,
+    planOff: (env) => {
+        let pkg: Pkg
+        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'no readable package.json' }
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).some((n) => n.startsWith('rvlib-')) ? null : 'no rvlib-* dependency'
+    },
     cacheKey: (env) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
@@ -84,7 +90,7 @@ export const rvlibVersions = check({
             .filter((n) => n.startsWith('rvlib-'))
             .sort()
             .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
-            .join(',')
+            .join(',') + (rootPublishesNpm(env.config) ? ' npm' : '')
     },
     run: async (c) => {
         let pkg: Pkg
@@ -137,6 +143,12 @@ export const rvlibVersions = check({
             c.warn(`newer rvlib live: ${drift} (frozen — apply with: ${cmd.join(' ')})`)
             return
         }
+        // a package published to npm: its package.json is its public
+        // contract, so the bump is a release decision, named and never made
+        if (rootPublishesNpm(c.config)) {
+            c.warn(`newer rvlib live: ${drift} (published to npm, never updated by a check — apply with: ${cmd.join(' ')})`)
+            return
+        }
         const dirty = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
         if (dirty.code !== 0 || dirty.out.trim() !== '') {
             c.warn(`newer rvlib live: ${drift} — self-update deferred (${dirty.code !== 0 ? `git says: ${dirty.out.trim().split('\n')[0] ?? `exit ${dirty.code}`}` : 'package.json/lockfile dirty'}); commit first, then re-run check`)

package/src/checks/SK006-npm-publish-safety.check.ts

@@ -15,6 +15,7 @@
 import { join, relative } from 'path'
 import { checkUnitReader, resolveUnits } from '../release/unit-resolve.ts'
 import { check } from '../check.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 
 type Pkg = {
     name?: string
@@ -65,6 +66,10 @@ export const npmPublishSafety = check({
             if (localHits.length === 0) c.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
             return
         }
+        if (rootPublishesNpm(c.config)) {
+            if (localHits.length === 0) c.ok('the root unit declares release.npm: publishes by design, no local dependency protocol in any releasing unit')
+            return
+        }
         if (pkg.private !== true) return c.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')

package/src/checks/SK007-github-visibility.check.ts

@@ -8,8 +8,9 @@
 // own base-repo resolution prefers `upstream`, which in a fork-shaped
 // checkout would confidently validate the WRONG repository. Flipping a
 // repo public stays a human act behind the pre-public audit; this rule is
-// the standing tripwire if it ever happens out of band. Clean passes cache
-// 7d, keyed on the declared value (a flip re-probes immediately); every
+// the standing tripwire if it ever happens out of band. A decided fact: a
+// clean pass is kept forever, keyed on the declared value (a flip re-probes
+// immediately, and the plan asks only while no answer exists); every
 // unverifiable path (no git, no remote, non-github remote, gh missing or
 // erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
 // never cached.
@@ -17,20 +18,19 @@ import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
 import { probeGitRoot } from '../core/git-root.ts'
 import { nestedIn } from '../core/nesting.ts'
 import { check } from '../check.ts'
+import { declaredVisibility } from '../core/repo-facts.ts'
 
 export const githubVisibility = check({
     id: 'SK007',
-    // blocking despite being measured over the network: the fact is about THIS
-    // REPO (it is public while it declares itself private), and every
-    // unverifiable path above is a skip, so an offline machine never goes red
-    blocking: true,
+    // a gate block does not un-leak a repo: the red shows on the needs surface
+    blocking: false,
     title: 'github visibility',
     description: 'the github visibility of this repo matches the one it declares',
     owner: 'meta/contracts.md',
-    ttl: '7d',
-    cacheKey: (env) => env.config.visibility ?? 'private',
+    ttl: 'forever',
+    cacheKey: (env) => declaredVisibility(env.config),
     run: async (c) => {
-        const declared = c.config.visibility ?? 'private'
+        const declared = declaredVisibility(c.config)
         const skip = (why: string): void => void c.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
         const firstLine = firstGhLine
         const repo = probeGitRoot(c.root)

package/src/checks/SK008-reviewer-agent.check.ts

@@ -8,12 +8,13 @@
 // harness then inherits every tool. The brief itself must exist. No
 // declaration = not a reviewer repo, and the rule passes silently.
 import { existsSync, mkdirSync, readFileSync } from 'fs'
-import { homedir } from 'os'
-import { dirname, isAbsolute, join } from 'path'
+import { dirname, join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type FixResult, type CheckEnv } from '../check.ts'
 import { LAYOUT } from '../core/layout.ts'
 import { atomicWrite } from '../core/locked-write.ts'
+import { configPath, fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
 
 /** where a review lands when its caller named no output file:
  *  `YYYYMMDD-HHMMSS-<review-name>.md`, local time, gitignored */
@@ -48,8 +49,7 @@ export function reviewerAgentIssues(text: string, reviewer: NonNullable<RepoConf
 /** the brief must EXIST: a reviewer whose mandated first action is reading a
  *  missing file flounders silently, which is the one thing this rule prevents */
 export function briefMissing(root: string, brief: string): boolean {
-    const p = brief.startsWith('~/') ? join(homedir(), brief.slice(2)) : isAbsolute(brief) ? brief : join(root, brief)
-    return !existsSync(p)
+    return !existsSync(configPath(root, brief))
 }
 
 function canonicalAgent(reviewer: NonNullable<RepoConfig['reviewer']>): string {
@@ -83,12 +83,18 @@ That brief overrides any habit of reviewing a diff for correctness alone.
 export const reviewerAgent = check({
     id: 'SK008',
     blocking: true,
-    title: 'reviewer agent',
+    title: 'reviewer definition',
     description: 'the declared reviewer agent has its brief, its definition and read only tools',
     owner: 'identity/how-we-work.md',
-    // the brief is a CONFIG path, and a `~/...` or absolute one puts it
-    // outside the repo, where no tree id can see whether it still exists
-    never: 'the reviewer brief may live outside the repo, where no tree id reaches it',
+    // the answer is the config, the definition file and the brief. The brief
+    // is a CONFIG path that may sit outside the repo, so both files enter the
+    // key by content, wherever they live
+    inputs: [CONFIG_FILE],
+    cacheKey: (env) => {
+        const r = env.config.reviewer
+        if (r == null) return 'no reviewer'
+        return `${r.name}|${(r.tools ?? REVIEWER_TOOLS).join(',')}|def=${fileStamp(join(env.root, reviewerAgentPath(r.name)))}|${r.brief}=${fileStamp(configPath(env.root, r.brief))}`
+    },
     run: (c) => {
         const r = c.config.reviewer
         if (r == null) return c.ok('no reviewer agent declared (repo.config reviewer:) — skipped')