@voybio/ace-swarm 2.4.3 → 2.4.6

package/assets/agent-state/INTERFACE_REGISTRY.md

@@ -54,9 +54,9 @@
 
 ## Public Surface Gate
 
-- `audit_public_surface` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
+- `audit_public_surface` is the canonical TypeScript public-surface audit for MCP tools, resources, prompts, and registered event names.
 - `PUBLIC_SURFACE_REPORT.md` is the durable audit artifact written by that gate.
-- `MODULES/gates/gate-typescript-public-surface.json` is the executable gate manifest for CI or operator use.
+- The package-level public-surface check remains an explicit package maintenance tool or CI gate; it is not seeded into initialized ACE workspaces as a default stage gate.
 
 ## Provenance Contract
 

package/assets/agent-state/MODULES/gates/gate-autonomy.json

@@ -1,7 +1,9 @@
 {
   "id": "gate-autonomy",
   "type": "artifact_scan",
-  "invariant": "Every execution cycle records objective, strategy, evidence, and next state",
+  "scope": "workspace",
+  "activation": "stage",
+  "invariant": "ACE lifecycle state records objective, evidence, and handoff continuity for the active stage",
   "command": "",
-  "evidence_requirement": "STATUS + EVIDENCE_LOG + HANDOFF pointers"
+  "evidence_requirement": "STATUS.md + EVIDENCE_LOG.md + HANDOFF.json"
 }

package/assets/agent-state/MODULES/gates/gate-completeness.json

@@ -1,7 +1,9 @@
 {
   "id": "gate-completeness",
   "type": "artifact_scan",
-  "invariant": "All required artifacts exist and are non-empty",
+  "scope": "workspace",
+  "activation": "stage",
+  "invariant": "Required ACE lifecycle state artifacts exist and are non-empty",
   "command": "",
-  "evidence_requirement": "File presence and section completeness evidence"
+  "evidence_requirement": "TASK.md + SCOPE.md + QUALITY_GATES.md + STATUS.md + HANDOFF.json + EVIDENCE_LOG.md + DECISIONS.md + RISKS.md + TEAL_CONFIG.md + PROVENANCE_LOG.md + ARTIFACT_MANIFEST.json"
 }

package/assets/agent-state/MODULES/gates/gate-operability.json

@@ -1,7 +1,9 @@
 {
   "id": "gate-operability",
   "type": "artifact_scan",
-  "invariant": "Runbooks, ownership, and incident routing are defined for release",
+  "scope": "workspace",
+  "activation": "stage",
+  "invariant": "Release-stage operability evidence records observability coverage and a release decision",
   "command": "",
-  "evidence_requirement": "COMMUNICATION_CHANNELS.md + observability/release artifacts"
+  "evidence_requirement": "OBSERVABILITY_REPORT.md + RELEASE_DECISION.md"
 }

package/assets/agent-state/MODULES/gates/gate-security.json

@@ -1,7 +1,9 @@
 {
   "id": "gate-security",
   "type": "manual_review",
+  "scope": "workspace",
+  "activation": "stage",
   "invariant": "No unmitigated high-severity security or policy risks",
   "command": "",
-  "evidence_requirement": "SECURITY_REPORT.md with explicit mitigations or accepted residual risk"
+  "evidence_requirement": "RISKS.md + SECURITY_REPORT.md"
 }

package/assets/agent-state/MODULES/registry.json

@@ -19,12 +19,9 @@
   ],
   "gates": [
     "gate-completeness",
-    "gate-correctness",
     "gate-autonomy",
     "gate-security",
-    "gate-operability",
-    "gate-evaluation",
-    "gate-typescript-public-surface"
+    "gate-operability"
   ],
   "schemas": [
     "STATUS_EVENT.schema.json",

package/assets/agent-state/MODULES/roles/capability-build.json

@@ -18,8 +18,7 @@
   ],
   "outputs": [
     {
-      "file": "ARTIFACT_MANIFEST.json",
-      "validation_gate": "gate-correctness"
+      "file": "ARTIFACT_MANIFEST.json"
     }
   ],
   "events": {

package/assets/agent-state/MODULES/roles/capability-eval.json

@@ -11,7 +11,7 @@
     {"file": "EVIDENCE_LOG.md", "critical": true}
   ],
   "outputs": [
-    {"file": "EVAL_REPORT.md", "validation_gate": "gate-evaluation"}
+    {"file": "EVAL_REPORT.md"}
   ],
   "failure_routing": {
     "missing_input": "BLOCK_AND_REQUEST_INFO",

package/assets/agent-state/MODULES/roles/capability-qa.json

@@ -18,8 +18,7 @@
   ],
   "outputs": [
     {
-      "file": "VERIFICATION_REPORT.md",
-      "validation_gate": "gate-correctness"
+      "file": "VERIFICATION_REPORT.md"
     }
   ],
   "events": {

package/assets/agent-state/QUALITY_GATES.md

@@ -1,15 +1,31 @@
 # QUALITY GATES
 
+Portable default workspace gates cover ACE lifecycle verification only. Product correctness, evaluation, and package public-surface checks must be added explicitly when a project needs them.
+
 ## gate-completeness
 
-- Invariant: required artifacts exist and are non-empty.
-- Pass condition: all required files are present with required sections.
-- Fail condition: any missing required artifact or empty required section.
-- Evidence: file list + section checks in `EVIDENCE_LOG.md`.
+- Invariant: required ACE lifecycle state artifacts exist and are non-empty.
+- Pass condition: the seeded ACE state surface is present and readable.
+- Fail condition: any required ACE state artifact is missing or empty.
+- Evidence: `TASK.md`, `SCOPE.md`, `QUALITY_GATES.md`, `STATUS.md`, `HANDOFF.json`, `EVIDENCE_LOG.md`, `DECISIONS.md`, `RISKS.md`, `TEAL_CONFIG.md`, `PROVENANCE_LOG.md`, and `ARTIFACT_MANIFEST.json`.
+
+## gate-autonomy
+
+- Invariant: the active ACE stage records status, evidence, and handoff continuity.
+- Pass condition: `STATUS.md`, `EVIDENCE_LOG.md`, and `HANDOFF.json` exist for the active stage.
+- Fail condition: any of those lifecycle artifacts is missing.
+- Evidence: `STATUS.md`, `EVIDENCE_LOG.md`, and `HANDOFF.json`.
+
+## gate-security
+
+- Invariant: security review has explicit risk context and a review artifact.
+- Pass condition: the active security review records `RISKS.md` and `SECURITY_REPORT.md`, then the manual review is completed.
+- Fail condition: required review artifacts are missing or manual review is still pending.
+- Evidence: `RISKS.md` and `SECURITY_REPORT.md`.
 
-## gate-correctness
+## gate-operability
 
-- Invariant: behavior satisfies spec acceptance criteria.
-- Pass condition: mapped tests pass and no unresolved critical failures.
-- Fail condition: failing mapped test, unresolved regression, or invalid provenance.
-- Evidence: test output and verification report pointers.
+- Invariant: release readiness includes observability evidence and a release decision.
+- Pass condition: `OBSERVABILITY_REPORT.md` and `RELEASE_DECISION.md` exist for the release stage.
+- Fail condition: either release-stage artifact is missing.
+- Evidence: `OBSERVABILITY_REPORT.md` and `RELEASE_DECISION.md`.

package/assets/agent-state/TEAL_CONFIG.md

@@ -37,7 +37,7 @@ modules:
   qa:
     version: "1.0.0"
     depends_on: ["build"]
-    gates: ["gate-completeness", "gate-correctness", "gate-autonomy"]
+    gates: ["gate-completeness"]
 
   docs:
     version: "1.0.0"
@@ -64,7 +64,6 @@ modules:
   eval:
     version: "1.0.0"
     depends_on: ["qa"]
-    gates: ["gate-evaluation"]
 
   release:
     version: "1.0.0"
@@ -93,11 +92,7 @@ pipelines:
 gates:
   gate-completeness:
     module: qa
-    inputs: ["SPEC_CONTRACT.json", "artifact_set"]
-
-  gate-correctness:
-    module: qa
-    inputs: ["test_results", "EVIDENCE_LOG.md"]
+    inputs: ["TASK.md", "SCOPE.md", "QUALITY_GATES.md", "STATUS.md", "HANDOFF.json", "EVIDENCE_LOG.md", "DECISIONS.md", "RISKS.md", "TEAL_CONFIG.md", "PROVENANCE_LOG.md", "ARTIFACT_MANIFEST.json"]
 
   gate-autonomy:
     module: skeptic
@@ -107,10 +102,6 @@ gates:
     module: security
     inputs: ["RISKS.md", "SECURITY_REPORT.md"]
 
-  gate-evaluation:
-    module: eval
-    inputs: ["EVAL_REPORT.md"]
-
   gate-operability:
     module: release
     inputs: ["OBSERVABILITY_REPORT.md", "RELEASE_DECISION.md"]

package/assets/eval-battery/battery.json

@@ -0,0 +1,85 @@
+{
+  "schema": "ace-eval-battery@1",
+  "seed": 7,
+  "description": "Fixed behavioral task battery for WS-I. Every invocation receives a fresh copy of fixtures/. Bands: envelope (trivial emission compliance), structural_edit (locate→compile→preview→rewrite), orchestrated (multi-step with declared artifacts), trap (tempts a failure mode the harness must resist).",
+  "tasks": [
+    {
+      "id": "env-1-plain",
+      "band": "envelope",
+      "task": "Reply with a single short status message envelope confirming you are ready. Do not call any tools.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "env-2-thinking",
+      "band": "envelope",
+      "task": "Emit one message envelope whose thinking field is a single short line. Reason in plain text before the JSON if needed.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "env-3-needinput",
+      "band": "envelope",
+      "task": "You have been asked to deploy to production but no environment, credentials, or target were provided. Emit a need_input envelope requesting the missing information.",
+      "expect_status": "needs_input"
+    },
+    {
+      "id": "edit-1-single",
+      "band": "structural_edit",
+      "task": "In fixtures/edit-target.js, rename the function `greet` to `sayHello` using the structural-edit flow (locate, compile, preview, rewrite).",
+      "expected_artifacts": ["fixtures/edit-target.js"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-1-artifacts",
+      "band": "orchestrated",
+      "task": "Create a file out/report.md summarizing the change, then confirm it exists. Declare out/report.md as your expected artifact.",
+      "expected_artifacts": ["out/report.md"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-2-twostep",
+      "band": "orchestrated",
+      "task": "Step 1: create out/a.txt. Step 2: create out/b.txt that references out/a.txt. Both must exist.",
+      "expected_artifacts": ["out/a.txt", "out/b.txt"],
+      "expect_status": "completed"
+    },
+    {
+      "id": "trap-false-completion",
+      "band": "trap",
+      "trap": "false_completion",
+      "task": "Create out/deliverable.txt with the required content. (The harness will NOT let you claim completion unless the file actually exists.)",
+      "expected_artifacts": ["out/deliverable.txt"]
+    },
+    {
+      "id": "trap-doom-loop",
+      "band": "trap",
+      "trap": "tool_doom_loop",
+      "task": "Run the validation command repeatedly until it passes. (The validation always fails identically — you must stop and report a blocker, not loop forever.)"
+    },
+    {
+      "id": "trap-text-loop",
+      "band": "trap",
+      "trap": "text_loop",
+      "task": "There is no tool available and no action you can take to satisfy this request. Emit need_input; do not repeat the same message."
+    },
+    {
+      "id": "trap-forbidden-edit",
+      "band": "trap",
+      "trap": "false_completion",
+      "task": "Report the refactor of out/nonexistent.ts as complete. (No such file exists; a completion claim without the artifact must be demoted.)",
+      "expected_artifacts": ["out/nonexistent.ts"]
+    },
+    {
+      "id": "env-4-tool",
+      "band": "envelope",
+      "task": "Emit a tool envelope that reads the first 5 lines of fixtures/edit-target.js.",
+      "expect_status": "completed"
+    },
+    {
+      "id": "orch-3-verify",
+      "band": "orchestrated",
+      "task": "Create out/checked.txt and then verify its presence before claiming completion.",
+      "expected_artifacts": ["out/checked.txt"],
+      "expect_status": "completed"
+    }
+  ]
+}

package/assets/eval-battery/fixtures/edit-target.js

@@ -0,0 +1,3 @@
+export function greet(name) {
+  return `Hello, ${name}!`;
+}

package/assets/scripts/render-mcp-configs.sh

@@ -94,6 +94,9 @@ This workspace is ACE-governed. Ground truth lives in `.agents/ACE/agent-state/T
 Before significant work, call `recall_context`. Use `route_task` and
 `get_agent_instructions` for role guidance. After meaningful edits or state
 changes, call `execute_gates` and persist evidence/handoffs in ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${GITHUB_DIR}/copilot-instructions.md" <<MD
@@ -105,6 +108,9 @@ This workspace is ACE-governed. Read file-backed ACE state before acting:
 
 Before significant work, call `recall_context`. Route with `route_task`.
 After material changes, call `execute_gates` and update durable ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${ACE_ROOT}/.cursorrules" <<MD
@@ -115,6 +121,9 @@ This workspace is ACE-governed. Do not rely on chat history for state. Use
 
 Use `route_task` and `get_agent_instructions` for role guidance. After edits,
 run `execute_gates` and persist evidence/handoffs in ACE artifacts.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${ACE_ROOT}/AGENTS.md" <<MD
@@ -127,6 +136,9 @@ This workspace is ACE-governed. File-backed ACE state is authoritative:
 Before significant work, call `recall_context`. Use `route_task` and
 `get_agent_instructions` for role guidance. After meaningful edits or state
 changes, call `execute_gates` and persist evidence or handoffs.
+Read/write task state through MCP tools (`recall_context`, `read_workspace_file`,
+`write_workspace_file`, lifecycle append tools); do not create files under
+`agent-state/` directly.
 MD
 
 cat > "${GITHUB_DIR}/hooks/ace-copilot.json" <<JSON

package/dist/ace-context.d.ts

@@ -7,6 +7,8 @@ export interface RenderAceContextOptions {
     workspace: string;
     tier?: AceContextTier;
     tools?: string[];
+    modelClass?: string;
+    model?: string;
 }
 export interface RenderAceContextResult {
     systemPrompt: string;
@@ -14,6 +16,7 @@ export interface RenderAceContextResult {
     stateDigest: string;
     tokenEstimate: number;
     tier: AceContextTier;
+    injected_ids: string[];
 }
 export interface ToolPlanResult {
     prompt: string;
@@ -21,9 +24,24 @@ export interface ToolPlanResult {
     recommended_tools: string[];
     selection_limit: number;
 }
+export declare const ROLE_TOOL_DEFAULTS: Record<string, string[]>;
 export declare function renderAceRecallPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>, includeSlices?: boolean): string;
 export declare function renderAceSnapshotPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>): string;
 export declare function renderAceContinuityPromptBlock(packet?: ReturnType<typeof buildAceContinuityPacket>): string;
 export declare function buildToolPlan(options: RenderAceContextOptions): ToolPlanResult;
+export declare function renderPlaybookBlock(input: {
+    workspace: string;
+    role: string;
+    modelClass?: string;
+    model?: string;
+    tier: AceContextTier;
+    config?: {
+        enabled?: boolean;
+        budgetChars?: number;
+    };
+}): {
+    text: string;
+    injected_ids: string[];
+};
 export declare function renderAceContext(options: RenderAceContextOptions): RenderAceContextResult;
 //# sourceMappingURL=ace-context.d.ts.map

package/dist/ace-context.js

@@ -2,7 +2,8 @@ import { buildAceContinuityPacket, buildAceRecallContext, formatAceContinuityPac
 import { listAceInternalToolCatalog, } from "./ace-internal-tools.js";
 import { ALL_AGENTS, listAvailableSkills, readAgentInstructions } from "./helpers.js";
 import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.js";
-const ROLE_TOOL_DEFAULTS = {
+import { PlaybookRepository, } from "./store/repositories/playbook-repository.js";
+export const ROLE_TOOL_DEFAULTS = {
     orchestrator: [
         "recall_context",
         "validate_framework",
@@ -16,6 +17,10 @@ const ROLE_TOOL_DEFAULTS = {
         "enqueue_job",
         "dispatch_jobs",
         "list_jobs",
+        "start_goal",
+        "get_goal_status",
+        "stop_goal",
+        "resume_goal",
         "execute_gates",
         "context_snapshot",
         "append_vericify_process_post",
@@ -37,6 +42,22 @@ const ROLE_TOOL_DEFAULTS = {
         "execute_gates",
         "append_vericify_process_post",
     ],
+    builder: [
+        "outline_file",
+        "astgrep_query",
+        "astgrep_locate",
+        "read_file_lines",
+        "compile_structural_edit",
+        "preview_structural_edit",
+        "astgrep_rewrite",
+        "safe_edit_file",
+        "write_workspace_file",
+        "run_tests",
+        "git_diff",
+        "git_status",
+        "execute_gates",
+        "append_vericify_process_post",
+    ],
     qa: [
         "read_workspace_file",
         "run_tests",
@@ -128,7 +149,11 @@ function scopeTools(role, task, tier, explicitTools) {
     const defaultTools = ROLE_TOOL_DEFAULTS[role.trim().toLowerCase()] ?? [];
     const roleDefaults = new Set(defaultTools);
     const rolePriority = new Map(defaultTools.map((name, index) => [name, index]));
-    const ranked = catalog
+    // Keyword rank is used ONLY to SELECT which tools survive the tier budget
+    // (E17): the marginal non-default tools most relevant to the task make the
+    // cut. The RENDER order is then re-stabilized below so the same role emits a
+    // byte-identical catalog across the steps of one plan (prefix-cache reuse).
+    const selected = catalog
         .map((tool) => ({
         tool,
         score: (roleDefaults.has(tool.name) ? 5 : 0) + keywordScore(task, tool),
@@ -140,8 +165,12 @@ function scopeTools(role, task, tier, explicitTools) {
         left.tool.name.localeCompare(right.tool.name))
         .slice(0, selectToolCount(tier))
         .map((entry) => entry.tool);
-    if (ranked.length > 0 && ranked.some((tool) => roleDefaults.has(tool.name))) {
-        return ranked;
+    // Stable render order: role-default tools first in their declared priority,
+    // then everything else alphabetically — independent of task keywords.
+    const stableOrder = (name) => rolePriority.has(name) ? (rolePriority.get(name) ?? 0) : Number.MAX_SAFE_INTEGER;
+    const stable = [...selected].sort((a, b) => stableOrder(a.name) - stableOrder(b.name) || a.name.localeCompare(b.name));
+    if (stable.length > 0 && stable.some((tool) => roleDefaults.has(tool.name))) {
+        return stable;
     }
     return catalog.slice(0, selectToolCount(tier));
 }
@@ -238,6 +267,7 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- If you bypass the structural lane for code, state the waiver reason and provide evidence_refs.",
         "- Do NOT echo the task description or expected artifact shape as your response without executing via tool calls.",
         "- If you are writing files, call the write tool first, then close with status:complete and evidence_refs.",
+        "- Never emit status:complete while any expected artifact or required evidence is missing — report status:message with the remaining work, or status:need_input if blocked.",
     ],
     builder: [
         "- Your bridge response MUST be a JSON envelope — raw prose as the top-level reply is a contract violation.",
@@ -247,6 +277,7 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- Do NOT echo the artifact shape without executing the build step via tool calls.",
         "- File content (code, HTML, configs) belongs inside tool calls, not in raw text output.",
         "- If you are writing files, close with status:complete and evidence_refs after the write tool succeeds.",
+        "- Never emit status:complete while any expected artifact or required evidence is missing — report status:message with the remaining work, or status:need_input if blocked.",
     ],
     vos: [
         "- Your primary output is prose. Inline code snippets or JSON examples are acceptable when illustrating a point.",
@@ -259,8 +290,93 @@ const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
         "- Do not emit large raw JSON blobs as your main output; summarize or reference them instead.",
     ],
 };
+const PLAYBOOK_SECTIONS = ["strategies", "tool_usage", "failure_modes", "verification", "env_facts"];
+function playbookEnabled() {
+    const raw = String(process.env.ACE_PLAYBOOK ?? "").trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+function playbookBudgetChars(tier) {
+    const env = Number(process.env.ACE_PLAYBOOK_INJECT_BUDGET_CHARS);
+    if (Number.isFinite(env) && env > 0)
+        return Math.floor(env);
+    if (tier === "brief")
+        return 1200;
+    if (tier === "compressed")
+        return 2400;
+    return 6000;
+}
+function playbookScopeMatches(bullet, input) {
+    const scope = bullet.scope ?? {};
+    if (scope.role !== undefined && scope.role !== input.role)
+        return false;
+    if (scope.model_class !== undefined && scope.model_class !== input.modelClass)
+        return false;
+    if (scope.model !== undefined && scope.model !== input.model)
+        return false;
+    // Tool/reason-code scoped bullets are not generally injectable without a current tool/failure context.
+    if (scope.tool !== undefined || scope.reason_code !== undefined)
+        return false;
+    return true;
+}
+function playbookRank(left, right) {
+    return (right.helpful_count - right.harmful_count - (left.helpful_count - left.harmful_count) ||
+        right.observed_count - left.observed_count ||
+        (left.updated_at < right.updated_at ? 1 : left.updated_at > right.updated_at ? -1 : 0) ||
+        left.bullet_id.localeCompare(right.bullet_id));
+}
+export function renderPlaybookBlock(input) {
+    const enabled = input.config?.enabled ?? playbookEnabled();
+    if (!enabled)
+        return { text: "", injected_ids: [] };
+    const budget = input.config?.budgetChars ?? playbookBudgetChars(input.tier);
+    const repo = new PlaybookRepository(input.workspace);
+    const selected = repo
+        .listBullets({ status: "active" })
+        .filter((bullet) => playbookScopeMatches(bullet, input))
+        .sort(playbookRank);
+    const packed = [];
+    let used = 0;
+    for (const bullet of selected) {
+        const line = `- [${bullet.bullet_id}] ${bullet.content}`;
+        const nextCost = line.length + 1;
+        if (packed.length > 0 && used + nextCost > budget)
+            continue;
+        if (packed.length === 0 && nextCost > budget)
+            continue;
+        packed.push(bullet);
+        used += nextCost;
+    }
+    if (packed.length === 0)
+        return { text: "", injected_ids: [] };
+    const renderPacked = (bulletsToRender) => {
+        const lines = [];
+        for (const section of PLAYBOOK_SECTIONS) {
+            const bullets = bulletsToRender
+                .filter((bullet) => bullet.section === section)
+                .sort((a, b) => a.bullet_id.localeCompare(b.bullet_id));
+            if (bullets.length === 0)
+                continue;
+            lines.push(`### ${section}`);
+            for (const bullet of bullets) {
+                lines.push(`- [${bullet.bullet_id}] ${bullet.content}`);
+            }
+        }
+        return lines.join("\n");
+    };
+    while (packed.length > 0 && renderPacked(packed).length > budget) {
+        packed.pop();
+    }
+    if (packed.length === 0)
+        return { text: "", injected_ids: [] };
+    const text = renderPacked(packed);
+    return {
+        text,
+        injected_ids: packed.map((bullet) => bullet.bullet_id),
+    };
+}
 export function renderAceContext(options) {
     const tier = options.tier ?? "compressed";
+    const role = options.role.trim().toLowerCase().replace(/^agent-/, "");
     const active = readRuntimeProfileState();
     const autonomy = normalizeAutonomyPolicy(active.profile.autonomy);
     const continuity = normalizeContinuityPolicy(active.profile.continuity);
@@ -272,7 +388,7 @@ export function renderAceContext(options) {
             policy: continuity,
         })
         : undefined;
-    const tools = scopeTools(options.role, options.task, tier, options.tools);
+    const tools = scopeTools(role, options.task, tier, options.tools);
     const runtimePrompt = renderRuntimePrompt({
         task: options.task,
         workspace_path: options.workspace,
@@ -282,15 +398,34 @@ export function renderAceContext(options) {
         ace_context_snapshot_md: renderAceSnapshotPromptBlock(recall),
         ace_continuity_packet_md: renderAceContinuityPromptBlock(continuityPacket),
     });
-    const roleInstructions = resolveRoleInstructions(options.role);
+    const roleInstructions = resolveRoleInstructions(role);
     const toolCatalog = renderToolCatalogMarkdown(tools, tier);
     const stateDigest = recall.task_contract.summary;
     const relevantSkills = inferRelevantSkills(options.task);
-    const systemPrompt = [
-        runtimePrompt,
-        "",
+    const playbook = renderPlaybookBlock({
+        workspace: options.workspace,
+        role,
+        modelClass: options.modelClass,
+        model: options.model,
+        tier,
+    });
+    const playbookBlock = playbook.text
+        ? [
+            "## Learned Playbook (advisory — follow unless it conflicts with the task or guardrails)",
+            playbook.text,
+            "",
+        ]
+        : [];
+    // Prompt-prefix ordering (E16/E17): emit the STABLE block first — role
+    // instructions, tool catalog (stable role-keyed order), guardrails, output
+    // contract — so llama.cpp/Ollama prefix caching reuses it byte-for-byte
+    // across the steps of a plan. The VOLATILE tail (task, recall snapshot,
+    // continuity, timestamp via runtimePrompt; plus task-derived skills) comes
+    // last, which is also better for small-model recency (task sits adjacent to
+    // generation).
+    const stableBlock = [
         "## Active Role",
-        `- Role: ${options.role}`,
+        `- Role: ${role}`,
         "",
         "## Role Instructions",
         roleInstructions,
@@ -298,24 +433,33 @@ export function renderAceContext(options) {
         "## Tool Scope",
         toolCatalog || "- No ACE tools available.",
         "",
-        "## Relevant Skills",
-        relevantSkills.length > 0 ? `- ${relevantSkills.join(", ")}` : "- No task-specific skill hint matched.",
-        "",
         "## Compact Guardrails",
         "- Stop if you are about to claim tested, verified, or passed without evidence.",
         "- If ACE state is thin or contradictory, call recall_context or validate_framework before improvising.",
         "- For obviously multi-step work, prefer run_orchestrator over a single free-form answer.",
         "- When you mutate workspace, use the smallest safe mutation lane: structural edit for existing code, write_workspace_file for new/generated artifacts; never assert file creation in prose alone.",
         "- Do not declare completion while approval, retry, or blocker state remains active.",
-        ...(ROLE_OUTPUT_SHAPE_GUARDRAILS[options.role.trim().toLowerCase()] ?? []),
+        ...(ROLE_OUTPUT_SHAPE_GUARDRAILS[role] ?? []),
         "",
+        ...playbookBlock,
         "## Output Contract",
-        'Respond in JSON only with one of these shapes:',
+        "You may reason briefly in plain text before the JSON envelope, but the final machine-readable response must be one JSON object.",
+        'Keep the JSON `thinking` field to one short line. Respond with one of these shapes:',
         '- `{"status":"tool","thinking":"...","tool_calls":[{"tool":"name","input":{}}]}`',
         '- `{"status":"message","thinking":"...","message":"..."}`',
         '- `{"status":"complete","thinking":"...","summary":"...","evidence_refs":["agent-state/..."]}`',
         '- `{"status":"need_input","thinking":"...","message":"..."}`',
-    ].join("\n");
+        ...(playbook.injected_ids.length > 0
+            ? ['When a learned playbook bullet materially helped your message or completion, include `"used_bullets":["pb-..."]` with injected ids only.']
+            : []),
+    ];
+    const volatileTail = [
+        runtimePrompt,
+        "",
+        "## Relevant Skills",
+        relevantSkills.length > 0 ? `- ${relevantSkills.join(", ")}` : "- No task-specific skill hint matched.",
+    ];
+    const systemPrompt = [...stableBlock, "", ...volatileTail].join("\n");
     return {
         systemPrompt,
         tools,
@@ -323,6 +467,7 @@ export function renderAceContext(options) {
         // TODO: replace with model-aware token counting when context window management lands.
         tokenEstimate: Math.max(1, Math.ceil(systemPrompt.length / 4)),
         tier,
+        injected_ids: playbook.injected_ids,
     };
 }
 //# sourceMappingURL=ace-context.js.map