@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/cli/doctor.mjs

@@ -1,48 +1,15 @@
 #!/usr/bin/env node
 // `doctor` — the Workspace Definition validator.
 //
-//   node cli/doctor.mjs <workspace-dir> [<workspace-dir> ...]
+//   node cli/doctor.mjs [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir>...
 //
 // Exit 0 every workspace validates · 1 at least one does not · 2 could not run.
-//
-// The third code is the one that carries weight here. A verdict ABOUT a workspace — a missing
-// manifest, a slot pointing nowhere, a rule with no provenance — is exit 1: the tool ran and
-// judged. Exit 2 means the tool could not judge at all: no arguments, an unreadable schema, an
-// unanticipated throw. Borrowing 1 for the last of those would claim a judgement nobody made,
-// which is the laundering already fixed once in ../.portulan/tools/gh-bot-token.mjs.
-//
-// Zero dependencies and no install step, deliberately — ../.portulan/identity.md places doctor at
-// milestone 2 as "zero-dependency JavaScript on Node, run from the repository", absorbed by the
-// TypeScript CLI at milestone 7. Nothing here touches the network: a check that fails for reasons
-// unrelated to the change under test is worse than no check (../.portulan/verify/README.md).
-//
-// What it does NOT do is written next to what it does, in ../spec/slots.md and in ../cli/README.md.
-// The short list: it never runs a verify recipe, never dereferences a link, and never judges whether a
-// sealed stamp is true.
-//
-// **It DOES score agent legibility, since milestone 7 session 7** — this line read "and never scores
-// agent-legibility" until then, which was the honest state from milestone 2 until row 7's 2026-07-28
-// amendment was built. The score reads the `affordances` slot and six manifest keys beside it, prints
-// one line, and **moves no exit code**: a measurement is not a verdict, and one that could fail a
-// workspace would make this tool's judgement a function of how much prose somebody wrote. See section
-// 3b for the dimensions and for why each of them can vary.
-//
-// **One name IS dereferenced, as of milestone 7: a pointer's `governed_by`.** It is resolved against
-// the host's installed-plugin record by ./discover.mjs — on disk, never over the network, and the
-// line above stays literally true because that is not a link. The result is REPORTED and never
-// graded: a pointer whose governor is not installed is a correct pointer, and this tool says where
-// the workspace is rather than passing judgement on it.
 
 import fs from "node:fs";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-// The enforcement compiler, imported rather than reimplemented. `doctor` reports what each backend
-// covers, and the only way that report can be true is for it to ask the backends themselves — a
-// second copy of the accounting would drift, and a *coverage claim* that drifts does not look wrong,
-// it looks like enforcement that quietly stopped covering something. Same reasoning that has
-// ./gate.mjs import the matcher instead of writing a second one. Zero
-// dependencies on both sides, so nothing is added to what this tool needs to run.
 import {
     parse,
     backends,
@@ -52,45 +19,22 @@ import {
     composeFragments,
     packDifferences,
     shadowedCopy,
+    personaDeclarations,
 } from "./compile.mjs";
-// The containment test the memory-index siting rule turns on, imported for the reason directly
-// above: the copy that used to live here drifted into the identical fail-open as the original.
 import { isInside, recordType } from "./index.mjs";
-// One frontmatter parser for this repository, not two. `plugin-lint` minted it and has the tests that
-// pin its edges — an unterminated block, a block that is not first, a value with a colon in it — and a
-// second implementation here would be a second carrier of one contract — the class that proposal
-// `0020` names (../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md), and what
-// ../core/operating/evolution.md prescribes leaving one site for.
-// `AGENT_DIR` for the same reason, and it is the stronger case of the two: it is not a convention this
-// tool is free to choose but a MEASUREMENT of where one host looks — with a positive control, recorded
-// at its declaration. A copy here would be this tool's opinion about somebody else's loader.
 import { parseFrontmatter, AGENT_DIR } from "./plugin-lint.mjs";
-// Host plugin-cache discovery, which is where a pointer's `governed_by` stops being a name and
-// becomes a directory. Imported rather than reimplemented for the reason above, and kept in its own
-// file for a second one: the boot skill's whole instruction is to report what THIS resolver said, so
-// there must be exactly one thing that says it.
 import { resolveGovernor, AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 import { composedId } from "./recipe-set.mjs";
+import { alwaysLine } from "./context.mjs";
+import { formLine } from "./form.mjs";
+import { sessionsLine } from "./sessions.mjs";
+import { hostPaths, ledger, print, readSpend, worktrees, linesChanged } from "./ledger.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_SCHEMA = path.resolve(HERE, "..", "spec", "workspace.schema.json");
-// The Pack Definition is a SEPARATE contract on its own version train — see spec/README.md. A pack
-// and a workspace are different artifacts, and one number governing both would make a bump in
-// either mean a change in the other.
 const DEFAULT_PACK_SCHEMA = path.resolve(HERE, "..", "spec", "pack.schema.json");
 
-/**
- * The tail of `doctor`'s binding-success line, exported so the suite keys on ONE carrier.
- *
- * Two tests guard this sentence: one asserts it IS printed for an ordinary binding, the other that it is
- * NOT printed for a name that traverses out of the tree — a path-traversal case where a green would mean
- * `doctor` had opened a file the pack chose. Held as two literals, a reword satisfies the negative
- * assertion **for the wrong reason**: the string is gone, nothing prints it, the test passes, and it
- * would go on passing with the traversal guard deleted. Measured at milestone 7's close, where exactly
- * that happened. Kept here beside the other module constants rather than beside its use, because the
- * first attempt put it between `validatePersona`'s docblock and `validatePersona` — a doc comment
- * attaches to the next symbol, so that silently reassigned it. (Copilot, round 1 on #240.)
- */
+/** The binding-success line's tail, one constant so a test asserting its absence cannot pass on a reword. */
 export const BINDING_OK = "names match and a tool grant is declared";
 
 /** Raised when `doctor` cannot run at all. Always exit 2, never 1. */
@@ -101,26 +45,8 @@ export class DoctorError extends Error {
     }
 }
 
-// ===========================================================================================
-// 1. The schema subset
-// ===========================================================================================
-//
-// spec/README.md names the exact JSON Schema subset this validator implements, on the reasoning
-// that a validator carried rather than depended on must be small enough to implement completely
-// and honestly. The list below IS that sentence, in a form that fails.
-//
-// Everything outside it is refused rather than ignored — which is the point. A validator that
-// skips the keywords it does not know reports conformance it never checked: the author wrote a
-// constraint, the machine agreed, and nothing enforced it. That is the same fail-open shape this
-// repository has now minted three rules about (../.portulan/memory/verify-preconditions-fail-closed.md),
-// and a validator is exactly where a fourth would hide.
-
-// Each supported keyword, with what a well-formed VALUE for it looks like. Knowing the name is not
-// enough: `pattern: "["` and `enum: "repository"` are both inside the subset by name and neither can
-// be honoured, and without this table they surface at instance-validation time as a raw SyntaxError
-// or TypeError — an "unanticipated failure" (exit 2) naming no keyword and no location, from a defect
-// that is squarely in the schema. Refusing at compile time is the same rule one level finer: the unit
-// this validator must refuse is a constraint it cannot apply, not merely a word it does not know.
+// ---------------------------------------------------------------- the schema subset
+
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
 const regexCompiles = (v) => {
@@ -135,8 +61,7 @@ const SUPPORTED = {
     $ref: (v) => typeof v === "string",
     title: (v) => typeof v === "string",
     description: (v) => typeof v === "string",
-    // Constrained to the names `check` can actually test. `type: "integer"` would otherwise be
-    // accepted here and then match nothing, failing every instance — loud, but for the wrong reason.
+    // No "integer": `check` cannot test it, so it would fail every instance.
     type: (v) => ["object", "array", "string", "number", "boolean", "null"].includes(v),
     properties: isObject,
     required: (v) => Array.isArray(v) && v.every((n) => typeof n === "string"),
@@ -163,15 +88,9 @@ const SHAPE = {
         "keys through a check this validator does not implement",
 };
 
-// Siblings a `$ref` may carry. Annotations only: they describe, they never constrain, so they
-// cannot silently narrow what the ref resolves to. Used where a field reuses a shared definition
-// and still deserves its own prose — `name` and `verify.default` both do with `$defs/slug`.
 const REF_SIBLINGS = new Set(["$ref", "title", "description"]);
 
-/**
- * Walk a schema and refuse anything outside the subset. Returns the schema unchanged; the value
- * is the walk, not the result.
- */
+/** Throws a DoctorError for any keyword or value outside the subset; returns the schema unchanged. */
 export function compileSchema(schema, where = "#") {
     if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
         throw new DoctorError(`schema at ${where} is not an object`);
@@ -230,10 +149,7 @@ export function compileSchema(schema, where = "#") {
 const typeOf = (v) =>
     v === null ? "null" : Array.isArray(v) ? "array" : typeof v === "number" ? "number" : typeof v;
 
-/**
- * Validate an instance against a schema written in the subset.
- * Returns `[{ pointer, message }]` — empty when the instance conforms.
- */
+/** The instance's faults as `[{ pointer, message }]`, empty where it conforms. */
 export function validate(schema, instance) {
     compileSchema(schema);
     const errors = [];
@@ -261,7 +177,7 @@ function check(schema, value, pointer, root, errors) {
         const ok = schema.type === "number" ? actual === "number" : actual === schema.type;
         if (!ok) {
             add(`expected type \`${schema.type}\`, found \`${actual}\``);
-            return; // Every other keyword here would be reporting the same fault again.
+            return;
         }
     }
 
@@ -300,10 +216,7 @@ function check(schema, value, pointer, root, errors) {
             if (!(name in value)) add(`required property \`${name}\` is missing`);
         }
         if (schema.additionalProperties === false) {
-            // `properties` may legitimately be absent, and then this forbids EVERY property — the
-            // 2020-12 semantics. Treating a missing `properties` as "nothing to check" would make a
-            // supported spelling silently mean the opposite of what it says, which is the failure
-            // ../.portulan/memory/a-checker-must-refuse-what-it-cannot-check.md is about.
+            // With no `properties` this forbids every key, as JSON Schema 2020-12 does.
             const declared = schema.properties ?? {};
             for (const name of Object.keys(value)) {
                 if (!(name in declared)) {
@@ -338,46 +251,22 @@ function check(schema, value, pointer, root, errors) {
     }
 }
 
-// ===========================================================================================
-// 2. Provenance, parsed out of a Markdown record
-// ===========================================================================================
-//
-// The Workspace Definition puts provenance on a rule rather than in the manifest: a rule lives in
-// Markdown, so a manifest key would describe a workspace's POLICY about provenance while leaving
-// every actual rule unchecked (spec/slots.md). So the schema defines the shape and the records
-// carry instances — one definition, two carriers — and this is the parser between them.
-//
-// The accepted syntax is deliberately narrow: backticked `key=value` tokens on the `**provenance:**`
-// paragraph, keys drawn from the five the schema names. Narrow because the alternative is false
-// reds — the live records carry annotation prose after the stamp ("— the milestone-2 pull request,
-// where…"), and a parser that treated every backtick in that prose as a field would fail records
-// that are perfectly correct.
+// ---------------------------------------------------------------- provenance
 
 const PROVENANCE_KEYS = ["form", "href", "owner", "date", "shape"];
 const PROVENANCE_TOKEN = new RegExp("`(" + PROVENANCE_KEYS.join("|") + ")=([^`]*)`", "g");
 
-/**
- * Pull the provenance stamp out of a record.
- * Returns `{ present, fields, raw }`; `fields` is null when the record carries prose provenance
- * — which is a finding for a rule and a note for anything else, not a parse failure.
- */
+/** A record's provenance stamp as `{ present, fields, raw }`, `fields` null where the provenance is prose. */
 export function parseProvenance(source) {
     const lines = source.split("\n");
     const start = lines.findIndex((l) => /^\s*\*\*provenance:\*\*/i.test(l));
     if (start === -1) return { present: false, fields: null, raw: "" };
 
-    // The stamp may wrap, so the unit is the paragraph, not the line.
     let end = start;
     while (end + 1 < lines.length && lines[end + 1].trim() !== "") end += 1;
     const raw = lines.slice(start, end + 1).join(" ");
 
-    // First occurrence wins. The stamp leads the paragraph and annotation prose follows it, so a
-    // later `form=…` inside that prose is somebody writing *about* provenance, not declaring it —
-    // and last-wins would let a sentence mentioning the other form turn a correct record red. A
-    // false red is the failure that gets a whole check switched off, so the tie breaks toward the
-    // stamp. The residual limit is stated in ../core/templates/memory-entry.md rather than left to
-    // be discovered: a backticked `key=value` using one of these five keys is reserved syntax
-    // wherever it appears in the paragraph.
+    // First occurrence wins: prose after the stamp may mention another `key=value`.
     const fields = {};
     for (const [, key, value] of raw.matchAll(PROVENANCE_TOKEN)) {
         if (!(key in fields)) fields[key] = value.trim();
@@ -385,46 +274,10 @@ export function parseProvenance(source) {
     return { present: true, fields: Object.keys(fields).length ? fields : null, raw };
 }
 
-// A record's declared `**type:**` — imported from ./index.mjs rather than spelled again here. Three
-// tools ask this of the same records and all three carried their own regex, which is half of what #74
-// is about; the direction of the import is set by ./index.mjs already being this module's dependency
-// for `isInside`, so putting the one carrier there keeps the graph acyclic.
-
-// The retirement condition is a template field, not a schema one (core/templates/memory-entry.md):
-// the line a demotion pass retires by. Anchored to the bolded field at line start, so prose that
-// merely discusses retiring never matches — the same false-red caution parseProvenance takes with
-// backticked tokens, for the same reason: a false red is what gets a whole check switched off.
-// **Exported for `./skill-goldens.mjs`**, which binds `core/skills/consolidate/SKILL.md` step 1 —
-// *"Every record carries a `Retire when:` line"* — to the live store. Exported rather than re-spelled:
-// a second regex there would be a second carrier of this field's spelling, and the anchoring caution
-// above is the part a re-speller gets wrong first.
+/** A record's `**Retire when:**` line, anchored at a line's start so prose about retiring never matches. */
 export const RETIRE_WHEN = /^\s*\*\*retire when:\*\*/im;
 
-// ===========================================================================================
-// 3. Claims against the tree
-// ===========================================================================================
-//
-// The milestone-2 criterion asks for this "the way the `map` check already holds the root README
-// to the repo's shape" — so a claim that is verifiable and wrong FAILS, exactly as `map` does.
-//
-// Three things make that safe to do. First, the lint reads only what parses confidently as a path:
-// a code span or link target containing `/`, never absolute. `build: none — no build step yet`
-// claims nothing and is treated as claiming nothing. Prose outside the two parsed sections is
-// **left alone** — not failed and not reported — because reporting every ordinary sentence in a
-// repo card would bury the findings that matter.
-//
-// Second, FAIL is reserved for a claim that is unambiguous. A build/test/run candidate that is a
-// single path-shaped token is a claim a file exists; a candidate that is a command merely contains
-// tokens that might be paths, output paths, flag values or globs, and those are reported rather
-// than failed. A false red is the outcome that gets a whole recipe switched off
-// (../.portulan/verify/README.md), and an ambitious parser is the shortest route to one — which
-// this check learned by producing them.
-//
-// Second, the tree is DECLARED rather than guessed. A workspace that makes claims about the
-// repository containing it says so with the `tree` slot; one that describes repositories not
-// present beside it — a demo, or a portfolio spanning many — omits it, and its claims are reported
-// **unverifiable**. Never silently skipped: a check class that disappears without saying so is the
-// fail-open this repository keeps re-finding.
+// ---------------------------------------------------------------- claims against the tree
 
 const CODE_SPAN = /`([^`]+)`/g;
 const LINK_TARGET = /\]\(([^)]+)\)/g;
@@ -442,9 +295,7 @@ function repoCardClaims(source) {
         return lines.slice(start, end + 1);
     };
 
-    // Absolute paths are excluded because they resolve against the HOST rather than the tree:
-    // `/usr/bin/env` inside a command would otherwise be checked, found, and counted as a passing
-    // claim about a repository it has nothing to do with.
+    // Not absolute: `/usr/bin/env` resolves on the host, not in the tree.
     const isPathish = (token) =>
         token.includes("/") &&
         !token.startsWith("/") &&
@@ -460,28 +311,9 @@ function repoCardClaims(source) {
             const spans = [...rest.matchAll(CODE_SPAN)].map((m) => m[1].trim());
             const candidate = spans[0] ?? rest.trim().split(/\s+/)[0];
             if (!candidate) continue;
-            if (/^none\b/i.test(candidate)) continue; // an explicit no-claim
-
-            // Severity turns on whether the candidate IS a path or merely CONTAINS one, and that
-            // split is the whole design of this branch.
-            //
-            // A candidate that is a single path-shaped token — `./verify.sh` — is unambiguously a
-            // claim that a file exists, and absent it is a **failure**. That is the shape customer
-            // zero's card uses and the shape the milestone-2 close demonstrated red.
-            //
-            // A candidate that is a command — `dotnet run --project src/App` — contains tokens that
-            // may be an input path, an output path not built yet, a flag value, a `sed` expression, a
-            // glob, an npm script name, or an SSH remote. Nothing here can tell those apart, so every
-            // extracted token is **reported, never failed**. An earlier version failed them and bought
-            // false reds on `go test ./...`, `cc -o bin/app src/main.c`, and `--project=src/App` with
-            // the directory present — on exactly the input `../core/templates/repo-card.md` tells
-            // adopters to write. Tightening the pattern cannot fix it: `bin/app` and `test/unit` are
-            // clean-looking paths. A false red gets a whole recipe switched off; a missed check does
-            // not, and this repository has ranked those two twice.
-            //
-            // What both branches guarantee is that nothing is **silent**. Before this, a
-            // command-shaped line was tested whole, rejected for containing a space, and dropped:
-            // not checked, not counted, not reported.
+            if (/^none\b/i.test(candidate)) continue;
+
+            // A lone path is a claim; a command's tokens may be outputs, flags or globs, so they are only reported.
             const tokens = candidate.split(/\s+/);
             const targets = tokens.filter(isPathish);
             if (tokens.length === 1 && targets.length === 1) {
@@ -515,11 +347,6 @@ function repoCardClaims(source) {
     return claims;
 }
 
-/**
- * The status-check contexts a gate map claims `main` requires — every one named in the row, not just
- * the first. A repository may require several, and reading only the first silently exempts the rest:
- * the third real workspace requires two, and the one that was ignored was the one that was wrong.
- */
 function requiredCheckClaims(source) {
     for (const line of source.split("\n")) {
         if (!/^\s*\|/.test(line)) continue;
@@ -532,18 +359,8 @@ function requiredCheckClaims(source) {
 }
 
 /**
- * The status-check contexts a workflow file will report, as `{ id, context }`.
- *
- * The context is the job's `name:` when it sets one, and the job id otherwise — that is what branch
- * protection pins, and the distinction is invisible until a job has both. It surfaced on the third
- * real workspace: a job id `example-job` carrying `name: Example Job`, where the ruleset requires
- * `Example Job` and this function previously returned only `example-job`, so a gate map claiming the
- * id passed a check that should have failed. Customer zero could never have shown it, because its
- * workflow deliberately sets no `name:` precisely so the two coincide.
- *
- * A regex rather than a YAML parse, because a parser is a dependency and this reads one shape from one
- * well-known file. Stated as a limit rather than left to be discovered: unusual-but-valid YAML — flow
- * mappings, quoted or multi-line keys, `name` given as an expression — is not recognised.
+ * Each workflow job as `{ id, context }`, the context being its `name:` where set, as branch protection pins it.
+ * A regex, not a YAML parser: flow mappings, quoted or multi-line keys and `name` expressions go unrecognised.
  */
 function workflowJobs(source) {
     const lines = source.split("\n");
@@ -551,7 +368,7 @@ function workflowJobs(source) {
     if (start === -1) return [];
     const jobs = [];
     for (const line of lines.slice(start + 1)) {
-        if (/^\S/.test(line) && line.trim() !== "") break; // back to top level
+        if (/^\S/.test(line) && line.trim() !== "") break;
         const id = line.match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
         if (id) {
             jobs.push({ id: id[1], context: id[1] });
@@ -567,24 +384,14 @@ function workflowJobs(source) {
     return jobs;
 }
 
-// ===========================================================================================
-// 4. Inspecting one workspace
-// ===========================================================================================
+// ---------------------------------------------------------------- inspecting one workspace
 
 const PATH_SLOTS = {
     identity: "file", principles: "file", gates: "file", dod: "file",
     constitution: "either",
-    memory: "dir", repos: "dir", tasks: "dir", handoffs: "dir", proposals: "dir",
+    memory: "dir", repos: "dir", tasks: "dir", handoffs: "dir", proposals: "dir", context: "dir",
 };
 
-/**
- * The five parts `core/personas/README.md` fixes, each with the pattern that finds it and the word a
- * failure must use so a reader learns **which** part is missing rather than that "the contract" is unmet.
- *
- * The `tools:` allow-list is frontmatter and the other four are sections, which is why the first entry
- * is matched differently — it is a field, not a heading, and a persona that writes it as a heading has
- * not declared a tool grant a host can read.
- */
 const PERSONA_PARTS = [
     { part: "a `tools:` allow-list", find: (fields) => typeof fields?.tools === "string" && fields.tools.trim().length > 0 },
     { part: "a Charter section", find: (_f, body) => /^##\s+Charter\b/im.test(body) },
@@ -593,53 +400,20 @@ const PERSONA_PARTS = [
     { part: "a Read / write posture section", find: (_f, body) => /^##\s+Read\s*\/\s*write posture\b/im.test(body) },
 ];
 
-/**
- * How deep a declared skills root is walked, and it is a bound rather than a recursion.
- *
- * **Three, matching `cli/plugin-lint.mjs`'s `MAX_DECLARED_SKILL_DEPTH`.** The first cut here was 1 and
- * cited `.portulan/tasks/0008-a-declared-skills-path-sees-one-level-down.md` as fixing it — which that
- * task does not do: it fixes plugin-lint's bound, in a different tool, at 3. Two walkers over the same
- * declared key disagreeing about how deep a skill may sit is the sibling-divergence class this
- * repository already has a rule for, so the number is shared rather than independently chosen, and the
- * task is cited for the *shape* it fixes rather than for a number it never gave this tool.
- *
- * **The bound reports when it stops.** That sentence was in this comment before it was true — the walk
- * returned silently at the limit, so a pack whose only skill sat below it was reported as a root with
- * nothing in it, and a skill with a bad name and an empty description passed. Found by the pre-commit
- * checkpoint. Task 0008's own acceptance criterion is that a validator reaching the limit says so
- * rather than reporting an absence it did not establish.
- */
+/** How deep a declared skills root is walked; kept equal to `MAX_DECLARED_SKILL_DEPTH` in ./plugin-lint.mjs. */
 const SKILL_DEPTH = 3;
 
-/**
- * Open and validate what a pack contributes: its skills' frontmatter and its personas' five-part
- * contract. Returns what was actually opened, so the caller's report line can say *opened* rather than
- * *declared* — the distinction the whole check exists to make. `bindable` carries the key each opened
- * persona would be bound by on a host; the caller owns that check, because it needs the tree.
- *
- * **Containment is checked after resolution, never by pattern.** `spec/pack.schema.json` bars only the
- * leading `../` form and says so in its own text; `a/../../x` matches it and still escapes, and a symlink
- * matches nothing until it is followed. `cli/index.mjs` already models the answer for personas —
- * `realpathSync` on both the pack directory and the file, compared after resolution — and this is that
- * rule applied to the half of the manifest nothing had opened.
- */
+/** Opens and validates a pack's skills and personas, counting what was opened; `bindable` holds each persona's host key. */
 export function validateContributions(packDir, contributes, { fail, report, pack }) {
     let realPack;
     try {
         realPack = fs.realpathSync(packDir);
     } catch (cause) {
         fail("packs", `\`${pack}\` resolved to a directory that cannot be realpathed — ${cause.code ?? cause.message}`);
-        // The SAME shape as the success path, `unreadableRoots` included. A caller reading a property
-        // this branch omits gets `undefined`, which is falsy — so the report line silently prints the
-        // clean wording over a pack nothing could open. Raised by Copilot, round 1 on #227.
         return { skills: 0, personas: 0, unreadableRoots: 0, bindable: [] };
     }
 
-    // Three answers, not two. `null` meant "could not resolve" and was reported to the reader as "is not
-    // there" — which is only true for ENOENT. An EACCES is a question that could not be ANSWERED, and
-    // answering it "absent" is the fail-open — "nothing looked" reported as "nothing wrong" — arriving
-    // inside the function added to prevent one. Copilot, round 1 on #156; the same class as session 1's
-    // round 7, one tool over.
+    // Contained after realpath, never by pattern: `a/../../x` and a symlink both pass one. Only ENOENT is absent.
     const inside = (target) => {
         let real;
         try {
@@ -679,19 +453,11 @@ export function validateContributions(packDir, contributes, { fail, report, pack
             continue;
         }
         const found = walkSkills(contained.real, { fail, report, pack, rel });
-        // `null` means the walk could not look, which is NOT zero. Summing it as zero would put "0
-        // skill(s)" in the report line over a root nothing opened — the same "nothing looked recorded as
-        // nothing wrong" the walker itself refuses, arriving one layer out in the sentence a reader
-        // actually reads. Found by the test written for the walker, which is the argument for testing the
-        // report line and not only the finding.
         if (found === null) unreadableRoots += 1;
         else skills += found;
     }
 
     let personas = 0;
-    // What each opened persona would be BOUND by on a host, collected here because this is the one
-    // place the file is read. The caller matches them against `agents/` once the tree is known — the
-    // check needs a repository, and this function is given a pack.
     const bindable = [];
     for (const rel of contributes.personas ?? []) {
         const file = path.join(packDir, rel);
@@ -717,11 +483,6 @@ export function validateContributions(packDir, contributes, { fail, report, pack
         }
         const declared = validatePersona(text, { fail, pack, rel });
         personas += 1;
-        // The key is the declared `name`, and the file's basename where it declares none. Two sources
-        // rather than one because the contract's five parts do not include a name — a persona missing
-        // it is not thereby unbindable, and `new persona` writes `personas/<name>.md`, so the basename
-        // is the author's own answer to the same question. Which one answered is printed, since a
-        // binding resolved by filename is a weaker fact than one resolved by declaration.
         const basename = path.basename(rel, ".md");
         bindable.push({
             rel,
@@ -734,20 +495,8 @@ export function validateContributions(packDir, contributes, { fail, report, pack
 }
 
 /**
- * One persona against the five-part contract, plus the tier no role may claim.
- *
- * **What this checks is PRESENCE, and that is narrower than "validated".** Four of the five parts are
- * matched as headings, so a persona whose Charter, Autonomy reach, Memory scope and Read/write posture
- * sections are all empty passes; and `tools:` is satisfied by any non-empty value, so `tools: []` passes.
- * Both measured at the pre-commit checkpoint. The distinction matters because `core/operating/memory.md`
- * frames this milestone as where a declared memory scope stops being prose a checker can read but not
- * honour — a heading check reads it and does not honour it, and the sentence saying so belongs beside the
- * check rather than only in the milestone's record.
- *
- * **Returns the name the persona declares, or `null` where it declares none** — the key the binding
- * check below resolves a host agent file by. It is returned rather than re-parsed at the call site
- * because the frontmatter has already been read here, and two parses of one block are two chances to
- * disagree about what it said.
+ * One persona against the five-part contract, by presence only: an empty section or `tools: []` passes.
+ * Returns `{ name }`, `name` null where none is declared, or null where there is no frontmatter.
  */
 export function validatePersona(text, { fail, pack, rel }) {
     const { fields, error } = parseFrontmatter(text);
@@ -760,30 +509,9 @@ export function validatePersona(text, { fail, pack, rel }) {
             fail("packs", `\`${pack}\`'s persona \`${rel}\` is missing ${part} — the five-part contract core/personas/README.md fixes`);
         }
     }
-    // Prohibited is the one tier no role may act in, so a persona declaring it as a reach claims a
-    // permission that does not exist for anyone.
-    //
-    // **The first cut of this check flagged the word anywhere in the reach section, and its first run
-    // false-redded this repository's own `checkpoints` supervisor** — whose reach section says
-    // *"**Prohibited is not a reach** and does not appear here"*. That file is obeying the rule by
-    // explaining it, and the checker could not tell disclaiming from claiming. A false red is the failure
-    // that gets a whole recipe switched off (`.portulan/memory/` records `json.sh` costing exactly that),
-    // so the matcher is narrowed to an affirmative mention.
-    //
-    // **The limit, restated after the pre-commit checkpoint measured it WIDER than the first wording
-    // admitted.** This is a prose heuristic and prose defeats it. The splitter breaks on sentence
-    // punctuation and blank lines, so a *block* — a bullet list, which is the ordinary way a reach
-    // section is written — counts as one unit: a negation **anywhere in the same block** suppresses the
-    // finding, not merely one in the same sentence. Both of these pass:
-    //
-    //     - Acts in Prohibited
-    //     - This role does not merge
-    //
-    //     Reach is Prohibited, and there is no ceiling above it
-    //
-    // The structural fix is a declared reach *field* the way `tools:` is a field — a persona-contract
-    // change, and not an implementer's to make. Named at this width so the gap is visible instead of
-    // assumed covered, which is the rule `core/operating/verification.md` legislates.
+    for (const problem of personaDeclarations(text).problems) {
+        fail("packs", `\`${pack}\`'s persona \`${rel}\` ${problem} — core/personas/README.md gives the fields a persona may declare, and none is defaulted`);
+    }
     const reach = text.split(/^##\s+Autonomy reach\b.*$/im)[1]?.split(/^##\s/m)[0];
     if (reach && claimsProhibited(reach)) {
         fail(
@@ -795,14 +523,11 @@ export function validatePersona(text, { fail, pack, rel }) {
     return { name: typeof fields.name === "string" && fields.name.trim() ? fields.name.trim() : null };
 }
 
-/** Walk one declared skills root to the fixed depth, validating each `SKILL.md` frontmatter. */
+/** Walks a declared skills root to `SKILL_DEPTH`, validating each `SKILL.md`: the count, or null where a directory went unread. */
 function walkSkills(root, { fail, report, pack, rel }, depth = 0) {
     let found = 0;
     const own = path.join(root, "SKILL.md");
-    // `lstat`, not `existsSync` — the latter FOLLOWS links, and a `SKILL.md` symlinked out of the pack
-    // under a contained root was opened, validated and counted as the pack's own. Containment covered the
-    // declared root and not the files found beneath it, which is the half-guarantee shape session 1 paid
-    // for twice. Found by the pre-commit checkpoint.
+    // `lstat`, since `existsSync` follows a link and would count a `SKILL.md` linked in from outside the pack.
     let ownStat = null;
     try {
         ownStat = fs.lstatSync(own);
@@ -822,9 +547,6 @@ function walkSkills(root, { fail, report, pack, rel }, depth = 0) {
         found += 1;
     }
     if (depth >= SKILL_DEPTH) {
-        // Reported, never silent. Only when there is something below to miss: announcing a stop over an
-        // empty directory would be noise, and a note nobody can act on trains a reader to skip the ones
-        // they can.
         let below = [];
         try {
             below = fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory());
@@ -845,8 +567,6 @@ function walkSkills(root, { fail, report, pack, rel }, depth = 0) {
     try {
         entries = fs.readdirSync(root, { withFileTypes: true });
     } catch (cause) {
-        // Only ENOENT means absent. Anything else and the walk could not look, which must never be
-        // reported as a root with no skills in it — #108's shape, arriving in a new walker.
         if (cause.code === "ENOENT") {
             fail("packs", `\`${pack}\` declares the skills root \`${rel}\`, which is not there`);
             return found;
@@ -859,11 +579,7 @@ function walkSkills(root, { fail, report, pack, rel }, depth = 0) {
         return null;
     }
     for (const entry of entries) {
-        // A symlinked directory has `isDirectory() === false` and `isSymbolicLink() === true`, so the
-        // obvious `if (!isDirectory()) continue` SKIPS it — silently, with no finding, hiding whatever
-        // skills sit behind it. That is a false green of the walk's own kind, and it is reported rather
-        // than followed for the same reason the `SKILL.md` link is: following it is how a pack ships
-        // content it does not contain. Copilot, round 3 on #156.
+        // A symlinked directory's Dirent is not `isDirectory()`, so the check below would skip it in silence.
         if (entry.isSymbolicLink()) {
             fail(
                 "packs",
@@ -874,20 +590,13 @@ function walkSkills(root, { fail, report, pack, rel }, depth = 0) {
         }
         if (!entry.isDirectory()) continue;
         const child = walkSkills(path.join(root, entry.name), { fail, report, pack, rel: path.join(rel, entry.name) }, depth + 1);
-        // A child that could not be read returns `null`, and `found += null` would add ZERO — not NaN,
-        // which is what the review that found this proposed; `null` coerces to 0 in numeric addition,
-        // measured. The conclusion was right and the mechanism was not, and the real defect is the worse
-        // of the two: an unreadable subdirectory would be silently counted as *no skills here*, which is
-        // exactly the "nothing looked recorded as nothing wrong" this walk was changed to stop — surviving
-        // one level down from the fix. Propagated instead, so the root reports UNREAD however deep the
-        // unreadable directory sits.
+        // Propagated: `found += null` adds 0, which would count an unread directory as empty.
         if (child === null) return null;
         found += child;
     }
     return found;
 }
 
-/** One skill's frontmatter: the `name` and `description` that ARE the contract a host reads. */
 export function validateSkill(file, { fail, pack, rel }) {
     let text;
     try {
@@ -920,12 +629,8 @@ export function validateSkill(file, { fail, pack, rel }) {
 const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /**
- * Does this reach section CLAIM Prohibited, as opposed to disclaiming it?
- *
- * Sentence-scoped, because the two readings sit in the same section and differ only by a negation. A
- * sentence mentioning the tier alongside `not` / `never` / `no role` / `nobody` / `cannot` is the
- * disclaimer every well-written persona contains — this repository's own supervisor is one — and
- * flagging it made a correct file red on the check's first run.
+ * Whether a reach section claims Prohibited: a sentence naming it with no negation, so a disclaimer passes.
+ * A prose heuristic: a bullet block splits as one sentence, so a negation anywhere in it hides a claim.
  */
 function claimsProhibited(reach) {
     for (const sentence of reach.split(/(?<=[.!?])\s+|\n{2,}/)) {
@@ -936,12 +641,7 @@ function claimsProhibited(reach) {
     return false;
 }
 
-/**
- * The Pack Definition version a schema implements, read from its `$id` — the same argument as
- * `schemaVersion` below, on the other version train. Separate rather than shared because the two
- * `$id` shapes differ deliberately (`/spec/2.5/` and `/spec/pack/1.0/`), and a single regex loose
- * enough to read both would read `/spec/pack/1.0/` as Workspace Definition version 1.0.
- */
+/** The Pack Definition version in a pack schema's `$id` (`/spec/pack/1.0/`) as `{ major, minor }`; a DoctorError without one. */
 export function packSchemaVersion(schema) {
     const match = /\/spec\/pack\/([0-9]+)\.([0-9]+)\//.exec(schema.$id ?? "");
     if (!match) {
@@ -953,14 +653,7 @@ export function packSchemaVersion(schema) {
     return { major: Number(match[1]), minor: Number(match[2]) };
 }
 
-/**
- * The Workspace Definition version a schema implements, read from its `$id`.
- *
- * Carried in the identifier rather than parsed out of `title`, because a machine fact read from a
- * human sentence drifts the first time somebody rewords the sentence. Absent is a hard stop: a
- * validator that cannot tell which version of the contract it implements cannot honestly say a
- * manifest conforms to it.
- */
+/** The Workspace Definition version in a schema's `$id` (`/spec/2.5/`) as `{ major, minor }`; a DoctorError without one. */
 export function schemaVersion(schema) {
     const match = /\/spec\/([0-9]+)\.([0-9]+)\//.exec(schema.$id ?? "");
     if (!match) {
@@ -993,48 +686,9 @@ function loadSchema({ schema, schemaPath }) {
     }
 }
 
-// ===========================================================================================
-// 3b. Agent legibility
-// ===========================================================================================
-//
-// Row 7's 2026-07-28 amendment: `doctor` scores agent legibility — the audit `docs/vision.md`'s
-// influence map calls the **unclaimed niche**, "repo affordances scored by doctor".
-//
-// **It moves no exit code, and that is the design rather than a shortfall.** A score is a
-// measurement; `doctor`'s exit codes are verdicts about conformance. A score that could fail a
-// workspace would make the verdict a function of how much affordance prose somebody wrote, and
-// every incentive it created would point at writing more of it.
-//
-// **Every carrier of the amendment says the `affordances` slot "is its input", and this reads six
-// keys besides.** That is a reading, stated rather than taken in silence: the constitution's own
-// gloss is *"repo affordances scored by doctor"* — the repository's affordances, of which the slot
-// is the written half — and a score confined to the slot could not tell two workspaces apart at
-// all. **The slot is the named input, not the only one.**
-//
-// What each dimension has in common is the property that makes a score honest: every one is
-// **optional in the Workspace Definition**, so it can genuinely be absent, and none of them
-// duplicates a check that already fails. A dimension that cannot vary measures nothing, and a
-// dimension that restates a hard failure is a second carrier of one fact.
-//
-// **Three candidates were dropped by that rule, and they are named because two of them were in this
-// session's own plan.** *A declared `tree`* and *a repo card for every repository the products name*
-// were both listed in task 0013's acceptance list; each is already a hard failure — `tree` for any
-// `kind: repository`, the cards through the `cross` check — so scoring them would have been a
-// guaranteed point for every workspace that got far enough to be scored, and a second carrier of a
-// verdict the tool already renders. *Executable verification* was the third, and it survived one
-// checkpoint before being measured: see `legibility` itself. **Seven dimensions is what the rule
-// leaves**, and the number is derived by the suite rather than trusted here.
+// ---------------------------------------------------------------- agent legibility
 
-/**
- * The headings that state limits, and it is a FORM check.
- *
- * A named table rather than a matcher clever enough to be wrong quietly — the same shape and the
- * same reason as `PERSONA_PARTS` above and as the writer table in `cli/compile.mjs`. What it
- * establishes is that a limits section is **present**, never that what it says is true or complete:
- * a heading with an empty body passes. `.portulan/products/portulan/affordances.md` states the rule
- * this scores in its own words — *"a legibility report that lists only strengths is marketing"* — and
- * a form check is the most a reader of the tree can hold anybody to.
- */
+/** Headings that mark a limits section: a form check, so an empty section passes. */
 const LIMIT_HEADINGS = [
     /^#{2,3}\s+What an agent must not assume\b/im,
     /^#{2,3}\s+.*\bmust not\b/im,
@@ -1044,27 +698,13 @@ const LIMIT_HEADINGS = [
 ];
 
 /**
- * Score one workspace's agent legibility.
- *
- * Returns `{ met, applicable, dimensions }`, where a dimension is
- * `{ id, title, met, applicable, why }`. **Inapplicable dimensions leave the denominator** rather
- * than counting as failures: a workspace with no products has nothing to declare affordances for,
- * and scoring it down for that would be grading it against a standard it is not under.
- *
- * Reads the tree only through paths the manifest declares, so it fetches nothing and infers nothing.
+ * Scores agent legibility as `{ met, applicable, dimensions }`; an inapplicable dimension leaves the denominator.
+ * A dimension must be optional in the Workspace Definition and must not restate a check that already fails.
  */
 export function legibility(workspace, dir) {
     const dimensions = [];
     const add = (id, title, met, why, applicable = true) => dimensions.push({ id, title, met, applicable, why });
 
-    // **`verify` itself is deliberately NOT a dimension**, and the reason is the rule this list is
-    // built on. The schema's first `oneOf` form requires `slots` and `verify` of every workspace that
-    // is not a pointer, a pointer returns long before this line, and a manifest that fails the schema
-    // returns earlier still — so *does this workspace declare executable verification* is a question
-    // whose answer is always yes by the time anything here could ask it. It was scored for exactly one
-    // pre-commit checkpoint, which measured it and found a dimension that could not vary: a constant
-    // +1 dressed as a measurement, in a list whose whole claim is that every entry can genuinely be
-    // absent. What a recipe DECLARES about itself still varies, which is the dimension below.
     const recipes = workspace.verify?.recipes ?? [];
     add(
         "requires",
@@ -1093,21 +733,6 @@ export function legibility(workspace, dir) {
         "why a decision was taken survives the session that took it, and is reachable without reading the series",
     );
 
-    // The slot the amendment names, read for both of its dimensions in one pass.
-    //
-    // **Per DOCUMENT, not per product**, and the distinction is the whole of #228 item 1. `products`
-    // resolve `product.affordances ?? workspace.affordances`, so N products inheriting one
-    // workspace-level default all name the same `rel` — which was read N times, and, when it could not
-    // be read, counted N times. `unreadable` was therefore a count of **products**, under a name that
-    // says documents, and both dimensions below are about documents.
-    //
-    // Nothing read the magnitude — `limits` asks only `unreadable === 0`, so no verdict moved — which
-    // is exactly why it is worth fixing now rather than after something starts reading it. A count
-    // wrong about its own unit, in the tool whose subject is claims being checkable.
-    //
-    // Triaged out of [#227](https://github.com/sleepy-panda-srl/portulan/pull/227) at the two-fix-round
-    // bound and **dropped on 2026-08-12 for scope, not on merits** — "nothing here opens
-    // cli/doctor.mjs" — which is the disposition this change reverses now that something does.
     const products = workspace.products ?? [];
     const docs = [];
     const seen = new Set();
@@ -1119,8 +744,6 @@ export function legibility(workspace, dir) {
         try {
             docs.push({ rel, text: fs.readFileSync(path.resolve(dir, rel), "utf8") });
         } catch {
-            // Counted, never skipped: a document that could not be read has not been found to state
-            // its limits, and treating it as absent and as present are both claims nothing established.
             unreadable += 1;
         }
     }
@@ -1144,22 +767,19 @@ export function legibility(workspace, dir) {
 }
 
 /**
- * Inspect one workspace directory.
- * Returns `{ dir, workspace, findings, stats }`. A finding is `{ severity, check, message }`,
- * where severity is `fail` (exit 1) or `report` (worth reading, not a verdict).
+ * Inspects one workspace: `{ dir, workspace, findings, stats }`, with `governor` for a pointer. A finding is
+ * `{ severity, check, message }`, and only a `fail` is a verdict; a DoctorError means it could not judge.
  */
 export async function inspect(workspaceDir, options = {}) {
     const schema = loadSchema(options);
     const packSchema = loadPackSchema(options);
     const dir = path.resolve(workspaceDir);
     const findings = [];
-    // `unretirable` counts records stating no `Retire when:` condition — retirable by a human
-    // re-reading them, never by the condition-driven pass, which is the sense that matters here.
     const stats = { records: 0, rules: 0, sealed: 0, linked: 0, claims: 0, unverifiable: 0, bytes: 0, unretirable: 0, unassessed: 0, packs: 0 };
     const fail = (check, message) => findings.push({ severity: "fail", check, message });
     const report = (check, message) => findings.push({ severity: "report", check, message });
 
-    // ---- the manifest itself
+    // ---------------------------------------------------------------- the manifest itself
     const manifestPath = path.join(dir, "workspace.json");
     let workspace;
     try {
@@ -1170,14 +790,7 @@ export async function inspect(workspaceDir, options = {}) {
         return { dir, workspace: null, findings, stats };
     }
 
-    // Which contract is this manifest written against? Checked BEFORE conformance, because grading
-    // a manifest against a definition it was not written for produces confident nonsense: an
-    // optional slot added in a later MINOR would come back as an unexpected property, and the
-    // report would blame the author for using the spec correctly.
-    //
-    // Both mismatches are exit 2 rather than 1. "This workspace is wrong" and "I do not implement
-    // the contract it names" are different statements, and only the first is a verdict `doctor` is
-    // entitled to make — see ../.portulan/memory/a-checker-must-refuse-what-it-cannot-check.md.
+    // Before conformance: graded against a contract it was not written for, a correct manifest would read as wrong.
     const here = schemaVersion(schema);
     const declared = /^([0-9]+)\.([0-9]+)$/.exec(workspace?.portulan?.spec ?? "");
     if (declared) {
@@ -1187,10 +800,6 @@ export async function inspect(workspaceDir, options = {}) {
                 `${path.relative(process.cwd(), dir)} declares Workspace Definition ${major}.${minor}; ` +
                     `this schema is ${here.major}.${here.minor}. A MAJOR difference means a migration ` +
                     `exists and this validator is not the one to run — ` +
-                    // Named since milestone 7 session 9. This sentence said a migration exists and
-                    // stopped there, which is a refusal that describes a remedy nobody could reach:
-                    // the tool did not exist when it was written. It reads the direction too, since
-                    // a workspace AHEAD of this bundle is not one `upgrade` can help with.
                     (major > here.major
                         ? "and this validator is OLDER than that workspace, so upgrade the CLI rather than the workspace."
                         : "run `portulan upgrade <workspace-dir>` to see what it owes, and `--write` to apply it."),
@@ -1201,9 +810,6 @@ export async function inspect(workspaceDir, options = {}) {
                 `${path.relative(process.cwd(), dir)} declares Workspace Definition ${major}.${minor}, ` +
                     `which is ahead of the ${here.major}.${here.minor} this schema implements. Refusing ` +
                     `rather than grading it against an older contract and reporting the difference as errors — ` +
-                    // The MAJOR arm above names its remedy and this one stopped at "Refusing", which is
-                    // one rule enforced at two sites and repaired at one — `0020`, ten lines apart, in
-                    // the change that repaired the other site. Caught at the pre-commit checkpoint.
                     "and this validator is OLDER than that workspace, so upgrade the CLI rather than the workspace.",
             );
         }
@@ -1215,6 +821,24 @@ export async function inspect(workspaceDir, options = {}) {
                     `${major}.${minor} will simply be absent`,
             );
         }
+        // A key newer than the declared MINOR is refused only for keys born gated, from 2.9: refusing an older
+        // key now would fail a manifest that passes today.
+        for (const [key, since, value] of [
+            ["context", 9, workspace.context],
+            ["slots.context", 10, workspace.slots?.context],
+            ["memory.store.budget.cutoff", 11, workspace.memory?.store?.budget?.cutoff],
+            ["sessions", 11, workspace.sessions],
+            ["spend", 12, workspace.spend],
+            ["spend.restart", 13, workspace.spend?.restart],
+        ]) {
+            if (major === 2 && minor < since && value !== undefined) {
+                fail(
+                    "schema",
+                    `\`${key}\` is Workspace Definition 2.${since}'s, and this manifest declares ${major}.${minor}, ` +
+                        `whose validator refuses it as an unknown key. Declare 2.${since}, or remove the key`,
+                );
+            }
+        }
     }
 
     const errors = validate(schema, workspace);
@@ -1222,34 +846,15 @@ export async function inspect(workspaceDir, options = {}) {
         fail("schema", `${e.pointer || "/"} — ${e.message}`);
     }
     if (errors.length) {
-        // The later checks read the manifest's shape. Running them on a manifest that failed the
-        // schema would produce noise at best and a crash at worst — so they are skipped, and the
-        // skip is said out loud rather than left to look like a pass.
         report("schema", "path, cross-field, claims and provenance checks were skipped: the manifest must conform first");
         return { dir, workspace, findings, stats };
     }
 
-    // ---- residence: exactly one workspace governs a repository
-    //
-    // The maintainer's ruling of 2026-07-30, recorded in ../.portulan/proposals/0017. Two of its three
-    // refusals are here, where a single manifest is enough to see the fault; the third needs to look
-    // outside this directory and is below, with the repo cards.
-    //
-    // These are `doctor`'s and not the schema's ON PURPOSE, and the reason is mechanical rather than
-    // stylistic: the schema's own failures return above at "the manifest must conform first", so a
-    // shape refused by the schema is a shape whose refusal never prints the sentence it exists to
-    // print. The rule is a sentence a human has to read — the whole point is that the reader learns
-    // *why* two workspaces are one too many — so the schema permits the shape and this refuses it.
+    // ---------------------------------------------------------------- residence
     const GOVERNS =
         "a repository is governed by exactly one workspace — it carries its own full workspace, or a " +
         "pointer to the workspace that names it, never both";
-    // Everything a pointer may carry. `summary` is here because one line an agent reads before loading
-    // anything else costs nothing and is the difference between "governed elsewhere" and a bare name.
     const POINTER_KEYS = new Set(["portulan", "name", "summary", "kind", "governed_by"]);
-    // Read off the schema rather than written out again. The cross-repository check below needs to tell a
-    // kind it UNDERSTANDS from one it does not, and a second hand-maintained copy of that list is the
-    // defect class this whole change is partly about — one fact, two carriers, only one of them checked.
-    // Derived, so a fifth kind joins both at once or neither.
     const KNOWN_KINDS = new Set(schema.properties?.kind?.enum ?? []);
 
     if (workspace.kind === "pointer") {
@@ -1263,18 +868,7 @@ export async function inspect(workspaceDir, options = {}) {
                     "two policy layers for one repository and nothing holding them in agreement",
             );
         }
-        // A pointer is not a small workspace, it is a different object: no slots to resolve, no
-        // recipes, no products, no packs, no store, no cards. Every check below reads one of those, so
-        // running them here would grade the absence of things a pointer correctly does not have —
-        // `verify.default` alone would fail every compliant pointer, naming a recipe list that is empty
-        // because the manifest is right. Skipped, and SAID, on the standing rule that a check which
-        // disappears without a word is worse than one that admits what it could not reach.
-        // Blank reads as absent HERE too, because the resolver one file away now treats it that way and
-        // two carriers of one fact are this repository's signature defect. Reporting *"delivered through
-        // `   `"* while `resolveGovernor` ignores that value is a report describing a constraint the tool
-        // does not apply — worse than either behaviour alone, since a reader would go looking for the
-        // marketplace it names. Found by Copilot on the round that reviewed the fix, and by the
-        // pre-commit checkpoint independently, both of them at the site the fix did not reach.
+        // A blank `feed` reads as absent, as `resolveGovernor` reads it.
         const rawFeed = workspace.governed_by?.feed;
         const feed = typeof rawFeed === "string" && rawFeed.trim() !== "" ? rawFeed : undefined;
         report(
@@ -1283,51 +877,11 @@ export async function inspect(workspaceDir, options = {}) {
                 (feed ? `, delivered through \`${feed}\`` : "") +
                 " — no workspace resides here, and this manifest says so rather than improvising one",
         );
-        // ---- and now the name is dereferenced, which it was not until milestone 7's discovery
-        //
-        // This report said *"Nothing was fetched: resolving a pointer to the workspace it names is
-        // discovery, and the roots are named rather than found (milestone 7)"*. Discovery has landed
-        // (./discover.mjs), so the sentence became a document denying a capability that exists —
-        // condition 4 of ../.portulan/dod.md pointing the other way, which this repository has now
-        // corrected often enough to expect.
-        //
-        // **Nothing is fetched is still true and is still said**, by the resolver's own sentence: the
-        // host's installed-plugin record is read from disk and no network call is made anywhere in
-        // this path. What changed is that a name on disk is now looked up, not that anything is
-        // downloaded.
-        //
-        // The verdict is REPORTED and never graded, and that boundary is load-bearing rather than
-        // cautious. `not-installed` is not a defect in this manifest — a pointer is correct while its
-        // governor is uninstalled, which is the ordinary state of a fresh clone — so failing here
-        // would red every honest pointer on every machine that had not run an install yet, including
-        // CI, where nothing is ever installed. What the reader gets instead is the root, and what to
-        // run against it.
-        // `await`ed, though today's resolver is synchronous and `await` on a plain value is a no-op.
-        // `options.discover` is an injection point, `inspect` is already `async`, and a hook that ever
-        // returns a promise would otherwise yield `governor.state === undefined` — a report about a
-        // Promise rather than about a host. One keyword now against a class of silent wrong answer
-        // later (Copilot, round 2).
+        // ---------------------------------------------------------------- the pointer's governor
+        // Reported, never failed: an uninstalled governor is the ordinary state of a fresh clone and of CI.
+        // Awaited although `resolveGovernor` is synchronous, since an injected `discover` may return a promise.
         const resolve = options.discover ?? ((governedBy) => resolveGovernor(governedBy, options));
         const governor = await resolve(workspace.governed_by);
-        // The resolver owns the sentence — one carrier, so every surface reporting this prints the same
-        // words rather than four paraphrases. The fallback names what the resolver answered rather than
-        // inventing prose: a resolver returning no sentence is a defect in the resolver, and a report
-        // that hid it behind something still looking like a report would be the worse failure.
-        //
-        // **The fallback had that defect itself, in the line that claimed to prevent it** (#182 item 2).
-        // It interpolated `governor.state` directly, so a verdict object carrying no `state` printed the
-        // literal word `undefined` inside the one sentence whose whole job is to say a resolver
-        // misbehaved. It now distinguishes three shapes — a state, a state that is not a string, and no
-        // state at all — because "no `state` at all" said of `{state: 123}` is the same class of wrong
-        // one revision later, which is what the pre-commit checkpoint found by feeding it that value.
-        //
-        // Deliberately NOT changed: a resolver that throws, or returns `null` or `undefined`, still
-        // propagates to this tool's top-level catch and exits **2** — *could not run*, which is what that
-        // catch's own header says of anything reaching it, a defect in `doctor` included. Measured four
-        // ways through `run()` before any of this was written, and three of the four were already right.
-        // And the reachability is worth recording so nobody prices this above what it is: `options.discover`
-        // is a test seam, every `resolveGovernor` return path sets `sentence`, so no shipped path reaches
-        // the fallback at all. It is the most marginal of #182's three items.
         const answered = () => {
             if (typeof governor.state === "string") return `\`${governor.state}\``;
             if ("state" in governor) return `a \`state\` that is not a string (\`${typeof governor.state}\`)`;
@@ -1345,7 +899,8 @@ export async function inspect(workspaceDir, options = {}) {
         report(
             "residence",
             "the governing-workspace checks did not run here — path slots, cross-field, packs, claims, " +
-                "enforcement, provenance and the store reports all read a policy layer this manifest " +
+                "enforcement, provenance, the store reports, the legibility score and the always tier's " +
+                "report all read a policy layer this manifest " +
                 "correctly does not carry. They run where the workspace resides, and a green pointer is " +
                 "not a statement that the workspace it names is green",
         );
@@ -1362,14 +917,12 @@ export async function inspect(workspaceDir, options = {}) {
         );
     }
 
-    // ---- path slots
-    // Containment is judged between REAL paths on both sides. Resolving only the target would
-    // report a false escape wherever the workspace's own path runs through a symlink — on macOS
-    // `/tmp` is one, which is where the tests build their scratch workspaces.
+    // ---------------------------------------------------------------- path slots
+    // Both sides realpathed, or a workspace reached through a symlink (macOS `/tmp`) would seem to escape itself.
     let realDir = dir;
     try {
         realDir = fs.realpathSync(dir);
-    } catch { /* the manifest read below reports a workspace that is not there */ }
+    } catch { /* the manifest read above reports a workspace that is not there */ }
     const inside = (target) => {
         const rel = path.relative(realDir, target);
         return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
@@ -1386,19 +939,12 @@ export async function inspect(workspaceDir, options = {}) {
         }
         if (kind === "file" && !stat.isFile()) fail("paths", `${label} points at \`${value}\`, which is not a file`);
         if (kind === "dir" && !stat.isDirectory()) fail("paths", `${label} points at \`${value}\`, which is not a directory`);
-        // Containment is tested on the REAL path, so a symlink out of the workspace is seen for
-        // what it is. `realpathSync` is only safe after the stat above proved the target exists.
         let real = target;
         try {
             real = fs.realpathSync(target);
         } catch { /* keep the lexical path; the stat already succeeded, so this is unusual */ }
         if (!inside(real)) {
-            // Reported, never failed. A workspace embedded in a larger repository may legitimately
-            // reach for a shared document, and failing would make the tool wrong about a case it
-            // cannot see. Two slots are *expected* to escape and are noted as unremarkable rather
-            // than flagged: `constitution`, because a product's constitution normally lives with
-            // the product, and `tree`, which names the repository the workspace sits inside and
-            // would be pointing at the wrong thing if it did not escape.
+            // Reported, never failed: a workspace inside a larger repository may share a document outside it.
             const ordinary = {
                 "slots.constitution": "a constitution usually lives with the product",
                 tree: "a workspace usually sits inside the tree it describes",
@@ -1418,48 +964,24 @@ export async function inspect(workspaceDir, options = {}) {
     }
     if (workspace.affordances) resolvePath(workspace.affordances, "file", "affordances");
     if (workspace.tree) resolvePath(workspace.tree, "dir", "tree");
-    // Added with the `gates` key in Workspace Definition 2.1. It shipped for one checkpoint without
-    // this line while ../spec/slots.md already promised "What `doctor` checks: that the path
-    // resolves" — a manifest naming a policy file that did not exist validated GREEN. Caught at the
-    // pre-commit checkpoint, and it is exactly the shape of
-    // ../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md: the mandate was written in
-    // the same change as the key, and nothing looked.
     if (workspace.gates) resolvePath(workspace.gates, "file", "gates");
-    // Added with the `memory` object in Workspace Definition 2.3, in the same change as the key —
-    // because the `gates` line above records what happens when it is not: a manifest naming a file
-    // that does not exist, validating GREEN, for one whole checkpoint.
     if (workspace.memory?.index?.path) resolvePath(workspace.memory.index.path, "file", "memory.index.path");
     (workspace.products ?? []).forEach((product, i) => {
         resolvePath(product.product, "file", `products[${i}].product`);
         if (product.affordances) resolvePath(product.affordances, "file", `products[${i}].affordances`);
     });
-    // Reads `verify.recipes` directly, and that is deliberate now that `cli/recipe-set.mjs` is the one
-    // carrier of the RUNNABLE set. This is not a reader of that set: it validates the workspace's own
-    // DECLARATION — that each declared recipe's `doc` resolves — which is a claim about this manifest,
-    // not about what CI will run. A composed recipe's `doc` resolves from its own pack root and is that
-    // pack's to validate. The same distinction governs the `verify.default` cross-check below. Both are
-    // exempt from the undeclared-reader sweep in `cli/recipe-set.live.test.mjs` for this reason, and
-    // the exemption is named there too so the two cannot drift apart.
     (workspace.verify?.recipes ?? []).forEach((recipe, i) => {
         if (recipe.doc) resolvePath(recipe.doc, "file", `verify.recipes[${i}].doc`);
     });
 
-    // ---- cross-field
-    //
-    // Scoped to the workspace's OWN recipes on purpose, and it stays that way now that a pack's
-    // recipes compose into the runnable set. `verify.default` is a bare slug (`$defs/slug`) and a
-    // composed id is `<category>/<name>:<id>`, so a composed recipe can never be named here — widening
-    // this check to the composed union would accept nothing new and would quietly suggest that naming
-    // a pack's recipe as the default is a thing a manifest may do. Row 7 forbids exactly that: a
-    // composed recipe may never become the workspace's `verify.default`.
+    // ---------------------------------------------------------------- cross-field
+    // Own recipes only: a composed recipe may never be the workspace's `verify.default`.
     const ids = (workspace.verify?.recipes ?? []).map((r) => r.id);
     if (!ids.includes(workspace.verify?.default)) {
         fail("cross", `verify.default names \`${workspace.verify?.default}\`, which is not among the declared recipes (${ids.join(", ") || "none"})`);
     }
 
-    // Uniqueness is `verify.default`'s missing sibling. The schema's `uniqueItems` compares whole
-    // objects, so two recipes sharing an id and differing anywhere else pass it — and then naming
-    // that id resolves to whichever the reader happens to look at first.
+    // `uniqueItems` compares whole objects, so two entries sharing only an id pass the schema.
     const duplicates = (list, what) => {
         const seen = new Set();
         for (const id of list) {
@@ -1482,8 +1004,6 @@ export async function inspect(workspaceDir, options = {}) {
 
     (workspace.products ?? []).forEach((product, i) => {
         for (const name of product.repos ?? []) {
-            // Exact basename, never a substring: `portulan` must not be satisfied by
-            // `portulan-internal.md`.
             if (!cardNames.has(name)) {
                 fail("cross", `products[${i}].repos names \`${name}\`, for which there is no card in the repos slot`);
             }
@@ -1493,14 +1013,7 @@ export async function inspect(workspaceDir, options = {}) {
         }
     });
 
-    // Proposal 0005, accepted 2026-07-25 and applied here. A `repository` workspace is the policy layer
-    // of a repository that is present, so it always has an answer; `demo` and `portfolio` describe
-    // repositories that are not beside them and genuinely do not.
-    //
-    // This constraint cannot live in the schema: a conditional dependency between two keys needs `if`/
-    // `then` or `dependentRequired`, and neither is in the subset spec/README.md declares. So it is here,
-    // and spec/slots.md states it as a rule the schema does not carry. That asymmetry is a real cost —
-    // a constraint invisible to anyone reading the schema alone — and it is stated rather than hidden.
+    // Constraints between keys live here: the subset has no `if`/`then` or `dependentRequired`.
     if (workspace.kind === "repository" && !workspace.tree) {
         fail(
             "cross",
@@ -1510,15 +1023,7 @@ export async function inspect(workspaceDir, options = {}) {
         );
     }
 
-    // The residence ruling's third refusal, and the only one that has to look outside this directory:
-    // a repository this workspace NAMES must not carry a governing workspace of its own. Visibility is
-    // the whole difficulty — a portfolio workspace declares no `tree`, so it has no path to the
-    // repositories it covers — and it is bought the way the packs resolver buys its own, with named
-    // roots rather than discovery. `--repo-root` is to repo cards what `--pack-root` is to packs.
-    //
-    // What this does NOT do, stated because the asymmetry is real: the refusal runs from the naming
-    // workspace outward. A repository carrying a full workspace cannot see a portfolio that claims it,
-    // and nothing here changes that.
+    // Checked from the naming side only: a repository carrying a full workspace cannot see a portfolio naming it.
     const repoRoots = options.repoRoots ?? [];
     if (cardNames.size) {
         if (repoRoots.length === 0) {
@@ -1549,12 +1054,7 @@ export async function inspect(workspaceDir, options = {}) {
                     );
                     continue;
                 }
-                // A workspace that names its own repository finds ITSELF at the root — one manager seen
-                // twice, not two managers. Customer zero is exactly this shape: `.portulan/` names the
-                // card `portulan`, so the first run of this check against a root holding the Portulan
-                // checkout would have refused the very arrangement the ruling permits. Compared on the
-                // REAL path, because the root is commonly reached through a symlink and a lexical
-                // comparison would miss the identity and print a false red.
+                // A workspace naming its own repository finds itself here, compared on real paths: roots are often links.
                 let identical = false;
                 try {
                     identical = fs.realpathSync(found) === fs.realpathSync(manifestPath);
@@ -1581,20 +1081,7 @@ export async function inspect(workspaceDir, options = {}) {
                     );
                     continue;
                 }
-                // A manifest at a named root is READ, never validated — `doctor` grades one workspace per
-                // run and this is somebody else's. Everything below follows from that one fact, and it
-                // took two rounds to apply it consistently: this check refuses only what a manifest
-                // clearly DECLARES, and reports every shape it merely fails to understand. A refusal
-                // built on a field this run never validated would be a verdict about a workspace nobody
-                // graded.
-                //
-                // The first miss was a pointer with no `governed_by.workspace`, refused for "naming
-                // `undefined`" — a conflicting-governor verdict about a manifest naming no governor at
-                // all. The second was its sibling one field over, and it survived the fix to the first:
-                // a manifest with a MISSING or unrecognised `kind` fell into the governing branch and was
-                // refused as `kind: "undefined"`. Both found by Copilot on #135, rounds 1 and 4, which is
-                // the sibling class the 2026-07-27 ruling names — found here in the very change that
-                // quotes that ruling twice.
+                // Somebody else's manifest, read and never validated: only what it clearly declares is refused.
                 if (!KNOWN_KINDS.has(other.kind)) {
                     report(
                         "residence",
@@ -1612,22 +1099,8 @@ export async function inspect(workspaceDir, options = {}) {
                             "residences carry full functionality, so nothing is lost either way",
                     );
                 } else if (typeof other.governed_by?.workspace !== "string" || other.governed_by.workspace.trim() === "") {
-                    // The question is **is this a usable governor name**, not *is the key present* — the
-                    // third gap of this same class in this one block, and the one the first two fixes
-                    // left. `=== undefined` catches ABSENT and not INVALID, so `""`, `null` and a
-                    // non-string fell through to the conflicting-governor branch below and were refused
-                    // for naming a governor they do not name: a **false red** about somebody else's
-                    // manifest, in the block whose own rule is *read, never validated*.
-                    //
-                    // Blank counts as no name, which is the rule `cli/discover.mjs` now enforces at the
-                    // other site of this same operation. **Non-blank string**, deliberately, not *usable
-                    // slug*: a padded or otherwise illegal name is still a name the manifest DECLARES, and
-                    // judging its legality would be validating somebody else's workspace — the one thing
-                    // this block forbids. So `"  sleepy-panda  "` stays a conflict rather than becoming
-                    // "no name", and a test pins that boundary. The schema would refuse `""` through `$defs/slug`, but the schema
-                    // never runs here, and that is the whole point of read-not-validated.
-                    // ([#141](https://github.com/sleepy-panda-srl/portulan/issues/141), found by Copilot
-                    // on #135 and filed rather than fixed there.)
+                    // Blank is no name, as in `resolveGovernor`; a non-blank name counts even if illegal, since
+                    // judging it would be validating somebody else's manifest.
                     const named = other.governed_by?.workspace;
                     report(
                         "residence",
@@ -1654,89 +1127,32 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // Every persona a composed pack contributes, with the key a host would bind it by. Declared out
-    // here rather than inside the branch below so the binding check has one shape to read: a workspace
-    // composing no packs contributes no personas, which is an empty list and not a missing one.
     const composedPersonas = [];
 
-    // The roots the packs section resolved, carried to the enforcement section so the two read ONE
-    // resolution rather than each running `rootPlan`. Two calls would be two answers whenever
-    // discovery is in play — the host's plugin record can change between them, and more to the point a
-    // second call is a second carrier of the precedence rule this file already imports rather than
-    // respells. `null` means the packs section never ran, which is not the same as "it ran and found
-    // nothing": the enforcement section keys on that difference below.
     let resolvedPackRoots = null;
     let packsUnresolved = 0;
 
     if (workspace.packs?.length) {
-        // Resolution, not a count. Until milestone 6 this reported how many packs were declared and
-        // said so — "a declaration only" — because there was no format to validate one against and
-        // nowhere to resolve a name. Both now exist. What is still NOT demonstrated here is resolution
-        // from a FEED: the roots below are the tree this workspace already declares, and an adopter
-        // installing a pack from a private marketplace resolves inside the installed plugin instead.
-        // The resolver takes its roots as an argument for exactly that reason — the second case is the
-        // same code path, not a parallel one — but this repository has not yet run it.
-        // Through the SHARED precedence rule rather than a third spelling of it — see `rootPlan`.
-        // `options.packRoots` keeps the meaning `compile`'s `packContributions` gives it — the FINAL
-        // root set, replacing the derived one, so an explicitly empty array means search nowhere. The
-        // three tools disagreed about this once and `../cli/compile.mjs`'s `namedRootsOption` records
-        // what that cost; aligned here before a caller finds it the same way.
-        // Built through `rootPlan` on EVERY path, including the named one. It used to short-circuit
-        // here with a plan literal, which is how `options.packRoots` came to silently ignore
-        // `discoverPacks`: a caller asking for both got one of them and no word about the other.
-        // `namedGiven` is what lets the shared rule keep this option's meaning — the FINAL root set,
-        // so an explicitly empty array still means search nowhere.
+        // `packRoots`, when given, is the final root set, as `compile` reads it: an empty array searches nowhere.
         const plan = rootPlan(dir, workspace, {
             named: options.packRoots ?? [],
             namedGiven: options.packRoots !== undefined && options.packRoots !== null,
-            // `options` carries the injected env — the same one the pointer resolver above is given.
-            // Without it this reader consulted the MACHINE the suite runs on, so the end-to-end pack
-            // cases could not build a host and the file header's "every environment input injectable"
-            // was true of one of its two readers.
             discovery: () => discoverPackRoots(options),
             forced: options.discoverPacks === true,
         });
         if (plan.refusal) throw new DoctorError(plan.refusal);
-        // Asked-for discovery that could not look is could-not-run, never a green over an unread host.
         if (plan.couldNotRun) throw new DoctorError(plan.couldNotRun);
         const roots = plan.roots;
         resolvedPackRoots = roots;
-        // Which root answered, for each root that could answer. A union's whole contract is that a
-        // tree-derived resolution is visible rather than silent, and a lookup is how a per-pack line
-        // says so without re-deriving the first-match rule.
         const originOf = new Map((plan.origins ?? []).map((o) => [o.root, o.origin]));
-        // **A MISS is a failure only where somebody CLAIMED a root**, and since 2026-08-13 that is a
-        // question about origin rather than about count. A named root is the caller's claim; a root
-        // derived from `tree` is the workspace's own claim; a **discovered** root is neither — it is a
-        // fact about the machine, and this tool must not turn a fact about the machine into a verdict
-        // about the repository. Keyed on `roots.length` alone, it did exactly that: measured
-        // 2026-08-13, `doctor examples` exited **0** and `doctor --pack-root auto examples` exited
-        // **1**, because `examples` derives no root and `tools/github` is not in this host's cache. The
-        // count key let host state flip a workspace's verdict, and making discovery the unasked default
-        // would have moved that flip onto the bare invocation — red on a laptop, green in CI.
-        //
-        // So: **discovery may flip a note to resolved, and may never turn a MISS into a FAIL.** A hit is
-        // a different matter and is graded whatever its origin — a resolved-but-invalid copy fails with
-        // its origin named, below, because that is a claim the pack's own files make about themselves.
+        // A miss fails only under a root somebody claimed: discovery may resolve a pack, never fail one.
         const claimed = roots.filter((root) => originOf.get(root) !== "discovered");
         report("packs", `resolution root ${plan.source} — ${plan.why}`);
         for (const name of workspace.packs) {
             const found = resolvePack(name, roots);
             if (!found.dir) {
-                // A workspace with no `tree` has no root of its own to search, so its declared packs are
-                // *unverifiable* rather than *wrong* — the same answer `tree`'s absence already gives
-                // every other claim needing a tree. Where a claimed root exists, resolution was claimed
-                // and a miss is a failure.
                 if (claimed.length === 0) {
-                    // Counted, never skipped: the pack was not graded, and `stats.unverifiable`'s
-                    // contract at the head of this file is that a check class which disappears without
-                    // saying so is the defect. A discovered-only miss is exactly that class.
                     stats.unverifiable += 1;
-                    // Two causes, two sentences. The claimed set is empty either because there was no
-                    // root at all — no `tree`, or discovery finding nothing — or because every root
-                    // there IS was discovered, which is a real search that nobody asked for and whose
-                    // failure is therefore nobody's claim. Saying "there is no packs root to search"
-                    // about the second is false: there was one, and it was looked in.
                     const why = roots.length
                         ? `\`${name}\` was looked for under ${roots.length} discovered root(s) and is not there — reported rather than failed, because a root discovered on this host is not a claim this workspace made: ${plan.why}`
                         : `\`${name}\` cannot be resolved — there is no packs root to search: ${plan.why}`;
@@ -1744,10 +1160,6 @@ export async function inspect(workspaceDir, options = {}) {
                 } else {
                     fail("packs", `\`${name}\` does not resolve — ${found.why}`);
                 }
-                // Counted, not inspected: an unresolved pack's manifest is unreadable, so this tool
-                // cannot know whether it would have contributed gates. The enforcement section says
-                // only that — never that gates were missed, which would claim knowledge of a file it
-                // could not open.
                 packsUnresolved += 1;
                 continue;
             }
@@ -1758,13 +1170,6 @@ export async function inspect(workspaceDir, options = {}) {
                 fail("packs", `\`${name}\` resolves to ${path.relative(dir, found.manifest)} but its manifest is unreadable — ${cause.message}`);
                 continue;
             }
-            // Refuse before grading, exactly as the workspace train does: a manifest written against a
-            // contract this validator does not implement produces confident nonsense — a key added in a
-            // later MINOR comes back as an unexpected property and the report blames the author for
-            // using the spec correctly. This sentence is normative in spec/pack.schema.json, and for one
-            // pre-commit checkpoint it was normative there and implemented nowhere, while `doctor`
-            // printed "validates against Pack Definition 99.0" — a conformance claim about a contract it
-            // had never seen.
             const declaredPack = /^([0-9]+)\.([0-9]+)$/.exec(manifest?.portulan?.pack ?? "");
             if (declaredPack) {
                 const [major, minor] = [Number(declaredPack[1]), Number(declaredPack[2])];
@@ -1790,11 +1195,6 @@ export async function inspect(workspaceDir, options = {}) {
             stats.packs += 1;
             const c = manifest.contributes ?? {};
 
-            // Milestone 7, the maintainer's ruling of 2026-08-03 on #150: the artifacts a pack ships are
-            // OPENED and validated, not counted. Until this landed, `doctor` counted these paths into the
-            // line below and read none of them — which is why spec/pack.schema.json could say an escaping
-            // `contributes.skills` value was "still inert". It is not inert once something opens it, so
-            // the containment check arrives in the same change as the opening.
             const opened = validateContributions(found.dir, c, { fail, report, pack: name });
             for (const one of opened.bindable) composedPersonas.push({ pack: name, ...one });
 
@@ -1804,19 +1204,12 @@ export async function inspect(workspaceDir, options = {}) {
                       (opened.unreadableRoots ? `, ${opened.unreadableRoots} root(s) UNREAD — that count is over what was opened, not over what was declared` : "")
                     : null,
                 c.personas?.length ? `${opened.personas} of ${c.personas.length} persona(s) opened` : null,
-                // Merged as of milestone 7's composition amendment. This said "declared and not
-                // merged" while that was true, and became false the hour `cli/recipe-set.mjs` landed
-                // — a code carrier of the same fact the schema note carries, which is why both moved
-                // in one change. The ids are printed rather than counted: the namespace is what makes
-                // a collision impossible, so a reader should be able to see it.
                 c.verify?.length
                     ? `${c.verify.length} recipe(s) composed as ${c.verify.map((r) => `\`${composedId(name, r.id)}\``).join(", ")}`
                     : null,
                 c.gates?.length ? `${c.gates.length} gate fragment(s)` : null,
             ].filter(Boolean);
-            // Stated only where the set is a union, because that is the only arrangement in which a
-            // reader cannot tell the origin from the invocation they typed. Adding it everywhere would
-            // put a sentence on every line that says nothing the command did not already say.
+            // Named only for a union, the one plan whose origin the invocation does not show.
             const origin = plan.source === "union" ? originOf.get(found.root) ?? null : null;
             const from =
                 origin === "discovered"
@@ -1829,15 +1222,7 @@ export async function inspect(workspaceDir, options = {}) {
                 `\`${name}\` resolves${from} to ${path.relative(dir, found.dir)} and validates against Pack Definition ${manifest.portulan.pack} — contributes ${parts.length ? parts.join(", ") : "nothing"}`,
             );
 
-            // **A SHADOWED pack is reported, and the report says WHAT DIFFERS** (#264). Resolution is
-            // first-match-wins and discovered roots come first, so where the host carries a copy of a
-            // pack the tree also carries, the installed one answers and nothing said so. Silence about
-            // the shadowed copy is the part that makes the failure unreproducible: the compiled artifact
-            // moves, the rail reds, and the deciding input is a directory outside the repository.
-            //
-            // A REPORT, never a verdict — an installed pack shadowing a tree copy is a fact about the
-            // machine, and this tool must not turn a fact about the machine into a verdict about the
-            // repository (the boundary this file already states for discovered roots).
+            // First match wins and discovered roots come first, so an installed copy can shadow the tree's.
             {
                 const shadowed = shadowedCopy(name, origin, roots, (r) => originOf.get(r)) ?? { dir: null };
                 if (shadowed.dir) {
@@ -1845,23 +1230,12 @@ export async function inspect(workspaceDir, options = {}) {
                     try {
                         other = JSON.parse(fs.readFileSync(shadowed.manifest, "utf8"));
                     } catch (cause) {
-                        // Could-not-compare, in so many words. A shadow we cannot read is not a shadow
-                        // we can call harmless, and saying nothing here would be the silence this whole
-                        // report exists to end.
                         report(
                             "packs",
                             `\`${name}\` is SHADOWED — the tree-derived root also carries it at ${path.relative(dir, shadowed.dir)}, and that copy could not be read (${cause.message}), so what differs could not be compared`,
                         );
                     }
                     if (other) {
-                        // **The comparison lives in `compile.mjs`, and this calls it.** It grew here,
-                        // and its two earlier spellings each claimed more than they compared — a
-                        // projection over `[id, tier, action]` that read a copy differing in `reason`
-                        // as agreeing, and a *byte-identical* claim `JSON.stringify` of a parsed value
-                        // cannot make. `compile` now has to answer the same question in order to refuse
-                        // a shadow it cannot honestly pick between (#316), and a second copy of a
-                        // comparison already corrected twice is exactly proposal `0020`'s defect. The
-                        // rationale for parsed-and-key-sorted moved with the code.
                         const differs = packDifferences(manifest, other);
                         report(
                             "packs",
@@ -1875,15 +1249,6 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // Workspace Definition 2.3's and 2.4's conditional constraints, here for the same reason the
-    // `repository`/`tree` pair above is: `dependentRequired` is not in the subset spec/README.md
-    // declares, so the schema cannot carry any of them and ../spec/slots.md says so.
-    //
-    // The count went one → three in a single MINOR at 2.3 and three → five at 2.4. That is the
-    // thing to watch rather than absorb quietly: every one of them is a rule the schema states
-    // nowhere, so a workspace validated by some other tool against the published schema alone would
-    // pass shapes this validator refuses. `../spec/README.md` carries the running count for exactly
-    // that reason.
     if (workspace.librarian && !workspace.slots?.memory) {
         fail(
             "cross",
@@ -1893,23 +1258,6 @@ export async function inspect(workspaceDir, options = {}) {
         );
     }
 
-    // Every number the schema can only type as `number`, checked here for the constraint the declared
-    // subset cannot express. Without this, `record_days: 0` — or `-1`, or `"90"` — passes CI green and
-    // fails at 06:00 on a Monday, when `cli/librarian.mjs` refuses it with exit 2 and nobody is
-    // watching. A policy defect that only surfaces in an unattended run is the worst place for one, and
-    // this is a `doctor` failure rather than a `librarian` one because it is a fact about the manifest.
-    // Raised by Copilot on #81, suppressed half. The memory budgets are checked the same way, and were
-    // missing it too — a sibling of the same class, fixed in the same stroke rather than left for the
-    // next round to find.
-    //
-    // **The message stated a downstream behaviour this tree does not have**, and that is issue #84,
-    // fixed here. It said a zero or negative value *reads as undeclared to the tool that consumes it* —
-    // which was true of nothing: both consumers, `cli/index.mjs`'s `budgetNumber` and
-    // `cli/librarian.mjs`'s `threshold`, refuse such a value outright with exit 2. What the sentence
-    // described was the hazard those refusals exist to prevent, written in the present tense as though
-    // it survived them. ../.portulan/dod.md condition 4 refuses a claim of a capability that does not
-    // exist; this was the same error pointed the other way, a claim of a *defect* that does not exist,
-    // inside a failure message — where a reader has the least room to check it.
     const positive = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
     for (const [where, value] of [
         ["memory.index.budget.lines", workspace.memory?.index?.budget?.lines],
@@ -1931,6 +1279,90 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
+    const alwaysTokens = workspace.context?.always?.budget?.tokens;
+    if (alwaysTokens !== undefined && !positive(alwaysTokens)) {
+        fail(
+            "schema",
+            `context.always.budget.tokens is ${JSON.stringify(alwaysTokens)}, which is not a positive integer. ` +
+                "The declared keyword subset has no `minimum` and cannot say `integer`, so this is checked here",
+        );
+    }
+
+    // Not an integer: 2.99 bytes per token is a real figure.
+    const bytesPerToken = workspace.context?.ratio?.bytes_per_token;
+    if (bytesPerToken !== undefined && !(Number.isFinite(bytesPerToken) && bytesPerToken >= 1)) {
+        fail(
+            "schema",
+            `context.ratio.bytes_per_token is ${String(bytesPerToken)}, and it must be a finite number of at least 1. ` +
+                "A token covers at least one byte, so a smaller figure is tokens per byte entered inverted. The " +
+                "declared keyword subset has no `minimum`, so this is checked here",
+        );
+    }
+
+    const cutoff = workspace.memory?.store?.budget?.cutoff;
+    if (cutoff !== undefined) {
+        const m = typeof cutoff === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(cutoff) : null;
+        const at = new Date(0);
+        if (m) at.setUTCFullYear(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+        if (!m || at.toISOString().slice(0, 10) !== cutoff) {
+            fail(
+                "schema",
+                `memory.store.budget.cutoff is ${JSON.stringify(cutoff)}, which is not a real day written YYYY-MM-DD. ` +
+                    "The declared keyword subset's pattern admits a day that does not exist, so this is checked here",
+            );
+        }
+        if (workspace.memory?.store?.budget?.record_kilobytes === undefined) {
+            fail(
+                "cross",
+                "`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",
+            );
+        }
+    }
+
+    // Held to the bounds of `readSpend` and `overflowingWrite` in ./ledger.mjs, so what passes here, the ledger takes.
+    const readMultiplier = workspace.spend?.multipliers?.read;
+    if (readMultiplier !== undefined && !(Number.isFinite(readMultiplier) && readMultiplier > 0 && readMultiplier <= 1)) {
+        fail(
+            "schema",
+            `spend.multipliers.read is ${String(readMultiplier)}, and it must be a finite number above 0 and at most 1. A token ` +
+                "read from cache costs something, and never more than the same token sent uncached. The declared keyword subset " +
+                "has neither `minimum` nor `maximum`, so this is checked here",
+        );
+    }
+    for (const lifetime of ["5m", "1h"]) {
+        const writeMultiplier = workspace.spend?.multipliers?.write?.[lifetime];
+        if (writeMultiplier !== undefined && !(Number.isFinite(writeMultiplier) && writeMultiplier >= 1)) {
+            fail(
+                "schema",
+                `spend.multipliers.write["${lifetime}"] is ${String(writeMultiplier)}, and it must be a finite number of at least 1. ` +
+                    "Writing a token to the cache costs at least what sending it uncached does. The declared keyword subset " +
+                    "has no `minimum`, so this is checked here",
+            );
+        }
+    }
+    if (Number.isFinite(readMultiplier) && readMultiplier > 0) {
+        for (const lifetime of ["5m", "1h"]) {
+            const writeMultiplier = workspace.spend?.multipliers?.write?.[lifetime];
+            if (Number.isFinite(writeMultiplier) && !Number.isFinite(writeMultiplier / readMultiplier)) {
+                fail(
+                    "schema",
+                    `spend.multipliers.write["${lifetime}"] divided by spend.multipliers.read overflows, so no finite restart ` +
+                        "threshold can be computed from them. No keyword in the declared subset relates two figures, so this is " +
+                        "checked here",
+                );
+            }
+        }
+    }
+    const horizonRequests = workspace.spend?.horizon?.requests;
+    if (horizonRequests !== undefined && !positive(horizonRequests)) {
+        fail(
+            "schema",
+            `spend.horizon.requests is ${JSON.stringify(horizonRequests)}, which is not a positive integer. ` +
+                "The declared keyword subset has no `minimum` and cannot say `integer`, so this is checked here",
+        );
+    }
+
     if (workspace.librarian?.staleness?.proposal_days !== undefined && !workspace.slots?.proposals) {
         fail(
             "cross",
@@ -1950,21 +1382,9 @@ export async function inspect(workspaceDir, options = {}) {
         );
     }
 
-    // An index inside the store it indexes is counted as a record by the retirement and provenance
-    // walks below — sized into the KB figure and reported for stating no retirement condition. The
-    // repair is a siting rule rather than an exemption by filename: teaching one name to hide from a
-    // walk is a door any record could use, which is the fail-open class this repository has now found
-    // eight of in its own scaffolding — and then this check turned out to be the ninth, in the very
-    // containment test that was supposed to be the door-less alternative. See `isInside`.
     if (workspace.memory?.index?.path && workspace.slots?.memory) {
         const storeDir = path.resolve(dir, workspace.slots.memory);
         const indexPath = path.resolve(dir, workspace.memory.index.path);
-        // Imported rather than restated. This check and `index`'s had two copies of one containment
-        // rule and both carried the same fail-open: `!path.relative(…).startsWith("..")` calls a file
-        // named `..index.md` *outside* the directory it sits in, because a leading `..` in a filename
-        // is not a traversal. Measured — such an index was written into the store, and this walk then
-        // counted it as a record. Same reasoning as `parse`/`backends` from ./compile.mjs above: a
-        // rule with two copies drifts, and these two drifted identically before either shipped.
         if (isInside(storeDir, indexPath)) {
             fail(
                 "cross",
@@ -1975,10 +1395,6 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // The handoff series gets both of the memory index's conditional requirements, added at 2.5, and
-    // gets them here rather than in a second copy of the reasoning: they are the same two rules about
-    // the same kind of object. What differs is only which walk would swallow a badly-sited index —
-    // `doctor`'s store report there, `docs.sh`'s date correspondence here.
     if (workspace.handoffs && !workspace.slots?.handoffs) {
         fail(
             "cross",
@@ -2002,10 +1418,6 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // The scopes layer, at 2.6, gets the same pair for the third time. What differs is only which walk
-    // would swallow a badly-sited index: the store report there, `docs.sh`'s date correspondence for the
-    // handoffs, and here `index`'s orphan sweep — a generated file inside the layer would be read by the
-    // one check whose whole job is telling an arrived location from a directory somebody made.
     if (workspace.personas && !workspace.slots?.personas) {
         fail(
             "cross",
@@ -2028,33 +1440,13 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // ---- claims against the tree
+    // ---------------------------------------------------------------- claims against the tree
     const treeRoot = workspace.tree ? path.resolve(dir, workspace.tree) : null;
     const claimTargets = [];
 
-    // ---- persona ↔ agent bindings
-    //
-    // Row 7's fourth validation, and the one that was still owed after milestone 7 session 2 built the
-    // other three. A persona is host-agnostic — its `tools:` are capability classes — and a **binding**
-    // is the file that translates one into a host's own vocabulary. `core/personas/README.md` records
-    // that the translation is **lossy**: of three charters exactly one survives it. So this check grades
-    // agreement and never equivalence, and there are exactly two things it can honestly hold.
-    //
-    // **Absence is reported, never failed**, for the same reason a pointer's `governed_by` is reported
-    // and never graded: whether a binding file exists is deployment state, and a persona with no binding
-    // is a legitimate choice — an adopter may be on a host with no agent layer at all. This repository is
-    // the exhibit rather than the embarrassment: the `checkpoints` supervisor is deliberately unbound,
-    // because that pack's own `self-certify-a-checkpoint` gate makes a **fresh context** the mechanism,
-    // and a subagent binding inside the implementer's session is precisely what it refuses.
-    //
-    // **A binding that contradicts its persona is failed**, because that one is wrong on every host: the
-    // loader keys on frontmatter `name`, so a mismatch binds a persona nobody named, and a binding with
-    // no `tools:` hands the role the host's whole toolbox — the context firewall's first part, gone.
+    // ---------------------------------------------------------------- persona ↔ agent bindings
     if (composedPersonas.length) {
         if (!treeRoot) {
-            // The same answer every other claim gets without a tree, and it is counted with them: a
-            // workspace that declares no repository has nowhere for `agents/` to be, which is not the
-            // same as having looked and found nothing.
             stats.unverifiable += composedPersonas.length;
             report(
                 "bindings",
@@ -2062,17 +1454,12 @@ export async function inspect(workspaceDir, options = {}) {
                     `so there is no repository to look in. Unverifiable, not unbound`,
             );
         }
-        // BOTH sides are resolved before they are compared, which is the half a first cut got wrong.
-        // Comparing a realpathed file against an unresolved root fails wherever the root itself sits
-        // under a link — every macOS temporary directory does, `/var` being a link to `/private/var` —
-        // so the guard below refused perfectly ordinary bindings until this line existed. That is the
-        // rule `validateContributions` already applies to a pack directory, applied to a tree.
+        // Both sides realpathed: a tree under a link (macOS `/var`) would otherwise refuse ordinary bindings.
         let realTree = treeRoot;
         try {
             if (treeRoot) realTree = fs.realpathSync(treeRoot);
         } catch {
-            // An unresolvable tree is already reported by the claims checks; keeping the declared path
-            // here means the containment test still runs, on the stricter of the two spellings.
+            // Already reported by the claims checks; the declared path keeps the containment test running.
         }
         for (const persona of treeRoot ? composedPersonas : []) {
             const rel = path.join(AGENT_DIR, `${persona.key}.md`);
@@ -2080,23 +1467,8 @@ export async function inspect(workspaceDir, options = {}) {
             const keyed = persona.keyedBy === "declaration" ? "" : " (keyed by filename — the persona declares no `name`)";
             const file = path.join(treeRoot, rel);
 
-            // **The key is a pack's free text, so it is contained before it is opened.** A persona's
-            // `name` is unconstrained — the five-part contract does not include it and the Pack
-            // Definition does not reach persona markdown — so a pack declaring `name: ../../poison`
-            // aims this read anywhere on the machine. Before this guard it read the file, validated
-            // it, and printed *names and tool grant agree*: a green over something no host would ever
-            // load as an agent, with the outside file's own `name:` echoed into the report.
-            //
-            // Resolved and then compared, never matched as a pattern — the rule `validateContributions`
-            // already applies to a pack's own paths, and the same one `plugin-lint` applies to a
-            // symlinked `agents/` entry. A symlink is why the test is on the REAL path: a link inside
-            // the tree pointing out of it passes any check on the spelling.
-            // The LEXICAL test comes first, and it is not redundant with the resolved one below.
-            // `path.join("agents", "../../poison.md")` is `../poison.md`, so a traversing name aims
-            // outside the tree whether or not anything is there — and where nothing is, the resolved
-            // test never runs and this check fell through to its *unbound* sentence, which named the
-            // escaping path as "the one location a host loads agents from". A refusal that depends on
-            // whether the attacker's file happens to exist is not a refusal.
+            // The key is a pack's free text, so it is contained before it is opened: lexically here, since the
+            // realpath test below is skipped where nothing exists.
             if (!isInside(treeRoot, path.resolve(treeRoot, rel))) {
                 fail(
                     "bindings",
@@ -2114,8 +1486,7 @@ export async function inspect(workspaceDir, options = {}) {
                     report("bindings", `${where}'s binding at \`${rel}\` could not be resolved — ${cause.code ?? cause.message}. Unread, not absent`);
                     continue;
                 }
-                // ENOENT is the ordinary unbound case and falls through to the read below, which
-                // renders the one sentence this check has for it.
+                // ENOENT falls through to the read below, which reports the persona unbound.
             }
             if (real !== null && !isInside(realTree, real)) {
                 fail(
@@ -2134,12 +1505,9 @@ export async function inspect(workspaceDir, options = {}) {
                     report(
                         "bindings",
                         `${where} has no host binding at \`${rel}\`${keyed} — reported, not failed: a persona without one is unbound rather than wrong, ` +
-                            "and this is the one location a Claude Code host loads agents from",
+                            "and this is where a Claude Code plugin's agents load from — a repository that is not a plugin loads its agents from `.claude/agents/`",
                     );
                 } else {
-                    // `existsSync` would answer *false* here and this would print as an absence. The
-                    // distinction is the same one `validateContributions` carries: only a missing file
-                    // means absent, and a question that could not be answered is not an answer.
                     report("bindings", `${where}'s binding at \`${rel}\` could not be read — ${cause.code ?? cause.message}. Unread, not absent`);
                 }
                 continue;
@@ -2170,13 +1538,7 @@ export async function inspect(workspaceDir, options = {}) {
                 );
                 continue;
             }
-            // *Declared*, not *agrees*: the check above establishes only that `tools:` is a non-empty
-            // string. Nothing here compares it against the persona's own contract — the persona's
-            // `tools:` never reaches `bindable` — and by design, since `../docs/milestones/m07.md`
-            // holds that a binding may licitly grant less, or other, than the persona describes. The
-            // previous wording said the two *agree*, which reported a grant of `Read, Write, Bash` to a
-            // persona whose contract is *does not write* as though it had been checked. Found by
-            // milestone 7's close pass, forcing exactly that case green.
+            // Declared, not compared: a binding may grant less, or other, than its persona describes.
             report("bindings", `${where} is bound by \`${rel}\`${keyed} — ${BINDING_OK}`);
         }
     }
@@ -2189,8 +1551,6 @@ export async function inspect(workspaceDir, options = {}) {
             try {
                 source = fs.readFileSync(card, "utf8");
             } catch (cause) {
-                // Was a bare `continue`: an unreadable card dropped every claim it makes, silently,
-                // and the run stayed green. A card that cannot be read is not a card with no claims.
                 fail("claims", `repos/${name}.md could not be read, so its claims went unchecked — ${cause.message}`);
                 continue;
             }
@@ -2200,28 +1560,12 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // The gate map's claim is extracted OUTSIDE the tree branch on purpose. Reading it only when a
-    // tree exists is how a check class disappears without saying so — a no-`tree` workspace whose
-    // gate map named a status check nothing reports used to produce no mention of it at all, while
-    // spec/slots.md promised those claims were "counted and reported unverifiable, never skipped
-    // silently". Found at the pre-commit checkpoint, in the paragraph that made the promise.
     let claimedChecks = [];
-    // The same list, captured before anything mutates it. `claimedChecks` is emptied further down
-    // when there are no workflows to compare against, and the floor cross-check read it afterwards —
-    // reporting that the gate map named nothing, about a gate map that named it plainly. That is the
-    // SECOND consumer caught reading this array after the mutation; the first fix added a separate
-    // flag for one consumer instead of making the array safe to read, so the next consumer inherited
-    // the trap. Found by review on the pull request. Snapshot rather than flag this time, so a third
-    // consumer inherits something true instead of something to remember.
+    // A snapshot: `claimedChecks` is emptied below where there are no workflows to compare it with.
     let declaredChecksInProse = [];
     let gatesRead = false;
-    // What the tree's workflows actually report, filled in once a tree is available. `null` means
-    // no tree was declared, which is a different thing from a tree with no workflows in it.
+    // Null without a tree, which differs from a tree with no workflows.
     let workflowContexts = null;
-    // Captured immediately after parsing and never reassigned. `claimedChecks` is emptied later when
-    // there are no workflows to compare against, and keying the "names no check" report off the
-    // mutated array made it fire for a gate map that had named one — two contradictory findings from
-    // the same run.
     let namedAnyCheck = false;
     if (workspace.slots?.gates) {
         try {
@@ -2230,8 +1574,7 @@ export async function inspect(workspaceDir, options = {}) {
             gatesRead = true;
             namedAnyCheck = claimedChecks.length > 0;
         } catch {
-            // Unreadable is already a `paths` failure; it must not also become an exit-2 crash,
-            // which would trade a verdict this run had already reached for "could not run".
+            // Already a `paths` failure; a throw here would trade the verdicts reached for exit 2.
         }
     }
 
@@ -2242,18 +1585,11 @@ export async function inspect(workspaceDir, options = {}) {
                 report("claims", `${claim.where} states ${claim.what}, which contains nothing path-shaped to check — counted as unverifiable rather than passed over`);
                 continue;
             }
-            // A token pulled out of a command is never a *checked* claim, whether or not it happens to
-            // resolve. Counting it in `stats.claims` when it resolved and in `unverifiable` when it did
-            // not would make the accounting depend on incidental filesystem state and would overstate
-            // what was verified — `docker run -v $(pwd)/state:/state` is not a claim about the tree
-            // because `state` exists. It is unverifiable either way; only the finding differs.
             const checkable = claim.severity !== "report";
             if (checkable) stats.claims += 1;
             else stats.unverifiable += 1;
 
-            // Two bases, because a card legitimately mixes them: `.portulan/` is written from the
-            // repository root while `../../core/` is written from the card. A claim that resolves
-            // under either is a claim that points at something real, which is what the lint is for.
+            // Two bases: a card writes some paths from the repository root and some from itself.
             const resolved = [path.resolve(treeRoot, claim.target), path.resolve(claim.base, claim.target)];
             if (!resolved.some((p) => fs.existsSync(p))) {
                 const message = `${claim.where} claims ${claim.what}, which exists nowhere in the tree`;
@@ -2265,10 +1601,6 @@ export async function inspect(workspaceDir, options = {}) {
             }
         }
 
-        // Read once and shared by two consumers: the gate map's prose claim about required checks,
-        // and — since the floor backend arrived — the gate policy's `floor.checks`. It was nested
-        // inside the first consumer's `if`, which would have left the second silently unable to
-        // check anything whenever the prose named nothing.
         const workflows = path.join(treeRoot, ".github", "workflows");
         let jobs = [];
         let found = false;
@@ -2283,9 +1615,6 @@ export async function inspect(workspaceDir, options = {}) {
         workflowContexts = { contexts, found };
 
         if (claimedChecks.length) {
-            // A job whose id is claimed but whose reported context differs is the interesting failure,
-            // and it deserves its own message: "no job declares that" would send the reader hunting for
-            // a missing job when the job is right there under a display name.
             if (!found) {
                 stats.unverifiable += claimedChecks.length;
                 report("claims", `the gate map requires ${claimedChecks.length} status check(s) — ${claimedChecks.map((c) => `\`${c}\``).join(", ")} — and there are no workflows in the tree to report them — unverifiable`);
@@ -2321,12 +1650,6 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // Finding no claim is a result, not an absence, and it has to say so. `doctor` recognises the
-    // required-check claim by one convention — a table row whose first cell reads "required status
-    // check" — and no template defines that label (see spec/slots.md). A gate map wording the row
-    // differently produced **nothing at all**: no finding, no count, and a reader with a GREEN in
-    // front of them had no way to tell "this workspace requires no check" from "I did not recognise
-    // your table". Reported since the review that measured it.
     if (gatesRead && !namedAnyCheck) {
         report(
             "claims",
@@ -2334,50 +1657,21 @@ export async function inspect(workspaceDir, options = {}) {
         );
     }
 
-    // ---- the per-host degradation report
-    //
-    // `../docs/vision.md`: "the enforcement backends are per-host with an honest degradation
-    // report." The compiler's accounting IS that report's data — every rule ends as compiled or
-    // refused-with-a-reason, per backend — so this reads the backends rather than re-deriving what
-    // they cover. Two implementations of one accounting is the drift this repository keeps finding,
-    // and it is the reason `./gate.mjs` imports the matcher instead of copying it.
-    //
-    // Reported, never failed, with one exception below: nothing legislates a coverage floor, and
-    // `doctor` does not enforce what nobody legislated — the same reasoning that made `retirement`
-    // report-only. What it must not do is print a green that reads as "everything is enforced".
+    // ---------------------------------------------------------------- the per-host degradation report
+    // Coverage is reported, never failed: nothing legislates a minimum.
     if (workspace.gates) {
         const policyFile = path.resolve(dir, workspace.gates);
         let parsed = null;
         let columns = null;
         let composed = null;
         try {
-            // **Composed before the policy is parsed**, which is the order `compile` uses and for its
-            // reason: a pack's fragment is then validated by exactly the code that validates a
-            // hand-written rule, rather than by a second, laxer path. Through `compile.mjs`'s own
-            // `packContributions` + `composeFragments` — this file already imports four functions from
-            // there and mints none of them, because the last thing a policy needs is a second opinion
-            // about what it contains.
-            //
-            // Why this reads the composed set at all: until 2026-08-13 it read `gates.json` alone, so
-            // its report described a policy the workspace does not have. Measured on `d5a5eb7`, this
-            // section printed `Claude Code: 10 of 23 rule(s) compiled → .claude/settings.json` while
-            // that file carried **eleven** rules' compilation, the eleventh being a composed one — an
-            // arrow naming an artifact beside a number that is not that artifact's. `../.portulan/dod.md`
-            // condition 1 had already been rewritten from *declares* to **yields** for the recipe set,
-            // for the identical reason; this is that word applied to the gate policy.
+            // Composed before parsing, as `compile` does, so a pack's fragment is validated as a hand-written rule is.
             const composition = packContributions(dir, ".", { packRoots: resolvedPackRoots ?? [] });
             composed = composeFragments(JSON.parse(fs.readFileSync(policyFile, "utf8")), composition.contributions);
             parsed = parse(composed.policy);
-            // Inside the SAME guard as the parse, which it was not for one checkpoint. A policy can
-            // parse cleanly and still be refused by a backend — a declared floor no rule reaches, or
-            // gate rules that all compile to nothing — and with `backends()` outside the try, that
-            // threw out of `inspect`, exited 2, and discarded every verdict this run had already
-            // reached. Trading a verdict for "could not run" is the milestone-2 gates-file defect,
-            // and it was sitting three lines under a comment naming it. Found at the pre-commit
-            // checkpoint.
+            // In the guard: a backend may refuse a policy that parses, and an unguarded throw discards every verdict.
             columns = backends(parsed, { source: workspace.gates });
         } catch (cause) {
-            // A defect in the WORKSPACE's own policy, reported where every other finding is.
             fail("enforcement", `${workspace.gates} — ${cause.message}`);
             parsed = null;
         }
@@ -2391,16 +1685,12 @@ export async function inspect(workspaceDir, options = {}) {
                 );
             }
 
-            // The honest signal, split by tier because the halves mean opposite things. An `auto`
-            // rule compiled by nothing is the system working; a `gated` or `prohibited` one is a
-            // gate that exists only as a sentence, which is what this product is against.
+            // Gated and prohibited rules only: an `auto` rule compiled by nothing is the system working.
             const uncovered = parsed.rules.filter(
                 (rule) =>
                     (rule.tier === "gated" || rule.tier === "prohibited") &&
                     columns.every((c) => !c.compiled.some((x) => x.id === rule.id)),
             );
-            // "policy this workspace yields" rather than "declared policy": the count now includes
-            // composed rows, so *declared* would be the word that made this sentence wrong.
             report(
                 "enforcement",
                 uncovered.length
@@ -2408,15 +1698,7 @@ export async function inspect(workspaceDir, options = {}) {
                     : "every gate this workspace yields is compiled by at least one backend — which says the policy is reachable, never that a host honours what was emitted",
             );
 
-            // Declared from composed, kept legible. A reader who cannot tell which rows came from a
-            // pack cannot tell which half to go and change, and the composed half lives in a file this
-            // workspace does not own.
             if (composed.added?.length) {
-                // Its own subject and its own members. "N of those" read as the uncovered gates named on
-                // the line above — of which only one is composed — while the real antecedent was the
-                // whole yield two lines up. And a count alone does not tell a reader which file to
-                // change: with two gate-contributing packs, "composed from this workspace's packs" names
-                // neither. `composed.added` already carries `{ pack, id }`, so the members are printed.
                 const members = composed.added.map((a) => `\`${a.id}\` (${a.pack})`).join(", ");
                 report(
                     "enforcement",
@@ -2424,10 +1706,6 @@ export async function inspect(workspaceDir, options = {}) {
                 );
             }
 
-            // What this tool can KNOW, and no more. An unresolved pack's manifest is unreadable, so
-            // whether it would have contributed gates is not a fact in reach — the sentence says the
-            // totals may be incomplete, never that gates were missed. Severity is the packs section's
-            // to set and it has already set it above, origin-keyed; this line does not re-litigate it.
             if (packsUnresolved) {
                 report(
                     "enforcement",
@@ -2435,7 +1713,7 @@ export async function inspect(workspaceDir, options = {}) {
                 );
             }
 
-            // ---- the floor's declared contexts, against the tree and against the prose
+            // ---------------------------------------------------------------- the floor's declared contexts
             for (const check of parsed.floor?.checks ?? []) {
                 if (check.integration_id === undefined) {
                     report(
@@ -2454,10 +1732,7 @@ export async function inspect(workspaceDir, options = {}) {
                     continue;
                 }
                 stats.claims += 1;
-                // The one enforcement FAILURE, and it earns the severity: a required context that
-                // never reports blocks every pull request, and `enforce_admins` leaves nobody able
-                // to force past it. That is proposal 0004's lesson, which cost a three-step rename
-                // to work around after the fact — the highest-priced typo this tree can catch.
+                // Failed, not reported: a required context that never reports blocks every pull request.
                 if (!workflowContexts.contexts.includes(check.context)) {
                     fail(
                         "enforcement",
@@ -2466,18 +1741,7 @@ export async function inspect(workspaceDir, options = {}) {
                 }
             }
 
-            // Two in-tree carriers of one fact: the gate map's platform-floor table and the policy's
-            // `floor`. Reported rather than failed — the prose row is a human summary and may
-            // legitimately be shaped differently — but never left silent, because two files stating
-            // one policy is this repository's signature defect, and the prose half is the half no
-            // other check here reads for content.
-            // NOT gated on the prose having named a check. It was for one round, which exempted the
-            // worst divergence there is: a policy declaring required checks beside a gate-map row that
-            // is missing or written in a shape `requiredCheckClaims` does not recognise. The generic
-            // "names no required status check" note fires there, but it reports that nothing was
-            // compared against the *tree* and says nothing about the policy carrying checks the prose
-            // does not. A check that quietly skips its own extreme case is
-            // `a-checker-must-refuse-what-it-cannot-check.md` again. Found by review, round 2.
+            // Not gated on the prose naming a check: a missing or unrecognised row is the widest divergence.
             if (parsed.floor && gatesRead) {
                 const declared = parsed.floor.checks.map((c) => c.context);
                 const missingFromProse = declared.filter((c) => !declaredChecksInProse.includes(c));
@@ -2494,33 +1758,11 @@ export async function inspect(workspaceDir, options = {}) {
             }
         }
     } else if (workspace.packs?.length) {
-        // **The edge one door down, named rather than left to be found.** This section is guarded on
-        // the workspace declaring a `gates` slot, and composition does not care whether it does: a
-        // workspace can compose a pack that contributes gates while declaring no policy of its own,
-        // and then the guard above skips — silence, over a policy that has gate rules in it. That is
-        // the same shape as the divergence this whole change repairs, displaced by one condition.
-        //
-        // Measured on `d5a5eb7`: `examples/` is exactly this workspace — it composes
-        // `rituals/checkpoints`, which contributes two gate fragments, and declares no `gates` and
-        // carries no `gates.json`. `compile --workspace examples --check` exits **2** there
-        // (could-not-run: nothing to compose *into*), while `doctor` said nothing at all.
-        //
-        // **Report, never fail**, and the severity is not a preference: `../.portulan/verify/doctor.sh`
-        // grades `examples` on every run as part of a required check, so a failure here would turn the
-        // repository's own verify red over a workspace that is behaving as designed. It is also keyed
-        // on contributions being non-empty rather than on `packs` being non-empty, so a workspace
-        // composing packs that contribute no gates keeps producing zero enforcement findings — which
-        // is what `./doctor.test.mjs`'s no-gates case pins.
+        // Reported, never failed: gate fragments composed with no `gates` policy are a valid shape, only uncompiled.
         try {
             const { contributions } = packContributions(dir, ".", { packRoots: resolvedPackRoots ?? [] });
             const fragments = contributions.reduce((n, c) => n + (c.fragments?.length ?? 0), 0);
             if (fragments) {
-                // `fragments` counts RESOLVED packs only — `packContributions` cannot read a manifest it
-                // could not find — so where a declared pack did not resolve this number is a floor and
-                // not a total. Saying "composes N from its packs" without that caveat implies the count
-                // covers every declared pack, which is the same overstatement this whole change repairs
-                // one branch up: a number claiming more than it measured. The gates-slot branch already
-                // carried the caveat and this one did not. (Copilot, round 1 on #241.)
                 const incomplete = packsUnresolved
                     ? `, and ${packsUnresolved} declared pack(s) did not resolve, so this count is a floor rather than a total`
                     : "";
@@ -2530,13 +1772,12 @@ export async function inspect(workspaceDir, options = {}) {
                 );
             }
         } catch (cause) {
-            // A composition this tool cannot even read is the packs section's finding, not this one's;
-            // saying it twice would be one defect wearing two severities.
+            // The packs section owns that failure; failing it here too would count one defect twice.
             report("enforcement", `the composed gate contributions could not be read — ${cause.message}`);
         }
     }
 
-    // ---- provenance, and the store's own growth
+    // ---------------------------------------------------------------- provenance and the store's growth
     if (workspace.slots?.memory) {
         const memoryDir = path.resolve(dir, workspace.slots.memory);
         let entries = [];
@@ -2545,19 +1786,12 @@ export async function inspect(workspaceDir, options = {}) {
         } catch { /* the missing directory is already a `paths` failure */ }
 
         for (const entry of entries) {
-            // A record that is present and unreadable is a defect in the WORKSPACE — exit 1, reported
-            // alongside everything else already found. Letting the read throw made it exit 2 and
-            // discarded every finding the run had reached, which is the gates-file defect over again
-            // one function down: the same shape, missed in the same change that fixed it.
             let source;
             try {
                 source = fs.readFileSync(path.join(memoryDir, entry), "utf8");
             } catch (cause) {
                 stats.records += 1;
-                // The unreadable record still occupies the store, and it is already counted in
-                // `records` — so it is sized from stat, or `record(s)` and `KB` would disagree
-                // about what a record is. Its content is still never assessed: this run is
-                // already red on the read failure, and only the accounting stays consistent.
+                // Sized from stat, so the record and KB counts agree; its content is never assessed.
                 try { stats.bytes += fs.statSync(path.join(memoryDir, entry)).size; } catch { /* unstattable: its size stays unknown */ }
                 stats.unassessed += 1;
                 fail("provenance", `${entry} could not be read — ${cause.message}`);
@@ -2570,11 +1804,7 @@ export async function inspect(workspaceDir, options = {}) {
             const isRule = type === "rule";
             if (isRule) stats.rules += 1;
 
-            // Growth control rather than provenance: the retirement pass demotes a record by the
-            // condition its own `Retire when:` line states, so a record stating none is one no
-            // condition will ever demote. Reported, never failed — no rule mandates the field, and
-            // doctor does not enforce what nobody legislated. Checked ahead of the provenance
-            // branches below, so a record with a provenance defect is still assessed for this.
+            // Ahead of the provenance branches below, which `continue`, so every readable record is assessed.
             if (!RETIRE_WHEN.test(source)) {
                 stats.unretirable += 1;
                 report(
@@ -2589,10 +1819,6 @@ export async function inspect(workspaceDir, options = {}) {
                 continue;
             }
             if (!fields) {
-                // Prose provenance. Mandatory only on a rule: thesis 4, proposal 0002 as adopted,
-                // dod.md condition 3 and the task's own criterion are all rule-scoped, and having
-                // doctor bind types nobody legislated for would be tooling enforcing a rule the
-                // constitution does not state — backwards for this product.
                 const message = `${entry} (${type || "untyped"}) carries prose provenance rather than a link or a sealed stamp`;
                 isRule ? fail("provenance", message) : report("provenance", message);
                 continue;
@@ -2607,9 +1833,6 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
-    // Always emitted, including for zero records. A workspace with no memory yet is valid — the
-    // minimality rule is explicit that a day-one workspace must pass — but "checked nothing" and
-    // "checked everything and found nothing wrong" print identically unless one of them says so.
     const proportion = stats.rules ? `${stats.sealed} of ${stats.rules}` : "0 of 0";
     report(
         "provenance",
@@ -2620,12 +1843,7 @@ export async function inspect(workspaceDir, options = {}) {
             ". The form is checked, never the truth: a fabricated stamp passes exactly as a real one does",
     );
 
-    // The store's growth, always emitted for the same reason the line above is: a store quietly
-    // growing and a store quietly fine print identically unless something says which. Size and
-    // count are what doctor can honestly see — it reads the tree and never git, and in a fresh
-    // clone every file's mtime is checkout time, so an age report from here would be fabrication.
-    // Staleness is ./librarian.mjs's, the scheduled pass, which may legitimately ask git — and which
-    // is not a verify recipe precisely so that asking is safe. Built at milestone 5.
+    // Size and count only: in a fresh clone every file's mtime is the checkout's, so no age is read here.
     report(
         "retirement",
         stats.records
@@ -2638,12 +1856,10 @@ export async function inspect(workspaceDir, options = {}) {
               (stats.unassessed
                   ? `; ${stats.unassessed} unreadable and never assessed`
                   : "") +
-              ". Size and count only: ages live in git, which doctor does not read, so staleness belongs to `cli/librarian.mjs` — the scheduled pass, which may ask git and does"
+              ". Size and count only: memory ages are not measured here, so staleness belongs to `cli/librarian.mjs` — the scheduled pass, which may ask git and does"
             : "no memory records — nothing measured, nothing awaiting retirement",
     );
 
-    // Always emitted, for the third time on this page and for the same reason: a workspace nobody
-    // scored and a workspace that scored well print identically unless one of them says which.
     const score = legibility(workspace, dir);
     const missed = score.dimensions.filter((d) => d.applicable && !d.met);
     const skipped = score.dimensions.filter((d) => !d.applicable);
@@ -2656,38 +1872,72 @@ export async function inspect(workspaceDir, options = {}) {
             "because a score that could fail a workspace would make the verdict a function of how much prose somebody wrote",
     );
 
+    const always = alwaysLine(dir, workspace);
+    (always.verdict === "over" || always.verdict === "unjudged" ? fail : report)("context", always.line);
+
+    // Never a verdict: failing it would turn red every workspace drafted before the new form.
+    let form;
+    try {
+        form = formLine(dir, workspace, { over: always.verdict === "over" });
+    } catch (error) {
+        form = `not read — ${error.message}`;
+    }
+    report("form", form);
+
+    let sessions;
+    try {
+        sessions = sessionsLine(workspace);
+    } catch (error) {
+        sessions = `not read — ${error.message}`;
+    }
+    report("sessions", sessions);
+
     return { dir, workspace, findings, stats };
 }
 
-// ===========================================================================================
-// 5. The command
-// ===========================================================================================
+/** Optional usage accounting: a data failure never changes the workspace-validation verdict. */
+export async function workspaceUsageReport(workspaceDir, workspace, options = {}) {
+    const unmeasured = (why) => [`  note spend      unmeasured — ${why}`];
+    if (typeof workspace?.tree !== "string" || workspace.tree.trim() === "") return unmeasured("the workspace declares no tree to attribute usage to");
+    try {
+        const repo = path.resolve(workspaceDir, workspace.tree);
+        const roots = worktrees(repo);
+        if (roots === null || roots.length === 0) return unmeasured("the declared tree has no Git worktree ownership");
+        const branch = execFileSync("git", ["-C", repo, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 }).trim();
+        if (!branch || branch === "HEAD") return unmeasured("the declared tree has no current named Git branch");
+        const host = hostPaths(options.env ?? process.env, options.home);
+        if (host.why !== undefined) return unmeasured("the configured usage-record location is ambiguous");
+        const report = ledger({ ...host, roots, branch, lines: linesChanged(repo, branch), spend: readSpend(workspace.spend, "this workspace") });
+        const lines = [];
+        if (report.collected.malformed) lines.push(`  note spend      partial data — ${report.collected.malformed} malformed usage line(s) were ignored`);
+        if (report.figures.main.requests + report.figures.subagents.requests === 0 && report.local.receipts === 0) {
+            return [...lines, ...unmeasured("no host requests or local receipts on this branch are recorded here")];
+        }
+        print(report, (line) => lines.push(line));
+        return lines;
+    } catch {
+        // Parser messages can quote a private record. Never print them or a raw usage line.
+        return unmeasured("optional local usage data could not be read or parsed; no totals were reported");
+    }
+}
+
+// ---------------------------------------------------------------- the command
 
 const ICON = { fail: "FAIL ", report: "note " };
 
-/** Relative when that is shorter to read, absolute when the relative form is a ladder of `../`. */
 function display(target) {
     const rel = path.relative(process.cwd(), path.resolve(target));
     return rel === "" ? "." : rel.startsWith("..") ? path.resolve(target) : rel;
 }
 
-/** Run against one or more workspace directories. Returns the exit code; never throws. */
-/**
- * The help screen. An explicit `--help` exits **0** and prints to stdout — `./portulan.mjs` states that
- * contract ("asking for help is a request, and it succeeded") and five sibling tools already keep it;
- * this tool did not, and what a user saw instead was the no-arguments usage line on **stderr** at exit
- * 2, which is the could-not-run fallback rather than an answered question. Added at milestone 7's
- * follow-up, with `compile` and `index`, after the close pass found three nonconformers where its own
- * handoff had said two.
- *
- * `../.portulan/dod.md` condition 4 binds this text: every flag below exists in the parser above it.
- */
+/** The help screen: every flag it names must be one `run` parses. */
 function usage() {
     return [
         "portulan doctor — validate a workspace against the Workspace Definition",
         "",
-        "  portulan doctor [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]",
+        "  portulan doctor [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]",
         "",
+        "  --static      skip local usage records; validation and plugin discovery remain unchanged.",
         "  --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`",
         "  --repo-root   where the repositories this workspace's cards NAME are checked out, so their",
@@ -2701,70 +1951,20 @@ function usage() {
     ].join("\n");
 }
 
+/** Runs against each workspace directory and returns the exit code; never throws. */
 export async function run(argv, options = {}) {
     const say = options.quiet ? () => {} : (line = "") => process.stdout.write(`${line}\n`);
-    // **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.
+    // Before any other argument is judged, so help is never outranked by a complaint about the rest.
     if (argv.includes("--help") || argv.includes("-h")) {
         say(usage());
         return 0;
     }
     try {
-        // `--pack-root <dir>`, repeatable: resolution roots that REPLACE the one derived from `tree`
-        // rather than being searched ahead of it. `inspect` has read `options.packRoots` since session 0
-        // and no caller set it, so the path shaped for an adopter resolving from an installed feed had no
-        // way in from a command line. Replacement rather than precedence so that "it resolved from the
-        // feed" cannot be satisfied by a copy in the local tree at all — the three tools disagreed about
-        // this once, and `../cli/compile.mjs`'s `namedRootsOption` carries what that cost.
-        //
-        // **A PACK root IS discovered by default as of 2026-08-13, and the boundary moved rather than
-        // being dropped.** `./discover.mjs` reads the host's installed-plugin record, and this tool uses
-        // it for two things: dereferencing a POINTER's `governed_by`, and resolving pack roots (#123).
-        //
-        // This passage read *"discovered only when asked … what is deliberately not taken is a DEFAULT"*,
-        // and defended it as a boundary. Row 7's clause is that discovery makes `--pack-root` **optional
-        // where discovery finds a root**, and it was not: measured on the workspace `init` drafts by
-        // default plus one pack of the adopter's own, `doctor` exited **1** with no flag and **0** under
-        // `auto`. The maintainer ruled a behaviour change rather than a row amendment; a fresh supervisor
-        // graded that sound from `../docs/vision.md`, which defines this tool as a **per-host capability
-        // report** — answering about the host is what it is for.
-        //
-        // **The boundary it replaces, sharpened, is: a verdict about the *repository* must not depend on
-        // the machine.** Three things hold it, and none of them is the absence of a default:
-        //
-        // 1. **The pins.** Six required invocations name their root, a named root REPLACES every other
-        //    source, and `./pinned-roots.live.test.mjs` reds if one drops it or a seventh joins unpinned.
-        // 2. **The note-vs-fail keying below is on ORIGIN**, so a root nobody claimed can turn an
-        //    unresolved pack from a note into a resolution, and never into a failure.
-        // 3. **Never silently.** The `resolution root` note names the source, and each pack's line names
-        //    which root answered and whether it was discovered or derived.
-        //
-        // The row's own direction is unchanged and is what the arms above implement: **add a root where
-        // none was named; never replace one that was.**
-        //
-        // `--repo-root <dir>`, repeatable, is its sibling and is deliberately shaped the same way: the
-        // directories under which the repositories a workspace's cards NAME are checked out, so the
-        // residence ruling's third refusal has somewhere to look. Named rather than discovered for the
-        // same reason the pack roots are — a host's plugin cache holds installed plugins, and a
-        // developer's checkouts are not in it, so there is nothing there to find. The two lists are
-        // separate because they answer different questions and a single `--root` would make a packs
-        // root and a checkout root interchangeable, which they are not: one holds `category/name` pack
-        // directories, the other holds repositories.
+        let staticMode = false;
         const namedRoots = [];
         let discoverPacks = false;
         const repoRoots = [];
         const dirs = [];
-        // ONE validator for both flags, and it is one because a reviewer caught the comment claiming so
-        // while `--pack-root` still carried its own copy (Copilot, round 1 on #135). Two inputs have to
-        // fail closed here and each has a real incident behind it: a root that is **not there** is a
-        // filesystem fact rather than a pack that failed to resolve, and reporting it as the latter sends
-        // a reader to the one file that is not at fault; and existence is not enough, because
-        // `existsSync` is true for a FILE, so one was accepted and every later resolution failure was
-        // misattributed to the workspace. Three tools take `--pack-root` and only `index` had the
-        // directory check — the sibling class the 2026-07-27 ruling names, found by Copilot on #117 round
-        // 7, one round after the same defect was fixed in `index` alone. `what` keeps each flag's message
-        // specific: sharing the check must not cost the reader the sentence that says what a root is FOR.
         const directoryRoot = (flag, value, what) => {
             if (value === undefined || value.startsWith("-")) throw new DoctorError(`${flag} needs a directory${what.keyword ?? ""}`);
             let stat = null;
@@ -2780,8 +1980,6 @@ export async function run(argv, options = {}) {
             }
             return path.resolve(value);
         };
-        // `keyword` is PACK_ROOT's alone: `auto` discovers a plugin cache, and there is no such thing
-        // for a repository checkout, so offering it on `--repo-root` would advertise a refused value.
         const PACK_ROOT = {
             unresolvable: "a pack unresolvable",
             holds: "packs",
@@ -2789,37 +1987,27 @@ export async function run(argv, options = {}) {
         };
         const REPO_ROOT = { unresolvable: "a repository ungoverned", holds: "repositories" };
         for (let i = 0; i < argv.length; i += 1) {
-            if (argv[i] === "--repo-root") {
+            if (argv[i] === "--static") {
+                staticMode = true;
+            } else if (argv[i] === "--repo-root") {
                 repoRoots.push(directoryRoot("--repo-root", argv[i + 1], REPO_ROOT));
                 i += 1;
             } else if (argv[i] === "--pack-root") {
-                // The keyword, on the raw argument and before `directoryRoot` resolves anything.
                 if (argv[i + 1] === AUTO) discoverPacks = true;
                 else namedRoots.push(directoryRoot("--pack-root", argv[i + 1], PACK_ROOT));
                 i += 1;
             } else if (!argv[i].startsWith("-")) dirs.push(argv[i]);
             else {
-                // **Refused loudly, where it used to be swallowed.** This arm read `else if
-                // (!startsWith("-")) dirs.push(...)` with no `else` at all, so any `-`-prefixed
-                // argument this parser did not recognise was silently discarded. Measured on
-                // `d5a5eb7`: `doctor --repo-rot /nonexistent` dropped the misspelled flag and graded
-                // `/nonexistent` **as a workspace**, red for a reason that had nothing to do with what
-                // was asked. A typo in a flag is could-not-run, never a verdict — and #155's lesson is
-                // that the refusal names both real invocations, because a user who typed one of them
-                // cannot act on advice about the other.
                 throw new DoctorError(
                     `unknown argument \`${argv[i]}\` — run \`portulan doctor --help\` or \`node cli/doctor.mjs --help\` for the flags this tool takes`,
                 );
             }
         }
-        // Refused at PARSE time, which is where an exit 2 belongs: before a workspace is read, so the
-        // refusal cannot be mistaken for a verdict about one. `resolutionRoots` refuses the same
-        // combination for callers that never parsed anything; both ask the same exported predicate.
         const bothAsked = namedWithAuto(namedRoots, discoverPacks);
         if (bothAsked) throw new DoctorError(bothAsked);
         if (dirs.length === 0) {
             if (!options.quiet) {
-                process.stderr.write("usage: node cli/doctor.mjs [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]\n");
+                process.stderr.write("usage: node cli/doctor.mjs [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]\n");
             }
             return 2;
         }
@@ -2831,7 +2019,7 @@ export async function run(argv, options = {}) {
                 ...(discoverPacks ? { discoverPacks } : {}),
                 ...(repoRoots.length ? { repoRoots } : {}),
             };
-            const { findings, stats } = await inspect(dir, { ...options, ...roots });
+            const { findings, stats, workspace } = await inspect(dir, { ...options, ...roots });
             const bad = findings.filter((f) => f.severity === "fail");
             say(display(dir));
             for (const f of findings) say(`  ${ICON[f.severity]} ${f.check.padEnd(10)} ${f.message}`);
@@ -2840,14 +2028,15 @@ export async function run(argv, options = {}) {
                     `${findings.length - bad.length} note(s), ${stats.claims} claim(s) checked` +
                     (stats.unverifiable ? `, ${stats.unverifiable} unverifiable` : ""),
             );
+            if (!staticMode && !options.quiet && !bad.length && workspace) {
+                for (const line of await workspaceUsageReport(path.resolve(dir), workspace, options)) say(line);
+            }
             say();
             if (bad.length) failed += 1;
         }
         return failed ? 1 : 0;
     } catch (error) {
-        // Anything reaching here means doctor could not judge — including a defect in doctor
-        // itself. Exit 2. Reporting 1 would assert a verdict about the workspace that was
-        // never reached, and reporting 0 would be the fail-open this whole tool exists against.
+        // Anything reaching here could not be judged, a defect in doctor included: 2, never a verdict.
         if (!options.quiet) {
             process.stderr.write(`doctor: ${error instanceof DoctorError ? error.message : `unanticipated failure — ${error.stack ?? error}`}\n`);
         }