@sleepy_panda_srl/portulan 0.1.3 → 0.2.0

package/cli/gate.mjs

@@ -1,185 +1,27 @@
 #!/usr/bin/env node
 // The PreToolUse gate runner — the *explanation* half of the enforcement compiler.
 //
-// Wired by `./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*: the rules in
-// `.portulan/gates.json` plus the fragments its packs contribute — see "The policy this runner reads"
-// below, which is the whole of what `#269` was.
-//
-// ## This file is not the gate. Read that twice.
-//
-// The gate is the `permissions` rule the same compiler emits. This runner exists because a bare
-// "permission denied" teaches nobody anything, while `gates.json` already holds a sentence written
-// for exactly this moment. The split is forced by a measurement, not by taste: on CLI 2.1.220 a
-// PreToolUse hook that CRASHES **fails open** — the tool proceeds — on the identical wiring that
-// blocks when the hook is healthy. So a hook can never be the load-bearing layer here, and this one
-// is written to fail open *deliberately and visibly* rather than pretending otherwise:
-//
-//   any internal error => exit 0, emit nothing => the permission rule governs, unchanged.
-//
-// Refusing loudly on error *is* available — a hook exiting 2 blocks — and it is still wrong here, for a
-// reason worth stating precisely rather than with the hand-wave an earlier draft used. If this runner
-// failed closed, a malformed `.portulan/gates.json` would deny EVERY matched tool call until someone fixed it:
-// an undriveable session, whose only repair is inside the repository it can no longer edit. What is lost
-// by stepping aside is bounded and known — the wrapper coverage and the sentences — because the
-// permission layer never reads that file at runtime.
-//
-// ## Why the decision mirrors the permission rule
-//
-// `prohibited` => `deny`, `gated` => `ask`. The hook returns the SAME decision the permission rule
-// carries. A hook returning `deny` for a Gated action would convert a per-action prompt into a hard
-// block — that is the tier above it, and collapsing the two would make the constitution's
-// protection indistinguishable from an ordinary push.
-//
-// ## What this layer is FOR, which is not what its author first assumed
-//
-// The first version of this runner existed to supply a better sentence than "permission denied".
-// Measured, that was wrong: when a permission rule matches, **the host runs this hook and then
-// discards its reason** — the permission layer's generic message is what the agent sees. Verified
-// with a canary that recorded both the invocation and the command it saw. A hook emitted purely to
-// improve a message it cannot reach would be an inert component that reads as an active one, which
-// is the defect this repository already has a rule about.
-//
-// So the split earns its keep somewhere else: **this layer covers what the permission pattern
-// cannot.** Two things, and in both the permission layer has nothing to say, so this decision AND
-// its sentence are what the agent gets:
-//
-//   1. The WRAPPER spelling. `Bash(git push:*)` is a prefix match against the literal command, so
-//      `bash -c "git push …"` is invisible to it — measured, and the reason
-//      `../core/operating/autonomy.md` calls the platform floor the gate that holds when this
-//      layer fails. This runner unwraps one level of `sh -c` / `bash -c` / `zsh -c` before matching.
-//   2. A SHELL WRITE to a path a `write:` rule protects. `Edit(./docs/vision.md)` denies all three
-//      file-editing tools — ONE emitted pattern, which the host matches for every one of them — and
-//      `echo x >> docs/vision.md` is a fourth way to the same bytes. `matchesRule` now
-//      answers for `Bash` on a write rule, by a table of redirections and file-writing commands
-//      that `./compile.mjs` states in full.
-//
-// Two layers, two jobs: the permission rule cannot fail open, and this one covers more ground.
-// **The second case above is the uncomfortable one**, and it is named in `../gate-map.md`'s
-// honest-holes list rather than left here: it is the only gate whose sole layer is this file, so
-// every "fails open" sentence above is, for shell writes to the constitution, the whole story
-// rather than a footnote about a lost message.
-//
-// **One level of unwrapping, and no more.** Deeper nesting, a heredoc, an interpolated variable, a
-// command assembled at runtime — all still escape, and no amount of parsing here would close that.
-// The same is true one layer over: a write spelled through a runtime (`python3 -c`) or a writer
-// outside that table reaches the file. Anything that must not happen regardless of spelling belongs
-// on the platform floor, not in a matcher.
+// On Claude Code 2.1.220 a PreToolUse hook that crashes fails open, so the compiled permission rule is the gate.
+// Any internal error exits 0 with no decision, so the permission rule governs unchanged.
+// It covers what a permission pattern cannot: one level of `sh -c` wrapping, and a shell write to a path a `write:` rule protects.
 
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-// The action vocabulary is defined ONCE, in the compiler, and imported here. Two implementations of
-// one matcher is the drift this repository keeps finding — and a matcher that drifts does not look
-// wrong, it looks like a gate that quietly stopped covering something.
-//
-// **The same argument reaches one level up, and for a milestone it was applied only to the matcher.**
-// Importing `matchesRule` kept the two layers agreeing about what an action *is* while they disagreed
-// about which rules *exist*: this file read the workspace's declared policy, and `./compile.mjs`
-// enforced that policy plus its packs' contributions. `packContributions` and `composeFragments` are
-// imported for the same reason as the matcher — a second composer would drift the same way — and
-// `doctor` took this identical repair for this identical noun one session earlier.
 import { matchesRule, policyPath, packContributions, composeFragments, parse } from "./compile.mjs";
 
-// **The project root is TOLD to this runner, never derived from where this file sits.**
-//
-// It used to be derived: this file lived at `.portulan/compile/gate.mjs`, so `HERE/../..` was the
-// repository and `basename(HERE/..)` was the workspace directory. That worked for exactly one layout —
-// the author's — and it is why the file could not ship. Milestone 7 moves both runners into `cli/` so an
-// adopter actually receives them (`package.json`'s `files` never carried `.portulan/`, so every compiled
-// policy named a file the adopter did not have, and a missing hook fails open). From `cli/`, and even
-// more so from `node_modules/@sleepy_panda_srl/portulan/cli/`, this file has no idea where the
-// adopter's workspace is — and inferring one would be #131's class, paths resolved against the author's
-// layout, in the tool with the most to lose from it.
-//
-// `CLAUDE_PROJECT_DIR` is what the host sets and what the emitted hook already interpolates; `cwd` is the
-// honest fallback, because a hook runs from the project. `||` rather than `??` on purpose: an env var set
-// to the empty string must fall through to `cwd`, not resolve every path against `""`.
-//
-// **What happens when no workspace is found differs between the two runners, and the first draft of this
-// paragraph claimed the stricter behaviour for both.** THIS file steps aside silently — `main()` catches
-// and returns without a decision — which is its own defended design: a PreToolUse hook that cannot read
-// the policy must not block every tool call, and the permission rules compiled beside it still hold, so
-// the layer degrades rather than disappearing. `./stop-gate.mjs` does the opposite and blocks loudly,
-// because a Stop-gate that cannot read the workspace has nothing beneath it. Stated per file rather than
-// as one sentence covering both, since they genuinely differ and the difference is the interesting part.
+// `||` so an empty CLAUDE_PROJECT_DIR falls back to cwd, the directory the host runs a hook from.
 const PROJECT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const WORKSPACE_DIR = process.env.PORTULAN_WORKSPACE || ".portulan";
 const POLICY = policyPath(PROJECT, WORKSPACE_DIR);
 
-/** Exit without a decision. The permission rule still holds; only the sentence is lost. */
 function stepAside() {
     process.exit(0);
 }
 
-// ## The policy this runner reads
-//
-// **Declared plus composed, and until #269 it was declared alone.** A pack contributes gate fragments
-// (`contributes.gates` in its `pack.json`); `./compile.mjs` composes them onto the workspace's own rules
-// before it emits anything, so the permission rules sitting beside this hook are compiled from the
-// composed set. This file read `.portulan/gates.json` and nothing else, so a rule a pack contributed was
-// enforced by the layer that cannot say why and invisible to the layer whose whole job is the sentence —
-// and for a `prohibited` fragment with a matcher, the two layers returned different decisions.
-//
-// **What this cost on THIS repository is nothing, and saying so is the point.** Its one gate-contributing
-// pack (`rituals/checkpoints`) contributes two fragments and both carry `action: {none: …}`, which no
-// matcher can reach — `compile --matrix` lists them among the gates no backend compiles. So the defect
-// here was latent rather than live, and it is fixed on the shape rather than on an incident. The demonstration
-// in `./gate.test.mjs` uses a fixture whose pack contributes a *matchable* fragment, because manufacturing
-// a live case would have meant giving a `none` rule a matcher — reversing the ruling recorded in
-// `../.portulan/proposals/0029-a-constraint-names-a-category-not-a-list.md` Q3, which removed one.
-//
-// **Three limits, named rather than left to be measured.** _(This said "Two" while enumerating three:
-// the third arrived with the round-1 fix below and the count above it did not move. Exactly the
-// undercount-by-enumeration `../.portulan/gate-map.md`'s own `action none` row was corrected for on
-// 2026-08-14, repeated here within the week. Found by Copilot on #272, round 2.)_
-//
-// The three share one principle, and stating it is what keeps a later reader from deriving the wrong
-// rule from the pair: **this runner degrades toward whatever intact policy remains — composed to
-// declared, declared to nothing — and never toward a block.** It is never the load-bearing layer, so
-// every arm below hands the decision back rather than taking it.
-//
-//   1. **No discovery.** `packContributions` is called with no `discovery` thunk, so `resolutionRoots`'
-//      unasked arm never consults the host's plugin cache and roots come from the workspace manifest's
-//      `tree` alone. Deliberate twice over: this runs on every tool call, and a gate whose answer moved
-//      with what is installed on the machine would be a gate nobody could review. A pack resolving ONLY
-//      from the host cache therefore contributes to what a bare `compile` yields and not to what this
-//      hook composes — the residual gap, stated in `../.portulan/gate-map.md` and owned by `#264`.
-//   2. **A composition failure falls back to the DECLARED policy**, and does not step aside. Composition
-//      only ever adds a rule or raises a tier — `composeFragments` throws on a demotion rather than
-//      applying it — so the composed policy is never weaker than the declared one, and falling back can
-//      only lose coverage this file already had rather than drop below it. Stepping aside instead would
-//      let a malformed `pack.json` switch off gates the workspace declares in its own file, which hands a
-//      dependency a lever on the layer above it. `./compile.mjs` refuses to build in the same case, and
-//      the divergence is the intended one: it fails closed at build time against a file you can edit,
-//      while this runs on every tool call.
-//   3. **The composed policy is VALIDATED, by the same `parse` the compiler validates with.** Composition
-//      checks a fragment's *tier* and, when tightening, that the action shape is unchanged; it does not
-//      check that an ADDED fragment is a well-formed rule. So a pack contributing
-//      `{id, tier: prohibited, action: {shell: curl}}` and no `reason` composed cleanly and this hook
-//      denied with the sentence `— undefined`, where `compile` refuses the same input at exit 2 with
-//      *"rule `no-reason` carries no reason — a gate with no sentence to show a human is not finished"*.
-//      Measured, on the runner. The two layers disagreeing about whether a policy is admissible is this
-//      file's own defect one step further in. Raised by Copilot on #272, round 1, in the suppressed
-//      channel. **The limit, since the fix is narrower than it reads:** this covers the COMPOSED arm. A
-//      rule missing its `reason` in the *declared* policy still denies with `— undefined`, byte-identically
-//      with every predecessor — because the fallback for an inadmissible declared policy is that same
-//      policy, and stepping aside there would drop a live prohibition over a missing string. `compile`
-//      refuses that shape at build time, which is where it belongs. Pinned in `./gate.test.mjs` so the
-//      arm cannot be quietly converted to a step-aside.
-//
-//      **Validation only — the decision is still made on the composed policy, not on `parse`'s return.**
-//      Not because the parsed shape would not match: measured, `parse` returns rules carrying the SAME
-//      `action` object beside the added `kind`/`target`, and `matchesRule` answers correctly on them —
-//      a draft of this comment claimed otherwise and was wrong. The two real grounds: `parse` **refuses
-//      rather than normalises**, so once it passes, the composed and parsed forms are identical for
-//      matching and deciding on the parsed one buys nothing; and the fallback path has no parsed form to
-//      offer — an inadmissible policy produces none — so deciding on `parse`'s return would hand
-//      `decide()` two different shapes on its two paths, importing a representational seam rather than
-//      closing one. **If `parse` ever stops refusing and starts normalising, that change must sweep this
-//      hook too.** The check costs 0.003 ms against a ~30 ms invocation, 2000 iterations, so it is free.
+// No `discovery` option: packs resolve from the manifest's `tree` alone, never from the host's plugin cache.
+// Falls back to the declared policy when composing or `parse` fails: a broken pack cannot switch off the workspace's gates.
 function yielded(declared) {
     try {
         const { contributions } = packContributions(PROJECT, WORKSPACE_DIR);
@@ -191,41 +33,7 @@ function yielded(declared) {
     }
 }
 
-/**
- * The rule this call answers to: the STRONGEST gate it falls under, not the first one listed.
- *
- * This returned the first match for one milestone, which is not the same rule whenever two of different
- * tiers match one call: the weaker one wins if it is listed higher. The shape is ordinary rather than
- * exotic — one dangerous spelling prohibited beneath a prefix the workspace already gates broadly,
- * `git push` at `gated` and `git push --mirror` at `prohibited` — and it lands on `ask` for an action the
- * policy prohibits.
- *
- * **Composition makes that systematic rather than causing it, and a draft of this paragraph had it the
- * other way round** — *"indistinguishable from the strongest for as long as the policy came from one
- * file"*. Measured on a workspace composing nothing, with those two rules in that order: the old scan
- * answered `ask`, this one answers `deny`. What composition adds is that a contributed rule can never
- * win the tie-break, because `composeFragments` APPENDS added rules after the workspace's own — so a
- * pack-contributed `prohibited` rule is always the later one and always the one first-match discards.
- * That is #269's case reached through the ordering rather than through the missing rules, and closing
- * only the missing-rules half would have left it.
- *
- * Grounded in the policy's own semantics rather than in host precedence between two matching patterns,
- * which this repository has never measured and which nothing here needs: `prohibited` means the action
- * must not happen, so answering `ask` on a call the policy prohibits is wrong on the policy's terms
- * whatever the host does with the compiled pair.
- *
- * **It only ever moves a decision UP, and that is the honest form of the guarantee.** `prohibited` is the
- * top of the tier order and `gated` the only other tier considered, so "strongest, ties to the first" is
- * exactly *the first `prohibited` match if there is one, otherwise the first `gated` match* — which is
- * what the loop below is. Output is byte-identical wherever no two matching rules sit at different tiers,
- * and `ask` becomes `deny` where they do. **Not** "byte-identical for any workspace that composes
- * nothing" — that is the claim the counterexample above kills, and this repository is not evidence for it
- * either: its own policy is unchanged only because `edit-the-constitution`, the one `prohibited` rule it
- * declares, is listed FIRST, so first-match already returned it. Measured, on a command matching both it
- * and a gated shell rule: `deny` from either runner. Move that rule down the file and the two disagree.
- * The early return on `prohibited` also keeps the denied path's short-circuit: nothing later can outrank
- * the top of the order.
- */
+/** The strongest gate the call matches, not the first listed: a `prohibited` match outranks any `gated` one. */
 function decide(payload, policy) {
     const tool = payload.tool_name;
     const input = payload.tool_input ?? {};

package/cli/goldens.mjs

@@ -1,65 +1,6 @@
 #!/usr/bin/env node
 // Grade this workspace's compiled gates against a corpus of adversarial fixtures.
 //
-// Milestone 8, clause (a): *golden tasks reach the gates as well as the skills, so a matcher ships
-// with the attack cases that prove its coverage instead of prose describing it.*
-//
-// ## What this is FOR, at its real size
-//
-// `../.portulan/gate-map.md` carries an honest-holes list. That list was wrong when first published —
-// four items, five missing, the plainest of them a newline — and it was corrected by a supervisor who
-// tried to DEFEAT the matcher rather than read it. Fourteen review rounds then found three more live
-// bypasses the attack pass itself had not tried. Eight in all, every one found after the gate was
-// called done.
-//
-// A hole list is a claim like any other, and the only thing that checks it is somebody attacking it.
-// This runner is where those attacks live so they are re-run on every commit instead of on the day
-// somebody happens to look.
-//
-// ## The two things it rails, and the one it does NOT
-//
-//   1. **Coverage is measured, not named.** A rule that compiles to a matcher and carries no fixture
-//      is RED. So a new gate cannot ship with prose standing in for attack cases — the failure
-//      `../.portulan/memory/a-checkers-coverage-is-measured-not-named.md` names, turned into a check.
-//   2. **A documented hole stays documented in BOTH directions.** A `documented-hole` case asserts the
-//      matcher's CURRENT behaviour and names the hole record it belongs to. If the hole silently
-//      closes, that case goes red too — because a hole list that still lists a closed hole is as wrong
-//      as one that hides an open one, which is a sentence the gate map has had to write about itself.
-//
-// **What it does not rail: adequacy.** This is a PRESENCE floor. One trivial happy-path fixture per
-// rule satisfies clause 1 while proving nothing adversarial, and no check here can tell the
-// difference — judging whether a corpus is a real attack is exactly the judgement a reviewer is for.
-// Written down rather than left to be discovered, because a rail whose limit is unstated gets read as
-// the guarantee it is not. What the floor buys is narrower and still worth having: a gate cannot reach
-// the compiled policy with NO adversarial thought recorded against it at all.
-//
-// ## How a case is graded — and what is deliberately never done to it
-//
-// Every case is answered by `./compile.mjs`'s own exported `matchesRule`, the same function
-// `./gate.mjs` calls at hook time. Never a re-implementation: "two implementations of one matcher is
-// the drift this repository keeps finding, and a *matcher* that drifts does not look wrong — it looks
-// like a matcher" (`./compile.mjs`).
-//
-// **A fixture's command string is DATA and is never executed.** The corpus contains
-// `git push --force`, `rm -rf docs` and constitution-write spellings by design — running one would be
-// somewhere between tripping the gate under test and destroying the tree it runs in. There is no code
-// path from a fixture to a subprocess, and `./goldens.test.mjs` asserts that this module spawns
-// nothing at all.
-//
-// ## Which policy it grades
-//
-// The one the workspace YIELDS — its own `gates.json` plus the fragments its composed packs
-// contribute — never the declared file alone. A rail scoped to the declared list would let a composed
-// gate ship with no fixtures while this check stayed green, which is the class `../.portulan/dod.md`
-// condition 1 names in so many words and `./gate.mjs` already had repaired.
-//
-// Resolution is HERMETIC: no host plugin-cache discovery, ever. `compile --matrix` without a pinned
-// root refuses on this maintainer's machine as SHADOWED — an installed cache copy at one version
-// against the tree's at another — so a runner that consulted the host would grade the machine rather
-// than the tree, and its verdict would move with what happens to be installed. The recipe names its
-// root as well, on the pin discipline `../.portulan/verify/compile.sh` and `./pinned-roots.live.test.mjs`
-// already hold the compiler to.
-//
 // Exit 0 green · 1 red · 2 could not run.
 
 import fs from "node:fs";
@@ -76,60 +17,24 @@ import {
     parse,
     policyDeclaration,
     resolveWorkspace,
+    unreadableManifest,
 } from "./compile.mjs";
 
-/** Where the corpus lives, relative to the repository root. */
 export const CORPUS_DIR = "evals/goldens/gates";
 
-/** The action kinds `matchesRule` can answer for. A rule shaped otherwise has no matcher to attack. */
 export const MATCHABLE = ["shell", "write", "read"];
 
-/**
- * The two case classes, and why there are exactly two.
- *
- * `holds` is a regression pin: the matcher catches this today and must keep catching it. Every one of
- * the eight bypasses found on #60 is one of these — they are CLOSED holes, and the corpus exists so
- * they cannot quietly re-open.
- *
- * `documented-hole` is the other direction: the matcher does NOT catch this, the gate map says so, and
- * the case exists to keep that admission true. A third class for "we hope this gets fixed" was
- * considered and refused — it would be a wish, and a wish that goes green when someone fixes it is
- * indistinguishable from a hole that closed without its record being updated.
- */
+/** `holds`: the matcher catches the case and must keep catching it; `documented-hole`: it does not, as the gate map records. */
 export const CLASSES = ["holds", "documented-hole"];
 
-/**
- * Which branch of `matchesRule` a case exercises — the session-open checkpoint's adjustment 3.
- *
- * **Why a case must say this.** One rule id can be answered by two different segmenters with two
- * different answers, and the corpus contains a live example: a `then`/`do`/brace-group leader is
- * CAUGHT on the write path (`shellSegments` knows `SEGMENT_LEADERS`) and ESCAPES on the shell path
- * (`commandSegments` does not). A reader meeting those two cases without this field would take the
- * pair for a contradiction rather than for the asymmetry it is.
- *
- * **And why it is DERIVED rather than declared.** `matcherPath` computes it from the rule's action
- * kind and the case's tool, and `grade` refuses a case whose declared path disagrees. A field written
- * from memory on 212 cases is a second carrier of what `WRITE_TOOLS`, `READ_TOOLS` and the action kind
- * already decide — and this repository's standing finding is that the second carrier is the one that
- * goes wrong. Writing it down keeps it readable; deriving it keeps it true.
- */
+/** The branch of `matchesRule` a case takes, since two branches segment a command differently. */
 export const PATHS = ["matchesPath", "shell-write", "shell-prefix", "no-branch"];
 
-/**
- * The branch `matchesRule` will take for this rule kind and tool.
- *
- * `no-branch` is a real answer and not a gap: it names a combination the matcher has no code for, and
- * a case declaring it is asserting exactly that — `Bash` against a `read:` rule, or a write tool
- * against a `shell:` one. Those cases matter because the asymmetry between action kinds is the sort of
- * thing a reader assumes away.
- */
+/** `no-branch`: a kind and tool the matcher has no code for, such as `Bash` against a `read:` rule. */
 export function matcherPath(kind, tool) {
     if (kind === "shell") return tool === "Bash" ? "shell-prefix" : "no-branch";
     if (kind === "write") {
         if (WRITE_TOOLS.includes(tool)) return "matchesPath";
-        // Bash reaches a `write:` rule through `commandSegments` × `spellings` and then `shellWrites`,
-        // which segments AGAIN with `shellSegments`. Named for the entry, since that is what a reader
-        // needs to find the code; the docblock above carries the two-segmenter consequence.
         return tool === "Bash" ? "shell-write" : "no-branch";
     }
     if (kind === "read") return READ_TOOLS.includes(tool) ? "matchesPath" : "no-branch";
@@ -138,7 +43,6 @@ export function matcherPath(kind, tool) {
 
 export class CouldNotRun extends Error {}
 
-/** Read one JSON file, or say which file and why not. */
 function readJson(file, what) {
     let text;
     try {
@@ -153,37 +57,33 @@ function readJson(file, what) {
     }
 }
 
-/**
- * The rules this workspace yields, parsed.
- *
- * Composition runs BEFORE `parse`, exactly as `compile` does it, so a pack's fragment is graded by the
- * same code that grades a hand-written rule. Following the compiler's order rather than inventing one
- * is the whole reason this function is four lines of plumbing and no judgement.
- */
+/** Composed before `parse`, as `compile` does, so a pack's fragment is graded like a hand-written rule. */
 export function yieldedRules(named, { packRoots = null } = {}) {
     const { workspaceRoot, workspaceDir } = resolveWorkspace(named);
+    const unreadable = unreadableManifest(workspaceRoot, workspaceDir);
+    if (unreadable !== null) {
+        throw new CouldNotRun(
+            `${unreadable.file} is not a manifest this tool can read: ${unreadable.why}. Read as one declaring nothing, ` +
+                `it would have fixtures graded against a \`gates.json\` found by convention, which it may not name. ` +
+                `There is nothing to grade fixtures against`,
+        );
+    }
     const { file: policyFile, declared, reason } = policyDeclaration(workspaceRoot, workspaceDir);
-    if (!declared && !fs.existsSync(policyFile)) {
-        // **The fallback is THREE states and the message names which one.** This said
-        // `${workspaceDir}/workspace.json declares none` for all of them, which is a sentence that is
-        // false twice over: when the manifest does not exist there is nothing to have declared
-        // anything, and when it named a policy this compiler refused, it declared one and was
-        // overruled. Both send a reader to audit the one file that is not at fault — the failure
-        // `../.portulan/memory/verify-preconditions-fail-closed.md` names, and the failure
-        // `compile.mjs` had already learned at `undeclaredPolicyMessage`, whose own comment says
-        // "only the caller knows to name what the absence costs". I copied that call site's SHAPE
-        // and not its discipline. Reported as a suppressed note by Copilot, round 8 on #336.
+    if (reason === "refused" || (!declared && !fs.existsSync(policyFile))) {
         const why =
             reason === "no-manifest"
                 ? `there is no ${workspaceDir}/workspace.json, so nothing here has been authored as a workspace yet`
                 : reason === "refused"
                   ? `${workspaceDir}/workspace.json DOES name a gate policy, and it was refused — the manifest is not at fault, the path it names is`
                   : `${workspaceDir}/workspace.json declares no \`gates\` key, which is a legitimate shape and means the policy is expected at the default path`;
-        throw new CouldNotRun(`no gate policy at ${policyFile}: ${why}. There is nothing to grade fixtures against`);
+        const head =
+            reason === "refused" && fs.existsSync(policyFile)
+                ? `the \`gates.json\` at ${policyFile} is not the gate policy the manifest names`
+                : `no gate policy at ${policyFile}`;
+        throw new CouldNotRun(`${head}: ${why}. There is nothing to grade fixtures against`);
     }
     const policy = readJson(policyFile, "the gate policy");
-    // `discovery: null` and `forced: false`, always. See the header: a rail that consults the host
-    // grades the host.
+    // Never the host's plugin cache: a rail that consulted it would grade the machine, not the tree.
     const { contributions, unresolved } = packContributions(workspaceRoot, workspaceDir, {
         ...(packRoots === null ? { named: [] } : { packRoots }),
         discovery: null,
@@ -193,19 +93,6 @@ export function yieldedRules(named, { packRoots = null } = {}) {
     return { workspaceRoot, rules: parse(composed.policy).rules, unresolved };
 }
 
-/**
- * Split the yielded rules into the ones a fixture can attack and the ones it cannot.
- *
- * A rule whose action is `none` has no tool-level surface at all — `spend-money-or-register-a-domain`
- * and `send-something-outside-this-repository` are the standing examples, and both say so in their own
- * `action.none` prose. There is no input to hand `matchesRule` for them, so requiring fixtures would be
- * requiring a test of nothing.
- *
- * **They are named in the output on every run regardless**, and that is the load-bearing half. The
- * exemption is the obvious way to dodge this rail — write the next gate `none`-shaped and it needs no
- * attack cases — so the census prints them the way `compile --matrix` prints its own refused rules,
- * rather than letting the exemption be silent.
- */
 export function partition(rules) {
     const matchable = [];
     const exempt = [];
@@ -217,7 +104,6 @@ export function partition(rules) {
     return { matchable, exempt };
 }
 
-/** Every fixture file in the corpus, read and shape-checked. */
 export function readCorpus(repoRoot, dir = CORPUS_DIR) {
     const base = path.join(repoRoot, dir);
     let names;
@@ -234,13 +120,6 @@ export function readCorpus(repoRoot, dir = CORPUS_DIR) {
         if (typeof doc.rule !== "string" || doc.rule === "") {
             throw new CouldNotRun(`${where} names no \`rule\` — a fixture file attacks exactly one rule and must say which`);
         }
-        // **One fixture file per rule, named for it — checked, because this file already SAYS it.**
-        // The red for a missing fixture prints `add evals/goldens/gates/<rule-id>.json`, `evals/README.md`
-        // documents the layout, and nothing enforced either: a renamed or misfiled file validated
-        // cleanly and still graded, so the convention held by everyone remembering it. That is the
-        // shape `../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md` names, and this
-        // module was carrying one of its own while its whole subject is mandates that need checkers.
-        // Reported as a suppressed note by Copilot, round 5 on #336.
         if (name !== `${doc.rule}.json`) {
             throw new CouldNotRun(
                 `${where} declares rule \`${doc.rule}\` — one fixture file per rule, named for it, so rename it to ` +
@@ -277,12 +156,6 @@ export function readCorpus(repoRoot, dir = CORPUS_DIR) {
     return files;
 }
 
-/**
- * Grade the corpus against the rules. Returns findings; the caller decides what they cost.
- *
- * Every finding names the file, the case and the repair. A red that does not say what to do about it
- * costs a reader the same time twice.
- */
 export function grade(rules, corpus) {
     const { matchable, exempt } = partition(rules);
     const byId = new Map(matchable.map((r) => [r.id, r]));
@@ -306,9 +179,6 @@ export function grade(rules, corpus) {
         covered.add(rule.id);
         for (const c of doc.cases) {
             cases += 1;
-            // The declared path is checked against the DERIVED one before the case is graded. A case
-            // that mislabels its own branch is a case a reader will draw the wrong conclusion from,
-            // and the label is the half no green would otherwise test.
             const derived = matcherPath(rule.kind, c.tool);
             byPath.set(derived, (byPath.get(derived) ?? 0) + 1);
             if (c.path !== derived) {
@@ -321,7 +191,6 @@ export function grade(rules, corpus) {
                 });
                 continue;
             }
-            // The one call that matters, and it is the compiler's own. Never re-implemented here.
             const actual = matchesRule(rule, c.tool, c.input);
             if (actual === c.expect) continue;
             findings.push({
@@ -363,8 +232,7 @@ function usage() {
 
 export function run(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
     const say = (line = "") => stdout.write(`${line}\n`);
-    // Before every other argument decision, so asking for help cannot be outranked by a complaint
-    // about the rest of the command line — the contract `./portulan.mjs` states.
+    // First, so `--help` is answered whatever else the command line holds.
     if (argv.includes("--help") || argv.includes("-h")) {
         say(usage());
         return 0;
@@ -381,9 +249,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             } else if (argv[i] === "--pack-root") {
                 const root = argv[i + 1];
                 i += 1;
-                // A single leading `-` is refused too, the way `compile` and `doctor` refuse it:
-                // `--pack-root -h` would otherwise be consumed as a path and fail later as an
-                // unreadable one. A directory genuinely named `-name` is `./-name`.
+                // A value starting with `-` is a flag, not a path; a directory so named is `./-name`.
                 if (root === undefined || root.startsWith("-")) throw new CouldNotRun("--pack-root needs a directory");
                 let stat = null;
                 try {
@@ -400,16 +266,11 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         const corpus = readCorpus(workspaceRoot);
         const { findings, cases, matchable, exempt, byPath } = grade(rules, corpus);
 
-        // An unresolved pack is a declaration the workspace believes it composed, so its fragments are
-        // absent from the denominator and this run's coverage claim is narrower than it looks. Printed
-        // before the verdict, for the reason `compile` prints it there.
         for (const u of unresolved) say(`pack    ${u.name} UNRESOLVED — ${u.why}; its gate fragments are not in this census`);
 
         say(`goldens: ${cases} case(s) over ${matchable.length} matchable rule(s) in ${corpus.length} fixture file(s)`);
-        // Per matcher branch, and printed even at zero. A corpus can carry 200 cases and exercise one
-        // branch of three; the total says nothing about that and this line says it plainly.
         say(`goldens: by matcher path — ${PATHS.map((p) => `${p} ${byPath.get(p) ?? 0}`).join(" · ")}`);
-        // The exemption, named on every run — see `partition`.
+        // Printed on every run, so the exemption cannot become a quiet way out of fixtures.
         if (exempt.length) {
             say(`goldens: ${exempt.length} rule(s) declare no matchable action and are exempt from fixtures:`);
             for (const e of exempt) say(`           ${e.id} (${e.tier}, ${e.why})`);
@@ -421,8 +282,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             return 1;
         }
         say("GREEN — every matchable gate carries fixtures, and every case answers as recorded");
-        // Said out loud rather than implied by the green, because the limit is the half a reader
-        // otherwise supplies wrongly. See the header.
         say("goldens: this is a PRESENCE floor — whether a corpus is a real attack is a reviewer's judgement, not this rail's");
         return 0;
     } catch (error) {
@@ -430,28 +289,13 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             stderr.write(`goldens: ${error.message}\n`);
             return 2;
         }
-        // **An unexpected throw is COULD-NOT-RUN, never a red**, and this arm exists because the first
-        // draft rethrew: a `ReferenceError` from a typo crashed the process, node exited 1, and
-        // `../.portulan/verify/goldens.sh` faithfully translated that into "RED — verify recipe failed"
-        // about a corpus nothing had finished grading. A crash that reads as a verdict is the shape
-        // this repository has now met in three tools — it is why `pack-version.sh` and
-        // `eval-bundle.sh` grew `[ -f ]` preconditions. The stack rides along, because a
-        // could-not-run nobody can debug is only half an answer.
+        // An unexpected throw exits 2, never 1: a crash is not a verdict on the corpus.
         stderr.write(`goldens: could not finish grading — ${error?.stack ?? error}\n`);
         return 2;
     }
 }
 
-// The entry guard, in the ONE form `./rule-carriers.mjs` designates after this repository got it wrong
-// twice. `file://${argv[1]}` is NOT that form: `import.meta.url` percent-encodes, this working copy
-// lives under a path with spaces, and the comparison fails — so the tool exits 0 having run nothing.
-// **A green that is the tool never starting.** This file shipped that spelling for exactly one
-// measurement: the first run of `node cli/goldens.mjs` printed nothing and exited 0, on a corpus that
-// did not exist yet and against a policy nothing had read. The third time this repository has met it,
-// and the reason the designated form is copied rather than re-derived.
-//
-// The realpath fallback covers the symlink case an npm `bin` produces, in a `try` because a missing
-// path must answer no rather than throw.
+// URLs on both sides, since `import.meta.url` percent-encodes; the realpath covers a symlinked `bin`.
 function isMain() {
     const invoked = process.argv[1];
     if (!invoked) return false;
@@ -463,7 +307,5 @@ function isMain() {
     }
 }
 
-// `process.exitCode` rather than `process.exit`, which `./control-chars.mjs` settled for this
-// repository: exiting outright can truncate a pipe that has not drained — and a truncated line IS exit
-// 0 with no output, the precise shape of the false green the guard above was fixed for.
+// `exitCode`, not `exit()`: exiting outright can cut off output a pipe has not drained.
 if (isMain()) process.exitCode = run(process.argv.slice(2));