karajan-code 3.3.0 → 3.4.0

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/roles/agent-role.js

@@ -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/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) {