rvlib-shipkit 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## 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.

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.2.0",
+    "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",

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

@@ -21,7 +21,7 @@
 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 type { Line } from './core/wire.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'
@@ -98,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. */
@@ -112,13 +115,16 @@ export type CheckDef = {
     /** 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'`), or null for on change
-     *  only. Or a PURE function of its last result (`status`, `at`, `streak`
+     *  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 waits for a save and
-     *  any other check runs every 24h. */
+     *  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`. */
@@ -130,6 +136,12 @@ export type CheckDef = {
      *  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. */
@@ -201,6 +213,8 @@ 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) {

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')

package/src/checks/SK009-commit-ai-tells.check.ts

@@ -8,11 +8,16 @@
 // the ban — a green line must never teach the wrong rule. The remedy for
 // pushed history is the owner's decision, never an automatic rewrite; only
 // an unpushed tip commit may be amended, and the fails say so.
+import { createHash } from 'crypto'
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { hasAiAttribution, hasDashPunctuation } from '../hooks/commit-message.ts'
 import { nestedIn } from '../core/nesting.ts'
-import { check } from '../check.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { fileStamp } from '../core/file-stamp.ts'
+import { CONFIG_FILE } from '../core/check-pass.ts'
+import { check, type CheckEnv } from '../check.ts'
+import { declaredVisibility } from '../core/repo-facts.ts'
 
 // the documented silencer: .claude/settings.json attribution.commit/.pr both
 // empty — the harness then never writes the trailer or the PR footer
@@ -25,20 +30,39 @@ const attributionSilenced = (root: string): boolean => {
     }
 }
 
+/** what the answer depends on: the declared visibility, and for a public
+ *  repo the commit HEAD names, every ref name and the silencer. So a commit,
+ *  a fetch or a new tag asks again, and nothing else does */
+export function historyKey(env: CheckEnv): string {
+    const declared = declaredVisibility(env.config)
+    const nested = nestedIn(env.root)
+    if (nested != null) return `nested in ${nested}`
+    if (declared !== 'public') return `declared ${declared}`
+    const git = (args: string[]): string => {
+        const p = Bun.spawnSync([gitBin(), ...args], { cwd: env.root, stdout: 'pipe', stderr: 'pipe' })
+        return p.exitCode === 0 ? p.stdout.toString() : `exit ${p.exitCode}`
+    }
+    const refs = git(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/tags', 'refs/heads', 'refs/remotes'])
+    const head = git(['rev-parse', 'HEAD'])
+    const digest = createHash('sha256').update(head).update('\0').update(refs).digest('hex').slice(0, 16)
+    return `public|refs=${digest}|settings=${fileStamp(join(env.root, '.claude', 'settings.json'))}`
+}
+
 export const commitAiTells = check({
     id: 'SK009',
     blocking: true,
     title: 'commit ai tells',
     description: 'the history of a public repo carries no AI attribution and no dash punctuation',
     owner: 'identity/how-we-commit.md',
-    // it scans the full `git log` and every ref name. History and refs are not
-    // work-tree content, so nothing a scan can produce describes this answer
-    never: 'reads the full commit history and every ref name, neither of which is work-tree content',
+    // it scans the full `git log` and every ref name, which no tree id
+    // describes, so the refs themselves are the key
+    inputs: [CONFIG_FILE],
+    cacheKey: historyKey,
     run: async (c) => {
         const nested = nestedIn(c.root)
         if (nested != null)
             return void c.lines.push({ kind: 'skip', text: `commit history not scanned, nested in ${nested}: that history belongs to the parent repo` })
-        const declared = c.config.visibility ?? 'private'
+        const declared = declaredVisibility(c.config)
         if (declared !== 'public')
             return c.ok(`declared ${declared} — the no-AI-attribution ban still applies from commit one (identity/how-we-commit.md); the full-history scan arms at visibility: 'public'`)
         // %x1f separates hash from body, %x1e terminates the record — commit

package/src/checks/SK013-one-way-in-policy.check.ts

@@ -15,6 +15,7 @@
 import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
 import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { check, type CheckCtx, type FixResult } from '../check.ts'
 
@@ -95,8 +96,8 @@ async function guardScriptMissing(d: Disk, command: string): Promise<string | nu
     return null // a form this rule cannot resolve is not a form it may condemn
 }
 
-/** the guard the fixer writes: the cli path the scripts run when a guard sits
- *  beside it (a repo's own `src/cli.ts` matches the same shape), else the
+/** the guard the fixer writes: the shipkit cli path the scripts run when a
+ *  guard sits beside it, else the
  *  repo's own dependency, else the copy of shipkit doing the fixing, which is
  *  the one the launcher falls back to in a repo that has none */
 export async function guardCommandFor(d: Disk): Promise<string> {
@@ -109,6 +110,11 @@ export async function guardCommandFor(d: Disk): Promise<string> {
     return guardCommand(join(import.meta.dir, '..', 'cli.ts'))
 }
 
+/** a package published to npm is worked on by strangers: this file binds
+ *  their agents, and a deny list with a hook would tie them to a toolkit they
+ *  never installed */
+const PUBLIC_SKIP = `the root unit publishes to npm: ${SETTINGS_PATH} belongs to every contributor, so it is never written`
+
 export const oneWayInPolicy = check({
     id: 'SK013',
     blocking: true,
@@ -119,6 +125,7 @@ export const oneWayInPolicy = check({
     // the declared guard script resolves. A guard at an absolute path lives
     // outside the repo, so an answer that probed one is never stored
     run: async (c) => {
+        if (rootPublishesNpm(c.config)) return c.ok(PUBLIC_SKIP)
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return c.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
@@ -165,6 +172,7 @@ export const oneWayInPolicy = check({
     // a repo's own allow list and its own hooks, and clobbering those to fix a
     // deny list would cost more than the finding it repairs
     fix: async (c): Promise<FixResult> => {
+        if (rootPublishesNpm(c.config)) return { changed: false, summary: PUBLIC_SKIP }
         const d = c
         const want = denyRules(exemptSlots(c.config))
         if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }