karajan-code 3.3.0 → 3.4.1

package/src/prompts/coder.js

@@ -1,6 +1,7 @@
 import { buildRtkInstructions } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -179,7 +180,16 @@ function buildStackSection({ stack, testFramework }) {
   return lines.join("\n");
 }
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null, stack = null, testFramework = null }) {
+/**
+ * Build the coder prompt as a { stable, volatile } layout (Φ1, KJC-PCS-0057).
+ *
+ * stable: identical across iterations of the same HU and across HUs of the
+ * same plan — rendered FIRST so prefix-caching providers hit on it, and
+ * available separately so ClaudeAgent can ship it via --append-system-prompt.
+ * volatile: per-HU/iteration content, rendered LAST preserving the relative
+ * order the legacy prompt used (ADRs → SPEC → findings → tests → … → feedback).
+ */
+export async function buildCoderPromptLayout({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null, stack = null, testFramework = null }) {
   const langInstruction = getLanguageInstruction(language);
   // KJC-BUG-0032 (PR-I): hard rule about file paths. Real bug: a HU
   // titled "Initialize project skeleton: create assistant/ directory…"
@@ -203,110 +213,75 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
       ].join("\n")
     : null;
 
-  const sections = [
-    serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
-    ...(langInstruction ? [langInstruction] : []),
-    `Task:\n${task}`,
-    "Implement directly in the repository.",
-    "Keep changes minimal and production-ready.",
-    "Follow SOLID principles. Write small, focused functions (< 30 lines).",
-    "Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.",
-    "Security: validate all input, parameterize queries, never expose secrets. Use the auth pattern that matches the stack (e.g. httpOnly cookies for web sessions).",
-    "Use the project's standard logger and type system (no console.log when a structured logger exists; use the project's type idiom — TS types, JSDoc, Python type hints, Go interfaces…).",
-    SUBPROCESS_CONSTRAINTS
-  ];
   const stackRule = buildStackSection({ stack, testFramework });
-  if (stackRule) sections.push(stackRule);
-  if (projectDirRule) sections.push(projectDirRule);
-
-  if (serenaEnabled) {
-    sections.push(SERENA_INSTRUCTIONS);
-  }
-
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
-  if (rtkSnippet) {
-    sections.push(rtkSnippet);
-  }
-
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  if (plan) {
-    sections.push(`## Implementation Plan (from planner)\nFollow these steps:\n${plan}`);
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider });
   }
 
-  // PR F context injections — order matters:
+  // Volatile sections keep the legacy relative order — order matters:
   //   1. ADRs first (they constrain HOW you implement),
   //   2. SPEC reference (what section we're satisfying),
   //   3. Reviewer findings about THIS HU (warnings the coder needs
   //      to consider while writing code),
   //   4. Acceptance tests (the gate the implementation must pass).
-  // All four sit BEFORE coder rules / TDD policy so the policy
-  // frames them, not the other way around.
-  const adrSection = renderAdrSection(adrs);
-  if (adrSection) sections.push(adrSection);
-
-  const specSectionLine = renderSpecSectionLine(specSection);
-  if (specSectionLine) sections.push(specSectionLine);
-
-  const reviewerSection = renderReviewerFindingsSection(reviewerFindings, huId);
-  if (reviewerSection) sections.push(reviewerSection);
-
-  // Tests-first contract: the gate the implementation must pass.
-  const testsSection = renderAcceptanceTestsSection(acceptanceTests);
-  if (testsSection) {
-    sections.push(testsSection);
-  }
-
-  if (coderRules) {
-    sections.push(`Coder rules (MUST follow):\n${coderRules}`);
-  }
-
-  if (methodology === "tdd") {
-    sections.push(
-      [
-        "Default development policy: TDD.",
-        "1) Add or update failing tests first.",
-        "2) Implement minimal code to make tests pass.",
-        "3) Refactor safely while keeping tests green."
-      ].join("\n")
-    );
-  }
-
-  if (sonarSummary) {
-    sections.push(`Sonar summary:\n${sonarSummary}`);
-  }
-
-  if (reviewerFeedback) {
-    sections.push(
-      `## Reviewer blocking feedback — YOU MUST FIX THESE BEFORE PROCEEDING`,
-      reviewerFeedback,
-      "",
-      "For each issue above:",
-      "1. Find the relevant file(s) in the project",
-      "2. Make the specific code change needed to resolve the issue",
-      "3. If tests are missing, write them",
-      "4. If dependencies are needed, install them with the project's package manager (npm install / pip install / go get / cargo add — pick the one that matches the stack above)",
-      "5. Do NOT skip any issue — all must be resolved"
-    );
-  }
-
-  if (deferredContext) {
-    sections.push(deferredContext);
-  }
+  const reviewerFeedbackSection = reviewerFeedback
+    ? [
+        `## Reviewer blocking feedback — YOU MUST FIX THESE BEFORE PROCEEDING`,
+        reviewerFeedback,
+        "",
+        "For each issue above:",
+        "1. Find the relevant file(s) in the project",
+        "2. Make the specific code change needed to resolve the issue",
+        "3. If tests are missing, write them",
+        "4. If dependencies are needed, install them with the project's package manager (npm install / pip install / go get / cargo add — pick the one that matches the stack above)",
+        "5. Do NOT skip any issue — all must be resolved"
+      ].join("\n\n")
+    : null;
 
-  if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills, { provider });
-    if (skillSection) {
-      sections.push(skillSection);
-    }
-  }
+  return buildPromptLayout([
+    section(serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section("Implement directly in the repository.", STABLE),
+    section("Keep changes minimal and production-ready.", STABLE),
+    section("Follow SOLID principles. Write small, focused functions (< 30 lines).", STABLE),
+    section("Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.", STABLE),
+    section("Security: validate all input, parameterize queries, never expose secrets. Use the auth pattern that matches the stack (e.g. httpOnly cookies for web sessions).", STABLE),
+    section("Use the project's standard logger and type system (no console.log when a structured logger exists; use the project's type idiom — TS types, JSDoc, Python type hints, Go interfaces…).", STABLE),
+    section(SUBPROCESS_CONSTRAINTS, STABLE),
+    section(stackRule, STABLE),
+    section(projectDirRule, STABLE),
+    section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
+    section(rtkSnippet, STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(coderRules ? `Coder rules (MUST follow):\n${coderRules}` : null, STABLE),
+    section(
+      methodology === "tdd"
+        ? [
+            "Default development policy: TDD.",
+            "1) Add or update failing tests first.",
+            "2) Implement minimal code to make tests pass.",
+            "3) Refactor safely while keeping tests green."
+          ].join("\n")
+        : null,
+      STABLE
+    ),
+    section(skillSection, STABLE),
+    section(`Task:\n${task}`, VOLATILE),
+    section(plan ? `## Implementation Plan (from planner)\nFollow these steps:\n${plan}` : null, VOLATILE),
+    section(renderAdrSection(adrs) || null, VOLATILE),
+    section(renderSpecSectionLine(specSection) || null, VOLATILE),
+    section(renderReviewerFindingsSection(reviewerFindings, huId) || null, VOLATILE),
+    section(renderAcceptanceTestsSection(acceptanceTests) || null, VOLATILE),
+    section(sonarSummary ? `Sonar summary:\n${sonarSummary}` : null, VOLATILE),
+    section(reviewerFeedbackSection, VOLATILE),
+    section(deferredContext, VOLATILE),
+  ]);
+}
 
-  return sections.join("\n\n");
+export async function buildCoderPrompt(options) {
+  return joinLayout(await buildCoderPromptLayout(options));
 }

package/src/prompts/hu-reviewer.js

@@ -1,5 +1,6 @@
 import { extractFirstJson } from "../utils/json-extract.js";
 import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -22,38 +23,31 @@ const DIMENSION_KEYS = [
  * @param {{stories: Array<{id: string, text: string}>, instructions: string|null, context?: string|null}} params
  * @returns {string} The assembled prompt.
  */
-export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null, domainContext = null, hu_language = "en" }) {
+/**
+ * Build the HU-reviewer prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057): preamble, instructions, JSON schema and contexts are
+ * identical across batches on the same project; the stories under
+ * evaluation and the per-batch additional context go last.
+ */
+function buildHuReviewerPromptLayout({ stories, instructions, context = null, productContext = null, domainContext = null, hu_language = "en" }) {
   const langInstruction = getLanguageInstruction(hu_language);
-  const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
-
-  if (instructions) {
-    sections.push(instructions);
-  }
-
-  sections.push("## Stories to Evaluate");
-
-  for (const story of stories) {
-    sections.push(`### ${story.id}\n${story.text}`);
-  }
-
-  sections.push(
-    "Return a single valid JSON object and nothing else.",
-    `JSON schema: {"evaluations":[{"story_id":string,"scores":{"D1_jtbd_context":number,"D2_user_specificity":number,"D3_behavior_change":number,"D4_control_zone":number,"D5_time_constraints":number,"D6_survivable_experiment":number},"total":number,"antipatterns_detected":[string],"verdict":"certified|needs_rewrite|needs_context","evaluation_notes":string,"rewritten":object|null,"certified_hu":object|null,"context_needed":object|null}],"batch_summary":{"total":number,"certified":number,"needs_rewrite":number,"needs_context":number,"consolidated_questions":string}}`
-  );
 
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  if (context) {
-    sections.push(`## Additional Context\n${context}`);
-  }
+  return buildPromptLayout([
+    section(SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(instructions, STABLE),
+    section("Return a single valid JSON object and nothing else.", STABLE),
+    section(`JSON schema: {"evaluations":[{"story_id":string,"scores":{"D1_jtbd_context":number,"D2_user_specificity":number,"D3_behavior_change":number,"D4_control_zone":number,"D5_time_constraints":number,"D6_survivable_experiment":number},"total":number,"antipatterns_detected":[string],"verdict":"certified|needs_rewrite|needs_context","evaluation_notes":string,"rewritten":object|null,"certified_hu":object|null,"context_needed":object|null}],"batch_summary":{"total":number,"certified":number,"needs_rewrite":number,"needs_context":number,"consolidated_questions":string}}`, STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section("## Stories to Evaluate", VOLATILE),
+    ...stories.map((story) => section(`### ${story.id}\n${story.text}`, VOLATILE)),
+    section(context ? `## Additional Context\n${context}` : null, VOLATILE),
+  ]);
+}
 
-  return sections.join("\n\n");
+export function buildHuReviewerPrompt(options) {
+  return joinLayout(buildHuReviewerPromptLayout(options));
 }
 
 /**

package/src/prompts/planner.js

@@ -70,7 +70,7 @@ export function parsePlannerOutput(output) {
  * @param {string} task
  * @returns {string[]} deduplicated trimmed exclusion items
  */
-export function extractScopeExclusions(task) {
+function extractScopeExclusions(task) {
   if (!task || typeof task !== "string") return [];
   const patterns = [
     /\bNO\s+incluye[^:\n]{0,60}:\s*([^.\n]+)/gi,

package/src/prompts/prompt-layout.js

@@ -0,0 +1,80 @@
+/**
+ * Prompt layout helper — Phase 1 (KJC-PCS-0057, cache propio).
+ *
+ * Separates prompt sections into two buckets so every prompt builder can
+ * emit a cache-friendly shape:
+ *
+ *   - stable:   identical across iterations of the same HU and across HUs
+ *               of the same plan (preamble, rules, constraints, skills,
+ *               product/domain context). Goes FIRST in the rendered prompt
+ *               so providers with automatic prefix caching (OpenAI, Gemini,
+ *               LiteLLM-routed) hit on the literal prefix. For Anthropic,
+ *               agents can send this bucket via --append-system-prompt
+ *               where the CLI already places cache breakpoints.
+ *   - volatile: changes per HU/iteration (task, plan, acceptance tests,
+ *               reviewer feedback, diff). Goes LAST, preserving the
+ *               relative order the builder pushed it in — the semantic
+ *               ordering inside the bucket ("order matters" in coder.js)
+ *               is untouched.
+ *
+ * Tagging is explicit on purpose: an untagged section throws instead of
+ * silently landing in one bucket (a misclassified volatile section would
+ * silently break the byte-identical invariant the prefix cache relies on).
+ */
+
+export const STABLE = "stable";
+export const VOLATILE = "volatile";
+
+const SEPARATOR = "\n\n";
+
+/**
+ * Tag a section for buildPromptLayout. Returns null for empty/non-string
+ * content so builders can push conditional sections without guards.
+ *
+ * @param {string|null|undefined} content
+ * @param {"stable"|"volatile"} [stability]
+ * @returns {{content: string, stability: string}|null}
+ */
+export function section(content, stability = VOLATILE) {
+  if (typeof content !== "string" || content.length === 0) return null;
+  return { content, stability };
+}
+
+/**
+ * Split tagged sections into { stable, volatile } blocks. Insertion order
+ * is preserved within each bucket. Null/undefined entries are skipped.
+ *
+ * @param {Array<{content: string, stability: string}|null|undefined>} sections
+ * @returns {{stable: string, volatile: string}}
+ */
+export function buildPromptLayout(sections) {
+  const stable = [];
+  const volatile = [];
+  for (const entry of sections) {
+    if (entry == null) continue;
+    if (entry.stability === STABLE) {
+      stable.push(entry.content);
+    } else if (entry.stability === VOLATILE) {
+      volatile.push(entry.content);
+    } else {
+      throw new Error(
+        `prompt-layout: section has invalid stability tag "${entry?.stability}" — use section(content, STABLE|VOLATILE)`
+      );
+    }
+  }
+  return { stable: stable.join(SEPARATOR), volatile: volatile.join(SEPARATOR) };
+}
+
+/**
+ * Render a layout as a single prompt string: stable prefix first, volatile
+ * tail last. Used by agents whose provider caches on the literal token
+ * prefix (codex, gemini, aider, opencode).
+ *
+ * @param {{stable: string, volatile: string}} layout
+ * @returns {string}
+ */
+export function joinLayout({ stable, volatile }) {
+  if (!stable) return volatile;
+  if (!volatile) return stable;
+  return `${stable}${SEPARATOR}${volatile}`;
+}

package/src/prompts/reviewer.js

@@ -1,6 +1,7 @@
 import { buildRtkInstructions } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -24,51 +25,45 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+/**
+ * Build the reviewer prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057). The stable block (preamble, mode, scope rules, JSON
+ * schema, serena/rtk, contexts, review rules, skills) is identical
+ * across reviews of the same project, so prefix-caching providers hit
+ * on it; the per-review content (task context + git diff, up to 12 KB
+ * and always different) goes last.
+ */
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const langInstruction = getLanguageInstruction(language);
-  const sections = [
-    serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
-    ...(langInstruction ? [langInstruction] : []),
-    `You are a code reviewer in ${mode} mode.`,
-    "CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.",
-    "Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.",
-    "Return only one valid JSON object and nothing else.",
-    "JSON schema:",
-    '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}'
-  ];
-
-  if (serenaEnabled) {
-    sections.push(SERENA_INSTRUCTIONS);
-  }
-
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
-  if (rtkSnippet) {
-    sections.push(rtkSnippet);
-  }
-
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  sections.push(
-    `Task context:\n${task}`,
-    `Review rules:\n${reviewRules}`,
-    `Git diff:\n${truncatedDiff}`
-  );
-
+  let skillSection = null;
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
-    if (skillSection) {
-      sections.push(skillSection);
-    }
+    skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
   }
 
-  return sections.join("\n\n");
+  return buildPromptLayout([
+    section(serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(`You are a code reviewer in ${mode} mode.`, STABLE),
+    section("CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.", STABLE),
+    section("Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.", STABLE),
+    section("Return only one valid JSON object and nothing else.", STABLE),
+    section("JSON schema:", STABLE),
+    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
+    section(rtkSnippet, STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(`Review rules:\n${reviewRules}`, STABLE),
+    section(skillSection, STABLE),
+    section(`Task context:\n${task}`, VOLATILE),
+    section(`Git diff:\n${truncatedDiff}`, VOLATILE),
+  ]);
+}
+
+export async function buildReviewerPrompt(options) {
+  return joinLayout(await buildReviewerPromptLayout(options));
 }

package/src/rag/embedders/factory.js

@@ -27,4 +27,3 @@ export function makeEmbedder(config = {}) {
   return new spec.cls({ url: cfg.url, apiKey: cfg.api_key, model: cfg.model, dim, timeoutMs: cfg.timeout_ms });
 }
 
-export { PROVIDERS };

package/src/rag/retriever.js

@@ -124,4 +124,4 @@ export async function query(db, embedder, text, { topK = 5, scope = "all", kindB
   return reranked;
 }
 
-export { shouldBoostSources, isTestPath, fuseHits, cosineSim };
+export { fuseHits, cosineSim };

package/src/roles/agent-role.js

@@ -25,7 +25,7 @@ import { withBrainRecovery } from "../brain/with-brain-recovery.js";
  * @param {object} config
  * @returns {number|null}
  */
-export function resolveAgentSilenceTimeoutMs(config) {
+function resolveAgentSilenceTimeoutMs(config) {
   const minutes = Number(config?.session?.max_agent_silence_minutes);
   return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
 }
@@ -123,12 +123,20 @@ export class AgentRole extends BaseRole {
     const agent = this.createAgentInstance(provider);
 
     const promptResult = await this.buildPrompt(extracted);
-    const { prompt, onOutput } = typeof promptResult === "string"
+    const { prompt, onOutput, stablePrompt, volatilePrompt } = typeof promptResult === "string"
       ? { prompt: promptResult, onOutput: extracted.onOutput }
       : { onOutput: extracted.onOutput, ...promptResult };
 
     const runArgs = { prompt, role: this.name };
     if (onOutput) runArgs.onOutput = onOutput;
+    // Φ1-D (KJC-PCS-0057): roles that build their prompt as a
+    // stable/volatile layout forward both buckets so cache-aware agents
+    // (ClaudeAgent) can ship the stable block as system prompt. Agents
+    // that don't know the fields keep reading `prompt` as before.
+    if (stablePrompt && volatilePrompt) {
+      runArgs.stablePrompt = stablePrompt;
+      runArgs.volatilePrompt = volatilePrompt;
+    }
     // Kill a hung agent: without a silence timeout a coder / reviewer
     // that stalls with no output left `kj run` waiting indefinitely.
     // PlannerRole set this itself; every other role was unprotected.

package/src/roles/audit-role.js

@@ -205,11 +205,13 @@ export class AuditRole extends AgentRole {
  * result fields. Returns a single object so consumers (CLI formatter,
  * report-file writer, MCP) don't need to know about the spread shape.
  *
+ * Consumed by tests via vi.importActual (knip blind spot) — keep exported.
+ * @public
  * @param {object} result - raw agent.runTask() return
  * @param {{provider: string, durationMs: number}} ctx
- * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
+ * @returns {{available: boolean, provider: string, model?: string, tokens_in?: number, tokens_out?: number, cached_tokens?: number, total_tokens?: number, cost_usd?: number, durationMs: number, reason?: string}}
  */
-function extractUsage(result, { provider, durationMs }) {
+export function extractUsage(result, { provider, durationMs }) {
   if (!result || typeof result !== "object") {
     return { available: false, provider, durationMs, reason: "no agent result" };
   }
@@ -218,12 +220,18 @@ function extractUsage(result, { provider, durationMs }) {
   if (tokens_in === null && tokens_out === null) {
     return { available: false, provider, model: result.model, durationMs, reason: `provider "${provider}" did not report token usage` };
   }
+  // KJC-BUG-0085: cached_tokens must survive this consolidation — the
+  // budget chain (computeUsage → BudgetTracker → summary.md Cache hits →
+  // telemetry) reads it from `usage` and the audit is the most expensive
+  // role of the session.
+  const cached_tokens = Number.isFinite(result.cached_tokens) ? result.cached_tokens : 0;
   return {
     available: true,
     provider,
     model: result.model,
     tokens_in: tokens_in ?? 0,
     tokens_out: tokens_out ?? 0,
+    cached_tokens,
     total_tokens: (tokens_in ?? 0) + (tokens_out ?? 0),
     cost_usd: typeof result.cost_usd === "number" ? result.cost_usd : null,
     durationMs,

package/src/roles/coder-role.js

@@ -1,5 +1,6 @@
 import { AgentRole } from "./agent-role.js";
-import { buildCoderPrompt } from "../prompts/coder.js";
+import { buildCoderPromptLayout } from "../prompts/coder.js";
+import { joinLayout } from "../prompts/prompt-layout.js";
 import { isHostAgent } from "../utils/agent-detect.js";
 import { HostAgent } from "../agents/host-agent.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -66,7 +67,7 @@ export class CoderRole extends AgentRole {
       try { stack = await detectProjectStack(projectDir); } catch { /* best-effort */ }
       try { testFramework = await detectTestFramework(projectDir); } catch { /* best-effort */ }
     }
-    const prompt = await buildCoderPrompt({
+    const layout = await buildCoderPromptLayout({
       task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
       adrs, specSection, reviewerFindings, huId,
       coderRules: this.instructions,
@@ -79,7 +80,9 @@ export class CoderRole extends AgentRole {
       stack, testFramework,
       provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
     });
-    return { prompt };
+    // Φ1-D: prompt is the joined layout (identical for every agent);
+    // the buckets ride along so ClaudeAgent can system-split them.
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }
 
   buildSuccessResult(parsed, provider, agentResult) {

package/src/roles/reviewer-role.js

@@ -1,6 +1,7 @@
 import { AgentRole } from "./agent-role.js";
 import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -32,30 +33,26 @@ export class ReviewerRole extends AgentRole {
     };
   }
 
+  // Φ1-E (KJC-PCS-0057): stable block (preamble, instructions, mode,
+  // schema, contexts, rtk, review rules) first; task + diff — different
+  // on every review — last. The buckets ride along so ClaudeAgent can
+  // ship the stable block via --append-system-prompt (Φ1-D).
   async buildPrompt({ task, diff, reviewRules }) {
-    const sections = [SUBAGENT_PREAMBLE];
-    if (this.instructions) sections.push(this.instructions);
-    sections.push(
-      `You are a code reviewer in ${this.config?.review_mode || "standard"} mode.`,
-      "Return only one valid JSON object and nothing else.",
-      "JSON schema:",
-      '{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}',
-      `Task context:\n${task}`
-    );
-
-    const pc = this.config?.productContext;
-    if (pc) sections.push(`## Product Context\n${pc}`);
-    const dc = this.config?.domainContext;
-    if (dc) sections.push(`## Domain Context\n${dc}`);
-
-    const rtkSnippet = buildRtkInstructions({
-      rtkAvailable: Boolean(this.config?.rtk?.available)
-    });
-    if (rtkSnippet) sections.push(rtkSnippet);
-    if (reviewRules) sections.push(`Review rules:\n${reviewRules}`);
-    sections.push(`Git diff:\n${truncateDiff(diff)}`);
-
-    return { prompt: sections.join("\n\n") };
+    const layout = buildPromptLayout([
+      section(SUBAGENT_PREAMBLE, STABLE),
+      section(this.instructions, STABLE),
+      section(`You are a code reviewer in ${this.config?.review_mode || "standard"} mode.`, STABLE),
+      section("Return only one valid JSON object and nothing else.", STABLE),
+      section("JSON schema:", STABLE),
+      section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+      section(this.config?.productContext ? `## Product Context\n${this.config.productContext}` : null, STABLE),
+      section(this.config?.domainContext ? `## Domain Context\n${this.config.domainContext}` : null, STABLE),
+      section(buildRtkInstructions({ rtkAvailable: Boolean(this.config?.rtk?.available) }), STABLE),
+      section(reviewRules ? `Review rules:\n${reviewRules}` : null, STABLE),
+      section(`Task context:\n${task}`, VOLATILE),
+      section(`Git diff:\n${truncateDiff(diff)}`, VOLATILE),
+    ]);
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
   }
 
   parseOutput(raw) {