karajan-code 1.32.1 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.32.1",
+  "version": "1.33.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/orchestrator/pipeline-context.js

@@ -37,6 +37,9 @@ export class PipelineContext {
     this.pgProject = null;
     this.pgCard = null;
 
+    // Product context (loaded from .karajan/context.md or product-vision.md)
+    this.productContext = null;
+
     // Planned task (may differ from original task after planner)
     this.plannedTask = null;
 

package/src/orchestrator.js

@@ -1,3 +1,5 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 import { createAgent } from "./agents/index.js";
 import {
   createSession,
@@ -39,6 +41,29 @@ import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
 import { detectRtk } from "./utils/rtk-detect.js";
 
 
+// --- Product Context loader ---
+
+/**
+ * Load product context from well-known file locations.
+ * Returns the file content or null if no file is found.
+ * @param {string|null} projectDir
+ * @returns {Promise<{content: string|null, source: string|null}>}
+ */
+export async function loadProductContext(projectDir) {
+  const base = projectDir || process.cwd();
+  const candidates = [
+    path.join(base, ".karajan", "context.md"),
+    path.join(base, "product-vision.md")
+  ];
+  for (const file of candidates) {
+    try {
+      const content = await fs.readFile(file, "utf8");
+      return { content, source: file };
+    } catch { /* not found, try next */ }
+  }
+  return { content: null, source: null };
+}
+
 // --- Extracted helper functions (pure refactoring, zero behavior change) ---
 
 function resolvePipelineFlags(config) {
@@ -71,8 +96,8 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
   const projectDir = config.projectDir || process.cwd();
   const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
   const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available) });
-  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available) });
+  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
+  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
 
   const summary = {
     dry_run: true,
@@ -1099,6 +1124,18 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
     }));
   }
 
+  // --- Product Context ---
+  const ctxProjectDir = config.projectDir || process.cwd();
+  const { content: productContext, source: productContextSource } = await loadProductContext(ctxProjectDir);
+  if (productContext) {
+    config = { ...config, productContext };
+    logger.info(`Product context loaded from ${productContextSource}`);
+    emitProgress(emitter, makeEvent("context:loaded", ctx.eventBase, {
+      message: "Product context loaded",
+      detail: { source: productContextSource }
+    }));
+  }
+
   ctx.session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
   ctx.eventBase.sessionId = ctx.session.id;
 

package/src/prompts/architect.js

@@ -6,7 +6,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export function buildArchitectPrompt({ task, instructions, researchContext = null }) {
+export function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -31,6 +31,10 @@ export function buildArchitectPrompt({ task, instructions, researchContext = nul
     '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 (researchContext) {
     sections.push(`## Research Context\n${researchContext}`);
   }

package/src/prompts/coder.js

@@ -31,7 +31,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null }) {
+export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -48,6 +48,10 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(RTK_INSTRUCTIONS);
   }
 
+  if (productContext) {
+    sections.push(`## Product Context\n${productContext}`);
+  }
+
   if (coderRules) {
     sections.push(`Coder rules (MUST follow):\n${coderRules}`);
   }

package/src/prompts/hu-reviewer.js

@@ -19,7 +19,7 @@ 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 }) {
+export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -37,6 +37,10 @@ export function buildHuReviewerPrompt({ stories, instructions, context = null })
     `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 (context) {
     sections.push(`## Additional Context\n${context}`);
   }
@@ -88,6 +92,43 @@ function parseEvaluation(raw) {
   };
 }
 
+const VALID_AC_FORMATS = new Set(["gherkin", "checklist", "pre_post", "invariant"]);
+const AC_PREFIX_RE = /^\[(GHERKIN|CHECKLIST|PRE_POST|INVARIANT)]\s*/i;
+
+/**
+ * Detect the format of a single acceptance criterion.
+ * Supports both prefixed strings ("[GHERKIN] Given...") and legacy Gherkin objects ({given, when, then}).
+ * @param {string|object} criterion
+ * @returns {{format: string, text: string}}
+ */
+export function detectAcFormat(criterion) {
+  if (typeof criterion === "object" && criterion !== null && ("given" in criterion || "when" in criterion || "then" in criterion)) {
+    const text = `Given ${criterion.given || "..."}, When ${criterion.when || "..."}, Then ${criterion.then || "..."}`;
+    return { format: "gherkin", text };
+  }
+  if (typeof criterion === "string") {
+    const match = AC_PREFIX_RE.exec(criterion);
+    if (match) {
+      const format = match[1].toLowerCase();
+      const text = criterion.slice(match[0].length);
+      return { format, text };
+    }
+    return { format: "checklist", text: criterion };
+  }
+  return { format: "checklist", text: String(criterion) };
+}
+
+/**
+ * Normalize an acceptance_criteria array to a uniform structure.
+ * Handles both legacy Gherkin objects and prefixed strings.
+ * @param {Array} criteria
+ * @returns {Array<{format: string, text: string}>}
+ */
+export function normalizeAcceptanceCriteria(criteria) {
+  if (!Array.isArray(criteria)) return [];
+  return criteria.map(detectAcFormat);
+}
+
 /**
  * Parse the raw output from the HU reviewer agent.
  * @param {string} raw - Raw text output from the agent.

package/src/prompts/planner.js

@@ -64,7 +64,7 @@ function formatArchitectContext(architectContext) {
   return lines.length > 1 ? lines.join("\n") : null;
 }
 
-export function buildPlannerPrompt({ task, context, architectContext }) {
+export function buildPlannerPrompt({ task, context, architectContext, productContext = null }) {
   const parts = [
     "You are an expert software architect. Create an implementation plan for the following task.",
     "",
@@ -73,6 +73,10 @@ export function buildPlannerPrompt({ task, context, architectContext }) {
     ""
   ];
 
+  if (productContext) {
+    parts.push("## Product Context", productContext, "");
+  }
+
   if (context) {
     parts.push("## Context", context, "");
   }

package/src/prompts/reviewer.js

@@ -22,7 +22,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false }) {
+export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const sections = [
@@ -43,6 +43,10 @@ export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabl
     sections.push(RTK_INSTRUCTIONS);
   }
 
+  if (productContext) {
+    sections.push(`## Product Context\n${productContext}`);
+  }
+
   sections.push(
     `Task context:\n${task}`,
     `Review rules:\n${reviewRules}`,

package/src/roles/architect-role.js

@@ -59,7 +59,7 @@ export class ArchitectRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildArchitectPrompt({ task, instructions: this.instructions, researchContext });
+    const prompt = buildArchitectPrompt({ task, instructions: this.instructions, researchContext, productContext: this.config?.productContext || null });
     const runArgs = { prompt, role: "architect" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/coder-role.js

@@ -42,7 +42,8 @@ export class CoderRole extends BaseRole {
       coderRules: this.instructions,
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled),
-      rtkAvailable: Boolean(this.config?.rtk?.available)
+      rtkAvailable: Boolean(this.config?.rtk?.available),
+      productContext: this.config?.productContext || null
     });
 
     const coderArgs = { prompt, role: "coder" };

package/src/roles/hu-reviewer-role.js

@@ -52,7 +52,7 @@ export class HuReviewerRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context });
+    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context, productContext: this.config?.productContext || null });
     const runArgs = { prompt, role: "hu-reviewer" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/planner-role.js

@@ -63,7 +63,7 @@ function appendArchitectSection(sections, architectContext) {
   sections.push("");
 }
 
-function buildPrompt({ task, instructions, research, triageDecomposition, architectContext }) {
+function buildPrompt({ task, instructions, research, triageDecomposition, architectContext, productContext = null }) {
   const sections = [];
 
   if (instructions) {
@@ -76,6 +76,10 @@ function buildPrompt({ task, instructions, research, triageDecomposition, archit
     ""
   );
 
+  if (productContext) {
+    sections.push("## Product Context", productContext, "");
+  }
+
   appendDecompositionSection(sections, triageDecomposition);
   appendArchitectSection(sections, architectContext);
   appendResearchSection(sections, research);
@@ -102,7 +106,7 @@ export class PlannerRole extends BaseRole {
     const provider = resolveProvider(this.config);
 
     const agent = this._createAgent(provider, this.config, this.logger);
-    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition, architectContext });
+    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition, architectContext, productContext: this.config?.productContext || null });
 
     const runArgs = { prompt, role: "planner" };
     if (onOutput) runArgs.onOutput = onOutput;

package/src/roles/reviewer-role.js

@@ -25,7 +25,7 @@ function truncateDiff(diff) {
     : diff;
 }
 
-function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false }) {
+function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false, productContext = null }) {
   const sections = [];
 
   sections.push(SUBAGENT_PREAMBLE);
@@ -42,6 +42,10 @@ function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAva
     `Task context:\n${task}`
   );
 
+  if (productContext) {
+    sections.push(`## Product Context\n${productContext}`);
+  }
+
   if (rtkAvailable) {
     sections.push(RTK_INSTRUCTIONS);
   }
@@ -84,7 +88,8 @@ export class ReviewerRole extends BaseRole {
       reviewRules: reviewRules || null,
       reviewMode: this.config?.review_mode || "standard",
       instructions: this.instructions,
-      rtkAvailable: Boolean(this.config?.rtk?.available)
+      rtkAvailable: Boolean(this.config?.rtk?.available),
+      productContext: this.config?.productContext || null
     });
 
     const reviewArgs = { prompt, role: "reviewer" };

package/templates/roles/architect.md

@@ -12,6 +12,7 @@ You are the **Architect** in a multi-role AI pipeline. Your job is to design the
 - List internal and external dependencies
 - Document tradeoffs and their rationale
 - Flag areas where clarification is needed before implementation
+- Evaluate if the project benefits from containerization (Docker/Docker Compose) for development consistency and deployment, and recommend it in the architecture output if appropriate
 
 ## Verdict
 

package/templates/roles/hu-reviewer.md

@@ -100,6 +100,46 @@ The HU depends on other work, APIs, or decisions that are not documented.
 The HU optimizes something without evidence that it is a real problem.
 - Example: "Cache all API responses to improve performance." (Is performance actually a problem? Where is the data?)
 
+## Acceptance Criteria Format
+
+Choose the format that best fits the task type:
+
+### For user-facing behavior → Gherkin
+Use Given/When/Then when the task describes observable user behavior:
+- Given [precondition], When [action], Then [observable result]
+
+### For technical tasks → Verifiable Checklist
+Use when the task is implementation/refactoring without new user behavior:
+- [ ] Module exports function X with signature Y
+- [ ] All existing tests still pass
+- [ ] Build time does not exceed N seconds
+
+### For infrastructure → Pre/Post Conditions
+Use when the task changes system configuration or environment:
+- Before: [current state]
+- After: [target state with measurable criteria]
+
+### For refactors → Invariants
+Use when the task changes internal structure without changing external behavior:
+- External behavior unchanged (same API, same outputs)
+- Test coverage does not decrease below X%
+- Zero regressions in existing test suite
+- [Specific quality metric maintained or improved]
+
+### Selection rule
+Classify the task FIRST, then apply the matching format:
+- If the HU starts with "As a [user role]" and describes user action → Gherkin
+- If it's about internal code structure, performance, or technical debt → Checklist or Invariants
+- If it's about infrastructure, deployment, or environment → Pre/Post Conditions
+- When in doubt, use Checklist — it's the most universal format
+
+### Prefixing convention
+When writing acceptance criteria, prefix each criterion with the format tag:
+- `[GHERKIN] Given X, When Y, Then Z`
+- `[CHECKLIST] Function exported as named export from src/validate.js`
+- `[PRE_POST] Before: no cache layer; After: Redis cache with TTL 300s`
+- `[INVARIANT] All existing tests still pass after changes`
+
 ## Rewrite Instructions
 
 When a HU scores below certification threshold but has enough information to improve:
@@ -108,7 +148,7 @@ When a HU scores below certification threshold but has enough information to imp
 2. Make the user more specific (D2)
 3. Add quantification where possible (D3)
 4. Clarify boundaries (D4)
-5. Add acceptance criteria in Given/When/Then format
+5. Add acceptance criteria using the appropriate format (see Acceptance Criteria Format above)
 6. Flag what you assumed vs. what was in the original
 
 **Never invent business requirements.** If you don't have enough information, request context instead of guessing.
@@ -124,8 +164,10 @@ When a HU is certified, produce it in this structured format:
   "want": "single, focused behavior change",
   "so_that": "measurable business outcome with quantification",
   "acceptance_criteria": [
-    {"given": "...", "when": "...", "then": "..."},
-    {"given": "...", "when": "...", "then": "..."}
+    "[GHERKIN] Given precondition, When action, Then result",
+    "[CHECKLIST] Specific verifiable criterion",
+    "[PRE_POST] Before: X; After: Y",
+    "[INVARIANT] Behavior unchanged, tests pass"
   ],
   "boundaries": {
     "in_scope": ["..."],
@@ -137,6 +179,8 @@ When a HU is certified, produce it in this structured format:
 }
 ```
 
+Note: `acceptance_criteria` supports both legacy Gherkin objects (`{"given":"...","when":"...","then":"..."}`) and prefixed strings. Use prefixed strings for new evaluations.
+
 ## Output Format
 
 Return a single valid JSON object with this schema: