@meetless/mla 0.1.4

package/dist/lib/enrichment/protocol.js

@@ -0,0 +1,359 @@
+"use strict";
+// Onboarding enrichment protocol: the pure, dependency-free core shared by the two
+// CLI bookends (`enrich plan` writes the authoritative run record; `enrich ingest`
+// loads it and validates the scouts' candidates). Everything here is deterministic
+// and side-effect-free: types, the candidate identity hash, the plan digest, and the
+// SHAPE validators. Impure checks (realpath containment, exist-at-HEAD, line-range vs
+// real file length, fs/network) live in ingest.ts; clock + id injection lives in
+// plan.ts. See notes/20260626-mla-agent-onboarding-enrichment-plan.md (§5, §5b, §6, §6b, §8).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOUT_STATUSES = exports.SCOUT_NAMES = exports.ENRICHMENT_KINDS = exports.MIN_COMMIT_SHA_LENGTH = exports.MAX_EVIDENCE_PER_CANDIDATE = exports.MIN_STATEMENT_LENGTH = exports.MAX_STATEMENT_LENGTH = exports.DEFAULT_BUDGET_MS = exports.MAX_CANDIDATES_TOTAL = exports.MAX_PREPARED_INPUT_BYTES = exports.MAX_HISTORY_COMMITS = exports.MAX_DOCUMENT_TARGETS = exports.PROTOCOL_VERSION = void 0;
+exports.normalizeStatement = normalizeStatement;
+exports.candidateAnchors = candidateAnchors;
+exports.candidateId = candidateId;
+exports.candidateSlug = candidateSlug;
+exports.candidateRelPath = candidateRelPath;
+exports.stableStringify = stableStringify;
+exports.computePlanDigest = computePlanDigest;
+exports.defaultLimits = defaultLimits;
+exports.commitAllowlist = commitAllowlist;
+exports.resolveAllowedCommit = resolveAllowedCommit;
+exports.validateCandidateShape = validateCandidateShape;
+exports.validateScoutResultShape = validateScoutResultShape;
+exports.validateIngestRequestShape = validateIngestRequestShape;
+const crypto_1 = require("crypto");
+exports.PROTOCOL_VERSION = 1;
+// Input bounds (§8). Explicit MVP constants; only the time budget is configurable.
+exports.MAX_DOCUMENT_TARGETS = 20;
+exports.MAX_HISTORY_COMMITS = 40;
+exports.MAX_PREPARED_INPUT_BYTES = 200_000;
+exports.MAX_CANDIDATES_TOTAL = 20; // ceiling, not a target; zero is valid
+exports.DEFAULT_BUDGET_MS = 240_000;
+// Defensive bounds NOT pinned by the plan (§5 says only "max statement length" and
+// "allowed kind"); these are conservative defaults, tune freely.
+exports.MAX_STATEMENT_LENGTH = 500;
+exports.MIN_STATEMENT_LENGTH = 1; // non-empty after normalization; no semantic floor (the human governs durability)
+exports.MAX_EVIDENCE_PER_CANDIDATE = 12;
+exports.MIN_COMMIT_SHA_LENGTH = 7; // git's conventional abbreviation floor
+exports.ENRICHMENT_KINDS = [
+    "constraint",
+    "decision",
+    "convention",
+    "boundary",
+    "deprecation",
+];
+exports.SCOUT_NAMES = ["documentation", "history"];
+exports.SCOUT_STATUSES = ["complete", "failed", "timed_out"];
+// --- Identity + digest -----------------------------------------------------------
+// Nothing semantic: no stemming, no punctuation removal, no LLM canonicalization (§6).
+function normalizeStatement(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+// The anchors that define a candidate's identity: file paths (from file evidence) and
+// commit SHAs (from commit evidence). Line numbers are EXCLUDED so identity survives
+// line drift (§6). Anchors are type-tagged ("f:"/"c:") to prevent a path that happens
+// to equal a SHA string from colliding across the two evidence kinds, then deduped and
+// sorted for a stable hash. A commit's optional historical `path` is supplementary
+// context, not identity (the SHA is the anchor).
+function candidateAnchors(candidate) {
+    const anchors = new Set();
+    for (const ev of candidate.evidence) {
+        if (ev.type === "file") {
+            anchors.add(`f:${ev.path}`);
+        }
+        else {
+            anchors.add(`c:${ev.commit.toLowerCase()}`);
+        }
+    }
+    return [...anchors].sort();
+}
+// candidateId = sha256( protocolVersion + kind + normalizeStatement(statement) + sortedAnchors )
+// Identical content reuses the same id (idempotent re-ingest); changed content gets a
+// different id. The server's per-revision PENDING default is the real authority backstop;
+// this hash is only for dedup stability (§6).
+function candidateId(candidate) {
+    const parts = [
+        String(exports.PROTOCOL_VERSION),
+        candidate.kind,
+        normalizeStatement(candidate.statement),
+        candidateAnchors(candidate).join("\n"),
+    ];
+    // Join with "\n" (not " "): normalizeStatement collapses all whitespace to single
+    // spaces so a statement can never contain a newline, which makes "\n" an unambiguous
+    // tuple delimiter. A space would be ambiguous (statements contain spaces); a NUL byte
+    // would make this file read as binary to grep/diff. Keep it "\n".
+    return (0, crypto_1.createHash)("sha256").update(parts.join("\n")).digest("hex");
+}
+// Human-friendly suffix for the persisted path; identity lives in the hash, the slug is
+// cosmetic. Path: onboarding/<candidateId>-<slug>.md (§6).
+function candidateSlug(statement, maxLen = 40) {
+    const slug = normalizeStatement(statement)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, maxLen)
+        .replace(/-+$/g, "");
+    return slug || "candidate";
+}
+function candidateRelPath(candidate) {
+    return `onboarding/${candidateId(candidate)}-${candidateSlug(candidate.statement)}.md`;
+}
+// Deterministic JSON: recursively sort object keys so the digest is stable regardless of
+// property insertion order. Arrays keep their order (it is meaningful here: ranks, etc.).
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const body = keys
+        .filter((k) => obj[k] !== undefined)
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`)
+        .join(",");
+    return `{${body}}`;
+}
+// Digest over the integrity-bearing plan content: everything that defines the plan's
+// commitments. Excludes runId (the lookup key), createdAt/deadlineAt (volatile
+// orchestration), and planDigest itself. ingest recomputes this and rejects on mismatch,
+// catching on-disk corruption of the stored record (§5b step 4).
+function computePlanDigest(run) {
+    const canonical = stableStringify({
+        protocolVersion: run.protocolVersion,
+        workspaceId: run.workspaceId,
+        repositoryRoot: run.repositoryRoot,
+        limits: run.limits,
+        documentationTargets: run.documentationTargets,
+        historyEvidence: run.historyEvidence,
+    });
+    return (0, crypto_1.createHash)("sha256").update(canonical).digest("hex");
+}
+function defaultLimits(budgetMs = exports.DEFAULT_BUDGET_MS) {
+    return {
+        maxDocumentTargets: exports.MAX_DOCUMENT_TARGETS,
+        maxHistoryCommits: exports.MAX_HISTORY_COMMITS,
+        maxPreparedInputBytes: exports.MAX_PREPARED_INPUT_BYTES,
+        maxCandidatesTotal: exports.MAX_CANDIDATES_TOTAL,
+        budgetMs,
+    };
+}
+// --- Commit allowlist resolution (pure; membership against the stored plan) ------
+function commitAllowlist(run) {
+    return run.historyEvidence.map((e) => e.commit.toLowerCase());
+}
+// Resolve a candidate-cited commit (possibly abbreviated) against the plan's allowlist
+// of full SHAs. Returns the canonical full SHA, or null if it matches none or is
+// ambiguous (a too-short prefix hitting more than one allowlisted commit). ingest uses
+// this to enforce "commit must be in the plan's allowlist" (§5b step 5).
+function resolveAllowedCommit(allowlist, cited) {
+    const needle = cited.trim().toLowerCase();
+    if (!/^[0-9a-f]+$/.test(needle) || needle.length < exports.MIN_COMMIT_SHA_LENGTH)
+        return null;
+    const exact = allowlist.find((c) => c === needle);
+    if (exact)
+        return exact;
+    const prefixed = allowlist.filter((c) => c.startsWith(needle));
+    return prefixed.length === 1 ? prefixed[0] : null;
+}
+// --- Pure shape validators -------------------------------------------------------
+const CANDIDATE_FIELDS = new Set(["kind", "statement", "evidence", "sourceScout"]);
+const FILE_EVIDENCE_FIELDS = new Set(["type", "path", "startLine", "endLine"]);
+const COMMIT_EVIDENCE_FIELDS = new Set(["type", "commit", "path"]);
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isPositiveInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 1;
+}
+// Validates a single untrusted candidate's SHAPE only (§5). Pure: no fs, no git. The
+// caller (ingest) layers on realpath containment, exist-at-HEAD, line-range-vs-file,
+// and commit-allowlist membership. Collects ALL shape errors for one candidate so the
+// scout's report is actionable rather than first-error-only.
+function validateCandidateShape(raw, index) {
+    const errors = [];
+    const err = (code, message, field) => {
+        errors.push({ index, code, message, field });
+    };
+    if (!isPlainObject(raw)) {
+        return { ok: false, errors: [{ index, code: "not_an_object", message: "candidate must be a JSON object" }] };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!CANDIDATE_FIELDS.has(key))
+            err("unknown_field", `unknown field "${key}"`, key);
+    }
+    const kind = raw.kind;
+    if (typeof kind !== "string" || !exports.ENRICHMENT_KINDS.includes(kind)) {
+        err("bad_kind", `kind must be one of: ${exports.ENRICHMENT_KINDS.join(", ")}`, "kind");
+    }
+    const sourceScout = raw.sourceScout;
+    if (typeof sourceScout !== "string" || !exports.SCOUT_NAMES.includes(sourceScout)) {
+        err("bad_source_scout", `sourceScout must be one of: ${exports.SCOUT_NAMES.join(", ")}`, "sourceScout");
+    }
+    const statement = raw.statement;
+    if (typeof statement !== "string") {
+        err("bad_statement", "statement must be a string", "statement");
+    }
+    else {
+        const norm = normalizeStatement(statement);
+        if (norm.length < exports.MIN_STATEMENT_LENGTH)
+            err("empty_statement", "statement is empty", "statement");
+        if (norm.length > exports.MAX_STATEMENT_LENGTH) {
+            err("statement_too_long", `statement exceeds ${exports.MAX_STATEMENT_LENGTH} chars`, "statement");
+        }
+    }
+    const evidence = raw.evidence;
+    const validEvidence = [];
+    if (!Array.isArray(evidence) || evidence.length === 0) {
+        err("no_evidence", "evidence must be a non-empty array", "evidence");
+    }
+    else if (evidence.length > exports.MAX_EVIDENCE_PER_CANDIDATE) {
+        err("too_much_evidence", `evidence exceeds ${exports.MAX_EVIDENCE_PER_CANDIDATE} items`, "evidence");
+    }
+    else {
+        evidence.forEach((ev, i) => {
+            const parsed = validateEvidenceShape(ev, index, i, err);
+            if (parsed)
+                validEvidence.push(parsed);
+        });
+    }
+    // Anchor-type cross-check (§5): documentation candidates require >= 1 file anchor;
+    // history candidates require >= 1 commit anchor.
+    if (sourceScout === "documentation" && !validEvidence.some((e) => e.type === "file")) {
+        err("missing_file_anchor", "documentation candidate requires at least one file anchor", "evidence");
+    }
+    if (sourceScout === "history" && !validEvidence.some((e) => e.type === "commit")) {
+        err("missing_commit_anchor", "history candidate requires at least one commit anchor", "evidence");
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        candidate: {
+            kind: kind,
+            statement: statement,
+            evidence: validEvidence,
+            sourceScout: sourceScout,
+        },
+    };
+}
+function validateEvidenceShape(raw, candidateIndex, evidenceIndex, err) {
+    const field = `evidence[${evidenceIndex}]`;
+    if (!isPlainObject(raw)) {
+        err("bad_evidence", "evidence item must be an object", field);
+        return null;
+    }
+    const type = raw.type;
+    if (type === "file") {
+        for (const key of Object.keys(raw)) {
+            if (!FILE_EVIDENCE_FIELDS.has(key))
+                err("unknown_field", `unknown field "${key}" on file evidence`, `${field}.${key}`);
+        }
+        const path = raw.path;
+        const startLine = raw.startLine;
+        const endLine = raw.endLine;
+        let ok = true;
+        if (typeof path !== "string" || path.trim().length === 0) {
+            err("bad_path", "file evidence requires a non-empty path", `${field}.path`);
+            ok = false;
+        }
+        if (!isPositiveInt(startLine)) {
+            err("bad_line", "startLine must be an integer >= 1", `${field}.startLine`);
+            ok = false;
+        }
+        if (!isPositiveInt(endLine)) {
+            err("bad_line", "endLine must be an integer >= 1", `${field}.endLine`);
+            ok = false;
+        }
+        if (isPositiveInt(startLine) && isPositiveInt(endLine) && endLine < startLine) {
+            err("bad_range", "endLine must be >= startLine", `${field}.endLine`);
+            ok = false;
+        }
+        if (!ok)
+            return null;
+        return { type: "file", path: path, startLine: startLine, endLine: endLine };
+    }
+    if (type === "commit") {
+        for (const key of Object.keys(raw)) {
+            if (!COMMIT_EVIDENCE_FIELDS.has(key))
+                err("unknown_field", `unknown field "${key}" on commit evidence`, `${field}.${key}`);
+        }
+        const commit = raw.commit;
+        const path = raw.path;
+        let ok = true;
+        if (typeof commit !== "string" || !/^[0-9a-f]+$/i.test(commit) || commit.length < exports.MIN_COMMIT_SHA_LENGTH || commit.length > 40) {
+            err("bad_commit", `commit must be a hex SHA of ${exports.MIN_COMMIT_SHA_LENGTH}-40 chars`, `${field}.commit`);
+            ok = false;
+        }
+        if (path !== undefined && (typeof path !== "string" || path.trim().length === 0)) {
+            err("bad_path", "commit evidence path must be a non-empty string when present", `${field}.path`);
+            ok = false;
+        }
+        if (!ok)
+            return null;
+        const out = { type: "commit", commit: commit.toLowerCase() };
+        if (typeof path === "string")
+            out.path = path;
+        return out;
+    }
+    err("bad_evidence_type", 'evidence type must be "file" or "commit"', `${field}.type`);
+    return null;
+}
+// Validates the OUTER scout envelope shape (§6b). candidates[] content is intentionally
+// left as unknown[] here; each candidate is validated independently downstream so one bad
+// candidate never discards the rest from the same scout.
+function validateScoutResultShape(raw) {
+    if (!isPlainObject(raw))
+        return { ok: false, error: "scout result must be an object" };
+    const scout = raw.scout;
+    if (typeof scout !== "string" || !exports.SCOUT_NAMES.includes(scout)) {
+        return { ok: false, error: `scout must be one of: ${exports.SCOUT_NAMES.join(", ")}` };
+    }
+    const status = raw.status;
+    if (typeof status !== "string" || !exports.SCOUT_STATUSES.includes(status)) {
+        return { ok: false, error: `status must be one of: ${exports.SCOUT_STATUSES.join(", ")}` };
+    }
+    if (!Array.isArray(raw.candidates)) {
+        return { ok: false, error: "candidates must be an array" };
+    }
+    if (raw.truncated !== undefined && typeof raw.truncated !== "boolean") {
+        return { ok: false, error: "truncated must be a boolean when present" };
+    }
+    if (raw.error !== undefined && typeof raw.error !== "string") {
+        return { ok: false, error: "error must be a string when present" };
+    }
+    const result = {
+        scout: scout,
+        status: status,
+        candidates: raw.candidates,
+    };
+    if (typeof raw.truncated === "boolean")
+        result.truncated = raw.truncated;
+    if (typeof raw.error === "string")
+        result.error = raw.error;
+    return { ok: true, result };
+}
+// Validates the top-level ingest envelope (§5b). Per-scout envelope and per-candidate
+// validation happen downstream.
+function validateIngestRequestShape(raw) {
+    if (!isPlainObject(raw))
+        return { ok: false, error: "ingest request must be an object" };
+    if (raw.protocolVersion !== exports.PROTOCOL_VERSION) {
+        return { ok: false, error: `protocolVersion must be ${exports.PROTOCOL_VERSION}` };
+    }
+    if (typeof raw.runId !== "string" || raw.runId.trim().length === 0) {
+        return { ok: false, error: "runId must be a non-empty string" };
+    }
+    if (!Array.isArray(raw.results)) {
+        return { ok: false, error: "results must be an array" };
+    }
+    return {
+        ok: true,
+        request: {
+            protocolVersion: exports.PROTOCOL_VERSION,
+            runId: raw.runId,
+            results: raw.results,
+        },
+    };
+}

package/dist/lib/enrichment/scout-brief.js

@@ -0,0 +1,176 @@
+"use strict";
+// Onboarding scout briefs: the internal subagent prompt for each scout role.
+//
+// `/mla onboard` runs `enrich plan` (writes the authoritative run record), then
+// dispatches one subagent per incomplete scout, then runs `enrich ingest`. This
+// module renders the per-role brief from the run record so EVERY input a scout sees
+// (the exact document targets, the bounded git evidence) is exactly what `enrich
+// ingest` will validate against. The brief is a pure function of (run, role): no
+// clock, no randomness, no IO. `enrich brief --run-id --role` prints it.
+//
+// The shared rules of engagement (role identity, candidate kinds, evidence rule,
+// non-authoritative posture, untrusted-content rule) come from buildScoutPolicy in
+// ../scanner/scout-mission, the SAME source the human copy/paste mission uses, so
+// the two surfaces cannot drift (plan §4).
+//
+// Capability boundary: SCOUT_TOOL_ALLOWLIST is the single source of truth for what
+// each scout may do. The documentation scout gets Read only; the history scout gets
+// nothing (it interprets in-prompt evidence). A static test (gate 7) asserts neither
+// allowlist contains a shell, mutation, or network tool, and the subagent .md
+// definitions' `tools:` frontmatter is cross-checked against this map.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOUT_AGENT_NAME = exports.SCOUT_TOOL_ALLOWLIST = void 0;
+exports.buildScoutPrompt = buildScoutPrompt;
+const scout_mission_1 = require("../scanner/scout-mission");
+// The capability each scout role is granted. Read-only for documentation; no tools
+// for history (the plan precomputes and inlines its evidence). Deliberately narrow:
+// the deterministic plan already discovered and ranked inputs, so scouts never need
+// Glob/Grep, and they never need shell, write, or network. Widen only if real
+// dogfood proves a need (plan §4).
+exports.SCOUT_TOOL_ALLOWLIST = {
+    documentation: ["Read"],
+    history: [],
+};
+// The Claude Code subagent `name:` each scout role dispatches as. `/mla onboard`
+// (the mla-onboard skill) reads this to pick the subagent_type per role, and
+// wire.ts installs one ~/.claude/agents/<name>.md per role whose `tools:`
+// frontmatter is rendered from SCOUT_TOOL_ALLOWLIST above. Single source of truth
+// so the skill, the installed agent files, and the contract test cannot drift.
+exports.SCOUT_AGENT_NAME = {
+    documentation: "meetless-doc-scout",
+    history: "meetless-history-scout",
+};
+function renderCategoryLines(policy) {
+    return policy.categories.map((c) => `  • ${c.kind}: ${c.gloss}`);
+}
+function renderDocumentationTargets(targets) {
+    if (targets.length === 0) {
+        return [
+            "(The plan issued no document targets for this run. Return status \"complete\"",
+            " with an empty candidates array.)",
+        ];
+    }
+    return [...targets]
+        .sort((a, b) => a.rank - b.rank)
+        .map((t) => `  ${t.rank}. ${t.path}  [${t.tier}]`);
+}
+function renderGitEvidence(evidence) {
+    if (evidence.length === 0) {
+        return [
+            "(The plan issued no commit history for this run. Return status \"complete\"",
+            " with an empty candidates array.)",
+        ];
+    }
+    const lines = [];
+    for (const c of evidence) {
+        lines.push(`commit ${c.commit}`);
+        lines.push(`  date: ${c.timestamp}`);
+        lines.push(`  subject: ${c.subject}`);
+        if (c.body && c.body.trim().length > 0) {
+            lines.push("  message:");
+            for (const bodyLine of c.body.split("\n")) {
+                lines.push(`    ${bodyLine}`);
+            }
+        }
+        if (c.changedFiles.length > 0) {
+            lines.push("  files:");
+            for (const f of c.changedFiles) {
+                const renamed = f.renamedFrom ? ` (from ${f.renamedFrom})` : "";
+                lines.push(`    ${f.status}  ${f.path}${renamed}`);
+            }
+        }
+        if (c.diffExcerpt && c.diffExcerpt.trim().length > 0) {
+            lines.push("  diff excerpt:");
+            for (const diffLine of c.diffExcerpt.split("\n")) {
+                lines.push(`    ${diffLine}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function toolLine(role) {
+    const tools = exports.SCOUT_TOOL_ALLOWLIST[role];
+    if (tools.length === 0) {
+        return ("You have NO tools. Do not attempt to read files, run commands, or fetch " +
+            "anything; everything you need is reproduced in this brief.");
+    }
+    return `Your only tools are: ${tools.join(", ")}. Do not attempt any other tool.`;
+}
+function renderOutputContract(run, role) {
+    const evidenceExample = role === "documentation"
+        ? '{ "type": "file", "path": "<one of the documents above>", "startLine": 10, "endLine": 24 }'
+        : '{ "type": "commit", "commit": "<one of the commits above>", "path": "optional/historical/path" }';
+    const anchorRule = role === "documentation"
+        ? "Every candidate needs at least one `file` anchor whose path is exactly one of the documents listed above; the line range must point at the text that states the claim."
+        : "Every candidate needs at least one `commit` anchor whose SHA is exactly one of the commits listed above; an optional `path` may name a historical file even if it no longer exists at HEAD.";
+    return [
+        "Return EXACTLY one JSON object and nothing else (no prose before or after it):",
+        "",
+        "{",
+        `  "scout": "${role}",`,
+        '  "status": "complete",            // or "timed_out" if you ran out of time, "failed" if you could not proceed',
+        '  "candidates": [',
+        "    {",
+        '      "kind": "<one of the kinds listed above>",',
+        '      "statement": "<one specific claim, 500 characters or fewer>",',
+        `      "evidence": [ ${evidenceExample} ],`,
+        `      "sourceScout": "${role}"`,
+        "    }",
+        "  ]",
+        "}",
+        "",
+        anchorRule,
+        `Surface at most ${run.limits.maxCandidatesTotal} candidates total across all scouts; ` +
+            "choose the highest-value ones rather than padding.",
+        'Zero candidates with status "complete" is a valid, successful result: only record a',
+        "candidate you can anchor to the evidence above.",
+        "Also note any contradictions you see in a short prose summary after the JSON; a",
+        "contradiction is a flag for the human, not a candidate of its own.",
+    ];
+}
+/**
+ * Render the brief for one scout role from the authoritative run record. Pure: the
+ * same (run, role) always yields the same string. The documentation brief lists the
+ * exact ranked document targets and grants Read; the history brief inlines the
+ * bounded git evidence and grants no tools. Both state the shared scout policy and
+ * the JSON output contract `enrich ingest` expects.
+ */
+function buildScoutPrompt(run, role) {
+    const policy = (0, scout_mission_1.buildScoutPolicy)();
+    const head = [
+        `Onboarding scout: ${role} (run ${run.runId}).`,
+        "",
+        ...policy.roleIdentity,
+        "",
+        "Surface these kinds of candidate (use the exact value for the `kind` field):",
+        ...renderCategoryLines(policy),
+        "",
+        ...policy.evidenceRule,
+        "",
+        ...policy.untrustedContent,
+        "",
+        ...policy.nonAuthoritative,
+        "",
+        toolLine(role),
+        `Wall-clock deadline: ${run.deadlineAt}. If you approach it, stop and return what you`,
+        'have so far with status "timed_out" rather than working past the deadline.',
+        "",
+    ];
+    const body = role === "documentation"
+        ? [
+            "Read ONLY these documents, in rank order. The plan already selected and ranked",
+            "them; do not search for, glob, or open any other file.",
+            "",
+            ...renderDocumentationTargets(run.documentationTargets),
+        ]
+        : [
+            "You cannot open files or run git. The relevant history is reproduced below,",
+            "bounded to what fits this brief. Interpret it: why a current design exists, what",
+            "was reversed or superseded, which mistake keeps reappearing, which approach was",
+            "killed.",
+            "",
+            ...renderGitEvidence(run.historyEvidence),
+        ];
+    return [...head, ...body, "", ...renderOutputContract(run, role)].join("\n");
+}