@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/cli/release-eval.mjs

@@ -1,86 +1,6 @@
 #!/usr/bin/env node
 // Portulan — the eval result a release carries.
 //
-// Milestone 8's ninth clause: *a release carries an eval result*. `../docs/plan.md`'s Protocol →
-// Versioning has carried the obligation since the plan was locked — *"from milestone 8, releases carry
-// an eval result"* — and the maintainer's ruling of 2026-08-24 made it bind row 8's close. The
-// legislative history is `../docs/milestones/m08.md`; the criterion itself is the row, and this file
-// deliberately restates neither.
-//
-// ## The three things the amendment left open, and what this module settles
-//
-// The 2026-08-24 amendment named what it did **not** settle: *"what an eval result attached to a
-// release consists of, where it is carried (the changelog entry, the release body, a file in the
-// payload), and whether a release with no eval result is refused by a rail or by a person. Those are
-// this row's remaining work, not this amendment's content."*
-//
-//  1. **What it consists of.** The verdict every recipe the workspace YIELDS returned, measured by
-//     running them, plus the identity of the A/B baseline the release ships against. Not a summary
-//     anybody types.
-//  2. **Where it is carried.** One file per version, `evals/releases/<version>.md`, rendered from
-//     `evals/releases/<version>.json`. `CHANGELOG.md` and the release body CITE it and restate no
-//     figure — a rule with two carriers is obeyed at the narrower one.
-//  3. **Rail or person — it is BOTH, and the split is the honest answer.** A rail reaches the tree: a
-//     governed version with no record, a record that disagrees with its capture, a record listing a red
-//     rail. A rail reaches **no tag and no published release body** — `../.portulan/gate-map.md` keeps
-//     `tag-a-release` and `publish-a-release` Gated, and those happen outside any tree a check can
-//     read. Answering "a rail" flat would have claimed a reach this has not got. The split is the shape
-//     the drill calendar already uses for its own two halves.
-//
-// ## The subject is EVERY governed release, not the tree's current cut state — two wrong designs first
-//
-// The obvious cut-detector is `CHANGELOG.md`'s **top** heading: rename `## Unreleased` to a version and
-// the tree is a cut. **It never fires.** The cut commit RE-SEEDS the accumulator — `b410c020` renamed
-// the heading to `## 0.1.2 — 2026-08-20` and put a fresh `## Unreleased` back above it in the same
-// commit, which `CHANGELOG.md`'s own header requires so the tagged tree contains its own entry. So the
-// top heading is `Unreleased` on every commit including the cut, and a rail keyed to it would have
-// reported *no cut in this tree* on precisely the tree it was built to grade.
-//
-// The second design keyed off `package.json`'s `version` alone — what actually moves at a cut, and what
-// `./version-carriers.mjs` grades the prose against. It fires, and it **protects one release at a
-// time**: once `0.1.4` is declared, `0.1.3`'s record can be deleted or corrupted and nothing reds. A
-// rail over a record layer that only ever grades the newest record is not a rail over the record layer.
-//
-// So the subject is **every version `CHANGELOG.md` records**, from `FIRST_GOVERNED_VERSION` onward,
-// permanently — plus one cut-integrity check that holds between cuts as well as at one: the newest
-// version heading must be the version `package.json` declares. Both findings were the second opinion's,
-// caught before a line of the rail was written and recorded here rather than in a later repair.
-
-// ## What this cannot reach, and the one surface that can
-//
-// The heading rename happens *"in a change merged before the tag is created"* — `CHANGELOG.md`'s own
-// header — and that ordering is human-owned prose in a file that says of its neighbouring rule *"nothing
-// checks this"*. A maintainer who tags a commit whose accumulator was never renamed produces a release
-// no tree state ever flagged **where nothing else moved either** — `--verify` is green on such a tree,
-// since `package.json` and the heading still agree with each other. Where the version WAS bumped and a
-// record written, `--verify` reds it here on the pull request; what no rail sees is that same tree
-// reached by a tag rather than by a merge, since `--tagged` below never reads `CHANGELOG.md`.
-//
-// `../.github/workflows/publish-github-packages.yml` fires on `release: published` and checks out the
-// tag — the one mechanical surface at the release act itself — and it runs `--tagged` below against that
-// checkout. That is the half a rail can reach at the moment a person acts; the rest stays Gated and is
-// carried in `../.portulan/gate-map.md`.
-//
-// ## Read the WORKTREE, where `./version-carriers.mjs` reads the index — and the difference is the point
-//
-// That module reads `package.json` and the prose it compares **both** from the git index, because
-// comparing worktree prose against an index version compares two trees. Its recorded residual is that an
-// **unstaged** cut is therefore invisible to it: run against a fully-edited worktree it reported a green
-// about a tree that no longer existed.
-//
-// This module reads the worktree, uniformly, both the version and the record. `../.portulan/dod.md`
-// condition 1 asks that every recipe ran green *in this working copy*, and there is no cross-tree
-// comparison here to protect — the record and the version are read from one tree either way. Inheriting
-// the index read would have inherited that residual for nothing.
-//
-// ## `0.1.0`–`0.1.2` are out of scope, by the Protocol's own words
-//
-// *"**From milestone 8**, releases carry an eval result."* Three releases predate the clause and carry
-// none. `FIRST_GOVERNED_VERSION` is the boundary, and it is a **historical constant** rather than a
-// hand-maintained figure of a moving subject: which releases predate a ruling cannot change. The
-// distinction matters because this repository deletes hand-maintained figures on sight, and the reason
-// it does is that their subject moves. This one's does not.
-//
 // Exit 0 green · 1 a finding · 2 could not run.
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
@@ -90,46 +10,25 @@ import { pathToFileURL } from "node:url";
 
 import { recipeSet, resolverFor } from "./recipe-set.mjs";
 
-/** Raised when a precondition fails. Always exit 2 — never a finding about a release. */
+/** A failed precondition: always exit 2, never a finding about a release. */
 export class CouldNotRun extends Error {}
 
-/** Where a version's record lives. Both halves, because one carrier is a pair here as it is for the baseline. */
 export const RECORD_DIR = "evals/releases";
 export const snapshotPath = (version) => `${RECORD_DIR}/${version}.json`;
 export const registerPath = (version) => `${RECORD_DIR}/${version}.md`;
 
-/**
- * The first release the clause governs.
- *
- * `../docs/plan.md`'s Protocol → Versioning: *"from milestone 8, releases carry an eval result"*.
- * `v0.1.0`, `v0.1.1` and `v0.1.2` were cut before that clause had an owner — it belonged to no row
- * until 2026-08-24 — so they carry no record and this rail does not invent one for them. A retro-fitted
- * record would be a capture nobody ran, which is the one thing an eval result may not be.
- */
 export const FIRST_GOVERNED_VERSION = "0.1.3";
 
-/**
- * This module's own recipe id, excluded from every capture it writes.
- *
- * **The capture cannot be accurate about itself and the exclusion is the only honest resolution.**
- * `release-eval` is a yielded recipe, so its verdict would enter the record it lives inside: captured
- * before the record is written it is red, because the governed version has no record; captured after,
- * the capture is stale the moment the register is rendered from it. Every ordering is wrong. So its row
- * is excluded and the exclusion is PRINTED in the register — a dropped row that says nothing is how a
- * record starts implying a green nobody measured.
- */
+// The payload does not carry `evals/ab/`, so from this version a register cites it at the release's tag.
+// Earlier registers keep rendering the relative link npm froze into their tarballs.
+export const PINNED_FROM = "0.2.0";
+export const REPOSITORY = "https://github.com/sleepy-panda-srl/portulan";
+
 export const SELF = "release-eval";
 
-/** `X.Y.Z` and nothing else. A prerelease or a build tag is could-not-run rather than a guess at ordering. */
 const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
 
-/**
- * Compare two `X.Y.Z` versions. Throws `CouldNotRun` on anything else.
- *
- * Deliberately not a general semver comparator: this repository ships `X.Y.Z` and nothing more, and a
- * partial implementation that silently mis-orders a prerelease would decide whether a release is
- * governed. Refusing is the answer that cannot be quietly wrong.
- */
+/** Throws `CouldNotRun` on anything but `X.Y.Z` rather than guess where a prerelease falls. */
 export function compareVersions(a, b) {
     const pa = SEMVER.exec(a);
     const pb = SEMVER.exec(b);
@@ -142,12 +41,11 @@ export function compareVersions(a, b) {
     return 0;
 }
 
-/** Whether the clause governs this version. */
 export function isGoverned(version) {
     return compareVersions(version, FIRST_GOVERNED_VERSION) >= 0;
 }
 
-/** `package.json`'s version, from the worktree. See the header for why not the index. */
+/** Read from the worktree, not the index, so an unstaged cut is graded too. */
 export function declaredVersion(root) {
     let raw;
     try {
@@ -165,17 +63,7 @@ export function declaredVersion(root) {
     return v.trim();
 }
 
-/**
- * Every version `CHANGELOG.md` records, newest first.
- *
- * **This is the released set, and it is the rail's subject.** `../CHANGELOG.md` carries one `## X.Y.Z —
- * DATE` heading per release and one `## Unreleased` accumulator that is re-seeded at every cut, so the
- * version headings are the releases and the accumulator is never one. A heading is matched only in
- * column 0 at depth 2, because the entries below quote their own retired headings — and **fenced
- * regions are skipped**, because a worked example of a cut belongs in one and would otherwise enter the
- * released set as a phantom release. A version-shaped heading that is not `X.Y.Z` is refused rather than
- * skipped, so the subject list cannot decide by omission what `compareVersions` refuses out loud.
- */
+/** Every `## X.Y.Z` heading in file order, which is newest first. */
 export function changelogVersions(root) {
     let text;
     try {
@@ -186,10 +74,7 @@ export function changelogVersions(root) {
     const out = [];
     let fenced = false;
     for (const line of text.split("\n")) {
-        // **Fenced regions are skipped**, because a column-0 fence is exactly where this file would show
-        // a reader what a cut looks like — and a worked example naming `## 9.9.9` would enter the
-        // released set as a phantom, producing a false red on both the cut-integrity arm and the
-        // missing-record arm. Latent today; the docstring above claimed a robustness the fence broke.
+        // A fence may hold a worked example of a cut, and its heading is no release.
         if (/^(```|~~~)/.test(line)) {
             fenced = !fenced;
             continue;
@@ -200,10 +85,6 @@ export function changelogVersions(root) {
             out.push(m[1]);
             continue;
         }
-        // **A version-shaped heading this cannot order is REFUSED, never skipped.** `compareVersions`
-        // refuses a prerelease loudly on the ground that a partial ordering would silently decide whether
-        // a release is governed — and the subject-list builder was dropping `## 0.1.3-rc.1` without a
-        // word, which decides the same thing by omission. The two halves now agree.
         if (/^## \d/.test(line)) {
             throw new CouldNotRun(
                 `CHANGELOG.md carries the release heading ${JSON.stringify(line.trim())}, which is not \`## X.Y.Z\` — this rail ` +
@@ -215,7 +96,6 @@ export function changelogVersions(root) {
     return out;
 }
 
-/** The commit this capture was taken at, and whether the tree was clean when it was. */
 export function sourceOf(root) {
     let commit;
     try {
@@ -232,12 +112,7 @@ export function sourceOf(root) {
     return { commit, clean };
 }
 
-/**
- * The recipe set this workspace yields, pinned.
- *
- * The root is **named**, so it replaces every other source and this answer is about the tree rather than
- * about the machine — the same reason `./drills.mjs`'s recipe and `./goldens.mjs`'s pin theirs.
- */
+/** A named pack root wins outright over discovery, so the set depends on the tree, never on the machine. */
 export function yieldedRecipes({ root, workspace = ".portulan", packRoot = "packs" }) {
     const workspaceDir = path.join(root, workspace);
     let manifest;
@@ -257,19 +132,7 @@ export function yieldedRecipes({ root, workspace = ".portulan", packRoot = "pack
     return set.recipes.map((r) => ({ id: r.id, run: r.run }));
 }
 
-/**
- * The A/B baseline this release ships against — its IDENTITY, never its figures.
- *
- * **Restating the cells here would be the defect this whole module is arranged against.** The figures
- * have a carrier — `evals/ab/baseline.json`, and `evals/ab/baseline.md` rendered from it and
- * byte-compared by the `ab-run` recipe — and a second copy of them in a per-release record is a
- * hand-maintained figure of a moving subject wearing a machine-written costume. What a release record
- * owes its reader is *which* baseline it shipped against and where to read it, so that is what this
- * returns: path, capture date, the commit it was taken at, and whether that tree was clean.
- *
- * Returns `null` where no baseline is committed, which a release may legitimately be in — and the
- * register then says so rather than rendering a hole.
- */
+/** The A/B baseline's identity alone, since its figures have their own carrier; `null` when none is committed. */
 export function abBaselineIdentity(root) {
     const snapshot = "evals/ab/baseline.json";
     const abs = path.join(root, snapshot);
@@ -280,11 +143,7 @@ export function abBaselineIdentity(root) {
     } catch (e) {
         throw new CouldNotRun(`the A/B baseline at ${snapshot} is not valid JSON: ${e.message}`);
     }
-    // **Read through, and coerce nothing.** A first cut mapped a missing field to `null`, which the
-    // renderer then printed as `<undated>` / `<uncommitted>` — so a baseline whose capture lacked those
-    // fields produced a perfectly well-formed register naming a placeholder, and the derived probe below
-    // saw no hole because a fallback had filled it. Reading through means an absent field arrives as
-    // `undefined`, renders as `undefined`, and is refused before anything is written. Fail closed.
+    // No fallbacks: an absent field stays `undefined` so that `verifyShape` refuses it.
     return {
         snapshot,
         register: "evals/ab/baseline.md",
@@ -294,32 +153,17 @@ export function abBaselineIdentity(root) {
     };
 }
 
-/**
- * The limitations, DERIVED from the capture rather than fixed.
- *
- * 6d round 2's finding, and it is this milestone's signature defect: a limitation asserted flat about a
- * field the capture may or may not hold is a false sentence waiting for its first counterexample. That
- * block asserted *"the model is not recorded"* while the harness had just begun recording one.
- */
 export function limitationsFor(snap) {
     const out = [
         "**A green says this record agrees with its own capture — never that the release is good.** Every " +
             "line below is what the recipes returned at one commit, and a recipe's own green establishes only what " +
             "that recipe's documentation says it establishes.",
-        // No `??` here either — the fallback survived one round of removing them, in the block whose
-        // subject is claims a capture never made, so a null-commit record printed `null` in its table and
-        // `<commit>` in its limitations. `verifyShape` refuses such a capture before this is reached.
         `**The recipes were not run at the tag.** They ran at \`${snap?.source?.commit}\`, and this record is ` +
             "committed *in* the cut change — so the tagged tree is this commit plus whatever that change still adds " +
             "after the capture, the record itself at minimum. A record cannot be captured at a commit that does not " +
             "exist yet, and printing the one it was captured at is the only honest form.",
         `**\`${SELF}\` is excluded from the rows above**, because a capture cannot be accurate about the record it is inside. ` +
             "Its verdict for this release is the rail's own run on the pull request that carries this file.",
-        // **The record ships inside the npm payload, so it is read where nothing around it says what it
-        // is about.** In a consumer's `node_modules` a table headed *"N of M recipes this workspace
-        // yielded"* invites being read as a claim about THEIR workspace. It is a claim about this
-        // repository's own build and nothing else, and the sentence saying so travels with the document
-        // rather than living in a README that does not.
         "**This record measures the Portulan repository's own build**, at the commit named above — never the workspace, " +
             "project or package this release is installed into. Nothing here has looked at your tree.",
     ];
@@ -338,7 +182,7 @@ export function limitationsFor(snap) {
     return out;
 }
 
-/** The register, rendered from the capture. The one place a release's eval result is written for a reader. */
+/** No fallbacks, here or in `limitationsFor`: a missing field must render as a hole that `verifyShape` refuses. */
 export function renderRegister(snap) {
     const L = [];
     L.push(`# Eval result — Portulan ${snap.version}`);
@@ -383,11 +227,10 @@ export function renderRegister(snap) {
     if (snap.abBaseline === null) {
         L.push("None is committed in this tree.");
     } else {
-        // No `??` fallbacks: a missing field must render as a hole the derived check refuses, never as a
-        // placeholder that reads like a measurement. `clean` is the exception by nature — it renders as a
-        // branch — and is therefore checked by name in `verifyShape`.
+        const pinned = SEMVER.test(String(snap.version)) && compareVersions(snap.version, PINNED_FROM) >= 0;
+        const href = pinned ? `${REPOSITORY}/blob/v${snap.version}/${snap.abBaseline.register}` : `../../${snap.abBaseline.register}`;
         L.push(
-            `[\`${snap.abBaseline.register}\`](../../${snap.abBaseline.register}), rendered from ` +
+            `[\`${snap.abBaseline.register}\`](${href}), rendered from ` +
                 `\`${snap.abBaseline.snapshot}\` — captured ${snap.abBaseline.captured} at ` +
                 `\`${snap.abBaseline.commit}\`, over a tree that was ` +
                 `${snap.abBaseline.clean === true ? "clean" : "**not clean**"}.`,
@@ -403,73 +246,17 @@ export function renderRegister(snap) {
     return L.join("\n");
 }
 
-/**
- * The shape check, DERIVED from the renderer — and it runs before any render a caller trusts.
- *
- * 6d rounds 3, 4, 6 and 7 arrived at this shape over five rounds and it is adopted rather than
- * re-derived: report rather than throw; check **before** rendering rather than after; check what is
- * dereferenced rather than what is typed; and derive the list from the renderer instead of hand-writing
- * another function's reads, because a hand-written one goes stale the moment the renderer reads one more
- * thing.
- *
- * **The derived check is blind to anything the renderer supplies a value for**, and that is the whole of
- * its limit rather than "one boolean". A first cut of this module claimed exactly one blind spot and had
- * three: `abBaseline.captured` and `abBaseline.commit` were read through `??` fallbacks, so absence
- * printed `<undated>` and `<uncommitted>` — placeholders that read like measurements — and
- * `abBaseline.clean: null` was *explicitly permitted* by the check whose message said its absence must
- * not publish an unmeasured claim, then rendered as `**not clean**`. Caught by a fresh context deleting
- * every field the renderer reads, one at a time, which is the only way this class is ever found.
- *
- * So there are **four** rules, and each after the first was a further round of this same defect — which
- * is the honest way to carry the count, since a docblock claiming totality is what the last two rounds
- * caught this file doing. (1) The
- * renderer supplies no fallback, so absence renders as a hole. (2) Every field that renders as a
- * **branch** rather than a value is checked here by name, because no hole appears for those — only the
- * meaning is invented. (3) **No leaf may be `null` and no string leaf may be blank**, because a
- * present-degenerate value is neither absent nor a branch: `${null}` renders the four characters `null`
- * and `""` renders nothing at all, so the document comes out well-formed and the probe below — which
- * looks for `undefined` and `NaN` — sees a clean page. Six of these passed a check that had just been
- * hardened against exactly this class and whose comment claimed two rules were the whole of it.
- *
- * Rule 3 is **structural rather than a list of fields**: it walks the capture's own leaves. A
- * hand-written roster of "fields that must be non-empty" is the defect this file has now met at three
- * depths, and it would go stale the moment the renderer read one more. (4) **A field that names a commit
- * must look like one** — rule 3 is a floor under every leaf and a *name* check for none, so
- * `source.commit: "banana"` passed it, and `"HEAD"` passed while reading like an answer. Rules 3 and 4
- * are different questions about the same leaf: *is anything there* and *is it the kind of thing it
- * claims to be*.
- */
-/** `YYYY-MM-DD`. A capture that stamps itself from anything else cannot be reproduced, and it is printed. */
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 
-/**
- * A full object name — 40 hex for SHA-1, 64 for a SHA-256 repository.
- *
- * **A commit field is a NAME, and a name-shaped check is the only one that can tell a commit from a
- * word.** `source.commit: "banana"` passed shape, the render probe and the non-blank walk alike, because
- * it is a present, non-empty string that renders perfectly — and `"HEAD"` passed too, which is worse,
- * since it reads like an answer. The record's central claim is that it was measured *at a named commit*;
- * without this the claim is satisfied by any prose at all. Copilot's round 1 on
- * [#381](https://github.com/sleepy-panda-srl/portulan/pull/381), and it is the degenerate-value class one
- * field further in than the round before it reached: rule 3 asks whether a leaf is *present and
- * non-blank*, which is a floor under every field and a name check for none.
- *
- * Abbreviated shas are refused. Nothing here writes one — `sourceOf` runs `git rev-parse HEAD` — and a
- * short name is ambiguous in exactly the way a record meant to be re-derived cannot afford.
- */
+/** A full SHA-1 or SHA-256 name: an abbreviated one can become ambiguous. */
 const OBJECT_NAME = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 
-/**
- * Every leaf of the capture, as a dotted path — the subject of rule 3 above.
- *
- * `abBaseline: null` is the one legitimate null and is skipped by the caller rather than exempted here,
- * because an exemption inside a total walk is how a second one gets added later without argument.
- */
 function leafPaths(value, prefix = []) {
     if (value === null || typeof value !== "object") return [[prefix, value]];
     return Object.entries(value).flatMap(([k, v]) => leafPaths(v, [...prefix, k]));
 }
 
+/** Every reason this capture cannot be rendered truthfully; empty when it can. */
 export function verifyShape(snap) {
     const red = [];
     if (snap?.portulan?.releaseEval !== "1") red.push("the record does not declare `portulan.releaseEval: \"1\"` — this is not a release eval capture");
@@ -495,11 +282,6 @@ export function verifyShape(snap) {
     for (const field of ["source", "host"]) {
         if (snap?.[field] === undefined || snap[field] === null) red.push(`the record has no \`${field}\`, which the register prints among the release's conditions`);
     }
-    // **The host's two fields are printed as conditions, so they are strings or they are a claim nobody
-    // measured.** Found by sweeping rule 4's *class* — a type-conditional guard — across this file rather
-    // than by fixing the site the note named: `host.node: 22` rendered `` `22` `` and passed everything.
-    // `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` is the reason the sweep
-    // happened at all, and this is the site it turned up that round 4 did not name.
     if (snap?.host !== undefined && snap?.host !== null) {
         for (const k of ["node", "platform"]) {
             if (typeof snap.host[k] !== "string") {
@@ -507,28 +289,15 @@ export function verifyShape(snap) {
             }
         }
     }
-    // **The booleans, explicitly** — the derived check's one blind spot, measured rather than reasoned.
     if (snap?.source !== undefined && snap?.source !== null && typeof snap.source.clean !== "boolean") {
         red.push("the record's `source.clean` is not a boolean — it renders as a branch, so its absence would publish a claim about the tree that the capture never made");
     }
-    // **`null` was permitted here and it renders as `**not clean**`** — a claim about the baseline's tree
-    // that the capture never made, published by the check whose own message said absence must not do
-    // that. Permitting the third state defeated the check in the same line that stated it. Strict.
     if (snap?.abBaseline !== null && snap?.abBaseline !== undefined && typeof snap.abBaseline.clean !== "boolean") {
         red.push("the record's `abBaseline.clean` is not a boolean — it renders as a branch, so anything else would assert a dirty baseline tree the capture never recorded");
     }
     if (snap?.abBaseline === undefined) {
         red.push("the record has no `abBaseline` — `null` is how *no baseline* is recorded, and an absent field renders as one without ever having been measured");
     }
-    // **Rule 4: a field that names a commit must BE a string that names one.** See `OBJECT_NAME`.
-    //
-    // **The guard's shape is the finding, not the pattern.** Written as *"if it is a string, validate
-    // it"*, the check skipped every value that was not a string — so `source.commit: 1234567890` rendered
-    // `` `1234567890` ``, `true` rendered `` `true` ``, and `["a"]` rendered `` `a` ``, each a plausible
-    // measurement passing a check whose whole subject is that field. A type-conditional guard is not a
-    // guard over the field; it is a guard over the field *when someone already used the right type*.
-    // Copilot round 4, and the same shape as rule 3's own origin: `is anything there` and `is it the kind
-    // of thing it claims to be` have to be asked of the value, never of the value's type.
     const commitFields = [
         ["source.commit", snap?.source, "the record's central claim is that it was measured at a named commit"],
         ["abBaseline.commit", snap?.abBaseline, "a baseline cited by a name nothing can resolve is cited by nothing"],
@@ -540,18 +309,11 @@ export function verifyShape(snap) {
             red.push(`the record's \`${label}\` is ${JSON.stringify(value)}, which is not a full object name — ${why}`);
         }
     }
-    // **No `.trim()`**, and its presence here was the degenerate-value class once more. Trimming before
-    // the test accepted `"2026-09-01 "` and the renderer then printed the padding into the table —
-    // a value that passes a format check and violates the format it was checked against. A check that
-    // normalises its input is checking something other than what will be published. Copilot round 3.
+    // Not trimmed: the value is printed as is, so it is checked as is.
     if (typeof snap?.captured === "string" && !ISO_DATE.test(snap.captured)) {
         red.push(`the record's \`captured\` is ${JSON.stringify(snap.captured)}, which is not a \`YYYY-MM-DD\` date — it is printed as one`);
     }
 
-    // **Rule 3: no leaf is `null`, no string leaf is blank.** A present-degenerate value renders as a
-    // value, so neither the fallback rule nor the branch checks nor the probe below can see it: `null`
-    // prints the text `null` into a table cell and `""` prints nothing, and the register comes out
-    // looking measured. Structural rather than a field list, for the reason the docblock gives.
     if (snap !== null && typeof snap === "object") {
         const skip = snap.abBaseline === null ? "abBaseline" : null;
         for (const [pathParts, leaf] of leafPaths(snap)) {
@@ -567,9 +329,6 @@ export function verifyShape(snap) {
 
     if (red.length > 0) return red;
 
-    // **The list above is not the check; this is.** Render, and refuse a document that came out carrying
-    // `undefined` or `NaN`. Anything the renderer reads and the capture lacks reds here without anybody
-    // listing it, including reads added later.
     let rendered;
     try {
         rendered = renderRegister(snap);
@@ -585,24 +344,11 @@ export function verifyShape(snap) {
     return red;
 }
 
-/**
- * The rail's verdict over one record.
- *
- * **Totality against the LIVE recipe set is deliberately not checked**, and the reason is that a record
- * is a historical fact. A recipe added after `0.1.3` was cut does not make `0.1.3`'s record wrong; it
- * makes it a record of an earlier tree, which is what it is for. Totality is a **capture-time** property
- * — `--capture` runs whatever the workspace yields at that moment — and the register prints how many
- * that was. A verify-time totality check would turn every past release red on the commit that adds a
- * rail.
- */
+/** Checks a record against its own capture, never the live recipe set: a recipe added later does not make it wrong. */
 export function verifyRecord(snap, { version, keyedBy = "the file it is named for" }) {
     const red = verifyShape(snap);
     if (red.length > 0) return red;
     if (snap.version !== version) {
-        // The source of `version` is named rather than assumed: `--verify` keys every release but the
-        // newest from `CHANGELOG.md`, so a message hard-coding *package.json declares* would have been
-        // false for all of them — a diagnostic pointing at the wrong file is a diagnostic that sends the
-        // next reader to the wrong place.
         red.push(`the record declares version \`${snap.version}\` where ${keyedBy} says \`${version}\` — a record keyed to another release cannot answer for this one`);
     }
     for (const r of snap.recipes) {
@@ -610,13 +356,6 @@ export function verifyRecord(snap, { version, keyedBy = "the file it is named fo
             red.push(`the record shows \`${r.id}\` at exit ${r.exit} — a release may not carry an eval result that records a rail it did not pass`);
         }
     }
-    // **EXACTLY `SELF`, never merely including it.** Requiring presence let a red rail be *relocated*:
-    // move `tests` out of `recipes` into `excluded` with any reason string and the record is green, the
-    // register prints a smaller denominator and a principled-looking exclusion, and the recipe's own
-    // headline — *no record shows a rail at a non-zero exit* — is satisfied by not recording it. A
-    // verdict laundered into the exclusion list is worse than a red, because it reads as rigour.
-    // `--capture` only ever writes `SELF`, so requiring exactly that costs nothing. Found by a
-    // fresh-context reviewer attacking the record layer rather than the code.
     const excludedIds = snap.excluded.map((e) => e.id).sort();
     if (excludedIds.length !== 1 || excludedIds[0] !== SELF) {
         red.push(
@@ -627,7 +366,6 @@ export function verifyRecord(snap, { version, keyedBy = "the file it is named fo
     return red;
 }
 
-/** Run every yielded recipe except this module's own, and return the rows. */
 function measure(root, recipes, { stdout }) {
     const rows = [];
     for (const r of recipes) {
@@ -674,12 +412,6 @@ Exit 0 green · 1 a finding · 2 could not run.`;
 const MODES = ["--capture", "--write", "--verify", "--tagged"];
 
 function parse(argv) {
-    // **`tagged` and `version` are SEPARATE fields, and sharing one was a real defeat of the rail.**
-    // Both meanings once lived in `out.version`: `--tagged`'s argument — the tag being published — and
-    // `--write`'s optional target. So `--tagged v0.1.3 --version 0.1.2` silently overwrote the tag with
-    // the payload's own version, and the tag-versus-payload refusal that `--tagged` exists for became
-    // `exit 0`; reversing the two arguments gave the opposite answer, which is the tell that one slot was
-    // carrying two meanings. Two names cannot collide. Copilot round 5.
     const out = { mode: null, root: ".", date: null, version: null, tagged: null };
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
@@ -692,12 +424,8 @@ function parse(argv) {
         if (MODES.includes(a)) {
             if (out.mode !== null) throw new CouldNotRun(`pass exactly one of ${MODES.join(", ")}`);
             out.mode = a.slice(2);
-            // `--tagged` names the version being published; the others take it optionally.
             if (a === "--tagged") {
-                // Swept with `--version` rather than left because the note named only one of them: the
-                // tag also reaches `snapshotPath()` after its `v` is stripped. `isGoverned` would refuse
-                // a malformed tag downstream, but a value that reaches a path builder before it reaches
-                // a validator is the same shape twice, and only one of the two was reported.
+                // Validated here, before the tag reaches a record path.
                 const t = need("the tag being published, for example `v0.1.3`");
                 if (!SEMVER.test(t.replace(/^v/, ""))) throw new CouldNotRun(`\`--tagged\` takes a tag naming an \`X.Y.Z\` version, not \`${t}\``);
                 out.tagged = t;
@@ -709,26 +437,13 @@ function parse(argv) {
                 out.root = need("a directory");
                 break;
             case "--date": {
-                // Validated here rather than trusted: `--date banana` satisfied the parser and the shape
-                // check alike, and the usage below promises `YYYY-MM-DD`. The front door was the one
-                // reachable route into the degenerate-value class.
                 const v = need("a YYYY-MM-DD date");
                 if (!ISO_DATE.test(v)) throw new CouldNotRun(`\`--date\` takes a \`YYYY-MM-DD\` date, not \`${v}\``);
                 out.date = v;
                 break;
             }
             case "--version": {
-                // Meaningful for `--write` alone: it names which committed record to re-render. Passing
-                // it anywhere else is a refusal rather than a silently ignored argument, because an
-                // argument that looks accepted and does nothing is how the collision above went unseen.
-                //
-                // **And it is validated HERE, because it reaches `path.join` as a path segment.**
-                // Unvalidated, `--write --version ../../pwned` rendered into
-                // `evals/releases/../../pwned.md` — outside the record directory entirely, overwriting a
-                // file two levels up. Demonstrated rather than reasoned about. `X.Y.Z` contains no `/`
-                // and no `..`, so validating the shape closes the traversal as a side effect of
-                // validating the meaning, which is the better order: the value is refused for not being
-                // a version, not for looking like an attack. Copilot round 6.
+                // Validated here because it becomes a path segment, and `X.Y.Z` admits no `/` or `..`.
                 const v = need("an `X.Y.Z` version");
                 if (!SEMVER.test(v)) throw new CouldNotRun(`\`--version\` takes an \`X.Y.Z\` version, not \`${v}\` — it names a record file, so anything else is a path rather than a version`);
                 out.version = v;
@@ -780,11 +495,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     }
 
     if (parsed.mode === "capture") {
-        // **The governance refusal runs FIRST, before any git or workspace read.** It sat after
-        // `sourceOf()`, which throws on a tree that is not a git repository — so on the one fixture that
-        // exercised it the refusal was never reached, and the case guarding it passed on a
-        // `could not read HEAD` it had accidentally allowed through an alternation. A precondition that
-        // needs nothing should be checked before the ones that need something.
+        // Before any git or workspace read, so this refusal is reached outside a repository too.
         if (!governed) {
             stderr.write(
                 `release-eval: package.json declares \`${version}\`, which predates \`${FIRST_GOVERNED_VERSION}\` — ` +
@@ -804,8 +515,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             stderr.write(`release-eval: ${e.message}\n`);
             return 2;
         }
-        // **The date is an argument, never `new Date()`.** A capture that stamps itself from the clock
-        // cannot be reproduced, and this record is byte-compared.
+        // Never the clock: the record is byte-compared, so its date must be reproducible.
         const captured = parsed.date ?? execFileSync("git", ["-C", root, "log", "-1", "--format=%cs"], { encoding: "utf8" }).trim();
         const rows = measure(root, recipes, { stdout });
         const snap = {
@@ -864,18 +574,8 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     }
 
     // ---------------------------------------------------------------- `--tagged`, the release act
-    //
-    // **The one surface a check reaches at the moment a person publishes.** It reads the tag's own
-    // checkout and asks only its own question — does the tree being published carry a record for the
-    // version being published — because everything else about that tree was already graded on the pull
-    // request that made it.
     if (parsed.mode === "tagged") {
-        // **The argument is the TAG's version, and reading it from `package.json` instead was a hole that
-        // made this check green in every reachable variant of the one case it exists for.** Its motivating
-        // scenario is a tag created from a tree whose `## Unreleased` accumulator was never renamed — and
-        // in that tree `package.json` still declares the PREVIOUS version, so a step that asked
-        // `--tagged $(package.json version)` asked about `0.1.2`, got *predates the clause*, and published.
-        // The tag is the only thing in that scenario that names what is being released.
+        // The tag's version, never package.json's: a tag cut from an un-bumped tree still names what it releases.
         const tagged = parsed.tagged.replace(/^v/, "");
         let taggedGoverned;
         try {
@@ -884,9 +584,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             stderr.write(`release-eval: ${e.message}\n`);
             return 2;
         }
-        // **A disagreement is a FINDING, not a note.** It is the scenario itself: the tag says one release
-        // and the payload declares another, so one of the two was never moved. Reporting it and continuing
-        // would publish the thing this check exists to stop.
         if (tagged !== version) {
             stdout.write(
                 `release-eval: the tag names \`${tagged}\` while this tree's package.json declares \`${version}\` — one of the ` +
@@ -932,9 +629,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     }
     const red = [];
 
-    // **Cut integrity, and it holds between cuts as well as at one.** The newest heading is the last
-    // release cut, and `package.json` is bumped in the same change that renames it — so a disagreement
-    // means one of the two moved alone.
     if (released[0] !== version) {
         red.push(
             `CHANGELOG.md's newest release heading is \`${released[0]}\` where package.json declares \`${version}\` — one ` +
@@ -966,18 +660,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         red.push(...gradeOne(root, v, read.snap, v === version ? "package.json" : "CHANGELOG.md"));
     }
 
-    // **Everything ON DISK is graded, in both extensions, governed or not.** Three holes closed here,
-    // all found by a fresh context attacking the record layer rather than the code:
-    //
-    //   * a record for a version the clause does NOT govern was ungraded entirely — `--capture` refuses
-    //     to write one, so nothing could have produced it honestly, and a hand-written
-    //     `evals/releases/0.1.2.json` full of garbage beside a register reading *"all 25 recipes green"*
-    //     was green. A version this rail declines to demand a record for is not a version it permits an
-    //     unexamined record for;
-    //   * the sweep enumerated `.json` only, so a fabricated `<version>.md` with no capture beside it
-    //     was invisible — and the register is the reader-facing half, the one place a release's eval
-    //     result is written for a reader;
-    //   * a record for a version `CHANGELOG.md` never cut sits in the tree looking exactly like evidence.
     let present;
     try {
         present = existsSync(path.join(root, RECORD_DIR))
@@ -1001,10 +683,9 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             );
             continue;
         }
-        if (governedReleases.includes(v)) continue; // already graded above
+        if (governedReleases.includes(v)) continue;
         red.push(`${RECORD_DIR}/${v}.* is present but was not graded — this is a bug in the rail, not in the tree`);
     }
-    // A register with no capture beside it: the reader-facing half standing alone.
     for (const v of governedReleases) {
         if (existsSync(path.join(root, registerPath(v))) && !existsSync(path.join(root, snapshotPath(v)))) {
             red.push(`${registerPath(v)} stands with no capture beside it — the register is what a reader reads, and nothing holds it to anything`);
@@ -1031,7 +712,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
     return 0;
 }
 
-/** Read one version's capture. `snap: null` is *no record*; `couldNotRun` is *a record nothing could read*. */
+/** `snap: null` is no record; `couldNotRun` is a record nothing could read. */
 function readRecord(root, version) {
     const abs = path.join(root, snapshotPath(version));
     if (!existsSync(abs)) return { snap: null };
@@ -1042,7 +723,6 @@ function readRecord(root, version) {
     }
 }
 
-/** One record's full verdict: its contents, and its register byte-compared. */
 function gradeOne(root, version, snap, keyedBy = "CHANGELOG.md") {
     const red = verifyRecord(snap, { version, keyedBy });
     if (red.length > 0) return red;