@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/cli/new.mjs

@@ -1,43 +1,7 @@
 #!/usr/bin/env node
-// `new` — scaffold a skill · persona · pack · workspace · gate-policy · repo-card from a core template,
-// into the user's OWN layer, never into `core/`.
+// `portulan new`: scaffold a skill, persona, pack, workspace, gate policy or repo card, never into `core/`.
 //
-// Milestone 7, row 7 of docs/plan.md. Zero dependencies, ESM, no build step (the session-0 ruling).
-//
-// ## The one property this tool states in the imperative
-//
-// **Never into `core/`.** Row 7 says it, and it is the reason this tool exists at all rather than being
-// advice: the cascade runs core < pack < workspace < repo card < task, and a team that answers "where do
-// I put my own skill?" by editing `core/` has merged their specifics into the layer that ships to
-// everybody. Thesis 6 of the constitution — storage follows ownership.
-//
-// The refusal is **resolution-based, not pattern-based**, because every interesting escape parses fine:
-// `packs/../core` matches any path rule you could write, and a symlinked destination matches nothing at
-// all until you follow it. So the check resolves first and compares after — the same conclusion
-// `spec/pack.schema.json`'s `$defs/filePath` reaches from the other side, and the one `cli/compile.mjs`
-// already acts on for its policy path.
-//
-// ## Two exit codes, deliberately
-//
-// **0 wrote · 2 could not run.** There is no exit 1, for the same reason `init` has none: this tool
-// renders no verdict about anybody's workspace, so it has no red to report. `doctor` is what says
-// whether what landed is any good, and conflating "I could not write this" with "what I wrote is wrong"
-// would make a caller unable to tell a missing template from a bad scaffold.
-//
-// ## What it refuses, ahead of the first byte
-//
-// A file it would overwrite — **any** file, never only a manifest. Session 1 shipped a residence check
-// keyed on `workspace.json` and treated it as an answer to *is it safe to write here?*; a hand-written
-// `gate-map.md` was silently overwritten. Two questions, one key: that was the whole defect. Here there
-// is only one question and it is asked about every path.
-//
-// A symlink anywhere on the destination chain — resolved links are how a write leaves the tree it was
-// meant to stay inside, measured on `init` at nine files written into an unrelated directory and
-// reported as success.
-//
-// And an `lstat` failure that is **not** `ENOENT`, because only `ENOENT` means absent. `EACCES` means
-// the question could not be answered, and answering *nothing there* to an unanswerable question is
-// "nothing looked" recorded as "nothing wrong".
+// Exit 0 wrote · 2 could not run; never 1, since it renders no verdict on a workspace.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -46,36 +10,20 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const CORE = path.resolve(HERE, "..", "core");
 
-/** Raised for anything that means `new` could not run. Carries no verdict about a workspace. */
 export class NewError extends Error {}
 
-/**
- * The six kinds row 7 names. A Set rather than an array so membership is the question asked, and
- * exported so the suite compares against the row rather than against a count that passes while a name
- * is wrong.
- */
 export const KINDS = new Set(["skill", "persona", "pack", "workspace", "gate-policy", "repo-card"]);
 
-/** A lowercase hyphenated identifier — the same shape `$defs/slug` fixes in both schemas. */
+/** `$defs/slug`, as both schemas hold it. */
 export const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
-/** Kinds whose artifact is JSON, extracted from the template's first fenced `json` block. */
 const JSON_KINDS = new Set(["pack", "workspace", "gate-policy"]);
 
-/** Where a kind's core template lives. One place, so a missing template is one failure and not six. */
 export function template(kind) {
     return path.join(CORE, "templates", `${kind}.md`);
 }
 
-/**
- * The skeleton inside a template — everything after the first standalone `---`, or, for the JSON kinds,
- * the first fenced ```json block after it.
- *
- * The separator is the first `---` at column 0 rather than the last, which matters for the skill
- * template specifically: its skeleton BEGINS with YAML frontmatter, so the file legitimately contains
- * two `---` lines in a row and taking the last one would swallow the frontmatter the skeleton exists to
- * provide.
- */
+/** After the first `---`, not the last: the skill template's skeleton opens with frontmatter of its own. */
 export function skeleton(kind, source) {
     const lines = source.split("\n");
     const at = lines.findIndex((line) => line.trimEnd() === "---");
@@ -91,14 +39,6 @@ export function skeleton(kind, source) {
     return `${body.slice(start, close).trim()}\n`;
 }
 
-/**
- * Where a scaffold lands, as a pure function of kind, name and target.
- *
- * A repo card resolves through the workspace's **declared** `repos` slot rather than through a
- * convention, because deriving a path a manifest does not declare is the tool inventing a slot — and a
- * workspace that disagrees with its own manifest on the day it was scaffolded is exactly the drift the
- * claims lint exists to catch.
- */
 export function destination(kind, name, target) {
     switch (kind) {
         case "skill":
@@ -109,12 +49,6 @@ export function destination(kind, name, target) {
             return path.join(target, `${name}.json`);
         case "repo-card": {
             const slot = declaredSlot(target, "repos");
-            // The slot value is the WORKSPACE's, not this tool's, and a `..` in it escapes:
-            // `path.join("/ws/sub", "../../evil")` is `/evil`, measured. (An *absolute* slot does not
-            // escape `join` — that is `resolve`'s behaviour, not `join`'s — so only the `..` half of the
-            // review that found this was right, and the fix is written against what was measured rather
-            // than against what was reported.) Checked after resolution, like every other containment
-            // question here. Copilot, round 3 on #156.
             const landing = path.resolve(target, slot, `${name}.md`);
             const root = path.resolve(target);
             if (landing !== root && !landing.startsWith(`${root}${path.sep}`)) {
@@ -131,7 +65,6 @@ export function destination(kind, name, target) {
     }
 }
 
-/** Reads one slot out of a workspace manifest, refusing rather than guessing when it is not declared. */
 function declaredSlot(workspaceDir, slot) {
     const manifestPath = path.join(workspaceDir, "workspace.json");
     let manifest;
@@ -157,18 +90,6 @@ function declaredSlot(workspaceDir, slot) {
     return declared;
 }
 
-/**
- * Which of the destination paths already exist, and which sit behind a symlink.
- *
- * `lstatSync`, never `existsSync`/`statSync` — both of those follow links, which is how `init` wrote
- * nine files outside a repository and reported success. A symlink is reported as its own state rather
- * than resolved and permitted: deciding whether a link's target is "really" inside the intended tree is
- * a containment judgement with a bad failure mode, where refusing has none.
- *
- * An existing **directory** is not a collision. This tool writes files into directories a user may
- * legitimately have created; refusing an empty directory would make `new` unusable in the ordinary case
- * and teach nobody anything.
- */
 export function collisions(paths, root = null) {
     const found = [];
     for (const target of paths) {
@@ -177,8 +98,6 @@ export function collisions(paths, root = null) {
             try {
                 stat = fs.lstatSync(step);
             } catch (cause) {
-                // Only ENOENT means absent. Anything else means the question could not be answered, and
-                // an unanswerable question must not be answered "no".
                 if (cause.code === "ENOENT") continue;
                 found.push({ path: step, why: "unreadable", detail: cause.code ?? cause.message });
                 break;
@@ -187,12 +106,6 @@ export function collisions(paths, root = null) {
                 found.push({ path: step, why: "symlink" });
                 break;
             }
-            // A DIRECTORY at the leaf is a collision too, and the paragraph above says the opposite —
-            // rightly, about the *intermediate* segments, and wrongly here: every path this plans is a
-            // file, so a directory sitting at one is something already there. Preflight passed and
-            // `writeFileSync` then threw `EISDIR` mid-loop, which is the ordering this whole function
-            // exists to prevent. Found by Copilot on #164 against the copy of this shape in
-            // `cli/vendor.mjs`; fixed in both, because a defect and its source are the same defect.
             if (step === target) {
                 if (stat.isDirectory()) found.push({ path: step, why: "directory" });
                 else found.push({ path: step, why: "exists" });
@@ -202,25 +115,7 @@ export function collisions(paths, root = null) {
     return found;
 }
 
-/**
- * The path steps from `root` down to `target`, inclusive of both — or every step to the filesystem root
- * when no root is given.
- *
- * **Where the boundary sits is the whole rule, and getting it wrong was found by running rather than by
- * reading.** The first cut walked to the filesystem root and refused any symlink anywhere on the chain.
- * On macOS `os.tmpdir()` resolves under `/var`, and `/var` is a symlink to `/private/var` — so every
- * scratch directory in this suite was refused, and by extension so was every user whose destination sat
- * under a symlinked mount, a home directory on a linked volume, or `/tmp`.
- *
- * The reason it was wrong is not that the check was too strict; it is that it asked about the wrong
- * paths. A symlink among the **ancestors of the directory the user named** is a fact about their
- * filesystem, and the user named that path — resolving it is not an escape, it is obeying them. A
- * symlink **at or below** the named path is different: those are the segments this tool derives and
- * creates, and a link there is precisely how `init` wrote nine files into an unrelated directory and
- * reported success (session 1, rounds 4 and 6, the write path and then the read path).
- *
- * So the boundary is the named destination. Above it, resolve. At it and below it, refuse.
- */
+/** `root` down to `target`, both included; links above `root` are the user's own, as macOS `/var` is. */
 function chain(target, root = null) {
     const steps = [];
     let at = target;
@@ -235,30 +130,13 @@ function chain(target, root = null) {
     return steps.reverse();
 }
 
-/** A path as a reader would recognise it — relative to cwd when that is shorter, absolute otherwise. */
 function display(target) {
     const rel = path.relative(process.cwd(), target);
     return rel && !rel.startsWith("..") && rel.length < target.length ? rel : target;
 }
 
-/**
- * Is this destination inside a `core/` — this checkout's or anybody's?
- *
- * The rule is about the LAYER, not about this repository: a vendored or installed copy of core is still
- * core, and a scaffold landing there is still an edit to a file the project ships. So two questions are
- * asked — is it inside THIS checkout's core, and does the resolved path contain a `core` directory that
- * looks like one (it holds `engine.md` or `templates/`).
- */
 export function intoCore(resolved) {
-    // **Compared case-INSENSITIVELY, because the filesystem may not care and `realpathSync` does not
-    // canonicalise case.** Measured by the pre-commit checkpoint on macOS: `--into <repo>/CORE/templates/x`
-    // exited 0 and created a directory inside the shipped `core/`. A case-sensitive compare is not a
-    // compare at all on a case-insensitive volume, which is the default on macOS and common on Windows.
-    //
-    // The cost, stated rather than discovered: on a case-SENSITIVE filesystem a directory genuinely named
-    // `CORE` — distinct from `core` — is also refused. That is a conservative refusal, and the asymmetry
-    // is the whole argument: refusing costs the user one corrected path, permitting costs an edit to a
-    // layer this project ships and the property row 7 states in the imperative.
+    // Case-folded: a volume may ignore case and `realpathSync` keeps it, so a genuine `CORE/` is refused too.
     const fold = (p) => p.toLowerCase();
     const ours = path.resolve(CORE);
     if (fold(resolved) === fold(ours) || fold(resolved).startsWith(fold(`${ours}${path.sep}`))) return ours;
@@ -271,16 +149,6 @@ export function intoCore(resolved) {
     return null;
 }
 
-/**
- * Parse the command line.
- *
- * A value beginning with **any** leading `-` is a missing value, not a value — session 1's round 9,
- * where `--residence -h` was consumed as the residence and the user was then blamed for a token they
- * typed as a flag. `-h` is the likeliest thing to land there and it is a help request.
- *
- * An empty string is refused for every flag, because none of them has a meaningful empty value and an
- * empty one reached a manifest once already, failing `minLength: 1` on the run that reported success.
- */
 export function parseArgs(argv) {
     const out = { kind: null, name: null, into: null, category: null, kindOf: null, governedBy: null, help: false, given: new Set() };
     const positional = [];
@@ -338,11 +206,7 @@ function usage() {
     ].join("\n");
 }
 
-/**
- * What a kind writes: a list of `{ path, contents }`. Multi-file kinds are planned in one place so the
- * collision check sees **every** path before the first byte is written — a partial write that wedges its
- * own retry is what session 1 shipped when the manifest went out first.
- */
+/** Every file a kind writes, planned whole so the collision check sees each path before the first byte. */
 export function plan(parsed) {
     const { kind, name } = parsed;
     const into = path.resolve(parsed.into ?? process.cwd());
@@ -386,7 +250,6 @@ export function plan(parsed) {
     return [{ path: destination(kind, name, into), contents: fill(body, { name }) }];
 }
 
-/** Substitutes the placeholders a scaffold can honestly know. Everything else stays in `{braces}`. */
 function fill(body, values) {
     let out = body;
     if (values.name !== undefined) out = out.replaceAll("{kebab-case-name}", values.name);
@@ -414,33 +277,9 @@ function packReadme(name, category) {
     ].join("\n");
 }
 
-/**
- * A workspace scaffold that is **green under `doctor` on the run after it is written**.
- *
- * That is a deliberate departure from what `init` does, and the reason is that the two tools are in
- * different situations rather than that one of them is wrong. `init` composes a checkpoints pack by
- * default because row 7 clause (a) says the cycle arrives opt-**out**, and nothing discovers a pack — so
- * its draft is red until a root is named, loudly and on purpose. `new workspace` composes no pack: it is
- * for a workspace somebody is authoring by hand, where a red first run would be a red the author did not
- * cause and cannot act on.
- *
- * `portfolio` is the default kind for the same reason. A `repository` workspace must declare `tree`, and
- * a scaffold that guesses which tree it governs would be a claim about the filesystem that the scaffold
- * cannot check — the claims lint would then grade a repository nobody chose.
- */
 function workspaceFiles(root, name, wkind, body, governedBy = null) {
-    // A POINTER carries `governed_by` and NONE of the governing keys — no slots, no verify, no gates.
-    // The Workspace Definition requires the first and `doctor` refuses the second, so a pointer built
-    // from the governing shape is red on the run after it is written. Copilot's suppressed notes on #156
-    // caught it, twice on one file: the scaffolder always wrote the governing shape while the help screen
-    // advertised `pointer` as a supported kind. That is this session's own recurring defect for the third
-    // time — a scaffold failing the validation that lives beside it — so it is fixed rather than triaged.
     if (wkind === "pointer") {
-        // 2.7, not the newest definition: a writer declares the version its OUTPUT needs, and a pointer
-        // needs 2.7 — the version that added the kind. Nothing scaffolded here declares a key from a
-        // later MINOR, so claiming one would narrow the manifest against adopter tooling pinned at 2.7
-        // for a contract it does not use. Same rule as `cli/init.mjs`'s and `cli/vendor.mjs`'s `SPEC`,
-        // and as the `GATE_POLICY_SPEC = "2.2"` beside them.
+        // 2.7 added the pointer kind; a writer declares the version its output needs, not the newest.
         const manifest = { portulan: { spec: "2.7" }, name, kind: "pointer", governed_by: { workspace: governedBy } };
         return [
             { path: path.join(root, "workspace.json"), contents: `${JSON.stringify(manifest, null, 2)}\n` },
@@ -462,21 +301,12 @@ function workspaceFiles(root, name, wkind, body, governedBy = null) {
     }
 
     const manifest = {
-        // The version this output NEEDS, not the newest one — see the pointer branch above.
+        // The version this output needs, not the newest.
         portulan: { spec: "2.7" },
         name,
         summary: `{One line: whose workspace this is and what it governs.}`,
         kind: wkind,
-        // `repos` is declared and its directory scaffolded so the six kinds compose end-to-end from
-        // `new` alone: without it, `new repo-card --into <a workspace new just wrote>` exits 2 because
-        // the manifest declares nowhere for a card to land. A tool whose own output cannot host its own
-        // next command is a tool with a seam in the middle of it.
         slots: { identity: "identity.md", principles: "principles.md", gates: "gate-map.md", repos: "repos/" },
-        // The schema requires a `verify` block on every workspace that is not a pointer, so this is not
-        // optional and a scaffold omitting it is red on the run after it is written. What it must NOT be
-        // is a stub exiting 0: the author has not said what green means here yet, and a false green under
-        // every gate from the day the workspace was created is the worst artifact this tool could emit.
-        // Exit 2 — could not run — is the honest state, and it is the same answer `init` reached.
         verify: {
             default: "unset",
             recipes: [{ id: "unset", run: "./verify/unset.sh", requires: ["bash"], doc: "verify/README.md" }],
@@ -496,15 +326,6 @@ function workspaceFiles(root, name, wkind, body, governedBy = null) {
     ];
 }
 
-/**
- * The recipe a scaffolded workspace starts with: one that **exits 2**, meaning *could not run*.
- *
- * It is deliberately not a stub exiting 0. A verify recipe is what decides what *done* means for a
- * workspace, the Stop-gate runs the default, and a recipe returning green before anybody has said what
- * green means would put a false pass under every gate the workspace has — on day one, in the artifact
- * meant to welcome the author. The three-code discipline exists exactly for this: a recipe that cannot
- * run must never be indistinguishable from one that ran and passed.
- */
 function unsetRecipe(name) {
     return [
         "#!/usr/bin/env bash",
@@ -611,8 +432,6 @@ export function run(argv, options = {}) {
 
         const into = path.resolve(parsed.into ?? process.cwd());
 
-        // Refused before the template is even read: the destination is the question, and a `core/` answer
-        // is refused whether it was reached by name, by `..`, or by a link.
         const linkAt = firstLink(into);
         if (linkAt) {
             say(
@@ -623,9 +442,6 @@ export function run(argv, options = {}) {
         }
         const core = intoCore(realOrSelf(into));
         if (core) {
-            // Phrased against the RESOLVED destination rather than the argument as typed, because the two
-            // differ in exactly the cases worth naming — `packs/../core` and a link — and a refusal that
-            // echoes the argument back tells the reader nothing they did not already type.
             const resolved = realOrSelf(into);
             say(
                 `new: that destination resolves to ${resolved === core ? `\`${core}\`` : `${resolved}, inside \`${core}\``}, ` +
@@ -643,9 +459,7 @@ export function run(argv, options = {}) {
             return 2;
         }
 
-        // The manifest is written LAST for the multi-file kinds, so an I/O failure mid-loop cannot leave a
-        // torso that a later run reads as a finished artifact — session 1's partial write, which wedged
-        // its own retry and refused it with a sentence that was false.
+        // The manifest last, so a failure mid-loop leaves nothing a later run reads as finished.
         const ordered = [...files].sort((a, b) => Number(manifestish(a.path)) - Number(manifestish(b.path)));
         for (const file of ordered) {
             fs.mkdirSync(path.dirname(file.path), { recursive: true });
@@ -656,10 +470,6 @@ export function run(argv, options = {}) {
         for (const file of files) say(`  ${display(file.path)}`);
         say("");
         say(`It is a draft — the placeholders in \`{braces}\` are yours to fill. Then: portulan doctor <workspace-dir>`);
-        // What a scaffold CANNOT do for you, said at the moment it matters rather than in a README nobody
-        // opens next. This tool never edits a file it did not write — a manifest is a curated layer, and
-        // a generator that rewrites one is the generator that eventually rewrites the wrong one — so the
-        // wiring step is the author's, and leaving it unsaid would produce a file nothing reads.
         for (const line of wiring(parsed.kind, parsed.name, parsed.category, into)) say(line);
         return 0;
     } catch (error) {
@@ -670,24 +480,12 @@ export function run(argv, options = {}) {
 
 const manifestish = (p) => /(?:workspace|pack)\.json$/.test(p);
 
-/**
- * The step a scaffold cannot take for the author: declaring the thing it just wrote.
- *
- * Nothing here edits a manifest the tool did not write in the same run. That is deliberate and it is the
- * same rule `init` settled — a manifest is part of the curated layer, and a generator that edits one is
- * the generator that eventually edits the wrong one. The cost of that rule is a file nothing references,
- * so the cost is paid out loud, here, at the moment the file lands.
- */
+/** Said rather than done: nothing here edits a manifest it did not write in the same run. */
 function wiring(kind, name, category, target) {
     switch (kind) {
         case "gate-policy":
             return ["", `Nothing reads it yet: add \`"gates": "${name}.json"\` to the workspace's \`workspace.json\`, then \`portulan compile\`.`];
         case "skill": {
-            // **Say only what was actually checked.** The previous version read whether a `pack.json`
-            // EXISTED and then made a claim about what it DECLARES — which is the same defect one level
-            // down: a pack declaring `contributes.skills: ["parts/"]` was told `skills/` is "already
-            // declared", and a skill landing under a declared root was told nothing declares it. Found
-            // by review, inside the fix for that exact class.
             let roots = null;
             try {
                 roots = JSON.parse(fs.readFileSync(path.join(target ?? ".", "pack.json"), "utf8"))?.contributes?.skills ?? [];
@@ -713,20 +511,7 @@ function wiring(kind, name, category, target) {
     }
 }
 
-/**
- * The destination as the filesystem actually sees it, **including when it does not exist yet**.
- *
- * The first cut was `try { realpathSync(t) } catch { return path.resolve(t) }` — and the catch is not
- * the rare branch, it is the **ordinary** one: a scaffolding tool's destination usually does not exist.
- * So whenever the leaf was new, this returned an unresolved path and the `core/` check graded a string
- * the filesystem had never confirmed. Measured by the pre-commit checkpoint: a symlink whose target is
- * `core/`, plus a leaf one level below it, wrote into the shipped `core/` and exited 0. The file header
- * two hundred lines up promised "the check resolves first and compares after"; it did, only when the
- * destination already existed, which is the case that matters least.
- *
- * So: realpath the nearest **existing** ancestor and re-append the unresolved tail. That resolves every
- * link on the part of the path that exists — which is the only part a link can be on.
- */
+/** The realpath of the nearest existing ancestor, with the part not created yet appended. */
 function realOrSelf(target) {
     let head = path.resolve(target);
     const tail = [];
@@ -734,8 +519,6 @@ function realOrSelf(target) {
         try {
             return tail.length ? path.join(fs.realpathSync(head), ...tail) : fs.realpathSync(head);
         } catch (cause) {
-            // Only ENOENT means "not there yet, keep walking up". Anything else means the question could
-            // not be answered, and an unanswerable question must not be answered "fine".
             if (cause.code !== "ENOENT") {
                 throw new NewError(
                     `${display(head)} could not be resolved — ${cause.code ?? cause.message}. Refusing rather than grading a path nothing confirmed`,
@@ -750,29 +533,15 @@ function realOrSelf(target) {
     return path.resolve(target);
 }
 
-/**
- * Is the destination the user named itself a symlink?
- *
- * Only the named path is asked about here, not its ancestors — see `chain` for why that boundary is the
- * rule rather than a convenience. A user who points `--into` at a link is refused rather than followed,
- * because deciding whether a link's target is "really" where they meant is a containment judgement with
- * a bad failure mode, where refusing has none and costs one `realpath` of typing.
- */
 function firstLink(target) {
     try {
         return fs.lstatSync(target).isSymbolicLink() ? target : null;
     } catch (cause) {
-        // Only ENOENT means absent — a destination that does not exist yet is the ordinary case here.
         if (cause.code === "ENOENT") return null;
         throw new NewError(`${display(target)} could not be read — ${cause.code ?? cause.message}. Only a missing path means "nothing there", so nothing was written`);
     }
 }
 
-/**
- * One line per cause, not one per path. Session 1 learned this the hard way: a single symlinked
- * directory made the refusal name the same cause ten times, and a refusal nobody finishes reading is a
- * refusal that failed to explain.
- */
 function groupByCause(clash) {
     const by = new Map();
     for (const item of clash) {

package/cli/pack-identity.mjs

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