@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/cli/portulan.mjs

@@ -1,63 +1,7 @@
 #!/usr/bin/env node
 // Portulan — the one entry point the `npx` package exposes.
 //
-// `docs/vision.md` names **eight** subcommands and is human-owned: `init` · `doctor` · `compile` ·
-// `vendor` · `index` · `upgrade` · `new` · `feedback`. This is milestone 7's packaging clause.
-//
-// It named six until 2026-08-03. `new` and `feedback` arrived in the CLI first, licensed by row 7 of
-// `docs/plan.md` naming them in its own ratified text, and the maintainer then folded both into the
-// constitution — so the two-carrier state that licence created lasted one pull request and is gone. The
-// history is worth one sentence rather than none: a subcommand may be licensed by the row before the
-// constitution catches up, and when that happens this file says which document names it. Everything
-// beyond these eight is still the maintainer's call.
-//
-// ## What it is NOT
-//
-// **Not a reimplementation.** `doctor`, `compile`, `index` and `init` each live in their own file and
-// are exercised by their own suites; this dispatches to them and adds nothing to what they do. A
-// wrapper that re-derived any part of their behaviour would be a second carrier of one fact, which is
-// the class `0020` names — a rule enforced at two sites and repaired at one — so the dispatch imports each tool's
-// exported `run` and returns its exit code untouched.
-//
-// **Not a home for the tools that are off the list.** Several tools live in `cli/` and are deliberately
-// absent here. `docs/vision.md` names eight, it is human-owned, and whether any of the others ever joins
-// that list is the maintainer's call and not an implementer's. Wiring one in would mint a ninth
-// subcommand into a list this file does not own. They stay runnable exactly as they are today —
-// `node cli/plugin-lint.mjs …` — and every verify recipe still invokes them that way.
-//
-// **The roster itself is `cli/README.md`'s and is cited rather than repeated here.** This paragraph
-// said **two**, then **three**, and named a different three from the root `README.md`'s three while
-// **four** were on disk — one rule with three carriers, obeyed at the narrowest, in the file whose own
-// comments name that class. _(It also named the wrong ordinal once — *a seventh subcommand*, written
-// when the list held six. A count in prose beside a list nothing derives it from is the drift this
-// file's own suite catches for `SUBCOMMANDS.length` and cannot catch here.)_
-//
-// ## All eight are built, and the shape of the answer while one was not is kept
-//
-// `upgrade` carried `module: null` from milestone 7 session 0 until session 9 and exited **2 — could
-// not run**, naming where it arrived. It dispatches now like the rest. The paragraph is kept rather
-// than deleted, because the state it describes recurs: the constitution may name a verb before the
-// tree carries it, and both alternatives to that answer were worse — hiding the entry makes the
-// package look like a smaller tool and the row like it is further along than it is, and stubbing it
-// to exit 0 is a fail-open in the one place a user is most likely to trust silence. "Nothing looked"
-// is never "nothing wrong" — the same three-code discipline the verify recipes hold
-// (`.portulan/memory/verify-preconditions-fail-closed.md`). The machinery for the next such entry is
-// still here: `module: null` plus `arrives`, and the refusal below reads them.
-//
-// _(`vendor` was one of three until milestone 7 session 3, and `feedback` one of two until session 6.
-// The count is written out here and derived in the suite, which is the split that has held: the
-// sentence explains, the assertion counts.)_
-//
-// ## Exit codes, which are the tools' own
-//
-// `0` the subcommand succeeded · `1` it rendered a red verdict · `2` it could not run — including
-// an unknown subcommand, an unbuilt one, and being invoked with **no arguments at all**, because
-// none of those is a verdict about anybody's workspace. An **explicit** `--help` exits 0: asking for
-// help is a request, and it succeeded.
-//
-// Zero dependencies and no build step, which is a ruling rather than an accident: the maintainer
-// settled on 2026-07-31 that this ships as plain ESM on Node, against `.portulan/identity.md`'s
-// older "TypeScript on Node" line, so that the repository stays checkable by cloning it.
+// Exit codes are the subcommand's own; else 0 for `--help` or `--version`, and 2 for no arguments or a subcommand that cannot run.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -65,23 +9,11 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
-// ONE carrier for the version, read from the manifest that publishes it — and read in `manifest.mjs`
-// rather than here, since milestone 7 session 6.
-//
-// It was written down twice — here and in `package.json` — which is this repository's dominant defect
-// class committed in the file whose own comments name it. The read moved down a level when `feedback`
-// needed the same value: importing it *from this file* made the subcommand circular with the entry
-// point and hung the command line on an unsettled top-level await, which `manifest.mjs`'s header
-// records in full. Re-exported here so this file's published surface is unchanged.
+// A subcommand imports VERSION from ./manifest.mjs: importing it from here would cycle through this file's top-level await and exit 13.
 export { VERSION } from "./manifest.mjs";
 import { VERSION } from "./manifest.mjs";
 
-// The eight, in the order `docs/vision.md` lists them. `module` is the file that carries the
-// subcommand's `run`; `null` means the subcommand exists in the vision and not yet in the tree.
-//
-// `arrives` is not decoration. Condition 4 of `.portulan/dod.md` is that a document describing
-// capability either has the capability or names where it arrives, and a help screen listing a verb
-// that does nothing is exactly that document.
+// In `docs/vision.md`'s order. An unbuilt entry sets `module: null` and `arrives`, and `namedIn` where another document names it.
 export const SUBCOMMANDS = [
     {
         name: "init",
@@ -91,7 +23,7 @@ export const SUBCOMMANDS = [
     {
         name: "doctor",
         module: "doctor.mjs",
-        summary: "validate a workspace against the Workspace Definition",
+        summary: "validate a workspace and report branch-owned host tokens beside local receipts; --static skips usage records",
     },
     {
         name: "compile",
@@ -101,11 +33,6 @@ export const SUBCOMMANDS = [
     {
         name: "vendor",
         module: "vendor.mjs",
-        // BOTH directions, because the constitution now glosses both. It said "a self-contained
-        // AGENTS.md + .portulan/ for any host" until 2026-08-03, when the maintainer widened the gloss
-        // to cover materialising a workspace out of a repository as well as into one — which is what
-        // settled the verb row 7 had deliberately left unassigned. A summary carrying only the older
-        // half would be the narrower of two carriers of one fact, which is the shape a reader obeys.
         summary: "materialise a workspace where it is needed: into a host, or between residences",
     },
     {
@@ -116,11 +43,6 @@ export const SUBCOMMANDS = [
     {
         name: "upgrade",
         module: "upgrade.mjs",
-        // BOTH kinds, because the chain carries both. A summary naming only the version half would
-        // be the narrower of two carriers of one fact — and the narrower is the one a reader obeys.
-        // What a step is lives in `spec/migrations/README.md`; this line only has to not contradict
-        // it, which the older wording ("migrate a workspace to a newer Workspace Definition") would
-        // have started doing the moment the maintainer admitted repairs on 2026-08-12.
         summary: "migrate a workspace: the Workspace Definition steps it owes, and the repairs a rewriter owes it",
     },
     {
@@ -148,8 +70,6 @@ export function usage() {
         "",
     ];
     for (const entry of SUBCOMMANDS) {
-        // The state is printed per subcommand rather than as a footnote, because a reader scanning
-        // this list is deciding what to type, and a footnote is read after that decision.
         const state = entry.module ? "" : `  (not built — arrives at ${entry.arrives})`;
         lines.push(`  ${entry.name.padEnd(width)}  ${entry.summary}${state}`);
     }
@@ -172,12 +92,6 @@ export async function run(argv, options = {}) {
 
     if (name === undefined || name === "--help" || name === "-h" || name === "help") {
         say(usage());
-        // The split is the point: a bare `portulan` was asked to do something and did nothing, which
-        // is could-not-run; an explicit `--help` asked for the help screen and got it, which is
-        // success. Written out because the two look alike in a shell and a reader scripting against
-        // this will meet both. _(These lines previously argued that explicit `--help` should exit 2
-        // as well — an argument the code never implemented and the tests contradict. Corrected in
-        // the direction of the behaviour, which is the conventional one.)_
         return name === undefined ? 2 : 0;
     }
 
@@ -189,28 +103,17 @@ export async function run(argv, options = {}) {
     const entry = find(name);
     if (!entry) {
         warn(`portulan: unknown subcommand \`${name}\`.`);
-        // Derived, never a literal. A hard-coded count is wrong the hour a subcommand lands — which is
-        // exactly what happened to a literal `3` in this file's own suite when `init` shipped.
         warn(`portulan: the ${SUBCOMMANDS.length} subcommands are ${SUBCOMMANDS.map((s) => s.name).join(", ")}. Run \`portulan --help\`.`);
         return 2;
     }
 
     if (!entry.module) {
-        // WHERE the name comes from, not a blanket "docs/vision.md". All eight are in the constitution
-        // as of 2026-08-03, so `namedIn` is unset on every entry today and the fallback is the whole
-        // behaviour — but the field stays, because the state it exists for is real and recurred once
-        // already: `feedback` was named by row 7 and by nothing else for one pull request, and the
-        // shipped tool told users the constitution named something it did not. A test asserts the
-        // sentence now, which is what that round was missing.
         warn(`portulan: \`${name}\` is named in ${entry.namedIn ?? "docs/vision.md"} and is not built yet — it arrives at ${entry.arrives}.`);
         warn("portulan: refusing to exit 0 on a subcommand that did nothing.");
         return 2;
     }
 
-    // Loaded on demand, never at startup. Two reasons and both are measured elsewhere in this
-    // repository: a tool that fails to parse takes down only its own subcommand rather than the
-    // whole command line, and the built modules together are large enough that eagerly importing
-    // them would make `portulan --help` pay for `doctor`.
+    // Imported on demand: a module that fails to load takes down only its own subcommand, and `--help` loads none.
     let module;
     try {
         module = await load(entry.module);
@@ -220,36 +123,14 @@ export async function run(argv, options = {}) {
     }
 
     if (typeof module.run !== "function") {
-        // A guard rather than an assumption. Every built tool exports `run` today; if one stops, the
-        // failure must name itself here instead of surfacing as `module.run is not a function`.
         warn(`portulan: ${entry.module} does not export a \`run\` function — refusing to guess at its entry point.`);
         return 2;
     }
 
-    // The tool's own exit code, returned unchanged. Re-mapping it here would put a second opinion
-    // about a workspace between the tool and its user.
     return await module.run(rest);
 }
 
-// THE MAIN-MODULE GUARD RESOLVES SYMLINKS, and this file is the one in the repository that must.
-//
-// Every other tool here guards with a bare `pathToFileURL(process.argv[1])` comparison and is right
-// to: nothing ever invokes them through a link. This one is a `bin`, and **npm installs a bin as a
-// symlink** — `node_modules/.bin/portulan` → `cli/portulan.mjs`. Node realpaths the main module for
-// `import.meta.url` while `process.argv[1]` keeps the link path, so the bare comparison is FALSE
-// through the link and `run` never executes.
-//
-// Measured on the staged tree before this line existed, by packing the package and installing the
-// tarball: through `node_modules/.bin/portulan`, `--version` printed nothing and exited 0, and
-// `doctor <nonexistent>` exited **0** where the same command exits 1 from a checkout. **Every
-// verdict became a silent success** — "nothing looked" reported as "nothing wrong", at the one
-// surface a user reaches by the documented route. Found by the pre-commit checkpoint, which
-// installed the tarball rather than reading the guard.
-//
-// `realpathSync` rather than `import.meta.main`, which needs a newer Node than `engines` asks for.
-// Wrapped, because `argv[1]` may be absent or unreadable and a guard that throws would be a worse
-// failure than the one it prevents — falling back to the unresolved path leaves the old behaviour
-// rather than crashing.
+// npm installs a bin as a symlink, and Node realpaths `import.meta.url` but not `argv[1]`; `import.meta.main` needs a newer Node than `engines`.
 function isMain() {
     const invoked = process.argv[1];
     if (!invoked) return false;

package/cli/recipe-set.mjs

@@ -1,105 +1,30 @@
-/**
- * The recipe set — the one carrier of *what this workspace runs*.
- *
- * Row 7's amendment of 2026-07-31 (argument in `docs/milestones/m07.md`) ruled that a composed
- * pack's verify recipes reach the adopting workspace's runnable set, under a contract stated in the
- * row rather than left to this file: **additive only** — a pack may add a recipe and may never
- * redefine, remove or replace one the workspace declares, nor become the workspace's
- * `verify.default` — **namespaced by its pack, so a collision is impossible rather than resolved**,
- * and **could-not-run — exit 2, never silently absent** when a composed recipe cannot resolve.
- *
- * ## Why this is a module and not four implementations
- *
- * Until this landed the recipe set was read independently in four places — `.github/workflows/verify.yml`,
- * `cli/doctor.mjs`, `cli/vendor.mjs` and `cli/stop-gate.mjs` — with none authoritative. Composing into
- * fewer than all four would have left the rest disagreeing about what the set IS, which is
- * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md`'s defect in its code
- * material: one rule, several enforcement sites, repaired at fewer than all of them. The repair that
- * proposal prescribes is `core/operating/evolution.md`'s — **one carrier, and the others reach it** —
- * and here the rule can be a function, which is where that repair applies.
- *
- * The row makes CI part of the contract in its own words: *CI runs the recipe set the manifest yields*,
- * and a composed recipe missing from it *"would be a green computed over something nobody ran"*. So
- * `verify.yml` calls this module rather than carrying its own enumeration, and `cli/recipe-set.test.mjs`
- * pins the roster so a fifth reader reds instead of drifting.
- *
- * ## What the namespace buys, and why the refusal stays anyway
- *
- * A workspace-declared recipe id is a bare slug (`$defs/slug`, `^[a-z0-9]+(-[a-z0-9]+)*$`) in
- * `spec/workspace.schema.json`, and so is `verify.default`. A composed id is `<category>/<name>:<id>`,
- * whose `/` and `:` are outside that grammar. So a composed recipe cannot carry a workspace id and
- * cannot be named by `verify.default`: **both are impossible by construction, not refused by a check
- * somebody has to remember.**
- *
- * The refusal below is kept as belt and braces behind that construction — the pattern `verify.yml`
- * already names in its own comment — and it is not a claim to an enforcement that cannot fire, which
- * `../.portulan/memory/a-stated-enforcer-must-be-the-real-one.md` would forbid. Two classes reach it:
- *
- *   1. **A pack declaring one id twice with different runs.** Schema-legal: `contributes.verify`'s
- *      `uniqueItems` compares whole recipe objects, so two entries differing only in `run` validate.
- *      The namespacer gives both the same composed id and only this refusal catches it. It is forced
- *      red in the suite.
- *   2. **A hand-edited manifest reaching a reader that does not validate against the schema** — CI and
- *      the Stop gate both read `workspace.json` raw.
- *
- * ## The composed `run` contract
- *
- * `spec/pack.schema.json` glosses a recipe's `run` as *"the command, as it would be typed from the
- * repository root"*. A pack has no repository until it is adopted, and its script ships inside the
- * pack — so a composed `run` needs a way to name its own files from a root it cannot know. It does
- * that with **`${PACK_ROOT}`**, expanded here to the resolved pack root before the command is handed
- * to anyone. After expansion the gloss is true again, which is the point: what runs is a command
- * typeable from the repository root.
- *
- * Expansion happens **before** the newline and tab check, so a pack root carrying one cannot smuggle
- * it past a validation that ran too early. A workspace recipe's `run` is never expanded — the token
- * has no meaning outside a pack, and rewriting it would be this module inventing a feature the
- * Workspace Definition does not declare.
- */
+// The recipe set: the verify recipes a workspace yields, its own plus each composed pack's, namespaced by pack.
 
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-// `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";
 
-/**
- * Every reader of the recipe set, by path.
- *
- * **Pinned in two halves, because this list alone holds less than it looks like it holds.**
- * `cli/recipe-set.test.mjs` asserts the roster's contents, which catches a reader being removed or
- * renamed — but a *fifth* reader that never adds itself here touches nothing that assertion reads. So
- * `cli/recipe-set.live.test.mjs` sweeps `cli/*.mjs` and the workflows for an undeclared enumeration of
- * `verify.recipes`, which is the half that actually catches drift. `cli/collisions.test.mjs` carries
- * the same pair for the three `collisions()`, and the sweep is the half it had to add for the same
- * reason: a copy nothing asserts is invisible to every other test.
- *
- * Two sites enumerate `verify.recipes` directly and are exempt by argument, not by oversight: this
- * module, and `cli/doctor.mjs`, which validates the workspace's own DECLARATION rather than reading
- * the runnable set.
- */
+/** Add any new reader here: `recipe-set.live.test.mjs` catches only a direct enumeration of `verify.recipes`. */
 export const RECIPE_SET_READERS = Object.freeze([
     ".github/workflows/verify.yml",
     "cli/doctor.mjs",
-    // Added 2026-08-25 with milestone 8 clause (d). `cli/drills.mjs` reads the set to know which rails
-    // it must drill — and it is the reader that shows the live sweep's own boundary: it calls
-    // `recipeSet()` rather than enumerating `verify.recipes`, so the sweep for an undeclared
-    // *enumeration* could not see it and this roster went stale in the one way the pair above was
-    // arranged not to allow. Raised as a suppressed note by Copilot, round 1 on #343.
     "cli/drills.mjs",
+    "cli/finish.mjs",
+    "cli/form.mjs",
     "cli/stop-gate.mjs",
     "cli/vendor.mjs",
 ]);
 
-/** `$defs/slug`, held identically by both schemas. A workspace id and `verify.default` are this. */
+/** `$defs/slug`, as both schemas hold it. */
 const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /** The token a composed `run` uses to name its own pack's files. */
 const PACK_ROOT_TOKEN = "${PACK_ROOT}";
 
-/** The composed spelling. Exported so no caller re-derives it — one carrier, again, one layer down. */
+/** Its `:` is outside `$defs/slug`, so a composed id never equals a workspace id or `verify.default`. */
 export function composedId(packRef, id) {
     return `${packRef}:${id}`;
 }
@@ -108,71 +33,25 @@ function refuse(reason) {
     return { ok: false, exitCode: 2, reason };
 }
 
-/**
- * Validate one recipe's runnable parts. Returns an error string or null.
- *
- * These four refusals were carried by `.github/workflows/verify.yml`'s inline emitter alone until this
- * module took them. Losing one in the move would have been a fix not done at the site it was found,
- * committed inside the change that cites the doctrine — so they are asserted here in the suite rather
- * than trusted to have survived.
- */
+/** An error sentence, or null when the recipe is runnable. */
 function invalidRunnable(id, run, where, { requireSlug = true } = {}) {
-    // `requireSlug` is off only on the deliberately-bypassed path. Without it `trustPackSpelling` could
-    // not do the one thing its JSDoc says it exists for: a genuinely pre-namespaced id carries `/` and
-    // `:`, so the slug check refused it *before* the shadow refusal it was meant to reach — an option
-    // that named a purpose it could not serve. Copilot round 6.
     if (requireSlug && !SLUG.test(String(id ?? ""))) return `${where} declares a recipe id that is not a slug: ${JSON.stringify(id)}`;
     const command = String(run ?? "");
     if (!command.trim()) return `${where} declares an empty run command for recipe \`${id}\``;
-    // Names all three characters it rejects. It said "newline or tab" while the pattern also refused a
-    // carriage return, so a manifest carrying one got a message pointing at two characters it did not
-    // contain — a diagnosis that sends the reader looking for the wrong thing. Copilot round 1.
     if (/[\n\r\t]/.test(command)) {
         return `${where} declares a run containing a newline, carriage return or tab for recipe \`${id}\``;
     }
     return null;
 }
 
-/**
- * The composed runnable set for a workspace manifest.
- *
- * @param {object} manifest              a parsed Workspace Definition
- * @param {object}   [options]
- * @param {string[]} [options.packs]     the workspace's `packs` array; defaults to `manifest.packs`
- * @param {(ref: string) => ({ ref: string, root: string, manifest: object } | null)} [options.resolve]
- *        resolves a pack reference to its root and manifest, or null when it cannot be found.
- *        Absent when packs are declared means nothing resolves, which is could-not-run — fail-closed,
- *        because a resolver that silently is not there would compose nothing and report green.
- * @param {boolean}  [options.trustPackSpelling]  use a pack's own recipe id verbatim instead of
- *        namespacing it. Exists so the shadow refusal can be exercised against a real input; no
- *        production caller passes it.
- *
- * @returns {{ ok: true, recipes: object[], default: string|undefined }
- *          | { ok: false, exitCode: 2, reason: string }}
- */
+/** `{ ok: true, recipes, default }`, or `{ ok: false, exitCode: 2, reason }` when the set cannot be composed. */
 export function recipeSet(manifest, options = {}) {
     const { packs = manifest?.packs ?? [], resolve = null, trustPackSpelling = false } = options;
 
-    // `packs` must be an array, for the same reason `verify.recipes` must be — and this is that fix's
-    // sibling, at the site round 1 did not reach. A string here would iterate CHARACTERS and report
-    // "the pack `t` could not be resolved", a refusal whose message names something the manifest never
-    // said; an object would throw a TypeError, which is a stack trace rather than a diagnosis. Both are
-    // could-not-run wearing a worse face. Copilot round 3.
     if (!Array.isArray(packs)) {
         return refuse(`this workspace's \`packs\` is not an array (${typeof packs}) — could-not-run rather than a set composed from a value nothing can enumerate`);
     }
 
-    // A manifest with no `verify.recipes` ARRAY is could-not-run, not a workspace that declares none.
-    //
-    // This was `?? []`, and that was a fail-open the move introduced: the CI emitter this carrier
-    // replaced iterated `m.verify.recipes` directly, so an absent block threw and became exit 2. Under
-    // `?? []` an invalid manifest could still yield a runnable set as soon as a pack contributed one —
-    // CI would then run a green over a workspace whose own declaration nobody could read. One of the
-    // four validations that was supposed to survive the move, and the one that did not; the pre-commit
-    // checkpoint asked the question and neither pass caught it. Copilot round 1's suppressed note did.
-    //
-    // Absent is distinguishable from empty here only in the message: both refuse, because `spec/workspace.schema.json`
-    // requires the block and a workspace that declares no recipes cannot report green either way.
     if (!Array.isArray(manifest?.verify?.recipes)) {
         return refuse(
             "the workspace manifest declares no `verify.recipes` array — could-not-run rather than a set " +
@@ -186,14 +65,7 @@ export function recipeSet(manifest, options = {}) {
     for (const recipe of declared) {
         const bad = invalidRunnable(recipe?.id, recipe?.run, "the workspace manifest");
         if (bad) return refuse(bad);
-        // Normalised to strings on the way out, the way the pack path below already does.
-        //
-        // The validation above coerces with `String(...)`, so a non-string `id` that stringifies to a
-        // slug PASSED and was then pushed through unchanged — and every downstream comparison is an
-        // identity check on that value: `r.id === set.default` in the Stop gate, `seen.has(id)` here,
-        // the emitter's tab-separated line. One arm of this function stringified and the other did not,
-        // which is the two-sites-one-rule shape this whole change is about, inside the carrier that
-        // carries it. Copilot round 2's suppressed note.
+        // As strings: validation coerced them with `String`, and every reader compares ids with `===`.
         const id = String(recipe.id);
         const run = String(recipe.run);
         if (seen.has(id)) return refuse(`the workspace manifest declares the recipe \`${id}\` more than once`);
@@ -204,23 +76,13 @@ export function recipeSet(manifest, options = {}) {
     for (const ref of packs) {
         const found = resolve ? resolve(ref) : null;
         if (!found) {
-            // Never silently absent. The row's words: exit 2, and the run says which pack — and which
-            // recipe, where one is known. A composed recipe quietly missing from the set would be a
-            // green computed over something nobody ran, arriving through the composition path.
             return refuse(
                 `the pack \`${ref}\` is composed by this workspace and could not be resolved, so its verify recipes ` +
                     `could not be read — could-not-run rather than a set that quietly lost them`,
             );
         }
 
-        // A pack declaring no `verify` key contributes no recipes and is not an error. That is
-        // `packs/rituals/checkpoints`'s deliberate shape, by its own argued policy, and conflating
-        // "declared none" with "failed to resolve" would make the honest pack red.
-        //
-        // But a key that is PRESENT and not an array is neither of those: it is a manifest nobody can
-        // read, and `for..of` over it throws a TypeError — the carrier crashing where its whole
-        // contract is to exit 2 with a sentence naming the pack. Third site of round 1's rule, and the
-        // second one it did not reach. Copilot round 3.
+        // An absent `contributes.verify` is a pack that contributes no recipes, not an error.
         const contributed = found.manifest?.contributes?.verify;
         if (contributed !== undefined && !Array.isArray(contributed)) {
             return refuse(`the pack \`${ref}\` declares \`contributes.verify\` as ${typeof contributed}, not an array — could-not-run`);
@@ -250,79 +112,26 @@ export function recipeSet(manifest, options = {}) {
         }
     }
 
-    // Reporting green having run nothing is the failure the whole gate exists to prevent, and
-    // enumeration is a precondition exactly as it is inside each recipe —
-    // `../.portulan/memory/verify-preconditions-fail-closed.md`.
     if (recipes.length === 0) return refuse("the manifest yields no verify recipes — refusing to report green");
 
-    // `default` is normalised the same way the ids are, and this is round 2's own fix's sibling.
-    //
-    // Round 2 stringified every recipe's `id` on the way out and left `default` as whatever the
-    // manifest held. Every downstream lookup is an identity comparison — `r.id === set.default` in
-    // `cli/stop-gate.mjs` — so a non-string default that used to match a non-string id stopped matching
-    // the moment one side was normalised and the other was not. A repair that reached one of the two
-    // values it had to reach, in the change whose subject is exactly that. Copilot round 6.
     const declaredDefault = manifest?.verify?.default;
     return { ok: true, recipes, default: declaredDefault == null ? declaredDefault : String(declaredDefault) };
 }
 
-/**
- * A resolver over a workspace's declared pack roots, for callers that actually compose.
- *
- * Reaches `compile.mjs`'s `rootPlan` and `resolvePack` rather than re-deriving where a pack lives —
- * the precedence rule (**a named root wins outright; otherwise discovery is unioned with the derived
- * root, discovered first**) lives once, in `resolutionRoots`, and a second derivation here would be a
- * second carrier of the fact `cli/discover.mjs` was built to hold. _(It read "asked-for discovery" until
- * 2026-08-13; the unasked arm consults a wired thunk too, and what asking still changes is the degrade —
- * asked-and-could-not-look is exit 2, unasked-and-could-not-look keeps the derived root.)_ The pack root handed to
- * `${PACK_ROOT}` is made **relative to the repository root**, because that is the root a recipe's
- * `run` is typed from.
- *
- * **`forced` rides beside `discovery` because without it the pair WAS dead plumbing.** This function
- * accepted `discovery` and passed it on while `resolutionRoots` consulted it only under `forced`, so no
- * caller could ever have reached discovery through here — the parameter looked wired and was not. Both
- * are still threaded and `forced` now carries less: since 2026-08-13 a wired `discovery` is consulted
- * either way, and `forced` selects the strict degrade. A caller passing neither stays hermetic, which is
- * the property `recipe-set.test.mjs` pins — and it is the reason `stop-gate`, which passes `packs: []`,
- * still reaches no host at all.
- */
+/** The `resolve` that `recipeSet` takes; throws on a refusal, a could-not-look or a shadowed pack. */
 export function resolverFor({ workspaceDir, manifest, repoRoot = ".", named = [], discovery = null, forced = false }) {
     const plan = rootPlan(workspaceDir, manifest, { named, discovery, forced });
-    // A refusal must not arrive as an empty root set. That is the silent drop this change exists to
-    // remove, and the first cut of this function reintroduced it one layer down — an API caller
-    // passing `named` beside `forced: true` would have resolved nothing and been told nothing.
-    // Raised by Copilot, round 1 on #233; swept to `skills-set.mjs`'s sibling in the same stroke.
     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.
+    // Checked here, not in the returned closure: that runs inside `recipeSet`, beyond the caller's `try`.
     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(
@@ -337,20 +146,12 @@ export function resolverFor({ workspaceDir, manifest, repoRoot = ".", named = []
 
     return (ref) => {
         const found = resolvePack(ref, roots);
-        // `resolvePack` returns `manifest` as the PATH to `pack.json`, not as the parsed object —
-        // reading it is this adapter's job. The first cut of this function treated it as parsed, and
-        // every pack then contributed nothing while the suite stayed green, because the fixture
-        // resolver in `recipe-set.test.mjs` handed back a parsed object and so inherited the same
-        // assumption the code made. Caught by running the emitter against this repository rather than
-        // against its own fixtures; `cli/recipe-set.live.test.mjs` is what stops it coming back.
         if (!found?.dir || !found.manifest) return null;
         let parsed;
         try {
             parsed = JSON.parse(fs.readFileSync(found.manifest, "utf8"));
         } catch {
-            // A pack whose manifest is present and unreadable is NOT a pack that contributes nothing.
-            // Returning null here makes it could-not-run at the caller, which is the honest answer —
-            // only absence is absence.
+            // Unreadable is not absent: null makes it could-not-run, not a pack with no recipes.
             return null;
         }
         const rel = path.relative(path.resolve(repoRoot), path.resolve(found.dir));
@@ -358,22 +159,8 @@ export function resolverFor({ workspaceDir, manifest, repoRoot = ".", named = []
     };
 }
 
-/**
- * The emitter CI runs: one `id<TAB>run` line per recipe in the composed set, exit 2 if the set cannot
- * be produced.
- *
- * `.github/workflows/verify.yml` carried this as an inline `node -e` until milestone 7's composition
- * amendment. It is here now because the row puts CI inside the contract — *CI runs the recipe set the
- * manifest yields* — so a workflow computing its own set would be the required check reporting green
- * over a recipe nobody ran, which is the false green the row names in words.
- */
+/** CI's emitter: one `id<TAB>run` line per recipe in the set; exit 2 when the set cannot be produced. */
 export function run(argv = [], { stdout = process.stdout, stderr = process.stderr } = {}) {
-    // **Three refusals, not one.** `init`, `new` and `vendor` each refuse a missing value, a FLAG as a
-    // value, and an empty one; session 9 recorded a fourth parser taking only the first, where
-    // `--tree --write <dir>` swallowed the write and silently reported instead of migrating. This was
-    // the fifth: `argv.indexOf` plus a truthiness test meant `--workspace --pack-root packs` bound the
-    // workspace to the string `--pack-root`, and the run then failed with a misleading *manifest could
-    // not be read* about a directory nobody asked for. Copilot, round 5 on #236.
     let argError = null;
     const arg = (flag, fallback) => {
         const i = argv.indexOf(flag);
@@ -391,12 +178,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         return 2;
     }
 
-    // `--pack-root`, repeatable, with `auto` and the shared refusal — the same surface the other six
-    // tools take (`compile`, `doctor`, `index`, `init`, `vendor`, `skills-set`). It was missing here, and the plumbing behind it (`resolverFor`'s `discovery` and
-    // `forced`) existed with no way to reach it: a capability that looked wired and was not, which is
-    // the defect this file's neighbour `skills-set` was caught with a day earlier. CI calls this
-    // command for the recipe set it runs, so without the flag a workspace composing from the host
-    // cache had no invocation that could enumerate its own recipes.
     const named = [];
     let forced = false;
     for (let i = 0; i < argv.length; i += 1) {
@@ -412,17 +193,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             forced = true;
             continue;
         }
-        // A root that is not there is a fact about the FILESYSTEM, not a pack that failed to resolve,
-        // and reporting it as the latter sends an author to the one file that is not at fault. A FILE
-        // is the sharper case: `resolvePack` only tests for `pack.json` under the root, so a file-valued
-        // root yields "unresolvable" for every pack while the argument is what was wrong. Fourth carrier
-        // of a rule `compile`, `doctor` and `index` already hold; raised by Copilot, round 1 on #236,
-        // as an inconsistency with them.
-        // **The RAW value is stat'd, and resolution happens after.** `path.resolve("")` is the current
-        // working directory, so resolving first would let `--pack-root ""` pass the directory check and
-        // silently adopt the cwd as a pack root — the empty-value refusal this file gained one round
-        // earlier for `--workspace`, still missing here. `doctor`'s `directoryRoot` stats the raw value
-        // for exactly this reason. Copilot, round 6 on #236.
+        // The raw value is stat'd: `path.resolve("")` is the cwd, so resolving first would pass an empty root.
         let rootStat = null;
         try {
             rootStat = fs.statSync(value);
@@ -454,7 +225,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     try {
         resolve = resolverFor({ workspaceDir, manifest, repoRoot, named, discovery: () => discoverPackRoots(), forced });
     } catch (err) {
-        // `resolverFor` throws on a refusal or a could-not-look; both are exit 2 rather than a set.
         stderr.write(`${err.message}\n`);
         return 2;
     }