@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/cli/discover.mjs

@@ -1,189 +1,39 @@
 #!/usr/bin/env node
-// Host plugin-cache discovery — reading a host's installed-plugin record so a POINTER can be
-// resolved to the workspace it names.
-//
-// Row 7 of `../docs/plan.md` owns this, by the amendment of 2026-08-03: *"reading a host's
-// installed-plugin record to resolve an installed workspace or pack, resolving a pointer's
-// `governed_by` to the workspace it names (a cache hit, or the honest not installed here
-// sentence)"*. The same amendment fixes where the answer is produced and where it is merely
-// reported: **the boot is a skill, and real resolution stays the CLI's.** So this file resolves and
-// `../plugin/skills/portulan/SKILL.md` reports what it says.
-//
-// ## What this closes, and what it deliberately leaves open
-//
-// [#134](https://github.com/sleepy-panda-srl/portulan/issues/134)'s boot half: a workspace
-// delivered by a private feed was invisible to `/portulan`, because the boot looked at exactly one
-// path and nothing anywhere resolved `governed_by`. The pointer kind landed at Workspace Definition
-// 2.7 with proposal `0017` and named the governing workspace; nothing dereferenced the name.
-//
-// **`--pack-root` IS wired to this file**, and this paragraph said the opposite until 2026-08-12. It
-// read *"`--pack-root` is NOT wired to this file … nothing here adds a root at all"*, which was true
-// when written and stopped being true at milestone 7 session 4, when
-// [#123](https://github.com/sleepy-panda-srl/portulan/issues/123)'s half landed `resolutionRoots`
-// here — a stale sentence that survived a session because the change that falsified it added a
-// function below rather than editing the header above it. Corrected in the same stroke as the union,
-// whose whole subject is a rule with more carriers than its author remembered.
-//
-// #117's property is the one to keep hold of while reading the rest: **a NAMED root replaces the
-// `tree`-derived one**, so *"this pack resolved from the feed"* cannot be satisfied by a copy lying in
-// the local tree. That half is untouched. The row states the direction discovery takes: it **adds a
-// root only where none was named**, and never replaces one that was — and since 2026-08-12 the
-// implementation takes that verb literally, which is what `resolutionRoots`' own docblock argues.
-// **On 2026-08-13 it began taking the row's OTHER verb literally too** — *`--pack-root` and its
-// siblings are optional where discovery finds a root* — so the unasked arm consults a wired thunk
-// as well. `resolutionRoots`' docblock carries the ruling, the asymmetry between the two arms, and
-// what now holds the boundary the old narrowing was standing in for.
-//
-// ## Four states, because three of them are not "no"
-//
-// A resolver with two answers is the fail-open this repository keeps minting rules about
-// (`../.portulan/memory/verify-preconditions-fail-closed.md`): *could not look* must never read as
-// *nothing wrong*, and *two candidates* must never read as *this one*.
-//
-//   `resolved`       exactly one installed plugin carries a workspace manifest whose `name` is the
-//                    one the pointer asks for. The root is the directory that manifest sits in.
-//   `not-installed`  nothing on this host carries it — including the case where the host has no
-//                    installed-plugin record at all, which is a host with nothing installed.
-//   `ambiguous`      two or more distinct roots answer to the name. REFUSED, both named. Picking one
-//                    would be booting on a workspace the project did not ask for while looking
-//                    exactly like success, which is the failure the boot skill's step 2 exists for.
-//   `could-not-look` the record is there and could not be read or parsed. Never reported as absence.
-//
-// ## What it matches on, and why that is the manifest rather than the plugin
-//
-// A pointer names a **workspace**, by the `name` the governing workspace's own manifest carries —
-// `spec/workspace.schema.json` says so of `governed_by.workspace`, on the same slug definition, "so
-// a pointer and its target cannot drift into different spellings of one identifier". A plugin name
-// is a different identifier in a different namespace, and the two agreeing on this machine today is
-// a coincidence of naming rather than a contract. So every candidate's `workspace.json` is read and
-// its `name` compared. A cache hit is a hit on the manifest.
-//
-// ## Three limits, stated rather than left to be found
-//
-//  1. **Two candidate locations per plugin, named.** `<installPath>/workspace.json` and
-//     `<installPath>/.portulan/workspace.json` — the payload that IS a workspace, and the payload
-//     that is a repository carrying one. A recursive walk would find more and would be the matcher
-//     clever enough to be wrong quietly that `../.portulan/gate-map.md` refuses elsewhere; a limit a
-//     reader can measure is worth more here than reach.
-//  2. **Nothing is fetched.** No network call, ever — not by this file and not by anything it is
-//     wired into. A workspace that is not installed is not installed, and the row puts feed
-//     authentication and discovery of the uninstalled explicitly out of scope.
-//  3. **A resolved workspace is not a graded workspace.** This says where it is. Whether it is green
-//     is `doctor`'s answer about THAT directory, and running it is the caller's business.
-//
-// ## It is also runnable, and that is a seam rather than a convenience
+// Host plugin-cache discovery: reads a host's installed-plugin record to resolve a pointer and find pack roots.
 //
 //   node cli/discover.mjs [--json] <workspace-dir>
 //
-// The boot skill has to get a DIRECTORY out of this, and the only other route was reading `doctor`'s
-// prose — a sentence this very change rewrites, parsed by an agent, with no field to key on. So there
-// is a surface, and `--json` is the machine-readable half of it.
-//
-// **This is not a ninth `portulan` subcommand.** `docs/vision.md` names eight and is human-owned;
-// `plugin-lint` and `librarian` are the standing precedent for a tool that lives in `cli/`, runs as
-// `node cli/<tool>.mjs`, and is deliberately absent from `./portulan.mjs`'s list. Whether this ever
-// joins that list is the maintainer's call, exactly as theirs is.
-//
-// Exit codes are the three this repository uses everywhere: **0** resolved — **and also
-// `resides-here`**, the answer for a manifest that is not a pointer at all · **1** a verdict that the
-// workspace is not resolvable here (`not-installed`, `ambiguous`) · **2** could not run or could not
-// look. The split matters at the one place it is read: *could not look* must never be spendable as
-// *not installed*.
-//
-// **`state` is the field to key on, not the code.** Two states share exit 0 and no exit code can tell
-// them apart — that is the cost of answering the question for both kinds of manifest rather than
-// pushing the case analysis back onto the caller, and it is a cost rather than a defect. _(This
-// paragraph said "**0** resolved" alone until #182 item 3: a sentence narrower than the code it
-// described, committed in the same change that corrected that exact shape in eleven other carriers.
-// Copilot, round 4 on #181.)_
-//
-// Zero dependencies, Node built-ins only, and every environment input injectable — the host config
-// directory is read from `env`, so a test never depends on the machine it runs on.
+// Exit 0 resolved or resides-here · 1 not-installed or ambiguous · 2 could not run or could not look.
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-/** The plugin-record filename and its directory, both the host's rather than ours. */
 export const RECORD = path.join("plugins", "installed_plugins.json");
 
-/**
- * The record schema versions this reader claims to understand. Measured: `2` on Claude Code 2.1.226.
- *
- * Exported because it is a limit, and because refusing an unrecognised version is a **decision** rather
- * than an oversight. The file belongs to the host, not to us: a later version may move `installPath`,
- * rename it, or nest it, and a reader that parsed on regardless would report roots that are not roots —
- * a confident wrong answer, which is the class this module's four states exist to prevent. So an
- * unknown version is `unreadable`, which reaches a caller as **could-not-look** and never as
- * *not installed*.
- *
- * The cost is stated rather than hidden: on the day the host bumps to `3`, discovery stops here until
- * this set is widened by someone who has looked. That is the direction
- * `../.portulan/memory/a-checker-must-refuse-what-it-cannot-check.md` requires, and the opposite
- * failure — silently resolving against a shape nobody verified — is the one that cannot be noticed.
- *
- * _(Raised by the session building `--pack-root auto` on #183, which had the guard on its own reader and
- * flagged its absence here before the two modules were reconciled. Verified against the live record
- * rather than accepted: it carries `"version": 2`.)_
- */
+/** Claude Code 2.1.226 writes record version `2`; a version not listed here reads as `unreadable`. */
 export const RECORD_VERSIONS = new Set([2]);
 
-/**
- * Where a candidate plugin payload may carry a workspace manifest, in the order tried.
- *
- * Exported because it is a limit, and a limit nobody can enumerate is a limit nobody can check —
- * the suite asserts this list rather than restating it.
- */
 export const MANIFEST_AT = ["workspace.json", path.join(".portulan", "workspace.json")];
 
-/**
- * The host's configuration directory.
- *
- * `CLAUDE_CONFIG_DIR` overrides it — that is the host's documented escape hatch and it is the reason
- * this takes an `env` at all rather than reading `process.env` at the point of use. An empty string
- * is treated as unset: an exported-but-blank variable is a shell accident, and honouring it would
- * point discovery at **the process's working directory**, since `path.resolve("")` is `cwd` and not
- * `/` — a plausible-looking answer to a question nobody asked, and worse than an obvious one because
- * it changes with where the tool was invoked from.
- *
- * _(This said "the filesystem root" until #182's round, which is wrong about `path.resolve` and was
- * contradicted by this function's own test one file away — the same two-carriers-one-fact shape this
- * change corrected in eleven other places, here in the docblock of the guard the fix cites as its
- * precedent. Copilot, on the round reviewing the records.)_
- */
+/** A blank `CLAUDE_CONFIG_DIR` is unset: `path.resolve("")` would answer the working directory. */
 export function configDir({ env = process.env, home = os.homedir() } = {}) {
     const named = env.CLAUDE_CONFIG_DIR;
     if (typeof named === "string" && named.trim() !== "") return path.resolve(named);
     return path.join(home, ".claude");
 }
 
-/** The installed-plugin record's path for a host. */
 export function recordPath(options = {}) {
     return path.join(configDir(options), RECORD);
 }
 
-/**
- * Read the host's installed-plugin record.
- *
- * Returns `{ state, path, entries, detail }` where `state` is one of `read` · `absent` ·
- * `unreadable`. The three are kept apart at the source because collapsing them is exactly how a
- * resolver starts answering "not installed" to a question it never asked.
- *
- * `entries` is flat — the record maps `<plugin>@<marketplace>` to an ARRAY, one per install scope,
- * and a caller reasoning about roots wants the installs rather than the grouping. Malformed
- * individual entries are dropped rather than taking the whole read down: one plugin's bad record
- * should not blind discovery to every other plugin on the host.
- */
 export function readInstalls(options = {}) {
     const file = recordPath(options);
     let raw;
     try {
         raw = fs.readFileSync(file, "utf8");
     } catch (cause) {
-        // ENOENT is a host with nothing installed — or no host at all, which is CI. Every other
-        // errno is a file that exists and would not open, which is a different fact and gets a
-        // different word.
         if (cause.code === "ENOENT") return { state: "absent", path: file, entries: [], detail: null };
         return { state: "unreadable", path: file, entries: [], detail: cause.code ?? cause.message };
     }
@@ -193,18 +43,9 @@ export function readInstalls(options = {}) {
     } catch (cause) {
         return { state: "unreadable", path: file, entries: [], detail: `not JSON — ${cause.message}` };
     }
-    // `Array.isArray` is checked on BOTH the record and its `plugins`, and the second was missing — the
-    // sibling of a guard sitting one clause away. `typeof [] === "object"`, so `{"plugins": []}` read as
-    // a healthy record with nothing installed, and a malformed file collapsed into `not-installed`:
-    // *could not look* spent as absence, which is the one thing this file's four states exist to prevent.
-    // Found by Copilot, round 2, in a function whose own docblock argues that the three read states are
-    // kept apart at the source.
     if (record === null || typeof record !== "object" || Array.isArray(record) || typeof record.plugins !== "object" || record.plugins === null || Array.isArray(record.plugins)) {
         return { state: "unreadable", path: file, entries: [], detail: "no `plugins` object — this is not an installed-plugin record" };
     }
-    // The version is checked BEFORE the entries are read, because it is the claim that makes reading them
-    // meaningful: `installPath` means what it means in version 2, and this reader has only ever seen
-    // version 2. Refused rather than parsed hopefully — see RECORD_VERSIONS for the argument and its cost.
     if (!RECORD_VERSIONS.has(record.version)) {
         return {
             state: "unreadable",
@@ -239,28 +80,6 @@ export function readInstalls(options = {}) {
     return { state: "read", path: file, entries, detail: null };
 }
 
-/**
- * Read a candidate manifest, returning `{ manifest, name, kind }` or `null`.
- *
- * Unreadable and unparseable are both `null` and both deliberate: a plugin payload carrying
- * something that is not a workspace manifest at one of the two named paths is simply not a
- * candidate, and a resolver that failed loudly on every unrelated `workspace.json` on the host would
- * be unusable. What it must never do is COUNT such a file as a match, and returning `null` is that.
- *
- * **`name` alone is not enough to say a file is a workspace manifest, and requiring only `name` was a
- * fail-open.** Found at the pre-commit checkpoint by building it rather than by reading this
- * function: a plugin payload carrying an Nx-style `workspace.json` — `{"version": 2, "name": "…",
- * "projects": {…}}`, no `portulan` key, no `kind` — resolved, exit 0, and the boot would have been
- * pointed at it. `workspace.json` is a common filename in the wider ecosystem, so that is an ordinary
- * file rather than a contrived one, and the docblock above already promised it was not a candidate.
- *
- * The gate is `portulan` **and** `name`, which is the Workspace Definition's required identity minus
- * `kind` — `kind` is read here for the pointer refusal and is not required, because a manifest
- * missing it is schema-invalid and that is `doctor`'s verdict about the directory rather than
- * discovery's. **This is deliberately not a second schema validator**: it is the cheapest test that
- * distinguishes *a Portulan workspace manifest* from *a file that happens to share the name*, and
- * conformance stays the one tool that owns it.
- */
 function readCandidate(root) {
     for (const rel of MANIFEST_AT) {
         const file = path.join(root, rel);
@@ -272,11 +91,7 @@ function readCandidate(root) {
         }
         if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
         if (typeof parsed.name !== "string") continue;
-        // `portulan.spec`, not merely a `portulan` key. An empty object satisfied the first cut of this
-        // gate, so a non-Portulan file could still qualify by carrying one — the same fail-open one
-        // tightening later (Copilot, round 2). `spec` is what the Workspace Definition REQUIRES of the
-        // block, so this keys on the contract rather than on a key's presence; the pattern is left to
-        // `doctor`, which owns conformance.
+        // `workspace.json` is a common filename in other tools; `portulan.spec` is what marks a Portulan one.
         if (parsed.portulan === null || typeof parsed.portulan !== "object" || Array.isArray(parsed.portulan)) continue;
         if (typeof parsed.portulan.spec !== "string") continue;
         return { manifest: file, dir: path.dirname(file), name: parsed.name, kind: typeof parsed.kind === "string" ? parsed.kind : null };
@@ -284,43 +99,8 @@ function readCandidate(root) {
     return null;
 }
 
-/**
- * Resolve a pointer's `governed_by` against a host's plugin cache.
- *
- * `governedBy` is the manifest's own object — `{ workspace, feed }`. `feed`, where present,
- * CONSTRAINS: it names the marketplace the workspace ships through, and an install from a different
- * marketplace is not the thing the pointer asked for however well its name matches. That near miss
- * is reported rather than swallowed, because "the right name from the wrong feed" is a diagnosis a
- * reader needs and an absence sentence would hide.
- *
- * Returns a verdict carrying its own `sentence` — one carrier, so every surface that reports this
- * prints the same words rather than paraphrasing them into four slightly different claims.
- */
 export function resolveGovernor(governedBy, options = {}) {
-    // **Blank is unset on both, which is `configDir()`'s rule applied at a second site of the same
-    // operation** — and blank-testing is the whole of it: the value that survives is the RAW one, never
-    // a trimmed copy.
-    //
-    // The two halves are different classes and the difference is worth stating, because a fix that
-    // flattened them would be claiming to close more than it does. `governed_by.feed` is
-    // `type: string, minLength: 1` in the Workspace Definition and nothing more, so `"   "` **validates**
-    // — it constrained every candidate to a marketplace of that name, matched nothing, and answered
-    // `not-installed` about a workspace that is installed, which is the real defect and the class the
-    // four verdicts exist to prevent. `governed_by.workspace` is a `slug`, so `"   "` is
-    // **schema-invalid** and `doctor` refuses it before anything reaches here: that half is
-    // defence-in-depth on this file's own runnable seam rather than a hole in the schema.
-    //
-    // **Not trimmed, deliberately, and the reason is a measurement.** Trimming only the wanted side makes
-    // `" sleepy-panda "` in a pointer match `sleepy-panda` on disk while the same padding ON DISK still
-    // misses — a new asymmetry, and discovery quietly repairing a manifest the slug pattern refuses,
-    // which `readCandidate` above promises it is not doing. `configDir()` blank-tests and hands
-    // `path.resolve` the raw string for the same reason; normalising identifiers is conformance's job and
-    // conformance is `doctor`'s. Found at the pre-commit checkpoint, which built the padded case rather
-    // than reading the diff — the first draft here trimmed, and turned a `resolved` into a
-    // `not-installed`.
-    //
-    // Copilot, #181 rounds 3 and 4; filed as #182 item 1 at the bound and taken here on the maintainer's
-    // grant of an extension, recorded in this pull request's own conversation.
+    // Blank is unset, but padding is kept: normalising a slug is conformance, and conformance is `doctor`'s.
     const named = (value) => (typeof value === "string" && value.trim() !== "" ? value : null);
     const wanted = {
         workspace: named(governedBy?.workspace),
@@ -341,9 +121,6 @@ export function resolveGovernor(governedBy, options = {}) {
     });
 
     if (wanted.workspace === null) {
-        // A pointer with no `governed_by.workspace` is refused by `doctor` and by the schema before
-        // anything reaches here. Guarded anyway: a resolver asked to find "undefined" must say what
-        // it was asked rather than search for it.
         return verdict("could-not-look", {
             sentence: "this pointer names no governing workspace, so there is nothing to resolve — `governed_by.workspace` is required of a pointer",
         });
@@ -380,17 +157,13 @@ export function resolveGovernor(governedBy, options = {}) {
             continue;
         }
         if (found.kind === "pointer") {
-            // A pointer resolving to a pointer is a chain, and the residence ruling permits none: a
-            // repository is governed by exactly one workspace. Refused as a near miss rather than
-            // silently skipped, because the reader needs to know the name WAS found.
             nearMisses.push({ ...candidate, why: "pointer" });
             continue;
         }
         matches.push(candidate);
     }
 
-    // Distinct roots, because one workspace installed at two scopes is two record entries and one
-    // directory, and refusing that would be refusing the ordinary case.
+    // One workspace installed at two scopes is two entries and one root, not an ambiguity.
     const roots = [...new Set(matches.map((m) => m.root))];
     if (roots.length > 1) {
         return verdict("ambiguous", {
@@ -431,11 +204,6 @@ export function resolveGovernor(governedBy, options = {}) {
                       .map((m) =>
                           m.why === "feed"
                               ? `\`${m.key}\` carries that name and ships through ${
-                                    // `marketplace` is null wherever the record key carries no `@` — a shape
-                                    // `readInstalls` tolerates on purpose, so the sentence has to survive it.
-                                    // It printed "ships through `null`", which reads as a marketplace called
-                                    // null rather than as one nobody recorded. Copilot, on the round that
-                                    // reviewed the fix; the same class as the note beside it.
                                     m.marketplace === null ? "no marketplace the record names" : `\`${m.marketplace}\``
                                 }, which is not the feed \`${wanted.feed}\` this pointer names`
                               : `\`${m.key}\` carries that name and is itself a pointer, and a repository is governed by exactly one workspace`,
@@ -450,36 +218,14 @@ export function resolveGovernor(governedBy, options = {}) {
 // The command — the seam the boot skill reads
 // ===========================================================================================
 
-/**
- * Which exit code each verdict carries. Exported so the suite asserts the mapping rather than a literal.
- *
- * **This maps the RESOLVER's four states, and `run()` carries a fifth answer of its own.** A directory
- * whose manifest is not a pointer is answered `resides-here` and exits **0** without consulting this
- * table — so exit 0 does not identify a state, and `state` is the field a caller keys on. Said here
- * rather than left implicit, because a table named `EXIT` with four entries reads as the whole contract
- * (#182 item 3).
- */
+/** The resolver's verdicts; `run()` also exits 0 on `resides-here`, so a caller keys on `state`. */
 export const EXIT = { resolved: 0, "not-installed": 1, ambiguous: 1, "could-not-look": 2 };
 
-/**
- * Resolve the pointer at `<workspace-dir>/workspace.json` and print the answer.
- *
- * The argument is a **workspace directory**, the same thing `doctor` takes, so a caller holding one
- * path can hand it to either tool. A directory carrying a governing manifest is not an error and not
- * a resolution: it is answered as *this repository's workspace resides here*, exit 0, because the
- * question "where is the workspace that governs this" has a true answer for both kinds and a tool
- * that only understood one of them would push the case analysis back onto its caller.
- */
 export function run(argv, options = {}) {
     const say = options.say ?? ((line) => process.stdout.write(`${line}\n`));
     const warn = options.warn ?? ((line) => process.stderr.write(`${line}\n`));
     const json = argv.includes("--json");
     const dirs = argv.filter((a) => !a.startsWith("-"));
-    // An unknown flag is REFUSED rather than dropped, and this is the boot's contract rather than
-    // tidiness: `--jsonn <ptr>` used to print prose and exit 0, so a typo — or a later rename of this
-    // flag — silently degraded the machine-readable answer into the half the skill is told never to
-    // read, with a success code on top. `./doctor.mjs` already guards leading-`-` arguments; found at
-    // the pre-commit checkpoint by typing the typo rather than by reading the filter.
     const KNOWN = new Set(["--json", "--help", "-h"]);
     const unknown = argv.filter((a) => a.startsWith("-") && !KNOWN.has(a));
     if (unknown.length) {
@@ -510,9 +256,6 @@ export function run(argv, options = {}) {
         return 2;
     }
     if (manifest?.kind !== "pointer") {
-        // Answered rather than refused, and the shape is the same object so a caller keys on `state`
-        // either way. `resides-here` is not one of the resolver's four: those are answers about a
-        // HOST, and this is an answer about the argument.
         const verdict = {
             state: "resides-here",
             root: path.dirname(manifestPath),
@@ -533,46 +276,10 @@ export function run(argv, options = {}) {
 // ===========================================================================================
 // Pack-resolution roots
 // ===========================================================================================
-//
-// The second half of row 7's discovery clause (#123). Everything above resolves a WORKSPACE by name,
-// which is what a pointer needs; this resolves the roots a declared PACK is looked up under, which is
-// what `--pack-root` needed a value for.
-//
-// It is built on `readInstalls` above rather than on a second reader — the two halves landed as
-// separate pull requests (#181 and #183) and each shipped its own record reader, which is the
-// three-tools-two-semantics defect `../cli/compile.mjs`'s `namedRootsOption` records. Reconciled on
-// merge: the reader, the config directory and the record-version refusal are this file's, once.
 
-/**
- * The value of `--pack-root` that means *discover it*, rather than naming a directory.
- *
- * Matched against the **raw argument, before any path resolution**, so a directory genuinely called
- * `auto` stays reachable as `./auto` or by an absolute path. A keyword in a value space that until now
- * held only paths is a spelling whose meaning this change flips, so the escape is stated in the help
- * text everywhere, and in the missing-value error of the three tools that resolve roots themselves
- * (`compile`, `doctor`, `index`). `init` and `vendor` forward roots rather than resolving them and
- * carry it in their usage text only — narrower than "every parse error", which is what this sentence
- * said until a checkpoint checked it.
- */
+/** Matched against the raw `--pack-root` value, so a directory named `auto` is reached as `./auto`. */
 export const AUTO = "auto";
 
-/**
- * Is this directory a pack-resolution root — does it hold `<category>/<name>/pack.json`?
- *
- * Asking the RESOLVER's own question rather than looking for a directory named `packs` is what makes
- * this work on both shapes a plugin lands in, and the first version of this function did not:
- *
- * - **Repository-shaped** — the plugin IS a repository checkout (`source: "./"`), so its packs sit
- *   under `<installPath>/packs`. The engine plugin is this shape.
- * - **Flat** — the plugin ships a pack family directly, so the CATEGORIES are at the install root:
- *   `<installPath>/rituals/checkpoints/pack.json`. `portulan-checkpoints@portulan-internal` is this
- *   shape, and it is the pack this project's own workspace composes.
- *
- * Probing only the first meant discovery could not see either plugin the private feed actually ships,
- * with a green suite throughout, because the fixtures encoded the same assumption as the code. Found
- * by a pre-commit checkpoint that looked at a real install — `.portulan/memory/`'s standing lesson:
- * a harness you write to check your own change inherits your blind spot.
- */
 export function isPackRoot(dir) {
     let categories;
     try {
@@ -596,53 +303,8 @@ export function isPackRoot(dir) {
     return false;
 }
 
-/**
- * Pack-resolution roots discovered from the host's plugin cache.
- *
- * Returns `{ ok, roots, installs, why }`. `ok: false` is **could not look** — the record is there and
- * could not be read — and is never the same answer as `ok: true` with no roots, which is *looked,
- * found nothing installed that carries packs*.
- *
- * ## An ABSENT record is `ok: true`, and this line was the opposite until 2026-08-13
- *
- * `readInstalls` keeps three states apart at the source — `read`, `absent`, `unreadable` — and its
- * docblock says collapsing them is how a resolver starts lying. **This function then collapsed two of
- * them**, mapping `absent` to could-not-look from the day this function was written (2026-08-09) to
- * 2026-08-13 — four days, not the "year of sessions" an earlier draft of this paragraph claimed, which
- * was a superlative nobody counted in a file about answers nobody measured. The docblock above
- * described the collapse as though it were the design.
- *
- * It is not a style question, and the measurement is what settles it. A host with **no record at all**
- * is a host with nothing installed — which is every CI runner, and precisely what
- * `readInstalls`'s own comment above says `absent` means. Reported as could-not-look it made
- * `--pack-root auto` return the **empty set**, and an empty set makes `doctor` report every declared
- * pack *unverifiable* and exit **0**. Measured on the workspace `init` drafts by default: with no
- * flag, exit 1 and the cache pack correctly FAILS; with `--pack-root auto`, exit **0** and neither
- * pack is looked at — including one that resolves perfectly well from the adopter's own tree. The flag
- * did not merely fail to help, it **discarded a root it already had** and converted a correct red into
- * a green.
- *
- * The target behaviour was already in the table: a host with a **valid record and nothing installed**
- * has always done the right thing here. `absent` now joins it, and **this module already said so in
- * two other places** — `readInstalls`'s ENOENT comment, and the pointer path below, which has always
- * turned `absent` into a `not-installed` VERDICT ("nothing is installed for it to be among") rather
- * than a could-not-look. `./plugin-lint.mjs` states the general rule: *"Absent counts as
- * examined … that IS the finding."* `discoverPackRoots` was the outlier inside its own file.
- *
- * **The distinction that keeps this from contradicting the fail-closed rule:** a *dependency the check
- * needs* being missing is could-not-run — that is `../.portulan/memory/verify-preconditions-fail-closed.md`'s
- * subject, and why a missing tool still exits 2. A *world-state the check observes* being empty is an
- * answer. The plugin record is the second kind: discovery's whole question is "what is installed
- * here", and "nothing" answers it.
- *
- * Both shapes are offered per install, repository-shaped first; `resolvePack` is first-match-wins, and
- * no plugin carries both.
- */
 export function discoverPackRoots(options = {}) {
     const read = readInstalls(options);
-    // Absent is an ANSWER: nothing is installed. Only a record that is there and will not be read is
-    // could-not-look, and that one keeps `ok: false` — asking for discovery and being unable to look
-    // must never be spendable as a green.
     if (read.state === "absent") {
         return {
             ok: true,
@@ -662,6 +324,7 @@ export function discoverPackRoots(options = {}) {
     const roots = [];
     const contributing = [];
     for (const install of read.entries) {
+        // A repository-shaped plugin keeps its packs under `packs/`; a flat pack family is a root itself.
         for (const candidate of [path.join(install.installPath, "packs"), install.installPath]) {
             if (!isPackRoot(candidate)) continue;
             roots.push(candidate);
@@ -671,167 +334,25 @@ export function discoverPackRoots(options = {}) {
     return { ok: true, roots, installs: contributing, why: null };
 }
 
-/**
- * The one sentence every tool prints when a caller asks for both a named root and `auto`.
- *
- * A constant because **seven** commands reach this refusal — `compile`, `doctor`, `index`, `init`,
- * `vendor`, `skills-set` and, since 2026-08-13, `recipe-set` — and seven spellings of it is how one of
- * them ends up wording it as a warning, which is the silent drop it replaces wearing a different coat.
- * _(It said "five" until `recipe-set` gained the flag; six was already wrong.)_
- */
 export const NAMED_WITH_AUTO =
     "name roots or ask for `auto`, never both: `--pack-root auto` cannot be combined with a named root";
 
-/**
- * The refusal's CONDITION, exported so an argument parser and the resolver share one, not two.
- *
- * Each command must refuse at parse time — that is where an exit 2 belongs, before a workspace is
- * read — while `resolutionRoots` must refuse for API callers that never parsed anything. Two places
- * have to ask, so the thing they ask is a function rather than a repeated `&&`.
- *
- * Returns the sentence to print, or `null` when the combination was not asked for.
- */
+/** The refusal to print, or `null` unless both a named root and `auto` were asked for. */
 export function namedWithAuto(named = [], forced = false) {
-    // Takes the array a parser has or the boolean a resolver has, because the two callers genuinely
-    // hold different shapes of the same fact and the alternative was worse: the first cut passed a
-    // one-element array containing a SENTINEL STRING so an explicitly-empty named set would trip this.
-    // That put a fake root in a predicate about roots, and made the refusal say "a named root" about a
-    // set that had none. Raised by Copilot, round 1 on #233.
     const given = Array.isArray(named) ? named.length > 0 : Boolean(named);
     return given && forced ? NAMED_WITH_AUTO : null;
 }
 
-/**
- * Apply the precedence rule to the sources of a pack-resolution root.
- *
- * ## A named root wins outright; asked-for discovery ADDS
- *
- * Two ratified texts describe this and use the verb "add" for different objects, which reads as a
- * contradiction until the objects are named:
- *
- * - **The row** (`docs/plan.md` row 7): *"an explicitly named root is never silently overridden —
- *   discovery adds a root only where none was named"*. The object is a **named** root; discovery
- *   loses to `--pack-root`, and that half has never moved.
- * - **#123's closing constraint:** *"Discovery that silently adds roots would reintroduce exactly the
- *   substitution the pre-commit checkpoint caught."* The object is the **`tree`-derived** root, and
- *   the operative word in it is **silently**.
- *
- * **The rule is: named > (discovered ∪ derived), discovered first.** It was *named > discovered >
- * derived, never union* until 2026-08-12, and what changed it was a measurement rather than a
- * preference — see below. The order inside the union is load-bearing and not cosmetic:
- * `resolvePack` is first-match-wins, so where both carry a pack the **discovered** copy wins, which
- * keeps every result the old `auto` produced as a subset of this one and keeps the pin meaningful.
- *
- * ## What forced the change: the ordinary workspace could not go green
- *
- * A workspace composing a cache-installed pack **and** one of its own — which is what `init` produces
- * by default the moment an adopter adds a pack, since it composes `rituals/checkpoints` — had **no
- * green invocation** that did not require typing the host plugin-cache path by hand. Measured
- * 2026-08-12 across all four arrangements: no flag reds on the cache pack, `auto` reds on the
- * adopter's own, `auto` plus a named root reds on the cache pack because named replaces both, and
- * only two named roots — one of them a cache path nobody should have to know — went green. That
- * falsified this docblock's own claim that the narrowing survived *"where it matters — nobody has to
- * know the cache path"*. For that shape, somebody had to.
- *
- * ## What the union costs, said plainly because the first framing of it did not
- *
- * The replaced rule had **two** grounds and only the first was surfaced when the change was proposed.
- *
- * 1. **The unasked path must not read the host.** An earlier draft gave a discovered root, unasked, to
- *    a workspace deriving none. A pre-commit checkpoint priced it: `examples/workspace.json` declares
- *    packs and no `tree`, and `.portulan/verify/doctor.sh` grades `examples`, so that branch made a
- *    **required recipe** read `~/.claude` on every run — red locally, green in CI. **Untouched here by
- *    construction:** the union lives inside the `forced` branch, so nothing changes when nobody asks.
- * 2. **A structural provenance guarantee, now traded.** Under the old rule the resolution set held no
- *    tree-derived root under `auto`, so *"this pack resolved from the feed"* was a property of the
- *    set's composition — knowable from the invocation alone. Under the union it becomes a **statement
- *    per pack**, which is detection where there was prevention, and this repository has measured that
- *    nobody reads a passing validator's output. The trade was put to the maintainer and ruled: union,
- *    **but never silently** — which is #123's own word, and the reason `origins` below is a field
- *    rather than a sentence. A provenance a caller can only grep out of prose is checkable against
- *    sentences this same change wrote.
- *
- * **What may be claimed after the trade:** no path needs typing; every pack's resolution names the root
- * it used and whether that root was discovered or derived; a local-tree resolution is visible rather
- * than silent. **What may NOT:** that `auto` resolves only from a feed — it no longer does — or that a
- * green under it certifies provenance. The green certifies resolution. What bounds a pack's *content* is
- * unchanged and is the pin, never this function. The narrower property #117 demonstrated also stands
- * verbatim: a **named** root still replaces the derived one, so a resolved-from-a-feed demonstration
- * given a named root cannot be satisfied by a local copy.
- *
- * _(Each clause above read "under `--pack-root auto`" until 2026-08-13. The trade is the same trade and
- * it now applies to the bare invocation as well, which is the disposal: a flag whose absence bought a
- * provenance guarantee could not also be optional. What asking still buys is the **strict degrade** —
- * see the asymmetry below — and nothing else.)_
- *
- * ## Asking for both is refused, not reconciled
- *
- * `--pack-root auto --pack-root ./packs` used to drop the `auto` without a word. A rule whose whole
- * justification is *never silently* cannot ship beside a branch that silently discards an explicit
- * request, so the combination is a **refusal** — `refusal` is set, and the roots are empty so a caller
- * that forgets to check fails closed rather than resolving against half of what was asked for.
- *
- * ## The unasked arm consults discovery too, as of 2026-08-13 — the row's word, met
- *
- * The row's clause is *"optional where discovery finds a root"*, and until this date `--pack-root` was
- * not optional: on the workspace `init` drafts by default plus one pack of the adopter's own, `doctor`
- * exited **1** with no flag and **0** under `auto`. Measured, and it was worse than one red — the same
- * arrangement made `recipe-set` and `skills-set --check` exit **2**, and left `compile` composing the
- * bound checkpoint pack's two gate fragments into nothing. Three of five tools were unusable unasked.
- *
- * The maintainer ruled a **behaviour change rather than a row amendment**: the row's word stands and
- * the implementation meets it. A fresh supervisor graded that ruling sound from `../docs/vision.md`,
- * which defines `doctor` as a **per-host capability report** — answering about the host is what it is
- * for — and sharpened the boundary to: **a verdict about the *repository* must not depend on the
- * machine.**
- *
- * **What holds that boundary is the PIN, not this branch.** Six required invocations name their root
- * (2026-08-13), a named root **replaces** every other source, and `../cli/pinned-roots.live.test.mjs`
- * fails if any of them drops it or if a seventh joins them unpinned. So a required check's verdict
- * cannot move with what is installed on the machine running it, whatever the unasked default is. This
- * docblock said the **thunk** was what kept `compile --check` host-independent, and that sentence had
- * already gone false one pull request earlier, when `.portulan/verify/compile.sh` gained
- * `--pack-root packs`: it names a root. The guarantee moved carriers and the prose had not.
- *
- * ## The asymmetry between the two arms, which is the whole reason they are two
- *
- * **`forced` and unasked differ on exactly one question: what an unreadable record means.**
- *
- * - **Asked and could not look is could-not-run** — exit 2, ruled 2026-08-13. You asked; the question
- *   is unanswerable; that is what the third code is for.
- * - **Unasked and could not look degrades to derived-only, with the diagnostic REPORTED** — never an
- *   empty set, never exit 2. Nobody asked, so the readability of the host's record cannot be a
- *   precondition for grading a repository. Silent, though, it must not be: the diagnostic rides in
- *   `why`, so a host with a corrupt record is visible rather than merely survived.
- *
- * **Reusing the `forced` branch as the unasked default is therefore the one implementation that must
- * not happen.** It would import that branch's `couldNotRun` and every CI runner — where the record is
- * absent, then unreadable the day a host bumps its schema — would exit 2 or, worse, be given an empty
- * root set and go green by not looking. That is the fail-open this module spent a session closing.
- *
- * `discovery` may be a THUNK, and **its presence is the switch**: an API caller that wires none keeps
- * the hermetic behaviour this function had before, on every arm. There is no second flag for it,
- * because a per-caller opt-out would be a second carrier of the precedence rule — the
- * three-tools-two-semantics defect `./compile.mjs`'s `namedRootsOption` records.
- */
+/** A named root wins outright; otherwise discovered roots lead the derived ones, as `resolvePack` takes the first match. */
 export function resolutionRoots({ named = [], namedGiven = null, derived = [], discovery = null, forced = false } = {}) {
     let cached;
     const resolveDiscovery = () => {
         if (cached === undefined) cached = typeof discovery === "function" ? discovery() : discovery;
         return cached;
     };
-    // `namedGiven` separates *a caller named roots* from *the list is non-empty*, because an
-    // explicitly EMPTY named set means **search nowhere** for API callers and must not fall through to
-    // the derived root. Three tools disagreed about that once; keeping the distinction here rather
-    // than in each of them is what stops a fourth from inventing a fifth answer.
+    // An explicitly empty named set searches nowhere rather than falling through to the derived root.
     const givenNamed = namedGiven ?? named.length > 0;
-    // Every branch returns the same shape, `origins` included: a caller joining a resolved pack to its
-    // root must not have to know which branch produced the plan.
     const tag = (roots, origin) => roots.map((root) => ({ root, origin }));
-    // `refusal` and `couldNotRun` are separate fields because they are separate facts, and both map to
-    // exit 2. `refusal` says *your command line asked for two different resolution sets*; `couldNotRun`
-    // says *you asked me to look and I could not*. Collapsing them would send a reader with an
-    // unreadable plugin record to re-read their flags.
     const plan = (roots, source, why, origins = null, refusal = null, couldNotRun = null) => ({
         roots,
         source,
@@ -840,20 +361,7 @@ export function resolutionRoots({ named = [], namedGiven = null, derived = [], d
         refusal,
         couldNotRun,
     });
-    // **ONE union, reached from both arms.** Discovered-first is load-bearing rather than cosmetic:
-    // `resolvePack` is first-match-wins, so where both roots carry a pack the discovered copy answers,
-    // which keeps every result the old `auto` produced a subset of this one. Written once because two
-    // orders keyed on whether a flag was typed would make the flag change the *meaning* of resolution
-    // rather than its inputs — and two matching literals are a convention, while one function is a
-    // guarantee. `lead` is the only difference between the arms: who asked.
-    //
-    // **What `source: "union"` means, because the arms reach this differently and a reader will assume
-    // they do not.** The `forced` arm calls this even when discovery found **nothing** — you asked, and
-    // *"I looked, and there is nothing installed"* is the answer to report. The unasked arm calls it only
-    // where discovery contributed a root; otherwise it returns `derived`, with discovery's own sentence in
-    // the `why`. So `union` reads as *discovery contributed, or was asked for* — never as *the set has two
-    // origins*. Recorded because a test fixture with an empty cache passed the asked half and bound
-    // nothing on the unasked one, which is how the asymmetry was noticed at all.
+    // `union` means discovery contributed a root or was asked for, not that the set has two origins.
     const union = (found, lead) => {
         const nothingFound = found.roots.length === 0 && found.why;
         return plan(
@@ -875,9 +383,6 @@ export function resolutionRoots({ named = [], namedGiven = null, derived = [], d
         );
     }
     if (givenNamed) {
-        // Deliberately does not consult discovery: the row's guarantee is that a named root is never
-        // silently overridden, and the cheapest way to keep that true is to have nothing to override
-        // it with on this branch.
         return plan(
             [...named],
             "named",
@@ -886,93 +391,31 @@ export function resolutionRoots({ named = [], namedGiven = null, derived = [], d
     }
     if (forced) {
         const found = resolveDiscovery();
-        // **Also could-not-run**, and it took Copilot's round 4 to see it: this branch's own `why`
-        // says *discovery was requested and did not run*, which is the definition of the third exit
-        // code, and it was returning a bare empty plan — the exact fail-open the branch below was just
-        // repaired for, one line above it. `resolutionRoots` is exported and `rootPlan` takes `forced`
-        // and `discovery` independently, so a caller can reach this with no thunk wired and, treating
-        // an empty root set as *nothing to check*, exit 0 over a discovery that never happened.
         if (!found) {
             const why = "discovery was requested and did not run — no discovery was wired into this call";
             return plan([], "none", why, [], null, why);
         }
-        // **Asked for, and could not look — exit 2.** Ruled 2026-08-13 on a measurement: this branch
-        // returned an empty plan, and an empty root set makes `doctor` report every declared pack
-        // *unverifiable* and exit **0**. So `--pack-root auto` against an unreadable record was a
-        // green over a host nobody could read, and it discarded the tree-derived root on the way —
-        // turning a correct red into a green while losing information it already had. A discovery that
-        // could not look is a could-not-run, which is what the third exit code exists for.
-        //
-        // An **absent** record no longer reaches here: `discoverPackRoots` answers `ok: true` with no
-        // roots for that, because a host with no record is a host with nothing installed. Only a
-        // record that exists and will not be read is this branch.
-        //
-        // **The strongest ground for exit 2 rather than a quiet degrade is `RECORD_VERSIONS`.** That
-        // constant promises discovery stops on a record schema this reader has not seen, "until this
-        // set is widened by someone who has looked". A host bumping its record version lands exactly
-        // here — so a degrade-and-carry-on would silently convert every `auto` user to derived-only on
-        // that day, fleet-wide, repealing a decision the constant records as deliberate. Exit 2 makes
-        // it loud, which is what the constant asked for.
-        //
-        // **That argument is about the ASKED arm alone, and saying so is the point.** Since the unasked
-        // arm began consulting discovery (2026-08-13) a record-version bump degrades the *bare* fleet to
-        // derived-only rather than stopping it — which is correct, because nobody asked — so "loud" has
-        // to be delivered there by the diagnostic rather than by an exit code. Where each tool surfaces
-        // it: `doctor` prints `plan.why` on its `resolution root` note and on every unresolved pack;
-        // `compile` prints the plan line whenever the source is a union and an `UNRESOLVED` line per
-        // pack; `recipe-set` and `skills-set` still exit **2** on a composed artefact they could not
-        // read, which is the row's own could-not-run rule and is untouched by the degrade.
+        // Asked for and could not look is could-not-run, never an empty set `doctor` would pass as unverifiable.
         if (!found.ok) return plan([], "none", found.why, [], null, found.why);
-        // Where discovery found NOTHING, its own sentence rides through — see `union`. "0 root(s)" alone
-        // cannot tell a host with no record from a host with a valid record listing nothing installed,
-        // and those are different facts about the machine — the second is a host that has Portulan packs
-        // available and none of them relevant; the first is a host that has never installed one.
         return union(found, "discovered in the host plugin cache");
     }
-    // ── The unasked arm. Nobody named a root and nobody typed `auto`.
-    //
-    // A wired thunk is consulted here, and the DEGRADES are the whole of the difference from the arm
-    // above: an unreadable record loses the discovered half and keeps the derived one, rather than
-    // becoming a could-not-run. Guarded on `discovery` rather than on the memoised value, so a caller
-    // that wires nothing never reaches the thunk at all — that identity, not a flag, is what keeps an
-    // API caller hermetic.
     const found = discovery === null || discovery === undefined ? null : resolveDiscovery();
     if (found && found.ok && found.roots.length) return union(found, "discovered in the host plugin cache unasked");
-    // Everything below is derived-only, and the three ways of getting here need three sentences,
-    // because collapsing them is how this module started lying about `absent` in the first place.
-    // `couldNotRun` is null on every one of them: nobody asked.
-    // `found.why` is **optional**, and appending it unguarded put the literal `null` in a user-facing
-    // sentence. `discoverPackRoots` returns `why: null` on its ordinary success path — a record that
-    // READ fine and simply lists no plugin carrying packs — which is a real host rather than an edge:
-    // anyone with plugins installed and none of them a pack feed. The `union` helper one screen up
-    // guards exactly this (`found.roots.length === 0 && found.why`) and this arm did not: one operation,
-    // two sites, correct at one. Raised by Copilot, round 1 on #237.
     const said = (lead) => (found.why ? `${lead} — ${found.why}` : lead);
     const because = !found
         ? null
         : found.ok
-          ? // Looked, nothing installed that carries packs. Discovery's own sentence, where it has one,
-            // distinguishes a host with no record from one whose record lists nothing relevant.
+          ? // `why` is optional: a record that lists no pack root carries none.
             said("discovery was consulted and found no root")
-          : // Could not look, and it is REPORTED rather than swallowed. Degrading in silence would
-            // make a corrupt plugin record indistinguishable from a clean host, which is the pair
-            // `discoverPackRoots` keeps apart one function above.
+          : // Unasked, an unreadable record degrades to the derived root, reported rather than exit 2.
             said("discovery was consulted and could not look, so only the derived root is searched");
     if (derived.length) {
-        // Same discipline as the arm below: the stem is ONE string and only the tail branches, so a
-        // discriminator matching on it cannot be broken by editing the other case.
         return plan(
             [...derived],
             "derived",
             `derived from the workspace manifest's \`tree\`${because ? `; ${because}` : " — pass `--pack-root auto` to search the host plugin cache as well"}`,
         );
     }
-    // The STEM is deliberately the same clause in both arms — *no root was named and none is derivable
-    // from the manifest* — and only the tail differs. Rewording it cost a test that was asserting the
-    // right property for the right reason: `doctor.test.mjs`'s *"a declared pack on a workspace with no
-    // tree is REPORTED, never failed"* matched on `none is derivable from the manifest`, and a
-    // paraphrase broke a discriminator this change had no business touching. Prose that carries a
-    // discriminator is an interface.
     return plan(
         [],
         "none",