@sleepy_panda_srl/portulan 0.1.1 → 0.1.3

package/cli/compile.mjs

@@ -45,6 +45,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 // Host plugin-cache discovery (#123). The record reader, the config directory and the version refusal
 // all live there, once — see that file's pack-root section for why this half arrived separately.
 import { AUTO, discoverPackRoots, namedWithAuto, resolutionRoots } from "./discover.mjs";
+import { isInside } from "./inside.mjs";
 
 /** Raised when `compile` cannot run, or cannot compile honestly. Always exit 2, never 1. */
 export class CompileError extends Error {
@@ -69,7 +70,11 @@ export class CompileError extends Error {
 // Workspace Definition. A fresh reviewer at milestone 6 session 1 sight-read this as a carrier left
 // stale by the 2.5 → 2.6 bump and had to measure to clear it. It is correctly untouched by any
 // Workspace Definition bump; renamed to say so, because the next reader may not measure.
-const KNOWN_GATE_POLICY_SPECS = new Set(["2.1", "2.2"]);
+// Exported so a test can assert MEMBERSHIP against it rather than restate the literal. The
+// scaffold `new gate-policy` emits must declare a spec THIS set contains (#329), and a rail
+// spelling `"2.2"` on its own side would pass while the two drifted apart — which is the
+// shape #329 was.
+export const KNOWN_GATE_POLICY_SPECS = new Set(["2.1", "2.2"]);
 
 const TIERS = new Set(["auto", "propose", "gated", "prohibited"]);
 
@@ -80,8 +85,12 @@ const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const FILE_PATH = /^[^#?:/]([^#?:]*[^#?:/])?$/;
 
 /** The tools that can write a path, and the tools that can read one. */
-const WRITE_TOOLS = ["Edit", "Write", "NotebookEdit"];
-const READ_TOOLS = ["Read"];
+// Exported since 2026-08-24 so `./goldens.mjs` can DERIVE which branch of `matchesRule` a fixture
+// exercises instead of a corpus author declaring it from memory. A hand-declared path would be a
+// second carrier of what these two tables already decide, and the fixture format asks for the path on
+// every case — which is exactly the volume at which a hand-copied answer goes wrong.
+export const WRITE_TOOLS = ["Edit", "Write", "NotebookEdit"];
+export const READ_TOOLS = ["Read"];
 
 // ===========================================================================================
 // 1. Parse: policy -> validated, normalised rules. NO backend opinion lives here.
@@ -473,7 +482,10 @@ function stripHeredocs(command) {
 }
 
 /** A shell command split into words, with unquoted operators kept as words of their own. */
-function shellWords(command) {
+// Exported since 2026-08-24 so the suite can hold `REDIRECTION_TARGET` to THIS definition of a word
+// rather than to a reviewer's patience. Three review findings in a row were the same class — the
+// target reader narrower than a shell word — and each was fixed at the instance quoted.
+export function shellWords(command) {
     const words = [];
     let text = "";
     let open = false; // a word has begun — so an empty `""` argument survives as a word
@@ -534,11 +546,74 @@ function shellWords(command) {
             // A backslash-newline is a line continuation: both characters vanish, and the word
             // continues on the next line. Appending the newline instead would have glued it into the
             // middle of a path, which no target matches.
-            // `\r\n` is consumed as a PAIR. Skipping one character left the `\n` behind, and a
-            // newline is an operator here, so a CRLF continuation flushed the word instead of
-            // continuing it: `cp /tmp/x \\<CRLF>docs/vision.md` stepped aside where the LF spelling
-            // answers `deny` — the constitution, reachable by editing the file on Windows. Measured
-            // both ways, 2026-07-28. Found by Copilot review on #60.
+            // `\r\n` is consumed as a PAIR, and **the reachability that argued for it has been
+            // retired.** What stood here from 2026-07-28 until 2026-08-25 was: skipping one character
+            // left the `\n` behind, a newline is an operator here, so `cp /tmp/x \\<CRLF>docs/vision.md`
+            // stepped aside where the LF spelling answers `deny` — "the constitution, reachable by
+            // editing the file on Windows". The first half is a true statement about THIS reader. The
+            // second is a claim about a shell, and it did not reproduce on any shell measured.
+            //
+            // **Measured 2026-08-25 on five shells, with a neutral target path — never the
+            // constitution.** `bash 3.2.57(1)` (arm64-apple-darwin25, the maintainer's machine),
+            // `bash 5.2.15(1)` (aarch64-unknown-linux-gnu) and `bash 5.2.37(1)` (x86_64-pc-linux-gnu),
+            // both in containers; `zsh 5.9`; and **the measured host's `/bin/sh`**, which on that macOS host
+            // resolves to bash 3.2.57 in POSIX mode — elsewhere `/bin/sh` is commonly `dash` or `busybox`
+            // and NEITHER was measured, so this row is a fifth reading of bash and zsh rather than a claim
+            // about `/bin/sh` as such.
+            // **All five agree, and none of them joins the pair:** the backslash escapes the `\r`, the
+            // newline then ends the command, and the fragment after it is run as its own command. The
+            // LF spelling in the same harness DID join and DID write the target, so the harness fires
+            // rather than reporting nothing everywhere. For the `cp`-shaped payload the retired
+            // sentence names, the target is left byte-for-byte unchanged on all five — so this branch
+            // is a **false red** there, fail-closed, and worth one prompt.
+            //
+            // **It is not a false red everywhere, which is why the branch is still here.** A shell
+            // applies a redirection BEFORE it looks the command up, so a clobbering `>` or `1>` on the
+            // fragment left by the split still fires and truncates its target to zero bytes — measured
+            // on all three bash builds. `>>` appends and does not. The carriers of that split verdict
+            // are `./fuzz-shell.mjs`'s `crlf-continuation-in-the-payload` EXPECT cells and
+            // `./compile.test.mjs`'s paired CRLF assertions. **Not `../.portulan/gate-map.md`**, which
+            // an earlier draft of this sentence named and which carries no CRLF entry at all — a
+            // citation to a record that does not exist, in the comment repairing exactly that.
+            //
+            // **Removing the branch is fail-OPEN on a gate matcher, so it is the maintainer's and not
+            // this comment's.** Deleting BOTH carriers in a scratch clone and running the recipes moves
+            // **four** surfaces, which is the count an accepting change has to carry:
+            //   1. `fuzz-shell` — the `crlf-continuation-in-the-payload|write-named` EXPECT cell, whose
+            //      recorded divergence CLOSES. Good news, and a red until the record absorbs it.
+            //   2. `goldens` — the `a-CRLF-continuation` fixture in
+            //      `../evals/goldens/gates/edit-the-constitution.json` regresses.
+            //   3. `./compile.test.mjs` — **two** direct assertions fail, *a CRLF continuation before
+            //      the path* and *a CRLF continuation after `>`*.
+            //   4. `mutants` — exit **2, could-not-run**, downstream of 2: a census over a red corpus
+            //      measures nothing, so it refuses until the fixture is repaired.
+            // **An earlier draft of this comment said "those two and nothing else" and had counted only
+            // the first two** — an exhaustive claim that had not run the suite it was exhaustive about,
+            // in the comment repairing an unmeasured claim. Reported by Copilot, round 1 on #342.
+            // What does NOT move, **and the reason an earlier draft gave for it was false.** That draft
+            // said "the redirection is recognised off the raw segment text rather than off a joined
+            // word". There is no raw-text path: `shellWrites` iterates `shellSegments`, which is built
+            // from `shellWords`. The real reason is narrower and is a property of WHERE the pair sits.
+            // With the branch gone the newline splits, and for the fuzzer's shape — pair after the head,
+            // `echo \<CRLF>ok > docs/vision.md` — the `> docs/vision.md` lands in a LATER segment whose
+            // `redirects` still name the target, so that cell stays `true`. Put the pair AFTER the `>`
+            // and the opposite happens: the operator takes the escaped `\r` as its target and the path
+            // becomes an ordinary word in the next segment — which is precisely why surface 3's second
+            // assertion fails. **So the true positive survives for this production and NOT for every
+            // redirect spelling**, and generalising it was the overclaim. Reported by Copilot, rounds 2
+            // and 3 on #342. A real LF continuation is untouched either way. Asked at
+            // `../.portulan/proposals/0031-a-continuation-no-shell-joins.md`; until that is ruled, the
+            // branch stays and this comment states what was measured rather than what was argued.
+            //
+            // **The honest limit, and it is the platform the retired sentence named: no Windows-side
+            // bash was measured** — not git-bash, MSYS2, Cygwin (whose `igncr` exists precisely for
+            // this) or WSL. Nor was any bash 4.x. The standing rail is `./fuzz-shell.ground.test.mjs`,
+            // which runs this production under **whatever bash the host running the `tests` recipe
+            // has** and reds if that bash joins the pair — so a joining shell is caught wherever the
+            // recipe runs, CI included, and is caught nowhere the recipe does not run. That boundary is
+            // stated because it is the whole of the enforcement: the container measurements above are a
+            // record, not a recipe, since a recipe that pulled an image would be a network call in CI.
+            // Found by Copilot review on #60; the claim retired by measurement 2026-08-25.
             if (command[i + 1] === "\r" && command[i + 2] === "\n") {
                 i += 2;
                 continue;
@@ -647,6 +722,85 @@ function normalisePath(p) {
     return (absolute ? "/" : "") + out.join("/");
 }
 
+/**
+ * Does this target match NO path a host actually submits? `true` means none can — the rule matches
+ * nothing, whatever it says.
+ *
+ * _(That first line asked the inverse question until 2026-09-09 — "can any path fall under this target?
+ * `false` means none can" — so it described a return value the function does not have. Eight
+ * fresh-context gradings read past it, four of them grading this docblock's accuracy: every one checked
+ * whether the predicate was right and none checked whether its opening sentence matched its own
+ * `return`. Found by Copilot on #408.)_
+ *
+ * **The predicate is a comparison between two forms of the target, and that is what makes it the
+ * class rather than a list.** `matchesPath` compares a *tail* — it strips a leading `./` and any
+ * leading `/` and then asks whether the candidate ends with, or contains, what is left. A host is
+ * **expected** to hand over a normalised absolute path — no `.` segment, no empty segment, no
+ * backslash — and that is an assumption rather than something measured here, argued below. So the
+ * target can match only if its comparison form is already normalised. Where the two forms differ, the comparison is against
+ * a spelling no candidate can carry, and the rule matches nothing whatever it says.
+ *
+ * That covers three families at once, which is why it is written as a comparison and not as a list of
+ * spellings a reader would have to keep in step:
+ *
+ * - **The target that reduces to nothing**, which compiles to `Edit(./)`, `Edit(./.)`, or — for one
+ *   spelling — the real subtree glob `Edit(././**)`.
+ * - **The target with an interior `.` or empty segment**, each compiling to a named surface that reads
+ *   like a real gate on a plausible path, and matches nothing.
+ * - **The target carrying a backslash**, and this one is why the argument above needs its second half
+ *   stated: `matchesPath` normalises the **candidate**'s backslashes to `/` and never the target's, so
+ *   a backslash in a target is compared against a character no candidate can still contain, **on every
+ *   platform**. Unlike the first two families this one has no conditional reading at all.
+ *
+ * **The host assumption, named because it is one.** *No `.` segment, no empty segment, no backslash*
+ * describes what a host is expected to send, and this repository does not control that and has not
+ * measured an unnormalised `file_path` arriving. The refusal does not rest on it: a rule matching only
+ * `/repo/x/.` gates nothing anybody meant to gate whichever way the assumption falls.
+ *
+ * **Four cuts, three of them incomplete, always in the same direction — and that arc is why this is a
+ * comparison rather than a list.** Cut 1 lifted `matchesPath`'s own strip and caught two of the first
+ * family's five. Cut 2 asked whether the target normalised to **empty**, catching that family alone
+ * while three carriers of its prose claimed the class. Cut 3 added the interior family. Cut 4 added the
+ * backslashes. Every miss was found by putting neighbouring spellings through the function at a
+ * checkpoint, never by re-reading the sentence. A predicate defined by the instances it was written for
+ * is ../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md's shape, and **this
+ * docblock is the one carrier of that arc** — the records cite it rather than recounting it.
+ *
+ * The thirteen spellings and the controls that must stay matchable are enumerated **and measured** in
+ * `./compile.test.mjs`'s `NEVER` and `CONTROLS` — the only carrier that measures them. Four records
+ * enumerate them for a reader; this docblock cites the suite rather than joining them.
+ *
+ * **`matchesPath` is left byte-identical on purpose**, and that is a decision rather than an omission:
+ * its answers are asserted by twelve `documented-hole` cases in ../evals/goldens/gates/ and by
+ * `mutants` operators anchored on its text, so moving its strip would move two census anchors and exit
+ * the census 2 — could-not-run wearing a pass's clothes. This function re-spells that strip rather than
+ * importing it, which is one carrier more than ideal and is pinned by a suite case comparing the two on
+ * every target below.
+ *
+ * The subtree marker is **meaning, not spelling**: exactly one trailing `/` says *the subtree* and is
+ * removed before the comparison, which is why `docs/` is a real target and `docs//` is not.
+ *
+ * What this does NOT answer is what `./` should MEAN as a policy target. That is
+ * https://github.com/sleepy-panda-srl/portulan/issues/337's reserved question, and this predicate
+ * answers only whether a target can *never* match.
+ */
+export function neverMatches(target) {
+    const clean = String(target ?? "").replace(/^\.\//, "").replace(/^\/+/, "");
+    // `clean === "/"` is UNREACHABLE, and so is the `body === ""` arm below — the strip above removes
+    // every leading slash, so `"/"` arrives here as `""`. Measured, not assumed. They are kept anyway
+    // because `matchesPath` carries the identical pair one screen down and this predicate is meant to be
+    // read beside it: deleting them here would make two functions that answer the same question about
+    // the same string look different, to save two comparisons nobody runs. Copilot raised it on #408;
+    // the answer is that the redundancy is deliberate and now says so, which is the half it was missing.
+    if (clean === "" || clean === "/") return true;
+    const body = clean.endsWith("/") ? clean.slice(0, -1) : clean;
+    // The backslash arm is separate because it is about the CANDIDATE's normalisation rather than the
+    // target's: `matchesPath` rewrites `\\` to `/` in what the host hands over, so a target keeping one
+    // is compared against a character the comparison has already removed from every candidate.
+    if (body.includes("\\")) return true;
+    return body === "" || normalisePath(body) !== body;
+}
+
 /**
  * The directories a target lives under, as exact paths: `a/b/c.md` -> `a`, `a/b`.
  *
@@ -717,6 +871,8 @@ function commandSegments(raw) {
     const out = [];
     let start = 0;
     let quote = null;
+    // The index of the character a backslash most recently turned into data. See the `\\` branch.
+    let escaped = -1;
     for (let i = 0; i < command.length; i += 1) {
         const c = command[i];
         if (quote) {
@@ -746,7 +902,28 @@ function commandSegments(raw) {
             // of one — so this is fixed for the reason the session kept re-learning rather than for a
             // failing case: one carrier corrected and its sibling left is how the last three defects
             // on this branch happened.
+            // **The pair's two carriers are this line and `shellWords`, and the measurement retiring
+            // the reachability claim is written up there once.** No shell measured joins the pair, so
+            // consuming it here is unfaithful to a shell in the same direction — **but this carrier
+            // records no false red of its own, and an earlier draft of this comment said it did.** On
+            // the shell path its `crlf-continuation-in-the-payload|shell` cell answers `false`, the
+            // correct negative: nothing gated runs there. On the write path it is an UNWRAPPER feeding
+            // `shellWrites`, reached through a short-circuiting `||` after the un-peeled spellings, so
+            // the recorded false red — `write-named` — is produced by `shellWords` and not here. **The
+            // reason to keep the two readers in step is synchronisation, not a shared verdict**: a
+            // carrier corrected while its sibling stands is how the last several defects on this line
+            // happened. Reported by Copilot, round 2 on #342. That is why
+            // `../.portulan/proposals/0031-a-continuation-no-shell-joins.md` names both carriers rather
+            // than the one whose comment argued for it. Reported by Copilot, round 1 on #342.
             i += command[i + 1] === "\r" && command[i + 2] === "\n" ? 2 : 1;
+            // **Remember WHICH character this backslash turned into data.** The redirection-operator
+            // check below reads one raw neighbour, and a raw read cannot tell `>` the operator from
+            // `\>` the literal. Without this, `echo \>| git push --force origin main` — a REAL pipe,
+            // measured in bash delivering bytes downstream — stopped splitting at the `|`, and the
+            // force-push after it went invisible to every matcher. `\>&` did the same across a real
+            // background separator. Both were caught at HEAD and were narrowed by the #71 fix itself;
+            // found by the pre-commit checkpoint, which attacked the change rather than reading it.
+            escaped = i;
             continue;
         }
         // `#` is NOT treated as starting a comment, and that is a decision rather than an oversight.
@@ -763,13 +940,91 @@ function commandSegments(raw) {
         //
         // Both spellings are asserted in the suite so this stays a choice rather than drift.
         // Reported by Copilot review on #60 and declined on those grounds.
+        // An `&` or `|` bound into a redirection OPERATOR is not a separator, and splitting there is
+        // what made the strip below unreachable for three of the four spellings. `2>&1 git push
+        // --force …` split at the `&` into `2>` and `1 git push --force …`, whose head is `1` — the
+        // redirection was already in pieces by the time anything could strip it, and `>| f git push
+        // --force …` broke the same way at the `|`. Both operators are closed forms: `&` preceded by
+        // `>`/`<` or followed by `>`, and `|` preceded by `>`. `a && b`, `a & b` and `a | b` are
+        // untouched — none of them puts a redirection character next to the separator.
+        // `i - 1 !== escaped` on both arms: a `>` or `<` that a backslash turned into DATA is not an
+        // operator, and treating it as one un-splits a real separator. The `command[i + 1]` arm needs
+        // no such guard — an escaped character is always preceded by its own backslash, so the
+        // character after `&` can never be an escaped `>`.
+        const opBefore = i - 1 !== escaped && (command[i - 1] === ">" || command[i - 1] === "<");
+        if (c === "&" && (opBefore || command[i + 1] === ">")) continue;
+        if (c === "|" && i - 1 !== escaped && command[i - 1] === ">") continue;
         if (";|&()\n\r".includes(c)) {
             out.push(command.slice(start, i));
             start = i + 1;
         }
     }
     out.push(command.slice(start));
-    return out.map((s) => s.trim()).filter(Boolean);
+    return out.map((s) => stripLeadingRedirections(s.trim())).filter(Boolean);
+}
+
+/**
+ * A redirection sitting where the command goes: an optional file descriptor, one of the operators
+ * below, and a word.
+ *
+ * **This is the one leader that is stripped, and the asymmetry is the point** (#71). The other
+ * leaders `commandSegments` leaves alone — `env`, `sudo`, `FOO=bar`, `then`, `do`, a brace group —
+ * are refused for a reason that does not apply here: a table of command prefixes has no natural edge
+ * (`nice`, `time`, `nohup`, `timeout`, `command`, `stdbuf`, `doas`), and one missing entry buys
+ * exactly the false confidence a hole list exists to deny. A redirection's grammar is CLOSED, so it
+ * can be stripped completely with an edge a reader can check. #60 left it open deliberately, because
+ * closing it would have been a matcher change on the same commit that stopped hole 2 overclaiming.
+ *
+ * **Do not extend this to a named table of command prefixes.** That is the change the paragraph
+ * above refuses, and the two look similar enough to be proposed together.
+ *
+ * Applied repeatedly, because redirections stack: `> /tmp/out 2>&1 git push --force …` carries two.
+ */
+/**
+ * The redirection TARGET, as one word.
+ *
+ * `[^\s]+` was wrong and shipped for exactly one review round: a redirection target may contain
+ * spaces when it is quoted or escaped, and `> "foo bar" git push --force …` then stripped only
+ * `> "foo`, leaving `bar" git push --force …` — head `bar"`, no gate, and the segment text corrupted
+ * into the bargain. Measured escaping on five spellings (both quote styles, an escaped space, `2>` and
+ * `>|`), and bash confirmed to run the command after each. **A fix that closes a hole by a width its
+ * own test never probed**, found by Copilot round 1 — which named the double-quoted case; the other
+ * four are its siblings and are closed in the same stroke rather than left for the next round.
+ *
+ * A word is therefore a run of quoted spans, backslash-escaped characters, and ordinary non-space
+ * characters — the same three things `shellWords` recognises, kept to a regex here because this reader
+ * needs the target's EXTENT and never its value.
+ *
+ * **Inside a double-quoted span a backslash escapes the next character, and inside a single-quoted one
+ * it does not.** POSIX gives `'…'` no escapes at all, so honouring one there would invent a hole —
+ * which is the same asymmetry `commandSegments`'s own quote loop already carries, and the same one
+ * `shellWords` carries at its quoted-run branch.
+ *
+ * **This is the THIRD review finding of one class, and the class is what the suite now pins.** Round 1
+ * found `[^\s]+` too narrow for a quoted target; round 3 found `"[^"]*"` too narrow for an escaped
+ * quote *inside* one — `> "foo \"bar baz\"" git push --force …`, measured escaping while bash was
+ * measured creating the file and running the command. Both times the fix landed at the spelling that
+ * was quoted. So `compile.test.mjs` now asserts this pattern against `shellWords` itself: every
+ * spelling that reader calls ONE word must be consumed whole here. A fourth sibling cannot be found by
+ * a reviewer first.
+ *
+ * Linear rather than backtracking-prone despite the alternation: the pattern is anchored, the trailing
+ * `\s*` matches empty, and the `+` is greedy over a match that always succeeds once an operator has
+ * been seen — so there is no failure to backtrack into. Probed to 200KB.
+ */
+const REDIRECTION_TARGET = String.raw`(?:"(?:\\[\s\S]|[^"\\])*"|'[^']*'|\\[\s\S]|[^\s])+`;
+
+const LEADING_REDIRECTION = new RegExp(String.raw`^\d*(?:&>>|&>|>>|>&|>\||<&|<>|<|>)\s*${REDIRECTION_TARGET}\s*`);
+
+function stripLeadingRedirections(segment) {
+    let text = segment;
+    for (;;) {
+        const shorter = text.replace(LEADING_REDIRECTION, "");
+        // A segment that is ONLY a redirection strips to the empty string and is dropped by the
+        // caller's `filter(Boolean)`, which is correct: a redirection is not a command.
+        if (shorter === text) return text;
+        text = shorter;
+    }
 }
 
 /**
@@ -872,8 +1127,32 @@ export function matchesRule(rule, tool, input = {}) {
         // wrapper and made `bash -c "bash -c 'git push origin HEAD'"` match, contradicting hole 1's
         // documented and asserted limit. The suite caught it, which is what that counterexample test
         // is for. Reading the raw command in both branches keeps the budget at exactly one unwrap.
-        const segments = commandSegments(input.command);
-        return spellings(input.command).some(hit) || segments.some((seg) => spellings(seg).some(hit));
+        //
+        // **A spelling is SEGMENTED as well as tested whole, and that half was missing until
+        // 2026-08-25.** The two calls above unwrap the raw command and unwrap each of its segments,
+        // which closes a wrapper before a separator — `ls && bash -c "git push --force origin main"`
+        // — and leaves a separator inside a wrapper wide open: `bash -c "ls; git push --force origin
+        // main"` answered **false**, and so did every other Gated shell action behind one wrapper and
+        // one separator. Bash runs it; the gate did not see it.
+        //
+        // **The write branch below never had this gap, and the reason is why the fix is shaped like
+        // this.** Its `writes` callback is `shellWrites`, which segments AGAIN internally with
+        // `shellSegments` — so the write half got a third segmentation for free while the shell half,
+        // whose `hit` is a plain prefix test, got none. One fix landing in one carrier and not its
+        // sibling, between two branches of one function, for the second time
+        // (`proposals/0020`). Found by ./fuzz-shell.mjs, which
+        // generates the grammar rather than reading it.
+        //
+        // `reach` is used on BOTH arms deliberately: without it on the second,
+        // `ls && bash -c "x; git push --force …"` — a separator outside AND inside — still escaped.
+        // Fixing only the spelling that was quoted is the class this repository keeps meeting.
+        //
+        // **The unwrap budget is still exactly one level**, which is hole 1's documented and asserted
+        // limit. `spellings` is called once on each path here and `commandSegments` peels nothing, so
+        // `bash -c "sh -c 'git push origin HEAD'"` stays false — asserted, because an earlier draft of
+        // the segment composition did peel twice and the suite is what caught it.
+        const reach = (s) => hit(s) || commandSegments(s).some(hit);
+        return spellings(input.command).some(reach) || commandSegments(input.command).some((seg) => spellings(seg).some(reach));
     }
     if (typeof action.write === "string") {
         if (WRITE_TOOLS.includes(tool)) return matchesPath(input.file_path ?? input.notebook_path, action.write);
@@ -969,6 +1248,16 @@ const HOST_TIER_NOT_A_GATE = {
     propose: "tier `propose` is enforced by the platform floor — pull requests, required checks, review — not by a tool-level permission rule on this machine",
 };
 
+/**
+ * The compiled-hook runners, in the order `claudeCode` spells them: the PreToolUse gate, then the Stop
+ * gate. **This is their one carrier.** They are invoked by generated host configuration rather than
+ * imported by anything, so no import graph can find them and every other roster that needs to know
+ * which `cli/` modules are runners has to ask here — `./payload.mjs` does. A third runner added below
+ * without a name added here would classify as unreachable in that rail, which is the direction that
+ * fails loudly rather than the one that ships something unnoticed.
+ */
+export const HOOK_RUNNERS = ["gate.mjs", "stop-gate.mjs"];
+
 /**
  * Translate the policy into a Claude Code settings object.
  *
@@ -1033,8 +1322,8 @@ export function claudeCode(parsed, options = {}) {
         pinned.push({ file, abs });
         return `"${abs}"`;
     };
-    const runner = options.runner ?? spell("gate.mjs");
-    const stopRunner = options.stopRunner ?? spell("stop-gate.mjs");
+    const runner = options.runner ?? spell(HOOK_RUNNERS[0]);
+    const stopRunner = options.stopRunner ?? spell(HOOK_RUNNERS[1]);
 
     const compiled = [];
     const refused = [];
@@ -1042,6 +1331,8 @@ export function claudeCode(parsed, options = {}) {
     const ask = [];
     const matchers = new Set();
     const shellWriteGates = [];
+    // Write gates whose single emitted permission pattern is `Edit(path)` — see the note they produce.
+    const editCoveredGates = [];
 
     for (const rule of parsed.rules) {
         if (!HOST_GATE_TIERS.has(rule.tier)) {
@@ -1055,6 +1346,60 @@ export function claudeCode(parsed, options = {}) {
             refused.push({ id: rule.id, tier: rule.tier, why: rule.target });
             continue;
         }
+        // ---- a path target no path can match, refused HERE and not at `parse`
+        //
+        // **Hole 8 of ../.portulan/gate-map.md, closed at the tier that asks the question.** A
+        // `gated` or `prohibited` rule whose path target can never match — see `neverMatches` for the
+        // three families, of which *reduces to nothing* is only the first — compiles to a named
+        // permission surface (`Edit(./)`, `Edit(./.)`, `Edit(././**)`, `Edit(./docs/./vision.md)`,
+        // `Edit(./docs\\vision.md)`) while `matchesRule` answers `false` for every path a host submits. The compiler then reports the rule COMPILED, and
+        // `doctor` counts it as covered. That is a hollow gate that reads from outside exactly like a
+        // whole one: hole 3's failure mode reached by a different road.
+        //
+        // **Why a throw and not a `refused` row.** `refused` is the accounting for a rule a backend
+        // legitimately declines — an `auto` tier, a `none` kind — and it writes the artifact without
+        // the rule and exits 0. Filing this there would leave `doctor` reporting a gate the policy
+        // declares and nothing enforces as ordinary non-coverage, which is precisely the laundering
+        // `parse`'s own target refusals (absolute, `..`, whitespace) already decline to do. A policy
+        // that cannot be enforced as written is malformed, and malformed is could-not-run.
+        //
+        // **Why here and not at `parse`.** That stage holds no tier partition, by a decision recorded
+        // in its own docblock: *"A partition that is one backend's opinion must live in that backend,
+        // or the second one is structurally incapable of disagreeing."* A session once put the
+        // `auto`/`propose` refusals there and the floor backend then needed the rules it had thrown
+        // away. This is that same shape — the hazard exists only for the tiers THIS backend enforces —
+        // so it lives with `HOST_GATE_TIERS` above it, and the two `auto` rules in
+        // ../.portulan/gates.json — `edit-on-a-working-branch` (`write: "./"`) and
+        // `read-anything-in-the-repository` (`read: "./"`), one of each path kind — keep their spelling
+        // and are refused one line earlier, for their tier, exactly as before.
+        //
+        // **One site, and the predicate exported rather than inlined.** The floor backend compiles no
+        // path target at all (see `floorRefusal`), so there is no second site to sweep today and
+        // saying "the same treatment there" would be a claim about code that does not exist.
+        // `neverMatches` is exported for the backend that does compile one, and for the tests.
+        //
+        // **What this does NOT reach, said here rather than left to be discovered.** ./gate.mjs reads
+        // the policy through `parse`, which this change does not touch, so a workspace that has
+        // committed such a rule still loads it at the hook, `matchesRule` answers `false`, and the
+        // hook steps aside because nothing matched. The rule is refused at COMPILE time — which is
+        // when the artifact that gates the host is written — and the residue is recorded in hole 8.
+        //
+        // Found by the milestone-8 gate corpus on its first run (#336) and put as three options in
+        // #337; this is the third, the narrowest, and it deliberately leaves open what `./` should
+        // MEAN as a policy target.
+        if ((rule.kind === "write" || rule.kind === "read") && neverMatches(rule.target)) {
+            throw new CompileError(
+                `rule \`${rule.id}\` is ${rule.tier} and its ${rule.kind} target ${JSON.stringify(rule.target)} matches no path a host ` +
+                    `can submit: the matcher compares a tail, and this target's comparison form is one no candidate can carry. ` +
+                    `This backend would emit ${pattern(rule.kind === "write" ? "Edit" : READ_TOOLS[0], rule.target)} ` +
+                    `and report the rule compiled, while the runtime matcher answered false for every input: a gate that reads as whole ` +
+                    `from outside and enforces nothing. Name the path the rule protects in its normalised spelling — no ` +
+                    `\`.\` or empty segment, no backslash — or drop the rule; and where this ` +
+                    `rule came from a pack, it is the pack that carries it, not the workspace composing it. ` +
+                    `(A never-matching target is harmless at \`auto\`, which this backend refuses one step earlier; it is a hollow gate only ` +
+                    `at the tiers that enforce. See .portulan/gate-map.md, honest holes, entry 8.)`,
+            );
+        }
         const into = rule.tier === "prohibited" ? deny : ask;
         const emitted = []; // permission patterns — the layer that cannot fail open
         const hookOnly = []; // coverage the permission DSL cannot express, carried by the hook alone
@@ -1062,11 +1407,36 @@ export function claudeCode(parsed, options = {}) {
             emitted.push(`Bash(${rule.target}:*)`);
             matchers.add("Bash");
         } else {
-            for (const tool of rule.kind === "write" ? WRITE_TOOLS : READ_TOOLS) {
-                emitted.push(pattern(tool, rule.target));
-                matchers.add(tool);
-            }
+            // **The PERMISSION pattern narrows to `Edit`; the HOOK matchers keep all three.** These two
+            // lines used to be one loop, and that emitted `Write(path)` and `NotebookEdit(path)` beside
+            // `Edit(path)` — patterns the host **discards**. Measured on Claude Code 2.1.240, printed on
+            // every start of this repository:
+            //
+            //   Permission deny rule (.claude/settings.json): Write(./docs/vision.md) is not matched by
+            //   file permission checks — only Edit(path) rules are. Use Edit(./docs/vision.md) instead
+            //   (Edit rules cover all file-editing tools).
+            //
+            // and the same for the `ask` tier, so this was never a `deny`-only defect. The gate held
+            // throughout — `Edit(path)` is matched for every file-editing tool — so what was wrong was
+            // the compiler's **accounting**: three rules reported compiled where one enforces, plus a
+            // permanent warning, which is `../.portulan/memory/a-stated-enforcer-must-be-the-real-one.md`.
+            //
+            // **`matchers` is a different consumer and must not narrow with it.** It drives the
+            // `PreToolUse` hook, where all three tool names genuinely arrive and `matchesRule` above
+            // answers for each; narrowing it would open a real hole where today there is none. That is
+            // why the repair is not narrowing `WRITE_TOOLS` — two consumers of one constant, one of
+            // which changes. A suite case pins the matcher set for exactly this reason.
+            //
+            // **The dropped patterns are NOT `hookOnly`.** Measured with the pattern alone in `deny` and
+            // `Write` allowed: the host refused the write. So their coverage is carried by the
+            // permission layer, not by the hook, and filing them under a channel documented as *carried
+            // by the hook alone* would be a false claim in the weakening direction. The fact goes on
+            // `notes` instead, where it names its host version.
+            const permissionTools = rule.kind === "write" ? ["Edit"] : READ_TOOLS;
+            for (const tool of permissionTools) emitted.push(pattern(tool, rule.target));
+            for (const tool of rule.kind === "write" ? WRITE_TOOLS : READ_TOOLS) matchers.add(tool);
             if (rule.kind === "write") {
+                editCoveredGates.push(rule.id);
                 // The hook is wired for Bash so that a shell spelling of this write reaches
                 // `matchesRule`, which now answers for it. **This line is the load-bearing half.**
                 // The matcher alone would be inert in any workspace whose policy declares no shell
@@ -1107,10 +1477,24 @@ export function claudeCode(parsed, options = {}) {
     // The generation header. An emitted artifact that does not say what generated it invites the
     // one edit this whole rail exists to catch — a hand-fix that survives until the next compile
     // silently reverts it.
+    // **What compiled this, recorded beside what generated it** (#264). An unpinned run WOULD read
+    // the host's plugin cache while the rail reads the tree — it now refuses that arrangement outright
+    // (#316) — and until this field the artifact said nothing about which answered, so a drift RED named a difference no reader could find in the repository, because the
+    // deciding input was a directory outside it.
+    //
+    // **Origin and version, never the ROOT PATH.** The discovered root is an absolute path under
+    // somebody's home directory; recording it would make a tracked artifact machine-dependent and red
+    // `verify/compile.sh` for every developer and CI — trading a silent hazard for a permanent false
+    // one. `recordedOrigin` collapses the resolver's three tags to two for the same reason: the pinned
+    // rail and a bare run must agree byte for byte about an identical world.
+    const packs = (options.packProvenance ?? [])
+        .map((c) => ({ pack: c.pack, origin: c.origin, version: c.version ?? null }))
+        .sort((a, b) => a.pack.localeCompare(b.pack));
     const value = {
         $portulan: {
             generated: "cli/compile.mjs",
             source,
+            ...(packs.length ? { packs } : {}),
             warning: `Generated file. Edit ${source} and recompile; \`verify/compile.sh\` fails on drift.`,
         },
         permissions: { deny, ask, allow: [] },
@@ -1148,6 +1532,21 @@ export function claudeCode(parsed, options = {}) {
                 `project, or pass \`--runner\`/\`--stop-runner\` to name a path you control`,
         );
     }
+    if (editCoveredGates.length) {
+        notes.push(
+            `${editCoveredGates.length} write gate(s) — ${editCoveredGates.join(", ")} — emit \`Edit(path)\` as their only ` +
+                `permission pattern, and that ONE pattern is matched for every file-editing tool. Measured on Claude Code ` +
+                `2.1.240: with \`Edit(path)\` alone in the list and \`Write\` allowed, the host refused the write — and a ` +
+                `\`Write\` to a DIFFERENT path succeeded in the same session, the control that tells *refused* from ` +
+                `*refuses everything*. \`Write(path)\` ` +
+                `and \`NotebookEdit(path)\` are NOT emitted because the host discards them — it says so on every start — and a ` +
+                `compiler that emitted them would report three rules where one enforces. **Re-measure on a host change in EITHER ` +
+                `direction:** this is a fact about one CLI version. If a later host stops treating \`Edit\` as tool-general, ` +
+                `this gate narrows to one tool at the permission layer with nothing here going red. And no EARLIER host was ` +
+                `re-measured — on one that honoured all three patterns and did not treat \`Edit\` as tool-general, this ` +
+                `emission removes two working rules. The hook covers all three tool names on any host.`,
+        );
+    }
     if (shellWriteGates.length) {
         notes.push(
             `${shellWriteGates.length} write gate(s) — ${shellWriteGates.join(", ")} — also match a Bash command that writes the ` +
@@ -1438,6 +1837,11 @@ function artifactPaths(workspaceDir) {
 
 /** Every backend, run against one parsed policy. The order is the order the matrix prints in. */
 export function backends(parsed, options = {}) {
+    // **Provenance rides in the Claude Code artifact only, and that is an honest limit rather than an
+    // oversight.** `githubRuleset` emits to a fixed external schema that has nowhere to carry a
+    // `$portulan` block; its provenance is the one line it can carry, in `name`. Both backends compile
+    // from ONE root plan per run, so the recorded origins describe the ruleset's inputs too — they are
+    // simply not readable in its file. Stated here and in `../.portulan/compile/README.md` (#264).
     return [claudeCode(parsed, options), githubRuleset(parsed, options)];
 }
 
@@ -1467,7 +1871,76 @@ export function matrix(parsed, options = {}) {
 // ===========================================================================================
 
 /**
- * Where a workspace's gate policy lives.
+ * The same answer as `policyPath`, plus WHICH ARM produced it — and, where the manifest named
+ * something unusable, WHY.
+ *
+ * `policyPath` returns a path either way, which is all a reader of the policy needs and is exactly
+ * what made the caller unable to tell two different situations apart: a workspace that NAMES a policy
+ * file which is missing (a genuine error — something is declared and absent), and a workspace that
+ * names none at all (a legitimate shape, per this function's own note below). Both arrived at
+ * `readJson` as `ENOENT` and were reported identically, so the second — documented here as legitimate
+ * — surfaced as `cannot read the gate policy at …/gates.json`, which reads like a corrupt or deleted
+ * file and sends the reader to look for one that was never supposed to exist.
+ *
+ * Found 2026-08-22 while booting the `sleepy-panda` workspace, which declares no `gates` key and
+ * composes a pack contributing two gate rules: the compiler refused with an ENOENT that mentioned
+ * neither fact. Reporting declaredness is what lets the caller say which of the two it is.
+ *
+ * **`declared: false` is four situations, not one, so it carries a `reason`.** The first cut reported
+ * every one of them as "`workspace.json` has no top-level `gates` key", which is false for a manifest
+ * that is absent and false for a `gates` value this function refused — the same two-situations-one-
+ * sentence defect this change exists to fix, reproduced one level down. `reason` is `no-key`,
+ * `no-manifest`, `refused`, or `declared`. Found by Copilot on this pull request.
+ */
+export function policyDeclaration(workspaceRoot, workspaceDir = ".portulan") {
+    const base = path.join(workspaceRoot, workspaceDir);
+    const manifest = path.join(base, "workspace.json");
+    const fallback = (reason) => ({ file: path.join(workspaceRoot, workspaceDir, "gates.json"), declared: false, reason });
+    let declared;
+    try {
+        declared = JSON.parse(fs.readFileSync(manifest, "utf8")).gates;
+    } catch {
+        // No manifest, or unreadable. `doctor` is the tool that judges a manifest; this one only needs
+        // to know where the policy is, and the default is where it is when nothing says otherwise.
+        return fallback("no-manifest");
+    }
+    if (declared === undefined) return fallback("no-key");
+    // Validated against the schema's `filePath` shape before it is used, and containment is
+    // checked after resolution rather than by pattern alone — a `../` chain passes any regex and
+    // still escapes. Without this, a malformed or hand-edited manifest turns a hook that runs on
+    // EVERY tool call into an arbitrary file read outside the workspace. `doctor` would refuse such
+    // a manifest, but this runner must not depend on `doctor` having been run: the two tools have
+    // no ordering between them, and the schema is the contract, not the sequence. Found by review.
+    //
+    // **`isInside`, not another hand-rolled spelling.** The containment test read
+    // `!path.relative(base, resolved).startsWith("..")` until 2026-08-22 — the spelling
+    // `./inside.mjs` exists to replace, which calls an ordinary directory named `..foo` an escape and
+    // falls back for a policy that was inside all along. This module already imports `isInside` and
+    // already carries the same warning at `recordedOrigin`, so the rule was in scope and unread.
+    // Pre-existing, and surfaced by Copilot on the pull request that touched this line.
+    //
+    // **No count is asserted here.** A first draft called this "the fifth copy"; the pre-commit
+    // checkpoint could not reproduce that figure and a census then found more, including one in THIS
+    // module at `resolveWorkspace`. The census is #331 rather than this commit, because the remaining
+    // sites do not share semantics — they disagree on the empty relative path and on absolute paths —
+    // so each needs its own red and green. An unreproducible number is worse than none.
+    if (typeof declared === "string" && declared.trim() && FILE_PATH.test(declared)) {
+        const resolved = path.resolve(base, declared);
+        if (resolved !== base && isInside(base, resolved)) return { file: resolved, declared: true, reason: "declared" };
+    }
+    // The manifest named something, and nothing it named is usable — a wrong type, an empty string, a
+    // shape the schema refuses, or a path that escapes the workspace. The compiler is on the
+    // conventional path, so the fallback owns the diagnostic; but this is NOT the state of a manifest
+    // that named nothing, and a message conflating the two is the defect this change is about.
+    return fallback("refused");
+}
+
+/**
+ * Where a workspace's gate policy lives — the path alone.
+ *
+ * Kept as the narrow answer because most callers want exactly that, and because every existing caller
+ * and test was written against a string. `policyDeclaration` is the one that also says whether the
+ * workspace named it, and why when it did not.
  *
  * Read from the manifest's top-level `gates` key, because that is what the key MEANS —
  * `../spec/slots.md` calls it "a path to a JSON file the enforcement compiler reads", and `doctor`
@@ -1481,26 +1954,73 @@ export function matrix(parsed, options = {}) {
  * refusing it would make the key required, which is a spec change nobody decided.
  */
 export function policyPath(workspaceRoot, workspaceDir = ".portulan") {
-    const base = path.join(workspaceRoot, workspaceDir);
-    const manifest = path.join(base, "workspace.json");
+    return policyDeclaration(workspaceRoot, workspaceDir).file;
+}
+
+/**
+ * What to say when a workspace declares no gate policy and none is there by convention.
+ *
+ * This is a STATE, not a failure to read a file, and the difference is the whole point: `policyPath`'s
+ * note calls an absent `gates` key "a legitimate shape, and refusing it would make the key required,
+ * which is a spec change nobody decided" — and then the reader refused it anyway, with `ENOENT` on a
+ * file the workspace never claimed to have.
+ *
+ * It stays a refusal (exit 2, nothing written), because nothing was compiled and a compiler that
+ * reports success having emitted nothing is the failure this repository keeps writing checks against.
+ * What changes is that the refusal names the actual state and what it costs.
+ *
+ * **The pack count is the load-bearing half.** A workspace in this shape may still compose packs
+ * contributing gate fragments — `sleepy-panda` composes `rituals/checkpoints`, which contributes two
+ * — and those rules silently reach nothing, because a fragment tightens a policy and there is none to
+ * tighten. That is the fact a reader needs and the one the old message could not carry: it threw
+ * before `packContributions` was ever called.
+ */
+function undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, reason = "no-key") {
+    const manifest = path.join(workspaceRoot, workspaceDir, "workspace.json");
+    // **One opening per arm, because the arm is the reader's first question.** `no-key` is the shape
+    // this whole change defends as legitimate; `no-manifest` is a workspace that has not been
+    // authored yet; `refused` is a manifest that DID name a policy and named one this compiler will
+    // not read, which is neither of the other two and must not be told it has no `gates` key.
+    const opening =
+        reason === "refused"
+            ? `\`workspace.json\` names a gate policy this compiler will not read — its top-level ` +
+              `\`gates\` key is not a relative path to a file inside the workspace — and there is no ` +
+              `\`gates.json\` at ${policyFile} either.`
+            : reason === "no-manifest"
+              ? `this workspace declares no gate policy — there is no readable \`workspace.json\` at ` +
+                `${manifest}, and there is no \`gates.json\` at ${policyFile}.`
+              : `this workspace declares no gate policy — \`workspace.json\` has no top-level \`gates\` key, ` +
+                `and there is no \`gates.json\` at ${policyFile}.`;
+    const lines = [`${opening} Nothing was compiled and nothing was written.`];
+    let composed = null;
     try {
-        const declared = JSON.parse(fs.readFileSync(manifest, "utf8")).gates;
-        // Validated against the schema's `filePath` shape before it is used, and containment is
-        // checked after resolution rather than by pattern alone — a `../` chain passes any regex and
-        // still escapes. Without this, a malformed or hand-edited manifest turns a hook that runs on
-        // EVERY tool call into an arbitrary file read outside the workspace. `doctor` would refuse such
-        // a manifest, but this runner must not depend on `doctor` having been run: the two tools have
-        // no ordering between them, and the schema is the contract, not the sequence. Found by review.
-        if (typeof declared === "string" && declared.trim() && FILE_PATH.test(declared)) {
-            const resolved = path.resolve(base, declared);
-            const inside = path.relative(base, resolved);
-            if (inside && !inside.startsWith("..") && !path.isAbsolute(inside)) return resolved;
-        }
+        composed = packContributions(workspaceRoot, workspaceDir, packOptions);
     } catch {
-        // No manifest, or unreadable. `doctor` is the tool that judges a manifest; this one only needs
-        // to know where the policy is, and the default is where it is when nothing says otherwise.
+        // The pack layer has refusals of its own — a shadowed pack, a malformed pack manifest, an
+        // unresolvable root. Swallowed HERE and nowhere else: this message is about the missing policy,
+        // and a pack refusal raised from inside a diagnostic would replace the answer with a different
+        // question. Declare a policy and the very next run surfaces it on its own terms.
     }
-    return path.join(workspaceRoot, workspaceDir, "gates.json");
+    const contributions = composed?.contributions ?? [];
+    const rules = contributions.reduce((n, c) => n + (c.fragments?.length ?? 0), 0);
+    if (rules > 0) {
+        const packs = contributions
+            .filter((c) => (c.fragments?.length ?? 0) > 0)
+            .map((c) => `\`${c.pack}\``)
+            .join(", ");
+        lines.push(
+            `${rules} pack-contributed gate rule(s) from ${packs} are therefore NOT compiled: ` +
+                `a fragment tightens a policy, and there is none here to tighten.`,
+        );
+    }
+    lines.push(
+        reason === "refused"
+            ? "Give `gates` a relative path to a file inside the workspace directory, or remove the key " +
+                  "and let `gates.json` be found by convention."
+            : "Declare one with `portulan new gate-policy`, or leave it undeclared deliberately — " +
+                  "a workspace with no gate policy is a legitimate shape, and this is a state rather than a fault.",
+    );
+    return lines.join("\n  ");
 }
 
 // ===========================================================================================
@@ -1626,6 +2146,103 @@ export function rootPlan(workspaceDir, manifest, { named = [], namedGiven = null
  * them. What it depends on instead is `parse`, which validates every composed rule exactly as it
  * validates a hand-written one, so a malformed fragment is refused by the same code either way.
  */
+/**
+ * How a resolved pack's ORIGIN is recorded in an emitted artifact — a deliberate collapse of the
+ * resolver's three tags into two, and the collapse is the load-bearing part.
+ *
+ * `resolutionRoots` tags roots `named | derived | discovered`. Recording that raw would be wrong in a
+ * way that turns this whole feature into a liability: the PINNED rail spells its root
+ * (`--pack-root packs`, tagged `named`) while a bare run derives the same directory (tagged
+ * `derived`). Two documented-correct spellings of the same world would emit different bytes, and
+ * `verify/compile.sh` would go red on a tree nothing was wrong with — a per-machine false red, which
+ * is worse than the silent hazard #264 is about.
+ *
+ * So: `discovered` iff the answering root came from discovery — **which is a statement about where the
+ * root was FOUND, not about where it sits.** Discovery reads a record under `CLAUDE_CONFIG_DIR`, and a
+ * hermetic run can point that inside the tree, so a discovered root is not necessarily an external one;
+ * the docblock said "a directory outside this repository" until review caught the conflation, and the
+ * distinction is this field's whole subject rather than a quibble — it is why `outside-tree` exists as
+ * a separate answer below. Otherwise `tree`, when the root is one the repository itself yields. A NAMED root that is not under the workspace root is neither, and is recorded as
+ * `outside-tree` rather than flattened into `tree`, because calling somebody's `--pack-root /elsewhere`
+ * "the tree" would be this field's first lie.
+ */
+export function recordedOrigin(root, plan, workspaceRoot) {
+    const same = (a, b) => path.resolve(a) === path.resolve(b);
+    const tagged = (plan?.origins ?? []).find((o) => same(o.root, root));
+    if (tagged?.origin === "discovered") return "discovered";
+    // **`derived` and `named` take the SAME inside-the-repository test**, and the first draft trusted
+    // `derived` on its tag alone. It is derived from the manifest's `tree`, which is a string a human
+    // edits: `tree: "../../elsewhere"` resolves a derived root of `/elsewhere/packs` — measured — and
+    // that would have been recorded as `tree`. A tag says where a root CAME FROM; only the path says
+    // whether it is in this repository, and this field's whole job is the second question. Copilot.
+    //
+    // Inside INCLUDES being the repository itself, which the first draft called `outside-tree` on a
+    // `rel` of `""`. By this function's own standard that was the field's first lie.
+    //
+    // **Both sides resolved through `realpathSync`**, because a lexical comparison makes two spellings
+    // of one directory disagree: `--workspace <alias> --pack-root <realpath>` recorded `outside-tree`
+    // for a root plainly inside the tree, which would emit a different artifact for an identical world
+    // — the per-machine false red this whole design refuses. Measured. It is the same trap #220's
+    // second arm repaired in the Stop-gate's divergence sentence, and it is worth stating twice
+    // because the two sites were written a day apart and neither inherits the other's guard.
+    const real = (dir) => {
+        try {
+            return fs.realpathSync(path.resolve(dir));
+        } catch {
+            return path.resolve(dir);
+        }
+    };
+    // **`isInside`, not a fourth hand-rolled spelling.** `!rel.startsWith("..")` calls a directory
+    // literally named `..foo` outside the tree — and this repository has already paid for that exact
+    // reasoning once: `./index.mjs`'s docblock records it as the ninth fail-open found in this
+    // scaffolding, and *the first one written by the change that cites the class*. This was the second.
+    // The helper is exported precisely so a third copy cannot drift into it. Copilot.
+    return isInside(real(workspaceRoot), real(root)) ? "tree" : "outside-tree";
+}
+
+/**
+ * Two copies of one pack answered, and this says what differs between them.
+ *
+ * **One carrier, because the comparison has already been wrong twice.** `doctor` grew this first and
+ * its history is the argument for not writing a fourth: a first spelling projected `[id, tier, action]`
+ * and so read a copy differing in `reason` as agreeing — while `composeFragments` pushes the WHOLE
+ * fragment, so those differences do reach the compiled policy; a second compared the whole fragment
+ * but claimed *byte-identical*, which `JSON.stringify` of a parsed value cannot promise. This is that
+ * third, correct version, moved here so `doctor` and `compile` cannot drift apart about what a shadow
+ * IS — proposal `0020`'s rule, applied to a function rather than to a sentence.
+ *
+ * Parsed and key-order-normalised is the RIGHT comparison: reformatting a `pack.json` changes nothing
+ * about what the pack contributes, so reporting it would be noise.
+ */
+export function packDifferences(mine, other) {
+    const canonical = (v) =>
+        Array.isArray(v)
+            ? v.map(canonical)
+            : v && typeof v === "object"
+              ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])]))
+              : v;
+    const frag = (m) => JSON.stringify(canonical(m?.contributes?.gates ?? []));
+    const mineV = mine?.portulan?.version ?? "no version";
+    const otherV = other?.portulan?.version ?? "no version";
+    const differs = [];
+    if (mineV !== otherV) differs.push(`version ${mineV} against the tree's ${otherV}`);
+    if (frag(mine) !== frag(other)) differs.push("gate fragments that differ once parsed");
+    return differs;
+}
+
+/**
+ * The non-discovered copy of a pack that a discovered root answered for — or `null` when there is no
+ * shadow. `originOf` maps a root to its tag; pass `plan.origins`' lookup.
+ *
+ * Only a **discovered** answer can be shadowed in the sense that matters: a named root replaces the
+ * derived one, so nothing is behind it, and a derived answer is the tree's own copy already.
+ */
+export function shadowedCopy(name, answeringOrigin, roots, originOf) {
+    if (answeringOrigin !== "discovered") return null;
+    const behind = resolvePack(name, roots.filter((r) => originOf(r) !== "discovered"));
+    return behind.dir ? behind : null;
+}
+
 export function packContributions(workspaceRoot, workspaceDir = ".portulan", options = {}) {
     const base = path.join(workspaceRoot, workspaceDir);
     let manifest;
@@ -1666,6 +2283,83 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
             continue;
         }
         const packManifest = readJson(found.manifest, `the pack manifest for \`${found.name}\``);
+        // **A shadowed pack is a could-not-run, not a resolution** (#316). Two roots answered for one
+        // declared name and the invocation does not say which the caller meant, so this compiler has
+        // no honest way to pick — and unlike `doctor`, which reports and never grades because an
+        // install state is a fact about a machine rather than a verdict about the repository, this one
+        // does not report: it EMITS. Picking silently wrote the discovered copy's fragments into the
+        // artifact while `verify/compile.sh` read the tree's, which on this project's own host meant a
+        // `git commit --no-verify` matcher that the tree had deliberately removed as false coverage.
+        //
+        // **Refused at RESOLUTION, so `--check` and the write path inherit one rule.** Refusing only
+        // on write would make one tool answer one ambiguity two ways: the check would go on adopting
+        // the discovered world and exit 1 — asserting that the *repository* drifted when it had not.
+        // An exit code is the machine-read API, and a false 1 is a false verdict about the tree.
+        //
+        // **Every unasked shadow refuses, including one whose manifests agree**, which reads as
+        // over-strict until you follow the bytes: `recordedOrigin` tags the answering root into
+        // `$portulan.packs[].origin`, so a discovered answer emits `discovered` where the rail's
+        // artifact says `tree`. Agreement in the manifests is therefore not agreement in the artifact,
+        // and a carve-out for it would ship a compile that still reds the recipe it was meant to
+        // reconcile with. The message distinguishes the two cases; the refusal does not.
+        //
+        // **Only where the caller did not choose.** `--pack-root auto` is discovery ELECTED, and
+        // electing it is the choice this refusal exists to ask for. Both spellings are offered in the
+        // message, because naming only the tree would make the refusal decide the question it claims
+        // to be handing back.
+        //
+        // **The `named` half of this guard is defence in depth, and that was measured rather than
+        // assumed.** Forcing the condition to `true` — refuse unconditionally — leaves the named-root
+        // case still passing: a named root REPLACES the derived one, so the plan carries no discovered
+        // root, `shadowedCopy` finds nothing behind, and there is no shadow to refuse. The protection
+        // is structural. The clause stays because it states the intent at the site where a future
+        // change to `resolutionRoots` could quietly make it load-bearing.
+        if (!(options.forced ?? false) && plan.source !== "named") {
+            const behind = shadowedCopy(found.name, recordedOrigin(found.root, plan, workspaceRoot), roots, (r) =>
+                (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin,
+            );
+            if (behind) {
+                let other = null;
+                try {
+                    other = JSON.parse(fs.readFileSync(behind.manifest, "utf8"));
+                } catch (cause) {
+                    throw new CompileError(
+                        `\`${found.name}\` resolved under the root ${found.root} while the root ` +
+                            `${path.relative(workspaceRoot, behind.root)} also carries it, ` +
+                            `and that second copy could not be read (${cause.message}) — so which one this would compile from could not be established. ` +
+                            "Name the root: `--pack-root packs` compiles from the tree, `--pack-root auto` from the installed copy.",
+                    );
+                }
+                const differs = packDifferences(packManifest, other);
+                // **Both ROOTS by path — the roots, not the pack directories.** `resolvePack` returns
+                // both, and a first cut printed `dir` (`<root>/<category>/<pack>`) while calling it a
+                // root: a diagnostic that mislabels the thing it names, in a message whose own claim is
+                // to name both roots. The root is also the more useful of the two, because it is what a
+                // reader types back into `--pack-root`. A refusal naming only one hands back a choice
+                // while withholding half of what it is between. Printing the absolute path is safe in a
+                // way it is not in `$portulan.packs`: this is stderr, read once by a human, never a
+                // tracked artifact, so #264's origins-never-paths rule (which exists to stop a
+                // machine-dependent path being committed) does not reach it. `doctor` already prints it
+                // in its resolves-from note, so the two tools now name the same two directories.
+                //
+                // **"Discovered on this host", never "outside this repository".** Discovery reads a
+                // record under `CLAUDE_CONFIG_DIR`, which a hermetic run can point INSIDE the tree — so
+                // a discovered root is not necessarily an external one, and the message must not assert
+                // a location it has not tested. `recordedOrigin` keeps `discovered` and `outside-tree`
+                // as separate answers for exactly this reason: where a root came from and where it sits
+                // are different questions, and the path is printed right there for a reader who wants
+                // the second one. Caught by review after the first cut conflated them.
+                throw new CompileError(
+                    `\`${found.name}\` is SHADOWED — it resolved under ${found.root}, a root discovered on this ` +
+                        `host, while the root ${path.relative(workspaceRoot, behind.root)} also carries it. ` +
+                        (differs.length
+                            ? `They differ by ${differs.join(" and ")}, so the two roots compile to different policies. `
+                            : "Their manifests agree, but the emitted artifact still records which root answered, so the two roots compile to different bytes. ") +
+                        "Refusing to pick: name the root instead — `--pack-root packs` compiles from the tree, which is what " +
+                        "`verify/compile.sh` checks, and `--pack-root auto` compiles from the installed copy.",
+                );
+            }
+        }
         const fragments = packManifest?.contributes?.gates;
         // Checked here rather than left to `composeFragments` iterating it: a manifest is a file a
         // human edits, `doctor` may not have run (the two tools have no ordering between them), and a
@@ -1678,7 +2372,18 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
                     `Refusing to compose it — run \`doctor\` to validate the pack against the Pack Definition.`,
             );
         }
-        contributions.push({ pack: found.name, dir: found.dir, fragments: fragments ?? [] });
+        contributions.push({
+            pack: found.name,
+            dir: found.dir,
+            fragments: fragments ?? [],
+            // **Provenance, recorded per pack**, so the artifact this compiles into can say what
+            // compiled it (#264). `version` comes from `portulan.version` — the pack manifest's own
+            // location for it, not a top-level `version` — and its ABSENCE is recorded as such rather
+            // than as a blank, because "this pack declares no version" and "I did not look" are
+            // different facts and only one of them is the pack's.
+            origin: recordedOrigin(found.root, plan, workspaceRoot),
+            version: typeof packManifest?.portulan?.version === "string" ? packManifest.portulan.version : null,
+        });
     }
     // `plan` travels with the result because every consumer prints it: which source won, and the path
     // it won with, is what tells a feed resolution from a local one.
@@ -2068,7 +2773,25 @@ export function run(argv, options = {}) {
         // The workspace may be named as a repository root or as the workspace directory itself, and the
         // second is how a feed-side workspace is reachable at all — see `resolveWorkspace`.
         const { workspaceRoot, workspaceDir } = resolveWorkspace(named);
-        const policyFile = policyPath(workspaceRoot, workspaceDir);
+        const { file: policyFile, declared: policyDeclared, reason: policyReason } = policyDeclaration(workspaceRoot, workspaceDir);
+        // **Declared-and-missing and never-declared are different answers.** Only the first is a
+        // failure to read something this workspace claimed to have; the second is a shape `policyPath`
+        // documents as legitimate, and reporting it as `ENOENT` sent readers hunting for a deleted
+        // file. Checked here rather than inside the reader because only the caller knows to name what
+        // the absence costs — see `undeclaredPolicyMessage`. The fallback arm is itself FOUR states,
+        // and `policyReason` is what lets the message name the one it is in rather than assert the
+        // commonest: this comment read "two different answers" while the code below had four.
+        if (!policyDeclared && !fs.existsSync(policyFile)) {
+            throw new CompileError(
+                undeclaredPolicyMessage(
+                    policyFile,
+                    workspaceRoot,
+                    workspaceDir,
+                    { named: namedRoots, discovery: () => discoverPackRoots(), forced },
+                    policyReason,
+                ),
+            );
+        }
         const policy = readJson(policyFile, "the gate policy");
         // The cascade's middle layer, composed before the policy is parsed so that a pack's fragment
         // is validated by exactly the code that validates a hand-written rule.
@@ -2106,7 +2829,14 @@ export function run(argv, options = {}) {
         // fails open, silently. That is the exact defect class this whole change exists to close,
         // reintroduced through the cross-compile path. Found by the pre-commit checkpoint, which
         // demonstrated it rather than reasoning about it.
-        const columns = backends(parsed, { source, root: path.resolve(workspaceRoot), workspaceDir });
+        const columns = backends(parsed, {
+            source,
+            root: path.resolve(workspaceRoot),
+            workspaceDir,
+            // What resolved each pack, carried to the artifact so the file the rail compares says
+            // which world compiled it (#264).
+            packProvenance: contributions,
+        });
 
         // Printed before the backends, because a rule's provenance changes how its compiled line reads
         // — and an unresolvable pack is a declaration the workspace believes it composed.
@@ -2162,7 +2892,34 @@ export function run(argv, options = {}) {
                     continue;
                 }
                 if (current !== column.artifact.text) {
-                    say(`RED — ${file} has drifted from ${policyFile}. Recompile.`);
+                    // **Name the origin difference AT THE MOMENT OF FAILURE** (#264). A drift caused by
+                    // a shadowed pack was previously reported as a diff nobody could reproduce from the
+                    // files in front of them, because the deciding input was a directory outside the
+                    // repository — and the remedy the sentence prescribed, "Recompile", is the very
+                    // unpinned act that caused it. Read DEFENSIVELY: the artifact on disk is a file a
+                    // human may have edited, so anything unparseable leaves the plain sentence standing
+                    // rather than turning a drift report into a crash.
+                    let why = "";
+                    try {
+                        const onDisk = JSON.parse(current)?.$portulan?.packs;
+                        const mine = JSON.parse(column.artifact.text)?.$portulan?.packs;
+                        if (Array.isArray(onDisk) && Array.isArray(mine)) {
+                            const key = (p) => `${p.origin ?? "?"} ${p.version ?? "no version"}`;
+                            const byName = new Map(mine.map((p) => [p.pack, p]));
+                            const moved = onDisk
+                                .filter((p) => byName.has(p.pack) && key(byName.get(p.pack)) !== key(p))
+                                .map((p) => `\`${p.pack}\` was compiled from the ${key(p)} copy; this check reads the ${key(byName.get(p.pack))} one`);
+                            if (moved.length) {
+                                why =
+                                    `\n      ${moved.join("\n      ")}` +
+                                    "\n      That is a different world, not a stale file: recompile with the root this check uses" +
+                                    `\n      — \`node cli/compile.mjs --workspace . --pack-root packs\` — rather than bare, or the drift returns.`;
+                            }
+                        }
+                    } catch {
+                        // Unparseable or hand-edited. The plain sentence below is still true.
+                    }
+                    say(`RED — ${file} has drifted from ${policyFile}. Recompile.${why}`);
                     drifted += 1;
                 }
             }