@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/compile.mjs

@@ -6,24 +6,25 @@
 //
 // Exit 0 wrote (or, with --check, agrees) · 1 an artifact has drifted · 2 could not run.
 
+import { readContextCap, contextCaps, contextCapLines, capOnlyPlan, emitCapOnly, CONTEXT_CAP_ENV } from "./ritual-contexts.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { AUTO, discoverPackRoots, namedWithAuto, resolutionRoots } from "./discover.mjs";
 import { isInside } from "./inside.mjs";
+import { importTargetIsFile } from "./import-files.mjs";
+export { importTargetIsFile } from "./import-files.mjs";
+import { parseFrontmatter } from "./frontmatter.mjs";
 import { CannotOutline, sectionOf } from "./symbols.mjs";
 import { HORIZON, LedgerError, readSpend } from "./ledger.mjs";
+import { readStopPolicy, STOP_HOOK_MARGIN } from "./stop-policy.mjs";
+import { assertSourceJournalReady } from "./instructions-journal.mjs";
 
-/** Raised when `compile` cannot run, or cannot compile honestly. Always exit 2, never 1. */
-export class CompileError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "CompileError";
-    }
-}
+import { CompileError, readOwnedBytes, readOwnedText, sameContent, nestedTarget, nestedMark, validateNestedTargets, workspaceProtection, nestedPlan, applyNestedEdits, preflightNestedEdits, NESTED_REGISTRY, readNestedState, ownedNestedFiles } from "./guidance-files.mjs";
+export { CompileError, readOwnedBytes, readOwnedText, NESTED_REGISTRY, readNestedState, ownedNestedFiles };
 
 /** 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 +132,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 +181,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
@@ -532,6 +537,8 @@ export const HOOK_RUNNERS = ["gate.mjs", "stop-gate.mjs", "advisory.mjs"];
  * `ask` for gated, a prompt that blocks headless. Two layers, since on Claude Code 2.1.220 a crashing hook fails open.
  */
 export function claudeCode(parsed, options = {}) {
+    const hasPolicy = parsed !== null;
+    const rules = hasPolicy ? parsed.rules : [];
     const source = options.source ?? ".portulan/gates.json";
     const runnerDir = path.dirname(fileURLToPath(import.meta.url));
     const project = options.root ?? process.cwd();
@@ -545,8 +552,8 @@ export function claudeCode(parsed, options = {}) {
         pinned.push({ file, abs });
         return `"${abs}"`;
     };
-    const runner = options.runner ?? spell(HOOK_RUNNERS[0]);
-    const stopRunner = options.stopRunner ?? spell(HOOK_RUNNERS[1]);
+    const runner = options.runner ?? (hasPolicy ? spell(HOOK_RUNNERS[0]) : null);
+    const stopRunner = options.stopRunner ?? (hasPolicy ? spell(HOOK_RUNNERS[1]) : null);
     const advisoryRunner = options.advisoryRunner ?? spell(HOOK_RUNNERS[2]);
 
     const compiled = [];
@@ -557,7 +564,7 @@ export function claudeCode(parsed, options = {}) {
     const shellWriteGates = [];
     const editCoveredGates = [];
 
-    for (const rule of parsed.rules) {
+    for (const rule of rules) {
         if (!HOST_GATE_TIERS.has(rule.tier)) {
             refused.push({ id: rule.id, tier: rule.tier, why: HOST_TIER_NOT_A_GATE[rule.tier] });
             continue;
@@ -605,16 +612,17 @@ export function claudeCode(parsed, options = {}) {
         compiled.push({ id: rule.id, tier: rule.tier, surface: [...emitted, ...hookOnly].join(" · ") });
     }
 
-    if (parsed.rules.some((r) => HOST_GATE_TIERS.has(r.tier)) && compiled.length === 0) {
+    if (rules.some((r) => HOST_GATE_TIERS.has(r.tier)) && compiled.length === 0) {
         throw new CompileError(
             "every gate in this policy refused to compile — refusing to write an artifact that enforces nothing while the policy claims gates",
         );
     }
 
-    // Each pack's origin and version, never its root: an absolute path would make the tracked artifact differ per machine.
+    // Portable provenance excludes absolute roots.
     const packs = (options.packProvenance ?? [])
         .map((c) => ({ pack: c.pack, origin: c.origin, version: c.version ?? null }))
         .sort((a, b) => a.pack.localeCompare(b.pack));
+    const contexts = options.contexts ?? contextCaps([]);
     const sessions = options.sessions ?? null;
     const switches = {};
     if (sessions?.git_instructions !== undefined) switches.includeGitInstructions = sessions.git_instructions;
@@ -624,48 +632,61 @@ export function claudeCode(parsed, options = {}) {
     const figures = [];
     if (spend?.multipliers) figures.push("--read", spend.multipliers.read, "--write-5m", spend.multipliers.write["5m"], "--write-1h", spend.multipliers.write["1h"]);
     if (spend?.horizon) figures.push("--horizon", spend.horizon);
+    if (spend?.resume != null) figures.push("--resume-tokens", spend.resume);
     const spendFlags = figures.map((f) => ` ${f}`).join("");
     const restartBlock = spend?.restart === "block";
     const spendFrom = figures.length || restartBlock ? spend.manifest : null;
-    const declaredIn =
+    const figuresIn =
         sessionsFrom && sessionsFrom === spendFrom
             ? `\`sessions\` and \`spend\` in ${sessionsFrom}`
             : [sessionsFrom && `\`sessions\` in ${sessionsFrom}`, spendFrom && `\`spend\` in ${spendFrom}`].filter(Boolean).join(", or ");
+    const stopPolicy = hasPolicy ? options.stopPolicy ?? null : null;
+    if (stopPolicy !== null) {
+        try {
+            const seconds = typeof stopPolicy === "object" && !Array.isArray(stopPolicy) ? stopPolicy.seconds : null;
+            readStopPolicy({ portulan: { spec: "2.14" }, verify: { stopTimeout: seconds ?? null } });
+        } catch (error) { throw new CompileError(error.message); }
+    }
+    const declaredIn = [figuresIn, contexts.limit !== null && "ritual contexts in composed pack manifests", stopPolicy && `\`verify.stopTimeout\` in ${stopPolicy.manifest}`].filter(Boolean).join(", or ");
     const value = {
         $portulan: {
             generated: "cli/compile.mjs",
             source,
             ...(sessionsFrom ? { sessions: sessionsFrom } : {}),
             ...(spendFrom ? { spend: spendFrom } : {}),
+            ...(stopPolicy ? { verify: stopPolicy.manifest } : {}),
             ...(packs.length ? { packs } : {}),
+            ...(contexts.limit !== null ? { contexts: contexts.sources } : {}),
             warning: declaredIn
                 ? `Generated file. Edit ${source}, or ${declaredIn}, and recompile; \`verify/compile.sh\` fails on drift.`
                 : `Generated file. Edit ${source} and recompile; \`verify/compile.sh\` fails on drift.`,
         },
-        permissions: { deny, ask, allow: [] },
+        ...(hasPolicy ? { permissions: { deny, ask, allow: [] } } : {}),
         hooks: {
-            // Each command is `node` and a quoted path: no pipe, redirection or separator, where a quoting fail-open would live.
-            PreToolUse: [...matchers].sort().map((matcher) => ({
-                matcher,
-                hooks: [{ type: "command", command: `node ${runner}` }],
-            })),
-            Stop: [
-                {
-                    hooks: [
-                        { type: "command", command: `node ${stopRunner}` },
-                        ...(restartBlock ? [{ type: "command", command: `node ${advisoryRunner} stop${spendFlags}` }] : []),
-                    ],
-                },
-            ],
+            ...(hasPolicy ? {
+                PreToolUse: [...matchers].sort().map((matcher) => ({
+                    matcher,
+                    hooks: [{ type: "command", command: `node ${runner}` }],
+                })),
+            } : {}),
+            ...(hasPolicy || restartBlock ? { Stop: [{ hooks: [
+                ...(hasPolicy ? [{ type: "command", command: `node ${stopRunner}`, ...(stopPolicy ? { timeout: stopPolicy.seconds + STOP_HOOK_MARGIN } : {}) }] : []),
+                ...(restartBlock ? [{ type: "command", command: `node ${advisoryRunner} stop${spendFlags}` }] : []),
+            ] }] } : {}),
             // No matcher means every tool; a non-blocking `Stop` hook's output would reach only the host's debug log.
             PostToolUse: [{ hooks: [{ type: "command", command: `node ${advisoryRunner} tool${spendFlags}` }] }],
             UserPromptSubmit: [{ hooks: [{ type: "command", command: `node ${advisoryRunner} prompt${spendFlags}` }] }],
         },
         statusLine: { type: "command", command: `node ${advisoryRunner} status${spendFlags}` },
         ...switches,
+        ...(contexts.limit !== null ? { env: { [CONTEXT_CAP_ENV]: String(contexts.limit) } } : {}),
     };
 
-    const notes = [];
+    const notes = contextCapLines(contexts);
+    if (!hasPolicy) notes.push(
+        "Claude Code: prompt/tool restart advisory and status line compile without a gate policy; declared session switches and ritual caps compose here. GitHub repository ruleset and AGENTS guidance: advisory/session settings not compiled by these adapters.",
+        `Undeclared prices use general read 0.1× and writes 1.25×/2×; horizon ${spend?.horizon ? `${spend.horizon} declared` : `${HORIZON} general`}; resume expense ${spend?.resume != null ? `${spend.resume} declared` : "unknown"}. Unknown resume expense or a general horizon permits conditional advice, never a Stop hold.`,
+    );
     if (pinned.length) {
         notes.push(
             `${pinned.length} hook(s) are pinned to an ABSOLUTE path on this machine — ` +
@@ -715,11 +736,12 @@ export function claudeCode(parsed, options = {}) {
                 `commands carry them, so an edit to \`spend\` is drift until recompiled`,
         );
     }
+    if (spend?.resume != null) notes.push(`restart resume expense: ${spend.resume} input-equivalent tokens, excluding the fresh-context write and baseline reads`);
     if (restartBlock) {
         notes.push(
-            `the restart advisory also holds a turn's end (\`spend.restart\` "block"): at the first stop at or past the restart ` +
-                `threshold that no block provoked, once in a session and again after each compaction, with the line as the reason, beside the Stop-gate. Nothing ends the ` +
-                `session, and the line still comes with a tool result or at the prompt`,
+            `the restart advisory's Stop command (\`spend.restart\` "block") holds once only with an explicit horizon, an explicit resume expense ` +
+                `and finite positive estimated savings; equality never holds. Without both estimates it reports conditionally without holding. ` +
+                `Retry protection and once per compaction still apply; nothing ends the session`,
         );
     }
     if (editCoveredGates.length) {
@@ -811,8 +833,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,
             },
@@ -988,7 +1009,7 @@ export const GUIDANCE_HOSTS = {
     "claude-code": {
         label: "Claude Code",
         always: `an unscoped rule in \`${GUIDANCE_RULES_DIR}/\``,
-        "on-path": "a rule scoped by `paths:`",
+        "on-path": "a paths-scoped rule or a declared nested CLAUDE.md",
         "on-invoke": `a project skill in \`${SKILLS_DIR}/\``,
         "on-read": `a line in \`${GUIDANCE_RULES_DIR}/${ON_READ_INDEX}\``,
     },
@@ -1029,11 +1050,148 @@ const STRAY_IMPORT = {
     "on-read": "an on-read file is opened as it stands, so the import would load nothing",
 };
 
-/**
- * The `@` imports Claude Code 2.1.281 finds: none in a fence, nor in a code span or HTML comment outside a list
- * item's text, which it reads raw. Misread: a list in a block quote, and a line its lexer keeps out of an item.
- */
+function importCandidate(text) {
+    return [...text.matchAll(/@((?:[^\s\\]|\\ )+)/g)].some(match =>
+        !/[\p{L}\p{N}.+-]/u.test(text[match.index - 1] ?? " ") && importPath(match[1]) !== null);
+}
+
+function importSyntax(text) {
+    const rows = text.split("\n");
+    const starts = [];
+    let offset = 0;
+    for (const row of rows) { starts.push(offset); offset += row.length + 1; }
+    const width = (prefix) => [...prefix].reduce((col, char) => col + (char === "\t" ? 4 - col % 4 : 1), 0);
+    const refuse = (name, region, i) => {
+        if (importCandidate(region)) throw new CompileError(`unsupported import syntax: ${name} at line ${i + 1}; put the import alone in a supported paragraph`);
+    };
+    let fence = null;
+    let comment = false;
+    let quotedList = null;
+    let list = null;
+    let flowing = false;
+    for (let i = 0; i < rows.length; i++) {
+        let line = rows[i].replace(/\r$/, "");
+        let shift = 0;
+        if (fence) {
+            if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}[ \\t]*$`).test(line)) fence = null;
+            continue;
+        }
+        if (comment) {
+            const end = line.indexOf("-->");
+            if (end === -1) continue;
+            comment = false;
+            shift = end + 3;
+            line = line.slice(shift);
+        }
+        const trim = line.trimStart();
+        const indent = width(/^[ \t]*/.exec(line)[0]);
+        const regionThrough = (stop) => [line, ...rows.slice(i + 1, stop)].join("\n");
+        const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (opening && !(opening[1][0] === "`" && opening[2].includes("`"))) {
+            fence = opening[1];
+            quotedList = null;
+            flowing = false;
+            continue;
+        }
+        let quoted = line;
+        let outerItem;
+        while ((outerItem = /^ {0,3}(?:[-+*]|\d{1,9}[.)])(?:[ \t]+|$)/.exec(quoted))) quoted = quoted.slice(outerItem[0].length);
+        let depth = 0;
+        let prefix;
+        while ((prefix = /^ {0,3}>[ \t]?/.exec(quoted))) { depth++; quoted = quoted.slice(prefix[0].length); }
+        const quotedItem = /^ {0,3}(?:[-+*]|\d{1,9}[.)])(?:[ \t]+|$)/.exec(quoted);
+        if (depth && quotedItem) {
+            quotedList = { depth, indent: width(quotedItem[0]), flowing: !opensBlock(quoted.slice(quotedItem[0].length)) };
+            refuse("blockquoted list", quoted, i);
+        } else if (quotedList) {
+            const contained = depth > quotedList.depth || (depth === quotedList.depth && width(/^[ \t]*/.exec(quoted)[0]) >= quotedList.indent);
+            if (quoted.trim() === "") {
+                if (depth < quotedList.depth) quotedList = null;
+                else quotedList.flowing = false;
+            }
+            else if (contained || (quotedList.flowing && !opensBlock(quoted))) {
+                refuse("blockquoted list", quoted, i);
+                quotedList.flowing = !opensBlock(quoted.trimStart());
+            } else quotedList = null;
+        }
+        const item = /^([ \t]*)([-+*]|\d{1,9}[.)])([ \t]+|$)/.exec(line);
+        if (item && (list || indent <= 3)) {
+            if (list && indent >= list.indent) list.reason = "list after nested list";
+            else list = { indent: width(item[0]), reason: null };
+            flowing = true;
+        } else if (line.trim() === "") {
+            flowing = false;
+        } else if (list && (indent >= list.indent || (flowing && !opensBlock(line)))) {
+            flowing = true;
+        } else {
+            list = null;
+            flowing = false;
+        }
+        if (list && flowing) {
+            const content = item ? line.slice(item[0].length) : trim;
+            if (OPENS_HTML_BLOCK.test(content) || /^<(?:\?|!\[CDATA\[|![A-Z])/.test(content)) list.reason = "list after HTML block";
+            else if ((item || indent >= list.indent) && /^<\/?[A-Za-z]/.test(content)) list.reason = "list after tag";
+            else if (!item && indent >= list.indent + 4) list.reason = "list after indented code";
+            if (list.reason && !item) refuse(list.reason, line, i);
+            continue;
+        }
+        const deepFence = /^(?: {4,}|[ \t]*\t[ \t]*)(`{3,}|~{3,})/.exec(line);
+        if (deepFence) {
+            let end = i + 1;
+            while (end < rows.length && !new RegExp(`^[ \\t]*${deepFence[1][0]}{${deepFence[1].length},}[ \\t]*$`).test(rows[end])) end++;
+            refuse("indented fence", regionThrough(Math.min(end + 1, rows.length)), i);
+            i = Math.min(end, rows.length - 1);
+            continue;
+        }
+        if (indent >= 4) { refuse("indented code", line, i); continue; }
+        let htmlEnd = null;
+        const raw = /^<(pre|script|style|textarea)(?=[ \t>]|$)/i.exec(trim);
+        if (raw) htmlEnd = new RegExp(`</${raw[1]}[ \\t]*>`, "i");
+        else if (/^<\?/.test(trim)) htmlEnd = /\?>/;
+        else if (/^<!\[CDATA\[/.test(trim)) htmlEnd = /\]\]>/;
+        else if (/^<![A-Z]/.test(trim)) htmlEnd = />/;
+        const html = htmlEnd || OPENS_HTML_BLOCK.test(trim) ||
+            ((i === 0 || rows[i - 1].trim() === "") && /^<\/?[A-Za-z][^<>]*>[ \t]*$/.test(trim));
+        if (html) {
+            let end = i;
+            while (end < rows.length && (htmlEnd ? !htmlEnd.test(end === i ? line : rows[end]) : (end === i ? line : rows[end]).trim() !== "")) end++;
+            const stop = htmlEnd ? Math.min(end + 1, rows.length) : end;
+            refuse("HTML block", regionThrough(stop), i);
+            i = Math.max(i, stop - 1);
+            continue;
+        }
+        let masked = line;
+        const ticks = [...line.matchAll(/`+/g)];
+        for (let k = 0; k < ticks.length; k++) {
+            const tick = ticks[k];
+            const absolute = starts[i] + shift + tick.index;
+            const rest = text.slice(absolute + tick[0].length).split(/\n[ \t]*\n/, 1)[0];
+            const close = [...rest.matchAll(/`+/g)].find(next => next[0] === tick[0]);
+            if (!close) continue;
+            const region = rest.slice(0, close.index);
+            if (region.includes("\n")) refuse("multiline code span", region, i);
+            else {
+                if (line.includes("<!--")) refuse("comment-opening line", region, i);
+                const end = tick.index + tick[0].length * 2 + close.index;
+                masked = masked.slice(0, tick.index) + " ".repeat(end - tick.index) + masked.slice(end);
+                while (k + 1 < ticks.length && ticks[k + 1].index < end) k++;
+            }
+        }
+        masked = masked.replace(/<!--.*?(?:-->|$)/g, match => " ".repeat(match.length));
+        for (const [name, pattern] of [
+            ["emphasis adjacency", /[*_]@((?:[^\s\\]|\\ )+)/g],
+            ["escape adjacency", /\\[!-/:-@[-`{-~]@((?:[^\s\\]|\\ )+)/g],
+            ["tag adjacency", />@((?:[^\s\\]|\\ )+)/g],
+        ]) for (const match of masked.matchAll(pattern)) if (importPath(match[1]) !== null) {
+            throw new CompileError(`unsupported import syntax: ${name} at line ${i + 1}; put the import alone in a supported paragraph`);
+        }
+        if (line.includes("<!--") && !line.slice(line.indexOf("<!--") + 4).includes("-->")) comment = true;
+    }
+}
+
+/** Proven import forms; ambiguous Markdown regions fail closed before offsets are read. */
 export function importSpans(text) {
+    importSyntax(text);
     const found = [];
     let fence = null;
     let comment = false;
@@ -1060,7 +1218,7 @@ export function importSpans(text) {
             } else if (item && (listed || /^ {0,3}\S/.test(line))) {
                 listed = flowing = true;
                 raw = !opensInItem.test(line.slice(item[0].length));
-            } else if (listed && (/^\s/.test(line) || (flowing && !OPENS_BLOCK.test(line)))) {
+            } else if (listed && (/^\s/.test(line) || (flowing && !opensBlock(line)))) {
                 flowing = true;
                 raw = !opensInItem.test(line.trimStart());
             } else {
@@ -1158,8 +1316,13 @@ function checkedImports(text, dir, root, where) {
     return own;
 }
 
-/** An unindented line that ends a list, as CommonMark reads it; a block tag such as `<div>` is read as a lazy line. */
 const OPENS_BLOCK = /^(?:#{1,6}(?:[ \t]|$)|>|([-*_])(?:[ \t]*\1){2,}[ \t]*$|(?:[-+*]|\d{1,9}[.)])(?:[ \t]|$)|<(?:!--|\?|![A-Za-z]|!\[CDATA\[))/;
+const OPENS_HTML_BLOCK = /^<(?:(?:pre|script|style|textarea)(?=[ \t>]|$)|\/?(?:address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[1-6]|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)(?=[ \t>]|\/>|$))/i;
+
+/** An unindented line that ends a list, as CommonMark reads it. */
+function opensBlock(line) {
+    return OPENS_BLOCK.test(line) || OPENS_HTML_BLOCK.test(line);
+}
 
 /** Each item's first sentence, byte for byte, from the first list in `file` or under its `#fragment` heading. */
 function leadsOf(file, where, fragment = null, name = path.basename(file)) {
@@ -1197,7 +1360,7 @@ export function leadsOfText(source, name, where) {
         } else if (kind !== null && /^\s+\S/.test(line)) {
             items.at(-1).text += ` ${line.trim()}`;
         } else if (kind !== null && line.trim() !== "") {
-            if (under && !OPENS_BLOCK.test(line)) {
+            if (under && !opensBlock(line)) {
                 throw new CompileError(
                     `${where}: line ${at + 1} of ${name} follows an item of its first list with no blank line and no indent, ` +
                         `where CommonMark reads a line of text as more of that item — indent it under the item, or end the list with a blank line`,
@@ -1249,7 +1412,7 @@ function gatesOf(file, where, packs = []) {
 }
 
 /** The unit's body with each leads, engine and gates line written out; a leads path may end `#<heading>`. */
-function expandedBody(unit, dir, root, packs = []) {
+export function expandedBody(unit, dir, root, packs = [], { originRoot = root } = {}) {
     unit.leadSources = [];
     unit.written = new Set();
     return unit.body
@@ -1259,11 +1422,13 @@ function expandedBody(unit, dir, root, packs = []) {
             const engine = leads ? null : ENGINE_LINE.exec(line);
             const gates = leads || engine ? null : GATES_LINE.exec(line);
             if (!leads && !engine && !gates) return [line];
-            if (engine) return engineLeads(unit, engine[1], root);
+            if (engine) return engineLeads(unit, engine[1], originRoot);
             const [what, spelled] = leads ? ["leads", leads[1]] : ["gates", gates[1]];
             const hash = leads ? spelled.indexOf("#") : -1;
             const [named, fragment] = hash === -1 ? [spelled, null] : [spelled.slice(0, hash), spelled.slice(hash + 1)];
-            const file = path.resolve(dir, named);
+            const file = path.isAbsolute(named) && originRoot !== root && isInside(originRoot, named)
+                ? path.resolve(root, path.relative(originRoot, named))
+                : path.resolve(dir, named);
             if (!isInside(root, file)) throw new CompileError(`${unit.source}: the ${what} of ${named} were asked for, and it lies outside the tree compiled here`);
             let real;
             try {
@@ -1304,7 +1469,7 @@ function engineLeads(unit, spelled, root) {
     return leadsOf(real, unit.source, fragment, shown).map((lead) => (own ? lead.replaceAll(PLUGIN_ROOT, "") : lead));
 }
 
-const UNIT_KEYS = new Set(["tier", "paths", "description"]);
+const UNIT_KEYS = new Set(["tier", "paths", "description", "target"]);
 
 /** A line break, by any spelling a host might honour, or another control character. */
 const CONTROL = /[\u0000-\u001f\u007f\u0085\u2028\u2029]/;
@@ -1337,7 +1502,7 @@ function unitFrontmatter(lines, where) {
         if (!match) throw new CompileError(`${where}: frontmatter line ${i + 2} is not \`key: value\` — ${JSON.stringify(line)}`);
         const [, key, rest = ""] = match;
         if (!UNIT_KEYS.has(key)) {
-            throw new CompileError(`${where}: \`${key}\` is not a key a unit takes — only \`tier\`, \`paths\` and \`description\` (spec/slots.md)`);
+            throw new CompileError(`${where}: \`${key}\` is not a key a unit takes — only \`tier\`, \`paths\`, \`target\` and \`description\` (spec/slots.md)`);
         }
         if (Object.hasOwn(fields, key)) throw new CompileError(`${where}: \`${key}\` is declared twice`);
         if (key !== "paths") {
@@ -1386,8 +1551,14 @@ export function parseUnit(name, text, source = `${name}.md`) {
     if (!LOAD_TIERS.includes(tier)) {
         throw new CompileError(`${where}: \`tier\` is ${tier === undefined ? "missing" : JSON.stringify(tier)}, and it must be one of ${LOAD_TIERS.map((t) => `\`${t}\``).join(", ")}`);
     }
-    let paths = null;
-    if (tier === "on-path") {
+    let paths = null, target = null;
+    if (fields.target !== undefined) {
+        if (tier !== "on-path") throw new CompileError(`${where}: target is valid only on-path`);
+        if (fields.paths !== undefined) throw new CompileError(`${where}: select one of paths or target, never both`);
+        target = nestedTarget(fields.target,where);
+        paths = [`${path.posix.dirname(target)}/**`];
+    }
+    if (tier === "on-path" && target === null) {
         if (fields.paths === undefined || fields.paths.length === 0) {
             throw new CompileError(`${where}: an on-path unit names the \`paths\` that load it, and this one names none`);
         }
@@ -1400,7 +1571,7 @@ export function parseUnit(name, text, source = `${name}.md`) {
             }
         }
         paths = fields.paths;
-    } else if (fields.paths !== undefined) {
+    } else if (tier !== "on-path" && fields.paths !== undefined) {
         throw new CompileError(`${where}: \`paths\` scopes an on-path unit, and this one is \`${tier}\` — a key that loads nothing is one its author believes is in force`);
     }
     let description = null;
@@ -1433,12 +1604,13 @@ export function parseUnit(name, text, source = `${name}.md`) {
     } else if (rest[0] === BOOT_CARD_LINE) {
         throw new CompileError(`${where}: \`${BOOT_CARD_LINE}\` opens the boot card, and only the unit named \`${BOOT_CARD_UNIT}\` is one — the boot skill would take this unit for the card`);
     }
+    if (target !== null && importSpans(rest.join("\n")).some(({target: spelled}) => importPath(spelled) !== null)) throw new CompileError(`${where}: nested instruction imports are not supported; put literal examples in code`);
     const written = [["leads", LEADS_LINE], ["engine", ENGINE_LINE], ["gates", GATES_LINE]].find(([, line]) => rest.some((text) => line.test(text)));
     if (tier !== "always" && written) {
         const [which] = written;
         throw new CompileError(`${where}: a \`<!-- ${which}: … -->\` line is written out only in an always unit, and this one is \`${tier}\``);
     }
-    return { name, tier, paths, description, body: `${rest.join("\n")}\n`, source, bytes: Buffer.byteLength(text, "utf8") };
+    return { name, tier, paths, ...(target === null ? {} : {target}), description, body: `${rest.join("\n")}\n`, source, bytes: Buffer.byteLength(text, "utf8") };
 }
 
 /** The declared `slots.context`, or null where none is declared or there is no manifest; one that will not parse throws. */
@@ -1453,7 +1625,7 @@ export function guidanceDeclaration(workspaceRoot, workspaceDir = ".portulan") {
     }
     let manifest;
     try {
-        manifest = JSON.parse(fs.readFileSync(path.join(base, "workspace.json"), "utf8"));
+        manifest = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir));
     } catch {
         return null;
     }
@@ -1474,11 +1646,12 @@ export function guidanceDeclaration(workspaceRoot, workspaceDir = ".portulan") {
                 `a unit there would be overwritten by what it compiles to, and \`vendor\` carries neither directory. Keep guidance in a directory of its own, such as \`context/\``,
         );
     }
-    return { dir, rel: `${rel}/`, packs: Array.isArray(manifest.packs) ? manifest.packs.filter((p) => typeof p === "string") : [] };
+    const workspace = path.relative(fs.realpathSync(workspaceRoot),fs.realpathSync(base)).split(path.sep).join("/") || ".";
+    return { dir, rel: `${rel}/`, workspace, packs: Array.isArray(manifest.packs) ? manifest.packs.filter((p) => typeof p === "string") : [] };
 }
 
 /** Every unit, read and checked, or null where no `slots.context` is declared. */
-export function guidanceUnits(workspaceRoot, workspaceDir = ".portulan") {
+export function guidanceUnits(workspaceRoot, workspaceDir = ".portulan", { originRoot = workspaceRoot } = {}) {
     const declared = guidanceDeclaration(workspaceRoot, workspaceDir);
     if (declared === null) return null;
     let entries;
@@ -1502,6 +1675,7 @@ export function guidanceUnits(workspaceRoot, workspaceDir = ".portulan") {
         }
     });
     const units = [];
+    for(const entry of entries) if(entry.name.endsWith(".md") && !entry.isDirectory() && !entry.isFile() && !entry.isSymbolicLink()) throw new CompileError(`${declared.rel}${entry.name} is not a regular guidance source`);
     const names = entries
         .filter((e) => e.name.endsWith(".md") && (e.isFile() || e.isSymbolicLink()))
         .map((e) => e.name)
@@ -1521,20 +1695,22 @@ export function guidanceUnits(workspaceRoot, workspaceDir = ".portulan") {
         }
         let text;
         try {
-            text = fs.readFileSync(full, "utf8");
+            if (!fs.statSync(full).isFile()) throw new CompileError(`${source} is not a regular guidance unit`);
+            text = readOwnedText(full,realBase);
         } catch (cause) {
             throw new CompileError(`${source} could not be read — ${cause.code ?? cause.message}`);
         }
         const unit = parseUnit(path.basename(file, ".md"), text, source);
+        unit.ownedSource = path.relative(fs.realpathSync(workspaceRoot),real).split(path.sep).join("/");
         if (unit.tier === "always") {
             unit.dir = path.dirname(full);
-            unit.text = expandedBody(unit, unit.dir, path.resolve(workspaceRoot), declared.packs);
+            unit.text = expandedBody(unit, unit.dir, path.resolve(workspaceRoot), declared.packs, { originRoot });
             unit.imports = checkedImports(unit.text, unit.dir, path.resolve(workspaceRoot), source);
         } else {
             for (const { target } of importSpans(unit.body)) {
                 const bare = importPath(target);
                 if (bare === null || bare.startsWith("~") || path.isAbsolute(bare)) continue;
-                if (fs.statSync(path.resolve(path.dirname(full), bare), { throwIfNoEntry: false })?.isFile()) {
+                if (importTargetIsFile(path.resolve(path.dirname(full), bare))) {
                     throw new CompileError(
                         `${source}: \`@${target}\` names a file, and only an always unit may import one — ${STRAY_IMPORT[unit.tier]}. ` +
                             `Name the file to open instead, in a code span`,
@@ -1544,7 +1720,12 @@ export function guidanceUnits(workspaceRoot, workspaceDir = ".portulan") {
         }
         units.push(unit);
     }
-    return { source: declared.rel, units, root: path.resolve(workspaceRoot) };
+    validateNestedTargets(units.filter(unit=>unit.target).map(unit=>unit.target));
+    for (const unit of units.filter(unit=>unit.target)) {
+        const at=path.resolve(workspaceRoot,unit.target);
+        if (units.some(other=>path.resolve(workspaceRoot,other.ownedSource)===at)) throw new CompileError(`${unit.target} would overwrite a guidance source`);
+    }
+    return { source: declared.rel, units, root: path.resolve(workspaceRoot), workspace:declared.workspace, protected:units.some(unit=>unit.target) ? workspaceProtection(workspaceRoot,workspaceDir) : undefined };
 }
 
 function rebasedText(unit, root, to) {
@@ -1573,6 +1754,8 @@ export function claudeCodeGuidance(guidance) {
         if (unit.tier === "always") {
             const at = `${GUIDANCE_RULES_DIR}/${unit.name}.md`;
             files.push({ unit, path: at, text: unit.text === undefined ? unit.body : rebasedText(unit, guidance.root, at) });
+        } else if (unit.tier === "on-path" && unit.target) {
+            files.push({unit,path:unit.target,text:`${nestedMark(guidance.workspace ?? ".",unit.ownedSource ?? unit.source,unit.target)}\n${unit.body}`,nested:true});
         } else if (unit.tier === "on-path") {
             const header = ["---", "paths:", ...unit.paths.map((glob) => `  - ${quoted(glob)}`), "---", ""].join("\n");
             files.push({ unit, path: `${GUIDANCE_RULES_DIR}/${unit.name}.md`, text: `${header}\n${unit.body}` });
@@ -1659,12 +1842,15 @@ function listReal(workspaceRoot, rel) {
 }
 
 /** Judged before either half writes, so a refusal leaves no gate artifact written beside it. */
-function planGuidance(guidance, workspaceRoot) {
+export function planGuidance(guidance, workspaceRoot, workspaceDir = ".portulan") {
+    assertSourceJournalReady(workspaceRoot,workspaceDir);
     const files = guidance ? claudeCodeGuidance(guidance).files : [];
+    const nested = nestedPlan(workspaceRoot,guidance,files,guidance?.workspace ?? workspaceDir);
     const rules = files.filter((f) => f.path.startsWith(`${GUIDANCE_RULES_DIR}/`));
     const owedFiles = rules.length
         ? [{ unit: null, marker: true, path: `${GUIDANCE_RULES_DIR}/${RULES_MARKER}`, text: markerText(rules.map((f) => path.posix.basename(f.path))) }, ...files]
         : files;
+    if (nested.control) owedFiles.push(nested.control);
     const owed = new Set(owedFiles.map((f) => f.path));
 
     for (const file of owedFiles) {
@@ -1706,11 +1892,11 @@ function planGuidance(guidance, workspaceRoot) {
                 // A run stopped before its marker leaves exactly its unit's output; anything else was written by hand.
                 let current;
                 try {
-                    current = fs.readFileSync(path.join(rulesDir, name), "utf8");
+                    current = fs.readFileSync(path.join(rulesDir, name));
                 } catch (cause) {
                     throw new CompileError(`${file.path} could not be read — ${cause.code ?? cause.message}`);
                 }
-                if (current !== file.text) {
+                if (!sameContent(current,file.text)) {
                     throw new CompileError(`${file.path} exists and was not compiled here — ${file.unit ? file.unit.source : `the on-read units in ${guidance.source}`} would replace a rule written by hand. Rename the unit or the rule`);
                 }
             }
@@ -1739,7 +1925,7 @@ function planGuidance(guidance, workspaceRoot) {
     if (listed instanceof Set || rules.length) {
         for (const entry of entries) {
             const rel = `${GUIDANCE_RULES_DIR}/${entry.name}`;
-            if (owed.has(rel)) continue;
+            if (owed.has(rel) || nested.claimed.has(rel)) continue;
             const ours = listed instanceof Set && entry.isFile() && (listed.has(entry.name) || entry.name === RULES_MARKER);
             stray.push({ path: rel, removable: ours });
         }
@@ -1763,7 +1949,20 @@ function planGuidance(guidance, workspaceRoot) {
     const kept = listed instanceof Set || rules.length
         ? rules.map((f) => path.posix.basename(f.path)).filter((name) => listed instanceof Set && listed.has(name) && present.has(name))
         : null;
-    return { owedFiles, stray, kept };
+    stray.push(...nested.stale.map(edit=>({path:edit.file,removable:true,nested:true})));
+    return { owedFiles, stray, kept, nested };
+}
+
+function preflightGuidanceWrites(plan, workspaceRoot) {
+    preflightNestedEdits(workspaceRoot, plan.nested.edits);
+    const outputs = new Set(plan.owedFiles.filter((file) => !file.nested && !file.control).map((file) => file.path));
+    if (plan.kept !== null) outputs.add(`${GUIDANCE_RULES_DIR}/${RULES_MARKER}`);
+    for (const rel of outputs) {
+        const target = path.join(workspaceRoot, ...rel.split("/"));
+        const at = fs.lstatSync(target, { throwIfNoEntry: false });
+        if (at?.isFile() && at.nlink !== 1)
+            throw new CompileError(`${target} is a multiply linked guidance output; refusing publication`);
+    }
 }
 
 function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
@@ -1771,7 +1970,7 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
     if (guidance === null && stray.length === 0) return 0;
 
     if (guidance) {
-        const files = owedFiles.filter((f) => !f.marker);
+        const files = owedFiles.filter((f) => !f.marker && !f.control);
         const counts = LOAD_TIERS.map((tier) => `${guidance.units.filter((u) => u.tier === tier).length} ${tier}`).join(", ");
         say(`guidance: ${guidance.units.length} unit(s) in ${guidance.source} — ${counts}`);
         for (const [id, host] of Object.entries(GUIDANCE_HOSTS)) {
@@ -1799,17 +1998,19 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
             const target = path.join(workspaceRoot, ...file.path.split("/"));
             let current = null;
             try {
-                current = fs.readFileSync(target, "utf8");
+                current = fs.readFileSync(target);
             } catch {
                 say(file.marker
                     ? `RED — ${target} does not exist; it is the marker that lists the rules this compiler wrote. Recompile to write it.`
+                    : file.control ? `RED — ${target} is missing its nested instruction ownership registry. Recompile to write it.`
                     : `RED — ${target} does not exist; ${file.unit ? file.unit.source : "an on-read unit"} compiles to it`);
                 drifted += 1;
                 continue;
             }
-            if (current !== file.text) {
+            if (!sameContent(current,file.text)) {
                 say(file.marker
                     ? `RED — ${target} does not list the rules the units compile to now. Recompile to rewrite it.`
+                    : file.control ? `RED — ${target} has drifted from nested instruction ownership. Recompile to rewrite it.`
                     : file.unit?.leadSources?.length
                       ? `RED — ${target} has drifted from ${file.unit.source}, whose ${[...file.unit.written].sort().join(" and ")} are written from ${file.unit.leadSources.join(" and ")}. Edit the unit or those files, then recompile.`
                       : `RED — ${target} has drifted from ${file.unit ? file.unit.source : `the on-read units in ${guidance.source}`}. Edit the unit, then recompile.`);
@@ -1826,6 +2027,8 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
         return drifted;
     }
 
+    preflightGuidanceWrites(plan, workspaceRoot);
+    applyNestedEdits(workspaceRoot,plan.nested.edits);
     // Listed only once written, unlisted before removal: an interrupted run never lists a file it did not write.
     const markerPath = path.join(workspaceRoot, ...GUIDANCE_RULES_DIR.split("/"), RULES_MARKER);
     if (kept !== null) {
@@ -1834,7 +2037,7 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
     }
     for (const s of stray) {
         const target = path.join(workspaceRoot, ...s.path.split("/"));
-        if (target === markerPath) continue;
+        if (target === markerPath || s.nested) continue;
         if (!s.removable) {
             say(`left ${target} — it is not a file this compiler wrote, so it is not this compiler's to remove`);
             continue;
@@ -1850,7 +2053,7 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
         }
     }
     for (const file of owedFiles) {
-        if (file.marker) continue;
+        if (file.marker || file.nested || file.control) continue;
         const target = path.join(workspaceRoot, ...file.path.split("/"));
         fs.mkdirSync(path.dirname(target), { recursive: true });
         fs.writeFileSync(target, file.text);
@@ -1875,10 +2078,11 @@ function emitGuidance(guidance, plan, { workspaceRoot, check, say }) {
 }
 
 /** The guidance half alone: the gate policy is not read, so host settings stay the output of a `compile` a human runs. */
-export function compileGuidance(named, { check = false, say = () => {} } = {}) {
+export function compileGuidance(named, { check = false, say = () => {}, originRoot } = {}) {
     const { workspaceRoot, workspaceDir } = resolveWorkspace(named);
-    const guidance = guidanceUnits(workspaceRoot, workspaceDir);
-    const plan = planGuidance(guidance, workspaceRoot);
+    const guidance = guidanceUnits(workspaceRoot, workspaceDir, { originRoot });
+    const plan = planGuidance(guidance, workspaceRoot, workspaceDir);
+    if (!check) preflightGuidanceWrites(plan, workspaceRoot);
     return { declared: guidance !== null, drifted: emitGuidance(guidance, plan, { workspaceRoot, check, say }) };
 }
 
@@ -1886,25 +2090,37 @@ export function compileGuidance(named, { check = false, say = () => {} } = {}) {
 export function guidanceEdits(named) {
     const { workspaceRoot, workspaceDir } = resolveWorkspace(named);
     const guidance = guidanceUnits(workspaceRoot, workspaceDir);
-    const { owedFiles, stray, kept } = planGuidance(guidance, workspaceRoot);
+    const { owedFiles, stray, kept, nested } = planGuidance(guidance, workspaceRoot, workspaceDir);
     const markerRel = `${GUIDANCE_RULES_DIR}/${RULES_MARKER}`;
     const current = (rel) => {
         try {
-            return fs.readFileSync(path.join(workspaceRoot, ...rel.split("/")), "utf8");
+            return fs.readFileSync(path.join(workspaceRoot, ...rel.split("/")));
         } catch (cause) {
             if (cause.code === "ENOENT") return null;
             throw new CompileError(`${rel} could not be read — ${cause.code ?? cause.message}`);
         }
     };
-    const edits = [];
-    for (const s of stray) if (s.removable && s.path !== markerRel) edits.push({ file: s.path, next: null });
-    for (const file of owedFiles) if (!file.marker && current(file.path) !== file.text) edits.push({ file: file.path, next: file.text });
+    const edits = [...nested.edits];
+    for (const s of stray) if (s.removable && !s.nested && s.path !== markerRel) edits.push({ file: s.path, next: null });
+    for (const file of owedFiles) if (!file.marker && !file.nested && !file.control && !sameContent(current(file.path),file.text)) edits.push({ file: file.path, next: file.text });
     const marker = owedFiles.find((f) => f.marker);
-    if (marker && current(markerRel) !== marker.text) edits.push({ file: markerRel, next: marker.text });
+    if (marker && !sameContent(current(markerRel),marker.text)) edits.push({ file: markerRel, next: marker.text });
     else if (!marker && kept !== null && current(markerRel) !== null) edits.push({ file: markerRel, next: null });
     return { root: path.resolve(workspaceRoot), edits, left: stray.filter((s) => !s.removable).map((s) => s.path) };
 }
 
+export function personaEdits(named, options = {}) {
+    const { workspaceRoot, workspaceDir } = resolveWorkspace(named);
+    const packs = packContributions(workspaceRoot, workspaceDir, { discovery: () => discoverPackRoots(), ...options });
+    if (packs.unresolved.length) throw new CompileError("persona binding sources are unresolved; refusing a partial refresh");
+    const planned = planPersonas(packs.contributions, workspaceRoot, workspaceDir);
+    return {
+        root: path.resolve(workspaceRoot), compared: planned.compared,
+        edits: planned.files.map(file => ({ file: file.path, next: file.text })),
+        notes: [...planned.lines, ...planned.degraded.map(value => value.line)],
+    };
+}
+
 // ---------------------------------------------------------------- the manifest's declarations
 
 /** `{ file, why }` for a manifest that is there and will not parse as an object; null when it reads or is absent. */
@@ -1912,7 +2128,7 @@ export function unreadableManifest(workspaceRoot, workspaceDir = ".portulan") {
     const file = path.join(workspaceRoot, workspaceDir, "workspace.json");
     let raw;
     try {
-        raw = fs.readFileSync(file, "utf8");
+        raw = readWorkspaceText(workspaceRoot, workspaceDir);
     } catch (cause) {
         if (cause.code === "ENOENT") return null;
         return { file, why: `it could not be read — ${cause.code ?? cause.message}` };
@@ -1934,7 +2150,7 @@ export function policyDeclaration(workspaceRoot, workspaceDir = ".portulan") {
     const fallback = (reason) => ({ file: path.join(workspaceRoot, workspaceDir, "gates.json"), declared: false, reason });
     let declared;
     try {
-        declared = JSON.parse(fs.readFileSync(manifest, "utf8")).gates;
+        declared = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir)).gates;
     } catch {
         // An unreadable manifest reaches here only from the hook's reader, which must not stop.
         return fallback("no-manifest");
@@ -1966,7 +2182,7 @@ export function sessionsDeclaration(workspaceRoot, workspaceDir = ".portulan") {
     const manifest = path.join(workspaceRoot, workspaceDir, "workspace.json");
     let declared;
     try {
-        declared = JSON.parse(fs.readFileSync(manifest, "utf8")).sessions;
+        declared = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir)).sessions;
     } catch {
         return null;
     }
@@ -1993,7 +2209,7 @@ export function spendDeclaration(workspaceRoot, workspaceDir = ".portulan") {
     const manifest = path.join(workspaceRoot, workspaceDir, "workspace.json");
     let parsed;
     try {
-        parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+        parsed = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir));
     } catch {
         return null;
     }
@@ -2007,16 +2223,43 @@ export function spendDeclaration(workspaceRoot, workspaceDir = ".portulan") {
         if (error instanceof LedgerError) throw new CompileError(error.message);
         throw error;
     }
-    const version = /^([0-9]+)\.([0-9]+)$/.exec(parsed.portulan?.spec ?? "");
-    if (spend.restart !== null && version && Number(version[1]) === 2 && Number(version[2]) < 13) {
-        throw new CompileError(
-            `\`spend.restart\` in ${where} is Workspace Definition 2.13's, and this manifest declares ${version[0]}, whose validator ` +
-                "refuses it as an unknown key. Declare 2.13, or remove the key",
-        );
+    if (spend.restart !== null) {
+        const spec = parsed.portulan?.spec;
+        const version = typeof spec === "string" ? /^([0-9]+)\.([0-9]+)$/.exec(spec) : null;
+        if (!version || Number(version[1]) !== 2) {
+            throw new CompileError(
+                `\`spend.restart\` in ${where} requires \`portulan.spec\` to be a string MAJOR.MINOR on supported major 2; ` +
+                    `got ${JSON.stringify(spec)}. Declare 2.13 or a later minor, or remove the key`,
+            );
+        }
+        if (Number(version[2]) < 13) {
+            throw new CompileError(
+                `\`spend.restart\` in ${where} is Workspace Definition 2.13's, and this manifest declares ${version[0]}, whose validator ` +
+                    "refuses it as an unknown key. Declare 2.13, or remove the key",
+            );
+        }
+    }
+    if (spend.resume !== null) {
+        const version = typeof parsed.portulan?.spec === "string" ? /^2\.([0-9]+)$/.exec(parsed.portulan.spec) : null;
+        const schema = JSON.parse(fs.readFileSync(new URL("../spec/workspace.schema.json", import.meta.url), "utf8"));
+        const supported = /\/spec\/2\.([0-9]+)\//.exec(schema.$id ?? "");
+        if (!version || !supported || Number(version[1]) < 16 || Number(version[1]) > Number(supported[1])) {
+            throw new CompileError(`\`spend.resume\` in ${where} requires Workspace Definition 2.16 through the shipped schema's supported minor`);
+        }
     }
     return spend;
 }
 
+function stopDeclaration(workspaceRoot, workspaceDir) {
+    const file = path.join(workspaceRoot, workspaceDir, "workspace.json");
+    let manifest;
+    try { manifest = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir)); } catch { return null; }
+    try {
+        const policy = readStopPolicy(manifest);
+        return policy.declared ? { ...policy, manifest: path.relative(workspaceRoot, file).split(path.sep).join("/") } : null;
+    } catch (error) { throw new CompileError(error.message); }
+}
+
 /** `guidanceOnly` is true where guidance still compiles, and `"leftover"` where only an earlier run's is removed. */
 function undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, reason = "no-key", guidanceOnly = false) {
     const manifest = path.join(workspaceRoot, workspaceDir, "workspace.json");
@@ -2034,8 +2277,14 @@ function undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOp
               : `this workspace declares no gate policy — \`workspace.json\` has no top-level \`gates\` key, ` +
                 `and there is no \`gates.json\` at ${policyFile}.`;
     const outcome =
-        guidanceOnly === "leftover"
+        guidanceOnly === "advisory"
+            ? "No gate policy is compiled; restart advice, declared session settings, ritual admission settings and guidance/persona bindings compile independently."
+            : guidanceOnly === "contexts"
+            ? "No gate policy is compiled; ritual admission settings and any declared guidance/persona bindings compile independently."
+            : guidanceOnly === "leftover"
             ? "No enforcement is compiled, and no guidance is declared: what an earlier run compiled from guidance is this compiler's to remove, and is named below."
+            : guidanceOnly === "personas"
+              ? "No enforcement or guidance is compiled; existing persona bindings still carry their declared fields."
             : guidanceOnly
               ? "No enforcement is compiled; the workspace's guidance still is."
               : "Nothing was compiled and nothing was written.";
@@ -2089,7 +2338,15 @@ export function resolvePack(rawName, roots = []) {
     for (const root of roots) {
         const dir = path.join(root, category, pack);
         const manifest = path.join(dir, "pack.json");
-        if (fs.existsSync(manifest)) return { name, category, pack, dir, manifest, root, why: null };
+        try {
+            const realRoot = fs.realpathSync(root), realDir = fs.realpathSync(dir);
+            if (!isInside(realRoot, realDir)) throw new CompileError(`${dir} resolves outside its resolution root ${root}`);
+            readOwnedText(manifest, dir);
+            return { name, category, pack, dir, manifest, root, why: null };
+        } catch (error) {
+            if (error.code === "ENOENT") continue;
+            throw new CompileError(`cannot resolve \`${name}\` under ${root} — ${error.code ?? error.message}`);
+        }
     }
     return { name, category, pack, dir: null, manifest: null, root: null, why: "no pack.json under any resolution root" };
 }
@@ -2140,6 +2397,7 @@ export function packDifferences(mine, other) {
     const differs = [];
     if (mineV !== otherV) differs.push(`version ${mineV} against the tree's ${otherV}`);
     if (frag(mine) !== frag(other)) differs.push("gate fragments that differ once parsed");
+    if (JSON.stringify(canonical(mine?.contributes?.contexts ?? null)) !== JSON.stringify(canonical(other?.contributes?.contexts ?? null))) differs.push("context caps that differ once parsed");
     return differs;
 }
 
@@ -2154,9 +2412,10 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
     const base = path.join(workspaceRoot, workspaceDir);
     let manifest;
     try {
-        manifest = JSON.parse(fs.readFileSync(path.join(base, "workspace.json"), "utf8"));
-    } catch {
-        return { contributions: [], unresolved: [] };
+        manifest = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir));
+    } catch (error) {
+        if (error.code === "ENOENT") return { contributions: [], unresolved: [] };
+        throw new CompileError(`the workspace manifest could not be read — ${error.code ?? error.message}`);
     }
     const declared = manifest?.packs;
     if (!Array.isArray(declared) || declared.length === 0) return { contributions: [], unresolved: [] };
@@ -2180,7 +2439,7 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
             unresolved.push(found);
             continue;
         }
-        const packManifest = readJson(found.manifest, `the pack manifest for \`${found.name}\``);
+        const packManifest = readJson(found.manifest, `the pack manifest for \`${found.name}\``, found.dir);
         if (!(options.forced ?? false) && plan.source !== "named") {
             const behind = shadowedCopy(found.name, recordedOrigin(found.root, plan, workspaceRoot), roots, (r) =>
                 (plan.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin,
@@ -2188,7 +2447,7 @@ export function packContributions(workspaceRoot, workspaceDir = ".portulan", opt
             if (behind) {
                 let other = null;
                 try {
-                    other = JSON.parse(fs.readFileSync(behind.manifest, "utf8"));
+                    other = JSON.parse(readOwnedText(behind.manifest, behind.dir));
                 } catch (cause) {
                     throw new CompileError(
                         `\`${found.name}\` resolved under the root ${found.root} while the root ` +
@@ -2217,10 +2476,19 @@ 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,
+            contextCap: readContextCap(packManifest, found.name),
             fragments: fragments ?? [],
+            personas: personas ?? [],
             origin: recordedOrigin(found.root, plan, workspaceRoot),
             version: typeof packManifest?.portulan?.version === "string" ? packManifest.portulan.version : null,
         });
@@ -2310,10 +2578,18 @@ export function composeFragments(policy, contributions) {
     return { policy: { ...policy, rules }, added, tightened };
 }
 
-function readJson(file, what) {
+function readWorkspaceText(workspaceRoot, workspaceDir) {
+    const base = path.join(workspaceRoot, workspaceDir);
+    fs.lstatSync(path.join(base, "workspace.json"));
+    const root = fs.realpathSync(workspaceRoot), owner = fs.realpathSync(base);
+    if (!isInside(root, owner)) throw new CompileError(`${base} resolves outside its nominated workspace root`);
+    return readOwnedText(path.join(base, "workspace.json"), base);
+}
+
+function readJson(file, what, scope = path.dirname(file)) {
     let raw;
     try {
-        raw = fs.readFileSync(file, "utf8");
+        raw = readOwnedText(file, scope);
     } catch (error) {
         throw new CompileError(`cannot read ${what} at ${file} — ${error.code ?? error.message}`);
     }
@@ -2328,6 +2604,360 @@ 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",
+    },
+};
+
+/** The plugin location; ordinary projects use `.claude/agents/`. */
+export const BINDING_DIR = "agents";
+
+const PLUGIN_MANIFEST = ".claude-plugin/plugin.json";
+
+export function bindingDirectory(treeRoot) {
+    const unread = (where, cause) => {
+        const error = new CompileError(`${where} could not be examined — ${cause.code ?? cause.message}; binding location is unread, not absent`);
+        error.unread = true;
+        return error;
+    };
+    let realRoot;
+    try { realRoot = fs.realpathSync(treeRoot); }
+    catch (cause) { throw unread(treeRoot, cause); }
+    const directory = rel => {
+        let current = treeRoot;
+        for (const part of rel.split("/")) {
+            current = path.join(current, part);
+            try { fs.lstatSync(current); }
+            catch (cause) { if (cause.code === "ENOENT") return false; throw unread(current, cause); }
+            let real, target;
+            try { real = fs.realpathSync(current); target = fs.statSync(real); }
+            catch (cause) { throw unread(current, cause); }
+            if (!isInside(realRoot, real)) throw new CompileError(`${current} resolves outside the declared tree`);
+            if (!target.isDirectory()) throw new CompileError(`${current} is not a directory`);
+        }
+        return true;
+    };
+    let selected = ".claude/agents";
+    if (directory(".claude-plugin")) {
+        const marker = path.join(treeRoot, PLUGIN_MANIFEST);
+        let stat = null;
+        try { stat = fs.lstatSync(marker); }
+        catch (cause) { if (cause.code !== "ENOENT") throw unread(marker, cause); }
+        if (stat !== null) {
+            if (!stat.isFile()) throw new CompileError(`${marker} is not a regular plugin marker`);
+            let raw;
+            try { raw = fs.readFileSync(marker); }
+            catch (cause) { throw unread(marker, cause); }
+            let value;
+            try { value = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw)); }
+            catch (cause) { throw new CompileError(`${marker} is not a readable UTF-8 JSON plugin marker — ${cause.message}`); }
+            if (value === null || typeof value !== "object" || Array.isArray(value) || typeof value.name !== "string" || !SLUG.test(value.name)) throw new CompileError(`${marker} is not a named plugin object`);
+            selected = BINDING_DIR;
+        }
+    }
+    directory(selected);
+    return selected;
+}
+
+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;
+    if (close === -1) {
+        const why = lines[0]?.trim() === "---" ? "the block is never closed" : "the first line must be `---`";
+        return { name: null, declared: {}, problems: [`has no usable frontmatter — ${why}`] };
+    }
+    const declared = {};
+    const problems = [];
+    const seen = new Set();
+    let name = null;
+    for (const line of 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)}`);
+
+/** Declared personas against existing bindings, including core sources when compiling this engine's own tree. */
+export function planPersonas(contributions, workspaceRoot, workspaceDir = ".portulan") {
+    const base = path.join(workspaceRoot, workspaceDir);
+    let tree = null;
+    try {
+        tree = JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir))?.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;
+    let ownTree = false;
+    if (treeRoot) {
+        try {
+            ownTree = fs.realpathSync(treeRoot) === fs.realpathSync(ENGINE_ROOT);
+        } catch (cause) {
+            if (cause.code !== "ENOENT") throw new CompileError(`the declared tree could not be resolved — ${cause.code ?? cause.message}`);
+        }
+    }
+    const sources = [...contributions];
+    if (ownTree) {
+        let personas;
+        try {
+            personas = fs.readdirSync(path.join(ENGINE_ROOT, "core/personas"))
+                .filter((entry) => entry.endsWith(".md") && entry !== "README.md")
+                .sort().map((entry) => `core/personas/${entry}`);
+        } catch (cause) {
+            throw new CompileError(`core/personas/ could not be read — ${cause.code ?? cause.message}, so its declarations are unknown`);
+        }
+        sources.unshift({ core: true, dir: ENGINE_ROOT, personas });
+    }
+    const files = [];
+    const lines = [];
+    const degraded = [];
+    const owners = new Map();
+    let compared = 0;
+    const bindingDir = treeRoot && sources.some(source => source.personas?.length) ? bindingDirectory(treeRoot) : BINDING_DIR;
+    for (const contribution of sources) {
+        for (const rel of contribution.personas ?? []) {
+            const where = contribution.core ? `core persona \`${rel}\`` : `\`${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 ${contribution.core ? "engine" : "pack"}`);
+                if (!fs.statSync(file).isFile()) throw new CompileError(`${where} is not a regular persona file`);
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(file));
+            } 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.${contribution.core ? " Restore the core source" : " 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 (contribution.core && name !== path.basename(rel, ".md")) {
+                throw new CompileError(`${where} declares name \`${name}\`, which differs from its filename and binding identity`);
+            }
+            if (!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.core ? rel : `${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}` });
+                }
+            }
+            const bindingRel = `${bindingDir}/${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, bindingDir, `${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}`);
+            }
+            let current;
+            try { current = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(binding)); }
+            catch (cause) { throw new CompileError(`${shown} could not be read as UTF-8 — ${cause.code ?? cause.message}`); }
+            const next = boundAgent(current, declared, source, shown);
+            const { fields: bindingFields, error } = parseFrontmatter(current);
+            if (error || bindingFields?.name?.trim() !== name || !bindingFields?.tools?.trim()) {
+                throw new CompileError(`${shown} needs matching name: ${name} and a tools allow-list in usable frontmatter before compilation`);
+            }
+            if (fields.length) lines.push(`persona  ${name.padEnd(22)} ${listed(fields)} → ${shown} (${PERSONA_HOSTS["claude-code"].label})`);
+            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 }) {
@@ -2391,7 +3021,7 @@ export function resolveWorkspace(named) {
     const manifestPath = path.join(dir, "workspace.json");
     let raw;
     try {
-        raw = fs.readFileSync(manifestPath, "utf8");
+        raw = readOwnedText(manifestPath, dir);
     } catch (cause) {
         // As given, not resolved: `compile` prints paths built on it.
         if (cause.code === "ENOENT") return { workspaceRoot: named, workspaceDir: ".portulan" };
@@ -2412,6 +3042,7 @@ export function resolveWorkspace(named) {
     if (typeof manifest?.tree === "string" && manifest.tree.trim()) {
         const root = path.resolve(dir, manifest.tree);
         const inside = path.relative(root, dir);
+        if(inside === "") return {workspaceRoot:root,workspaceDir:"."};
         // A `tree` that does not contain its workspace cannot be trusted, so the answer is the one that changes nothing.
         if (inside && !inside.startsWith("..") && !path.isAbsolute(inside)) {
             return { workspaceRoot: root, workspaceDir: inside.split(path.sep).join("/") };
@@ -2423,19 +3054,19 @@ export function resolveWorkspace(named) {
 
 function usage() {
     return [
-        "portulan compile — compile a workspace's gate policy into host enforcement",
+        "portulan compile — compile workspace advice, guidance, bindings and declared gates",
         "",
         "  portulan compile [--check] [--matrix] [--workspace <dir>] [--pack-root <dir>|auto]...",
         "",
-        "  (no flag)     compile the policy and the guidance, and write each artifact",
-        "  --check       write nothing; exit 1 if an artifact is out of date against the policy or the guidance",
+        "  (no flag)     compile native advice/settings, guidance, bindings and declared gates",
+        "  --check       write nothing; exit 1 if an artifact differs from its declarations",
         "  --matrix      print every rule against every backend, the gates neither compiles, and every",
-        "                guidance unit against every host",
+        "                guidance unit against every host; report native settings without a policy",
         "  --workspace   the workspace directory to compile; defaults to `.portulan`",
         "  --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`",
         "",
-        "The compiler emits RESTRICTION only: `auto` and `propose` compile to nothing in the Claude Code",
+        "Gate compilation emits RESTRICTION only: `auto` and `propose` compile to nothing in the Claude Code",
         "backend by design, and the partition inverts in the repository ruleset, which is the floor.",
         "",
         "Exit codes: 0 succeeded · 1 a red verdict · 2 could not run.",
@@ -2512,51 +3143,65 @@ export function run(argv, options = {}) {
             );
         }
         const guidance = guidanceUnits(workspaceRoot, workspaceDir);
-        const guidancePlan = showMatrix ? null : planGuidance(guidance, workspaceRoot);
+        const guidancePlan = showMatrix ? null : planGuidance(guidance, workspaceRoot, workspaceDir);
+        if (!check && guidancePlan) preflightGuidanceWrites(guidancePlan, workspaceRoot);
         const sessions = sessionsDeclaration(workspaceRoot, workspaceDir);
         const spend = spendDeclaration(workspaceRoot, workspaceDir);
+        const stopPolicy = stopDeclaration(workspaceRoot, workspaceDir);
         const { file: policyFile, declared: policyDeclared, reason: policyReason } = policyDeclaration(workspaceRoot, workspaceDir);
         const packOptions = { named: namedRoots, discovery: () => discoverPackRoots(), forced };
         if (policyReason === "refused") {
             throw new CompileError(undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason));
         }
         if (!policyDeclared && !fs.existsSync(policyFile)) {
-            // Only a manifest read and naming no policy clears leftovers: one that is missing has not been authored.
+            // Only an authored manifest clears stray guidance.
             const leftover = guidance === null && policyReason === "no-key" && guidancePlan !== null && guidancePlan.stray.length > 0;
-            if (guidance === null && !leftover) {
-                throw new CompileError(undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason));
-            }
-            say(`note    ${undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason, leftover ? "leftover" : true)}`);
-            if (sessions !== null) {
-                say(
-                    `note    \`sessions\` in ${sessions.manifest} compiled nothing: its host switches ride the settings a gate ` +
-                        `policy compiles to, and this workspace has none`,
-                );
+            let packs;
+            try { packs = packContributions(workspaceRoot, workspaceDir, packOptions); }
+            catch (cause) {
+                if (guidance === null && !leftover) throw new CompileError(`${undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason)}\n  Persona planning was unavailable: ${cause.message}`);
+                throw cause;
             }
-            if (spend !== null) {
-                say(
-                    `note    \`spend\` in ${spend.manifest} compiled nothing: what it declares rides the restart advisory's commands ` +
-                        `in the settings a gate policy compiles to, and this workspace has none`,
-                );
+            const contexts = contextCaps(packs.contributions, packs.unresolved);
+            const authored = policyReason === "no-key" && ["repository", "demo", "portfolio"].includes(JSON.parse(readWorkspaceText(workspaceRoot, workspaceDir)).kind);
+            const advice = authored ? claudeCode(null, {
+                source: path.join(workspaceDir, "workspace.json").split(path.sep).join("/"),
+                root: path.resolve(workspaceRoot), sessions, spend, contexts, packProvenance: packs.contributions,
+            }) : null;
+            const capPlan = capOnlyPlan(workspaceRoot, contexts, advice?.artifact.value ?? null);
+            const personas = planPersonas(packs.contributions, workspaceRoot, workspaceDir);
+            if (guidance === null && !leftover && personas.compared === 0 && !capPlan) {
+                printPersonaReport(say, personas);
+                for (const line of contextCapLines(contexts)) say(`note    ${line}`);
+                throw new CompileError(undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason));
             }
+            say(`note    ${undeclaredPolicyMessage(policyFile, workspaceRoot, workspaceDir, packOptions, policyReason, advice ? "advisory" : capPlan ? "contexts" : leftover ? "leftover" : guidance === null ? "personas" : true)}`);
+            if (advice) for (const line of advice.notes) say(`note    ${line}`);
+            else if (sessions !== null || spend !== null) say("note    session and spend settings require an authored governing workspace or gate policy");
+            if (stopPolicy !== null) say("note    verify.stopTimeout compiled no outer hook timeout: this workspace has no gate policy");
             say();
+            for (const u of packs.unresolved) say(unresolvedLine(u));
+            if (packs.unresolved.length) say();
+            if (!advice) for (const line of contextCapLines(contexts)) say(`note    ${line}`);
             if (showMatrix) {
-                printGuidanceMatrix(say, guidance);
+                if (guidance) printGuidanceMatrix(say, guidance);
+                printPersonaReport(say, personas);
                 return 0;
             }
-            const drifted = emitGuidance(guidance, guidancePlan, { workspaceRoot, check, say });
+            const drifted = emitCapOnly(capPlan, { check, say }) + 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" : ""}${capPlan ? ", and native settings match their declarations" : ""}`);
             return 0;
         }
-        const policy = readJson(policyFile, "the gate policy");
+        const policy = readJson(policyFile, "the gate policy", path.join(workspaceRoot, workspaceDir));
         // A thunk, so the host's plugin record is read only where discovery can win.
         const { contributions, unresolved, plan } = packContributions(workspaceRoot, workspaceDir, {
             named: namedRoots,
             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);
@@ -2569,23 +3214,25 @@ export function run(argv, options = {}) {
             packProvenance: contributions,
             sessions,
             spend,
+            stopPolicy,
+            contexts: contextCaps(contributions, unresolved),
         });
 
         for (const a of composed.added) say(`pack    ${a.pack.padEnd(30)} adds \`${a.id}\` (${a.tier})`);
         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) {
             printMatrix(say, parsed, columns, { source });
+            for (const line of contextCapLines(contextCaps(contributions, unresolved))) say(`note    ${line}`);
             if (guidance) {
                 say();
                 printGuidanceMatrix(say, guidance);
             }
+            printPersonaReport(say, personas);
             return 0;
         }
 
@@ -2642,9 +3289,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 +3313,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) {