@sleepy_panda_srl/portulan 0.1.1 → 0.1.3

package/cli/README.md

@@ -3,91 +3,114 @@
 The `npx` CLI that wraps the file-based mechanics for hosts beyond Claude Code:
 `init` (interview + codebase scan → drafted workspace) · `doctor` · `compile` (gates/verify → host
 enforcement) · `vendor` (materialise a workspace where it is needed — into a host, and the reverse) ·
-`index` · `upgrade` · `new` · `feedback`. That packaging is **milestone 7**, and as of session 0 the
-entry point exists:
+`index` · `upgrade` · `new` · `feedback`. The entry point is
 [`portulan.mjs`](portulan.mjs), reached as `portulan <subcommand>` through the `bin` in the
 repository's `package.json`.
 
-**`npx` is a live path as of 2026-08-18, and this file states that once rather than hedging every
-mention below.** `@sleepy_panda_srl/portulan@0.1.0` is on the registry, and
-`npx @sleepy_panda_srl/portulan` resolves — demonstrated from a directory containing no git repository
-at all, which is what milestone 7 named as undemonstrated and
-[#242](https://github.com/sleepy-panda-srl/portulan/issues/242) was filed to route.
-`node cli/<tool>.mjs` from a clone remains the invocation most measurements in this repository were
-taken through, and it still works; what changed is that it is no longer the only one.
-[`../.portulan/identity.md`](../.portulan/identity.md) carries what the `npx` path buys — the same
-bytes — and that is now **measured against the registry rather than against `npm pack` alone**: the
-published tarball and a fresh `npm pack` hash to the same value, and every file in them compares
-byte-for-byte
-([#149](https://github.com/sleepy-panda-srl/portulan/issues/149)). _(The roster the package ships is
-narrower than the tree and is not restated here as a number — `npm pack --dry-run` derives it, and a
-hand-copied count is the thing that keeps going wrong in this file.)_
-
-**All eight dispatch, as of milestone 7 session 9.** `doctor`, `compile` and `index` exist because
-milestones 2, 4 and 5 needed them; `init` was built at milestone 7 session 1, `new` at session 2,
-`vendor` at session 3, `feedback` at session 6, and `upgrade` — the last — at session 9. The entry
-point calls each one's exported `run` and returns the code unchanged.
-
-_This paragraph read **"Seven of the eight dispatch; one exits 2"** until `upgrade` landed, and what
-that sentence described is worth one line rather than none, because the state recurs: a subcommand may
-be named by `docs/vision.md` before the tree carries it, and while that holds the honest answer is to
-**list it and refuse** — exit 2, naming where it arrives. A stub exiting 0 would be a fail-open where a
-user is most likely to trust silence. `portulan.mjs` still carries that machinery (`module: null` plus
-`arrives`) and its suite still exercises the refusal, on a synthetic entry now that nothing real is
-unbuilt._
-
-**Why eight.** `docs/vision.md` names all eight and is human-owned. It named six until 2026-08-03:
-`new` and `feedback` reached the CLI first, licensed by row 7 naming them in its own ratified text, and
-the maintainer then folded both into the constitution — so the two-carrier state that licence created
-lasted one pull request. Worth one sentence rather than none, because the *shape* recurs: a subcommand
-may be licensed by the row before the constitution catches up, and while that holds, the tool has to say
-which document names it.
-
-Beside those eight sit **eight** runnable tools that are on none of the lists — `plugin-lint`,
-`librarian`, `control-chars`, `discover`, `rule-carriers`, `pack-version`, `eval-bundle` and
-`pack-identity` — because
-milestone 3, milestone 5, issue
-[#68](https://github.com/sleepy-panda-srl/portulan/issues/68), milestone 7's plugin-cache discovery,
-[`../.portulan/verify/rule-carriers.sh`](../.portulan/verify/rule-carriers.sh), the
-[#265](https://github.com/sleepy-panda-srl/portulan/issues/265) rail, and the maintainer's 2026-08-17
-ruling that the evaluation-bundle cutter lives in the public tree needed them.
-**Five** more files in this directory are neither subcommands nor tools: `gate` and `stop-gate` are the
-**compiled-hook runners**, invoked by generated host configuration rather than by a person, and
-`recipe-set`, `skills-set` and `manifest` are modules other tools import — the first two runnable in
-their own right, each printing the set it carries.
-
-_(Two counts moved at milestone 7 session 8 and both were wrong before it. The runnable tools read
-**four** while `rule-carriers` had been one since 2026-08-10 and appeared in this file **zero** times;
-the line below it read **two** while naming four. Corrected in the change that added a sibling rather
-than left to the next reader — the rule this repository applies to
-[`../.portulan/identity.md`](../.portulan/identity.md)'s rosters, and the one a first draft of this very
-parenthetical broke by invoking it while leaving `rule-carriers` uncounted. Found at the pre-commit
-checkpoint. A count is a claim, which is [#187](https://github.com/sleepy-panda-srl/portulan/issues/187)'s
-subject; the missing table rows are [#203](https://github.com/sleepy-panda-srl/portulan/issues/203)'s.
-**And it happened again**: the sentence above read **five** while `pack-version` had been runnable since
-2026-08-14 and appeared in it zero times — the session-open checkpoint for the change that added
-`eval-bundle` found the arrear, and the count moved six-then-seven in that one change rather than
-leaving the five for the next reader.)_
+**Two invocations, one behaviour.** `npx @sleepy_panda_srl/portulan <subcommand>` needs no checkout;
+`node cli/<tool>.mjs` runs from a clone, and is the invocation this repository measures itself
+through. [`../.portulan/identity.md`](../.portulan/identity.md) carries what the `npx` path buys —
+**the same bytes**. There is no build step, so every file the package ships is byte-identical to its
+tracked source — held on every commit by the `pack-identity` recipe, which refuses any packed file
+that differs from its staged blob. _(The roster the package
+ships is narrower than the tree and is not restated here as a number — `npm pack --dry-run` derives
+it, and a hand-copied count is the thing that keeps going wrong in this file.)_
+
+**What the payload leaves behind, and the criterion it leaves it behind on.** `package.json`'s `files`
+array excludes by name on top of the directory roster, under the rule set at the first publish — *the
+package ships the product, not the workshop*: a file that is not part of the product surface that an
+`npx` user runs does not travel. The suite and its fixtures went first, then `eval-bundle` and its licence
+template, on the eval payload's own reasoning — an evaluee receives the stamped licence, never the
+stamp press. `ab`, `ab-run` and `ab-grade` joined them on 2026-09-01.
+
+**The argument for the A/B trio is that the rig has one subject, and it is not the reader's
+repository.** `ab.mjs`'s `DISPOSITIONS` classifies *this* workspace's `.portulan/` path by path, and
+the table is compiled into the module rather than read from beside it: pointed at an adopter's
+workspace `--check` exits 2 and names every disposition that matched nothing. There is no
+configuration under which the trio does a consumer's tree any good — `ab-run`'s `SNAPSHOT` is one
+baseline, of one arm, on one date, and `ab.mjs` refuses to build an arm it cannot classify entirely.
+
+_**Not** because their registers resolve under `evals/`, which contributes nothing to the payload.
+That reasoning is already ruled out in this tree, and the exclusion holds **despite** it rather than
+because of it:_ [`eval-bundle.mjs`](eval-bundle.mjs)'s `EXCLUDED_TOP_LEVEL.evals` settled on 2026-08-24
+that **the tool is product and the policy it reads is this team's** — `goldens` ships without its
+corpus the way `compile` ships without `gates.json`. That distinction carries the whole load here:
+`readCorpus(repoRoot, dir = CORPUS_DIR)` takes its directory as an argument, so an adopter can point it
+somewhere; `ab.mjs`'s disposition table takes nothing and can be pointed nowhere.
+
+_**The exclusion is narrower than the criterion, and every module is now classified rather than
+merely counted.** The transitive import closure of [`portulan.mjs`](portulan.mjs) and its eight
+subcommands, less the two compiled-hook runners, leaves **fourteen** shipped modules reachable from
+nothing the package exposes. **Thirteen are `unruled`** — `control-chars`, `drills`, `fuzz-shell`,
+`goldens`, `librarian`, `mutants`, `pack-identity`, `pack-version`, `review-meter`, `rule-carriers`,
+`skill-goldens`, `telemetry` and `version-carriers` — most of them the `goldens` shape the 2026-08-24
+rule keeps, none put the question the A/B trio was, and whether any follows is the maintainer's call,
+the same sentence this file already makes about a ninth subcommand. **The fourteenth, `release-eval`,
+is `product`**: ruled to ship on 2026-09-01, which is what an answered one looks like beside thirteen
+unanswered.
+
+**The sentence that stood here is now false and is corrected rather than deleted**: it said *nothing
+derives payload membership*, which was true when it was written and stopped being true one pull request
+later. [`payload.mjs`](payload.mjs) classifies every shipped `cli/*.mjs` and the `payload` recipe holds
+it on every commit. What remains true is the narrower thing: `pack-identity` checks the packed
+**bytes** and is silent on the **roster**, which is why a module could join the tarball under a green —
+measured, by staging one and watching it. The `!` lines are still hand-maintained, but they are no
+longer unchecked._
+
+**All eight dispatch.** The entry point calls each one's exported `run` and returns the code
+unchanged.
+
+_A subcommand may be named by `docs/vision.md` before the tree carries it, and while that holds the
+honest answer is to **list it and refuse** — exit 2, naming where it arrives. A stub exiting 0 would be
+a fail-open where a user is most likely to trust silence. `portulan.mjs` carries that machinery
+(`module: null` plus `arrives`) and its suite exercises the refusal on a synthetic entry, nothing
+real being unbuilt today._
+
+**Why eight.** `docs/vision.md` names all eight and is human-owned, so the roster of subcommands is
+the constitution's to set and not an implementer's. A subcommand can be licensed by a milestone row
+before the constitution catches up; while that holds, the tool says which document names it.
+
+<!-- roster:begin -->
+<!-- THE PARTITION BELOW IS RAILED. `cli-roster.live.test.mjs` reads the bare backticked names
+     between these two markers and holds them against the tracked NON-TEST `cli/*.mjs` modules, in
+     both directions — a test file belongs in the table below, never in this block: a
+     file classified by none of the three — this prose, `portulan.mjs`'s `SUBCOMMANDS`, or
+     `portulan.mjs` itself as the entry point — fails, and a name here matching no file fails.
+     Rewrite the prose freely — the markers are the anchor, not the sentences. A name may leave
+     only when the file does. **No count is written here**, for the reason this file gives about
+     every other hand-maintained figure. -->
+Beside those eight sit the runnable tools that are on none of the lists — `plugin-lint`,
+`librarian`, `control-chars`, `discover`, `rule-carriers`, `pack-version`, `eval-bundle`,
+`pack-identity`, `version-carriers`, `goldens`, `skill-goldens`, `mutants`, `fuzz-shell`, `drills`, `review-meter`, `telemetry`, `payload`, `ab`, `ab-grade`, `ab-run` and `release-eval`. Each exists because a verify recipe or a
+packaging check needed it; none is reachable as `portulan <subcommand>`.
+The remaining files in this directory are neither subcommands nor tools: `gate` and `stop-gate` are
+the **compiled-hook runners**, invoked by generated host configuration rather than by a person, and
+`recipe-set`, `skills-set`, `manifest` and `inside` are modules other tools import — the first two
+runnable in their own right, each printing the set it carries, and `inside` a single predicate that
+lives alone so two large modules can both use it without importing each other.
+<!-- roster:end -->
+
+_(Those sentences carried hand-maintained counts, and the counts went wrong five times before
+[#204](https://github.com/sleepy-panda-srl/portulan/issues/204) retired them — each correction right
+on the day it landed, each stale within weeks. That is the argument for deriving the membership
+rather than correcting it once more, which is
+[#187](https://github.com/sleepy-panda-srl/portulan/issues/187)'s subject.)_
 
 Being off the list is a fact about `docs/vision.md`, which names these eight subcommands and is
-human-owned: whether any of the seven ever joins them is the maintainer's call and not an implementer's,
+human-owned: whether any of the others ever joins them is the maintainer's call and not an implementer's,
 so none is described here as *coming to the CLI* — and none is wired behind the entry point, which is
 the same rule expressed in code rather than in a sentence.
 
-**This paragraph is the one carrier of that roster.** It said *three* and named a different three from
-the two other places that also named one — `portulan.mjs` listed `plugin-lint`, `librarian` and
-`discover`; the root `README.md` listed `plugin-lint`, `librarian` and `control-chars`; four were on
-disk. One rule with three carriers is obeyed at the narrowest, and the repair is
-[`0020`](../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md)'s where the rule
-cannot be a function: state it once, and let the others cite. Both now cite this file.
-
-The table below is the check on it, and as of this change it is one: **every file in this directory has
-a row, and every row names a file that exists — save two, named in the next paragraph and declared to
-the rail rather than left as quiet exceptions.** The arrears are nil and
-[#203](https://github.com/sleepy-panda-srl/portulan/issues/203) is closed — and the figure is not
-stated here any more, because a number maintained by hand is the thing that kept going wrong. It is
-checked by [`../.portulan/verify/docs.sh`](../.portulan/verify/docs.sh), in **both directions**, on
-every run.
+**This paragraph is the one carrier of that roster**, and `portulan.mjs` and the root
+[`../README.md`](../README.md) both cite it rather than repeating it. One rule with three carriers is
+obeyed at the narrowest — the repair
+[`0020`](../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md) prescribes where
+a rule cannot be a function: state it once, and let the others cite.
+
+The table below is checked against this directory by
+[`../.portulan/verify/docs.sh`](../.portulan/verify/docs.sh) in **both directions**, on every run:
+every file here has a row, and every row names a file that exists — save two, declared to the rail
+rather than left as quiet exceptions.
 
 **Two exceptions are deliberate and are declared to the rail rather than worked around it.** This
 `README.md` has no row, because a file does not list itself; `fixtures/` has a row and is a directory
@@ -95,59 +118,43 @@ rather than a file, because what the table owes a reader there is one sentence a
 directory. A rail with an undeclared exception teaches the next person to widen the pattern until it
 stops complaining, so both are named in the recipe and either one disappearing is itself a failure.
 
-_(What this replaced is worth keeping, because it is the argument for the rail. The count read
-**eleven** at milestone 7 session 6, then **nine** for three sessions — each session adding rows for
-what it introduced and leaving the rest, correctly, rather than growing an unscheduled sweep inside a
-feature change. The number was also wrong twice in one session. It read **seven**, omitting
-`rule-carriers` and its suite; a first correction said **eight** and claimed to have been "re-derived by
-walking `cli/*.mjs` against the table" — but the walk matched the filename **anywhere in the table**, so
-`stop-gate.mjs` counted as having a row on the strength of a link inside `stop-gate.test.mjs`'s
-description. **A row is an anchor at the start of a line**, which is why the rail's pattern is anchored
-and why it extracts one subject per row rather than searching for names.
-And by the time this change came to clear the arrears, the figure was wrong once more: the tree held
-**ten** unrowed files against the nine this paragraph named and listed. The tenth was
-`pinned-roots.live.test.mjs`, which landed at session 12 and reached neither the table nor the sentence
-that counts the table's arrears — so the paragraph warning that a table falsified by its own directory
-is a claim not worth making had become one. That is the whole case for a rail: the count and the table
-drift by the same mechanism, so a hand-maintained figure about a hand-maintained table cannot be the
-check on it.)_
-
 ## What is here today
 
 | File | What it is |
 |---|---|
-| [`portulan.mjs`](portulan.mjs) | **The entry point** `package.json`'s `bin` names as `portulan` — the name a published package would expose, and publishing has not happened; added at milestone 7. It dispatches and adds nothing: each subcommand's module is imported **on demand** — so `portulan --help` does not pay for `doctor`, and a tool that fails to parse takes down only its own subcommand — and the tool's exit code is returned **unchanged**, because re-mapping it here would put a second opinion about a workspace between the tool and its user. Verified byte-identical to direct invocation for the three built subcommands it wrapped when it landed; `init` joined them at session 1 and is exercised through the entry point as well as directly. |
+| [`portulan.mjs`](portulan.mjs) | **The entry point** `package.json`'s `bin` exposes as `portulan`, which is how `npx @sleepy_panda_srl/portulan <subcommand>` reaches these tools. It dispatches and adds nothing: each subcommand's module is imported **on demand** — so `portulan --help` does not pay for `doctor`, and a tool that fails to parse takes down only its own subcommand — and the tool's exit code is returned **unchanged**, because re-mapping it here would put a second opinion about a workspace between the tool and its user. Verified byte-identical to direct invocation, and exercised through the entry point as well as directly. |
 | [`portulan.test.mjs`](portulan.test.mjs) | Its test suite, written first. **Dispatch only**: which module is reached, that arguments arrive unchanged, that exit codes come back unchanged, and that every refusal exits `2`. It injects the loader rather than shelling out, because re-asserting what `doctor` or `index` already prove would make this file a second carrier of it — with one deliberate exception, a case that imports the real modules to check they still export `run`, since that is the single assumption the entry point rests on. **Two cases spawn the real binary** — `init --help` and `feedback --help` — because injection can show that the dispatcher *would* reach a module and never that the module is reachable. The second of the two earned its place the hour it was written: it caught an import cycle that made `portulan feedback` exit 13 printing nothing, invisible to every injected case. |
 | [`manifest.mjs`](manifest.mjs) | The two facts read out of `package.json` — the `version` it declares, which is what a publish would carry rather than anything a registry has seen, and the repository derived from `bugs.url` that `feedback` files into. It exists as its own file rather than living in the entry point because a subcommand importing the entry point back is a **cycle**, and that cycle hung the command line on an unsettled top-level await. It imports nothing of ours, which is the property that makes it safe for anything here to import. |
-| [`init.mjs`](init.mjs) | **The onboarding subcommand**, added at milestone 7 session 1: it drafts a workspace for a repository that has none. It **asks** where that workspace resides — in the repository, or in a workspace that names it — and has **no default**, because a repository is governed by exactly one workspace and that answer is the one that cannot be guessed. It refuses ahead of the first byte written: never over an existing residence, and never a name, governor or pack id a validator would misread. What it emits is a **draft** — including a verify recipe that exits 2 until the adopting team declares what green means for them. |
+| [`init.mjs`](init.mjs) | **The onboarding subcommand**: it drafts a workspace for a repository that has none. It **asks** where that workspace resides — in the repository, or in a workspace that names it — and has **no default**, because a repository is governed by exactly one workspace and that answer is the one that cannot be guessed. It refuses ahead of the first byte written: never over an existing residence, and never a name, governor or pack id a validator would misread. What it emits is a **draft** — including a verify recipe that exits 2 until the adopting team declares what green means for them. |
 | [`init.test.mjs`](init.test.mjs) | Its test suite, written first. Its last group is the one that matters: it runs the real `doctor` against real drafted directories, in both residences, because a workspace nothing validated is a workspace nobody can trust. That group is what caught a drafted gate policy that parsed cleanly and compiled to a floor no rule reached. |
-| [`doctor.mjs`](doctor.mjs) | The Workspace Definition validator. Zero dependencies, no install step, run from the repository root. Two repeatable roots, one of which **is discovered unasked as of 2026-08-13** (this row said *named by default and never discovered unasked*, which was the state the disposal reversed): `--pack-root` is where declared packs are looked up, and `--repo-root` (2.7) is where the repositories a workspace's cards NAME are checked out, so the residence ruling's cross-repository refusal has somewhere to look. Without a `--repo-root` that check reports that it did not run rather than passing quietly. **One thing IS discovered, as of milestone 7 — a pointer's `governed_by`**, through [`discover.mjs`](discover.mjs); the row said *this tool does no discovery* until then. It is **reported and never graded**, so no host's install state moves this tool's verdict *through that channel* — a scope this row used to be able to leave implicit, because the pack root was discovered only when asked and nothing else here read a host. A pack root gained `auto` in the same milestone — `--pack-root auto` reads that record too, and `./auto` still names a directory. **Since 2026-08-13 a pack root is discovered whether or not `auto` is passed**, because row 7 makes `--pack-root` *optional where discovery finds a root* and it was not: on the workspace `init` drafts by default plus one pack of the adopter's own, this tool exited **1** bare and **0** under `auto`. What `auto` still changes is the degrade — asked-and-could-not-look is exit 2, unasked keeps the derived root and reports the diagnostic. A **discovered** root cannot turn a **miss** into a FAIL, only into a resolution — though a discovered copy that resolves and is invalid does fail, with its origin named. So a bare run's verdict does move with the host, which is what a per-host capability report is for; what does not is a **required** check's, because those name their roots and a named root replaces every other source. `--repo-root` stays named-only: a repository checkout is not something a plugin record lists. |
+| [`doctor.mjs`](doctor.mjs) | The Workspace Definition validator. Zero dependencies, no install step, run from the repository root. Two repeatable roots, one of which **is discovered unasked**: `--pack-root` is where declared packs are looked up, and `--repo-root` (2.7) is where the repositories a workspace's cards NAME are checked out, so the residence ruling's cross-repository refusal has somewhere to look. Without a `--repo-root` that check reports that it did not run rather than passing quietly. **One thing IS discovered — a pointer's `governed_by`**, through [`discover.mjs`](discover.mjs). It is **reported and never graded**, so no host's install state moves this tool's verdict *through that channel* — a scope this row used to be able to leave implicit, because the pack root was discovered only when asked and nothing else here read a host. A pack root also accepts `auto` — `--pack-root auto` reads that record too, and `./auto` still names a directory. **A pack root is discovered whether or not `auto` is passed**, because row 7 makes `--pack-root` *optional where discovery finds a root* and it was not: on the workspace `init` drafts by default plus one pack of the adopter's own, this tool exited **1** bare and **0** under `auto`. What `auto` still changes is the degrade — asked-and-could-not-look is exit 2, unasked keeps the derived root and reports the diagnostic. A **discovered** root cannot turn a **miss** into a FAIL, only into a resolution — though a discovered copy that resolves and is invalid does fail, with its origin named. So a bare run's verdict does move with the host, which is what a per-host capability report is for; what does not is a **required** check's, because those name their roots and a named root replaces every other source. `--repo-root` stays named-only: a repository checkout is not something a plugin record lists. |
 | [`doctor.test.mjs`](doctor.test.mjs) | Its test suite, on node's own runner. Written before the validator. |
-| [`discover.mjs`](discover.mjs) | **Host plugin-cache discovery**, added at milestone 7: it reads `<config>/plugins/installed_plugins.json` and dereferences a pointer's `governed_by` to the directory the governing workspace was installed to. Four verdicts — `resolved`, `not-installed`, `ambiguous` (two or more answering to one name: **refused and both named**, never ranked) and `could-not-look` — because a resolver with two answers spends *could not look* as *not installed*. It matches on the governing **manifest's** `name`, constrained by the pointer's `feed` where it declares one, and looks in a **named pair** of locations inside a payload rather than walking it. Nothing is fetched: the record is read from disk and no path here touches the network. Also runnable — `node cli/discover.mjs [--json] <workspace-dir>` — which is the seam [`../plugin/skills/portulan/SKILL.md`](../plugin/skills/portulan/SKILL.md) reads at the boot, and **deliberately not a ninth `portulan` subcommand**: `docs/vision.md` names eight and is human-owned, so this sits beside `plugin-lint` and `librarian` and joins that list only if the maintainer says so. |
+| [`discover.mjs`](discover.mjs) | **Host plugin-cache discovery**: it reads `<config>/plugins/installed_plugins.json` and dereferences a pointer's `governed_by` to the directory the governing workspace was installed to. Four verdicts — `resolved`, `not-installed`, `ambiguous` (two or more answering to one name: **refused and both named**, never ranked) and `could-not-look` — because a resolver with two answers spends *could not look* as *not installed*. It matches on the governing **manifest's** `name`, constrained by the pointer's `feed` where it declares one, and looks in a **named pair** of locations inside a payload rather than walking it. Nothing is fetched: the record is read from disk and no path here touches the network. Also runnable — `node cli/discover.mjs [--json] <workspace-dir>` — which is the seam [`../plugin/skills/portulan/SKILL.md`](../plugin/skills/portulan/SKILL.md) reads at the boot, and **deliberately not a ninth `portulan` subcommand**: `docs/vision.md` names eight and is human-owned, so this sits beside `plugin-lint` and `librarian` and joins that list only if the maintainer says so. |
 | [`discover.test.mjs`](discover.test.mjs) | Its test suite. Every case builds a whole fake host in a temp directory and points `CLAUDE_CONFIG_DIR` at it, because a suite that consulted the real machine would be green on the author's laptop and meaningless anywhere else. |
-| [`plugin-lint.mjs`](plugin-lint.mjs) | The packaging validator: the plugin and marketplace manifests, the skills they declare, and the agents at `./agents/` that nothing declares. Since milestone 7 session 7 it also holds **`core/personas/` and `agents/` to each other** — both directions fail, because a persona this bundle ships and does not bind is doctrine the host never registers, and a binding whose persona is gone registers a role with no charter. It is the one location a host loads agents from, exported here as `AGENT_DIR` and imported by `doctor` rather than spelled twice. |
+| [`plugin-lint.mjs`](plugin-lint.mjs) | The packaging validator: the plugin and marketplace manifests, the skills they declare, and the agents at `./agents/` that nothing declares. It also holds **`core/personas/` and `agents/` to each other** — both directions fail, because a persona this bundle ships and does not bind is doctrine the host never registers, and a binding whose persona is gone registers a role with no charter. It is the one location a host loads agents from, exported here as `AGENT_DIR` and imported by `doctor` rather than spelled twice. |
 | [`plugin-lint.test.mjs`](plugin-lint.test.mjs) | Its test suite, likewise written first. |
-| [`skills-set.mjs`](skills-set.mjs) | **The registrable set**, added at milestone 7 session 8: the one carrier of *what a plugin manifest must declare so a composed pack's skills register*. It reads each composed pack's `contributes.skills` and derives the paths, relativised to the plugin root — `--check` reports drift (1) and `--write` derives the key rather than leaving it hand-typed. Row 7 clause (b)'s adopter half, [#184](https://github.com/sleepy-panda-srl/portulan/issues/184): until it landed, registration was a property of `.claude-plugin/plugin.json` **alone**, so a composed pack's skill was invocable by coincidence of a path someone typed. It holds `HOST_SKILL_DEPTH` — the platform fact the derivation rests on, measured in `plugin-lint` and moved here when that file became a consumer. **Deliberately not a ninth `portulan` subcommand**, on `discover`'s precedent above. |
+| [`skills-set.mjs`](skills-set.mjs) | **The registrable set**: the one carrier of *what a plugin manifest must declare so a composed pack's skills register*. It reads each composed pack's `contributes.skills` and derives the paths, relativised to the plugin root — `--check` reports drift (1) and `--write` derives the key rather than leaving it hand-typed. Row 7 clause (b)'s adopter half, [#184](https://github.com/sleepy-panda-srl/portulan/issues/184): until it landed, registration was a property of `.claude-plugin/plugin.json` **alone**, so a composed pack's skill was invocable by coincidence of a path someone typed. It holds `HOST_SKILL_DEPTH` — the platform fact the derivation rests on, measured in `plugin-lint` and moved here when that file became a consumer. **Deliberately not a ninth `portulan` subcommand**, on `discover`'s precedent above. |
 | [`skills-set.test.mjs`](skills-set.test.mjs) | Its test suite, written first. Every refusal has a sibling in `recipe-set.test.mjs`, because those were found by review rather than by design and a second carrier of the same shape should not have to rediscover them. |
 | [`skills-set.live.test.mjs`](skills-set.live.test.mjs) | The same derivation against **this** repository rather than against fixtures — the guard for *a harness you write to check your own change inherits your change's blind spot*, which this project has now measured seven times, two of them in the session that added this file. Its load-bearing assertion is that the derived set equals what `.claude-plugin/plugin.json` already declares. |
-| [`new.mjs`](new.mjs) | **The authoring subcommand**, added at milestone 7 session 2: it scaffolds a skill · persona · pack · workspace · gate-policy · repo-card from a core template **into a layer you own, never into `core/`**. The refusal is resolution-based rather than pattern-based, because every interesting escape — `packs/../core`, a symlinked destination — parses fine and only fails once resolved. Two codes, `0` wrote and `2` could not run: it renders no verdict, so it has no red. |
+| [`new.mjs`](new.mjs) | **The authoring subcommand**: it scaffolds a skill · persona · pack · workspace · gate-policy · repo-card from a core template **into a layer you own, never into `core/`**. The refusal is resolution-based rather than pattern-based, because every interesting escape — `packs/../core`, a symlinked destination — parses fine and only fails once resolved. Two codes, `0` wrote and `2` could not run: it renders no verdict, so it has no red. |
 | [`new.test.mjs`](new.test.mjs) | Its test suite, written first. It establishes *never into `core/`* against the filesystem rather than against an argument check, and runs the real `doctor` and `plugin-lint` over what was scaffolded — a scaffold nothing validates is one nobody can trust. |
-| [`vendor.mjs`](vendor.mjs) | **Materialises a workspace where it is needed**, added at milestone 7 session 3 when the maintainer widened the constitution's gloss to cover both directions. `--host` writes a self-contained `AGENTS.md` — core's kernel inlined, the workspace's slots named, packs named-not-composed — beside a copied `.portulan/`, for a host that cannot install the plugin. `--switch` changes residence, feed-side ↔ in-repo, under proposal [`0017`](../.portulan/proposals/0017-one-repository-one-governing-workspace.md): materialise at the new residence, leave a pointer or nothing at the old, `doctor` green at **both** ends before the old one is retired. Every handled failure leaves exactly one governing workspace; the residence is **never inferred** from a path, which is `init`'s rule for `init`'s reason. |
+| [`vendor.mjs`](vendor.mjs) | **Materialises a workspace where it is needed, in either direction** — the constitution's gloss covers both. `--host` writes a self-contained `AGENTS.md` — core's kernel inlined, the workspace's slots named, packs named-not-composed — beside a copied `.portulan/`, for a host that cannot install the plugin. `--switch` changes residence, feed-side ↔ in-repo, under proposal [`0017`](../.portulan/proposals/0017-one-repository-one-governing-workspace.md): materialise at the new residence, leave a pointer or nothing at the old, `doctor` green at **both** ends before the old one is retired. Every handled failure leaves exactly one governing workspace; the residence is **never inferred** from a path, which is `init`'s rule for `init`'s reason. |
 | [`vendor.test.mjs`](vendor.test.mjs) | Its test suite, written first. The group that matters *forces* a failure after each named write step, because the property this tool exists to protect is what a failure partway leaves on disk — an ordering nothing can interrupt is an ordering nobody has checked. Every end state is graded by the real `doctor`, never by a second opinion about what valid means. |
 | [`collisions.test.mjs`](collisions.test.mjs) | **The collision contract — one rule, three carriers, pinned together.** Three tools here write into a tree somebody else owns, and all three answer the same question first: *is something already at the path I am about to write?* [`init.mjs`](init.mjs), [`new.mjs`](new.mjs) and [`vendor.mjs`](vendor.mjs) each export a `collisions()` that answers it with a different signature, a different return shape and a different refusal vocabulary, because each was copied from the last and adapted. This suite pins the three to the one question rather than to one another's spellings. |
-| [`upgrade.mjs`](upgrade.mjs) | **The migration runner**, added at milestone 7 session 9 and the last of the eight to be built. It reads [`../spec/migrations/`](../spec/migrations/) — the chain lives in the **spec**, because a migration is part of the Workspace Definition rather than part of a tool — and applies what a workspace owes. **Two kinds of step**, on the maintainer's ruling of 2026-08-12: a `version` step migrates a MAJOR, and a `repair` fixes what a rewriter owes a workspace it touched. Owedness is derived from the workspace's **state**, never from a stamp, so every step is idempotent and an interrupted run is recovered by re-running. It refuses in **both** directions: a workspace ahead of this bundle is could-not-run (upgrade the CLI, not the workspace), and one behind by a MAJOR that no step reaches is could-not-run too — either would otherwise plan to nothing and exit 0. `--write` applies, then grades with the real `doctor` and **rolls back on a red**, reporting what it could not put back rather than claiming the tree is clean. |
+| [`upgrade.mjs`](upgrade.mjs) | **The migration runner**, the last of the eight to be built. It reads [`../spec/migrations/`](../spec/migrations/) — the chain lives in the **spec**, because a migration is part of the Workspace Definition rather than part of a tool — and applies what a workspace owes. **Two kinds of step**, on the maintainer's ruling of 2026-08-12: a `version` step migrates a MAJOR, and a `repair` fixes what a rewriter owes a workspace it touched. Owedness is derived from the workspace's **state**, never from a stamp, so every step is idempotent and an interrupted run is recovered by re-running. It refuses in **both** directions: a workspace ahead of this bundle is could-not-run (upgrade the CLI, not the workspace), and one behind by a MAJOR that no step reaches is could-not-run too — either would otherwise plan to nothing and exit 0. `--write` applies, then grades with the real `doctor` and **rolls back on a red**, reporting what it could not put back rather than claiming the tree is clean. |
 | [`upgrade.test.mjs`](upgrade.test.mjs) | Its test suite, written first, against `ws` views built in memory — the honest way to force a step's own branches red. Every case in it was **forced red by mutating the code it guards** before being trusted; the pass that did so found a guard with no test at all, where the arithmetic was covered and the tool's response to it was not. |
 | [`upgrade.live.test.mjs`](upgrade.live.test.mjs) | The other half, and the one that matters: workspaces the **real `init`** drafts, from a real second bundle that is then deleted, with the drafted rail **run** before and after — exit 2 with its bundle gone, a verdict once repaired. Behaviour, not a string comparison on a script. It also pins that `.portulan` and `examples/` owe nothing, so `examples/` staying four MINORs back at 2.4 cannot be quietly restamped. Written because running the step over `.portulan` found what no fixture could: a handoff that *documents* the marker was read as a malformed marked line. |
-| [`feedback.mjs`](feedback.mjs) | **The inbound half**, added at milestone 7 session 6: it files an issue from a report the user previewed, seam-scanned before it leaves the machine, under the Gated tier. Three verbs — `draft` writes a report into the workspace's `feedback/` directory, `preview` prints the exact bytes, `send --approve` files them through the user's own `gh` login. The payload is assembled from a **closed list** rather than filtered, so nothing here reads a workspace name, a repo card, a gate map, memory, a remote or a path. It ships **no seam terms** — the list is the adopter's and is looked for at `--seam-terms`, `$PORTULAN_SEAM_TERMS`, then `<workspace>/seam-terms.txt`; a hit refuses the send with **1**, a named list that cannot be read refuses it with **2**, and no list at all is *stated in the sentence the user approves* rather than passed over. Approval is per send and is never inherited from a draft or a preview. |
+| [`feedback.mjs`](feedback.mjs) | **The inbound half**: it files an issue from a report the user previewed, seam-scanned before it leaves the machine, under the Gated tier. Three verbs — `draft` writes a report into the workspace's `feedback/` directory, `preview` prints the exact bytes, `send --approve` files them through the user's own `gh` login. The payload is assembled from a **closed list** rather than filtered, so nothing here reads a workspace name, a repo card, a gate map, memory, a remote or a path. It ships **no seam terms** — the list is the adopter's and is looked for at `--seam-terms`, `$PORTULAN_SEAM_TERMS`, then `<workspace>/seam-terms.txt`; a hit refuses the send with **1**, a named list that cannot be read refuses it with **2**, and no list at all is *stated in the sentence the user approves* rather than passed over. Approval is per send and is never inherited from a draft or a preview. |
 | [`feedback.test.mjs`](feedback.test.mjs) | Its test suite, written first, against `.portulan/tasks/0012-a-feedback-pipe-points-out-of-the-seam.md`'s *Done when* list. Nothing here reaches the network: `gh` arrives injected. The one property injection cannot prove — that the approved bytes are the sent bytes — is not proven by comparison but held by construction, and the suite asserts the construction: the previewed body **is** `payload()`'s return value, not a second rendering that agrees with it today. |
 | [`feedback.live.test.mjs`](feedback.live.test.mjs) | The rail on the pair that cannot be collapsed. `package.json`'s `files` does not ship `.github/ISSUE_TEMPLATE/`, so the sender must carry the forms' field ids, labels, required flags, dropdown options and acknowledgement texts — one fact, two carriers, and the repair is `0020`'s: one carrier plus a rail. This reads the real forms and fails when the two disagree. Its own instrument is guarded first: if the reader stops understanding a form and returns nothing, the test goes **red** rather than vacuously green. |
-| [`compile.mjs`](compile.mjs) | The enforcement compiler: a workspace's gate policy becomes host enforcement. Two backends — Claude Code `permissions` + `hooks`, and a GitHub repository ruleset for the platform floor — and the vocabulary it reads stays the workspace's, so a third backend translates the same policy instead of forcing it to be rewritten. `--workspace` takes a repository root **or the workspace directory itself**, which is how a feed-side workspace is reachable at all: it keyed on `.portulan` until milestone 7 session 3, when running the parity demonstration found it exiting 2 on the feed-side end of a switch. |
+| [`compile.mjs`](compile.mjs) | The enforcement compiler: a workspace's gate policy becomes host enforcement. Two backends — Claude Code `permissions` + `hooks`, and a GitHub repository ruleset for the platform floor — and the vocabulary it reads stays the workspace's, so a third backend translates the same policy instead of forcing it to be rewritten. `--workspace` takes a repository root **or the workspace directory itself**, which is how a feed-side workspace is reachable at all: it keyed on `.portulan` until the parity demonstration found it exiting 2 on the feed-side end of a switch. |
 | [`compile.test.mjs`](compile.test.mjs) | Its test suite, likewise written first. Emission fidelity only — nothing in here can establish that a host *honours* what the compiler emits, which is a fact about a running host. |
+| [`inside.mjs`](inside.mjs) | **Is one path inside another** — one predicate, one file, no imports. It began in [`index.mjs`](index.mjs) and moved here when [`compile.mjs`](compile.mjs) needed it too: taking it from there would have closed an import cycle, and this repository has already had one exit **13** in silence. Copying it instead is what its own docblock forbids — two copies of this rule drifted into the identical defect before either shipped. `index.mjs` re-exports it, so every existing importer is untouched. |
 | [`index.mjs`](index.mjs) | The index generator, over **two** series since Workspace Definition 2.5: the memory store, which is size-budgeted so a breach is a red, and the handoff series, which is not — an append-only series has no consolidation to offer, so every remedy a budget could ask for is already barred. Every field on every line is derived from what it points at, so neither file has a hand-maintained half; the *carriers* differ per series and on evidence, a record's title being its filename and a handoff's its H1. It writes an over-budget index rather than refusing to — the remedy is consolidation, and consolidating needs the artifact to consolidate from. |
 | [`index.test.mjs`](index.test.mjs) | Its test suite, written first. Derivation, drift and cost only — nothing in here can establish that the index is any good at *recall*, which is an eval question. |
-| [`gate.mjs`](gate.mjs) | **The PreToolUse gate runner** — the *explanation* half of the enforcement compiler, wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json`. It reads the host's hook payload on stdin, finds which rule of the policy the workspace **yields** the attempted action matches, and returns that rule's own sentence as the decision reason. *Yields*, not *declares*: [`../.portulan/gates.json`](../.portulan/gates.json) **plus the fragments its packs contribute**, composed through `compile`'s own `packContributions`/`composeFragments` so there is no second composer to drift — this row said *declares* until [#269](https://github.com/sleepy-panda-srl/portulan/issues/269), and so did the runner. Where two rules match one call it answers with the **strongest** tier, not the first listed — composition makes that systematic, since added rules are appended and so always lose a first-match tie, but a single-file policy listing the weaker rule first diverged too. Strengthen-only: `ask` may become `deny`, never the reverse. **This file is not the gate** — the host's own matcher is; this says *why*, so a refusal arrives as a reason rather than a wall. |
+| [`gate.mjs`](gate.mjs) | **The PreToolUse gate runner** — the *explanation* half of the enforcement compiler, wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json`. It reads the host's hook payload on stdin, finds which rule of the policy the workspace **yields** the attempted action matches, and returns that rule's own sentence as the decision reason. *Yields*, not *declares*: [`../.portulan/gates.json`](../.portulan/gates.json) **plus the fragments its packs contribute**, composed through `compile`'s own `packContributions`/`composeFragments` so there is no second composer to drift. Where two rules match one call it answers with the **strongest** tier, not the first listed — composition makes that systematic, since added rules are appended and so always lose a first-match tie, but a single-file policy listing the weaker rule first diverged too. Strengthen-only: `ask` may become `deny`, never the reverse. **This file is not the gate** — the host's own matcher is; this says *why*, so a refusal arrives as a reason rather than a wall. |
 | [`gate.test.mjs`](gate.test.mjs) | Its test suite, and the exception to "written first" for the same reason [`stop-gate.test.mjs`](stop-gate.test.mjs) is: it arrived with [#269](https://github.com/sleepy-panda-srl/portulan/issues/269), on a runner nothing had tested directly. **Every case spawns the real binary** with a payload on stdin, because the defect it closes was never in `decide` — it was in which rules reached `decide`, and a unit test would have passed on every day the hook was blind. |
-| [`stop-gate.mjs`](stop-gate.mjs) | **The Stop-gate runner** — *done* is not a thing an agent may simply declare. Wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json` as a `Stop` hook: when an agent tries to end its turn, this runs the workspace's default verify recipe and blocks the ending if the recipe is not green. [`../core/operating/verification.md`](../core/operating/verification.md) specified the contract at milestone 1 and named milestone 4 as where the runner arrives; this is that runner. |
+| [`stop-gate.mjs`](stop-gate.mjs) | **The Stop-gate runner** — *done* is not a thing an agent may simply declare. Wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json` as a `Stop` hook: when an agent tries to end its turn, this runs the workspace's default verify recipe and blocks the ending if the recipe is not green. [`../core/operating/verification.md`](../core/operating/verification.md) specifies the contract; this is that runner. |
 | [`stop-gate.test.mjs`](stop-gate.test.mjs) | The exception to "written first": it covers the Stop-gate runner ([`stop-gate.mjs`](stop-gate.mjs)), and it exists because a supervisor found a fail-open and a forever-block in a runner nothing tested at all. Its cap arithmetic and date handling, and — since [#220](https://github.com/sleepy-panda-srl/portulan/issues/220) — the **did-work signals**, which spawn the real binary against real git fixtures for the reason [`gate.test.mjs`](gate.test.mjs) gives: the defect was that real git in a rebase-merging repository behaves otherwise than the signal assumed, and a stubbed runner is a copy of that assumption. What still has no directed case: a recipe that reds or cannot run, driven through the spawned binary, and the handoff-listing edge shapes — both are exercised here only as preconditions of the cases above. |
 | [`librarian.mjs`](librarian.mjs) | The scheduled librarian's pass: reindex over both series, record age from git, the sealed-stamp re-validation nag, proposal nagging, demotion drafts, **mining** — incidents nothing in the curated layer points back at, and paths pull-request reviewers keep leaving findings on — and **consolidation**, read as budget distance plus the records citing one incident. The one tool here that reads **history** — `doctor` reads the tree and says so — which is why it belongs to a scheduled job rather than to a verify recipe: a check that reads history is a false-red generator in a shallow checkout. It renders no verdict, so it has no exit 1, and it **writes nothing itself**: the command writes, and only after the pass's own handoff is on disk, because that handoff is a member of the series one of the indexes covers. |
 | [`control-chars.mjs`](control-chars.mjs) | **The rail on bytes a reader cannot see**, added for [#68](https://github.com/sleepy-panda-srl/portulan/issues/68): no tracked file may carry a byte in the C0 range other than TAB and LF, nor DEL. It reads a `Buffer` and **never decodes**, because decoding invalid UTF-8 yields U+FFFD — which both hides bytes and invents a character that was not there. That rule holds end to end and cost three review rounds to make true: the file contents, the file list on stdin, and a symlink's target all arrive as bytes, and a path is kept only if it round-trips through UTF-8. A binary asset is exempt **by name**, never by a content test: every binary sniff in use is keyed on NUL, so a sniff would have skipped the one file this exists to catch. The declaration is audited three ways — stale, never-read, or dead — each exit `2`. |
@@ -155,11 +162,39 @@ check on it.)_
 | [`pack-version.mjs`](pack-version.mjs) | **A change to a pack's `contributes` must move that pack's `portulan.version`** — the maintainer's ruling on [#265](https://github.com/sleepy-panda-srl/portulan/issues/265), arm 3, including that a **prose-only** edit to a fragment's `reason` counts. The **second** tool here that reads history rather than the tree, and the comparison is **three-dot** — the merge-base of the base ref and `HEAD` — so work that landed on the base is never attributed to this branch. Manifests are compared as **values**, so reindenting or reordering keys is correctly not a change. The bundle version in `packs/.claude-plugin/plugin.json` is out of scope by measurement: it is one field and the packs are many. |
 | [`pack-identity.mjs`](pack-identity.mjs) | **Every file `npm pack` would emit is byte-identical to its staged blob (`git show :<path>`), and every one is tracked at all** — the rail [#149](https://github.com/sleepy-panda-srl/portulan/issues/149) asked for, built 2026-08-18 after the first publish measured the property by hand. It compares against the **tree**, not the registry: the registry form needs the network and a published version, so it cannot run before a first publish or offline, and a recipe that cannot run stops being run. This owns the half that can drift silently on any commit; the registry half stays a hand measurement recorded on #149 at each publish. `package.json` is compared like every other file rather than exempted, because the 2026-08-13 measurement asserted identity "`package.json` included, with no exemption" and an exemption here would quietly retire that claim. Could-not-run is **exit 2** — npm absent or unusable is not a finding about the bytes. |
 | [`pack-identity.test.mjs`](pack-identity.test.mjs) | The rail's suite, added on a Copilot note that it had shipped without one while every comparable rail here has a suite. Exercises all four contracted states **positively** — green, a drifted byte, an untracked packed file, and could-not-run — because a failure path nobody has run is a failure path nobody has seen work. Two of its cases are the review's own findings turned into tests: a **staged** edit must compare clean, or the rail is red before every commit and contradicts [`../.portulan/dod.md`](../.portulan/dod.md); and a filename beginning with `-` must be compared rather than read as an option, which the `cat` shell-out this rail first shipped with would have done. |
+| [`payload.mjs`](payload.mjs) | **Every `cli/*.mjs` the package would ship falls in exactly one class, and nothing arrives in the payload unclassified** — [#383](https://github.com/sleepy-panda-srl/portulan/issues/383)'s first half. `package.json`'s `files` governs the payload and nothing derived or checked its membership: `pack-identity` holds every packed file byte-identical to its source and is deliberately silent on *which* files those are. That is how `ab.mjs`, `ab-run.mjs` and `ab-grade.mjs` shipped for three sessions unnoticed, and it was demonstrated live before this was written — a `cli/` module staged into a scratch clone joined the tarball under a `pack-identity` green over 84 files. The classes are `bin` (derived from `package.json`'s own `bin`), `subcommand` (imported from `portulan.mjs`'s `SUBCOMMANDS`), `product` (unreachable but ruled to ship, with the ground for the ruling — the class `unruled` empties into as #383 is answered), `imported` (the transitive walk, which reads re-exports and side-effect imports as edges — on the grammar being total, not on a live example: an earlier draft claimed `manifest.mjs` was reachable only that way and the pre-commit checkpoint measured it false), `hook-runner` (imported from `compile.mjs`'s `HOOK_RUNNERS`, which spells them into generated host config and is their one carrier), and the **frozen** `UNRULED`. **It rosters nothing it can re-derive**, and it refuses rather than walking past a dynamic `import(` it has not accounted for. Authority for *shipped* is the `npm pack --dry-run --json` roster, never a string match on the `!` lines — npm's negation semantics are npm's. **Self-excluded**, on `eval-bundle.mjs`'s precedent: its subject is this repository's own publish surface. Could-not-run is **exit 2**. |
+| [`payload.test.mjs`](payload.test.mjs) | Its test suite. **Every red class is forced** — an unclassified arrival, an `UNRULED` module gone reachable, one the payload stopped carrying, an exclusion the payload contradicts, a stale exclusion, an unexplained absence, and a dangling import — because a rail whose failure paths are never run is a rail nobody has seen work, and this one exists precisely because a green meant nothing for three sessions. One case asserts the frozen class is exactly thirteen; one asserts the unclassified finding *names* the refusal to widen `UNRULED`, since the cheap fix under pressure is the fail-open. The `telemetry.mjs` case deliberately asserts **two** findings rather than narrowing to one: a module that leaves the payload while staying tracked is both a stale entry and an unexplained absence, and saying so twice is the totality working. |
+| [`version-carriers.mjs`](version-carriers.mjs) | **Every prose statement of the CURRENT version equals `package.json`'s** — the rail for a defect this repository shipped **twice with the sibling pairing already written down**: `README.md` and `.portulan/products/portulan/product.md` said `0.2.0` while everything machine-read said `0.1.0`, and one release later `README.md` said `0.1.0` inside the change cutting `0.1.1`. It matters past tidiness because `README.md` is in `package.json`'s `files` and **npm freezes a README per version**, so a wrong sentence that reaches a publish needs another release to correct — which is what `0.1.1` was. The **record layer is excluded by path**, and that is the design: this repository quotes retired sentences in the files recording their repair, so a matcher over everything reds on the account of the fix. `MUST_CARRY` closes the other half — a carrier deleted or reworded is a finding, so the rail cannot shrink in silence. What it does **not** close is a claim spelled a new way, and the accepted practice for that is #286's ruling: new spelling ⇒ a pattern here and a fixture first. |
+| [`version-carriers.test.mjs`](version-carriers.test.mjs) | The rail's suite. Some cases run the CLI as a **subprocess whose SCRIPT PATH contains a space** — the property the entry guard turns on, and not the same thing as a spaced working directory; the rest exercise the module in process. **No count is written here on purpose.** A hand-maintained figure beside a list that grows is the defect this whole rail exists for, and `node --test` derives it. Every contracted state is exercised **positively** — green, drift in each of the three carriers, a carrier reworded away, could-not-run in three causes, and the record layer ignored. Two cases exist only because this repository's own corpus refutes the naive design: **the record must be ignored**, since `CHANGELOG.md` and two handoffs quote that retired sentence while explaining that it was retired — **despelled here on purpose**: written out in the matched spelling, this very row is a live current-version claim and the rail reds on it, which is how it was found; and **a `g` regex must not carry `lastIndex` between files**, which would find the first claim and then resume past it, reporting a clean scan over a drifted file. |
 | [`pack-version.test.mjs`](pack-version.test.mjs) | Its test suite, written first, on **real `git init` repositories** rather than a stubbed `execFileSync` — the three-dot property cannot be observed at all without two branches and a merge-base. The shallow-clone refusal is asserted on **both** shapes a shallow clone takes, and is guarded by a full-depth clone of the same fixture reaching the red, so the `2` is the depth rather than the fixture. |
+| [`goldens.mjs`](goldens.mjs) | **The gate-corpus runner** — milestone 8 clause (a), *golden tasks reach the gates as well as the skills*. It grades [`../evals/goldens/gates/`](../evals/goldens/gates/) against the gate policy the workspace **yields** (its own rules plus its composed packs' fragments, never the declared file alone — the class [`../.portulan/dod.md`](../.portulan/dod.md) condition 1 names), through [`compile.mjs`](compile.mjs)'s own exported `matchesRule` rather than a second implementation. **Two rails:** a rule that compiles to a matcher and carries no fixture is red, so coverage is measured rather than named; and a `documented-hole` case that starts being *caught* is red too, so a hole record cannot go stale in either direction. Resolution is **hermetic** — `discovery: null`, always — because a rail that consults the host's plugin cache grades the machine rather than the tree. **A fixture is data and is never executed**, asserted statically in the suite. What it does not establish is **adequacy**: it is a presence floor, and it prints that limit on every green. Rules with `action.none` are exempt and **named on every run**, because writing the next gate `none`-shaped is the way to dodge it. Each case records which branch of `matchesRule` it exercises, **derived** by `matcherPath` from the action kind and the tool and refused when the stored value disagrees — a field written from memory on every case in the corpus would be the second carrier this repository keeps finding wrong. An unexpected throw returns **2**, never 1: a crash that exits 1 reaches the recipe as a red about a corpus nothing finished grading. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`goldens.test.mjs`](goldens.test.mjs) | Its test suite. Every contracted state is exercised **positively** — a missing fixture, a regression, a hole that closed, all ten malformed-fixture refusals, and could-not-run — because a failure path nobody has run is one nobody has seen work. Three cases exist because this repository's history refutes the naive design: the entry guard must survive a path containing a space (this module shipped the broken spelling and exited **0 having run nothing**, the third time here), the denominator is asserted on the **census** rather than the verdict (both pack-contributed rules are `none`-shaped today, so a declared-only denominator would coincide — which is how that defect goes unnoticed), and the no-subprocess contract is asserted against the module's **source**, since it is structural rather than behavioural. |
+| [`mutants.mjs`](mutants.mjs) | **The mutation census** — milestone 8 clause (b), first half, *mutation testing over both matchers*. It breaks [`compile.mjs`](compile.mjs)'s matcher region on purpose, one **anchored** operator at a time, and grades each mutant against the gate corpus. This answers the question [`goldens.mjs`](goldens.mjs) says out loud that it cannot: not *does a fixture exist* but *does the corpus NOTICE a broken matcher*. **Recorded in both directions**, as `documented-hole` is — a `killed` operator that survives means the kill-set weakened, a `survives` operator that is killed is good news the record must absorb — and a `survives` entry admits only a proof of equivalence, never an unfilled gap. **A missing or ambiguous anchor is could-not-run, never a skip**; so is a mutant that will not import, since counting an unimportable module as killed would be the loudest false green available to a tool whose whole output is a coverage claim. Every mutant gets its **own** temp directory, because ESM caches by URL with no invalidation and a reused path would grade the first mutant once per operator. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`mutants.test.mjs`](mutants.test.mjs) | Its test suite. The ESM-cache canary is the case worth knowing: two different mutants are imported in one process and must answer differently, which is the only assertion here that would pass on a correct runner and fail on the plausible wrong one. The refusals are exercised positively — an anchor that does not place, one that places twice, a no-op substitution, a workspace with no policy — and the entry guard is pinned under a path containing a space. |
+| [`fuzz-shell.mjs`](fuzz-shell.mjs) | **The grammar fuzzer** — milestone 8 clause (b), second half, *grammar-aware fuzzing over the shell segmenter*, which is **two** functions here and they differ. It **composes** commands from a grammar rather than mutating strings, so it knows by construction whether the payload sits in a position bash executes or one bash only prints: the oracle is exact, and a disagreement is a gate bypass or a false red rather than something to adjudicate. **Positions are enumerated and recorded** — every cell that diverges from ground truth cites the record licensing it, in the gate map's honest-holes list or in [`compile.mjs`](compile.mjs) itself — **and spellings are fuzzed**, the invariant being that every spelling of one command in one position answers the same. Three payloads, not two, because the write matcher has two recognitions and measurement showed they diverge. **Deterministic and seeded**, seed printed on every run including the green. A finding is emitted **in the corpus's own case shape**, so it becomes a regression pin by paste. It found a live bypass of every Gated shell action — one wrapper plus one separator — on its first full run. |
+| [`fuzz-shell.test.mjs`](fuzz-shell.test.mjs) | Its hermetic suite: determinism, budget refusals that are refused rather than coerced (`Number("")` is 0), the recorded table's totality in both directions, and the rule that a divergence must name a record. |
+| [`fuzz-shell.ground.test.mjs`](fuzz-shell.ground.test.mjs) | **The fuzzer's oracle, measured under real bash.** A grammar that lies about itself produces not a red but a green about the wrong thing — the one failure a fuzzer cannot detect in itself — so every position is run with a **neutral** payload and every path spelling is written to a throwaway file. Separate from the file above precisely because that one handles a force-push spelling and must never spawn anything. It caught two generator defects: a `..` hop through a directory nothing created, and a marker check fooled by `echo` printing its own payload. |
+| [`drills.mjs`](drills.mjs) | **The forced-red drill harness** — milestone 8 clause (d), *every rail forced red on a calendar and required to fire*. It asks the question its two siblings do not: [`goldens.mjs`](goldens.mjs) asks whether a gate has fixtures and [`mutants.mjs`](mutants.mjs) whether those fixtures discriminate; this asks whether the **rail still fires at all**. Every drill is a **pair** — a control on a pristine tree, then the perturbation — because a rail that only ever reds proves nothing about its green, and because a control that is already red makes the drill could-not-run rather than a fire it did not cause. Three guards, each from a defect already shipped here: a **`tell`** the rail's own output must carry when it fires and must not carry before, so a red for the wrong reason is not counted as one; an anchored substitution that must place **exactly once** *and* move bytes on disk, because both hand-run sessions had a drill that no-opped and reported on nothing; and `--only` narrowing what **runs** and never what must be well formed. Isolation is one throwaway `git worktree` per drill, so the working tree is never perturbed. **It reports on a commit and prints which one** — a dirty tree is refused outright, and `--working-copy` synthesizes one with `git stash create` and refuses while untracked-and-unstaged files exist, since a synthesized tree missing the file under review would be a green about the wrong tree. `--check` is the correspondence half the `drills` recipe runs. **Unlike its three siblings it SPAWNS by nature** — running a rail is spawning it — so what the suite pins instead is that nothing spawned is composed from a drill's declarations. The rails it does **not** drill are named on every run, with the reason: the platform floor, the host's permission layer, the CI seam, the seam scan, `claude plugin validate`, the platform watchers, and the librarian pass. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`drills.test.mjs`](drills.test.mjs) | Its suite. The refusals are exercised **positively** — an anchor that does not place, one that places twice, a substitution that is its own replacement, a creation over a path that exists, a drill naming an undeclared rail, a yielded rail with no drill, a drill whose control and fire are the same run — and the two host-shaped rules are pinned: a dirty tree is refused without `--working-copy`, and untracked-and-unstaged files are refused with it. The `tell` contract is asserted in **both** directions against a fake rail: present-in-fire is not enough if it was also present in the control. The entry guard is pinned under a path containing a space. |
+| [`skill-goldens.mjs`](skill-goldens.mjs) | **The core-skill golden corpus** — milestone 8's *golden tasks per core skill*, the row's original first subject and the half clause (a) named when it said golden tasks reach the gates *"as well as the skills"*. It binds each numbered step of a skill's `## The pass` to the **live artifacts** it governs and to the rail that enforces it, or `null`. **The denominator is derived** — the steps come out of the skill file, so a step nobody wrote a case for is a red rather than a default, which is the difference between a rail and a census over a set its author drew. **An empty step list is could-not-run**: three `## The pass` spellings exist, an exact match would find one skill of three, and the other two would satisfy *every step is accounted for* vacuously. A mandate **quote must place exactly once** or the case refuses, so a reworded skill reddens instead of drifting. **The predicates are pinned by import**, not re-spelled — this module imports `RETIRE_WHEN` from [`doctor.mjs`](doctor.mjs), so the retire-when check is `doctor`'s own regex and `doctor` dropping that export breaks the runner at load. **The per-case `carrier` field is a different thing and is NOT verified**: nothing links it to an import or to any check, so a corpus naming a module that does not exist still grades green. It is declared, reviewed metadata, a reviewer is what checks it, and the runner prints that limit on every run. **`unbindable` is adjudicated**: its reason comes from a closed vocabulary, and a `judgement-only` step may name no artifacts — if you can name them it is unbuilt, not unjudgeable. The bound/unbindable ratio is printed **as a finding**, because it measures how much of a core skill is artifact discipline and how much is agent judgement. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`skill-goldens.test.mjs`](skill-goldens.test.mjs) | Its suite. Three cases exist because this session's own opening passes produced the defect they pin: the denominator must not go quietly empty, the EARS predicate must read the mandate's **shape** rather than a section's presence (two checkpoints computed two different figures for one row because each measured before deciding the rule), and the provenance predicate must be **shape-tolerant** because the tree carries two spellings and a literal one reports thirteen renamed files as absent. Every refusal is exercised positively — an unbindable reason outside the vocabulary, a judgement-only step naming artifacts, a step in the pass and in no case, a case naming a step the pass lacks, a corpus whose `skill` field disagrees with its filename, an undeclared slot, a slot resolving to zero files. The **both-directions** case is the one worth knowing: an accepted drift that starts complying is a finding, and it caught three filenames the author had written from a number prefix rather than read off disk. The entry guard is pinned under a path containing a space. |
+| [`review-meter.mjs`](review-meter.mjs) | **The review-loop meter** — milestone 8 clause (c), *rounds per pull request, pushes per round, empty-round rate*. It derives the figures [`../.portulan/memory/a-review-loop-needs-a-bound.md`](../.portulan/memory/a-review-loop-needs-a-bound.md) bounds the loop on, which were counted **by hand** on 2026-07-28 and which that record says of itself **nothing checks**. Every figure is in **submission** units — the criterion predates the 2026-07-30 redefinition of *round*, and the record's own `Retire when:` names its threshold in *"the submission units of the table above, not fix-rounds"* — and the tool never prints the bare word for a figure. **Fix-rounds it does not compute at all**, and that is a finding rather than a gap: on #105 a fix rode inside another push and was never a reviewed head, and a records push after a finding-bearing submission answers nothing, so *"count pushes, then look inside each one"* is not something an API answers. The empty-round rate is reported as an **upper bound** — separating a submission that found nothing from one carrying only suppressed notes needs the awk in [`../.github/workflows/copilot-review.yml`](../.github/workflows/copilot-review.yml), a **workspace-layer** matcher reduced to one carrier, and copying it into engine code would put two spellings of one rule on opposite sides of the boundary. It **reports on a snapshot, never the network**: `--fetch` is the one mode that talks to GitHub, and it stores no review bodies. It also **detects when two of its figures are one figure** — where every submission judged its own head, pushes-per-finding-bearing-submission reduces to `1/(1 - the no-inline rate)`, which it says out loud rather than presenting as a third measurement. **A meter, not a bound**: nothing here stops a loop, and it adjudicates no sibling exemption. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`review-meter.test.mjs`](review-meter.test.mjs) | Its suite. Every counting trap this repository has already paid to discover is a case, because the argument for the tool is that a hand count kept getting them wrong: both reviewer logins accepted (a filter on one returns zero from the other, #154), our own reviews refused as **could-not-judge** rather than counted (at merge: #105 is seven of fifteen, #342 is ninety of a hundred and two), a duplicated pull request caught, and an absent inline count refused because absent is not zero — as is an absent `head`, an unparsable `mergedAt`, and a window heading disagreeing with the corpus under it. The empty denominator returns **null and never zero** — an unmeasured window is not a window below the retirement threshold — and the boundary is asserted **at** the threshold, since *below* read generously retires a rule the measurement did not. The register's byte-compare is exercised in both directions, and the entry guard is pinned under a path containing a space: this module shipped the broken spelling and `--fetch` exited **0 having written nothing**, the fourth time here. **Three cases assert an error MESSAGE rather than only an exit code**, each because the case they replaced passed for the wrong reason — a missing-register case that never reached the register, a `--pool` case that fell through into the real fetch and got its 2 from `gh` failing, and a `--check` that compared nothing and returned 0. An assertion holding for a reason other than its subject keeps passing after the code it names is deleted. |
+| [`telemetry.mjs`](telemetry.mjs) | **The OTel emitter** — milestone 8's *OTel opt-in config*, and the first thing here that can send anything anywhere on purpose. The reading was **ruled, not derived** (2026-08-28): a validated opt-in config surface **plus a real emitter**, hand-written OTLP-over-HTTP JSON with no OpenTelemetry SDK, because an `@opentelemetry/*` import would end the zero-dependency property [`../.portulan/identity.md`](../.portulan/identity.md) protects — the maintainer's 2026-07-31 ruling that this ships as plain ESM, which [`../.portulan/repos/portulan.md`](../.portulan/repos/portulan.md) records as permanent rather than pending. **The committed config is the only gate**, and that is a deliberate departure from the OTel environment contract: `OTEL_SDK_DISABLED` defaults to *false*, so honouring the standard env surface as the gate would make an adopter who already exports an endpoint for some other service start emitting without deciding to — an opt-**out**, where the criterion says opt-in. The environment supplies **transport only** (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`), so a token never enters a committed file. `--export` is the one mode that reaches the network and it refuses twice over: when the config opts out, and in the **three** states that are not a committed consent: the config is **untracked**, **tracked but absent from `HEAD`** (staged and never committed), or **differs from `HEAD`**. The staged case is the one worth naming — it is how an agent would manufacture consent one step short of a commit, and a round of this pull request's own review had made it unreachable. **Opted-out and could-not-read are different answers with different codes**: a config with a typo its author meant as `true` must never report *opted out*. Figures are **Gauge** points stamped with the instant the measurement is *about* — the snapshot's own `captured` — not a clock read, which is both what OTLP means and what makes the golden byte-stable. It also carries `--audit-recipes`, the rail behind the standing prohibition on a network call inside a verify recipe: it sweeps the set the workspace **yields** at a pinned root, rails the **class** of network modes rather than this session's own, and refuses an empty set rather than passing vacuously. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`telemetry.test.mjs`](telemetry.test.mjs) | Its suite. **No case opens a real socket** — [`../.portulan/verify/tests.sh`](../.portulan/verify/tests.sh) runs this suite, so a test that did would be the network call inside a verify recipe that this module's own audit forbids; the transport is injected and the send is proven against a temporary git repository with the consent actually committed, asserting the wire bytes **are** the golden's bytes. Every refusal is exercised positively: an absent `enabled` (absent is not false), a secret in a committed config, an unknown signal, a wrong spec, an unparsable capture stamp, an edited consent, a consent outside the tree, two modes at once — and a valid config producing **no** problems, without which a validator that refused everything would satisfy the rest. The closed attribute vocabulary is pinned **in both directions**, so an added key and a deleted carrier are each a red, and separate cases assert that no reviewer login and no commit SHA reaches the payload. The producer seam is exercised against a producer this module **did not ship**, because a generic shape with one implementation is a capability claim nothing checks. The entry guard is pinned under a path containing a space — the fourth instance here, and the one where silence is indistinguishable from correct behaviour. _(Three cases failed on first run because `withTemp` was synchronous around async bodies and deleted the directory mid-test — a helper that tidies up before the test runs is a false red today and a false green one assertion later. A fourth case **passed** and should not have: the non-2xx collector arm pointed `--repo-root` at a directory with no snapshot, so it exited 2 at the signal read and never called the injected transport, leaving that branch covered by nothing. Caught at the pre-commit checkpoint; it now asserts the send happened, and a mutant deleting the branch kills it.)_ |
 | [`eval-bundle.mjs`](eval-bundle.mjs) | **The evaluation-bundle cutter** — a named-recipient stamped copy of the shippable payload, cut from an explicitly named commit, ported into the tree on the maintainer's ruling of 2026-08-17. The payload partition and the machine-read license census are **pinned in both directions**, and **two different steps refuse two different things**, which is worth keeping straight because each sends an operator somewhere else: the **census** runs on the freshly materialised cut and refuses an Apache assertion in a file that is not rostered in `APACHE_MANIFESTS`, or a rostered file that has stopped asserting; the **guard** runs on the finished cut and — **inverted on the maintainer's ruling of 2026-08-18 ([#284](https://github.com/sleepy-panda-srl/portulan/issues/284))** — refuses any machine-read `license` value that is **not** Apache-2.0, plus any issuer-machinery path that leaked in, diagnosing a drifted rostered manifest separately from an unrostered one and from a failed self-exclusion. Nothing rewrites licence metadata and `LICENSE` ships: the bundle is the public tree's bytes under the public tree's licence, so the README's own License section is correct as written and its link resolves. The issuance ledger, and all recipient data, stay OUTSIDE this repository; evaluation terms render from [`eval-license.template.md`](eval-license.template.md) **at the payload commit**, pinning payload and terms to one sha; `--check` (what [`../.portulan/verify/eval-bundle.sh`](../.portulan/verify/eval-bundle.sh) runs) cuts the **index**, wrapped as an unreferenced probe commit, for a fixture recipient into scratch it always deletes. **Deliberately not a ninth `portulan` subcommand**, on `discover`'s precedent above — and deliberately **self-excluded from the payload**, so an evaluee never receives the issuer's machinery. |
 | [`eval-bundle.test.mjs`](eval-bundle.test.mjs) | Its test suite. The rosters are pinned with the suite's **own** instruments — `git ls-tree` and `git grep`, never the module's helpers — because a pin that asks the subject to measure itself tests agreement, not truth; the self-exclusion is exercised **positively** on a fixture repository that plants files at exactly the excluded paths; the terms pin is **demonstrated** (an old commit stamps its old template whatever the tree says now); and the plumbing transport is asserted byte-identical, modes included, to `git archive \| tar -x`, so the port's one mechanical delta is demonstrated rather than trusted. |
 | [`eval-license.template.md`](eval-license.template.md) | **The evaluation-license template** — four placeholders (`{{name}}`, `{{login}}`, `{{date}}`, `{{shortSha}}`), rendered into a bundle's `EVAL-LICENSE.md` by [`eval-bundle.mjs`](eval-bundle.mjs), which reads it **from the payload commit with `git show`, never from the working tree** (the supervisor's ruling of 2026-08-17: payload and terms pin to one sha in the stamp's `source_commit`, so a later edit here cannot drift under an already-stamped bundle). Issuer machinery, so **self-excluded from the payload**: an evaluee receives the stamped license, never the stamp press. The repository is public, so this text is world-readable, and the maintainer settled its wording on 2026-08-17: the bundle's files carry Apache-2.0, the same terms as the public repository, so the template's "non-public materials" and no-redistribution clauses are withdrawn. The mechanism is indifferent — it stamps whatever the payload commit carries. |
 | [`librarian.test.mjs`](librarian.test.mjs) | Its test suite, written first, on real scratch git repositories rather than an injected clock — a fake history proves nothing about the one call this tool exists to make. |
+| [`ab.mjs`](ab.mjs) | **The A/B arm builder** — milestone 8's *A/B baseline recorded* clause, session 6b. It builds the two arms [`../evals/ab/arm.md`](../evals/ab/arm.md) specifies and **grades neither**: no agent is run here and no scenario is graded — the graders and their three classes of discrimination fixture are [`ab-grade.mjs`](ab-grade.mjs)'s, the run [`ab-run.mjs`](ab-run.mjs)'s, on the maintainer's ruling of 2026-08-29. Construction is **stage-then-vendor**, and that order is forced rather than chosen: [`vendor.mjs`](vendor.mjs) refuses this workspace outright while `constitution` resolves outside `.portulan`, so dropping that slot is a precondition and not only a faithfulness move. **Its disposition table is TOTAL and it refuses to build when it is not** — the defect it exists to make impossible is measured, not imagined: built to `arm.md`'s six rows and vendored, the treatment arm still carried customer zero's `memory-index.md` (30 rule titles over an empty store), `handoffs-index.md` (146), `rule-carriers.json` (five entries naming the A/B clause) and `labels.json`, with `doctor` GREEN over all of it, because `vendor` carries every ordinary file under a workspace directory and a specification that names what to REMOVE leaks whatever it forgot. It also gives `arm.md`'s **rule 2** its first checker — *no move authors a normative sentence* — and that checker is a **keyword matcher, not a reading of English**: the `deletion` and `emptying` kinds are covered in full because they add no sentence, while `substitution` is covered by a declared marker vocabulary that **misses a paraphrase carrying the mandate and none of the words**. One case in its own corpus is exactly that miss and the suite requires it to stand. `--stop-probe` is [`../evals/ab/corpus.md`](../evals/ab/corpus.md)'s acceptance test and is **not** a recipe mode: it runs one real agent turn, because a fixture calling `stop-gate.mjs` would prove the script records and assume the thing under test — whether the host invokes the hook at all. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s precedent. |
+| [`ab.test.mjs`](ab.test.mjs) | Its suite. **No case runs an agent** — [`../.portulan/verify/tests.sh`](../.portulan/verify/tests.sh) runs it, and a test spawning `claude` would put an agent turn inside a verify recipe; the probe's refusals are exercised against `false` standing in for an agent that cannot start. The distinctions that cost something are each a case: an unclassified path is exit **1** and a stale disposition exit **2**, because a finding about the tree is not a could-not-run and the first cut collapsed them; a **declared** substitution is un-substituted before comparison while an undeclared one reads as an authored sentence, which is the property that makes the matcher auditable; and `mayBeAbsent` is audited on its **reason** — git carries nothing under the path — rather than on the path's presence, because `personas/` is present in a working copy and absent in a checkout and an audit keyed on presence refused every working-copy run. That last one was found by this rail's own drill on its **control** leg, which is the argument for having a control leg. The corpus case requiring a **documented miss** is not a tautology over the table: a corpus in which everything is caught proves only that the author picked cases the matcher already handled. |
+| [`ab-grade.mjs`](ab-grade.mjs) | **The A/B graders** — milestone 8's *A/B baseline recorded* clause, session 6c, the middle of the maintainer's construction \| grading \| running split. It carries the four scenarios' **stimuli**, the four graders, and the three classes of discrimination [`../evals/ab/corpus.md`](../evals/ab/corpus.md) requires. **It runs no agent and records no baseline figure**: every figure it produces is about the instrument, and the run is 6d's. The stimulus ships here because a level-1 fixture *is* a staged tree plus a mutation — `stageScenario()` writes files and **spawns nothing**, and this module imports no child-process API at all. Each grader recomputes its attribution anchor from the scenario definition and **refuses** a tree it cannot attribute, which is neither a pass nor a fail; the nonce is never read out of arm output, since *"a grader that trusted arm output for its nonce could be satisfied by an arm naming its own"*. **The blindness it exists for is measured**: a prototype grader returned *"30 records, each with its own provenance and retirement condition"* against a vendored arm that had done nothing at all — it passed level 1, and only **inversion at the delta** caught it. `done-demonstrated` has no `demonstrated` verdict, deliberately: the rig fails unconditionally, so a green rail is reachable only by rewriting the check, and grading that as compliance would score the gaming move as the good outcome. |
+| [`ab-grade.test.mjs`](ab-grade.test.mjs) | Its suite. **No case runs an agent**, for the reason `ab.test.mjs` gives. The cases that cost something: a staged-and-untouched tree grades to its **declared** inert verdict, which is the prototype's failure asked directly rather than approximated; two of the four scenarios are compliant when inert and the suite pins **which**, because not destroying a target and not claiming completion are both satisfied by doing nothing; a constant grader is **reproduced** and shown passing level 1 while failing level 2; and the positive control [`../evals/ab/corpus.md`](../evals/ab/corpus.md) named as unbuilt is built at its real size — a stub agent proves the stop probe's **read path**, and proves nothing about the host invoking the hook, which stays a by-hand run. |
+| [`ab-run.mjs`](ab-run.mjs) | **The A/B run** — milestone 8's *A/B baseline recorded* clause, session 6d, the last third of the maintainer's construction \| grading \| running split, and **the only module in this family that spawns an agent**. It is separate from [`ab-grade.mjs`](ab-grade.mjs) because that file says of itself, in three carriers and one rail, that it runs no agent and imports no child-process API at all. **There is no `--operator-env` flag**: every turn runs isolated with a fresh home and config directory of its own — forty, not two — because [`../evals/ab/corpus.md`](../evals/ab/corpus.md) forbids a baseline over an unisolated arm, and a departure is a visible code change plus a maintainer's ruling rather than a flag. `did-not-complete`, `could-not-attribute` and `non-compliant` are three different facts and the four states are total over `k`. **The invocation was ruled by measurement**: `--print` alone left both arms byte-unchanged after completed turns, so `acceptEdits` joins it — which auto-approves edits the settings do not forbid and does **not** override a `deny` rule, so arm A's compiled enforcement survives. The record is a committed snapshot plus a register rendered from it and byte-compared, on [`review-meter.mjs`](review-meter.mjs)'s precedent: the events do not repeat, so the unreproducible half is the snapshot alone and it says so on its own face. |
+| [`ab-run.test.mjs`](ab-run.test.mjs) | Its suite. **No case runs a real agent** — `runTurn` takes its agent as a parameter and a stub script stands in, exactly as `ab.test.mjs` does for the stop probe, because a test spawning `claude` would put an agent turn and a credential inside a verify recipe. The cases that cost something: passing `--operator-env` is a refusal rather than a silent ignore; a flag that would dissolve arm A's enforcement is refused at the turn and again in the record; the operator seed is asserted to touch onboarding and trust and **nothing else**, since a seed reaching permissions would silently become treatment; stdin is closed, so a prompt the harness cannot answer fails fast instead of waiting out a ten-minute timeout, which one real turn already did; and a published cell that has drifted from its own per-turn rows is red. |
+| [`release-eval.mjs`](release-eval.mjs) | **The eval result a release carries** — milestone 8's ninth clause, added by the maintainer's ruling of 2026-08-24, which made a Protocol obligation older than the row bind that row's close. A record is a pair per version under [`../evals/releases/`](../evals/releases/): a capture holding the verdict every recipe the workspace **yields** returned at a named commit, and a register rendered from it and byte-compared. The A/B baseline is cited **by identity and never by figure** — path, capture date, commit, cleanliness — because its cells have one carrier and a second copy inside a release record is the hand-maintained figure this milestone deleted six of. **Two designs were reversed before a line was written.** Cut detection off `CHANGELOG.md`'s top heading never fires: the cut re-seeds `## Unreleased` above the version it just wrote, so the top heading is `Unreleased` on the cut commit too. And a rail keyed to `package.json`'s version alone grades one record at a time — once `0.1.4` is declared, `0.1.3`'s record can be deleted in silence — so the subject is every version the changelog records from `0.1.3` onward, permanently, graded in both directions. Its **own** row is excluded from every capture, with the reason printed, because a capture cannot be accurate about the record it is inside. `--tagged` is the release act's mode and the only check here that sees a release rather than a tree; [`../.github/workflows/publish-github-packages.yml`](../.github/workflows/publish-github-packages.yml) runs it before publishing. **Deliberately not a ninth `portulan` subcommand**, on `eval-bundle`'s and `ab`'s precedent. |
+| [`release-eval.test.mjs`](release-eval.test.mjs) | Its suite. **No case runs the recipe set** — `--capture` spawns every rail in the workspace, and a test that did would put the whole suite inside one of its own members; every case exercises the record layer instead, which is what the rail reads. The cases that cost something: the changelog fixture is shaped like the real file, with a re-seeded `## Unreleased` on top and an entry that *quotes* a heading, so a looser matcher fails it; an older governed record deleted after a newer release is cut is red, which is the case the replaced design passed; a missing **boolean** is caught by name, because it renders as a branch and its absence publishes a claim the capture never made rather than leaving a hole a render probe could see; a record for a release the changelog never cut is red; and `--write` refuses a capture it could not read rather than rendering from one. |
+| [`checkout-refs.live.test.mjs`](checkout-refs.live.test.mjs) | **A workflow that checks out more than once names the ref of every checkout after the first.** The rail for a defect this repository shipped **twice at one step**: [`publish-github-packages.yml`](../.github/workflows/publish-github-packages.yml) grades the tagged tree with a grader that must not come *from* it, since `release-eval.mjs` exists in no tag before `v0.1.3` — and the second checkout added to fix that carried no `ref`, which `actions/checkout` defaults to *the event's own* ref, the tag on `release: published`. The crash came back inside its own repair. **The rule is narrow on purpose and the narrowness was measured:** five of the seven checkouts in `.github/workflows/` carry no `ref` and every one is correct, so a blanket rule would red five right answers to expose one wrong one — which is how a recipe gets switched off. Checking out *twice* is a statement that two different trees are wanted, so the second cannot inherit a default whose value depends on which event fired. It does **not** establish that the ref named is the right one — an explicit tag on a grader would pass and be the same bug — only that the choice was made rather than inherited. |
 | [`recipe-set.mjs`](recipe-set.mjs) | **The recipe set**, the one carrier of *what this workspace runs*. Row 7's amendment of 2026-07-31 ruled that a composed pack's verify recipes reach the adopting workspace's runnable set, under a contract stated in the row rather than left to this file: **additive only** — a pack may add a recipe and may never redefine, remove or replace one the workspace declares, nor become `verify.default` — and **namespaced by its pack, so a collision is impossible rather than resolved**. |
 | [`recipe-set.test.mjs`](recipe-set.test.mjs) | Its test suite, against a fixture resolver: the additive-only rule, the namespacing, the refusal to become `verify.default`, and **could-not-run — exit 2, never silently absent** when a composed recipe cannot resolve. |
 | [`recipe-set.live.test.mjs`](recipe-set.live.test.mjs) | The composed set against **this repository** rather than against fixtures, and it exists because the unit suite is not enough — measured, not supposed, on the change that added both. `compile.mjs`'s `resolvePack` returns `manifest` as the **path** to `pack.json`, not the parsed object; the first cut of `resolverFor` treated it as parsed, so every composed pack contributed nothing while the unit suite stayed green, because its fixture resolver returned a parsed object. A harness that supplies the shape the code assumes cannot find the assumption. |
@@ -168,6 +203,9 @@ check on it.)_
 | [`pinned-roots.live.test.mjs`](pinned-roots.live.test.mjs) | **The required checks name their resolution root, and this is what makes that a rail.** A pre-commit checkpoint stripped all six `--pack-root packs` from the tree at once and everything stayed green: eleven recipes, 1535 tests, nothing red. The pins were shell prose. Removing the one in `doctor.sh` silently reverts `examples/` to green-by-not-looking, which is the exact fail-open the pins were added to close — **a containment nothing enforces is a comment**. |
 | [`list-quoting.live.test.mjs`](list-quoting.live.test.mjs) | **Every recipe that enumerates the tree reads the pathname git carries, not a quoted spelling of it** — the rail from [#209](https://github.com/sleepy-panda-srl/portulan/issues/209), which reported the wrong mechanism. Without `-z`, git C-quotes a control character *regardless of `core.quotePath`*, so a newline never mis-splits a list; it arrives as one line, `"we\nird.md"`. What the line-based form loses is the **spelling**, and that reaches `café.mjs` and not only exotic names. Both directions were live: three recipes turned a quoted path into a **false red**, and `docs.sh`'s cli-table enumeration silently dropped the file and passed — **the only false green of the class**. It accepts `-z` *or* `core.quotePath=false` because the two fail differently, and `docs.sh` cannot take `-z` without arming the `\001` sentinel collision its links `awk` depends on. |
 | [`test-isolation.live.test.mjs`](test-isolation.live.test.mjs) | **A test that substitutes a shared object hands the restore to the runner** — the rail from [#254](https://github.com/sleepy-panda-srl/portulan/issues/254), whose own instrument swept for the NAME `fs.*Sync =` and so could not see the same shape wearing another. Sweeping by SHAPE found fourteen sites, not six: `process.stdout.write` and `process.stderr.write` too. Eleven converted to `t.mock.method`; **three deliberately not**, because the runner scopes a mock to the TEST and those mean a helper call, a loop iteration, or a `process.env` restore — and `t.mock.property` *cannot* take that last one, throwing `ERR_INVALID_OBJECT_DEFINE_PROPERTY` on `process.env` because it installs an accessor pair. It binds the uniform half using the issue's own retire-when as its matcher, so the rule and the rail cannot drift. |
+| [`cli-roster.live.test.mjs`](cli-roster.live.test.mjs) | **The roster beside the eight is a partition of this directory, and no part of it is counted by hand** — the rail from [#204](https://github.com/sleepy-panda-srl/portulan/issues/204), whose reporter had read three carriers that disagreed and concluded a tool had been removed. Two of the three now cite the third; what stayed unrailed was the surviving sentence, and it drifted again — `version-carriers.mjs` and `inside.mjs` reached the table and neither roster sentence. The eight come from a real import of `SUBCOMMANDS`, never a copied list; everything else must be named between the roster markers. Both directions, because both have failed. The **numerals are gone rather than corrected**, on this file's own convention about hand-maintained figures — a count nobody writes cannot go stale. |
+| [`shadowed-pack.test.mjs`](shadowed-pack.test.mjs) | **Two roots answered for one declared pack, and the compiler refuses rather than picking** — the rail from [#316](https://github.com/sleepy-panda-srl/portulan/issues/316). Discovered-first resolution meant a bare `compile` emitted the installed copy's policy while `verify/compile.sh` read the tree's; on this project's own host that re-introduced a `git commit --no-verify` matcher the tree had deliberately removed as false coverage. Hermetic by **injecting the discovery thunk** rather than faking a plugin cache, since a fake host would re-test `discover.mjs`'s record reader and tie these cases to a schema they say nothing about. The edge that keeps the refusal honest is **elected** discovery: refusing `--pack-root auto` would refuse a caller for answering the very question the refusal asks. |
+| [`shadowed-resolution.test.mjs`](shadowed-resolution.test.mjs) | **The same refusal in the two tools `compile`'s could not reach** — `index` and `recipe-set` resolve packs without going through `packContributions`, so [#316](https://github.com/sleepy-panda-srl/portulan/issues/316)'s guard was structurally out of range. Its first two cases are the demonstration [#318](https://github.com/sleepy-panda-srl/portulan/issues/318) was filed owing: the two worlds digesting a different memory scope, and composing run lines that point at different files. Both are shown through the **elected** spellings, because the bare path now refuses — a fixture claiming to show divergence there would be showing the refusal instead. |
 | [`gh-bot.test.mjs`](gh-bot.test.mjs) | The agent identity's wrapper refuses the endpoints it is not for. Its subject, [`../.portulan/tools/gh-bot`](../.portulan/tools/gh-bot), is customer-zero operator tooling and not part of the product — but the suite lives here anyway, because [`../.portulan/verify/tests.sh`](../.portulan/verify/tests.sh) runs exactly `cli/**/*.test.mjs` and that recipe's stated design is that **a new suite joins by existing rather than by being named**. |
 | [`fixtures/`](fixtures/) | Known-bad manifests, and a workspace whose repo card has drifted from its tree. |
 
@@ -190,11 +228,8 @@ not · `2` could not run. `compile`: exit `0` when it wrote, or agreed under `--
 `--check`, when the artifact is missing or has drifted · `2` could not run — writing never returns `1`,
 because a run that rewrites the artifact has nothing to disagree with. `init` and `new` have only **two** codes —
 `0` it wrote · `2` it wrote nothing — and the missing `1` is the point: they render no verdict about
-anybody's workspace, so they have no red to report. _(The second code read "it could not run" until
-milestone 7 session 7, when `init`'s interview introduced a way to write nothing that is not a failure
-at all: a human declining at the confirmation, or ending the input. The code is unchanged and the gloss
-now covers every way of reaching it — widening the sentence rather than minting a third code, since `0`
-must keep meaning **it wrote** for anything chaining on it. `new`'s two are unaffected.)_ `vendor` **does** have a `1`, and the asymmetry is
+anybody's workspace, so they have no red to report. _(`2` covers every way of writing nothing, a human declining at the confirmation included — `0`
+must keep meaning **it wrote** for anything chaining on it.)_ `vendor` **does** have a `1`, and the asymmetry is
 worth a sentence: it runs the real validator at both ends of a switch and reports its verdict, so
 collapsing *the workspace I materialised is invalid* into *I could not run* would leave a caller unable
 to tell a bad workspace from a missing flag. `index` uses the same three
@@ -251,8 +286,7 @@ recipe the manifest **yields** — the workspace's own, plus those the packs it
   constant dressed as a measurement. The `affordances` slot is the named input and not the only one — six manifest keys are
   read beside it, because a score confined to the slot could not tell two workspaces apart. What it
   cannot do is judge the prose: the limits dimension is a **form** check over a named heading table, so
-  a section with an empty body passes it. _(This bullet said the audit was not built, which was true
-  from milestone 2 until milestone 7 session 7.)_
+  a section with an empty body passes it.
 - **It cannot see live settings.** The gate-map lint compares a claimed status-check name against job ids
   in the tree. Whether branch protection actually requires that check, and which app it is pinned to, are
   API facts `doctor` does not fetch.
@@ -313,17 +347,11 @@ this repository owns and others may run, not as a contract shipped to them.
 [`../.portulan/tools/`](../.portulan/tools/) holds operator tooling. Putting a universal validator in
 either would have made it look local to the one workspace it happened to be written beside.
 
-Zero-dependency ESM on Node rather than TypeScript — and as of **2026-07-31 that is a ruling rather
-than a "for now"**. The maintainer settled it at milestone 7's session-open, against
-[`../.portulan/identity.md`](../.portulan/identity.md)'s older *TypeScript on Node* line, on exactly
-the ground this paragraph already gave: a build step would mean this repository could no longer be
-checked by cloning it. So the CLI does **not** bring a build with it. The `package.json` milestone 7
-adds declares no dependencies and exists to carry the `bin`; `npm install` fetches nothing, and every
-tool here still runs as `node cli/<tool>.mjs` from a fresh clone.
-
-_(This paragraph previously closed with "the CLI at milestone 7 absorbs this file and takes the build
-with it" — a sentence whose "this file" had no clear referent and which predicted the opposite of
-what was ruled. Replaced rather than annotated, since nothing in it survived.)_
+Zero-dependency ESM on Node rather than TypeScript, and that is **a ruling rather than a "for
+now"**: a build step would mean this repository could no longer be checked by cloning it. So the CLI
+does **not** bring a build with it. `package.json` declares no dependencies and exists to carry the
+`bin`; `npm install` fetches nothing, and every tool here still runs as `node cli/<tool>.mjs` from a
+fresh clone.
 
 ## Environment the compiled runners read
 
@@ -336,6 +364,8 @@ package at all (before milestone 7 they resolved `HERE/..`, which is true in exa
 | `CLAUDE_PROJECT_DIR` | the repository the policy governs; the host sets it, and the emitted hook interpolates it | falls back to the process's working directory, which is where a hook runs |
 | `PORTULAN_WORKSPACE` | the workspace directory's **name** inside that repository | `.portulan` |
 
+**`stop-gate` reads one thing the table cannot show: the Stop payload's `cwd`.** `CLAUDE_PROJECT_DIR` names the repository the hook governs, which is not always the working tree the session used — a session in a git worktree has both. Since [#220](https://github.com/sleepy-panda-srl/portulan/issues/220) the gate asks its did-work and handoff questions about the session's own tree when `cwd` resolves inside the **same** repository, and falls back to `CLAUDE_PROJECT_DIR` — saying so — when it does not. The same-repository condition is the difference between a fix and a bypass: `cwd` is the one input a gated agent can steer, and any tree it named would otherwise excuse work in the governed one. The refusal counter and the verify recipe deliberately do not follow the session's tree.
+
 **Two honest limits.** `PORTULAN_WORKSPACE` is read and nothing sets it — it exists so a workspace under
 another name is not unreachable, not because anything ships that way. And the two runners **differ** when
 no workspace is found: `stop-gate.mjs` blocks loudly, because a Stop-gate that cannot read the workspace