karajan-code 3.2.0 → 3.4.0

package/src/agents/opencode-agent.js

@@ -1,6 +1,38 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/**
+ * Extract OpenAI-style `usage` from OpenCode stdout. With `--format json`
+ * (used in reviewTask) the CLI emits a JSON document; with LiteLLM-backed
+ * runs that document carries `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Accepts the whole payload, individual lines, or array elements with a
+ * nested `usage` object. Returns `{tokens_in, tokens_out, cached_tokens}`
+ * or null (= unmeasured).
+ */
+export function extractOpenCodeUsage(text) {
+  if (!text) return null;
+  const candidates = [text.trim()];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("{") || t.startsWith("[")) candidates.push(t);
+  }
+  for (const candidate of candidates) {
+    let obj;
+    try { obj = JSON.parse(candidate); } catch { continue; }
+    const usage = obj?.usage
+      ?? obj?.result?.usage
+      ?? (Array.isArray(obj) ? obj.find((e) => e?.usage)?.usage : null);
+    if (!usage || typeof usage.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: usage.prompt_tokens,
+      tokens_out: usage.completion_tokens ?? 0,
+      cached_tokens: usage.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  return null;
+}
+
 export class OpenCodeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -34,6 +66,7 @@ export class OpenCodeAgent extends BaseAgent {
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    const usage = extractOpenCodeUsage(res.stdout) ?? extractOpenCodeUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
   }
 }

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -316,8 +316,19 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
       await savePlanToDisk(projectDir, loadedPlan);
       if (outcome && Number.isFinite(outcome.cost_usd)) {
         try {
-          const { setStoryCost } = await import("../../../../packages/hu-board/src/db.js");
+          const { setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
           setStoryCost(huId, outcome.cost_usd);
+          // Φ0-G (KJC-TSK-0525): cached/in tokens travel in the same
+          // outcome blob as cost. Write them together so the board
+          // can render the "🎯 N% cached" badge on the same render.
+          // Either may be null (older runs, no cache) — setter handles it.
+          if (Number.isFinite(outcome.cached_tokens) || Number.isFinite(outcome.tokens_in)) {
+            setStoryCachedTokens(
+              huId,
+              Number.isFinite(outcome.cached_tokens) ? outcome.cached_tokens : null,
+              Number.isFinite(outcome.tokens_in) ? outcome.tokens_in : null,
+            );
+          }
         } catch (err) {
           logger?.warn?.(`Cost write failed for ${huId}: ${err.message}`);
         }

package/src/orchestrator/flow-runner.js

@@ -263,15 +263,23 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
 
     // --- Telemetry: anonymous pipeline_complete event (non-blocking) ---
     try {
-      const { sendTelemetryEvent } = await import("../utils/telemetry.js");
+      const { sendTelemetryEvent, computeCachedPct } = await import("../utils/telemetry.js");
       const durationS = Math.round((Date.now() - ctx.startedAt) / 1000);
       const sessionStatus = ctx.session?.status || "unknown";
+      // Φ0-H (KJC-TSK-0526): aggregate cache-hit ratios per role so we
+      // can see on the fleet how much each provider's cache is buying.
+      let cachedPct = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+      try {
+        const budgetSummary = ctx.budgetTracker?.summary?.();
+        if (budgetSummary) cachedPct = computeCachedPct(budgetSummary);
+      } catch { /* non-blocking — telemetry must never break runs */ }
       sendTelemetryEvent("pipeline_complete", {
         mode: config.review_mode,
         agent: ctx.coderRole?.provider || config.coder,
         duration_s: durationS,
         success: sessionStatus === "approved",
-        taskType: ctx.session?.resolved_policies?.taskType || null
+        taskType: ctx.session?.resolved_policies?.taskType || null,
+        ...cachedPct
       }, config).catch(() => {});
     } catch { /* non-blocking */ }
   }

package/src/orchestrator/hu-sub-pipeline.js

@@ -105,6 +105,31 @@ function sumCostUsd(entries) {
   return Math.round(total * 1e6) / 1e6;
 }
 
+/**
+ * Sum an integer token-counter field across a slice of BudgetTracker
+ * entries (Φ0-G, KJC-TSK-0525). Same null-vs-0 semantics as sumCostUsd:
+ * returns null when nothing measurable was recorded so the board can
+ * distinguish "unmeasured" from "really zero".
+ *
+ * @param {Array<object>} entries
+ * @param {string} field — entry key to sum, e.g. "cached_tokens"
+ * @returns {number|null}
+ */
+function sumTokenField(entries, field) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  let total = 0;
+  let hasAny = false;
+  for (const e of entries) {
+    const n = Number(e?.[field]);
+    if (Number.isFinite(n) && n >= 0) {
+      total += n;
+      hasAny = true;
+    }
+  }
+  if (!hasAny) return null;
+  return Math.round(total);
+}
+
 /**
  * Build the per-HU outcome blob from whatever metadata the iteration
  * loop returned. Tolerant by design — most fields are optional and we
@@ -157,6 +182,11 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
     blockers,
     summary,
     cost_usd: sumCostUsd(huBudgetEntries),
+    // Φ0-G (KJC-TSK-0525): cached/input tokens drive the "🎯 N% cached"
+    // board badge. Null when nothing measurable was recorded so the UI
+    // can hide the chip on cold runs or providers without cache.
+    cached_tokens: sumTokenField(huBudgetEntries, 'cached_tokens'),
+    tokens_in: sumTokenField(huBudgetEntries, 'tokens_in'),
     finishedAt: new Date().toISOString(),
   };
 }

package/src/prompts/architect.js

@@ -1,5 +1,6 @@
 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.",
@@ -9,19 +10,28 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+/**
+ * Build the architect prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057): instructions, guidelines, schema, contexts and skills
+ * are identical across invocations on the same project; research
+ * context and the task itself go last.
+ */
+export async function buildArchitectPromptLayout({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const langInstruction = getLanguageInstruction(language);
-  const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
-
-  if (instructions) {
-    sections.push(instructions);
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider, role: "architect" });
   }
 
-  sections.push(
-    "You are the architect in a multi-role AI pipeline.",
-    "Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.",
-    "## Architecture Guidelines",
-    [
+  return buildPromptLayout([
+    section(SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(instructions, STABLE),
+    section("You are the architect in a multi-role AI pipeline.", STABLE),
+    section("Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.", STABLE),
+    section("## Architecture Guidelines", STABLE),
+    section([
       "- Identify the architecture type (layered, microservices, event-driven, etc.)",
       "- Define the layers and their responsibilities",
       "- Identify design patterns to apply",
@@ -30,34 +40,19 @@ export async function buildArchitectPrompt({ task, instructions, researchContext
       "- List external and internal dependencies",
       "- Document tradeoffs and their rationale",
       "- If critical decisions cannot be made without more information, list clarifying questions"
-    ].join("\n"),
-    "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"verdict":"ready|needs_clarification","architecture":{"type":string,"layers":[string],"patterns":[string],"dataModel":{"entities":[string]},"apiContracts":[string],"dependencies":[string],"tradeoffs":[string]},"questions":[string],"summary":string}'
-  );
-
-  if (productContext) {
-    sections.push(`## Product Context\n${productContext}`);
-  }
-
-  if (domainContext) {
-    sections.push(`## Domain Context\n${domainContext}`);
-  }
-
-  if (researchContext) {
-    sections.push(`## Research Context\n${researchContext}`);
-  }
-
-  sections.push(`## Task\n${task}`);
-
-  if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills, { provider, role: "architect" });
-    if (skillSection) {
-      sections.push(skillSection);
-    }
-  }
+    ].join("\n"), STABLE),
+    section("Return a single valid JSON object and nothing else.", STABLE),
+    section('JSON schema: {"verdict":"ready|needs_clarification","architecture":{"type":string,"layers":[string],"patterns":[string],"dataModel":{"entities":[string]},"apiContracts":[string],"dependencies":[string],"tradeoffs":[string]},"questions":[string],"summary":string}', STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(skillSection, STABLE),
+    section(researchContext ? `## Research Context\n${researchContext}` : null, VOLATILE),
+    section(`## Task\n${task}`, VOLATILE),
+  ]);
+}
 
-  return sections.join("\n\n");
+export async function buildArchitectPrompt(options) {
+  return joinLayout(await buildArchitectPromptLayout(options));
 }
 
 function filterStrings(arr) {

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.
+ */
+export 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/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}`;
+}