@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/cli/plugin-lint.mjs

@@ -3,65 +3,13 @@
 //
 //   node cli/plugin-lint.mjs [--payload] <plugin-root> [<plugin-root> ...]
 //
-// Exit 0 the packaging holds together · 1 it does not · 2 could not run. Same three codes as
-// ./doctor.mjs and for the same reason: a verdict ABOUT the tree is 1, and 2 means nothing was
-// judged at all. Borrowing 1 for the second would claim a judgement nobody reached.
-//
-// ## What this checks, and what it deliberately does not
-//
-// This validator checks **this repository's own invariants** about its packaging: that both
-// manifests parse and are objects, that the fields this repository depends on are present and
-// correctly shaped, that the two manifests agree with each other, that every path they declare
-// starts with `./`, stays inside the tree, and resolves — and that every skill and agent behind
-// those paths is a real artifact with frontmatter and a non-empty description.
-//
-// It is **not** an implementation of the Claude Code plugin contract, and must never be described
-// as one. `claude plugin validate --strict` is the authority for that contract; it is run at the
-// supervised checkpoints and before any release, and its result is recorded in the session log.
-// The split exists because CI here installs nothing by stated doctrine (.github/workflows/verify.yml),
-// so a recipe declaring the `claude` binary as a dependency would exit 2 — "could not run" — on
-// every pull request, which under this repository's own precondition rule is permanently red.
-//
-// So: the platform's contract is checked by the platform's own tool at a checkpoint, and the rail
-// that runs on every pull request checks what this repository can honestly own. The gap between
-// those two is real and is stated in ./README.md and in ../.portulan/products/portulan/affordances.md
-// rather than left for someone to discover — a mandate nothing checks is already broken
-// (../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md), and so is a claim of coverage
-// nothing measures.
-//
-// Explicitly NOT checked, each for a reason:
-//   * reserved marketplace names — the platform re-checks that list on every marketplace load and
-//     has already changed it once. A copy frozen here would drift into either a false red or a
-//     false green, and the platform enforces it where it actually matters.
-//   * field semantics beyond shape — whether a description is *good*, whether a skill is worth its
-//     tokens. That is review, and ../core/skills/README.md holds the bar.
-//   * anything needing the network. Nothing here fetches (../.portulan/verify/README.md).
-//   * **whether a declared skill becomes a capability the host registers — beyond its DEPTH.** Since
-//     2026-08-07 one half of that question is checked: a skill resolved more than HOST_SKILL_DEPTH
-//     below its declared root fails, because the host expands a declared root exactly one level and a
-//     skill deeper than that is packaged, counted and inert. That was measured in both directions on
-//     Claude Code 2.1.224 against a local marketplace built from this repository — `./packs/rituals/`
-//     registered 0 of the pack's 3, `./packs/rituals/checkpoints/skills/` registered all 3 — and it is
-//     why `N skill(s)` and the host's inventory had disagreed by three for a milestone (#134).
-//     Since 2026-08-09 a second half is checked, and it is a different question: not *can the host
-//     reach this path* but *did the workspace ask for it*. The `compose` check below pins the
-//     governing workspace's `packs` array to the `skills` paths that land inside `./packs/`, both
-//     ways, because registration is otherwise a property of plugin.json alone — measured by deleting
-//     the `packs` key outright and reinstalling, which changed the host's inventory not at all.
-//     What is still NOT checked is everything else about registration: whether the host accepts the
-//     frontmatter, whether a name collides, whether the plugin loads at all. `N skill(s)` answers *is
-//     the packaging coherent and reachable*, never *does this install work* — that stays the
-//     fresh-machine demonstration below and `claude plugin validate --strict`.
-//   * whether the plugin, once installed, behaves. That is the fresh-machine install demonstration
-//     the milestone-3 criterion asks for, and no lint can stand in for it.
+// Exit 0 the packaging holds together · 1 it does not · 2 could not run.
+// It checks this repository's own invariants; `claude plugin validate --strict` owns the plugin contract.
 
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-// The registrable set — what a composed pack's own `contributes.skills` says this manifest must
-// declare. `HOST_SKILL_DEPTH` was measured in THIS file and lives there now; see its note below for
-// why the direction is this way round rather than the other.
 import { HOST_SKILL_DEPTH, skillsSet, canonical } from "./skills-set.mjs";
 
 /** Raised when `plugin-lint` cannot run at all. Always exit 2, never 1. */
@@ -74,26 +22,11 @@ export class PluginLintError extends Error {
 
 const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
-// The private feeds this project ships, named so a public manifest cannot be sourced from one. Named
-// rather than pattern-matched on "private": visibility is a live GitHub setting no file can read, so the
-// only honest form is a list this repository maintains. `docs/plan.md`'s topology is the declaring
-// authority for what is on it, and the name is already public there — what is refused is a *pointer*,
-// not a mention. Entries are `owner/name`, not bare names: matching a name alone refused an unrelated
-// public repository that happened to share it, which is a false red in a rail, and a false red is how a
-// whole rail gets switched off. A feed added to the topology and not added here is the drift this comment
-// exists to make findable; the list is short enough to keep by hand.
+// Kept by hand with docs/plan.md's repo topology: visibility is a GitHub setting no file can read.
 const PRIVATE_FEEDS = ["sleepy-panda-srl/portulan-internal"];
-// Deliberately permissive about pre-release and build metadata, strict about the three numbers:
-// the platform compares version strings, and this repository's own convention is SemVer from
-// v0.1.0 (../docs/plan.md, Protocol → Versioning).
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const BLOCK_SCALAR = /^[|>][+-]?$/;
 
-// Manifest keys whose value may name a path. `hooks`, `mcpServers` and `lspServers` also accept an
-// inline object, so only string values are treated as paths — an object there is configuration, not
-// a claim about the tree.
-//
-// `agents` is deliberately absent: see AGENT_DIR below. Declaring it does not resolve to a component
-// the host will load, so treating it as a path claim would be validating a path nobody reads.
 const PATH_FIELDS = [
     "skills",
     "commands",
@@ -104,48 +37,18 @@ const PATH_FIELDS = [
     "lspServers",
 ];
 
-// Directories never walked when looking for skills nobody declared: `.git` and `node_modules` for
-// size, and `.claude-plugin/` because it holds manifests rather than skills. Deliberately NOT a
-// blanket dot-directory rule — a SKILL.md under any other dot-directory is walked and reported,
-// because "declared is what ships" and a skill hidden from this pass is one its author believes is
-// shipping. Reporting beats skipping here for the same reason it does everywhere else in this tree.
+// Only these: a SKILL.md under any other dot-directory is still walked and reported.
 const SKIP_DIRS = new Set([".git", "node_modules", ".claude-plugin"]);
 
-// The one location the host loads agents from, and it loads them from nowhere else. Measured
-// 2026-07-26 against Claude Code v2.1.215 with a positive control, because the failure is silent in
-// both directions:
-//
-//   files at ./agents/, no `agents` key         →  Agents (1)   loaded
-//   the same files named explicitly in `agents` →  Agents (0)   the key SUPPRESSES the scan
-//   files at ./plugin/agents/, no key           →  Agents (0)   nowhere else is scanned
-//   `agents` naming a directory, any path       →  the plugin fails to load at all
-//
-// So agents are found here by convention rather than by declaration. That is not a preference: the
-// manifest cannot express a working agent path, and `claude plugin validate --strict` accepts the
-// explicit-file form that loads nothing — this repository shipped exactly that and its personas were
-// inert on every install (../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md).
-// **Exported since milestone 7 session 7**, because `cli/doctor.mjs` now resolves a composed pack's
-// persona to the host binding that would carry it and needs this exact directory. A second spelling
-// there would be one measurement with two carriers — the class
-// ../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md names — and the one that
-// drifts is always the copy, never the file that did the measuring.
+// Claude Code 2.1.215 loads agents from ./agents/ alone, and an `agents` key in plugin.json stops even that.
 export const AGENT_DIR = "agents";
 const MAX_WALK_DEPTH = 6;
 
 // ===========================================================================================
 // Frontmatter
 // ===========================================================================================
-//
-// A deliberately small YAML reader: enough for `name` and `description`, and honest about the rest.
-// The policy is the same one ./doctor.mjs applies to a repo card — parse conservatively, because a
-// false red is what gets a whole recipe switched off — with one inversion: the ABSENCE of a
-// frontmatter block is reported, because for a skill the block is the contract, not decoration.
-
-/**
- * @returns {{fields: Record<string,string>|null, error?: string}}
- *   `fields` is null when there is no usable frontmatter; `error` says why when that is a defect
- *   rather than simply an absent block.
- */
+
+/** A flat-YAML reader: `fields` is null without a usable block, and `error` is set when that is a defect. */
 export function parseFrontmatter(text) {
     const lines = text.split(/\r?\n/);
     if (lines[0]?.trim() !== "---") return { fields: null };
@@ -158,16 +61,12 @@ export function parseFrontmatter(text) {
     const fields = {};
     const body = lines.slice(1, close);
     for (let i = 0; i < body.length; i += 1) {
-        // Only the first colon splits: `description: Use when: x` is one value, not a truncated
-        // one. Getting this wrong would silently shorten exactly the field this validator judges.
         const match = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(body[i]);
         if (!match) continue;
         const key = match[1];
         let value = match[2].trim();
 
-        // A block scalar (`|`, `>`, with any chomping indicator) is legal YAML and common in long
-        // skill descriptions. Failing one would be a false red on correct input.
-        if (/^[|>][+-]?$/.test(value)) {
+        if (BLOCK_SCALAR.test(value)) {
             const collected = [];
             while (i + 1 < body.length && (body[i + 1].trim() === "" || /^\s+/.test(body[i + 1]))) {
                 i += 1;
@@ -189,38 +88,14 @@ export function parseFrontmatter(text) {
 // Inspection
 // ===========================================================================================
 
-/** True when `target` lies outside `root`. Lexical — the caller decides what it is fed. */
+/** Lexical: a symlink inside `root` can still lead out of it. */
 function escapes(root, target) {
     const inside = path.relative(root, target);
     return inside.startsWith("..") || path.isAbsolute(inside);
 }
 
-/**
- * Lint the packaging rooted at `root`.
- *
- * @param {string} rawRoot - the plugin root, absolute or relative.
- * @param {object} [options]
- * @param {boolean} [options.payload=false] - treat this root as a **payload**: a plugin a feed
- *   publishes without being a marketplace itself. It changes exactly one thing — a
- *   `marketplace.json` that is **absent** becomes a counted `unverifiable` note instead of a
- *   `manifest` failure, and every marketplace-specific check is skipped because there is nothing to
- *   check. Everything else is unchanged, and three boundaries are deliberate: a marketplace manifest
- *   that is **present** is validated in full, an **unusable** one (a dangling symlink, an unreadable
- *   file) still fails, and the mode is never inferred from an absent file — the caller opts in. What
- *   the exemption costs is what the note says: nothing here can check that the feed's entry agrees
- *   with this manifest, so the name, version and source path it publishes under are unverified.
- * @throws {PluginLintError} when the root itself cannot be read — that is not a verdict.
- * @returns {{findings: Array<{severity: "fail"|"note", check: string, message: string}>,
- *            stats: {skills: number, agents: number, paths: number, unverifiable: number}}}
- */
+/** Throws PluginLintError only when the root is not a readable directory; `payload` excuses an absent marketplace.json. */
 export function inspect(rawRoot, { payload = false } = {}) {
-    // Absolute from here on. Two sets of paths are compared later — the skills the manifest declares
-    // and the skills found by walking the tree — and they are only comparable if both are built the
-    // same way. With a relative root (`node cli/plugin-lint.mjs .`, which is how the verify recipe
-    // calls it) the declared side resolved to absolute while the walked side stayed relative, so
-    // every shipped skill was reported as undeclared: a note that was false about every skill, which
-    // is worse than no note, because it hides the true one in noise. The suite missed it because
-    // every fixture passed an absolute temp directory. Now normalised once, at the boundary.
     let stat;
     try {
         stat = fs.statSync(path.resolve(rawRoot));
@@ -228,10 +103,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         throw new PluginLintError(`cannot read ${rawRoot} — ${error.code ?? error.message}`);
     }
     if (!stat.isDirectory()) throw new PluginLintError(`${rawRoot} is not a directory`);
-    // Canonical, not merely absolute: every containment answer below compares against this, and
-    // comparing a canonical target to a symlinked root reports an escape that is not one. Both
-    // sides must be canonicalised or neither. (On macOS this is not hypothetical — the temp
-    // directories the suite builds fixtures in live under a symlinked `/tmp`.)
+    // Canonical, since every containment check and set comparison below is between canonical paths.
     let root;
     try {
         root = fs.realpathSync(path.resolve(rawRoot));
@@ -241,32 +113,23 @@ export function inspect(rawRoot, { payload = false } = {}) {
 
     const findings = [];
     const stats = { skills: 0, agents: 0, paths: 0, unverifiable: 0 };
-    // Every agent file this pass opened, keyed by the basename the persona correspondence below looks
-    // it up by. Collected during the walk rather than re-read afterwards: the files are already open,
-    // and a second read is a second chance to disagree about what they said.
-    const bound = new Map();
-    // Whether the agents directory was actually EXAMINED, which is not the same as whether `bound` has
-    // anything in it. An empty map has two causes — nothing is bound, or nothing could be looked at —
-    // and the correspondence below may only speak on the first. Absent counts as examined: a plugin
-    // with no `agents/` has genuinely bound nothing, and that IS the finding.
+    const bindings = new Map();
+    // Absent counts as examined: a plugin with no ./agents/ has genuinely bound nothing.
     let agentsExamined = false;
     const fail = (check, message) => findings.push({ severity: "fail", check, message });
     const note = (check, message) => findings.push({ severity: "note", check, message });
 
-    /** Read a file, turning any failure into a finding rather than an exception. */
+    /** Never throws: a failed read becomes a finding and returns null. */
     const read = (file, check, label) => {
         try {
             return fs.readFileSync(file, "utf8");
         } catch (error) {
-            // doctor shipped this defect twice: an unguarded read turned a tree already judged red
-            // into "could not run", discarding every finding the run had made. A file that cannot
-            // be read IS a verdict about the tree.
             fail(check, `${label} could not be read — ${error.code ?? error.message}`);
             return null;
         }
     };
 
-    /** Parse a manifest. Returns null on any problem, having recorded it. */
+    /** Null on any problem, having recorded it as a finding. */
     const manifest = (rel) => {
         const file = path.join(root, rel);
         if (!fs.existsSync(file)) {
@@ -289,26 +152,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         return value;
     };
 
-    /**
-     * Resolve a declared path against the root, enforcing the platform's two stated rules — it
-     * must start with `./` and it must not leave the plugin root — and this repository's one:
-     * it must actually resolve.
-     *
-     * Containment is checked **twice**, and the second one is the check that means something.
-     * `path.relative` is lexical: it reads `./plugin/skills/` as inside the root whether or not
-     * `plugin/skills` is a symlink to somewhere else entirely. Since a plugin's whole contract is
-     * that its components live inside it — and since a symlink escaping the root is a shape this
-     * repository actively considered and rejected for its own packaging — the lexical answer is
-     * the one an attacker or an accident would satisfy. So the target is canonicalised and asked
-     * again. The lexical check is kept first because it is the only one that can judge a path that
-     * does not exist: `./../elsewhere/` must fail as *outside*, not as *missing*.
-     *
-     * The kind travels back with the path deliberately: it is read here, once, inside this
-     * function's guard, so no caller has a second unguarded `statSync` to throw from.
-     *
-     * @returns {{file: string, isDirectory: boolean}|null} the canonical absolute path and what it
-     *   is, or null having recorded the failure.
-     */
+    /** The canonical path and its kind, or null having recorded why. */
     const resolve = (raw, check, where) => {
         stats.paths += 1;
         if (typeof raw !== "string" || raw.trim() === "") {
@@ -324,8 +168,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
             fail(check, `${where} declares "${raw}", which resolves outside the plugin root`);
             return null;
         }
-        // `existsSync` follows symlinks, so a broken link is reported as not resolving rather than
-        // crashing the canonicalisation below.
         if (!fs.existsSync(target)) {
             fail(check, `${where} declares "${raw}", which does not resolve to anything`);
             return null;
@@ -344,14 +186,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
             );
             return null;
         }
-        // The kind is read here, once, inside the guard — rather than by the callers, which used to
-        // `statSync` the path a second time unguarded. Existence having been established two lines
-        // up makes that second call *look* safe, and it is not: the window is small (a removal
-        // between the two calls, a transient filesystem error) but what it costs is large, because
-        // a throw from there reaches the top-level catch and turns a run that had already found
-        // real failures into exit 2 — "could not run" — discarding every one of them. That is the
-        // defect this repository has now fixed four times, and the reliable cure is not another
-        // try/catch but having only one read to guard.
         let stat;
         try {
             stat = fs.statSync(real);
@@ -367,36 +201,13 @@ export function inspect(rawRoot, { payload = false } = {}) {
     // --- the two manifests --------------------------------------------------------------------
 
     const plugin = manifest(path.join(".claude-plugin", "plugin.json"));
-    // A **payload** root is a plugin a feed ships without being a marketplace itself. `packs/` is one:
-    // the private feed's `portulan-checkpoints` entry is a `git-subdir` source rooted there, so the
-    // marketplace entry describing it lives in that feed and cannot exist here. Requiring one would
-    // demand a fake marketplace beside a real payload.
-    //
-    // It is an OPT-IN and not an inference — a root that merely *lacks* a marketplace still fails, and
-    // the caller has to say which roots are payloads. Inferring it would turn a deleted
-    // `marketplace.json` into a silently narrower lint, which is the relaxation
-    // `../.portulan/gate-map.md` says to scrutinise hardest.
-    //
-    // What it costs is stated rather than hidden: **nothing here checks that the feed's entry agrees
-    // with this manifest** — the name, the version and the source path are verified in the feed's own
-    // repository or not at all. That is one unverifiable, counted as such.
-    // `lstatSync` rather than `existsSync`, and the difference is a verdict: `existsSync` FOLLOWS a
-    // symlink, so a payload root whose `marketplace.json` is a dangling link read as "none is owed" and
-    // went green, where the strict path calls the same tree a `manifest` failure. That is this file's
-    // recurring defect in its own words one screen down — *"absent and unusable are different verdicts
-    // and only one is benign"* — and it is why only ENOENT takes the payload arm. Found at the
-    // pre-commit checkpoint by planting the dangling link.
+    // lstat, not existsSync: existsSync follows links, so a dangling marketplace.json would read as absent.
     const marketPath = path.join(root, ".claude-plugin", "marketplace.json");
     let marketAbsent = false;
     let marketUnexaminable = null;
     try {
         fs.lstatSync(marketPath);
     } catch (error) {
-        // ENOENT is the only absence. Every other errno — EACCES, EIO, ELOOP — is a file that is
-        // THERE and would not answer, and falling through with `marketAbsent` false sent it to
-        // `manifest()`, whose `existsSync` cannot stat it either and reports it **missing**. That is
-        // the same conflation this block exists to prevent, one branch further out, and it reached
-        // both the payload and the strict path. Reported as itself instead. (Copilot, final round.)
         if (error.code === "ENOENT") marketAbsent = true;
         else marketUnexaminable = error.code ?? error.message;
     }
@@ -444,9 +255,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         if (!Array.isArray(market.plugins)) {
             fail("market", "marketplace.json needs a `plugins` array");
         } else if (market.plugins.length === 0) {
-            // The failure this whole file exists to stop being a warning. `claude plugin validate`
-            // reports an empty marketplace as a warning, and a warning is the severity a milestone
-            // walks past: the repository would call itself a plugin marketplace and ship nothing.
+            // Stricter than `claude plugin validate`, which only warns about an empty marketplace.
             fail("market", "marketplace.json declares no plugins — a marketplace that ships nothing");
         }
     }
@@ -468,37 +277,10 @@ export function inspect(rawRoot, { payload = false } = {}) {
             continue;
         }
         if (typeof entry.source !== "string") {
-            // **One direction only.** The private feed may point at this repository — that is the
-            // maintainer's #113 ruling, "the feed points, the public repository carries" — and this
-            // repository may never point back. A public entry sourced from the private feed is a **dead
-            // pointer for every stranger**, since the fetch 404s on a repository they cannot see, and it
-            // publishes the private feed's internal structure in a manifest anyone can read. Refused
-            // rather than noted, because the two failure modes are invisible from inside this tree: no
-            // resolution attempt here can tell a private repository from a nonexistent one.
-            //
-            // Deliberately narrow. Pointing at another PUBLIC repository is a legal shape nobody has
-            // ruled against, and it stays counted-and-reported below — widening this to every off-tree
-            // source would be this lint inventing a policy rather than enforcing one.
-            // Matched as a NAME, never as a substring. `includes` false-positives on an unrelated public
-            // repository whose name merely contains the feed's — `someone-else/portulan-internal-tools` —
-            // and a false red in a rail is how the whole rail gets switched off. Found by Copilot on #117,
-            // round 5. Split on everything that can delimit a repository or package name, so
-            // `owner/portulan-internal`, an `https://` URL and an `scp`-style `git@host:owner/name.git`
-            // all reduce to the same segment set.
             const target = [entry.source?.repo, entry.source?.url, entry.source?.package]
                 .filter((v) => typeof v === "string")
                 .join(" ");
-            // **Lowercased on both sides.** GitHub repository names are case-insensitive, so
-            // `Sleepy-Panda-Srl/Portulan-Internal` resolves to the same repository and walked straight
-            // through a case-sensitive membership test. Found by Copilot one round after the rail landed —
-            // a rail a different capitalisation gets past is not a rail, which is why this went past the
-            // review loop's two-fix-round bound rather than to triage (the precedent is #105).
-            // Matched as **owner/name**, not name alone. Matching the repo segment by itself refused
-            // `someone-else/portulan-internal` — an unrelated public repository — which contradicts this
-            // rail's own stated narrowness, and a false red is how a whole rail gets switched off. Copilot,
-            // #117 round 8. Lowercased on both sides because GitHub names are case-insensitive (round 6),
-            // and adjacent segment PAIRS are compared so `owner/name`, an https URL and an scp-style
-            // `git@host:owner/name.git` all reduce to the same set.
+            // Compared as owner/name pairs, case-insensitively, as GitHub compares repository names.
             const segments = target.toLowerCase().split(/[\s/:@]+/).map((seg) => seg.replace(/\.git$/, "")).filter(Boolean);
             const pairs = new Set(segments.slice(0, -1).map((seg, i) => `${seg}/${segments[i + 1]}`));
             if (PRIVATE_FEEDS.some((feed) => pairs.has(feed.toLowerCase()))) {
@@ -511,9 +293,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
                 );
                 continue;
             }
-            // A github / url / git-subdir / npm source is legal and points outside this tree, so
-            // nothing here can resolve it. Counted and reported, never silently skipped — the same
-            // rule doctor applies to a workspace that declares no tree.
             stats.unverifiable += 1;
             note("market", `${label} ("${name ?? "?"}") has an off-tree source — not verifiable here`);
             continue;
@@ -522,10 +301,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         const resolved = resolve(entry.source, "market", `${label} ("${name ?? "?"}") source`);
         if (!resolved) continue;
 
-        // The entry that points at the marketplace root IS this plugin, so the two manifests are
-        // describing one artifact and must not contradict each other. Drift between them is
-        // invisible at runtime — plugin.json wins — which is what makes it worth a check.
-        // Both sides are canonical by construction, so this compares like with like.
+        // This entry is this plugin; at runtime plugin.json wins, so a disagreement would go unseen.
         if (resolved.file === root && plugin) {
             if (name && typeof plugin.name === "string" && name !== plugin.name) {
                 fail(
@@ -560,10 +336,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
     }
 
-    // An `agents` key is refused whatever it names — see AGENT_DIR. A path that resolves is exactly
-    // as dead as one that does not, so this fails on the key's presence rather than on its value,
-    // and it fails rather than notes: a note is read past, and re-adding the key silently unloads
-    // every persona the plugin ships.
     if (plugin !== null && typeof plugin === "object" && plugin.agents !== undefined) {
         fail(
             "agents",
@@ -581,8 +353,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
             fail("skills", `plugin.json skills path ${path.relative(root, skillRoot)} is not a directory`);
             continue;
         }
-        // A skills path may point straight at one skill (the `"./"` form), at a directory of them, or
-        // at a pack-shaped tree with them nested deeper — see expandDeclaredSkillRoot below.
         const expanded = expandDeclaredSkillRoot(skillRoot);
         if (expanded.unreadable !== undefined) {
             fail("skills", `${path.relative(root, skillRoot)} could not be read — ${expanded.unreadable}`);
@@ -610,9 +380,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
                     `find nothing`,
             );
         }
-        // Its own heading, and its own sentence. Sharing `truncated`'s would have named the depth
-        // bound as the cause of a permission error — a confident wrong reason, which is worse than
-        // no reason, and the class this whole batch is about. (#108)
         for (const { dir, why } of expanded.unreadableBranches ?? []) {
             fail(
                 "skills",
@@ -621,11 +388,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
                     `branch empty: could-not-look is not nothing-there`,
             );
         }
-        // The host expands a declared root ONE level. A skill this validator resolves deeper than that
-        // is packaged, counted, and inert on every install — which is a green over a skill nobody can
-        // invoke, the failure ../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md
-        // records against the sibling `agents` key. The repair is in the message because it is one
-        // edit: name the directory that actually holds the skills.
         for (const dir of expanded.beyondHostReach ?? []) {
             fail(
                 "skills",
@@ -647,68 +409,12 @@ export function inspect(rawRoot, { payload = false } = {}) {
         stats.skills += 1;
         const text = read(file, "skills", `${rel}/SKILL.md`);
         if (text === null) continue;
-        // `name` is required here although the platform makes it optional, and the stricter rule is
-        // this repository's own invariant rather than a claim about the contract. Without it the
-        // invocation name is inherited from the layout, and the fallback differs by layout: a skill
-        // in a `skills/<dir>/` subdirectory takes the directory name, which is stable, while a skill
-        // reached by a path pointing straight at it — the `"./"` form, which packs will use — takes
-        // the *install* directory name, which for a marketplace install is a version string that
-        // changes on every update. Requiring `name` makes the invocation name a property of the
-        // skill rather than of where it happens to sit, and every skill this repository ships has
-        // one already, so the rule costs nothing and closes the case before packs arrive.
+        // The host would name a `"./"`-form skill without `name` after its install directory, a version string.
         checkFrontmatter(text, `${rel}/SKILL.md`, "skills", { requireName: true });
     }
 
     // --- composition drives registration -------------------------------------------------------
-    //
-    // Two manifests carry one fact and nothing pinned them together. A workspace's `packs` array
-    // says which packs this repository **composes**; `plugin.json`'s `skills` says which directories
-    // the **host registers**. Registration is a property of `plugin.json` and of nothing else —
-    // measured 2026-08-09 on Claude Code 2.1.226 by deleting the `packs` key from
-    // `.portulan/workspace.json` outright and reinstalling, which changed the host's inventory not at
-    // all: the same `Skills (7)`, the checkpoints pack's three among them. So a composed pack's skill
-    // is invocable here by coincidence of a hand-written path, which is exactly what row 7 clause (b)
-    // refuses ([#184](https://github.com/sleepy-panda-srl/portulan/issues/184)): the demonstration
-    // it asks for is **parity** — invoked because the workspace composed it — not files present at a
-    // path a human knows.
-    //
-    // The correspondence runs both ways, and each direction is a defect that is silent today:
-    //
-    //   composed, undeclared  →  packaged, counted by this validator, inert on every install. The
-    //                            failure ../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md
-    //                            records against the sibling `agents` key, arriving through the other
-    //                            manifest.
-    //   declared, uncomposed  →  a capability the host registers that no workspace asked for. The
-    //                            cascade is core < pack < workspace, and a pack reaching the host
-    //                            without the workspace naming it has skipped the layer that owns the
-    //                            decision.
-    //
-    // **Scoped to the workspace that GOVERNS this bundle, never to every manifest it ships.** The demo
-    // under `examples/` composes packs of its own and the fixture under `cli/fixtures/` exists to be
-    // invalid; neither governs this bundle, and that is the durable reason — it is the whole reason
-    // this reads one named path rather than discovering manifests.
-    //
-    // _This paragraph justified the scoping by saying the demo's packs "deliberately do not exist",
-    // which was half-false from milestone 7 session 5 (`tools/github` landed) and wholly false from
-    // 2026-08-13 (`stacks/python`, which never existed, was swapped for `rituals/checkpoints`). It
-    // also said holding the demo to this rule would be "a red by construction" — and after that swap
-    // the demo composes what the governing workspace composes, so it would now coincidentally PASS.
-    // A justification that has become an accident is worse than none, which is why the scoping now
-    // rests on governance alone. Found by the pre-commit checkpoint on the change that falsified it._
-    //
-    // What this does NOT establish, each found by the pre-commit checkpoint on #195 rather than
-    // assumed:
-    //   * **that the host then INVOKES the skill.** This establishes that the path the host registers
-    //     from is the one composition asked for. `claude plugin details` counts registration and is
-    //     run at the checkpoints; nobody has yet shown a composed pack's skill *invoked* through
-    //     composition, which is the parity row 7 clause (b) ultimately asks for.
-    //   * **that a `packs` entry names a pack at all.** `"."` or a family name like `"rituals"`
-    //     satisfies the correspondence without pointing at anything carrying a `pack.json`. Requiring
-    //     one here would put a second answer to *what is a pack* beside `doctor`'s, so the gap is
-    //     named instead of closed.
-    //   * **that the host resolves symlinks the way either walk does.** The walks are aligned with
-    //     each other and with `doctor`; what the host does with a symlinked `SKILL.md` at install is
-    //     unmeasured, and nothing here claims it.
+    // Claude Code 2.1.226 registers skills from plugin.json alone, whatever the workspace composes.
 
     const GOVERNING = path.join(".portulan", "workspace.json");
     let composition;
@@ -716,10 +422,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
     try {
         composition = JSON.parse(fs.readFileSync(path.join(root, GOVERNING), "utf8"));
     } catch (error) {
-        // A bundle shipping no governing workspace composes nothing, which is coherent rather than a
-        // fault. *Could not read* is a different answer and is never *not there*
-        // (../.portulan/memory/verify-preconditions-fail-closed.md), so the two are reported apart and
-        // only the second is a finding.
         if (error.code === "ENOENT") composable = false;
         else {
             fail(
@@ -731,17 +433,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
     }
 
-    // A manifest that PARSES but is not a plain object — an array, a string, a number, **or the JSON
-    // literal `null`** — silently skipped this whole check in the first cut, which is a green over
-    // something nobody evaluated: the exact shape the `could not read` branch above exists to refuse,
-    // one type away.
-    //
-    // `null` is the one that hid, and it hid because it was doing two jobs. The first cut used `null`
-    // as the *sentinel* for "there is no governing workspace here", and `null` is also what
-    // `JSON.parse("null")` returns — so a present, invalid manifest was indistinguishable from an
-    // absent one and skipped the check without a word. A sentinel that collides with a legal value of
-    // the thing it describes cannot report on that thing; the state is a separate boolean now, and
-    // absence is the only thing that reads as absence. Raised by Copilot on #195, both halves.
     if (composable && (composition === null || typeof composition !== "object" || Array.isArray(composition))) {
         fail(
             "compose",
@@ -751,15 +442,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
         composable = false;
     }
 
-    // `packs` PRESENT but not an array is the check's core invariant going quiet: a manifest saying
-    // `"packs": "rituals/checkpoints"` iterates zero times and the run then reports nothing at all
-    // about parity. Absent is a real state — a workspace may compose nothing — and *the wrong type* is
-    // not that state. It joins the unreadable-manifest case above rather than being caught inside the
-    // block: the first cut failed here and then RAN ON with an empty composition, so the converse
-    // direction reported every declared pack skill as belonging to no composed pack — an unreadable
-    // composition read as *composes nothing*, the same fail-open pointing the other way, contradicting
-    // the sentence it had just emitted. Both halves raised by Copilot on #195, one round apart: the
-    // guard was right and its control flow was not.
     if (composable && composition.packs !== undefined && !Array.isArray(composition.packs)) {
         fail(
             "compose",
@@ -773,9 +455,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
         const packsRoot = path.join(root, "packs");
         const composed = [];
         for (const entry of Array.isArray(composition.packs) ? composition.packs : []) {
-            // A `packs` entry that is not a usable name is `doctor`'s verdict on the workspace, but
-            // going quiet about it here would be this check reporting on a composition it did not
-            // read in full. Named, then passed on.
             if (typeof entry !== "string" || entry === "") {
                 fail(
                     "compose",
@@ -786,31 +465,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
             }
             const name = entry;
             const dir = path.join(packsRoot, name);
-            // A `packs` entry escaping the tree is the workspace validator's verdict, not this one's —
-            // but *skipping* it is not this one's either. It is named as unchecked below rather than
-            // `continue`d in silence, because a check that goes quiet on what it could not evaluate is
-            // the fail-open this file refuses everywhere else.
-            //
-            // `escapes` is LEXICAL, and lexical containment is not containment: `packs/` or a composed
-            // pack directory can be a symlink whose target is anywhere, and `statSync`/`readdirSync`
-            // follow it. So the path is canonicalised and re-checked before anything is walked.
-            //
-            // **What that buys, stated as narrowly as it is true: a link whose target ESCAPES
-            // `./packs/` is refused.** A symlink resolving to somewhere still inside `./packs/` passes,
-            // and is meant to — it reaches nothing the walk could not reach by its own path, so
-            // refusing it would be policy about tree layout rather than containment. This is
-            // deliberately weaker than `../cli/vendor.mjs`'s rule 2, which refuses a symlink at or
-            // below the named destination outright: that tool WRITES into somebody's tree, where a
-            // link is a way to make it write outside; this one only reads, and the harm is reading
-            // outside. The two are different rules for different verbs, and the earlier draft of this
-            // comment claimed vendor's. Both halves raised by Copilot on #195 — the lexical hole
-            // first, then the comment that overclaimed the fix.
-            // Both containment checks are against `packsRoot`, not `root`. The first cut compared
-            // against the plugin root while the message and the rule said `./packs/`, so an entry like
-            // `../plugin` stayed inside the bundle, passed, and was WALKED — its skills then measured
-            // against the declared roots as though it were a composed pack. A guard whose test is wider
-            // than the sentence beside it is the two-carriers defect in one statement. Raised by Copilot
-            // on #195, in the round after the one that closed the lexical hole.
             if (escapes(packsRoot, dir)) {
                 fail(
                     "compose",
@@ -833,20 +487,11 @@ export function inspect(rawRoot, { payload = false } = {}) {
                 );
                 continue;
             }
-            // Everything past this point uses `real`, the CANONICALISED path, and that is not tidiness.
-            // `skillDirs` is built from declared roots that `resolve()` already canonicalised, so a
-            // composed pack directory that is itself a symlink to somewhere else inside `./packs/`
-            // would make the two sides describe one directory by two path forms — and the set
-            // comparison below is by string. The result is a FALSE "composed but undeclared" failure
-            // on a bundle that is correct. Raised by Copilot on #195, twice in one round, which is what
-            // a defect with two symptoms looks like.
+            // Only `real` from here: the set comparisons below are by string, against canonical paths.
             let stat;
             try {
                 stat = fs.statSync(real);
             } catch (error) {
-                // A composed pack absent from the bundle cannot be registered from it, but *why* it is
-                // absent is `doctor`'s verdict on the workspace and would be a second carrier here.
-                // Noted so the reader knows this check saw it and passed it on.
                 note(
                     "compose",
                     `${GOVERNING} composes \`${name}\`, which does not resolve under ./packs/ — ` +
@@ -855,13 +500,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
                 );
                 continue;
             }
-            // A path that exists and is NOT a directory was dropped from evaluation silently in the
-            // first cut — composition claimed and never checked. It is a NOTE rather than a failure,
-            // and the distinction was earned rather than chosen: the pre-commit checkpoint on #195
-            // tried to construct a false green through a regular file and could not, because a file
-            // holds no `SKILL.md` for either walk to disagree about. So this matches the ENOENT branch
-            // above — `doctor` owns the verdict on a malformed `packs` entry, and what this check owes
-            // is to say it saw it. A failure here would claim a hazard nobody could demonstrate.
             if (!stat.isDirectory()) {
                 note(
                     "compose",
@@ -874,9 +512,6 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
 
         for (const { name, dir } of composed) {
-            // `problems` is what makes the walk's silences visible to a consumer whose output is a
-            // failure. Each one is a place this check could not look, and *could not look* reported as
-            // *nothing wrong* is the whole defect class the `compose` check was written inside.
             const problems = [];
             for (const skillDir of walkForSkills(root, dir, 0, [], problems)) {
                 if (skillDirs.has(skillDir)) continue;
@@ -908,48 +543,11 @@ export function inspect(rawRoot, { payload = false } = {}) {
             );
         }
 
-        // --- the DECLARATION side, through the one carrier -------------------------------------
-        //
-        // Everything above asks about the TREE: is every skill actually sitting in a composed pack
-        // reachable from a declared path? This asks a different question from different evidence —
-        // does this manifest declare the root each composed pack's own `contributes.skills` NOMINATES?
-        //
-        // **These are not two implementations of one rule**, and collapsing them would delete a check.
-        // A pack whose declaration and tree disagree is a finding, and only asking both finds it. The
-        // distinctive case this half catches, which the walk cannot: a pack nominates a skills root
-        // that **is not there, or cannot be examined**, while the manifest declares nothing — the walk
-        // finds no skill, has nothing to compare, and goes green over a pack that registers nothing.
-        // That is *nothing looked* reported as *nothing wrong*, arriving through the composition path.
-        //
-        // A nominated root that exists and is genuinely EMPTY is a different answer and gets a note:
-        // there is nothing to register, so there is no hazard to report — an empty set is two
-        // questions, and this one has been examined.
-        //
-        // The policy — what a manifest must declare — lives once, in ./skills-set.mjs. This calls it.
-        //
-        // **Resolved against `./packs/`, never against the workspace's `tree`.** The carrier's own
-        // resolver derives roots from `tree`, which is right for a workspace on disk and wrong here: a
-        // bundle's packs sit where the PLUGIN layout puts them, and this check has already walked and
-        // contained exactly those directories. Resolving any other way would answer about a different
-        // set of directories than the ones above were graded on. Found by running the suite: every
-        // fixture bundle composes packs with no `tree` at all.
-        //
-        // **A composed entry with no `pack.json` is skipped, deliberately.** This file already refuses
-        // to require one — *"Requiring one here would put a second answer to what is a pack beside
-        // `doctor`'s"* — and a declaration check that failed on its absence would be that second
-        // answer arriving through the back door. No `pack.json` means no declaration to check, which
-        // is not the same as a declaration that could not be read: that one fails, below.
+        // --- the declaration side: what each composed pack's pack.json nominates ---------------
+        // The walk above goes green over a nominated root that is missing or unreadable; this half does not.
         const declaring = [];
         const resolved = new Map();
         for (const { name, dir } of composed) {
-            // Read and parse are two failures with two repairs. This said "could not be read" for
-            // both, so a malformed `pack.json` sent a reader to look at permissions and paths — the
-            // same defect `cli/skills-set.mjs`'s workspace-manifest arm carried, fixed there one round
-            // earlier and left standing HERE. That is
-            // `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` in one
-            // sentence, and it was a suppressed low-confidence note that caught it rather than the
-            // session that wrote the sibling fix. Absent stays a `continue`: a composed entry with no
-            // `pack.json` is deliberately not this check's verdict.
             let text;
             try {
                 text = fs.readFileSync(path.join(dir, "pack.json"), "utf8");
@@ -991,10 +589,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
             const declaredRoots = new Set(declaredSkillRoots.map(({ file }) => canonical(path.relative(root, file))));
             for (const { path: want, pack: packName } of derived.paths) {
                 if (declaredRoots.has(want)) continue;
-                // A manifest may name each skill individually — the `"./"` form — instead of the root.
-                // That registers them just as well, so it is not a failure, and the walk above has
-                // already held those to the tree. Checked rather than assumed, because failing it would
-                // be a false red on a bundle that is correct.
+                // Declaring each skill by its own path registers them as well as declaring the root.
                 const problems = [];
                 const beneath = walkForSkills(root, path.join(root, want), 0, [], problems);
                 if (problems.length === 0 && beneath.length > 0 && beneath.every((d) => skillDirs.has(d))) continue;
@@ -1017,15 +612,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
     }
 
-    // A skill authored and never declared is a skill nobody ships, and its author will believe
-    // otherwise. Reported rather than failed: an undeclared SKILL.md may legitimately be an example
-    // or a fixture, and this validator has no way to tell which.
-    // The same report, for the side of the asymmetry that has already bitten: a skill under a
-    // declared custom path loads, and an agent under any custom path does not. So an agent file
-    // anywhere but `./agents/` is one its author believes is loading, and nothing else in this
-    // validator would ever mention it. Reported rather than failed for the reason below — a `.md`
-    // under some other `agents/` may be a fixture, an example, or another host's binding, and this
-    // validator cannot tell which.
+    // Notes, not failures: an undeclared SKILL.md or a stray agent file may be an example or a fixture.
     for (const stranded of walkForStrandedAgents(root)) {
         note(
             "agents",
@@ -1044,24 +631,8 @@ export function inspect(rawRoot, { payload = false } = {}) {
     }
 
     // --- the agents at the convention location --------------------------------------------------
-    //
-    // Nothing declares these, so nothing but this pass covers them. The milestone-3 criterion asks
-    // that CI check "every declared skill and agent"; for agents the manifest cannot carry the
-    // claim, and the coverage has to come from the convention instead. The moment the `agents` key
-    // came out of this repository's manifest, the recipe printed `0 agent(s)` and GREEN.
-
-    // `lstat`, not `exists`: the question here is whether the tree *has* an `agents` entry, and
-    // `existsSync` answers a different one because it follows the link — so a broken `agents`
-    // symlink reported "absent", took the note branch, and went GREEN with `0 agent(s)` over a tree
-    // that plainly has an `agents` entry and cannot use it. Absent and unusable are different
-    // verdicts and only one is benign. Deciding it non-dereferencingly leaves every other case to
-    // `resolve()` below, which already knows how to fail a link that does not resolve. Found by
-    // review, and it is the short-input-set defect this pass was written to close, in the pass.
-    // Three states, not two, because "I could not tell" is a real answer and collapsing it into
-    // either of the others is a lie. Only ENOENT means absent; EACCES, EIO or anything else means
-    // the question was not answered, and answering an unanswerable question with the reassuring
-    // option is this file's recurring defect — caught here in review, one round after the same
-    // shape was caught in the line above.
+
+    // lstat, not existsSync: a broken ./agents/ link is unusable, not absent.
     let state;
     try {
         fs.lstatSync(path.join(root, AGENT_DIR));
@@ -1075,20 +646,11 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
     }
     if (state === "unknown") {
-        // Already failed; there is nothing further to say about a directory nobody could look at.
+        // Already failed above.
     } else if (state === "absent") {
-        // A plugin that ships no agents is legitimate, so this is a note. The residual hole this note
-        // named — deleting `agents/` outright degrades the whole check class to a note and exit 0 — is
-        // **closed since milestone 7 session 7 for a plugin that ships personas**: the correspondence
-        // below fails every unbound persona, so deleting the directory in THIS repository is now a red
-        // rather than a shrug. It stays a note for a plugin with no `core/personas/`, which is the
-        // legitimate shape and the reason this cannot simply become a failure.
         note("agents", `no ./${AGENT_DIR}/ directory — this plugin ships no agents`);
         agentsExamined = true;
     } else {
-        // Routed through the same resolver as every declared path, so an `agents/` that is a symlink
-        // out of the tree is an escape here too — undeclared does not mean unchecked, and this is the
-        // one component directory nothing declares.
         const dir = resolve(`./${AGENT_DIR}/`, "agents", "the plugin's agents directory");
         if (dir) {
             if (!dir.isDirectory) {
@@ -1103,12 +665,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
                 }
                 if (entries) {
                     agentsExamined = true;
-                    // `isFile()` is false for a symlink, so the obvious filter *drops* a symlinked
-                    // agent — present in the tree, absent from the count, nothing saying so, which
-                    // is the exact failure this pass exists to prevent. Symlinks are taken in and
-                    // judged instead: a broken one fails through `read` below, and one resolving
-                    // out of the plugin root fails here, the same answer `resolve` gives a declared
-                    // path. Reporting beats skipping, as everywhere else in this file.
+                    // `isFile()` is false for a symlink: links are judged here, not dropped unseen.
                     const files = entries
                         .filter((e) => e.name.endsWith(".md") && (e.isFile() || e.isSymbolicLink()))
                         .map((e) => ({ file: path.join(dir.file, e.name), link: e.isSymbolicLink() }))
@@ -1134,12 +691,8 @@ export function inspect(rawRoot, { payload = false } = {}) {
                         }
                         const text = read(file, "agents", rel);
                         if (text === null) continue;
-                        // The name comes back from the check that already parsed this block, rather
-                        // than from a second parse of the same text. They could not disagree — one
-                        // function, one string — but the doctor side returns it for exactly this
-                        // reason and a reader meeting two parses has to work out that they cannot.
                         const fields = checkFrontmatter(text, rel, "agents", { requireName: true });
-                        bound.set(path.basename(file, ".md"), { rel, name: fields?.name });
+                        bindings.set(path.basename(file, ".md"), { rel, name: fields?.name });
                     }
                 }
             }
@@ -1147,28 +700,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
     }
 
     // ---- the persona ↔ binding correspondence
-    //
-    // `../.portulan/tasks/0005-lint-the-persona-agent-binding.md`, opened 2026-07-26 on the maintainer's
-    // ruling that settled the separation, and unbuilt until milestone 7 session 7. A persona in
-    // `core/personas/` is doctrine; a file in `agents/` is that persona registered on one host. The
-    // relationship is source → binding, the same shape as gate map → compiled hooks, and the only thing
-    // keeping the binding from drifting was whoever last edited it.
-    //
-    // **Both directions FAIL here, and the same absence is only a REPORT in `cli/doctor.mjs`.** That is
-    // not drift between two checkers, and it is worth saying which is which. This tool grades **this
-    // bundle's packaging**, where a shipped persona nothing binds is inert on the host the bundle
-    // targets — the class `../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md`
-    // records, and the residual hole the note above names. `doctor` grades **anybody's workspace**,
-    // where a composed pack's persona may legitimately have no binding: the adopter may not be on this
-    // host at all, and this repository's own `checkpoints` supervisor is deliberately unbound because
-    // its ritual's mechanism is a fresh context rather than a subagent.
-    //
-    // **Task 0005's third criterion is deliberately NOT built** — that a binding restating its persona's
-    // charter should be reported. Its own text says the measurable form of *thin* is an open question
-    // and that "a check that cannot state what it measures should not ship". Nothing has settled it, so
-    // shipping a line count or a similarity threshold here would be exactly the magic number that task
-    // refused to accept at review. The two mechanical halves are what this closes; the judgement half is
-    // still open and still that task's.
+    // Fails where doctor only reports: this bundle targets one host, and an unbound persona is inert there.
     const personaDir = path.join(root, "core", "personas");
     let personaFiles = null;
     try {
@@ -1178,21 +710,9 @@ export function inspect(rawRoot, { payload = false } = {}) {
             .map((entry) => path.basename(entry, ".md"))
             .sort();
     } catch (error) {
-        // ENOENT is a plugin that ships no core personas, which is a legitimate shape and not this
-        // check's business. Anything else is a question that could not be answered, and saying nothing
-        // would report an absence nobody established.
         if (error.code !== "ENOENT") fail("agents", `core/personas/ could not be read — ${error.code ?? error.message}, so the binding correspondence went unchecked`);
     }
     if (personaFiles && !agentsExamined) {
-        // **An empty `bound` is not evidence of an unbound persona when nothing could be listed.**
-        // Where `./agents/` could not be stat'd, resolved, or read, every persona would be failed for
-        // "no binding" — a red naming the wrong defect, blaming an author for a permission the pass
-        // could not exercise. The cause is already a failure of its own above, so this is a note: the
-        // run is red either way, and what this adds is which question went unanswered.
-        //
-        // Raised by Copilot as a suppressed note on round 3 of #227, promoted to a thread by the
-        // channel `0021` built. It is this file's own recurring defect read backwards — "nothing
-        // looked" recorded as "definitely missing" rather than as "nothing wrong".
         note(
             "agents",
             `the persona↔binding correspondence went unchecked — ./${AGENT_DIR}/ could not be examined, so an empty binding set is a ` +
@@ -1200,7 +720,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         );
     } else if (personaFiles) {
         for (const persona of personaFiles) {
-            const binding = bound.get(persona);
+            const binding = bindings.get(persona);
             if (!binding) {
                 fail(
                     "agents",
@@ -1217,13 +737,8 @@ export function inspect(rawRoot, { payload = false } = {}) {
                 );
             }
         }
-        // A Set rather than `personaFiles.includes(name)` inside the loop, which re-scanned the persona
-        // list once per bound agent — O(P·B). This bundle ships three of each, so the cost today is
-        // nothing and the SHAPE is an adopter's larger bundle: triaged out of #227 as
-        // [#228](https://github.com/sleepy-panda-srl/portulan/issues/228) and taken here because this
-        // session already had the file open. Behaviour-preserving, and the suite is what says so.
         const personaNames = new Set(personaFiles);
-        for (const [name, binding] of bound) {
+        for (const [name, binding] of bindings) {
             if (!personaNames.has(name)) {
                 fail(
                     "agents",
@@ -1234,7 +749,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         }
     }
 
-    /** Validates a component's frontmatter and RETURNS the parsed fields, or `null` if there were none. */
+    /** The parsed fields, or null when there were none. */
     function checkFrontmatter(text, label, check, { requireName }) {
         const { fields, error } = parseFrontmatter(text);
         if (!fields) {
@@ -1255,33 +770,14 @@ export function inspect(rawRoot, { payload = false } = {}) {
     return { findings, stats };
 }
 
-/** Every directory beneath `root` that holds a SKILL.md. Bounded, and skips the obvious noise. */
-/**
- * Every directory named `agents` in the tree apart from the loadable one at the plugin root.
- *
- * The mistake this catches is not exotic — it is the one this repository made and shipped: agent
- * files under `plugin/agents/`, where the host will never look. It is the natural place to put them,
- * because **skills** do load from custom declared paths and agents do not, and nothing about the
- * asymmetry announces itself. See ../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md
- * for the measurement.
- *
- * **This rule and that memory entry retire together.** Both exist only because the platform loads
- * agents from one fixed location; if a release makes the `agents` key register the files it names,
- * the stranding stops being a defect, this walk becomes a source of false notes, and both go.
- */
 function walkForStrandedAgents(root, dir = root, depth = 0, found = []) {
     if (depth > MAX_WALK_DEPTH) return found;
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
     } catch {
-        // Same reasoning as the skills walk: an unreadable subtree is not a verdict about packaging.
         return found;
     }
-    // Every `agents/` **except the loadable one**, compared by path rather than by depth: the first
-    // version of this used `depth > 0`, which excludes the plugin root itself and not the `agents/`
-    // directly under it — so it reported the three files sitting exactly where it exists to tell
-    // people to put them. Caught by strengthening the test to assert what must *not* be named.
     if (dir !== path.join(root, AGENT_DIR) && path.basename(dir) === AGENT_DIR) {
         for (const entry of entries) {
             if (entry.isFile() && entry.name.endsWith(".md")) found.push(path.join(dir, entry.name));
@@ -1295,27 +791,6 @@ function walkForStrandedAgents(root, dir = root, depth = 0, found = []) {
     return found;
 }
 
-// `problems` is opt-in and changes nothing for the caller that does not pass it. It exists because
-// this walk acquired a SECOND consumer — the `compose` check — whose output is a **failure** rather
-// than a note, and the silences below were sized for the first consumer only. A sweep that misses an
-// undeclared skill under-reports a note; the same miss under `compose` is a **silent green over a
-// composed pack whose skills nothing registers**, which is the thing that check exists to refuse.
-// Raised by the pre-commit checkpoint on #195, which built both cases.
-//
-// Two silences, and both are the fail-open this repository keeps naming:
-//
-//   an unreadable subtree      `readdirSync` throws and the walk returns what it has. *Could not
-//                              look* becoming *nothing there* — `../cli/vendor.mjs` rule 3.
-//   a SYMLINKED SKILL.md       `Dirent.isFile()` is FALSE for a symlink, so the walk cannot see it,
-//                              while the DECLARED-side walk reaches the same file through
-//                              `existsSync`, which follows links. `../cli/doctor.mjs`'s `walkSkills`
-//                              already refuses this shape by `lstat` and says why. One shape, three
-//                              behaviours in one repository; this closes the third.
-/**
- * What a JSON value IS, for a diagnostic — `typeof null` is `"object"`, which turned a message about a
- * null `packs` into one about an object and sent a reader looking for a key that was not there.
- * Raised by Copilot on #195.
- */
 function jsonKind(value) {
     if (value === null) return "null";
     if (Array.isArray(value)) return "an array";
@@ -1331,8 +806,6 @@ function walkForSkills(root, dir = root, depth = 0, found = [], problems = null)
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
     } catch (error) {
-        // For the note-only consumer this stays a silence, deliberately: the declared paths are what
-        // that consumer judges, and a failure to read one of those is already reported there.
         if (problems) problems.push({ dir, why: `could not be read — ${error.code ?? error.message}` });
         return found;
     }
@@ -1356,93 +829,19 @@ function walkForSkills(root, dir = root, depth = 0, found = [], problems = null)
     return found;
 }
 
-// The depth a DECLARED skills root is searched to, counted from the root itself. Three is what the
-// pack shape needs — `<pack>/skills/<skill>/SKILL.md` — and it is deliberately its own bound rather
-// than MAX_WALK_DEPTH, which governs the undeclared-skill sweep over a whole tree. One is a search of
-// something the manifest pointed at; the other is a sweep of everything it did not.
+// Three reaches `<pack>/skills/<skill>/SKILL.md` from a declared root.
 const MAX_DECLARED_SKILL_DEPTH = 3;
 
-// How far below a DECLARED skills root the host itself looks — measured here, and since milestone 7
-// session 8 it LIVES in ./skills-set.mjs and is imported at the top of this file.
-//
-// It moved because the `compose` check below now asks that carrier what a manifest must declare, so
-// this file imports it; exporting the constant back the other way would have made an import cycle.
-// The direction matches `AGENT_DIR`, which flows plugin-lint → doctor: the carrier of a derived set
-// carries the platform constant its derivation depends on. The measurement and its re-measure mandate
-// travel with it rather than being restated here, because a constant with two homes is the two-carrier
-// defect this repository keeps paying for.
-
-/**
- * Expand one DECLARED skills root into the skill directories beneath it.
- *
- * For one milestone this resolved a declared root exactly two ways — the root IS one skill (it holds
- * `SKILL.md`), or its IMMEDIATE children are — and nothing deeper. A pack shipping
- * `<root>/<pack>/skills/<skill>/SKILL.md` therefore resolved `<root>/<pack>` as a skill directory and
- * failed it with `has no SKILL.md`, which blocked packs from carrying skills — most of what a pack is
- * for (../.portulan/tasks/0008-a-declared-skills-path-sees-one-level-down.md).
- *
- * Four results, because the fix must not buy depth with silence — and because for one milestone three
- * of these were reported as one, which is #108:
- *   `found`     — directories holding a SKILL.md, at any depth within the bound.
- *   `barren`    — a directory under the root that is not a skill and holds none beneath it. This is
- *                 the real failure the one-level version already caught, kept with its own wording.
- *                 **It means SEARCHED, and found nothing** — never *the search stopped here*.
- *   `truncated` — where the bound stopped the search with subdirectories still unlooked-at. Reported
- *                 rather than passed over: a check that goes green on what it could not reach is the
- *                 `docs.sh` `map` hole and the `git ls-files` precondition, a third time.
- *   `unreadableBranches` — a subtree below the root that could not be read at all. Kept apart from
- *                 `truncated` because they are different facts with different repairs: one is this
- *                 validator's own bound, which the packager fixes by declaring a deeper path, and the
- *                 other is a permission on their disk. Reporting them through one sentence made that
- *                 sentence wrong about whichever case it was not written for.
- *
- * **Until #108 the last three were one.** `walk()` returned `false` for all of them and the caller
- * turned any `false` into `barren`, so `skills/a/` was reported as holding no SKILL.md when the truth
- * was that the walk had stopped looking — a false classification riding alongside the true one, which
- * is the shape this repository keeps naming: a verdict about something never examined.
- *
- * A skill directory is a leaf — skills do not nest inside skills — so the walk stops descending the
- * moment it finds one. Symlinked directories are not descended, which is `Dirent.isDirectory()`'s
- * own behaviour rather than a new rule here; the escape refusal on the declared path itself is
- * `escapes()` and does not loosen.
- */
+/** `{ unreadable }` alone when the root cannot be read; otherwise each outcome in its own list. */
 function expandDeclaredSkillRoot(skillRoot) {
     const found = [];
     const truncated = [];
     const barren = [];
-    // **`unreadableBranches`, and the clumsy name is load-bearing.** This function returns a UNION the
-    // caller discriminates with `expanded.unreadable !== undefined` — the arm for a declared root that
-    // could not be read at all. Naming this list `unreadable` would make that test true on every
-    // ordinary return, since `[] !== undefined`, and every successful expansion would be reported as an
-    // unreadable root. A silent catastrophe reachable by picking the obvious word, so the word is not
-    // picked. _(The two facts are genuinely different: one is the declared path itself, which is the
-    // manifest's claim; these are subtrees below it.)_
+    // Not `unreadable`: the caller reads that key's presence as the whole root being unreadable.
     const unreadableBranches = [];
-    // Skills this validator resolves and the HOST will never see. Measured 2026-08-07 on Claude Code
-    // 2.1.224 by installing this repository as a local marketplace and reading the inventory back: the
-    // host expands a declared skills root exactly one level — `<root>/<skill>/SKILL.md` — and descends
-    // no further. `./core/skills/` gave 3, `./plugin/skills/` gave 1, `./packs/rituals/` gave **0**
-    // because the pack's skills sit at `<root>/checkpoints/skills/<skill>/`, and the inventory read
-    // `Skills (4)` while this tool counted 7. Declaring `./packs/rituals/checkpoints/skills/` instead
-    // read `Skills (7)`, naming `pre-commit`, `session-open` and `milestone-close`.
-    //
-    // So the depth bound above buys a resolution the platform does not honour, and a count that is
-    // higher than the host's is the exact shape of a false green: the packaging looks coherent and
-    // three skills are inert on every install. That is
-    // ../.portulan/memory/a-manifest-field-can-validate-and-load-nothing.md a second time, in the
-    // sibling field, and it is why this is a FAILURE rather than a note.
     const beyondHostReach = [];
 
-    // **The boolean means ACCOUNTED FOR, not *holds a skill*, and the distinction is this function's
-    // whole repair** (#108). Three outcomes used to return `false` — genuinely barren, stopped by the
-    // depth bound, and could-not-be-read — and the caller turned every `false` into `barren`. So a
-    // branch the walk never finished searching was reported as one it had searched and found empty:
-    // one defect wearing two failures, and one of the two classifications simply false. *Searched and
-    // found nothing* and *did not finish searching* are different facts, and only the first is barren.
-    //
-    // Truncated and unreadable now return `true` — they are reported under their own headings by the
-    // caller, so the barren list must not claim them as well. `false` is left meaning exactly one
-    // thing: this branch was searched to the bottom and holds no skill.
+    // True once a branch is accounted for; false only when searched to the bottom without a skill.
     const walk = (dir, depth) => {
         if (fs.existsSync(path.join(dir, "SKILL.md"))) {
             found.push(dir);
@@ -1453,9 +852,6 @@ function expandDeclaredSkillRoot(skillRoot) {
         try {
             entries = fs.readdirSync(dir, { withFileTypes: true });
         } catch (error) {
-            // *Could not look* is not *nothing there* — `cli/vendor.mjs` rule 3, and the fail-open this
-            // repository names more than any other. It was silent here, and silence let the caller call
-            // it barren. Now it is a fact with its own list and its own sentence.
             unreadableBranches.push({ dir, why: error.code ?? error.message });
             return true;
         }
@@ -1472,8 +868,7 @@ function expandDeclaredSkillRoot(skillRoot) {
         return any;
     };
 
-    // The `"./"` form: the root is itself one skill. Checked before the expansion so a root holding
-    // both a SKILL.md and subdirectories stays one skill rather than becoming several.
+    // The `"./"` form: a root holding a SKILL.md is one skill, whatever lies beneath it.
     if (fs.existsSync(path.join(skillRoot, "SKILL.md"))) {
         return { found: [skillRoot], barren, truncated, unreadableBranches, beyondHostReach, empty: false };
     }
@@ -1487,8 +882,6 @@ function expandDeclaredSkillRoot(skillRoot) {
     const children = entries.filter((e) => e.isDirectory() && !SKIP_DIRS.has(e.name));
     if (children.length === 0) return { found, barren, truncated, unreadableBranches, beyondHostReach, empty: true };
 
-    // Attribution is per immediate child rather than per branch: a barren branch reported at every
-    // level of itself is one defect wearing three failures.
     for (const child of children) {
         const dir = path.join(skillRoot, child.name);
         if (!walk(dir, 1)) barren.push(dir);
@@ -1505,9 +898,6 @@ const ICON = { fail: "FAIL", note: "note" };
 export async function run(argv, options = {}) {
     const say = options.quiet ? () => {} : (line = "") => process.stdout.write(`${line}\n`);
     try {
-        // `--payload` marks EVERY root on the line as a payload root. Kept deliberately coarse: the
-        // recipe invokes this once per kind, which is clearer at the call site than a per-root syntax
-        // nobody would read twice.
         const payload = argv.includes("--payload");
         const unknown = argv.filter((a) => a.startsWith("-") && a !== "--payload");
         if (unknown.length) {
@@ -1519,12 +909,6 @@ export async function run(argv, options = {}) {
         const roots = argv.filter((a) => !a.startsWith("-"));
         if (roots.length === 0) {
             if (!options.quiet) {
-                // The usage line takes BOTH the plural and the flag, because it was narrower than the
-                // tool on both counts: several roots have been accepted since this file shipped, and
-                // `--payload` arrived with this change. A usage message printed at the moment a caller
-                // already got it wrong is the worst place to be out of date. (Copilot, on the round
-                // reviewing the payload mode — the same sentence-narrower-than-its-code shape this
-                // pull request exists to correct one layer down.)
                 process.stderr.write("usage: node cli/plugin-lint.mjs [--payload] <plugin-root> [<plugin-root> ...]\n");
                 process.stderr.write("  --payload  the roots are payloads a feed publishes: no marketplace.json here, and none owed\n");
             }