@sleepy_panda_srl/portulan 0.2.0 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ workspaces and premium packs delivered as private-marketplace plugins.
 
 ## Status
 
-**Current release: `0.2.0`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
+**Current release: `0.3.0`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
 account of what the release does *not* contain.
 
 This is pre-release software. The leading `0.` is meant literally: nothing here is stable yet, and
@@ -119,7 +119,7 @@ commit, refusing any packed file that differs from its source.
 |---|---|
 | [`init`](cli/init.mjs) | Interview plus codebase scan, producing a drafted workspace |
 | [`doctor`](cli/doctor.mjs) | Validate a workspace against the Workspace Definition |
-| [`compile`](cli/compile.mjs) | Turn gates and verify recipes into host enforcement |
+| [`compile`](cli/compile.mjs) | Turn gates and verify recipes into host enforcement, and what a pack's persona declares about its context into the agent binding it is given, which Claude Code loads only at a plugin root |
 | [`vendor`](cli/vendor.mjs) | Materialise a workspace where it is needed, in either direction |
 | [`index`](cli/index.mjs) | Rebuild the declared indexes over memory, handoffs and personas; print changelog fragments for a release |
 | [`upgrade`](cli/upgrade.mjs) | Migrate a workspace across Workspace Definition versions |

package/cli/README.md

@@ -22,7 +22,7 @@ in [`../.portulan/verify/`](../.portulan/verify/), and its operator tooling in
 |---|---|
 | [`portulan.mjs`](portulan.mjs) | Portulan — the one entry point the `npx` package exposes. |
 | [`init.mjs`](init.mjs) | `portulan init`: draft a workspace for a repository that has none. |
-| [`doctor.mjs`](doctor.mjs) | `portulan doctor`: validate a workspace against the Workspace Definition. |
+| [`doctor.mjs`](doctor.mjs) | `portulan doctor`: validate a workspace and report branch-owned host tokens beside local receipts; --static skips usage records. |
 | [`compile.mjs`](compile.mjs) | `portulan compile`: compile a workspace's gate policy into host enforcement. |
 | [`vendor.mjs`](vendor.mjs) | `portulan vendor`: materialise a workspace where it is needed: into a host, or between residences. |
 | [`index.mjs`](index.mjs) | `portulan index`: regenerate the memory, handoff and scope indexes. |
@@ -63,6 +63,7 @@ Run as `node cli/<file>.mjs`, or imported by the files above.
 | [`instructions.mjs`](instructions.mjs) | `instructions` — the sections a team marks in its own instruction file, moved to on-read units and proved. |
 | [`ledger.mjs`](ledger.mjs) | What a change spends, measured from the host's own usage records. |
 | [`librarian.mjs`](librarian.mjs) | `librarian` — the scheduled pass over the curated layer: reindex, staleness, nags, demotion drafts. |
+| [`local-routing.mjs`](local-routing.mjs) | Verify the shipped operational local roles against their immutable acquired A/B record. No model. Not shipped. |
 | [`manifest.mjs`](manifest.mjs) | The two facts every tool here needs out of `package.json`, read once and in a module that imports nothing of ours. |
 | [`mutants.mjs`](mutants.mjs) | Mutation-test this repository's two gate matchers against the corpus that claims to cover them. |
 | [`pack-identity.mjs`](pack-identity.mjs) | Every file `npm pack` emits is byte-identical to the tracked blob it came from. |
@@ -71,7 +72,7 @@ Run as `node cli/<file>.mjs`, or imported by the files above.
 | [`plugin-lint.mjs`](plugin-lint.mjs) | `plugin-lint` — the packaging validator. |
 | [`recipe-set.mjs`](recipe-set.mjs) | The recipe set: the verify recipes a workspace yields, its own plus each composed pack's, namespaced by pack. |
 | [`release-eval.mjs`](release-eval.mjs) | Portulan — the eval result a release carries. |
-| [`review-meter.mjs`](review-meter.mjs) | The review-loop meter: the figures that bound this repository's review loop, derived from its reviews. |
+| [`review-meter.mjs`](review-meter.mjs) | The review-loop meter: the historical figures of this repository's Copilot review loop, derived from its reviews. |
 | [`roster.mjs`](roster.mjs) | The cli roster: `cli/README.md`, rendered from the files it lists and never edited by hand. Not shipped. |
 | [`rule-carriers.mjs`](rule-carriers.mjs) | `rule-carriers` — the rail that keeps a reduced rule reduced. |
 | [`sessions.mjs`](sessions.mjs) | The session switches' texts: the cache-lifetime offer `init` and `upgrade` print, and the one line `doctor` reports on them. |
@@ -92,6 +93,7 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`ab-run.test.mjs`](ab-run.test.mjs) | Tests for `ab-run` — the A/B runner: isolation, the matrix, the journal, the register and the checks behind it. |
 | [`ab.test.mjs`](ab.test.mjs) | Tests for `ab` — the A/B arm builder: its disposition table, rule-2 matcher, nonces, isolation and stop probe. |
 | [`advisory.test.mjs`](advisory.test.mjs) | Tests for `advisory` — the restart advisory's one line with a tool result or at the prompt, and its figure in the status line. |
+| [`branch-freshness.test.mjs`](branch-freshness.test.mjs) | Tests for this repository's branch freshness check and trusted workflow. |
 | [`checkout-refs.live.test.mjs`](checkout-refs.live.test.mjs) | A workflow that checks out MORE THAN ONCE names the ref of every checkout after the first. |
 | [`cli-roster.live.test.mjs`](cli-roster.live.test.mjs) | `cli/README.md` is exactly what ./roster.mjs renders from this directory, and the render keeps its shape. |
 | [`collisions.test.mjs`](collisions.test.mjs) | The collision contract: `init`, `new` and `vendor` answer each contracted state alike, and no fourth `collisions` exists. |
@@ -100,7 +102,7 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`context.test.mjs`](context.test.mjs) | Tests for `context` — what a boot reads and what the host loads into every context, measured. |
 | [`control-chars.test.mjs`](control-chars.test.mjs) | Tests for `control-chars` — the rail on bytes a reader cannot see. |
 | [`discover.test.mjs`](discover.test.mjs) | Tests for host plugin-cache discovery. |
-| [`doctor.test.mjs`](doctor.test.mjs) | Tests for `doctor` — the Workspace Definition validator. |
+| [`doctor.test.mjs`](doctor.test.mjs) | Tests for `doctor` — workspace validation, branch-owned hybrid usage and static-mode isolation. |
 | [`drills.test.mjs`](drills.test.mjs) | Tests for `drills` — the forced-red drill harness: its table, perturbation guards, pair oracle, hook rails and tree choice. |
 | [`eval-bundle.test.mjs`](eval-bundle.test.mjs) | The evaluation-bundle cutter, driven on this repository AND on real fixture repositories. |
 | [`feedback.live.test.mjs`](feedback.live.test.mjs) | The sender's field map, against the real issue forms rather than against a fixture. |
@@ -121,6 +123,7 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`mutants.test.mjs`](mutants.test.mjs) | Tests for `mutants`, the mutation-census rail: its operator table, its imports, its corpus and its refusals. |
 | [`new.test.mjs`](new.test.mjs) | Tests for `new`: scaffolds that validate, written into the user's own layer and never into `core/`. |
 | [`pack-identity.test.mjs`](pack-identity.test.mjs) | Tests for the byte-identity rail: green, both findings and could-not-run, each exercised. |
+| [`pack-local-llm.test.mjs`](pack-local-llm.test.mjs) | Tests for the `tools/local-llm` pack's runner — its loopback, input-budget and rollback rails, its eval screen, dedup ranking and A/B record. |
 | [`pack-version.test.mjs`](pack-version.test.mjs) | The pack-version rail, driven on REAL git repositories rather than an injected history. |
 | [`payload.test.mjs`](payload.test.mjs) | Tests for the payload-classification rail. |
 | [`pinned-roots.live.test.mjs`](pinned-roots.live.test.mjs) | Required checks name their resolution root, and every suite whose imports reach the host's plugin record empties it. |

package/cli/compile.mjs

@@ -23,7 +23,7 @@ export class CompileError extends Error {
 }
 
 /** The `portulan.spec` versions of `gates.json`: a train separate from the Workspace Definition's, though the numbers overlap. */
-export const KNOWN_GATE_POLICY_SPECS = new Set(["2.1", "2.2"]);
+export const KNOWN_GATE_POLICY_SPECS = new Set(["2.1", "2.2", "2.3"]);
 
 const TIERS = new Set(["auto", "propose", "gated", "prohibited"]);
 
@@ -131,11 +131,11 @@ export function parse(policy) {
         rules.push({ id, tier: rule.tier, kind, target: action[kind], reason: rule.reason, action });
     }
 
-    return { rules, floor: parseFloor(policy.floor) };
+    return { rules, floor: parseFloor(policy.floor, String(spec)) };
 }
 
-/** The optional `floor`, validated whole, or null; `strict` is not declarable, as no pull request merges from behind its base. */
-function parseFloor(floor) {
+/** The optional platform floor, with strict freshness unless the policy explicitly chooses otherwise. */
+function parseFloor(floor, spec) {
     if (floor === undefined || floor === null) return null;
     if (typeof floor !== "object" || Array.isArray(floor)) {
         throw new CompileError("`floor` is present but is not a JSON object");
@@ -180,7 +180,11 @@ function parseFloor(floor) {
     if (typeof floor.resolve_conversations !== "boolean") {
         throw new CompileError("`floor.resolve_conversations` must be a boolean — omitting it would export a floor weaker than the one in force");
     }
-    return { branch, checks, reviews: floor.reviews, resolve_conversations: floor.resolve_conversations };
+    if (Object.hasOwn(floor, "strict")) {
+        if (spec !== "2.3") throw new CompileError("`floor.strict` requires gate-policy 2.3");
+        if (typeof floor.strict !== "boolean") throw new CompileError("`floor.strict` must be a boolean");
+    }
+    return { branch, checks, reviews: floor.reviews, resolve_conversations: floor.resolve_conversations, strict: floor.strict ?? true };
 }
 
 // ---------------------------------------------------------------- what an action means, to the compiler and the gate alike
@@ -811,8 +815,7 @@ export function githubRuleset(parsed, options = {}) {
         rules.push({
             type: "required_status_checks",
             parameters: {
-                // Not declarable: a pull request may never merge from behind its base.
-                strict_required_status_checks_policy: true,
+                strict_required_status_checks_policy: floor.strict,
                 do_not_enforce_on_create: false,
                 required_status_checks: floor.checks,
             },
@@ -2217,10 +2220,18 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
                     `Refusing to compose it — run \`doctor\` to validate the pack against the Pack Definition.`,
             );
         }
+        const personas = packManifest?.contributes?.personas;
+        if (personas !== undefined && !Array.isArray(personas)) {
+            throw new CompileError(
+                `the pack manifest for \`${found.name}\` declares \`contributes.personas\` as ${typeof personas} rather than an array. ` +
+                    `Refusing to compose it — run \`doctor\` to validate the pack against the Pack Definition.`,
+            );
+        }
         contributions.push({
             pack: found.name,
             dir: found.dir,
             fragments: fragments ?? [],
+            personas: personas ?? [],
             origin: recordedOrigin(found.root, plan, workspaceRoot),
             version: typeof packManifest?.portulan?.version === "string" ? packManifest.portulan.version : null,
         });
@@ -2328,6 +2339,291 @@ export function render(settings) {
     return `${JSON.stringify(settings, null, 2)}\n`;
 }
 
+// ---------------------------------------------------------------- personas: what a role declares about its context
+
+/** The fields a persona may declare about the context it runs in, in the order a binding carries them. */
+export const PERSONA_FIELDS = ["model", "effort", "omitClaudeMd", "cacheLifetime"];
+
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+
+const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:@/[\]-]{0,199}$/;
+
+const readBoolean = (raw) => raw === "true" ? true : raw === "false" ? false : undefined;
+
+const PERSONA_VALUES = {
+    model: { read: (raw) => (MODEL_NAME.test(raw) ? raw : undefined), takes: "one model name or alias, written as a single token" },
+    effort: { read: (raw) => (EFFORT_LEVELS.includes(raw) ? raw : undefined), takes: `one of ${EFFORT_LEVELS.join(", ")}` },
+    omitClaudeMd: { read: readBoolean, takes: "`true` or `false`, unquoted" },
+    cacheLifetime: { read: (raw) => (CACHE_LIFETIMES.includes(raw) ? raw : undefined), takes: `one of ${CACHE_LIFETIMES.join(", ")}` },
+};
+
+/** Claude Code's frontmatter key for each field, a dotted one nested under its first word. */
+const CLAUDE_CODE_KEYS = { model: "model", effort: "effort", omitClaudeMd: "omitClaudeMd", cacheLifetime: "experimental.cacheTtl" };
+
+/** `null` is a field the host cannot express; `why` is the sentence the degradation report gives for it. */
+export const PERSONA_HOSTS = {
+    "claude-code": {
+        label: "Claude Code",
+        ...Object.fromEntries(PERSONA_FIELDS.map((field) => [field, `\`${CLAUDE_CODE_KEYS[field]}\``])),
+    },
+    "agents-md": {
+        label: "AGENTS.md, vendored",
+        model: null,
+        effort: null,
+        omitClaudeMd: null,
+        cacheLifetime: null,
+        why: "AGENTS.md defines no agent to carry it, so the role runs with the session's own",
+    },
+};
+
+/** Where a Claude Code binding sits in a tree, as `AGENT_DIR` in ./plugin-lint.mjs, which a test holds it to. */
+export const BINDING_DIR = "agents";
+
+const PLUGIN_MANIFEST = ".claude-plugin/plugin.json";
+
+const unquoted = (raw) => (raw.length >= 2 && `"'`.includes(raw[0]) && raw.at(-1) === raw[0] ? raw.slice(1, -1) : raw);
+
+/** What a persona's top-level frontmatter lines declare: `{ name, declared, problems }`, a malformed value a problem and never a default. */
+export function personaDeclarations(text) {
+    const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+    const close = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
+    const declared = {};
+    const problems = [];
+    const seen = new Set();
+    let name = null;
+    for (const line of close === -1 ? [] : lines.slice(1, close)) {
+        const match = /^([A-Za-z_][\w-]*)\s*:(.*)$/.exec(line);
+        if (match?.[1] === "name") name = unquoted(match[2].trim()).trim() || null;
+        if (!match || !Object.hasOwn(PERSONA_VALUES, match[1])) continue;
+        const [, key, rest] = match;
+        if (seen.has(key)) {
+            problems.push(`declares \`${key}\` twice`);
+            continue;
+        }
+        seen.add(key);
+        const raw = key === "omitClaudeMd" ? rest.trim() : unquoted(rest.trim());
+        const value = PERSONA_VALUES[key].read(raw);
+        if (value === undefined) problems.push(`sets \`${key}\` to ${JSON.stringify(rest.trim())}, and \`${key}\` takes ${PERSONA_VALUES[key].takes}`);
+        else declared[key] = value;
+    }
+    return { name, declared, problems };
+}
+
+const PERSONA_MARK = "# compiled by `portulan compile` from ";
+const PERSONA_MARK_TAIL = "; edit that file, then recompile";
+const BINDING_KEY = /^([A-Za-z_][\w-]*)\s*:(.*)$/;
+const topKey = (field) => CLAUDE_CODE_KEYS[field].split(".")[0];
+
+function bindingLines(declared) {
+    const lines = [];
+    for (const field of PERSONA_FIELDS) {
+        if (declared[field] === undefined) continue;
+        const value = field === "model" ? quoted(declared[field]) : String(declared[field]);
+        const [top, nested] = CLAUDE_CODE_KEYS[field].split(".");
+        lines.push(...(nested ? [`${top}:`, `  ${nested}: ${value}`] : [`${top}: ${value}`]));
+    }
+    return lines;
+}
+
+/** Read recognized compiled fields strictly; the rewritten lines must still match byte for byte. */
+function blockFields(lines, where) {
+    const read = {};
+    let under = null;
+    for (const line of lines) {
+        const nested = /^\s+([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+        const match = nested ? null : BINDING_KEY.exec(line);
+        const key = nested ? `${under}.${nested[1]}` : match?.[1];
+        const raw = (nested?.[2] ?? match?.[2] ?? "").trim();
+        if (!nested) under = key;
+        const field = PERSONA_FIELDS.find((f) => CLAUDE_CODE_KEYS[f] === key);
+        if (!field) continue;
+        let input = raw;
+        if (field === "model") {
+            try { input = JSON.parse(raw); } catch { /* The byte comparison rejects noncanonical quoting. */ }
+        }
+        const value = typeof input === "string" ? PERSONA_VALUES[field].read(input) : undefined;
+        if (value === undefined) throw new CompileError(`${where}: the compiled block holds \`${line}\`, which this compiler did not write — ${PERSONA_VALUES[field].takes}`);
+        read[field] = value;
+    }
+    return read;
+}
+
+/** A Claude Code binding's text with its compiled block rewritten in place from `declared`; every other byte is the binding's own. */
+export function boundAgent(text, declared, source, where) {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    if (eol === "\r\n" && text.replaceAll("\r\n", "").includes("\n")) {
+        throw new CompileError(`${where} mixes CRLF and LF line endings, so which lines are its own cannot be told apart. Give it one ending, then compile again`);
+    }
+    const lines = text.split(eol);
+    const close = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
+    if (close === -1) {
+        throw new CompileError(`${where} has no frontmatter block to compile ${source}'s fields into — a host reads an agent's \`name\`, \`description\` and \`tools\` from one`);
+    }
+    const owned = new Set(PERSONA_FIELDS.map(topKey));
+    const front = [];
+    let at = null;
+    for (let i = 1; i < close; i += 1) {
+        if (!lines[i].startsWith(PERSONA_MARK)) {
+            front.push(lines[i]);
+            continue;
+        }
+        if (at !== null) throw new CompileError(`${where} carries two compiled blocks. Delete one, then compile again`);
+        at = front.length;
+        const block = [];
+        while (i + 1 < close && (/^\s/.test(lines[i + 1]) || owned.has(BINDING_KEY.exec(lines[i + 1])?.[1]))) block.push(lines[(i += 1)]);
+        const written = bindingLines(blockFields(block, where));
+        const stray = block.find((line) => !written.includes(line)) ?? block.find((line, n) => line !== written[n]);
+        if (stray !== undefined) {
+            throw new CompileError(
+                `${where}: the block compiled from ${source} holds \`${stray}\`, which this compiler did not write. Move the line above the ` +
+                    "mark or delete it, then compile again: removing it unasked would lose a line somebody wrote",
+            );
+        }
+    }
+    const writes = new Set(PERSONA_FIELDS.filter((f) => declared[f] !== undefined).map(topKey));
+    for (const line of front) {
+        const key = BINDING_KEY.exec(line)?.[1];
+        if (writes.has(key)) {
+            throw new CompileError(
+                `${where} sets \`${key}\` by hand, and ${source} declares it. Remove the line from the binding: the persona's value is the one compiled, and two would leave the host to pick`,
+            );
+        }
+        if (writes.size && owned.has(key)) {
+            throw new CompileError(
+                `${where} sets \`${key}\` by hand, which ${source} does not declare. Declare it in the persona or remove the line: in a binding ` +
+                    "it compiles into, `compile` owns every key a persona may declare",
+            );
+        }
+    }
+    const block = writes.size ? [`${PERSONA_MARK}${source}${PERSONA_MARK_TAIL}`, ...bindingLines(declared)] : [];
+    const place = at ?? front.length;
+    return [lines[0], ...front.slice(0, place), ...block, ...front.slice(place), ...lines.slice(close)].join(eol);
+}
+
+const listed = (names) => (names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`);
+
+/** Each composed persona against its host binding: the bindings to rewrite, the lines to say, and what each host cannot carry. */
+export function planPersonas(contributions, workspaceRoot, workspaceDir = ".portulan") {
+    const base = path.join(workspaceRoot, workspaceDir);
+    let tree = null;
+    try {
+        tree = JSON.parse(fs.readFileSync(path.join(base, "workspace.json"), "utf8"))?.tree;
+    } catch {
+        // `run` refuses an unreadable manifest before this is reached; an absent one declares no tree.
+    }
+    const treeRoot = typeof tree === "string" && tree.trim() ? path.resolve(base, tree) : null;
+    const files = [];
+    const lines = [];
+    const degraded = [];
+    const owners = new Map();
+    let compared = 0;
+    for (const contribution of contributions) {
+        for (const rel of contribution.personas ?? []) {
+            const where = `\`${contribution.pack}\`'s persona \`${rel}\``;
+            const file = path.resolve(contribution.dir, rel);
+            let text;
+            try {
+                if (!isInside(fs.realpathSync(contribution.dir), fs.realpathSync(file))) throw new CompileError(`${where} resolves outside its pack`);
+                text = fs.readFileSync(file, "utf8");
+            } catch (cause) {
+                if (cause instanceof CompileError) throw cause;
+                throw new CompileError(`${where} could not be read — ${cause.code ?? cause.message}, so what it declares is unknown. Run \`doctor\` to validate the pack`);
+            }
+            const { name: declaredName, declared, problems } = personaDeclarations(text);
+            if (problems.length) {
+                throw new CompileError(`${where} ${problems.join("; it ")}. core/personas/README.md gives the fields a persona may declare`);
+            }
+            const fields = PERSONA_FIELDS.filter((f) => declared[f] !== undefined);
+            const name = declaredName ?? path.basename(rel, ".md");
+            if (fields.length && !SLUG.test(name)) {
+                throw new CompileError(`${where} is named \`${name}\`, which is not a slug, so no binding file can be named for it`);
+            }
+            const source = `${contribution.pack}'s ${rel}`;
+            for (const field of fields) {
+                for (const [id, host] of Object.entries(PERSONA_HOSTS)) {
+                    if (host[field] === null) degraded.push({ persona: name, field, host: id, line: `degraded ${name.padEnd(22)} ${field.padEnd(14)} ${id} (${host.label}): ${host.why}` });
+                }
+            }
+            if (!SLUG.test(name)) continue;
+            const bindingRel = `${BINDING_DIR}/${name}.md`;
+            if (owners.has(bindingRel)) {
+                const sources = [owners.get(bindingRel), source].sort();
+                throw new CompileError(`${bindingRel} has multiple persona owners: ${sources.join(" and ")}. Each binding must have one owner`);
+            }
+            owners.set(bindingRel, source);
+            if (!treeRoot) {
+                if (fields.length) lines.push(`persona  ${name.padEnd(22)} UNBOUND — declares ${listed(fields)}, and this workspace declares no \`tree\` to hold its binding`);
+                continue;
+            }
+            const binding = path.join(treeRoot, BINDING_DIR, `${name}.md`);
+            const shown = path.relative(workspaceRoot, binding).split(path.sep).join("/");
+            let stat = null;
+            try {
+                stat = fs.lstatSync(binding);
+            } catch (cause) {
+                if (cause.code !== "ENOENT") throw new CompileError(`${shown} could not be examined — ${cause.code ?? cause.message}`);
+            }
+            if (stat === null) {
+                if (fields.length) lines.push(`persona  ${name.padEnd(22)} UNBOUND — declares ${listed(fields)}, and no host binding at \`${bindingRel}\` carries them`);
+                continue;
+            }
+            if (!stat.isFile()) {
+                throw new CompileError(`${shown} binds ${where} and is not a regular file, so nothing is compiled through it`);
+            }
+            try {
+                if (!isInside(fs.realpathSync(treeRoot), fs.realpathSync(binding))) {
+                    throw new CompileError(`${shown} resolves outside the declared tree, so nothing is compiled through it`);
+                }
+            } catch (cause) {
+                if (cause instanceof CompileError) throw cause;
+                throw new CompileError(`${shown} could not be resolved against the declared tree — ${cause.code ?? cause.message}`);
+            }
+            const current = fs.readFileSync(binding, "utf8");
+            const next = boundAgent(current, declared, source, shown);
+            if (fields.length) lines.push(`persona  ${name.padEnd(22)} ${listed(fields)} → ${shown} (${PERSONA_HOSTS["claude-code"].label})`);
+            if (fields.length && !fs.existsSync(path.join(treeRoot, ...PLUGIN_MANIFEST.split("/")))) {
+                degraded.push({
+                    persona: name,
+                    field: null,
+                    host: "claude-code",
+                    line:
+                        `degraded ${name.padEnd(22)} ${listed(fields)} claude-code (Claude Code): ${shown} loads only from a plugin root, and this tree ` +
+                        `has no ${PLUGIN_MANIFEST}; compile writes no .claude/agents/, so nothing here loads the compiled fields`,
+                });
+            }
+            if (fields.length || next !== current) compared += 1;
+            if (next !== current) files.push({ path: shown, file: binding, text: next, source });
+        }
+    }
+    return { files, lines, degraded, compared };
+}
+
+const unresolvedLine = (u) => `pack    ${u.name.padEnd(30)} UNRESOLVED — ${u.why}; it contributes nothing`;
+
+function printPersonaReport(say, personas) {
+    if (!personas.lines.length && !personas.degraded.length) return;
+    say();
+    for (const line of [...personas.lines, ...personas.degraded.map((d) => d.line)]) say(`  ${line}`);
+}
+
+function emitPersonas(personas, { check, say }) {
+    if (!personas) return 0;
+    for (const line of personas.lines) say(line);
+    for (const d of personas.degraded) say(d.line);
+    let drifted = 0;
+    for (const f of personas.files) {
+        if (check) {
+            say(`RED — ${f.path} has drifted from ${f.source}. Recompile.`);
+            drifted += 1;
+        } else {
+            fs.writeFileSync(f.file, f.text);
+            say(`wrote ${f.file}`);
+        }
+    }
+    if (personas.lines.length || personas.degraded.length || personas.files.length) say();
+    return drifted;
+}
+
 // ---------------------------------------------------------------- the command line
 
 function printMatrix(say, parsed, columns, { source }) {
@@ -2540,14 +2836,19 @@ export function run(argv, options = {}) {
                 );
             }
             say();
+            const packs = packContributions(workspaceRoot, workspaceDir, packOptions);
+            for (const u of packs.unresolved) say(unresolvedLine(u));
+            if (packs.unresolved.length) say();
+            const personas = planPersonas(packs.contributions, workspaceRoot, workspaceDir);
             if (showMatrix) {
                 printGuidanceMatrix(say, guidance);
+                printPersonaReport(say, personas);
                 return 0;
             }
-            const drifted = emitGuidance(guidance, guidancePlan, { workspaceRoot, check, say });
+            const drifted = emitPersonas(personas, { check, say }) + emitGuidance(guidance, guidancePlan, { workspaceRoot, check, say });
             if (!check) return 0;
             if (drifted) return 1;
-            say("GREEN — every compiled guidance file matches its unit");
+            say(`GREEN — every compiled guidance file matches its unit${personas.compared ? ", and every persona binding its persona" : ""}`);
             return 0;
         }
         const policy = readJson(policyFile, "the gate policy");
@@ -2557,6 +2858,7 @@ export function run(argv, options = {}) {
             discovery: () => discoverPackRoots(),
             forced,
         });
+        const personas = planPersonas(contributions, workspaceRoot, workspaceDir);
         // Only under `--matrix`, as it moves with what is installed; but a union is never silent.
         if (plan && (showMatrix || plan.source === "union")) say(`packs: resolution root ${plan.source} — ${plan.why}`);
         const composed = composeFragments(policy, contributions);
@@ -2575,9 +2877,7 @@ export function run(argv, options = {}) {
         for (const t of composed.tightened) {
             say(`pack    ${t.pack.padEnd(30)} tightens \`${t.id}\` ${t.from} → ${t.to}`);
         }
-        for (const u of unresolved) {
-            say(`pack    ${u.name.padEnd(30)} UNRESOLVED — ${u.why}; it contributes nothing`);
-        }
+        for (const u of unresolved) say(unresolvedLine(u));
         if (composed.added.length || composed.tightened.length || unresolved.length) say();
 
         if (showMatrix) {
@@ -2586,6 +2886,7 @@ export function run(argv, options = {}) {
                 say();
                 printGuidanceMatrix(say, guidance);
             }
+            printPersonaReport(say, personas);
             return 0;
         }
 
@@ -2642,9 +2943,12 @@ export function run(argv, options = {}) {
                     drifted += 1;
                 }
             }
+            drifted += emitPersonas(personas, { check, say });
             drifted += emitGuidance(guidance, guidancePlan, { workspaceRoot, check, say });
             if (drifted) return 1;
-            say(guidance ? "GREEN — every emitted artifact matches the policy, and every guidance file its unit" : "GREEN — every emitted artifact matches the policy");
+            const bindings = personas.compared ? ", and every persona binding its persona" : "";
+            const guided = bindings ? `, every guidance file its unit${bindings}` : ", and every guidance file its unit";
+            say(`GREEN — every emitted artifact matches the policy${guidance ? guided : bindings}`);
             return 0;
         }
 
@@ -2663,6 +2967,7 @@ export function run(argv, options = {}) {
             fs.writeFileSync(file, column.artifact.text);
             say(`wrote ${file}`);
         }
+        emitPersonas(personas, { check, say });
         emitGuidance(guidance, guidancePlan, { workspaceRoot, check, say });
         return 0;
     } catch (error) {

package/cli/doctor.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 // `doctor` — the Workspace Definition validator.
 //
-//   node cli/doctor.mjs [--pack-root <dir>|auto]... [--repo-root <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.
 
 import fs from "node:fs";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -18,6 +19,7 @@ import {
     composeFragments,
     packDifferences,
     shadowedCopy,
+    personaDeclarations,
 } from "./compile.mjs";
 import { isInside, recordType } from "./index.mjs";
 import { parseFrontmatter, AGENT_DIR } from "./plugin-lint.mjs";
@@ -26,6 +28,7 @@ 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");
@@ -506,6 +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`);
         }
     }
+    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(
@@ -1499,7 +1505,7 @@ 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 {
                     report("bindings", `${where}'s binding at \`${rel}\` could not be read — ${cause.code ?? cause.message}. Unread, not absent`);
@@ -1850,7 +1856,7 @@ 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",
     );
 
@@ -1889,6 +1895,32 @@ export async function inspect(workspaceDir, options = {}) {
     return { dir, workspace, findings, stats };
 }
 
+/** 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 " };
@@ -1903,8 +1935,9 @@ 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",
@@ -1927,6 +1960,7 @@ export async function run(argv, options = {}) {
         return 0;
     }
     try {
+        let staticMode = false;
         const namedRoots = [];
         let discoverPacks = false;
         const repoRoots = [];
@@ -1953,7 +1987,9 @@ 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") {
@@ -1971,7 +2007,7 @@ export async function run(argv, options = {}) {
         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;
         }
@@ -1983,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}`);
@@ -1992,6 +2028,9 @@ 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;
         }