@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/librarian.mjs

@@ -22,6 +22,8 @@ import { pathToFileURL } from "node:url";
 
 import { inspect as inspectIndex, IndexError, recordType, dateOf, isInside } from "./index.mjs";
 import { parseProvenance } from "./doctor.mjs";
+import { alwaysTier, declaredContext, ESTIMATED_BYTES_PER_TOKEN, tokensOf, TOP_CONTRIBUTORS, treeOf } from "./context.mjs";
+import { BOOT_CARD_UNIT, ENGINE_LINE, GATES_LINE, guidanceDeclaration, guidanceEdits, GUIDANCE_RULES_DIR, LEADS_LINE, parseUnit, resolveWorkspace, RULES_MARKER } from "./compile.mjs";
 
 /** Raised when the pass cannot run, or cannot report honestly. Always exit 2. */
 export class LibrarianError extends Error {
@@ -31,7 +33,7 @@ export class LibrarianError extends Error {
     }
 }
 
-const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13"]);
+const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "2.15", "2.16"]);
 
 const NOT_A_RECORD = new Set(["README.md"]);
 
@@ -89,22 +91,32 @@ export function retireWhen(source) {
         .trim();
 }
 
-/** Whether a proposal still waits on the human gate: anything short of a stated verdict does, as this feeds a nag, never a gate. */
+/** Explicit leading outcomes only; this classifies a report, never grants consent. */
 export function proposalPending(source) {
-    const lines = source.split("\n");
-    const parts = [];
-    for (let i = 0; i < lines.length; i += 1) {
-        if (!/^\s*\*\*(decision|status)\b/i.test(lines[i])) continue;
-        let end = i;
-        while (end + 1 < lines.length && lines[end + 1].trim() !== "") end += 1;
-        parts.push(lines.slice(i, end + 1).join(" "));
-        i = end;
-    }
-    if (!parts.length) return true;
-    const text = parts.join(" ").replace(/[*_`]/g, "");
-    if (/\bpending\b/i.test(text)) return true;
-    if (/[{}]|\|/.test(text)) return true; // an unfilled template line is not a decision
-    return !/\b(accepted|rejected|revised|applied|withdrawn|superseded)\b/i.test(text);
+    const words = "accepted|rejected|revised|applied|withdrawn|superseded|ruled";
+    const outcome = new RegExp(`^(${words})\\b`, "i");
+    const outcomeWord = new RegExp(`\\b(${words}|pending)\\b`, "i");
+    let settled = false;
+    for (const line of source.split("\n")) {
+        const marker = line.match(/^\s*\*\*(decision|status)[.:]/i);
+        if (!marker) continue;
+        const declaration = line.replace(/[*_]/g, "").replace(/^\s*(decision|status)[.:]\s*/i, "").split(/\bbecause\b/i)[0].trim();
+        const ownerForm = marker[1].toLowerCase() === "decision" ? declaration.match(/^[^—{}|<>\n]{1,160}—\s*(.*)$/) : null;
+        const leading = outcome.test(declaration) ? declaration : ownerForm?.[1] ?? declaration;
+        const match = leading.match(outcome);
+        if (!match) {
+            if (outcomeWord.test(declaration) || /[{}|<>]/.test(declaration)) return true;
+            if (ownerForm && !/^\d{4}-\d{2}-\d{2}\b/.test(leading)) return true;
+            continue;
+        }
+        const header = leading.split(/—|\bbecause\b/i)[0];
+        if (/[{}|<>?]/.test(header)) return true;
+        const rest = header.slice(match[0].length);
+        const alternative = rest.match(/\/|\bor\b|\bversus\b|\bvs\b|\b(?:and|but)\s+not\b/i);
+        if (alternative && outcomeWord.test(rest.slice(alternative.index))) return true;
+        settled = true;
+    }
+    return !settled;
 }
 
 // ---------------------------------------------------------------- Reading history
@@ -173,6 +185,58 @@ const listMarkdown = (dir) => {
     return names.filter((n) => n.endsWith(".md") && !NOT_A_RECORD.has(n)).sort();
 };
 
+function contextHeadroom(dir, workspace) {
+    try {
+        const declared = declaredContext(workspace);
+        const tree = treeOf(dir, workspace);
+        const base = { budget: declared.budget, ratio: declared.ratio ?? ESTIMATED_BYTES_PER_TOKEN, calibratedBy: declared.calibratedBy, drafts: [] };
+        if (tree === null) return { ...base, state: "unmeasured", bytes: null, tokens: null, remaining: null, reason: "no tree is declared" };
+        const root = fs.realpathSync(tree);
+        const measured = alwaysTier(root);
+        const bytes = measured.entries.reduce((sum, entry) => sum + entry.bytes, 0);
+        const tokens = tokensOf(bytes, base.ratio);
+        const result = { ...base, state: "measured", bytes, tokens, remaining: base.budget === null ? null : base.budget - tokens,
+            exclusions: { missing: measured.missing, outside: measured.outside, tooDeep: measured.tooDeep, scoped: measured.scoped, unlisted: measured.unlisted } };
+        if (base.budget === null) return result;
+        const realDir = fs.realpathSync(dir);
+        const declaration = guidanceDeclaration(root, path.relative(root, realDir) || ".");
+        if (declaration === null) return result;
+        const realContext = fs.realpathSync(declaration.dir);
+        if (!isInside(realDir, realContext) || realContext === realDir) throw new LibrarianError("slots.context resolves outside its workspace");
+        const loaded = new Map(measured.entries.filter(entry => entry.label === "rule").map(entry => [path.resolve(entry.file), entry]));
+        for (const file of listMarkdown(declaration.dir)) {
+            const source = path.join(declaration.dir, file);
+            if (fs.realpathSync(source) !== path.resolve(source)) continue;
+            if (measured.entries.some(entry => fs.realpathSync(entry.file) === source)) continue;
+            const unit = parseUnit(path.basename(file, ".md"), fs.readFileSync(source, "utf8"), file);
+            if (unit.tier !== "always" || unit.name === BOOT_CARD_UNIT || unit.body.includes("@")) continue;
+            if (unit.body.split("\n").some(line => [ENGINE_LINE, GATES_LINE, LEADS_LINE].some(pattern => pattern.test(line)))) continue;
+            const target = path.join(root, GUIDANCE_RULES_DIR, file);
+            const entry = loaded.get(target);
+            if (!entry || fs.realpathSync(target) !== path.resolve(target)) continue;
+            result.drafts.push({ source: path.relative(realDir, source).split(path.sep).join("/"), target: path.relative(root, target).split(path.sep).join("/"),
+                from: "always", to: "on-read", bytes: entry.bytes, tokens: tokensOf(entry.bytes, base.ratio) });
+        }
+        if (result.drafts.length) {
+            const plan = guidanceEdits(realDir);
+            if (fs.realpathSync(plan.root) !== root) throw new LibrarianError("the compiler ownership plan does not cover the measured tree; no demotions can be drafted");
+            const resolved = resolveWorkspace(realDir);
+            if (fs.realpathSync(path.resolve(resolved.workspaceRoot, resolved.workspaceDir)) !== realDir) throw new LibrarianError("the compiler ownership plan does not cover the measured workspace; no demotions can be drafted");
+            const repairs = new Set([...plan.edits.map(edit => edit.file), ...plan.left]);
+            if (repairs.has(`${GUIDANCE_RULES_DIR}/${RULES_MARKER}`)) {
+                result.drafts = [];
+                result.draftNote = "Compiler ownership needs regeneration; recompile before drafting demotions.";
+            } else result.drafts = result.drafts.filter(draft => !repairs.has(draft.target));
+        }
+        result.drafts.sort((a, b) => b.bytes - a.bytes || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0));
+        result.drafts = result.drafts.slice(0, TOP_CONTRIBUTORS);
+        return result;
+    } catch (cause) {
+        if (cause instanceof LibrarianError) throw cause;
+        throw new LibrarianError(`the always tier could not be measured or drafted — ${cause.message}`);
+    }
+}
+
 /** One workspace's pass, which never writes: `run` does, after it. */
 export function passWorkspace(dir, { asOf, reviews, since } = {}) {
     parseDate(asOf, "--as-of");
@@ -385,6 +449,7 @@ export function passWorkspace(dir, { asOf, reviews, since } = {}) {
         handoffs: series,
         mining,
         consolidation,
+        context: contextHeadroom(dir, workspace),
     };
 }
 
@@ -509,8 +574,8 @@ export function renderReport(results, { asOf }) {
         "",
         `**Date:** ${asOf} · Filed by \`cli/librarian.mjs\` on a cron.`,
         "",
-        "**State.** Every figure below is **as of " + asOf + "**, read from git history rather than from the",
-        "filesystem, and nothing here is a decision. This pass drafts; the maintainer disposes.",
+        `**State.** Ages are read from git history as of ${asOf}; sizes and context headroom describe the tree on arrival, before any index regeneration.`,
+        "Nothing here is a decision. This pass drafts; the maintainer disposes.",
         "",
     ];
 
@@ -521,6 +586,25 @@ export function renderReport(results, { asOf }) {
         }
         const t = r.thresholds;
         out.push(`## ${r.name}`, "");
+        const context = r.context;
+        if (context) {
+            const cap = context.budget === null ? "budget undeclared; headroom unjudged" : `budget ${context.budget} tokens`;
+            if (context.state === "unmeasured") out.push(`**Always tier — Claude Code project.** Not measured: ${context.reason}; ${cap}.`, "");
+            else {
+                const headroom = context.remaining === null ? cap : `${cap}; ~${context.remaining} tokens headroom`;
+                out.push(`**Always tier — Claude Code project.** ${context.bytes} B, ~${context.tokens} tokens at ${context.ratio} bytes per token (${context.calibratedBy ?? "unconfigured estimate"}); ${headroom}.`, "");
+                const e = context.exclusions;
+                out.push(`**Measurement limits.** ${e.missing.length} missing imports; ${e.outside.length} outside imports or links; ${e.tooDeep.length} depth-limited imports; ${e.scoped} path-scoped rules; ${e.unlisted} descriptions unavailable. Personal/parent instructions, auto memory, system/tool prompts and plugin descriptions are outside this project measurement.`, "");
+                for (const [label, values] of [["Missing", e.missing], ["Outside", e.outside], ["Depth-limited", e.tooDeep]]) {
+                    if (values.length) out.push(`${label}: ${values.map(value => `\`${value}\``).join(", ")}.`, "");
+                }
+            }
+            out.push(`**Context demotion drafts.** ${context.drafts.length} conditional candidate(s); nothing applied. Pure, loaded, compiler-owned, matching always units only; boot cards, at-sign text, imported sources, expansions, links and stale targets are not drafted.`, "");
+            if (context.draftNote) out.push(context.draftNote, "");
+            for (const draft of context.drafts) {
+                out.push(`- **Draft: \`${draft.source}\`, \`${draft.from}\` → \`${draft.to}\`.** \`${draft.target}\` currently contributes ${draft.bytes} B (~${draft.tokens} tokens). If the maintainer decides this guidance can wait for an explicit read, change its tier, add a one-line \`description\`, preserve its body, recompile, and record before/after measurements. This is not a measured savings claim.`, "");
+            }
+        }
         out.push(
             `**Store.** ${plural(r.counts.records, "record")}, ${plural(r.counts.rules, "rule")}, ` +
                 `${(r.counts.bytes / 1024).toFixed(1)} KB` +
@@ -543,7 +627,7 @@ export function renderReport(results, { asOf }) {
                     `${(r.handoffs.bytes / 1024).toFixed(1)} KB, oldest ${r.handoffs.oldest ? `\`${r.handoffs.oldest.file}\` at ${plural(r.handoffs.oldest.days, "day")}` : "none — the series is empty"}. ` +
                     "Index: " +
                     indexState(r.index.series.handoffs) +
-                    ". No threshold reaches this series and no demotion is drafted against it: it is " +
+                    ". No aggregate size or staleness threshold reaches this series and no staleness demotion is drafted against it: it is " +
                     "append-only, so the only repair a staleness draft could recommend is deleting the " +
                     "record the series exists to keep.",
                 "",

package/cli/persona-routing.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// Regrade the acquired core-persona records and check their shipped routing without a model.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { CORPUS, grade, price } from "../evals/ab/personas/grader.mjs";
+
+export const CAPTURE = "evals/ab/personas/acquisition.json";
+export const CAPTURE_SHA256 = "ff3688658bc20af6b78e834a5149ea6bd52bc88027b0340ec98cb52430c6d641";
+export const ROLES = ["implementer", "reviewer", "librarian"];
+export const ROUTING = { model: "inherit", effort: null, omitClaudeMd: false, cacheLifetime: "5m" };
+const CLASSES = ["uncached", "written5m", "written1h", "writtenUnknown", "read", "output"];
+const BAD_DESCRIPTION = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+const sha = bytes => createHash("sha256").update(bytes).digest("hex");
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const demand = (ok, why) => { if (!ok) throw new Finding(why); };
+export class Finding extends Error {}
+
+export function bindingContract(text) {
+    demand(typeof text === "string" && text.startsWith("---\n") && !text.includes("\uFFFD"), "binding frontmatter is unusable");
+    const close = text.indexOf("\n---\n", 4);
+    demand(close !== -1, "binding frontmatter is unclosed");
+    const lines = text.slice(4, close).split("\n");
+    const descriptions = lines.filter(line => /^\s*description\s*:/.test(line));
+    demand(descriptions.length === 1 && /^description: \S/.test(descriptions[0]), "binding needs one nonempty single-line description");
+    for (const line of lines.slice(lines.indexOf(descriptions[0]) + 1)) {
+        if (/^[A-Za-z_][\w-]*\s*:/.test(line)) break;
+        demand(!line.trim() || /^\s*#/.test(line), "binding description has a multiline continuation");
+    }
+    const raw = descriptions[0].slice("description: ".length);
+    demand(!BAD_DESCRIPTION.test(raw), "binding description contains a control or line separator");
+    let value;
+    if (raw.startsWith('"')) {
+        try { value = JSON.parse(raw); } catch {}
+    } else if (raw.startsWith("'")) {
+        if (/^'(?:[^']|'')*'$/.test(raw)) value = raw.slice(1, -1).replaceAll("''", "'");
+    } else if (/^[\p{L}_][^:#{}\[\]\r\n]*$/u.test(raw) && !/^(true|false|null)$/i.test(raw.trim())) value = raw;
+    demand(typeof value === "string" && value.trim() && !BAD_DESCRIPTION.test(value), "binding description is not a usable single-line scalar");
+    return text.slice(0, 4) + lines.map(line => line === descriptions[0] ? "description: <description>" : line).join("\n") + text.slice(close);
+}
+
+export function costOf(call) {
+    const parent = price(call.usage.parent), child = price(call.usage.child);
+    return { parent, child, observed: parent.observed + child.observed, normalized: parent.normalized + child.normalized };
+}
+
+export function summarize(record) {
+    const arms = Object.fromEntries(["a", "b"].map(arm => {
+        const turns = record.turns.filter(turn => turn.arm === arm);
+        const costs = turns.map(costOf);
+        return [arm, { passed: turns.filter(turn => grade(CORPUS.cases.find(task => task.id === turn.task), turn.answer).ok).length,
+            cases: turns.length, observed: costs.reduce((sum, value) => sum + value.observed, 0), normalized: costs.reduce((sum, value) => sum + value.normalized, 0) }];
+    }));
+    return { arms, mediumWinsObservedCorpus: arms.b.passed === 3 && arms.b.normalized < arms.a.normalized,
+        shipped: ROUTING, scope: "retained policy; one observed model and three cases; no global medium default earned" };
+}
+
+export function register(record) {
+    const result = summarize(record);
+    const lines = [`# ${record.role} — acquired routing comparison`, "", `Host: ${record.host}. Concrete model: ${record.model}.`, "",
+        "A uses the shipped inherited model and undeclared child effort (observed high). B requests medium through the native child tool. Each case has one attempt per arm.", "",
+        "| Arm | Semantic passes | Observed cost index | Cold-normalized cost index |", "|---|---:|---:|---:|"];
+    for (const arm of ["a", "b"]) {
+        const value = result.arms[arm];
+        lines.push(`| ${arm.toUpperCase()} | ${value.passed}/${value.cases} | ${value.observed.toFixed(2)} | ${value.normalized.toFixed(2)} |`);
+    }
+    lines.push("", `Medium wins this observed corpus: **${result.mediumWinsObservedCorpus ? "yes" : "no"}**. The shipped policy remains inherited model, undeclared effort, instruction floor retained and five-minute cache lifetime.`, "",
+        "These are three observations, not a reliability estimate. A result on this concrete model does not establish medium effort for other inherited models. Cost indexes use the frozen declared vector, include parent and child requests, and are not subscription bills. First-request input is normalized separately in each fresh parent and child context.", "",
+        "| Case | A | B |", "|---|---|---|");
+    for (const task of CORPUS.cases.filter(task => task.role === record.role)) {
+        const verdict = arm => grade(task, record.turns.find(turn => turn.task === task.id && turn.arm === arm).answer).ok ? "PASS" : "FAIL";
+        lines.push(`| ${task.id} | ${verdict("a")} | ${verdict("b")} |`);
+    }
+    lines.push("", "The common acquisition record accounts for both mechanism probes and discloses the one retained-answer decoder repair after the first outcome. The original failed decode score and the repaired score are both retained; that child was never rerun.", "");
+    return lines.join("\n");
+}
+
+function checkCall(call, model, ids, contexts, quality = false) {
+    demand(call && ["complete", "invalid"].includes(call.state), "call completion state missing");
+    demand(typeof call.context === "string" && !contexts.has(call.context), "a parent context was reused");
+    contexts.add(call.context);
+    demand(typeof call.childContext === "string" && !contexts.has(call.childContext), "a child context was reused");
+    contexts.add(call.childContext);
+    demand(hash(call.raw?.parent) && hash(call.raw?.result), "raw parent/result digest missing");
+    demand(Date.parse(call.started) <= Date.parse(call.ended), "call timing is invalid");
+    for (const side of ["parent", "child"]) {
+        const requests = call.usage?.[side];
+        demand(Array.isArray(requests) && requests.length > 0, `${side} usage missing`);
+        for (const [index, request] of requests.entries()) {
+            demand(typeof request.id === "string" && !ids.has(request.id), "duplicate request identity");
+            ids.add(request.id);
+            demand(request.model === model, "concrete model changed");
+            demand(request.effort === (side === "parent" ? "high" : call.effort ?? "high"), "effective effort differs from frozen arm");
+            demand(Number.isFinite(request.at) && request.at >= Date.parse(call.started) && request.at <= Date.parse(call.ended), "request outside its call");
+            demand(index === 0 || request.at >= requests[index - 1].at, "usage requests are out of chronological order");
+            for (const key of CLASSES) demand(Number.isSafeInteger(request[key]) && request[key] >= 0, `invalid ${key} count`);
+        }
+    }
+    costOf(call);
+    if (!quality) return;
+    demand(call.state === "complete" && call.exit === 0 && call.timedOut === false, "quality call did not complete");
+    demand(hash(call.raw.child) && hash(call.invocation?.promptSha256), "raw child/prompt digest missing");
+    demand(call.invocation.type === `portulan:${call.role}` && call.invocation.effort === call.effort && call.invocation.model === null && call.invocation.background === false, "native child selection changed");
+    demand(call.model === model && call.requestedModel === model, "quality model changed");
+    demand(call.parentEffort === "high" && call.fresh === true, "quality parent was not fresh/high");
+    demand(hash(call.answerRawSha256) && sha(call.answer) === call.answerPresentationSha256 && typeof call.answerNormalized === "boolean", "answer presentation provenance missing");
+    demand(call.answerNormalized === (call.answerRawSha256 !== call.answerPresentationSha256), "answer normalization flag differs");
+    demand(!/\/Users\/|\/private\/var\/folders\//.test(call.answer), "an original local path remains in a public answer");
+}
+
+export function verifyData(capture, records) {
+    demand(capture.version === 1 && capture.phase === "complete", "acquisition is incomplete");
+    demand(capture.model === "claude-sonnet-5-5" && same(capture.prices, CORPUS.prices), "frozen model or price vector changed");
+    demand(capture.seed === CORPUS.seed && /^[a-f0-9]{40}$/.test(capture.sourceCommit), "corpus seed or source commit missing");
+    demand(same(Object.keys(capture.taskSha256 ?? {}).sort(), CORPUS.cases.map(task => task.id).sort()), "frozen task roster changed");
+    for (const task of CORPUS.cases) demand(sha(JSON.stringify({ role: task.role, task: task.task }, null, 2) + "\n") === capture.taskSha256[task.id], "frozen task bytes differ from the public corpus");
+    demand(same(capture.routing, ROUTING), "routing differs from retained policy");
+    demand(capture.preflights?.length === 2 && capture.preflights[0].state === "invalid" && capture.preflights[1].state === "complete", "both mechanism probes must be accounted");
+    demand(capture.preflights[0].reason === "error_max_budget_usd" && capture.preflights[0].argvProvenance === "reconstructed-after-execution", "failed first probe provenance missing");
+    demand(capture.preflights[1].markerSeen === true, "native medium mechanism was not demonstrated");
+    demand(capture.preflights[0].instrumentSha256 === capture.instruments.firstProbe.sha256 && capture.preflights[1].instrumentSha256 === capture.instruments.secondProbe.sha256, "probe instrument attribution differs");
+    const repair = capture.decodeRepair;
+    demand(repair?.observedOutcomes === 1 && repair.retainedKey === "implementer-lower-bound-a" && repair.reruns === 0 && repair.approval === "PASS", "one-answer repair disclosure missing");
+    for (const key of ["previousGrader", "grader", "abortedJournalSha256", "approvalSha256", "semanticSuffixSha256"]) demand(hash(repair[key]), `repair ${key} missing`);
+    const ids = new Set(), contexts = new Set();
+    checkCall(capture.preflights[0], "claude-fable-5-2", ids, contexts);
+    checkCall(capture.preflights[1], capture.model, ids, contexts, true);
+    demand(capture.preflights[1].effort === "medium" && capture.preflights[1].answer === "MECHANISM_OK", "medium probe answer/effort differs");
+    const all = [];
+    for (const role of ROLES) {
+        const record = records[role];
+        demand(record?.version === 1 && record.role === role && record.model === capture.model && record.host === capture.host, "role record identity changed");
+        demand(record.turns?.length === 6, "role has other than six acquired turns");
+        const expected = CORPUS.cases.filter(task => task.role === role).flatMap(task => ["a", "b"].map(arm => `${task.id}-${arm}`));
+        demand(same(record.turns.map(turn => turn.key).sort(), expected.sort()), "role case/arm coverage differs");
+        for (const turn of record.turns) {
+            const task = CORPUS.cases.find(task => task.id === turn.task);
+            demand(turn.role === role && task.role === role && turn.key === `${turn.task}-${turn.arm}` && turn.effort === (turn.arm === "a" ? null : "medium"), "role/arm changed");
+            checkCall(turn, capture.model, ids, contexts, true);
+            demand(turn.instrumentSha256 === capture.instruments[turn.key === repair.retainedKey ? "firstOutcome" : "continuation"].sha256, "quality instrument attribution differs");
+            const actual = grade(task, turn.answer);
+            demand(same(actual, turn.regraded ?? turn.grade), "stored semantic grade differs");
+            if (turn.key === repair.retainedKey) demand(turn.grade.ok === false && turn.regraded?.ok === true, "original failed decode score was overwritten");
+            else demand(!Object.hasOwn(turn, "regraded"), "an unapproved outcome was regraded");
+            if (turn.arm === "a") demand(actual.ok, "a failed control earns no routing");
+            all.push(turn);
+        }
+        demand(same(record.summary, summarize(record)), "stored role summary differs");
+    }
+    const expectedOrder = CORPUS.cases.flatMap((task, index) => (index % 2 === 0 ? ["a", "b"] : ["b", "a"]).map(arm => `${task.id}-${arm}`));
+    demand(same(capture.order, expectedOrder), "frozen acquisition order changed");
+    const chronological = all.sort((a, b) => Date.parse(a.started) - Date.parse(b.started));
+    demand(same(capture.publication?.normalizedAnswers, chronological.filter(turn => turn.answerNormalized).map(turn => turn.key)), "normalized answer disclosure differs");
+    demand(same(chronological.map(turn => turn.key), expectedOrder), "turns did not run in frozen order");
+    demand(Date.parse(capture.qualityFrozenAt) <= Date.parse(chronological[0].started) && Date.parse(capture.continuationFrozenAt) >= Date.parse(chronological[0].ended) && Date.parse(capture.continuationFrozenAt) <= Date.parse(chronological[1].started), "freeze/repair timing differs from the disclosed sequence");
+    const calls = [...capture.preflights, ...chronological];
+    demand(calls.every((call, index) => index === 0 || Date.parse(call.started) >= Date.parse(calls[index - 1].ended)), "fresh calls overlap or probes were reordered");
+    const requests = capture.preflights.flatMap(call => [...call.usage.parent, ...call.usage.child]).length + all.flatMap(call => [...call.usage.parent, ...call.usage.child]).length;
+    demand(capture.accounting.requests === requests && capture.accounting.calls === 20 && capture.accounting.qualityChildren === 18 && capture.accounting.parentContexts === 20, "usage accounting is incomplete");
+    return { roles: ROLES.length, qualityChildren: all.length, requests, overhead: capture.preflights.map(costOf) };
+}
+
+export function verifyCapture(root, expectedDigest = CAPTURE_SHA256) {
+    const bytes = fs.readFileSync(path.join(root, CAPTURE));
+    demand(sha(bytes) === expectedDigest, "acquisition digest changed");
+    const capture = JSON.parse(bytes), directory = path.dirname(path.join(root, CAPTURE));
+    const records = {};
+    for (const role of ROLES) {
+        const file = `${role}.json`, data = fs.readFileSync(path.join(directory, file));
+        demand(sha(data) === capture.files[file], `${role} record digest changed`);
+        records[role] = JSON.parse(data);
+        demand(fs.readFileSync(path.join(directory, `${role}.md`), "utf8") === register(records[role]), `${role} register differs`);
+    }
+    const sources = ["evals/ab/personas/corpus.json", "evals/ab/personas/grader.mjs", ...ROLES.map(role => `core/personas/${role}.md`)];
+    demand(same(Object.keys(capture.sources ?? {}).sort(), sources.sort()), "required source roster differs");
+    for (const [file, expected] of Object.entries(capture.sources)) demand(sha(fs.readFileSync(path.join(root, file))) === expected, `source differs: ${file}`);
+    const old = fs.readFileSync(path.join(directory, "repairs/grader-before-decode-repair.mjs.txt"), "utf8");
+    const current = fs.readFileSync(path.join(directory, "grader.mjs"), "utf8");
+    demand(sha(old) === capture.decodeRepair.previousGrader && sha(current) === capture.decodeRepair.grader, "decoder versions differ");
+    const suffix = text => text.slice(text.indexOf("function codeCases"));
+    demand(suffix(old) === suffix(current) && sha(suffix(current)) === capture.decodeRepair.semanticSuffixSha256, "repair changed semantic predicates or pricing");
+    const first = records.implementer.turns.find(turn => turn.key === capture.decodeRepair.retainedKey);
+    demand(fs.readFileSync(path.join(directory, "repairs/first-control-answer.txt"), "utf8") === first.answer + "\n", "retained first answer differs");
+    for (const [key, name] of Object.entries({ firstProbe: "first-probe", secondProbe: "second-probe", firstOutcome: "first-outcome", continuation: "continuation", publisher: "publisher" })) {
+        demand(sha(fs.readFileSync(path.join(directory, `protocol/${name}.mjs.txt`))) === capture.instruments[key].sha256, "instrument snapshot differs");
+    }
+    for (const role of ROLES) {
+        const source = fs.readFileSync(path.join(root, `core/personas/${role}.md`), "utf8");
+        const header = source.split("---")[1];
+        demand(/^model: inherit$/m.test(header) && !/^effort:/m.test(header) && /^omitClaudeMd: false$/m.test(header) && /^cacheLifetime: 5m$/m.test(header), "shipped source routing differs");
+        const binding = fs.readFileSync(path.join(directory, `bindings/${role}.txt`));
+        demand(sha(binding) === capture.bindings[role], "captured binding differs");
+        const installed = path.join(root, `agents/${role}.md`);
+        if (fs.existsSync(installed)) demand(bindingContract(fs.readFileSync(installed, "utf8")) === bindingContract(binding.toString("utf8")), "shipped plugin binding differs outside its description");
+    }
+    return verifyData(capture, records);
+}
+
+export function run(argv = process.argv.slice(2)) {
+    try {
+        if (argv.length && !(argv.length === 2 && argv[0] === "--repo-root")) throw Error("usage: node cli/persona-routing.mjs [--repo-root <dir>]");
+        const result = verifyCapture(path.resolve(argv[1] ?? "."));
+        console.log(`persona-routing: ${result.roles} acquired role records, ${result.qualityChildren} quality children and ${result.requests} accounted requests; shipped policy matches`);
+        return 0;
+    } catch (error) { console.error(`persona-routing: ${error.message}`); return error instanceof Finding ? 1 : 2; }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) process.exitCode = run();

package/cli/plugin-lint.mjs

@@ -11,6 +11,9 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { HOST_SKILL_DEPTH, skillsSet, canonical } from "./skills-set.mjs";
+import { parseFrontmatter } from "./frontmatter.mjs";
+export { parseFrontmatter };
+import { packContributions, personaDeclarations } from "./compile.mjs";
 
 /** Raised when `plugin-lint` cannot run at all. Always exit 2, never 1. */
 export class PluginLintError extends Error {
@@ -25,7 +28,6 @@ const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 // 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"];
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const BLOCK_SCALAR = /^[|>][+-]?$/;
 
 const PATH_FIELDS = [
     "skills",
@@ -44,46 +46,6 @@ const SKIP_DIRS = new Set([".git", "node_modules", ".claude-plugin"]);
 export const AGENT_DIR = "agents";
 const MAX_WALK_DEPTH = 6;
 
-// ===========================================================================================
-// Frontmatter
-// ===========================================================================================
-
-/** 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 };
-
-    const close = lines.indexOf("---", 1);
-    if (close === -1) {
-        return { fields: null, error: "the frontmatter block is never closed" };
-    }
-
-    const fields = {};
-    const body = lines.slice(1, close);
-    for (let i = 0; i < body.length; i += 1) {
-        const match = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(body[i]);
-        if (!match) continue;
-        const key = match[1];
-        let value = match[2].trim();
-
-        if (BLOCK_SCALAR.test(value)) {
-            const collected = [];
-            while (i + 1 < body.length && (body[i + 1].trim() === "" || /^\s+/.test(body[i + 1]))) {
-                i += 1;
-                collected.push(body[i].trim());
-            }
-            value = collected.join(" ").trim();
-        } else if (
-            (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
-            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
-        ) {
-            value = value.slice(1, -1);
-        }
-        fields[key] = value;
-    }
-    return { fields };
-}
-
 // ===========================================================================================
 // Inspection
 // ===========================================================================================
@@ -91,7 +53,7 @@ export function parseFrontmatter(text) {
 /** 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);
+    return inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside);
 }
 
 /** Throws PluginLintError only when the root is not a readable directory; `payload` excuses an absent marketplace.json. */
@@ -119,10 +81,21 @@ export function inspect(rawRoot, { payload = false } = {}) {
     const fail = (check, message) => findings.push({ severity: "fail", check, message });
     const note = (check, message) => findings.push({ severity: "note", check, message });
 
+    const ownedText = (file, scope = root) => {
+        const realScope = fs.realpathSync(scope), real = fs.realpathSync(file);
+        if (escapes(root, realScope) || escapes(realScope, real)) throw Error(`${file} resolves outside its bundled owner`);
+        if (!fs.statSync(real).isFile()) throw Error(`${file} is not a regular source file`);
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(real));
+    };
+    const ownedJson = (file, scope = root) => {
+        const value = JSON.parse(ownedText(file, scope));
+        if (value === null || typeof value !== "object" || Array.isArray(value)) throw Error(`${file} is not a JSON object`);
+        return value;
+    };
     /** Never throws: a failed read becomes a finding and returns null. */
     const read = (file, check, label) => {
         try {
-            return fs.readFileSync(file, "utf8");
+            return ownedText(file);
         } catch (error) {
             fail(check, `${label} could not be read — ${error.code ?? error.message}`);
             return null;
@@ -420,7 +393,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
     let composition;
     let composable = true;
     try {
-        composition = JSON.parse(fs.readFileSync(path.join(root, GOVERNING), "utf8"));
+        composition = JSON.parse(ownedText(path.join(root, GOVERNING), path.join(root, ".portulan")));
     } catch (error) {
         if (error.code === "ENOENT") composable = false;
         else {
@@ -550,7 +523,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         for (const { name, dir } of composed) {
             let text;
             try {
-                text = fs.readFileSync(path.join(dir, "pack.json"), "utf8");
+                text = ownedText(path.join(dir, "pack.json"), dir);
             } catch (error) {
                 if (error.code === "ENOENT") continue;
                 fail(
@@ -616,8 +589,8 @@ export function inspect(rawRoot, { payload = false } = {}) {
     for (const stranded of walkForStrandedAgents(root)) {
         note(
             "agents",
-            `${path.relative(root, stranded)} is not in ./${AGENT_DIR}/, the only directory the host ` +
-                "loads agents from — it will not load",
+            `${path.relative(root, stranded)} is not in ./${AGENT_DIR}/, this plugin's agent directory — ` +
+                "it will not load as a plugin binding",
         );
     }
 
@@ -703,28 +676,77 @@ export function inspect(rawRoot, { payload = false } = {}) {
     // 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;
+    let corePresent = false;
     try {
+        fs.lstatSync(personaDir);
+        corePresent = true;
+        if (escapes(root, fs.realpathSync(personaDir))) throw Error("core/personas/ resolves outside the plugin");
         personaFiles = fs
             .readdirSync(personaDir)
             .filter((entry) => entry.endsWith(".md") && entry !== "README.md")
             .map((entry) => path.basename(entry, ".md"))
             .sort();
     } catch (error) {
-        if (error.code !== "ENOENT") fail("agents", `core/personas/ could not be read — ${error.code ?? error.message}, so the binding correspondence went unchecked`);
+        if (error.code !== "ENOENT" || corePresent) fail("agents", `core/personas/ could not be read — ${error.code ?? error.message}, so the binding correspondence went unchecked`);
+    }
+    const owners = new Map();
+    for (const name of personaFiles ?? []) {
+        const source = `core/personas/${name}.md`;
+        try { ownedText(path.join(root, source)); owners.set(name, source); }
+        catch (error) { fail("agents", `${source} could not be read — ${error.message}`); }
+    }
+    let composedDeclared = false;
+    const workspaceFile = path.join(root, ".portulan/workspace.json");
+    let workspacePresent = false;
+    try {
+        fs.lstatSync(workspaceFile);
+        workspacePresent = true;
+        const workspace = ownedJson(workspaceFile, path.dirname(workspaceFile));
+        if (workspace?.packs !== undefined && !Array.isArray(workspace.packs)) throw Error("workspace packs is not an array");
+        composedDeclared = (workspace?.packs?.length ?? 0) > 0;
+        if (composedDeclared) {
+            for (const ref of workspace.packs) {
+                if (typeof ref !== "string" || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(ref)) throw Error("a composed pack reference is malformed");
+                const packsRoot = fs.realpathSync(path.join(root, "packs"));
+                const packDir = fs.realpathSync(path.join(root, "packs", ref));
+                if (escapes(root, packsRoot) || escapes(packsRoot, packDir)) throw Error(`${ref} resolves outside its bundled packs root`);
+                const pack = ownedJson(path.join(packDir, "pack.json"), packDir);
+                if (pack.contributes !== undefined && (pack.contributes === null || typeof pack.contributes !== "object" || Array.isArray(pack.contributes))) throw Error(`${ref} contributes is not a mapping`);
+            }
+            const composed = packContributions(root, ".portulan", { packRoots: [path.join(root, "packs")] });
+            if (composed.unresolved.length) throw Error(`unresolved persona owners: ${composed.unresolved.map(pack => pack.name).join(", ")}`);
+            for (const contribution of composed.contributions) {
+                for (const rel of contribution.personas) {
+                    if (typeof rel !== "string" || !rel.trim()) throw Error("a composed persona path is not a nonempty string");
+                    const file = path.resolve(contribution.dir, rel);
+                    if (escapes(contribution.dir, file)) throw Error(`${contribution.pack}'s ${rel} resolves outside its bundled pack`);
+                    const source = `${contribution.pack}'s ${rel}`;
+                    const parsed = personaDeclarations(ownedText(file, contribution.dir));
+                    if (parsed.problems.length) throw Error(`${source}: ${parsed.problems.join("; ")}`);
+                    const name = parsed.name ?? path.basename(rel, ".md");
+                    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) throw Error(`${source} has no usable binding name`);
+                    if (owners.has(name)) throw Error(`${name} has multiple persona owners: ${owners.get(name)} and ${source}`);
+                    owners.set(name, source);
+                }
+            }
+        }
+    } catch (error) {
+        if (error.code !== "ENOENT" || workspacePresent) fail("agents", `composed persona ownership could not be read — ${error.code ?? error.message}`);
     }
-    if (personaFiles && !agentsExamined) {
+    const correspondence = personaFiles !== null || composedDeclared;
+    if (correspondence && !agentsExamined) {
         note(
             "agents",
             `the persona↔binding correspondence went unchecked — ./${AGENT_DIR}/ could not be examined, so an empty binding set is a ` +
-                `question nobody answered rather than ${personaFiles.length} persona(s) with nothing bound to them`,
+                `question nobody answered rather than ${owners.size} persona(s) with nothing bound to them`,
         );
-    } else if (personaFiles) {
-        for (const persona of personaFiles) {
+    } else if (correspondence) {
+        for (const [persona, source] of owners) {
             const binding = bindings.get(persona);
             if (!binding) {
                 fail(
                     "agents",
-                    `core/personas/${persona}.md has no binding at ./${AGENT_DIR}/${persona}.md — a persona this plugin ships and does not bind ` +
+                    `${source} has no binding at ./${AGENT_DIR}/${persona}.md — a persona this plugin ships and does not bind ` +
                         `is doctrine the host never registers, which looks from the outside exactly like a role that is available`,
                 );
                 continue;
@@ -732,14 +754,13 @@ export function inspect(rawRoot, { payload = false } = {}) {
             if (binding.name !== undefined && binding.name !== persona) {
                 fail(
                     "agents",
-                    `${binding.rel} binds \`core/personas/${persona}.md\` by its filename while declaring \`name: ${binding.name}\` — the host keys ` +
+                    `${binding.rel} binds \`${source}\` by its filename while declaring \`name: ${binding.name}\` — the host keys ` +
                         `on the field, so the two disagree about which role this file registers`,
                 );
             }
         }
-        const personaNames = new Set(personaFiles);
         for (const [name, binding] of bindings) {
-            if (!personaNames.has(name)) {
+            if (!owners.has(name)) {
                 fail(
                     "agents",
                     `${binding.rel} binds no persona — there is no \`core/personas/${name}.md\`. A host file that outlived the doctrine it was ` +

package/cli/portulan.mjs

@@ -23,7 +23,7 @@ export const SUBCOMMANDS = [
     {
         name: "doctor",
         module: "doctor.mjs",
-        summary: "validate a workspace against the Workspace Definition",
+        summary: "validate a workspace and report branch-owned host tokens beside local receipts; --static skips usage records",
     },
     {
         name: "compile",