@sleepy_panda_srl/portulan 0.1.0 → 0.1.2

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}`);
+}

package/cli/pack-identity.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// Every file `npm pack` emits is byte-identical to the tracked blob it came from.
+//
+// The rail [#149](https://github.com/sleepy-panda-srl/portulan/issues/149) asked for, in the form that
+// can actually run on every pull request. `.portulan/identity.md` states the property — **the `npx`
+// path IS an install, and it installs the SAME BYTES** — and until 2026-08-18 nothing checked it: the
+// figure was re-measured by hand three times (72 files, then 114, then 73) and was wrong in the tree
+// twice between those measurements.
+//
+// ## Why this compares against the TREE and not against the registry
+//
+// The measurement taken at the first publish compared the published tarball to a fresh `npm pack`, and
+// they hashed the same. That is the stronger claim and it is recorded on #149 — but it is the wrong
+// shape for a recipe: it needs the network, it needs a published version to exist, and it cannot run
+// before the first publish or on a machine offline. A recipe that cannot run is a recipe that stops
+// being run.
+//
+// What this checks instead needs neither: `npm pack --dry-run --json` lists what the package would
+// contain, and every one of those paths must be byte-identical to its STAGED blob, `git show :<path>`
+// — the index rather than HEAD, for the reason the comment on `blobAt` gives. That is the
+// property the registry comparison DEPENDS on — if the packed bytes match the tree, and the published
+// tarball matches a fresh pack, then the published bytes are the tree's. This rail owns the first half,
+// which is the half that can drift silently on any commit; the second half is a hand measurement taken
+// at each publish, which is what #149 asked for and what its comment records.
+//
+// ## Exit codes, per ../.portulan/memory/verify-preconditions-fail-closed.md
+//
+//   0  every packed file matches its staged blob
+//   1  a finding: at least one packed file differs from what is staged, or is not tracked at all
+//   2  could not run: `npm pack` unusable, not a git repository, or HEAD unreadable
+//
+// The 2 matters more here than in most recipes. `npm pack` shells out to npm, which can be absent,
+// offline-hostile, or a different major version — and a rail that reports "the bytes differ" when what
+// happened is "npm did not run" sends someone hunting a drift that does not exist.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import process from "node:process";
+
+class CannotRun extends Error {}
+
+const run = (cmd, args, opts = {}) => execFileSync(cmd, args, { encoding: "buffer", maxBuffer: 64 * 1024 * 1024, ...opts });
+
+/** What the package would contain, as repo-relative paths. */
+function packedPaths(root) {
+    let out;
+    try {
+        out = run("npm", ["pack", "--dry-run", "--json"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] }).toString("utf8");
+    } catch (error) {
+        throw new CannotRun(`\`npm pack --dry-run --json\` did not run: ${error.message.split("\n")[0]}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    } catch {
+        throw new CannotRun("`npm pack --dry-run --json` printed something that is not JSON");
+    }
+    const files = parsed?.[0]?.files;
+    if (!Array.isArray(files) || files.length === 0) throw new CannotRun("`npm pack` reported no files — refusing to report a green over an empty roster");
+    // The SHAPE is checked, not assumed. `files` is npm's JSON, and a changed schema or an odd entry
+    // would otherwise yield `undefined` paths that crash further down — surfacing as an uncaught
+    // exception the runner reads as a red FINDING about the package. npm's output is an input like any
+    // other; a roster this tool cannot read is could-not-run.
+    const paths = [];
+    for (const [i, entry] of files.entries()) {
+        const rel = entry?.path;
+        if (typeof rel !== "string" || rel.length === 0) {
+            throw new CannotRun(`\`npm pack\` reported an entry at index ${i} with no usable \`path\` — its JSON shape is not what this rail reads`);
+        }
+        paths.push(rel);
+    }
+    return paths;
+}
+
+// The blob is read from the INDEX (`git show :<path>`), not from HEAD, and the difference is the whole
+// usability of this rail. `npm pack` reads the WORKING TREE, so comparing it to HEAD makes the recipe red
+// for any uncommitted edit — and `.portulan/dod.md` requires every recipe green BEFORE a commit, which a
+// check that can only pass after one contradicts. The index is what is about to become the commit, so
+// staged work compares clean and unstaged work is correctly still a difference. In CI the distinction
+// vanishes: `actions/checkout` leaves the index matching HEAD, so this reads exactly as HEAD there.
+/** The staged blob for a path, or null when the path is not tracked. */
+function blobAt(root, rel) {
+    try {
+        return run("git", ["show", `:${rel}`], { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+        return null;
+    }
+}
+
+// Every path npm reports is checked for CONTAINMENT before it is used, by RESOLUTION rather than by
+// pattern — the shape `cli/eval-bundle.mjs` was hardened to on #280, for the same reason: a pattern
+// test answers a question about a string, and what matters is where the filesystem actually goes.
+// `rel` arrives from `npm pack`'s JSON, so it is not this tool's to trust: an absolute path, a `..`
+// escape or an embedded NUL would send both `git show` and the read outside the repository, and the
+// rail would then compare the wrong bytes and report GREEN. Refused as could-not-run, never as a
+// finding — a path this tool will not resolve supports no verdict about the package.
+//
+// Symlinks are refused for the same reason and separately from containment: `readFileSync` follows
+// them, so a link whose target sits outside the tree reads bytes git never carried while `git show`
+// reads the link itself. `lstat` is what distinguishes them, and `realpath` alone would not.
+function containedPath(root, rel) {
+    if (rel.includes("\0")) throw new CannotRun(`npm reported a path containing NUL — refusing to resolve it`);
+    if (path.isAbsolute(rel)) throw new CannotRun(`npm reported an absolute path (${rel}); packed paths are repo-relative`);
+    const resolved = path.resolve(root, rel);
+    const base = path.resolve(root);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new CannotRun(`npm reported a path that resolves outside the repository: ${rel}`);
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(resolved);
+    } catch (error) {
+        throw new CannotRun(`packed path ${rel} could not be stat'd: ${error.message.split("\n")[0]}`);
+    }
+    if (stat.isSymbolicLink()) throw new CannotRun(`packed path ${rel} is a symlink; its target is not what git carries`);
+    if (!stat.isFile()) throw new CannotRun(`packed path ${rel} is not a regular file`);
+    return resolved;
+}
+
+export function compare(root) {
+    try {
+        run("git", ["rev-parse", "--verify", "HEAD"], { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+        throw new CannotRun("not a git repository, or HEAD does not resolve");
+    }
+    const packed = packedPaths(root);
+    const untracked = [];
+    const differing = [];
+    for (const rel of packed) {
+        // `package.json` is the one path npm may rewrite on pack — it normalises fields. Compared like
+        // every other file rather than exempted: the 2026-08-13 measurement asserted all 114 identical
+        // "package.json included, with no exemption", and an exemption added here would quietly retire
+        // that claim.
+        const abs = containedPath(root, rel);
+        const blob = blobAt(root, rel);
+        if (blob === null) untracked.push(rel);
+        // Read with `fs`, not by shelling out. `cat` would be an undeclared dependency this recipe's
+        // `requires` does not list, and it takes its argument as an OPTION when a filename begins with
+        // `-` — so a file named `-n` would silently be read as a flag rather than compared.
+        else if (!blob.equals(fs.readFileSync(abs))) differing.push(rel);
+    }
+    return { packed, untracked, differing };
+}
+
+function main(argv, stdout, stderr) {
+    const root = argv[2] ?? process.cwd();
+    let result;
+    try {
+        result = compare(root);
+    } catch (error) {
+        if (error instanceof CannotRun) {
+            stderr.write(`pack-identity: could not run — ${error.message}\n`);
+            return 2;
+        }
+        // An unexpected throw is COULD-NOT-RUN, never a finding. Rethrowing would exit non-contractually
+        // — node's own code, typically 1 — and the runner would read a crash in this rail as a verdict
+        // about the package's bytes. `1` is reserved for a finding; this repository has a commit by that
+        // name. The diagnostic names the rail so the exit is traceable to the thing that broke.
+        stderr.write(`pack-identity: could not run — unexpected ${error?.name ?? "error"}: ${String(error?.message ?? error).split("\n")[0]}\n`);
+        return 2;
+    }
+    const { packed, untracked, differing } = result;
+    if (untracked.length === 0 && differing.length === 0) {
+        stdout.write(`ok  pack-identity — all ${packed.length} packed file(s) are byte-identical to their staged blob\n`);
+        return 0;
+    }
+    for (const rel of untracked) stderr.write(`pack-identity: ${rel} would ship but is NOT TRACKED — the package would carry a byte nobody reviewed\n`);
+    for (const rel of differing) stderr.write(`pack-identity: ${rel} differs from \`git show :${rel}\` — the package would not install the tree's bytes\n`);
+    stderr.write(`pack-identity: ${untracked.length + differing.length} of ${packed.length} packed file(s) failed; .portulan/identity.md's same-bytes claim does not hold\n`);
+    return 1;
+}
+
+// The same guard `pack-version.mjs` uses. A bare path comparison is FALSE when npm installs a bin as a
+// symlink — node realpaths the main module for `import.meta.url` while `process.argv[1]` keeps the link.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    process.exitCode = main(process.argv, process.stdout, process.stderr);
+}
+export { main };

package/cli/recipe-set.mjs

@@ -61,7 +61,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { resolvePack, rootPlan } from "./compile.mjs";
+// `shadowedCopy` rides along: one carrier for *is this pack shadowed*, per #316.
+import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
 /**
@@ -288,6 +289,46 @@ export function resolverFor({ workspaceDir, manifest, repoRoot = ".", named = []
     if (plan.refusal) throw new Error(`recipe-set: ${plan.refusal}`);
     if (plan.couldNotRun) throw new Error(`recipe-set: ${plan.couldNotRun}`);
     const roots = plan.roots ?? [];
+    const originAt = (r) => (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
+
+    // **A shadowed pack is refused here too** (#318), and this tool's ground is the strongest of the
+    // three. `compile` refuses even an agreeing shadow because its artifact records which root
+    // answered; `index` refuses one although its artifact deliberately does not. Here the answering
+    // root is not merely recorded — **it is spliced into the output**: `${PACK_ROOT}` expands to the
+    // root that answered, so two copies whose manifests are byte-identical still yield different `run`
+    // lines pointing at different files. What CI runs and what a bare local run runs would diverge,
+    // with nothing in either output to say so.
+    //
+    // So the agreeing case is not a carve-out anyone could argue for here, and the honest predicate was
+    // never manifest comparison: it is output equality, computable only by resolving both worlds.
+    // Refusing the ambiguity is what remains.
+    //
+    // **Checked HERE rather than inside the returned closure**, which is where a first cut put it. The
+    // closure runs during `recipeSet`, outside the `try` that wraps this constructor — so the refusal
+    // escaped as an uncaught throw, exit 1 with a stack trace, in a tool whose whole contract is exit 2
+    // for could-not-run. Measured, not reasoned about. Throwing from the constructor puts it on the
+    // path `plan.refusal` already uses and the caller already catches.
+    //
+    // **Only where the caller did not choose** — a named root replaces the derived one, `auto` is
+    // discovery elected — which is `compile`'s guard shape, bound to it deliberately.
+    if (!forced && plan.source !== "named") {
+        const declared = Array.isArray(manifest?.packs) ? manifest.packs : [];
+        for (const ref of declared) {
+            const found = resolvePack(String(ref), roots);
+            if (!found?.dir) continue;
+            // Path-resolved, matching `compile` — see the sibling note in `index.mjs`.
+            const behind = shadowedCopy(String(ref), originAt(found.root), roots, originAt);
+            if (!behind) continue;
+            throw new Error(
+                `recipe-set: \`${ref}\` is SHADOWED — it resolved under ${found.root}, a root discovered on ` +
+                    `this host, while the root ${path.relative(path.resolve(repoRoot), behind.root)} also carries it. ` +
+                    "A composed recipe's ${PACK_ROOT} expands to whichever root answered, so the two compose to " +
+                    "run lines pointing at different files. Refusing to pick: name the root — `--pack-root packs` " +
+                    "for the tree, which is what CI runs, or `--pack-root auto` for the installed copy.",
+            );
+        }
+    }
+
     return (ref) => {
         const found = resolvePack(ref, roots);
         // `resolvePack` returns `manifest` as the PATH to `pack.json`, not as the parsed object —

package/cli/skills-set.mjs

@@ -75,6 +75,33 @@
  *   every manifest in this repository already has. A manifest formatted otherwise is reformatted, and
  *   that is a real cost rather than a hidden one.
  *
+ * ## A pack two roots answer for is refused, not picked
+ *
+ * On a host carrying an installed copy of a composed pack **and** the tree's own, resolution is
+ * discovered-first and first-match-wins, so the installed copy answers. That copy lives outside the
+ * plugin root, containment fails, and this tool concluded the tree's declared skills path belonged to
+ * no composed pack — printing `--write` as the remedy, where `--write` is the mutation that strips a
+ * correct declaration out of a tracked manifest
+ * ([#317](https://github.com/sleepy-panda-srl/portulan/issues/317)).
+ *
+ * So this refuses at RESOLUTION — exit 2 — where `compile` refuses for the same family
+ * ([#316](https://github.com/sleepy-panda-srl/portulan/issues/316)), and for the same reason: the
+ * printer, `--check` and `--write` inherit ONE rule rather than three. Refusing on `--write` alone
+ * would leave `--check` exiting **1**, asserting the *repository* had drifted when it had not — and an
+ * exit code is the machine-read API, so a false 1 is a false verdict about the tree.
+ *
+ * **The predicate is imported, not re-spelled.** `shadowedCopy` and `packDifferences` live in
+ * `./compile.mjs`. That comparison had already been wrong twice in `doctor` before it became one
+ * carrier, and a third copy written inside a fix for its own family is precisely the defect
+ * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` names.
+ *
+ * **Where this tool's reason is SHARPER than `compile`'s, and the message says so.** `compile` refuses
+ * a shadow whose manifests agree because `recordedOrigin` writes the answering root into the artifact,
+ * so agreement in the manifests is not agreement in the bytes. Here agreement is beside the point in a
+ * more direct way: the two copies sit on opposite sides of the plugin root, so which one answers
+ * decides whether this pack contributes a `skills` path **at all**. Version parity does not save it,
+ * which is why this fires on hosts where `compile`'s difference-driven half would have nothing to say.
+ *
  * Zero dependencies, no network, no install step — the same constraints as every tool here.
  */
 
@@ -93,7 +120,7 @@ import { pathToFileURL } from "node:url";
 // root wins outright; otherwise discovery is unioned with the derived root, discovered first** — asking
 // only selects the strict degrade. This tool exited **2** on the ordinary drafted workspace until then,
 // which is what the row's "optional where discovery finds a root" was not.)_
-import { resolvePack, rootPlan } from "./compile.mjs";
+import { packDifferences, recordedOrigin, resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
 /**
@@ -425,6 +452,114 @@ export function declaredFor(set, pluginManifest, pluginRoot) {
     return [...portion.outside, ...set.paths.map((p) => p.path)];
 }
 
+/**
+ * The refusal a shadowed pack earns, or `null` when no declared pack is shadowed.
+ *
+ * Separated from `run` so the sentence a reader gets is testable without a command line, and kept in
+ * this file rather than pushed into `compile.mjs` because the CONSEQUENCE clause is this tool's own:
+ * `compile` talks about emitted policy, and this one talks about whether a `skills` path is derived.
+ * What is shared — *is there a second copy behind the one that answered, and do the two differ* — is
+ * imported, and that split is the point.
+ *
+ * Only the **unasked** path reaches here. `--pack-root <dir>` names a root, which replaces the derived
+ * one and leaves nothing behind it to shadow; `--pack-root auto` is discovery ELECTED, and refusing
+ * somebody for answering the question the refusal asks would be incoherent. Both spellings are offered
+ * in the message for that reason — naming only the tree would make the refusal decide the question it
+ * claims to hand back.
+ */
+export function shadowRefusal({ packs, roots, plan, repoRoot, pluginRoot }) {
+    const originOf = (r) => (plan?.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
+    for (const ref of Array.isArray(packs) ? packs : []) {
+        const found = resolvePack(ref, roots);
+        if (!found?.dir || !found.manifest) continue;
+        const behind = shadowedCopy(found.name, recordedOrigin(found.root, plan, repoRoot), roots, originOf);
+        if (!behind) continue;
+
+        const there = path.relative(repoRoot, behind.root) || behind.root;
+        // **The tree spelling is the root we just named, not the conventional guess.** Both arms below
+        // hard-coded `--pack-root packs`, and the derived root is `path.resolve(workspaceDir, tree,
+        // "packs")` — so a workspace whose `tree` is `../nested/` derives `nested/packs` and was being
+        // told to pass a directory that does not carry the pack. That is this branch's own defect class
+        // one more time: a message prescribing a remedy it had not checked, in the sentence whose whole
+        // job is to hand back an accurate choice. `there` is already the relative spelling of that root,
+        // and for the conventional layout it is exactly `packs`, so the common output is unchanged.
+        //
+        // The `verify/plugin.sh` clause is gated with it, because that rail pins the literal
+        // `--pack-root packs`: claiming the equivalence for `nested/packs` would replace one false
+        // sentence with another. Raised through the promoted suppressed-note channel, which carries
+        // findings the inline round does not.
+        const rail = there === "packs" ? ", which is what `verify/plugin.sh` checks" : "";
+
+        // **Read and parse are two failures with two repairs**, and one sentence for both misdiagnoses
+        // the commoner one — the defect Copilot raised against `run`'s workspace arm on #229, whose
+        // comment sits one screen below this and which the first cut of this block reintroduced
+        // anyway. A `SyntaxError` from `JSON.parse` carries no `.code`, so a collapsed arm reporting
+        // `error.code ?? error.message` under *could not be read* sends somebody with a malformed
+        // manifest to look at permissions. `readManifest` and `resolverFor` both keep the two apart;
+        // so does this. It also names WHICH of the two copies is the broken one, which the collapsed
+        // form could not — with two manifests in play, "one of the two" is half a diagnosis.
+        const load = (file) => {
+            let text;
+            try {
+                text = fs.readFileSync(file, "utf8");
+            } catch (error) {
+                return { why: `could not be read — ${error.code ?? error.message}` };
+            }
+            try {
+                return { value: JSON.parse(text) };
+            } catch (error) {
+                return { why: `does not parse as JSON — ${error.message}` };
+            }
+        };
+        const here = load(found.manifest);
+        const beneath = load(behind.manifest);
+        const broken = here.why ? { at: found.root, why: here.why } : beneath.why ? { at: there, why: beneath.why } : null;
+        if (broken) {
+            // Could-not-run wearing its own sentence rather than the SHADOWED one: with a manifest
+            // unreadable, *what differs* is unanswerable, and a refusal that guessed would be claiming
+            // to have compared two things it could not read. The remedy is the same either way.
+            return (
+                `the pack \`${found.name}\` resolved under the root ${found.root} while the root ${there} also ` +
+                `carries it, and the copy under ${broken.at} ${broken.why} — so which one this would derive ` +
+                `from could not be established. Name the root: \`--pack-root ${there}\` derives from the tree${rail}, ` +
+                "`--pack-root auto` from the installed copy"
+            );
+        }
+        const mine = here.value;
+        const other = beneath.value;
+
+        // **Containment, computed rather than assumed.** The sharp case — one copy inside the plugin
+        // root and one outside — is what makes `--write` destructive, but it is not a law: a
+        // `--plugin-root` pointing elsewhere puts both outside, and the refusal still stands because
+        // the derived path is relative to whichever root answered. Asserting the sharp case
+        // unconditionally would be this message's first lie, in the sentence that exists to be exact.
+        //
+        // Tested against the ROOTS, which is also what `packPortion` partitions on — `resolvePack`
+        // builds `dir` as `<root>/<category>/<pack>`, so the two can never disagree here, and using the
+        // root keeps this predicate spelled the same way as the derivation it is predicting.
+        const differs = packDifferences(mine, other);
+        const split = escapes(pluginRoot, path.resolve(found.root)) !== escapes(pluginRoot, path.resolve(behind.root));
+        // **Both ROOTS by path — the roots, not the pack directories.** The sibling refusal in
+        // `compile` shipped `dir` while calling it a root, which mislabels the thing it names in a
+        // message whose own claim is to name both; the root is also the half a reader types back into
+        // `--pack-root`. Corrected here in the same stroke rather than left to be found twice.
+        return (
+            `the pack \`${found.name}\` is SHADOWED — it resolved under ${found.root}, a root discovered on this ` +
+            `host, while the root ${there} also carries it. ` +
+            (differs.length
+                ? `They differ by ${differs.join(" and ")}, and which root answers decides the derived set anyway: `
+                : "Their manifests agree, and here that changes nothing: ") +
+            (split
+                ? "the two sit on opposite sides of this plugin root, so one of them derives a `skills` path for " +
+                  "this pack and the other derives none — `--write` would act on whichever answered. "
+                : "the two roots derive different `skills` paths, and `--write` would act on whichever answered. ") +
+            `Refusing to pick: name the root instead — \`--pack-root ${there}\` derives from the tree${rail}, ` +
+            "and `--pack-root auto` from the installed copy"
+        );
+    }
+    return null;
+}
+
 /**
  * A resolver over a workspace's declared pack roots.
  *
@@ -545,8 +680,11 @@ function readManifest(file, pluginRoot) {
  * The runnable surface: the printer CI and an adopter's own pipeline call, plus `--check` and
  * `--write`.
  *
- * `options.manifest` and `options.resolve` are injection points for the suite, the way `init` injects
- * its reader. No production caller passes either; every flag below is the real surface.
+ * `options.manifest`, `options.resolve` and `options.discovery` are injection points for the suite, the
+ * way `init` injects its reader. No production caller passes any of them; every flag below is the real
+ * surface. `discovery` is injected as a THUNK like the production one, because the guarantee that a
+ * branch which cannot use the answer never touches the host is a property of the ARGUMENT — a suite
+ * handed a pre-computed value would be testing a shape production never takes.
  */
 export function run(argv = [], options = {}) {
     const { stdout = process.stdout, stderr = process.stderr } = options;
@@ -623,7 +761,7 @@ export function run(argv = [], options = {}) {
         // caller wiring no thunk stays hermetic on every arm.)_
         const plan = rootPlan(workspaceDir, manifest, {
             named: namedRoots,
-            discovery: () => discoverPackRoots(),
+            discovery: options.discovery ?? (() => discoverPackRoots()),
             forced: wantsDiscovery,
         });
         if (plan.refusal || plan.couldNotRun) {
@@ -631,6 +769,30 @@ export function run(argv = [], options = {}) {
             return 2;
         }
         const roots = plan.roots ?? [];
+        // **Refused here, above the mode branches, so the printer, `--check` and `--write` inherit one
+        // rule** (#317). The damage this prevents is specific to the write path — the tool printed
+        // `run with --write` while `--write` would have stripped a correct, tracked `skills` entry on
+        // the strength of what happens to be installed on the machine — but guarding only `--write`
+        // would leave `--check` exiting 1 about a repository that had not drifted, which is a false
+        // verdict handed to a machine. `compile` settled the same question the same way for #316.
+        //
+        // A caller that injected its own `resolve` never reaches this, and that is deliberate rather
+        // than a hole: it chose its own roots, which is the same election `--pack-root` makes.
+        //
+        // **The `named` half of this condition is defence in depth, and it was measured HERE rather
+        // than inherited from `compile`'s note.** Forcing the whole condition to `true` reds exactly
+        // one case — the `--pack-root auto` exemption — while the named-root case goes on passing: a
+        // named root REPLACES the derived one, so the plan carries no discovered root, `shadowedCopy`
+        // finds nothing behind it, and there is no shadow to refuse. The protection is structural, and
+        // no test in this suite binds the clause. It stays because it states the intent at the site
+        // where a future change to `resolutionRoots` could quietly make it load-bearing.
+        if (!wantsDiscovery && plan.source !== "named") {
+            const shadowed = shadowRefusal({ packs: manifest?.packs, roots, plan, repoRoot, pluginRoot });
+            if (shadowed) {
+                stderr.write(`skills-set: ${shadowed}\n`);
+                return 2;
+            }
+        }
         resolve = resolverFor({ workspaceDir, manifest, roots });
         // The same roots stand in as the owned set when nothing resolves — so a workspace that has
         // stopped composing gets its stale entries cleaned wherever its packs WOULD have been, not