@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/cli/index.mjs

@@ -1,84 +1,18 @@
 #!/usr/bin/env node
 // `index` — the memory index generator, and the rail on what memory may cost.
 //
-//   node cli/index.mjs [--check] [--pack-root <dir>]... <workspace-dir> [<workspace-dir> ...]
+//   node cli/index.mjs [--check] [--pack-root <dir>|auto]... <workspace-dir> [<workspace-dir> ...]
+//   node cli/index.mjs --handoffs <workspace-dir> [<workspace-dir> ...]
+//   node cli/index.mjs [--check] --changes <dir>
 //
-// Exit 0 every index is current and within budget · 1 one is not · 2 could not run.
-//
-// ../core/operating/memory.md gives the store four states, and this is the third: "a size-budgeted
-// index is generated so the right memory is recalled without loading all of it. The index is built,
-// never hand-maintained." Before this file existed the *built* half was a promise and the *budgeted*
-// half was a sentence binding review — which ../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md
-// says is another way of spelling broken.
-//
-// ## What is budgeted, and why four numbers rather than one
-//
-// The index is the layer that gets loaded to decide what else to load, so its size is what memory
-// costs on every recall — that is the `lines` budget, and with one line per record it is a rail on
-// record COUNT. It cannot see the other axis: a store of unchanged record count can grow without
-// limit in bytes, and nothing in the index would move. So the store's own size is budgeted too, in
-// KB, against the same measure `doctor` already reports. The maintainer's directive was "memory
-// growing too large"; one number would have covered half of it.
-//
-// A third number, `columns`, closes the hole a line budget has — one record whose line is enormous
-// absorbs what the line budget is counting. It is refused rather than truncated, because a silently
-// shortened title is a generated file disagreeing with the store it was generated from, which is the
-// class of defect this whole file exists to make impossible.
-//
-// A fourth, `record_kilobytes`, closes the SAME hole one level down, and arrived at Workspace
-// Definition 2.8 with proposal `0025` — the store's `columns`. An aggregate over individually-authored
-// records cannot see inside them: one enormous record absorbs what the store budget counts, exactly as
-// one enormous line absorbs what the line budget counts. It also fixes where the rail lands. An
-// aggregate is a COMMONS — the record that grew to 15.7 KB never felt the total at write time, and
-// three unrelated changes in two weeks hit it instead, one of them with 551 bytes of headroom. A
-// per-record cap makes the breach LOCAL: record X over its cap never blocks writer Y, and it fires on
-// the author growing the record, at the moment of growth. This workspace declares it in place of
-// `kilobytes`; both stay legal, and `../examples/workspace.json` is the tree's live `kilobytes` case.
-//
-// **None of the four is defaulted.** An undeclared budget is not checked. Defaulting would be this
-// project setting policy for every workspace that ever adopts the spec, in a key nobody typed —
-// the rule spec 2.2 already applies to the gate policy's `floor` object.
-//
-// ## The remedy on breach is consolidation, never a larger budget
-//
-// Stated in ../core/operating/memory.md and carried out by ../core/skills/consolidate/SKILL.md.
-// What this tool can enforce is the breach; it cannot enforce the remedy. Refusing a budget RAISE
-// would mean reading git history — and **the reason that used to settle the matter no longer holds.**
-// This said a history check is "a false-red generator in a shallow CI checkout"; since #265 the verify
-// job sets `fetch-depth: 0`, because `./pack-version.mjs` reads a diff and cannot answer without one.
-// So a history-reading check now runs in this repository's CI, and the remaining reason is the smaller
-// and more honest one: nobody has written this particular check. #75 is its issue, and it is reachable
-// rather than blocked. The raise stays at the human gate until then, stated rather than implied away.
-//
-// ## Why this generator writes an over-budget index instead of refusing to
-//
-// Because the remedy is consolidation, and consolidating needs the artifact to consolidate FROM.
-// A generator that will not emit what breaches leaves the author holding a red and no file. So it
-// emits, and then judges — the one place in this repository where writing and verdict are separate
-// steps on purpose.
-//
-// Zero dependencies, no network, no install step — same constraints as ./doctor.mjs and
-// ./compile.mjs. Absorbed by the zero-dependency ESM CLI at milestone 7, where `index` is one of the eight
-// subcommands ../docs/vision.md names. (A note for that session: this file is `cli/index.mjs`
-// because the subcommand is called `index`, and npm packaging conventionally wants that name for a
-// package entry point. The collision is inherited deliberately rather than discovered.)
+// Exit 0 every index current and within budget · 1 a red verdict · 2 could not run.
 
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-// The cascade, imported rather than re-derived. The scopes series is the one series whose source is
-// not a directory this workspace owns: a persona's memory scope is declared inside a pack the
-// workspace merely composes, so finding it means resolving the `packs` array exactly the way the
-// compiler and `doctor` already resolve it. A second resolver here would be a second answer to
-// "which pack is that" — and issue #74 already records what a memory store cost this project when
-// three copies decided what counted as a record.
-// `shadowedCopy` rides along with the two this file already imports: the predicate for *is this pack
-// shadowed* is one carrier by #316's own argument, and a second spelling here would be the defect that
-// change was filed against, committed one tool over.
 import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
-// Host plugin-cache discovery (#123) — imported, never re-implemented, for the reason above.
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 
 /** Raised when `index` cannot run, or cannot judge honestly. Always exit 2, never 1. */
@@ -89,52 +23,19 @@ export class IndexError extends Error {
     }
 }
 
-// The Workspace Definition versions whose shape this tool reads. The `memory` object arrives at 2.3
-// and is optional, so an earlier manifest is read correctly — it simply declares no index, which is
-// a legitimate shape and the one every workspace had yesterday. Same reasoning as ./compile.mjs's
-// KNOWN_GATE_POLICY_SPECS — which tracks the GATE-POLICY train, not this one — and the same refusal
-// for anything outside the set: a tool that reads a manifest it
-// does not understand reports about a workspace it may have misread.
-const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8"]);
-
-// The store's own signpost, not a record. `doctor` excludes exactly this name from its walk, so the
-// two tools agree on what the store contains; disagreeing would put a record in the index that the
-// store report does not count, or the reverse.
+const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13"]);
+
+// `doctor` skips the same name, so the two count the same records.
 const NOT_A_RECORD = new Set(["README.md"]);
 
 const KB = 1024;
 
-// `isInside` moved to `./inside.mjs` and is re-exported here, so `./doctor.mjs` and every other
-// importer is untouched. It left because `./compile.mjs` needs it too and this file imports FROM
-// `compile.mjs` — taking it from here would have closed an import cycle, which this repository has
-// already had exit 13 in silence once. The predicate was not copied: one implementation, no new edges.
-// Imported AND re-exported: a bare `export … from` re-exports without binding the name in this
-// module's own scope, and this file calls `isInside` itself — 104 tests said so immediately.
 import { isInside } from "./inside.mjs";
 export { isInside };
 
-// ===========================================================================================
-// Titles
-// ===========================================================================================
-//
-// A record's title is its FILENAME. That is not a preference — it is the only title every record
-// already has: ../core/templates/memory-entry.md prescribes no heading, and 24 of the 27 live
-// records carry none. It is also the title every cross-reference in this repository already uses,
-// since links to records are written with the path as the link text.
-//
-// The three records that DO carry an H1 are the reason for the check below rather than an argument
-// against the rule. Two carriers of a name are tolerable; two answers are not.
-
-/**
- * A record's declared `**type:**`, lowercased — `""` when it declares none.
- *
- * The one carrier. Three tools ask this of the same records — this one puts it on every index line,
- * `./doctor.mjs` decides by it which records provenance is mandatory on, and `./librarian.mjs` needs
- * it because thesis 4's mandates are rule-scoped — and all three carried their own spelling of the
- * regex, which is half of what issue #74 is about. It lives here rather than in `./doctor.mjs`
- * because that module already imports `isInside` from this one, and the reverse direction would make
- * the graph a cycle for no gain.
- */
+// ---------------------------------------------------------------- titles
+
+/** A record's declared `**type:**`, lowercased, or `""` when it declares none. */
 export const recordType = (source) => (source.match(/^\s*\*\*type:\*\*\s*(\S+)/im)?.[1] ?? "").toLowerCase();
 
 /** `a-review-loop-needs-a-bound.md` → `A review loop needs a bound`. */
@@ -144,73 +45,38 @@ export function titleOf(filename) {
     return words.charAt(0).toUpperCase() + words.slice(1);
 }
 
-/**
- * The record's H1, or null — read from the document's **first non-blank line only**.
- *
- * The obvious spelling, a multiline `^#` match, is a false-red generator and was measured as one
- * before this comment was written: a record with no heading at all but a shell comment at column 0
- * inside a fenced block — `# regenerate the thing` — came back as carrying that heading, and the
- * title check failed a record whose filename was never in question. `docs.sh` has the same blind
- * spot with code spans and states it in Known limits rather than parsing Markdown; this takes the
- * cheaper repair available here, because a record's title can only be its first line.
- *
- * The residual limit, stated rather than left to be found: a heading further down the document is
- * not read, so a record whose *second* section is an `# H1` disagreeing with the filename passes.
- * That is the right trade — the failure it lets through is a stray heading nobody navigates by, and
- * the failure it prevents is a red on a record that is correct, which is what gets a check switched
- * off (../.portulan/verify/README.md).
- */
+/** The record's H1, or null; only its first non-blank line is read, so a `#` line inside a fence is never taken for one. */
 export function headingOf(source) {
     const first = source.split("\n").find((line) => line.trim() !== "");
     return first?.match(/^#[ \t]+(.+?)[ \t]*$/)?.[1] ?? null;
 }
 
-/**
- * A handoff's date, read from the leading `YYYY-MM-DD` of its filename — or `null`.
- *
- * ../core/operating/loop.md fixes the form as `YYYY-MM-DD-{slug}.md` and argues why the date is in the
- * filename rather than in the prose: a date buried in a document needs parsing and is written
- * differently by every author, while a filename sorts chronologically for free. This reads the carrier
- * that rule already established rather than adding a second one.
- *
- * **Validated, not merely matched.** `2026-13-45-impossible.md` matches the shape and names no day. An
- * index whose leading column is an unparseable string is a chronological index that is not
- * chronological, and every consumer downstream — the pass that ages the series, a reader scanning for
- * a month — would be reading a slug. The round-trip through `Date.UTC` is the cheapest complete check:
- * it rejects month 13, day 45, and 30 February, none of which a regex can see.
- *
- * `null` is a refusal, never a default. ../.portulan/verify/docs.sh already fails an undated file in
- * the series; this is not a second opinion about that rule but the generator being unable to derive a
- * field it must emit.
- */
+/** A handoff's date, the leading `YYYY-MM-DD` of its filename where that names a real day, else null. */
 export function dateOf(filename) {
     const m = filename.match(/^(\d{4})-(\d{2})-(\d{2})-/);
-    if (!m) return null;
-    const [, y, mo, d] = m;
-    const at = new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d)));
+    return m ? realDay(m[1], m[2], m[3]) : null;
+}
+
+function realDay(y, mo, d) {
+    const at = new Date(0);
+    // Not `Date.UTC`, which reads a year from 0 to 99 as 1900 to 1999.
+    at.setUTCFullYear(Number(y), Number(mo) - 1, Number(d));
     const iso = `${y}-${mo}-${d}`;
     return at.toISOString().slice(0, 10) === iso ? iso : null;
 }
 
-// Compared with punctuation and case removed, because a filename cannot carry either. "Who may
-// commit is verified, not assumed" is the same title as `who-may-commit-is-verified-not-assumed.md`
-// and must not be reported as a disagreement — a check that reds on a comma is a false-red machine,
-// and a false red is what gets a whole check switched off (../.portulan/verify/README.md).
+/** A record's `**dated:**` day, the day its text last changed, or null where the line is absent or names no real day. */
+export function recordDate(source) {
+    const m = source.match(/^\s*\*\*dated:\*\*[ \t]*(\d{4})-(\d{2})-(\d{2})[ \t]*$/im);
+    return m ? realDay(m[1], m[2], m[3]) : null;
+}
+
+// Without case or punctuation, which a record's filename does not carry.
 const normalize = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
 
-// ===========================================================================================
-// Reading the store
-// ===========================================================================================
-
-/**
- * The `.md` files of a series, sorted, or an `IndexError`.
- *
- * One enumeration for both series, because the failure it guards is the same one and this repository
- * has now fixed it four times: an unreadable directory returning `[]` renders an empty index, and an
- * empty index compares byte-equal to an empty committed one and passes
- * (../.portulan/memory/verify-preconditions-fail-closed.md). A second copy of this three-line function
- * is a second place for that to be got wrong.
- */
+// ---------------------------------------------------------------- reading the store
+
+/** The `.md` files of a series, sorted; a directory it cannot read is an `IndexError`, never an empty series. */
 function listSeries(seriesDir, slot, what) {
     let names;
     try {
@@ -224,14 +90,7 @@ function listSeries(seriesDir, slot, what) {
     return names.filter((n) => n.endsWith(".md") && !NOT_A_RECORD.has(n)).sort();
 }
 
-/**
- * Read a workspace's memory store.
- *
- * Returns `{ records: [{ file, title, type, heading, bytes }], bytes }`. Throws `IndexError` rather than
- * returning an empty store for anything it cannot read: an empty list renders an empty index, and an
- * empty index compares equal to an empty committed one and passes — the enumeration fail-open this
- * repository has now fixed four times (../.portulan/memory/verify-preconditions-fail-closed.md).
- */
+/** A workspace's memory store, `{ records, bytes }`; anything it cannot read is an `IndexError`, never a record left out. */
 export function readStore(dir, workspace) {
     const slot = workspace?.slots?.memory;
     if (!slot) {
@@ -251,8 +110,6 @@ export function readStore(dir, workspace) {
         try {
             source = fs.readFileSync(path.join(storeDir, file), "utf8");
         } catch (cause) {
-            // Present and unreadable is not "absent". Skipping it would drop a record from the index
-            // silently, which is precisely the shape a generated file must never have.
             throw new IndexError(`cannot read the record ${path.join(slot, file)} — ${cause.code ?? cause.message}`);
         }
         const recordBytes = Buffer.byteLength(source);
@@ -260,33 +117,17 @@ export function readStore(dir, workspace) {
         records.push({
             file,
             title: titleOf(file),
-            // The per-record measure the `record_kilobytes` rail is denominated in, taken here rather
-            // than re-read later so the aggregate and the per-unit rail cannot disagree about what
-            // they measured — the same reason the store total uses the figure `doctor` already prints.
             bytes: recordBytes,
-            // `untyped` rather than a failure: `doctor` already reports a record with no `**type:**`
-            // line, and legislating one field in two tools with two severities is how two checkers
-            // start disagreeing about one store.
             type: recordType(source) || "untyped",
             heading: headingOf(source),
+            dated: recordDate(source),
         });
     }
 
     return { records, bytes };
 }
 
-/**
- * Read a workspace's handoff series.
- *
- * Returns `{ records: [{ file, date, heading }], bytes }`, **newest first** — reverse filename order,
- * which is reverse chronological because the filename leads with the date. Two handoffs of the same
- * date fall in reverse slug order, which carries no claim about which was written first; nothing in
- * the series records that, and inventing an order would be the generated file asserting something its
- * source does not say.
- *
- * `date` and `heading` may be `null`. They are not repaired here — the judge reports them, with a
- * different repair for each, and emits no index at all while either is missing.
- */
+/** A workspace's handoff series, `{ records, bytes }`, newest first; a record's `date` or `heading` is null where it has none. */
 export function readHandoffs(dir, workspace) {
     const slot = workspace?.slots?.handoffs;
     if (!slot) {
@@ -297,6 +138,8 @@ export function readHandoffs(dir, workspace) {
     }
 
     const seriesDir = path.resolve(dir, slot);
+    // `readdirSync` follows a link, so a link on the series path is refused before it is listed.
+    refuseLinks(dir, slot, seriesDir, "a handoff series is read where its path says");
     const files = listSeries(seriesDir, slot, "handoff series").reverse();
     const records = [];
     let bytes = 0;
@@ -304,8 +147,13 @@ export function readHandoffs(dir, workspace) {
     for (const file of files) {
         let source;
         try {
+            const stat = fs.lstatSync(path.join(seriesDir, file));
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new IndexError(`${path.join(slot, file)} is not a regular file: a handoff is a file of its own, never a link or a directory`);
+            }
             source = fs.readFileSync(path.join(seriesDir, file), "utf8");
         } catch (cause) {
+            if (cause instanceof IndexError) throw cause;
             throw new IndexError(`cannot read the handoff ${path.join(slot, file)} — ${cause.code ?? cause.message}`);
         }
         bytes += Buffer.byteLength(source);
@@ -315,39 +163,15 @@ export function readHandoffs(dir, workspace) {
     return { records, bytes };
 }
 
-/**
- * The `## Memory scope` section of a persona file, normalized, or `null` if it carries none.
- *
- * The fourth part of the five-part persona contract (../core/personas/README.md). Read as a section
- * rather than a frontmatter key because that is where the contract puts it, and inventing a key would
- * make every persona this project already ships non-conforming to a contract nobody changed.
- */
+/** The `## Memory scope` section of a persona file, normalized, or `null` if it carries none. */
 export function memoryScopeOf(source) {
     const m = source.match(/^##[ \t]+Memory scope[ \t]*$([\s\S]*?)(?=^##[ \t]|$(?![\s\S]))/im);
     if (!m) return null;
-    // Collapsed to one line, and parenthetical provenance asides dropped, so the digest is stable
-    // against reflowing: a scope rewrapped to a different column width is the same declaration, and a
-    // rail that reddened on it would teach authors to distrust the rail. What it is deliberately NOT
-    // stable against is a changed word — which is the entire point of digesting this text.
-    // `_(…)_` non-greedily to the first `)_`, NOT `[^)]*`: the one aside the shipped supervisor persona
-    // carries contains a markdown link, whose own `)` defeated the character class — so the aside was
-    // digest input while this comment said asides were dropped. Found by the pre-commit checkpoint.
+    // Asides and line breaks dropped, so a rewrapped scope keeps its digest; an aside may hold a link's `)`.
     const body = m[1].replace(/_\([\s\S]*?\)_/g, " ").replace(/\s+/g, " ").trim();
     return body || null;
 }
 
-/**
- * The first sentence of a scope — the legible half of an index line, cut VISIBLY when it runs long.
- *
- * A colon does not end a sentence here, and that is a measured choice rather than a grammatical one:
- * the shipped supervisor persona opens `Its own supervisor memory: classes of defect …`, and breaking
- * on the colon rendered a line that named the persona twice and said nothing. The clause after the
- * colon is the informative half.
- *
- * When the sentence is longer than the budget it is truncated with an ellipsis rather than quietly
- * clipped — a generated file that shortens its source without saying so is the defect `render` above
- * refuses for the same reason. Completeness is the digest's job, not this text's.
- */
 const SENTENCE_BUDGET = 120;
 const firstSentence = (scope) => {
     const sentence = (scope.match(/^([\s\S]*?\.)(\s|$)/) ?? [null, scope])[1].trim();
@@ -357,24 +181,9 @@ const firstSentence = (scope) => {
     return `${(atWord > 40 ? clipped.slice(0, atWord) : clipped).trimEnd()}…`;
 };
 
-/** Eight hex of sha-256 over the normalized scope — the complete half, since a first sentence is not. */
 const scopeDigest = (scope) => crypto.createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 8);
 
-/**
- * Everything a pack ships that would be a memory record — any path with `memory` as a **segment**.
- *
- * The segment, not the prefix `memory/`: that reports a file under a `memory/` directory, the directory
- * itself, and a **symlink named `memory`** — which is the case the prefix form missed, since a link is
- * neither a directory this walk descends nor a file beneath one. Copilot found that bypass on #117 round
- * 8, and this docstring described the prefix form for one round after the code stopped implementing it —
- * a code/comment mismatch in a security-relevant check, which is `a-stated-enforcer-must-be-the-real-one`
- * pointed at a comment instead of a rule.
- *
- * Bounded by construction rather than by a depth constant: it walks the pack it was handed and nothing
- * above it, and it does not follow links — this answers *what does the pack carry*, and a link named
- * `memory` is something it carries whatever it points at. `memory` is the name the Workspace Definition's
- * store slot uses in both live manifests, so it is the name a pack author would reach for.
- */
+/** Every path in a pack with `memory` as a segment, matched before its type, so a link named `memory` counts; no link is followed. */
 function packRecords(packDir, rel = "", out = []) {
     let entries;
     try {
@@ -387,12 +196,6 @@ function packRecords(packDir, rel = "", out = []) {
     }
     for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
         const child = rel ? path.posix.join(rel, e.name) : e.name;
-        // `memory` as a SEGMENT, matched before anything is recursed into or classified. A symlink named
-        // `memory` is neither a directory this walk descends nor a file under `memory/`, so the old
-        // `memory/`-only pattern let a pack smuggle a whole store past a check whose entire subject is
-        // what the pack ships. Copilot, #117 round 8. Matching the segment closes it without following
-        // the link — which is the right trade: this walk answers "what does the pack CARRY", and a link
-        // named `memory` is something it carries whatever it points at.
         if (/(^|\/)memory(\/|$)/.test(child)) {
             out.push(child);
             continue;
@@ -402,24 +205,7 @@ function packRecords(packDir, rel = "", out = []) {
     return out;
 }
 
-/**
- * Read the per-persona memory scopes a workspace's composed packs declare.
- *
- * Returns `{ scopes: [{ persona, pack, location, scope, origin }], unresolved, carrying, broken }`.
- * `origin` is which root answered — `"discovered"`, `"derived"`, or null when the set was not a
- * union and the invocation therefore already said. It is reported and never written.
- *
- * **The one series whose source is the cascade rather than the tree.** A workspace declares `packs`;
- * each pack's manifest declares `contributes.personas`; each persona declares its memory scope. What
- * lands in the adopter's layer is one location per persona — declared by the pack, owned and populated
- * only by the adopter (../docs/milestones/m06.md; thesis 6 of ../docs/vision.md, storage follows
- * ownership). That is also why nothing here reads or writes a record: the scope is a declaration, and
- * the contents are the adopter's to earn.
- *
- * Unresolvable packs, packs carrying records of their own, and personas declaring no scope are all
- * RETURNED rather than thrown — each is a verdict about the composition and belongs in the findings
- * list beside the index's own. What throws is only what makes the render underivable at all.
- */
+/** The memory scopes a workspace's composed packs declare; defects are returned, and only what leaves no index to render throws. */
 export function readScopes(dir, workspace, options = {}) {
     const slot = workspace?.slots?.personas;
     if (!slot) {
@@ -430,28 +216,16 @@ export function readScopes(dir, workspace, options = {}) {
     }
 
     const declared = Array.isArray(workspace?.packs) ? workspace.packs : [];
-    // `options.packRoots` is the FINAL root set when given, matching `compile`'s `packContributions` —
-    // an explicitly empty array means search nowhere rather than falling through to the derived root.
-    // Built through `rootPlan` on every path, `namedGiven` carrying this option's FINAL-set meaning.
-    // The short-circuit it replaces made `packRoots` silently ignore `discoverPacks`, so a caller
-    // asking for both got one of them and no word about the other.
+    // `packRoots`, when given, is the whole root set: an empty one searches nowhere, not the derived root.
     const plan = rootPlan(dir, workspace, {
         named: options.packRoots ?? [],
         namedGiven: options.packRoots !== undefined && options.packRoots !== null,
-        // **Injectable, defaulting to the real reader.** It was hardcoded to `discoverPackRoots()`,
-        // which meant no case could exercise this tool's discovery path without the machine's own
-        // plugin cache deciding the outcome — so the shadow refusal below would have been testable
-        // only by arranging a real install. `recipe-set`'s `resolverFor` already takes the thunk;
-        // this is the same seam, and the default keeps every existing caller byte-identical.
         discovery: options.discovery ?? (() => discoverPackRoots()),
         forced: options.discoverPacks === true,
     });
     if (plan.refusal) throw new IndexError(plan.refusal);
     if (plan.couldNotRun) throw new IndexError(plan.couldNotRun);
     const roots = plan.roots;
-    // Origin is stated in what a reader SEES and never in what gets written: an index whose bytes
-    // recorded which root answered would regenerate differently on two machines, and `index --check`
-    // byte-compares. Provenance belongs in the finding, not in the artifact.
     const originOf = new Map((plan.origins ?? []).map((o) => [o.root, o.origin]));
     const posixSlot = slot.split(path.sep).join(path.posix.sep).replace(/\/$/, "");
 
@@ -466,42 +240,10 @@ export function readScopes(dir, workspace, options = {}) {
             unresolved.push(found);
             continue;
         }
-        // **A shadowed pack is refused here too** (#318), on the same ground `compile` refuses it and
-        // NOT on the same argument — the difference matters enough to write down, because copying
-        // compile's sentence here would state something this file spends four lines denying.
-        //
-        // The ground is the ambiguity: two roots answered for one declared name, the invocation does
-        // not say which the caller meant, and this tool goes on to digest the answering copy's memory
-        // scope into a **committed** index. Picking silently makes a tracked artifact a function of
-        // what happens to be installed.
-        //
-        // What does NOT transfer is compile's bytes argument. Compile refuses even an agreeing shadow
-        // because `recordedOrigin` tags the answering root into its artifact; this index records no
-        // such thing, by the design stated above and in this tool's own help. So an agreeing shadow
-        // here really would produce identical bytes — and the refusal is still unconditional, because
-        // the alternative is a per-tool predicate for *which* differences reach the digest. That
-        // predicate is narrower than "the manifests differ" and would silently widen with every key a
-        // later Pack Definition adds: fail-open by construction, and a third carrier of a comparison
-        // this repository has already had wrong twice.
-        //
-        // **Only where the caller did not choose**, exactly as in `compile`: a named root replaces the
-        // derived one, and `auto` is discovery elected.
         if (!(options.discoverPacks === true) && plan.source !== "named") {
-            // Path-resolved, matching `compile`. `resolutionRoots` builds `origins` and `roots` from
-            // the same strings today, so an exact-string lookup is equal — but two resolve-equal
-            // spellings of one directory would make `compile` refuse where this passed, and three
-            // tools answering one question two ways is the shape this whole family is about.
             const originAt = (r) => (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
             const behind = shadowedCopy(name, originAt(found.root), roots, originAt);
             if (behind) {
-                // **Relative to the REPOSITORY, so the path matches the flag the reader will type.**
-                // `dir` is the WORKSPACE directory, so relativising against it printed `../packs`
-                // beside a remedy reading `--pack-root packs` — one sentence disagreeing with itself.
-                // A first fix printed the absolute root, which made the sentence self-consistent and
-                // still showed a path nobody would type. `compile` and `recipe-set` relativise against
-                // the repository root; this derives the same root from the manifest's own `tree`, and
-                // falls back to the absolute path where a workspace declares none, since a workspace
-                // with no `tree` has no repository for a relative path to be relative to.
                 const repoRoot = typeof workspace?.tree === "string" && workspace.tree.trim() ? path.resolve(dir, workspace.tree) : null;
                 const behindShown = repoRoot ? path.relative(repoRoot, behind.root) : behind.root;
                 throw new IndexError(
@@ -524,9 +266,6 @@ export function readScopes(dir, workspace, options = {}) {
             );
         }
 
-        // Observation 3 of the landing clause, checked at the DISTRIBUTING side. A pack shipping
-        // records would be core-and-packs absorbing the adopter's specifics, and it is invisible from
-        // the adopter's own layer — which is exactly why the check lives here.
         for (const rel of packRecords(found.dir)) carrying.push({ pack: found.name, file: rel });
 
         const personas = manifest?.contributes?.personas;
@@ -538,38 +277,20 @@ export function readScopes(dir, workspace, options = {}) {
         }
 
         for (const rel of personas ?? []) {
-            // **A declared persona path must stay inside the pack.** `resolvePack` already refuses a `..`
-            // in the pack NAME, on the reasoning that it "would resolve a declared pack outside every root
-            // it was supposed to be searched in" — and the paths inside the manifest had no such guard, so
-            // `../../../somewhere` or an absolute path read a file the adopter never offered and put a
-            // digest of its contents into a committed index. A composed pack is third-party content by
-            // construction: that is the whole reason its gate fragments may only ever tighten, and the same
-            // reasoning binds what it may read. Found by Copilot on #117, round 5.
-            // Checked before `path.resolve` touches it: a manifest is a file a human edits, `doctor` may
-            // not have run (the two tools have no ordering), and `path.resolve` on a number throws a bare
-            // TypeError that escapes as an unanticipated crash rather than the exit 2 this module reserves
-            // for "could not judge". Every other malformed-manifest shape here already gets a named
-            // `IndexError`; this one did not. Found by Copilot on #117, round 6.
             if (typeof rel !== "string" || !rel.trim()) {
                 throw new IndexError(
                     `pack \`${found.name}\` declares a persona entry that is not a string path — ${JSON.stringify(rel)}. ` +
                         "Refusing rather than resolving it — run `doctor` to validate the pack against the Pack Definition",
                 );
             }
-            // Containment is checked on the CANONICAL path, not the lexical one. `path.resolve` is textual
-            // and `readFileSync` **follows symlinks**, so the lexical check proved a string was inside the
-            // pack and then read whatever the filesystem pointed at — a pack shipping `personas/x.md` as a
-            // link out of the tree got arbitrary files hashed into a committed index. Found by Copilot on
-            // #117 round 8, one round after the lexical traversal was closed: the same guard, a second
-            // door. `cli/doctor.mjs` already resolves containment this way, so this follows an established
-            // pattern rather than inventing one.
+            // Contained lexically and canonically: `path.resolve` is textual, and `readFileSync` follows a link out of the pack.
             const file = path.resolve(found.dir, rel);
             let real = file;
             let realPackDir = found.dir;
             try {
                 realPackDir = fs.realpathSync(found.dir);
                 real = fs.realpathSync(file);
-            } catch { /* absent or unresolvable — the lexical check below still applies, then the read reports it */ }
+            } catch { /* unresolvable: the lexical check still applies, and the read reports it */ }
             if (!isInside(found.dir, file) || !isInside(realPackDir, real)) {
                 throw new IndexError(
                     `pack \`${found.name}\` declares the persona ${JSON.stringify(rel)}, which resolves outside the pack ` +
@@ -592,8 +313,7 @@ export function readScopes(dir, workspace, options = {}) {
                 broken.push({ pack: found.name, persona, file: rel });
                 continue;
             }
-            // `origin` rides on the finding and never reaches `expected` below — see the note at
-            // `originOf`. Only a union can produce a non-null value here.
+            // Returned, never rendered: an index naming the root that answered would differ from host to host.
             const origin = plan.source === "union" ? originOf.get(found.root) ?? null : null;
             scopes.push({ persona, pack: found.name, location: `${posixSlot}/${persona}/`, scope, origin });
         }
@@ -603,29 +323,14 @@ export function readScopes(dir, workspace, options = {}) {
     return { scopes, unresolved, carrying, broken };
 }
 
-// ===========================================================================================
-// Rendering
-// ===========================================================================================
-//
-// One line per record: title, path, type. Everything on the line is derived, so nothing in the file
-// can be edited into disagreement with the store — which is what "built, never hand-maintained"
-// has to mean if it is to be checkable at all.
-//
-// `scope` is deliberately NOT on the line. It was measured before it was excluded: all 27 live
-// records across both stores carry the same scope head, `workspace`. A field that never varies buys
-// no recall and still costs the budget it is counted against, and ../core/operating/evolution.md
-// asks every line of context to earn its place.
+// ---------------------------------------------------------------- rendering
 
-/** The index as text, for a workspace and the store `readStore` returned. */
+/** The memory index as text. */
 export function render(workspace, store) {
     const indexPath = workspace?.memory?.index?.path;
     const lineBudget = workspace?.memory?.index?.budget?.lines;
     const slot = workspace.slots.memory;
 
-    // Links resolve from the index's own directory, not the workspace root — so an index sited
-    // anywhere still links correctly, and `docs.sh`'s links check holds it to that. Everything here
-    // is posix: these strings end up in a Markdown file that GitHub renders, where a backslash is a
-    // character in a filename rather than a separator.
     const posix = (p) => p.split(path.sep).join(path.posix.sep);
     const from = path.posix.dirname(posix(indexPath));
 
@@ -646,28 +351,6 @@ export function render(workspace, store) {
     return [...header, ...entries].join("\n") + "\n";
 }
 
-/**
- * The handoff index as text.
- *
- * Two derived fields per line — the date off the filename, the title off the record's own H1 — and the
- * link. The title carrier differs from the store's **because the evidence differs**: a memory record
- * usually has no heading, so its filename is the only title it has; a handoff always has one, and its
- * filename leads with a date, so `titleOf` would render `2026 07 28 the librarian goes on a cron`. A
- * generator that picked one rule for both series would be choosing consistency over correctness in the
- * one file whose whole claim is that it agrees with its source.
- *
- * The header states the absent budget rather than leaving its absence to be read as an oversight — the
- * argument is in spec/slots.md and ../core/operating/memory.md, and this is the sentence a reader of
- * the artifact gets.
- *
- * **The H1 is printed as written, and the redundancy that produces is deliberate.** Every handoff here
- * opens `# Handoff — …`, so every line of the index repeats the word. Stripping that prefix was the
- * obvious tidy-up and is refused: it is a rule about the series' *content*, which this generator does
- * not own, and it would render two handoffs differently for a difference that really exists between
- * them — a generated file quietly normalising its source is the failure this whole file is built to
- * make impossible. If the repetition is worth removing, the repair is to reword the headings, which
- * changes the fact rather than the report of it.
- */
 export function renderHandoffIndex(workspace, series) {
     const indexPath = workspace?.handoffs?.index?.path;
     const slot = workspace.slots.handoffs;
@@ -693,40 +376,12 @@ export function renderHandoffIndex(workspace, series) {
     return [...header, ...entries].join("\n") + "\n";
 }
 
-/**
- * The per-persona scope index — the artifact that makes a landing checkable.
- *
- * Every field on a line is derived from the pack that declared the scope, so nothing in the file can
- * be edited into disagreement with the cascade. That is the same property the other two indexes have,
- * and here it carries more weight than in either: this file **is** the positive control the landing
- * clause demands (../docs/milestones/m06.md). A location without a line here is a directory somebody
- * made; a line whose digest no longer matches the persona is a scope that moved without the adopter
- * being told.
- *
- * The digest is over the whole normalized scope, and the sentence beside it is only the legible half.
- * A first sentence alone would let a pack reword everything after it invisibly — which is the exact
- * shape of `a-checkers-coverage-is-measured-not-named`.
- *
- * **What this file is not**, stated here because the alternative is a page describing machinery that
- * does not exist (`.portulan/dod.md` condition 4): nothing reads these locations, nothing recalls from
- * them, and nothing consolidates them. Row 6 declares the scope and shows it landing; `doctor` GAINED
- * the persona-contract check at milestone 7 session 2 (`row 6 declares, row 7 validates`, the
- * maintainer's ruling of 2026-07-29 — ../core/operating/memory.md), so the *validates* half is no
- * longer a future arrival. What it checks is the PRESENCE of the five parts, including a `## Memory
- * scope` section — never what is in these locations, which stay unread by anything. So this remains a
- * declared scope with an empty location, and it says so on its own face rather than in a session
- * record nobody re-reads.
- */
 export function renderScopeIndex(workspace, series) {
     const header = [
         `# Persona memory scopes — ${workspace.name}`,
         "",
         "> Generated from the packs this workspace composes by `node cli/index.mjs`. Do not edit by hand:",
         "> it is regenerated and byte-compared, so a hand-edit survives exactly until the next run.",
-        // Every emphasis span stays on ONE line. Markdown strong emphasis cannot cross a newline, so a
-        // `**…**` split across two rendered lines prints its asterisks literally — which the committed
-        // index did, until Copilot pointed at it. A generated artifact that RENDERS wrong is the same class
-        // as one that says something wrong, and `cli/index.test.mjs` now asserts balanced `**` per line.
         `> ${series.scopes.length} declared scope(s). **Owned and populated only by this workspace.**`,
         "> Each location is empty until earned — the pack declares the scope and carries none of its",
         "> contents. Nothing reads these locations: `doctor` checks a persona against its five-part",
@@ -734,20 +389,7 @@ export function renderScopeIndex(workspace, series) {
         "",
     ];
 
-    // The location is NAMED, never LINKED, and the reason is the same property the whole design rests on:
-    // the location is empty, git does not carry an empty directory, and so it does not exist in a fresh
-    // clone. A markdown link asserts a resolvable target; this path is a *declaration* that may
-    // legitimately not exist yet. The first version linked it, `docs.sh`'s `links` check passed on the
-    // author's disk — where the directory had just been created — and failed in CI on a clean checkout.
-    // That is a **local false green in a generated file**, which regenerating would faithfully reproduce.
-    // Exempting the filename from the link walk was the other repair available and is refused for the
-    // reason this repository always refuses it: an exemption is a door every other record can use.
-    //
-    // Since 2026-07-30 `links` resolves against `git ls-files --cached` (#121), so linking the location
-    // would now be a consistent red rather than a local green. That changes nothing here, and the
-    // distinction is worth keeping straight: the check improved, the reason did not. Naming the location
-    // is right because the path is a declaration, and it would still be right in a workspace `vendor`
-    // shipped to a host that runs no recipes at all.
+    // Named, never linked: git carries no empty directory, so a fresh clone has no location to link to.
     const entries = series.scopes.map((s) =>
         `- \`${s.persona}\` · ${s.pack} · \`${s.location}\` · scope \`${scopeDigest(s.scope)}\` — ${firstSentence(s.scope)}`,
     );
@@ -755,26 +397,12 @@ export function renderScopeIndex(workspace, series) {
     return [...header, ...entries].join("\n") + "\n";
 }
 
-/** The number of lines in a rendered index — the unit the `lines` budget is denominated in. */
 const lineCount = (text) => text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 
-// ===========================================================================================
-// The verdict
-// ===========================================================================================
-
-/**
- * Judge one workspace's index.
- *
- * Returns `{ dir, declared, path, expected, findings }`. A finding is `{ severity, check, message }`
- * with severity `fail` (exit 1); `check` is one of `title`, `index`, `budget`. Throws `IndexError`
- * (exit 2) for anything that is not a verdict about a store.
- *
- * The three checks are kept apart on purpose. *The index is stale* is repaired by running the
- * generator; *the index is over budget* is repaired by consolidating the store; *a record's H1
- * disagrees with its filename* is repaired by editing the record. A single "index check failed"
- * would send an author to regenerate a file that is already correct and still too big.
- */
-export function inspect(dir, { write = false, packRoots: extraRoots, discoverPacks = false } = {}) {
+// ---------------------------------------------------------------- the verdict
+
+/** Judge one workspace's indexes: a finding is a red (exit 1), a note never is, and an `IndexError` means it could not judge (exit 2). */
+export function inspect(dir, { write = false, packRoots: extraRoots, discoverPacks = false, today = new Date().toISOString().slice(0, 10) } = {}) {
     const manifestPath = path.join(dir, "workspace.json");
     let workspace;
     try {
@@ -793,23 +421,15 @@ export function inspect(dir, { write = false, packRoots: extraRoots, discoverPac
 
     const findings = [];
     const fail = (series, check, message) => findings.push({ severity: "fail", series, check, message });
+    const notes = [];
+    const note = (series, message) => notes.push({ series, message });
 
-    // **The remedy a finding prints must be runnable on the machine that printed it** (#318). These
-    // findings surface through the PINNED `verify/index.sh` run — so on a pack developer’s host, where
-    // a declared pack is both installed and in the tree, a bare `node cli/index.mjs <dir>` now exits 2
-    // with the SHADOWED refusal instead of regenerating. That is the same defect this change repaired
-    // in `verify/index.sh`’s own comment, left standing one layer down: one rule, two sites, repaired
-    // at one — which is proposal `0020`’s shape and what the pre-commit sweep exists to catch.
-    //
-    // Echoing the caller’s flags is provably runnable: a finding only prints under an invocation that
-    // reached judgment, so that invocation’s own spelling resolved. A hardcoded `--pack-root packs`
-    // would be wrong for an adopter whose packs sit elsewhere.
     const remedyFlags = [
         ...(Array.isArray(extraRoots) ? extraRoots.map((r) => ` --pack-root ${r}`) : []),
         ...(discoverPacks ? [" --pack-root auto"] : []),
     ].join("");
 
-    const memory = judgeMemory(dir, workspace, { write, fail, remedyFlags });
+    const memory = judgeMemory(dir, workspace, { write, fail, note, today, remedyFlags });
     const handoffs = judgeHandoffs(dir, workspace, { write, fail, remedyFlags });
     const scopes = judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks, remedyFlags });
 
@@ -818,20 +438,11 @@ export function inspect(dir, { write = false, packRoots: extraRoots, discoverPac
         declared: memory.declared || handoffs.declared || scopes.declared,
         series: { memory, handoffs, scopes },
         findings,
+        notes,
     };
 }
 
-/**
- * Refuse an index sited inside the series it indexes, and return its resolved path.
- *
- * One rule, one implementation, two series — and it is refused rather than special-cased for the same
- * reason in both. In the store, `doctor` counts every `.md` as a record, so an index living there is
- * counted, sized into the KB figure, and reported for stating no retirement condition. In the handoff
- * series, `docs.sh`'s correspondence check counts every dated `.md` as a handoff and fails every
- * undated one, so an index there is either an extra handoff or a red. The alternative repair —
- * excluding the index's filename from each walk — is a door any record could use, and this repository
- * had found eight fail-opens of that shape in its own scaffolding before it stopped taking that door.
- */
+/** Refuse an index sited inside the series it indexes, and return its resolved path. */
 function siteOutside(dir, declaredPath, slot, word) {
     const indexPath = path.resolve(dir, declaredPath);
     if (slot && isInside(path.resolve(dir, slot), indexPath)) {
@@ -840,31 +451,43 @@ function siteOutside(dir, declaredPath, slot, word) {
                 `would count the index as one of its members. Site the index beside the ${word}, not in it`,
         );
     }
+    // Here, not where the index is compared, which a judge skips when a record cannot be rendered.
+    refuseLinks(dir, declaredPath, indexPath);
     return indexPath;
 }
 
-/**
- * Write (when asked) and byte-compare one generated index.
- *
- * Shared, because the ways this goes wrong are the same ways for every series and each has already
- * been paid for once. **Never written in check mode** — a verify recipe that repairs what it is
- * checking always passes, the property ../.portulan/verify/compile.sh was built around. **A failed
- * write is an `IndexError`, not a red** — an uncaught ENOENT here exits node with 1, which `index.sh`
- * passes through as "the index has drifted", said about a series nothing had judged, for what is a
- * configuration problem (`a-checker-must-refuse-what-it-cannot-check`; found by Copilot on #72).
- *
- * **And a failed READ is the same fact, which this function did not say for five review rounds.**
- * Only `ENOENT` means the index is absent; `EACCES`, `EISDIR`, `ELOOP` and the rest mean the process
- * could not look. Reported as *declared and absent* they came back as actionable drift at exit 1,
- * telling the operator to regenerate a file that may be correct and merely unopenable — *could not
- * look* dressed as *I looked and found nothing*, which is the record above in as many words. Issue
- * #91; Copilot raised it verbatim on #85 in rounds three through seven, each triaged under
- * `a-review-loop-needs-a-bound.md` rule 4, which is that rule working rather than failing: a triaged
- * note is not a withdrawn one. The rule it restores is stated three times in `./vendor.mjs` and again
- * in `./doctor.mjs`, `./new.mjs`, `./init.mjs`, `./plugin-lint.mjs` and `./compile.mjs` — this was the
- * one read in the repository that did not carry it.
- */
-function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series, source, fail, remedyFlags = "" }) {
+/** Refuse a link in the components the declared path adds; a workspace may itself sit under one, as macOS's `/var` is. */
+function refuseLinks(dir, declaredPath, indexPath, rule = "a kept index is a file of its own where its path says") {
+    let probe = path.resolve(dir);
+    while (!isInside(probe, indexPath)) probe = path.dirname(probe);
+    for (const part of path.relative(probe, indexPath).split(path.sep)) {
+        probe = path.join(probe, part);
+        let stat;
+        try {
+            stat = fs.lstatSync(probe);
+        } catch (cause) {
+            if (cause.code === "ENOENT") return;
+            throw new IndexError(`cannot look for the index at ${declaredPath} — ${cause.code ?? cause.message}`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new IndexError(
+                `${declaredPath} leads through a link at ${path.relative(path.resolve(dir), probe)}, and ${rule} — ` +
+                    "nothing was read or written through it. Replace the link with what it points at",
+            );
+        }
+    }
+}
+
+/** Write when asked, then byte-compare; returns whether a copy is kept. An absent index is a red, any other failed read or write an `IndexError`. */
+function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series, source, fail, remedyFlags = "", optional = false }) {
+    if (optional) {
+        try {
+            fs.lstatSync(indexPath);
+        } catch (cause) {
+            if (cause.code === "ENOENT") return false;
+            throw new IndexError(`cannot look for the index at ${declaredPath} — ${cause.code ?? cause.message}`);
+        }
+    }
     if (write) {
         try {
             fs.mkdirSync(path.dirname(indexPath), { recursive: true });
@@ -882,10 +505,6 @@ function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series,
     try {
         actual = fs.readFileSync(indexPath);
     } catch (cause) {
-        // Only ENOENT is the red below. Everything else is a fact about the filesystem, and the two
-        // repairs have nothing in common: one is `run the generator`, the other is `fix the permissions
-        // on this path`. The errno is named because it is the whole diagnosis — `declared and absent`
-        // sent an operator to regenerate a file that was sitting right there.
         if (cause.code !== "ENOENT") {
             throw new IndexError(
                 `cannot read the index at ${declaredPath} — ${cause.code ?? cause.message}. ` +
@@ -900,26 +519,22 @@ function compareOrWrite({ dir, declaredPath, indexPath, expected, write, series,
     } else if (!actual.equals(Buffer.from(expected, "utf8"))) {
         fail(series, "index", `${declaredPath} is out of date against the ${source} — run \`node cli/index.mjs${remedyFlags} ${dir}\` to regenerate it`);
     }
+    return true;
 }
 
-/** The memory store's index and its budgets. */
-function judgeMemory(dir, workspace, { write, fail, remedyFlags = "" }) {
+function judgeMemory(dir, workspace, { write, fail, note, today, remedyFlags = "" }) {
     const memory = workspace.memory;
     if (!memory) return { declared: false, path: null, expected: null, budgets: 0 };
 
     const declaredPath = memory.index?.path;
     if (!declaredPath) {
-        // A budget with no index is coherent — a workspace may rail its store's size and generate
-        // nothing — so this is not an error. There is simply no file to render.
         const store = readStore(dir, workspace);
-        return { declared: true, path: null, expected: null, budgets: budgetFindings(memory, store, null, fail) };
+        return { declared: true, path: null, expected: null, budgets: budgetFindings(memory, store, null, { fail, note, today }) };
     }
 
     const indexPath = siteOutside(dir, declaredPath, workspace.slots?.memory, "store");
     const store = readStore(dir, workspace);
 
-    // Titles first, and alone. A disagreement means there is no correct line to emit for that
-    // record, so rendering anyway would produce a generated file the generator knows is wrong.
     let broken = 0;
     for (const r of store.records) {
         if (r.heading && normalize(r.heading) !== normalize(r.title)) {
@@ -933,23 +548,16 @@ function judgeMemory(dir, workspace, { write, fail, remedyFlags = "" }) {
             );
         }
     }
-    // Scoped to this series, not to the whole run. A broken record title says nothing about whether
-    // the handoff index is current, and returning early on the shared list would have made one
-    // series' defect silence the other's verdict — a green by omission, which is the shape this file
-    // exists to refuse.
     if (broken) return { declared: true, path: indexPath, expected: null, budgets: 0 };
 
     const expected = render(workspace, store);
+    // Written even over budget: consolidating the store starts from the index.
     compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "memory", source: "store", fail, remedyFlags });
-    const budgets = budgetFindings(memory, store, expected, fail);
+    const budgets = budgetFindings(memory, store, expected, { fail, note, today });
 
     return { declared: true, path: indexPath, expected, budgets };
 }
 
-/**
- * The handoff series' index. No budget — see spec/slots.md: every remedy a budget could ask for on an
- * append-only series is barred, so a rail here is one built to be broken.
- */
 function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
     const declaredPath = workspace.handoffs?.index?.path;
     if (!declaredPath) return { declared: false, path: null, expected: null };
@@ -957,9 +565,6 @@ function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
     const indexPath = siteOutside(dir, declaredPath, workspace.slots?.handoffs, "series");
     const series = readHandoffs(dir, workspace);
 
-    // Two derived fields, two ways to be underivable, two repairs — so two checks. `date` is repaired
-    // by renaming the file; `title` by editing it. One "handoff malformed" would send an author to
-    // the wrong one half the time.
     let broken = 0;
     for (const r of series.records) {
         const where = path.join(workspace.slots.handoffs, r.file);
@@ -982,28 +587,15 @@ function judgeHandoffs(dir, workspace, { write, fail, remedyFlags = "" }) {
             );
         }
     }
-    if (broken) return { declared: true, path: indexPath, expected: null };
+    if (broken) return { declared: true, path: indexPath, expected: null, count: series.records.length };
 
     const expected = renderHandoffIndex(workspace, series);
-    compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "handoffs", source: "series", fail, remedyFlags });
+    // Kept only where a copy is on disk; without one, the series is rendered and nothing written or compared.
+    const kept = compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "handoffs", source: "series", fail, remedyFlags, optional: true });
 
-    return { declared: true, path: indexPath, expected };
+    return { declared: true, path: indexPath, expected, count: series.records.length, kept };
 }
 
-/**
- * The persona scopes series: its index, the landing itself, and the two controls the clause turns on.
- *
- * **Write mode creates the locations; check mode never does.** A verify recipe that materialised what
- * it is checking always passes — the property `../.portulan/verify/compile.sh` was built around, and
- * the reason `--check` is the flag the recipe passes and `--write` is the one it does not.
- *
- * The locations are created **empty**, and empty is not a state git records — so a fresh clone has the
- * index and no directories, which is correct and is why the index is the carrier of the declaration
- * rather than the directory. An absent location is therefore never a finding; what *is* a finding is a
- * location under this layer that no composed persona declares (the negative control), because without
- * that sweep the layer would accept anything at all and the positive control would only ever examine the
- * ones it already expected.
- */
 function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, discoverPacks, remedyFlags = "" }) {
     const declaredPath = workspace.personas?.index?.path;
     if (!declaredPath) return { declared: false, path: null, expected: null };
@@ -1012,7 +604,6 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
     const indexPath = siteOutside(dir, declaredPath, slot, "layer");
     const series = readScopes(dir, workspace, { packRoots: extraRoots, discoverPacks });
 
-    // Four ways this goes wrong, four repairs, so four checks rather than one "scopes malformed".
     for (const p of series.unresolved) {
         fail(
             "scopes",
@@ -1044,8 +635,7 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
         return { declared: true, path: indexPath, expected: null };
     }
 
-    // The negative control. Only over directories that exist — an absent layer means nothing has landed
-    // yet, which is the state of every fresh clone.
+    // An absent layer or location is a fresh clone's state: git carries no empty directory.
     if (slot) {
         const layer = path.resolve(dir, slot);
         const declared = new Set(series.scopes.map((s) => s.persona));
@@ -1053,7 +643,6 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
         try {
             present = fs.readdirSync(layer, { withFileTypes: true });
         } catch (cause) {
-            // ENOENT is the ordinary state; anything else is a filesystem fact, not a verdict.
             if (cause.code !== "ENOENT") {
                 throw new IndexError(
                     `cannot read the persona layer at ${slot} — ${cause.code ?? cause.message}. ` +
@@ -1061,26 +650,7 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
                 );
             }
         }
-        // **Empty means readable-and-zero, never could-not-look.** A declared location that cannot be
-        // enumerated is refused with exit 2, because the feature's own success state IS an
-        // empty directory — so the enumeration fail-open this repository has fixed four times would here
-        // read as the design working rather than as a broken read. Absent is a third, different fact and
-        // stays green: git carries no empty directory, so absent is the state of every fresh clone.
-        //
-        // **Absent is decided by the read itself, not by a prior `existsSync`** — the sibling of #91,
-        // in the paragraph that states the rule. `fs.existsSync` is a `stat` that answers `false` for
-        // every failure, `EACCES` included, so a layer mode `0400` — readable, not searchable, which
-        // the enumeration above passes — made every declared location under it stat-false, skipped as
-        // absent, and the refusal three lines down unreachable. The guard whose comment promises
-        // *never could-not-look* was the one thing looking, and it could not. Removing it also removes
-        // a TOCTOU: one syscall now decides, instead of two that can disagree.
-        //
-        // **The message no longer says the location EXISTS**, and that word had to go with the guard
-        // rather than after it. It was true while `existsSync` gated the read — a `stat` had succeeded
-        // — and this change is what made it reachable for an `EACCES` raised by an unsearchable
-        // ancestor, where existence is precisely what cannot be known. A refusal asserting the one
-        // thing it could not establish is the defect this pull request is about, wearing the fix's own
-        // sentence. Copilot, round 1 on #166.
+        // The read decides absence: `existsSync` is false on EACCES too, and would pass a location nothing could read.
         for (const s of series.scopes) {
             const location = path.resolve(dir, s.location);
             try {
@@ -1097,10 +667,6 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
 
         for (const e of present ?? []) {
             if (e.isDirectory() && declared.has(e.name)) continue;
-            // Directories AND files. The first draft tested `isDirectory()` and skipped everything else,
-            // so a `.md` dropped straight into the layer passed in silence — found by the pre-commit
-            // checkpoint, and the same shape as `a-checkers-coverage-is-measured-not-named`: a sweep
-            // whose description says "anything undeclared" while its code says "any directory".
             const where = path.posix.join(slot.replace(/\/$/, ""), e.name) + (e.isDirectory() ? "/" : "");
             fail(
                 "scopes",
@@ -1116,9 +682,7 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
     const expected = renderScopeIndex(workspace, series);
     compareOrWrite({ dir, declaredPath, indexPath, expected, write, series: "scopes", source: "packs this workspace composes", fail, remedyFlags });
 
-    // The landing itself, and it happens after the index is written rather than before: if the render
-    // could not be derived there is nothing to land, and a directory created for a scope no index
-    // records is the orphan the sweep above exists to catch.
+    // After the index, so no location is made for a scope it does not record.
     if (write) {
         for (const s of series.scopes) {
             const location = path.resolve(dir, s.location);
@@ -1136,11 +700,6 @@ function judgeScopes(dir, workspace, { write, fail, packRoots: extraRoots, disco
     return { declared: true, path: indexPath, expected };
 }
 
-// A declared budget must be a positive integer. Without this, `lines: 0` — or `lines: -1`, or
-// `lines: "60"` — reads as falsy and turns the rail OFF, silently, in a key whose whole purpose is
-// to be on. The schema cannot catch it: the declared keyword subset has no `minimum`, so `type:
-// "number"` is the strongest constraint expressible there (spec/README.md). Exit 2 rather than a
-// red, because it is a defect in the policy rather than a verdict about the store.
 const positive = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
 
 function budgetNumber(value, where) {
@@ -1154,28 +713,19 @@ function budgetNumber(value, where) {
     return value;
 }
 
-/**
- * The four budget checks, each skipped when the workspace declares no number for it.
- *
- * **Returns how many were actually JUDGED**, which is the only thing that licenses the run summary's
- * `within budget` clause. Budgets are optional in the schema and none is defaulted (see the header),
- * so a workspace may declare none at all — and the summary said `within budget` over it anyway, which
- * reads as a verified constraint where the truth is that there was nothing to check. Issue #92, raised
- * by Copilot on #85 round six and triaged there under `a-review-loop-needs-a-bound.md` rule 4.
- *
- * The count is what this function DID, never what the manifest declares, and the two can differ:
- * `lines` and `columns` are measured against the rendered index, so a manifest declaring them under
- * no `index.path` has neither judged. The schema makes `path` required inside `index`, so that shape
- * is one `doctor` rejects — but this tool does not validate against the schema and the two have no
- * ordering (see `readScopes`, where the same reasoning already refuses to resolve an unvalidated
- * path). Counting the declaration instead would have put the false green back in the one shape a
- * caller reaches without `doctor`, which is the class `0020` names: a fix arriving without its sibling.
- */
-function budgetFindings(memory, store, expected, fail) {
+/** The budget checks, each skipped where undeclared; returns how many were judged, which alone licenses `within budget`. */
+function budgetFindings(memory, store, expected, { fail, note, today }) {
     const lines = budgetNumber(memory.index?.budget?.lines, "memory.index.budget.lines");
     const columns = budgetNumber(memory.index?.budget?.columns, "memory.index.budget.columns");
     const kilobytes = budgetNumber(memory.store?.budget?.kilobytes, "memory.store.budget.kilobytes");
     const recordKilobytes = budgetNumber(memory.store?.budget?.record_kilobytes, "memory.store.budget.record_kilobytes");
+    const cutoff = budgetDay(memory.store?.budget?.cutoff, "memory.store.budget.cutoff");
+    if (cutoff !== undefined && recordKilobytes === undefined) {
+        throw new IndexError(
+            "memory.store.budget.cutoff is declared with no `record_kilobytes` beside it. A cutoff says which " +
+                "records the per-record cap binds, so alone it configures nothing while reading as configured",
+        );
+    }
 
     let judged = 0;
 
@@ -1214,13 +764,7 @@ function budgetFindings(memory, store, expected, fail) {
         judged += 1;
         const kb = store.bytes / KB;
         if (kb > kilobytes) {
-            // The exact byte count rides along with the rounded figure, because rounding alone can
-            // print a sentence that contradicts its own verdict: 1025 bytes is `1.0 KB` against a
-            // budget of `1 KB`, which reads as within budget in the message announcing that it is
-            // not. A red whose sentence argues against it is worse than no message. Found by Copilot
-            // on #72. (`doctor`'s retirement note rounds the same way and is left alone: it states a
-            // size and compares it with nothing, so there is no verdict for the rounding to
-            // contradict.)
+            // Bytes beside the rounded figure: 1025 bytes prints as 1.0 KB, which reads as within a 1 KB budget.
             fail(
                 "memory",
                 "budget",
@@ -1230,20 +774,37 @@ function budgetFindings(memory, store, expected, fail) {
         }
     }
 
-    // The per-record cap, added at Workspace Definition 2.8. This is to `kilobytes` what `columns` is
-    // to `lines`: an aggregate cannot see inside its units, so one enormous record absorbs what a store
-    // budget counts exactly as one enormous line absorbs what a line budget counts.
-    //
-    // **Every over-budget record is reported, not just the first.** `columns` breaks after one because
-    // the repair there is the same trivial rename every time and the second instance teaches nothing.
-    // Here each breach is a separate editorial decision — split this record, compress that one, demote
-    // the other's narrative — so stopping at the first would send the author round the loop once per
-    // record, each time believing they were done. The count of budgets JUDGED is still one: `judged`
-    // counts checks this function ran, never findings it raised (see the doc comment).
     if (recordKilobytes) {
         judged += 1;
         const cap = recordKilobytes * KB;
+        // A day past today (UTC), for an author in a time zone ahead of it.
+        const latest = cutoff === undefined ? undefined : nextDay(today);
+        const unbound = [];
         for (const record of store.records) {
+            if (cutoff !== undefined) {
+                if (record.dated === null) {
+                    fail(
+                        "memory",
+                        "date",
+                        `the record ${record.file} carries no \`**dated:** YYYY-MM-DD\` line naming a real day, so the per-record cap ` +
+                            `cannot tell whether its cutoff (${cutoff}) binds it. Add one: the day the record's text last changed`,
+                    );
+                    continue;
+                }
+                if (record.dated > latest) {
+                    fail(
+                        "memory",
+                        "date",
+                        `the record ${record.file} is dated ${record.dated}, more than a day after ${today} (UTC). A record is dated ` +
+                            "the day its text last changed, and a later date would carry it past a cutoff that binds it. Correct the date",
+                    );
+                    continue;
+                }
+                if (record.dated <= cutoff) {
+                    if (record.bytes > cap) unbound.push(record);
+                    continue;
+                }
+            }
             if (record.bytes > cap) {
                 fail(
                     "memory",
@@ -1251,106 +812,208 @@ function budgetFindings(memory, store, expected, fail) {
                     `the record ${record.file} is ${(record.bytes / KB).toFixed(1)} KB (${record.bytes} bytes) against a per-record cap of ` +
                         `${recordKilobytes} KB (${cap} bytes) — over by ${record.bytes - cap}. ` +
                         "Repair it where it is: SPLIT it if it holds more than one fact (which spends `memory.index.budget.lines`, " +
-                        "the axis with the headroom), COMPRESS it, or DEMOTE its narrative to the provenance layer. " +
-                        "Raising the cap in the change that broke it is the one repair core/operating/memory.md rules out",
+                        "the axis with the headroom), COMPRESS it, or DEMOTE its narrative to the provenance layer; never cut a why. " +
+                        (cutoff === undefined
+                            ? "Raising the cap in the change that broke it is the one repair core/operating/memory.md rules out"
+                            : "Raising the cap, or moving the cutoff, in the change that broke it is the repair core/operating/memory.md rules out"),
                 );
             }
         }
+        if (unbound.length) {
+            note(
+                "memory",
+                `${unbound.length} record(s) dated on or before the cutoff (${cutoff}) are over the per-record cap of ${recordKilobytes} KB: ` +
+                    "reported, never railed. Each meets the cap in the change that next rewrites it",
+            );
+        }
     }
 
     return judged;
 }
 
-// ===========================================================================================
-// The command
-// ===========================================================================================
+function nextDay(iso) {
+    const at = new Date(`${iso}T00:00:00Z`);
+    at.setUTCDate(at.getUTCDate() + 1);
+    return at.toISOString().slice(0, 10);
+}
+
+function budgetDay(value, where) {
+    if (value === undefined) return undefined;
+    const m = typeof value === "string" ? value.match(/^(\d{4})-(\d{2})-(\d{2})$/) : null;
+    const day = m ? realDay(m[1], m[2], m[3]) : null;
+    if (!day) {
+        throw new IndexError(
+            `${where} is ${JSON.stringify(value)}, which is not a real day written YYYY-MM-DD. A cutoff that cannot be read ` +
+                "would bind every record or none, and either would be a verdict the manifest never declared",
+        );
+    }
+    return day;
+}
+
+// ---------------------------------------------------------------- changelog fragments
+
+// `docs.sh` refuses the same fragments in bash, so a change to this rule is made there too.
+export const CHANGE_SECTIONS = ["added", "changed", "deprecated", "removed", "fixed", "security"];
+export const CHANGE_NAME = new RegExp(`^[a-z0-9][a-z0-9-]*\\.(${CHANGE_SECTIONS.join("|")})\\.md$`);
+
+/** Every fragment in `dir` in name order, and what is wrong with any that cannot be pasted; a missing directory holds none. */
+export function readChanges(dir) {
+    // `readdirSync` follows a link, so the directory itself is refused when it is one.
+    let entries = null;
+    try {
+        if (!fs.lstatSync(dir).isSymbolicLink()) entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (cause) {
+        if (cause.code === "ENOENT") return { fragments: [], problems: [] };
+        throw new IndexError(`cannot read ${dir} — ${cause.code ?? cause.message}`);
+    }
+    if (entries === null) {
+        throw new IndexError(`${dir} is a link, and fragments are read where they are written — replace it with the directory it points at`);
+    }
+    const fragments = [];
+    const problems = [];
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        if (!entry.isFile()) {
+            // Before the README is skipped, so a README that is a link or a directory is refused too.
+            problems.push({ name: entry.name, message: "is not a regular file: a fragment is a file of its own, never a link or a directory" });
+            continue;
+        }
+        if (NOT_A_RECORD.has(entry.name)) continue;
+        const match = CHANGE_NAME.exec(entry.name);
+        if (!match) {
+            problems.push({
+                name: entry.name,
+                message: `is not a fragment: name it <slug>.<section>.md, the section one of ${CHANGE_SECTIONS.join(", ")}`,
+            });
+            continue;
+        }
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, entry.name), "utf8").replace(/\s+$/, "");
+        } catch (cause) {
+            throw new IndexError(`cannot read ${path.join(dir, entry.name)} — ${cause.code ?? cause.message}`);
+        }
+        const lines = text.split("\n");
+        if (!lines[0].startsWith("- ") || lines.filter((line) => /^\S/.test(line)).length !== 1) {
+            problems.push({
+                name: entry.name,
+                message: "is not one top-level bullet: its first line opens `- `, and every later line is indented or blank",
+            });
+            continue;
+        }
+        fragments.push({ name: entry.name, section: match[1], text });
+    }
+    return { fragments, problems };
+}
+
+/** The fragments as the cut pastes them into `CHANGELOG.md`, one directory above `changes/`, so each `](../` loses its `../`. */
+export function renderChanges(fragments) {
+    const out = [];
+    for (const section of CHANGE_SECTIONS) {
+        const these = fragments.filter((f) => f.section === section);
+        if (these.length === 0) continue;
+        out.push(`### ${section[0].toUpperCase()}${section.slice(1)}`, "");
+        for (const f of these) out.push(f.text.replaceAll("](../", "]("), "");
+    }
+    return out.join("\n").trimEnd();
+}
+
+function runChanges(dir, check, say) {
+    let read;
+    try {
+        read = readChanges(dir);
+    } catch (error) {
+        if (!(error instanceof IndexError)) throw error;
+        say(`  ✗ ${error.message}`);
+        return 2;
+    }
+    for (const p of read.problems) say(`  ✗ ${path.join(dir, p.name)} ${p.message}`);
+    if (read.problems.length) return 1;
+    if (read.fragments.length === 0) say(`  · ${dir}: no change fragments`);
+    else if (check) say(`  ok ${dir}: ${read.fragments.length} change fragment(s), each one bullet`);
+    else say(renderChanges(read.fragments));
+    return 0;
+}
+
+// ---------------------------------------------------------------- the command
 
-/**
- * The help screen — see `./doctor.mjs`'s for the contract and why these three gained one late.
- * `../.portulan/dod.md` condition 4 binds it: every flag below exists in the parser above.
- */
 function usage() {
     return [
         "portulan index — regenerate the memory, handoff and scope indexes",
         "",
         "  portulan index [--check] [--pack-root <dir>|auto]... <workspace-dir> [<workspace-dir> ...]",
         "",
-        "  --check       write nothing; exit 1 if any index is out of date against its store",
+        "  portulan index --handoffs <workspace-dir> [<workspace-dir> ...]",
+        "  portulan index [--check] --changes <dir>",
+        "",
+        "  --check       write nothing; exit 1 if any index kept on disk is out of date against its store,",
+        "                or a handoff yields no index line. A handoff index with no copy on disk is not kept:",
+        "                it is rendered, and nothing is written or compared",
+        "  --handoffs    print each workspace's handoff index, whether or not one is kept and however stale a",
+        "                kept copy is; exit 1 only when a handoff yields no index line, reported instead",
         "  --pack-root   where declared packs are resolved from; `auto` discovers the host's plugin cache.",
         "                A named root REPLACES every other source. A directory actually named `auto` is `./auto`",
+        "  --changes     print the changelog fragments in <dir> grouped by section, as the release cut pastes",
+        "                them; each is <slug>.<section>.md holding one top-level bullet. With --check, print",
+        "                only the verdict",
         "",
         "What is WRITTEN never records which root answered: an index whose bytes carried that would",
-        "regenerate differently on two machines, and `--check` byte-compares.",
+        "regenerate differently on two machines, and `--check` byte-compares every index kept on disk.",
         "",
         "Exit codes: 0 succeeded · 1 a red verdict · 2 could not run.",
     ].join("\n");
 }
 
 export function run(argv, say = console.log) {
-    // **Before every other argument decision**, so asking for help cannot be outranked by a
-    // complaint about the rest of the command line. `./portulan.mjs` states the contract: an
-    // explicit `--help` exits 0, because asking for help is a request and it succeeded.
+    // First, so a request for help is never outranked by a complaint about the other arguments.
     if (argv.includes("--help") || argv.includes("-h")) {
         say(usage());
         return 0;
     }
     let check = false;
     const dirs = [];
-    // Named pack roots, which REPLACE a workspace's own derived root rather than being searched ahead
-    // of it. `resolvePack` was root-parameterized at session 0 so an installed-from-a-feed pack would
-    // travel the same code path as one shipping beside the workspace — but nothing set those roots, so
-    // the parameter was reachable only from a test. Replacement rather than precedence on purpose: a
-    // demonstration that "the pack resolved from the feed" must not be satisfiable by a copy sitting in
-    // the local tree at all. The three tools that take this flag disagreed about it once, and
-    // ./compile.mjs's `namedRootsOption` carries what that cost.
-    // Discovery of a host's plugin cache is built for both halves as of milestone 7 (#123): a POINTER's
-    // `governed_by` through ./discover.mjs, and a PACK root through `--pack-root auto`.
-    //
-    // **Discovery is the default as of 2026-08-13** — this said *"asking is the whole trigger"*, and row
-    // 7's clause is that `--pack-root` is *optional where discovery finds a root*. `auto` now insists
-    // rather than unlocks. The row's direction is unchanged and is the arm above: **add a root where none
-    // was named, never replace one that was.**
-    //
-    // **What this tool WRITES is unaffected, and that is stated in `readScopes` rather than here**: an
-    // index whose bytes recorded which root answered would regenerate differently on two machines and
-    // `index --check` byte-compares, so origin lives in the finding and never in the artifact. The
-    // required `index` recipe also pins its root (`../.portulan/verify/index.sh`), so its verdict is
-    // about the tree whatever this default is.
     const roots = [];
     let discoverPacks = false;
+    let changes = null;
+    let printHandoffs = false;
     for (let i = 0; i < argv.length; i += 1) {
         if (argv[i] === "--check") check = true;
-        else if (argv[i] === "--pack-root") {
+        else if (argv[i] === "--handoffs") printHandoffs = true;
+        else if (argv[i] === "--changes") {
+            changes = argv[i + 1];
+            i += 1;
+            if (changes === undefined || changes.startsWith("-")) {
+                say("  ✗ --changes needs the directory the changelog fragments live in — `changes` in this repository");
+                return 2;
+            }
+        } else if (argv[i] === "--pack-root") {
             const dir = argv[i + 1];
             i += 1;
-            // Single leading `-` refused as well, matching `doctor` — see `compile.mjs` for why.
             if (dir === undefined || dir.startsWith("-")) {
                 say("  ✗ --pack-root needs a directory, or `auto` to discover one from the host plugin cache. A directory actually named `auto` is `./auto`");
                 return 2;
             }
-            // Raw-argument match, before `path.resolve` — `./auto` still names a directory.
             if (dir === AUTO) discoverPacks = true;
             else roots.push(path.resolve(dir));
         } else if (argv[i].startsWith("-")) {
-            // Loud, where it used to be ENOENT noise. Before this, an unrecognised flag fell into
-            // `dirs` and was resolved as a workspace path — `index --help` reported `cannot read
-            // --help/workspace.json`, which reads as a broken workspace rather than a bad argument.
-            // Both real invocations are named for #155's reason.
             say(`  ✗ unknown argument \`${argv[i]}\` — run \`portulan index --help\` or \`node cli/index.mjs --help\` for the flags this tool takes`);
             return 2;
         } else dirs.push(argv[i]);
     }
 
+    if (changes !== null) {
+        if (dirs.length || roots.length || discoverPacks || printHandoffs) {
+            say("  ✗ --changes prints changelog fragments and judges no workspace — run it on its own");
+            return 2;
+        }
+        return runChanges(changes, check, say);
+    }
+
     if (dirs.length === 0) {
         say("usage: node cli/index.mjs [--check] [--pack-root <dir>|auto]... <workspace-dir> [<workspace-dir> ...]");
         return 2;
     }
 
-    // Refused at PARSE time like the other four tools, and NOT left to the plan built inside
-    // `judgeScopes`: that plan is only reached by a workspace declaring a scope index, so a workspace
-    // without one took both flags, silently kept one, and reported `ok`. Measured on this branch —
-    // four of the five carriers refused and this was the fifth, which is the whole class this change
-    // is about, found in the change that fixes it.
+    // Refused here too: `rootPlan` runs only for a workspace declaring a scope index, and one without would take both.
     const bothAsked = namedWithAuto(roots, discoverPacks);
     if (bothAsked) {
         say(`  ✗ ${bothAsked}`);
@@ -1358,13 +1021,6 @@ export function run(argv, say = console.log) {
     }
 
     for (const root of roots) {
-        // A root that is not there is a configuration fact, not a pack that failed to resolve. Reporting
-        // it as the latter would send an author to look at the one file that is not at fault — the same
-        // distinction ../.portulan/memory/verify-preconditions-fail-closed.md was written for.
-        // Existence is not enough: `existsSync` is true for a FILE, and the flag's own usage says it needs
-        // a directory — so a file was accepted and every later resolution failure was misattributed to the
-        // packs rather than to the argument. A stat that throws fails closed for the same reason. Found by
-        // Copilot on #117, round 6.
         let stat = null;
         try {
             stat = fs.statSync(root);
@@ -1382,43 +1038,34 @@ export function run(argv, say = console.log) {
     for (const dir of dirs) {
         let result;
         try {
-            result = inspect(dir, { write: !check, packRoots: roots.length ? roots : undefined, discoverPacks });
+            result = inspect(dir, { write: !check && !printHandoffs, packRoots: roots.length ? roots : undefined, discoverPacks });
         } catch (error) {
             if (!(error instanceof IndexError)) throw error;
             say(`  ✗ ${dir}: ${error.message}`);
-            // Exit 2 wins over a red from another workspace: a run that could not judge one of its
-            // targets has not produced the verdict the caller asked for, and reporting 1 would claim
-            // it did. Every workspace is still judged first, so one broken manifest does not hide
-            // the others' findings.
             worst = 2;
             continue;
         }
 
+        if (printHandoffs) {
+            // A stale kept copy does not stop the print; a handoff that yields no line does.
+            const broken = result.findings.filter((f) => f.series === "handoffs" && f.check !== "index");
+            for (const f of broken) say(`  ✗ ${dir}: ${f.message}`);
+            if (broken.length && worst < 1) worst = 1;
+            else if (!result.series.handoffs.declared) say(`  · ${dir}: declares no handoff index`);
+            else if (!broken.length) say(result.series.handoffs.expected.trimEnd());
+            continue;
+        }
         if (!result.declared) {
             say(`  · ${dir}: declares no index`);
             continue;
         }
         for (const f of result.findings) say(`  ✗ ${dir}: ${f.message}`);
+        for (const n of result.notes) say(`  · ${dir}: ${n.message}`);
         if (result.findings.length && worst < 1) worst = 1;
         if (!result.findings.length) {
-            // Each series is named separately, and a series that generates nothing says so. A
-            // workspace may declare budgets and no index — rail the store's size, generate nothing —
-            // and saying "index current" there is a green about a file that does not exist, which is
-            // the one sentence a tool whose subject is generated artifacts must not print. Found by
-            // Copilot on #72, in the suppressed half of the round; the same trap has two doors now
-            // that there are two series, and a workspace declaring one index would otherwise get a
-            // sentence that reads as covering both. **Three doors since 2.6**, and the first draft of
-            // the scopes series walked through the new one: `index` printed a green naming the store
-            // and the handoffs and silently omitted the scope index it had just written.
             const state = check ? "current" : "written";
             const parts = [];
             if (result.series.memory.declared) {
-                // **`within budget` only where a budget was judged.** All three are optional and none
-                // is defaulted, so a workspace may declare an index and no budget at all — and this
-                // sentence claimed a constraint had held when nothing had been measured, which is the
-                // same over-claim as the `index written` the clause beside it was already repaired for,
-                // one clause over. Issue #92; Copilot, #85 round six, in the suppressed channel.
-                // `budgets` counts what ran rather than what was declared — see `budgetFindings`.
                 const memory = result.series.memory;
                 if (memory.path === null) {
                     parts.push(memory.budgets ? "no store index declared; store within budget" : "no store index declared");
@@ -1426,7 +1073,10 @@ export function run(argv, say = console.log) {
                     parts.push(memory.budgets ? `store index ${state}, within budget` : `store index ${state}`);
                 }
             }
-            if (result.series.handoffs.declared) parts.push(`handoff index ${state}`);
+            if (result.series.handoffs.declared) {
+                const { kept, count } = result.series.handoffs;
+                parts.push(kept ? `handoff index ${state}` : `handoff index renders, ${count} handoff(s), none kept on disk`);
+            }
             if (result.series.scopes.declared) parts.push(`scope index ${state}`);
             say(`  ok ${dir}: ${parts.join("; ")}`);
         }