karajan-code 3.3.0 → 3.4.0

package/node_modules/yoctocolors/readme.md

@@ -0,0 +1,138 @@
+<sup>yoctocolors 🌈</sup>
+
+> The smallest and fastest command-line coloring package on the internet
+
+*Check out [Chalk](https://github.com/chalk/chalk) if you want something more mature and comprehensive.*
+
+## Highlights
+
+- Tiny
+- Fast
+- Handles nested colors
+- Tree-shakeable
+- No dependencies
+- Actively maintained
+
+## Install
+
+ESM:
+
+```sh
+npm install yoctocolors
+```
+
+Or CommonJS:
+
+```sh
+npm install yoctocolors-cjs
+```
+
+## Usage
+
+```js
+import colors from 'yoctocolors';
+
+console.log(colors.red('Yo!'));
+
+console.log(colors.blue(`Welcome to the ${colors.green('yoctocolors')} package!`));
+```
+
+You can also import colors as named imports:
+
+```js
+import {red, blue, green} from 'yoctocolors';
+
+console.log(red('Yo!'));
+
+console.log(blue(`Welcome to the ${green('yoctocolors')} package!`));
+```
+
+*This package supports [basic color detection](https://nodejs.org/api/tty.html#writestreamhascolorscount-env). Colors can be forcefully enabled by setting the `FORCE_COLOR` environment variable to `1` and can be forcefully disabled by setting `NO_COLOR` or `NODE_DISABLE_COLORS` to any value. [More info.](https://nodejs.org/api/tty.html#writestreamgetcolordepthenv)*
+
+## Styles
+
+### Modifiers
+
+- `reset` - Reset the current style.
+- `bold` - Make the text bold.
+- `dim` - Make the text have lower opacity.
+- `italic` - Make the text italic. *(Not widely supported)*
+- `underline` - Put a horizontal line above the text. *(Not widely supported)*
+- `overline` - Put a horizontal line below the text. *(Not widely supported)*
+- `inverse`- Invert background and foreground colors.
+- `hidden` - Print the text but make it invisible.
+- `strikethrough` - Put a horizontal line through the center of the text. *(Not widely supported)*
+
+### Colors
+
+- `black`
+- `red`
+- `green`
+- `yellow`
+- `blue`
+- `magenta`
+- `cyan`
+- `white`
+- `gray`
+- `redBright`
+- `greenBright`
+- `yellowBright`
+- `blueBright`
+- `magentaBright`
+- `cyanBright`
+- `whiteBright`
+
+### Background colors
+
+- `bgBlack`
+- `bgRed`
+- `bgGreen`
+- `bgYellow`
+- `bgBlue`
+- `bgMagenta`
+- `bgCyan`
+- `bgWhite`
+- `bgGray`
+- `bgRedBright`
+- `bgGreenBright`
+- `bgYellowBright`
+- `bgBlueBright`
+- `bgMagentaBright`
+- `bgCyanBright`
+- `bgWhiteBright`
+
+## Prior art
+
+Yes
+
+## Benchmark
+
+```sh
+$ ./benchmark.js
+┌─────────┬────────────────┬─────────────┐
+│ (index) │ library        │ ops/sec     │
+├─────────┼────────────────┼─────────────┤
+│ 0       │ 'yoctocolors'  │ '8,000,000' │
+│ 1       │ 'colorette'    │ '8,000,000' │
+│ 2       │ 'picocolors'   │ '8,000,000' │
+│ 3       │ 'nanocolors'   │ '5,988,024' │
+│ 4       │ 'chalk'        │ '4,807,692' │
+│ 5       │ 'kleur/colors' │ '4,807,692' │
+│ 6       │ 'kleur'        │ '4,784,689' │
+│ 7       │ 'ansi-colors'  │ '2,178,649' │
+│ 8       │ 'cli-color'    │ '585,138'   │
+└─────────┴────────────────┴─────────────┘
+```
+
+*See [benchmark.js](benchmark.js).*
+
+## FAQ
+
+### What is yocto?
+
+[It was the smallest official unit prefix in the metric system until 2022.](https://en.wikipedia.org/wiki/Yocto-) Much smaller than nano.
+
+## Related
+
+- [yoctodelay](https://github.com/sindresorhus/yoctodelay) - Delay a promise a given amount of time
+- [chalk](https://github.com/chalk/chalk) - Terminal string styling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -84,6 +84,7 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.7",
+    "@karajan/core": "*",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
@@ -99,6 +100,9 @@
     "valibot": "^1.4.1",
     "web-tree-sitter": "^0.26.9"
   },
+  "bundleDependencies": [
+    "@karajan/core"
+  ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.8",

package/src/agents/claude-agent.js

@@ -321,6 +321,21 @@ const ALLOWED_TOOLS = [
   "Read", "Write", "Edit", "Bash", "Glob", "Grep"
 ];
 
+/**
+ * Base CLI args for a task (Φ1-D, KJC-PCS-0057). When the role provides the
+ * prompt split in stable/volatile buckets, the stable block travels via
+ * --append-system-prompt — the CLI places cache breakpoints on the system
+ * block, so Anthropic's prompt cache hits on it across iterations — and only
+ * the volatile block goes in the -p message. Without the split, legacy
+ * single-prompt behavior is unchanged.
+ */
+function buildPromptArgs(task) {
+  if (task.stablePrompt && task.volatilePrompt) {
+    return ["-p", task.volatilePrompt, "--append-system-prompt", task.stablePrompt, "--allowedTools", ...ALLOWED_TOOLS];
+  }
+  return ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
+}
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -345,7 +360,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async _runTaskExec(task, model, _role) {
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS];
+    const args = buildPromptArgs(task);
     if (model) args.push("--model", model);
 
     // Use stream-json when onOutput is provided to get real-time feedback
@@ -373,7 +388,7 @@ export class ClaudeAgent extends BaseAgent {
   }
 
   async _reviewTaskExec(task, model) {
-    const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
+    const args = [...buildPromptArgs(task), "--output-format", "stream-json", "--verbose"];
     if (model) args.push("--model", model);
     const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,

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}`;
+}