@sleepy_panda_srl/portulan 0.1.1 → 0.1.2

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 {
@@ -1107,10 +1108,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: [] },
@@ -1438,6 +1453,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)];
 }
 
@@ -1626,6 +1646,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 +1783,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 +1872,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.
@@ -2106,7 +2311,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 +2374,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;
                 }
             }

package/cli/doctor.mjs

@@ -43,7 +43,16 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 // it looks like enforcement that quietly stopped covering something. Same reasoning that has
 // ./gate.mjs import the matcher instead of writing a second one. Zero
 // dependencies on both sides, so nothing is added to what this tool needs to run.
-import { parse, backends, resolvePack, rootPlan, packContributions, composeFragments } from "./compile.mjs";
+import {
+    parse,
+    backends,
+    resolvePack,
+    rootPlan,
+    packContributions,
+    composeFragments,
+    packDifferences,
+    shadowedCopy,
+} from "./compile.mjs";
 // The containment test the memory-index siting rule turns on, imported for the reason directly
 // above: the copy that used to live here drifted into the identical fail-open as the original.
 import { isInside, recordType } from "./index.mjs";
@@ -1815,6 +1824,50 @@ export async function inspect(workspaceDir, options = {}) {
                 "packs",
                 `\`${name}\` resolves${from} to ${path.relative(dir, found.dir)} and validates against Pack Definition ${manifest.portulan.pack} — contributes ${parts.length ? parts.join(", ") : "nothing"}`,
             );
+
+            // **A SHADOWED pack is reported, and the report says WHAT DIFFERS** (#264). Resolution is
+            // first-match-wins and discovered roots come first, so where the host carries a copy of a
+            // pack the tree also carries, the installed one answers and nothing said so. Silence about
+            // the shadowed copy is the part that makes the failure unreproducible: the compiled artifact
+            // moves, the rail reds, and the deciding input is a directory outside the repository.
+            //
+            // A REPORT, never a verdict — an installed pack shadowing a tree copy is a fact about the
+            // machine, and this tool must not turn a fact about the machine into a verdict about the
+            // repository (the boundary this file already states for discovered roots).
+            {
+                const shadowed = shadowedCopy(name, origin, roots, (r) => originOf.get(r)) ?? { dir: null };
+                if (shadowed.dir) {
+                    let other = null;
+                    try {
+                        other = JSON.parse(fs.readFileSync(shadowed.manifest, "utf8"));
+                    } catch (cause) {
+                        // Could-not-compare, in so many words. A shadow we cannot read is not a shadow
+                        // we can call harmless, and saying nothing here would be the silence this whole
+                        // report exists to end.
+                        report(
+                            "packs",
+                            `\`${name}\` is SHADOWED — the tree-derived root also carries it at ${path.relative(dir, shadowed.dir)}, and that copy could not be read (${cause.message}), so what differs could not be compared`,
+                        );
+                    }
+                    if (other) {
+                        // **The comparison lives in `compile.mjs`, and this calls it.** It grew here,
+                        // and its two earlier spellings each claimed more than they compared — a
+                        // projection over `[id, tier, action]` that read a copy differing in `reason`
+                        // as agreeing, and a *byte-identical* claim `JSON.stringify` of a parsed value
+                        // cannot make. `compile` now has to answer the same question in order to refuse
+                        // a shadow it cannot honestly pick between (#316), and a second copy of a
+                        // comparison already corrected twice is exactly proposal `0020`'s defect. The
+                        // rationale for parsed-and-key-sorted moved with the code.
+                        const differs = packDifferences(manifest, other);
+                        report(
+                            "packs",
+                            `\`${name}\` is SHADOWED — the installed copy answered and the tree-derived root also carries it at ` +
+                                `${path.relative(dir, shadowed.dir)}; ${differs.length ? `they differ by ${differs.join(" and ")}` : "the two agree today"}. ` +
+                                "An unpinned `compile` or `recipe-set` REFUSES this rather than picking, and so does `index` for a workspace declaring a scope index — name the root: `--pack-root packs` for the tree, which is what the recipes check",
+                        );
+                    }
+                }
+            }
         }
     }
 

package/cli/index.mjs

@@ -74,7 +74,10 @@ import { pathToFileURL } from "node:url";
 // compiler and `doctor` already resolve it. A second resolver here would be a second answer to
 // "which pack is that" — and issue #74 already records what a memory store cost this project when
 // three copies decided what counted as a record.
-import { resolvePack, rootPlan } from "./compile.mjs";
+// `shadowedCopy` rides along with the two this file already imports: the predicate for *is this pack
+// shadowed* is one carrier by #316's own argument, and a second spelling here would be the defect that
+// change was filed against, committed one tool over.
+import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 // Host plugin-cache discovery (#123) — imported, never re-implemented, for the reason above.
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
@@ -101,34 +104,14 @@ const NOT_A_RECORD = new Set(["README.md"]);
 
 const KB = 1024;
 
-/**
- * Is `child` inside `parent`? Exported because `doctor` asks the same question about the same two
- * paths, and the obvious spelling — `!path.relative(parent, child).startsWith("..")` — is wrong in a
- * way that fails OPEN.
- *
- * A name beginning with `..` is an ordinary filename, not a traversal: `path.relative` of
- * `memory/..index.md` against `memory/` is `..index.md`, which `startsWith("..")` calls *outside*.
- * Measured end to end before this was written — an index declared at `memory/..index.md` was written
- * into the store, reported `ok`, and `doctor` then counted it as a second record, reporting it for
- * stating no retirement condition. That is precisely the outcome the siting rule exists to prevent,
- * in the check chosen over a filename exemption **because** an exemption would be a door any record
- * could walk through. The door was in the containment test. Found by Copilot on #72, in the
- * suppressed half of the round; ninth fail-open found in this repository's scaffolding, and the
- * first one written by the change that cites the class.
- *
- * Only `..` exactly, or `..` followed by a separator, means outside. An absolute result means the
- * two paths share no root and cannot contain one another.
- *
- * It lives here and `doctor` imports it, on the reasoning that already put `compile`'s accounting
- * behind one import: two copies of a rule drift, and these two copies drifted into the identical
- * defect before either had shipped.
- */
-export function isInside(parent, child) {
-    const rel = path.relative(parent, child);
-    if (rel === "") return true;
-    if (path.isAbsolute(rel)) return false;
-    return rel !== ".." && !rel.startsWith(`..${path.sep}`);
-}
+// `isInside` moved to `./inside.mjs` and is re-exported here, so `./doctor.mjs` and every other
+// importer is untouched. It left because `./compile.mjs` needs it too and this file imports FROM
+// `compile.mjs` — taking it from here would have closed an import cycle, which this repository has
+// already had exit 13 in silence once. The predicate was not copied: one implementation, no new edges.
+// Imported AND re-exported: a bare `export … from` re-exports without binding the name in this
+// module's own scope, and this file calls `isInside` itself — 104 tests said so immediately.
+import { isInside } from "./inside.mjs";
+export { isInside };
 
 // ===========================================================================================
 // Titles
@@ -455,7 +438,12 @@ export function readScopes(dir, workspace, options = {}) {
     const plan = rootPlan(dir, workspace, {
         named: options.packRoots ?? [],
         namedGiven: options.packRoots !== undefined && options.packRoots !== null,
-        discovery: () => discoverPackRoots(),
+        // **Injectable, defaulting to the real reader.** It was hardcoded to `discoverPackRoots()`,
+        // which meant no case could exercise this tool's discovery path without the machine's own
+        // plugin cache deciding the outcome — so the shadow refusal below would have been testable
+        // only by arranging a real install. `recipe-set`'s `resolverFor` already takes the thunk;
+        // this is the same seam, and the default keeps every existing caller byte-identical.
+        discovery: options.discovery ?? (() => discoverPackRoots()),
         forced: options.discoverPacks === true,
     });
     if (plan.refusal) throw new IndexError(plan.refusal);
@@ -478,6 +466,53 @@ export function readScopes(dir, workspace, options = {}) {
             unresolved.push(found);
             continue;
         }
+        // **A shadowed pack is refused here too** (#318), on the same ground `compile` refuses it and
+        // NOT on the same argument — the difference matters enough to write down, because copying
+        // compile's sentence here would state something this file spends four lines denying.
+        //
+        // The ground is the ambiguity: two roots answered for one declared name, the invocation does
+        // not say which the caller meant, and this tool goes on to digest the answering copy's memory
+        // scope into a **committed** index. Picking silently makes a tracked artifact a function of
+        // what happens to be installed.
+        //
+        // What does NOT transfer is compile's bytes argument. Compile refuses even an agreeing shadow
+        // because `recordedOrigin` tags the answering root into its artifact; this index records no
+        // such thing, by the design stated above and in this tool's own help. So an agreeing shadow
+        // here really would produce identical bytes — and the refusal is still unconditional, because
+        // the alternative is a per-tool predicate for *which* differences reach the digest. That
+        // predicate is narrower than "the manifests differ" and would silently widen with every key a
+        // later Pack Definition adds: fail-open by construction, and a third carrier of a comparison
+        // this repository has already had wrong twice.
+        //
+        // **Only where the caller did not choose**, exactly as in `compile`: a named root replaces the
+        // derived one, and `auto` is discovery elected.
+        if (!(options.discoverPacks === true) && plan.source !== "named") {
+            // Path-resolved, matching `compile`. `resolutionRoots` builds `origins` and `roots` from
+            // the same strings today, so an exact-string lookup is equal — but two resolve-equal
+            // spellings of one directory would make `compile` refuse where this passed, and three
+            // tools answering one question two ways is the shape this whole family is about.
+            const originAt = (r) => (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
+            const behind = shadowedCopy(name, originAt(found.root), roots, originAt);
+            if (behind) {
+                // **Relative to the REPOSITORY, so the path matches the flag the reader will type.**
+                // `dir` is the WORKSPACE directory, so relativising against it printed `../packs`
+                // beside a remedy reading `--pack-root packs` — one sentence disagreeing with itself.
+                // A first fix printed the absolute root, which made the sentence self-consistent and
+                // still showed a path nobody would type. `compile` and `recipe-set` relativise against
+                // the repository root; this derives the same root from the manifest's own `tree`, and
+                // falls back to the absolute path where a workspace declares none, since a workspace
+                // with no `tree` has no repository for a relative path to be relative to.
+                const repoRoot = typeof workspace?.tree === "string" && workspace.tree.trim() ? path.resolve(dir, workspace.tree) : null;
+                const behindShown = repoRoot ? path.relative(repoRoot, behind.root) : behind.root;
+                throw new IndexError(
+                    `\`${name}\` is SHADOWED — it resolved under ${found.root}, a root discovered on this host, ` +
+                        `while the root ${behindShown} also carries it. This index digests the ` +
+                        `answering copy's memory scope, so which root answered decides what a committed file says. ` +
+                        "Refusing to pick: name the root — `--pack-root packs` for the tree, which is what " +
+                        "`verify/index.sh` checks, or `--pack-root auto` for the installed copy.",
+                );
+            }
+        }
 
         let manifest;
         try {
@@ -759,9 +794,24 @@ export function inspect(dir, { write = false, packRoots: extraRoots, discoverPac
     const findings = [];
     const fail = (series, check, message) => findings.push({ severity: "fail", series, check, message });
 
-    const memory = judgeMemory(dir, workspace, { write, fail });
-    const handoffs = judgeHandoffs(dir, workspace, { write, fail });
-    const scopes = judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks });
+    // **The remedy a finding prints must be runnable on the machine that printed it** (#318). These
+    // findings surface through the PINNED `verify/index.sh` run — so on a pack developer’s host, where
+    // a declared pack is both installed and in the tree, a bare `node cli/index.mjs <dir>` now exits 2
+    // with the SHADOWED refusal instead of regenerating. That is the same defect this change repaired
+    // in `verify/index.sh`’s own comment, left standing one layer down: one rule, two sites, repaired
+    // at one — which is proposal `0020`’s shape and what the pre-commit sweep exists to catch.
+    //
+    // Echoing the caller’s flags is provably runnable: a finding only prints under an invocation that
+    // reached judgment, so that invocation’s own spelling resolved. A hardcoded `--pack-root packs`
+    // would be wrong for an adopter whose packs sit elsewhere.
+    const remedyFlags = [
+        ...(Array.isArray(extraRoots) ? extraRoots.map((r) => ` --pack-root ${r}`) : []),
+        ...(discoverPacks ? [" --pack-root auto"] : []),
+    ].join("");
+
+    const memory = judgeMemory(dir, workspace, { write, fail, remedyFlags });
+    const handoffs = judgeHandoffs(dir, workspace, { write, fail, remedyFlags });
+    const scopes = judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks, remedyFlags });
 
     return {
         dir,
@@ -814,7 +864,7 @@ function siteOutside(dir, declaredPath, slot, word) {
  * in `./doctor.mjs`, `./new.mjs`, `./init.mjs`, `./plugin-lint.mjs` and `./compile.mjs` — this was the
  * one read in the repository that did not carry it.
  */
-function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series, source, fail }) {
+function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series, source, fail, remedyFlags = "" }) {
     if (write) {
         try {
             fs.mkdirSync(path.dirname(indexPath), { recursive: true });
@@ -846,14 +896,14 @@ function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series,
     }
 
     if (actual === null) {
-        fail(series, "index", `${declaredPath} is declared and absent — run \`node cli/index.mjs ${dir}\` to generate it`);
+        fail(series, "index", `${declaredPath} is declared and absent — run \`node cli/index.mjs${remedyFlags} ${dir}\` to generate it`);
     } else if (!actual.equals(Buffer.from(expected, "utf8"))) {
-        fail(series, "index", `${declaredPath} is out of date against the ${source} — run \`node cli/index.mjs ${dir}\` to regenerate it`);
+        fail(series, "index", `${declaredPath} is out of date against the ${source} — run \`node cli/index.mjs${remedyFlags} ${dir}\` to regenerate it`);
     }
 }
 
 /** The memory store's index and its budgets. */
-function judgeMemory(dir, workspace, { write, fail }) {
+function judgeMemory(dir, workspace, { write, fail, remedyFlags = "" }) {
     const memory = workspace.memory;
     if (!memory) return { declared: false, path: null, expected: null, budgets: 0 };
 
@@ -890,7 +940,7 @@ function judgeMemory(dir, workspace, { write, fail }) {
     if (broken) return { declared: true, path: indexPath, expected: null, budgets: 0 };
 
     const expected = render(workspace, store);
-    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "memory", source: "store", fail });
+    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "memory", source: "store", fail, remedyFlags });
     const budgets = budgetFindings(memory, store, expected, fail);
 
     return { declared: true, path: indexPath, expected, budgets };
@@ -900,7 +950,7 @@ function judgeMemory(dir, workspace, { write, fail }) {
  * The handoff series' index. No budget — see spec/slots.md: every remedy a budget could ask for on an
  * append-only series is barred, so a rail here is one built to be broken.
  */
-function judgeHandoffs(dir, workspace, { write, fail }) {
+function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
     const declaredPath = workspace.handoffs?.index?.path;
     if (!declaredPath) return { declared: false, path: null, expected: null };
 
@@ -935,7 +985,7 @@ function judgeHandoffs(dir, workspace, { write, fail }) {
     if (broken) return { declared: true, path: indexPath, expected: null };
 
     const expected = renderHandoffIndex(workspace, series);
-    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "handoffs", source: "series", fail });
+    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "handoffs", source: "series", fail, remedyFlags });
 
     return { declared: true, path: indexPath, expected };
 }
@@ -954,7 +1004,7 @@ function judgeHandoffs(dir, workspace, { write, fail }) {
  * that sweep the layer would accept anything at all and the positive control would only ever examine the
  * ones it already expected.
  */
-function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks }) {
+function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks, remedyFlags = "" }) {
     const declaredPath = workspace.personas?.index?.path;
     if (!declaredPath) return { declared: false, path: null, expected: null };
 
@@ -1064,7 +1114,7 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
     }
 
     const expected = renderScopeIndex(workspace, series);
-    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "scopes", source: "packs this workspace composes", fail });
+    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "scopes", source: "packs this workspace composes", fail, remedyFlags });
 
     // The landing itself, and it happens after the index is written rather than before: if the render
     // could not be derived there is nothing to land, and a directory created for a scope no index

package/cli/inside.mjs

@@ -0,0 +1,38 @@
+// Is one path inside another? One predicate, one file, no dependencies.
+//
+// **It lives alone because two large modules need it and must not import each other.** It began in
+// `./index.mjs`, which `./doctor.mjs` imports; when `./compile.mjs` needed it too, importing it from
+// there would have closed a cycle — `index.mjs` already imports `resolvePack`/`rootPlan` from
+// `compile.mjs`. This repository has paid for a cycle once already: `../docs/plan.md`'s session log
+// records **an import cycle exiting 13 in silence**, and three modules (`./plugin-lint.mjs:1369`,
+// `./skills-set.mjs:48` and `:114`) carry comments explaining that they chose their import direction
+// to avoid making one. Copying the predicate instead was the other option and is the one its own
+// docblock forbids: two copies of this rule drifted into the identical defect before either shipped.
+//
+// So the rule keeps one implementation and gains no edges. `./index.mjs` re-exports it, so every
+// existing importer is untouched.
+//
+// Found by Copilot on the change that closed #264, which had reached for the `index.mjs` export.
+
+import path from "node:path";
+
+/**
+ * Is `child` inside `parent`?
+ *
+ * **The obvious spelling — `!path.relative(parent, child).startsWith("..")` — is wrong, and it fails
+ * OPEN.** A name beginning with `..` is an ordinary filename, not a traversal: `path.relative` of
+ * `memory/..index.md` against `memory/` is `..index.md`, which `startsWith("..")` calls *outside*.
+ * Measured end to end before this was written — an index declared at `memory/..index.md` was written
+ * into the store, reported `ok`, and `doctor` then counted it as a second record. That is the ninth
+ * fail-open found in this repository's scaffolding, and the first one written by the change that
+ * cites the class; `recordedOrigin` in `./compile.mjs` was the second, which is why this moved here.
+ *
+ * Only `..` exactly, or `..` followed by a separator, means outside. An absolute result means the two
+ * paths share no root and cannot contain one another. A path is inside itself.
+ */
+export function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    if (rel === "") return true;
+    if (path.isAbsolute(rel)) return false;
+    return rel !== ".." && !rel.startsWith(`..${path.sep}`);
+}