karajan-code 2.7.3 → 2.8.0

package/src/prompts/coder.js

@@ -33,8 +33,155 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].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 }) {
+/**
+ * Render structured acceptance_tests (v2.7.5) as a Markdown section the
+ * coder reads as its contract. Legacy plain-string entries and
+ * structured { type, content, file? } objects are both accepted.
+ *
+ * The layout is intentional:
+ *   - Gherkin blocks preserve their newlines so the coder sees the
+ *     Given/When/Then scenarios as-is.
+ *   - Shell blocks are fenced so the coder can copy-paste to verify.
+ *   - The header says "MUST pass" because this is the gate the tester
+ *     role runs (phase 3) and refuses to approve without.
+ *
+ * @param {Array} tests
+ * @returns {string}
+ */
+function renderAcceptanceTestsSection(tests) {
+  if (!Array.isArray(tests) || tests.length === 0) return "";
+  const lines = [
+    "## Acceptance Tests — MUST pass before the HU can be approved",
+    "",
+    "These are the concrete contract for this task. The tester stage will execute them as the pass/fail gate — if any one fails, the HU is rejected. Write your implementation so each test passes.",
+    "",
+  ];
+  tests.forEach((entry, i) => {
+    // Normalise: accept legacy strings and structured objects.
+    let type = "shell";
+    let content;
+    let file = null;
+    if (typeof entry === "string") {
+      content = entry;
+    } else if (entry && typeof entry === "object") {
+      type = entry.type === "gherkin" ? "gherkin" : "shell";
+      content = typeof entry.content === "string" ? entry.content : JSON.stringify(entry);
+      file = typeof entry.file === "string" && entry.file.trim() ? entry.file.trim() : null;
+    } else {
+      content = String(entry ?? "");
+    }
+    const heading = file
+      ? `### Test ${i + 1} · \`${type}\` · target: \`${file}\``
+      : `### Test ${i + 1} · \`${type}\``;
+    lines.push(heading);
+    if (type === "gherkin") {
+      lines.push("```gherkin", content, "```", "");
+    } else {
+      lines.push("```bash", content, "```", "");
+    }
+  });
+  lines.push(
+    "If a test is ambiguous, implement what makes it pass AND add the clarifying assertion to the PR description — do NOT silently rewrite the test."
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Render the active ADRs (PR F) as a "MUST respect" preamble. Each
+ * ADR is shown verbatim — they're already in Nygard format
+ * (Context · Decision · Consequences) and the coder benefits from
+ * the full text, not a summary. Keeps the prompt size sane: caps at
+ * 8 ADRs (the planner shouldn't realistically emit more for one
+ * plan, but bound it just in case).
+ */
+function renderAdrSection(adrs) {
+  if (!Array.isArray(adrs) || adrs.length === 0) return "";
+  const capped = adrs.slice(0, 8);
+  const lines = [
+    "## Architecture Decision Records (active)",
+    "",
+    "These ADRs were committed by the architect role. Your implementation MUST respect them. If the SPEC asks for something incompatible with one of these, surface the conflict in your PR description rather than silently overriding the ADR.",
+    "",
+  ];
+  for (const adr of capped) {
+    lines.push(adr.markdown.trim(), "", "---", "");
+  }
+  if (adrs.length > capped.length) {
+    lines.push(`_(…${adrs.length - capped.length} more ADRs not shown — see ~/.kj/plans/<slug>/<planId>/adrs/.)_`, "");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * SPEC-section pointer (PR F). One short line. Lets the coder put
+ * "implements §X.Y of SPEC.md" in the PR description for traceability.
+ */
+function renderSpecSectionLine(specSection) {
+  if (!specSection) return "";
+  return [
+    "## SPEC reference",
+    "",
+    `This HU implements **§${specSection}** of the source SPEC. Cite this section in your PR description so the reviewer can trace coverage end-to-end.`,
+  ].join("\n");
+}
+
+/**
+ * Plan-reviewer findings relevant to this HU (PR F). The reviewer's
+ * output is plan-wide; we filter to entries that mention the
+ * current HU id so the coder gets only what's actionable for them.
+ */
+function renderReviewerFindingsSection(findings, huId) {
+  if (!findings || !huId) return "";
+  const items = [];
+  for (const md of findings.missing_dependencies || []) {
+    if (md.from === huId) items.push(`- This HU should depend on **${md.on}** — ${md.rationale}`);
+    else if (md.on === huId) items.push(`- HU **${md.from}** should depend on this one — ${md.rationale}`);
+  }
+  for (const ov of findings.scope_overlaps || []) {
+    if (Array.isArray(ov.between) && ov.between.includes(huId)) {
+      const others = ov.between.filter((id) => id !== huId);
+      items.push(`- Scope overlap with **${others.join(", ")}** — ${ov.rationale}`);
+    }
+  }
+  for (const oi of findings.order_issues || []) {
+    if (Array.isArray(oi.hus) && oi.hus.includes(huId)) {
+      items.push(`- Order issue (${oi.issue}): ${oi.rationale}`);
+    }
+  }
+  if (items.length === 0) return "";
+  return [
+    "## Reviewer findings about this HU",
+    "",
+    "The plan reviewer flagged the following — consider them while implementing:",
+    "",
+    ...items,
+  ].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 }) {
   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…"
+  // had Claude run `cd /home/manu/assistant && pnpm init …` and 36 MB
+  // of code landed in $HOME instead of inside projectDir. Reinforce
+  // the constraint at the prompt level (soft fix) AND enforce it
+  // post-coder via fs-leak-detector.js (hard fix).
+  const projectDirRule = projectDir
+    ? [
+        "## CRITICAL — Project directory boundary",
+        `The project root is **${projectDir}**. EVERY file you create, write, edit, mkdir or cd to MUST stay inside this directory.`,
+        "",
+        "Forbidden, regardless of what the task says:",
+        "- Absolute paths outside the project root (e.g. `/home/USER/something`, `/tmp/x`, `/etc/y`).",
+        "- `cd` to any directory outside the project root inside Bash commands.",
+        "- Creating sibling top-level directories under `$HOME`.",
+        "",
+        "If the task or HU title mentions a directory like `assistant/` or `app/`, treat it as RELATIVE to the project root. NEVER as an absolute path under $HOME.",
+        "",
+        "Karajan runs a deterministic post-coder guard that detects writes outside the project root and ABORTS the HU. If you ignore this rule the run will fail and your work will be discarded."
+      ].join("\n")
+    : null;
+
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     ...(langInstruction ? [langInstruction] : []),
@@ -47,6 +194,7 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
     "No console.log — use a structured logger. No 'any' types — use JSDoc annotations.",
     SUBPROCESS_CONSTRAINTS
   ];
+  if (projectDirRule) sections.push(projectDirRule);
 
   if (serenaEnabled) {
     sections.push(SERENA_INSTRUCTIONS);
@@ -69,6 +217,29 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
     sections.push(`## Implementation Plan (from planner)\nFollow these steps:\n${plan}`);
   }
 
+  // PR F context injections — 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}`);
   }

package/src/prompts/hu-reviewer.js

@@ -100,7 +100,6 @@ 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;
 
 /**

package/src/prompts/planner.js

@@ -1,3 +1,5 @@
+import { detectSpecSections } from "../plan/spec-detector.js";
+
 function extractStepText(line) {
   const numberedStep = /^\d+[).:-]\s*(.+)$/.exec(line);
   if (numberedStep) return numberedStep[1].trim();
@@ -64,7 +66,68 @@ function formatArchitectContext(architectContext) {
   return lines.length > 1 ? lines.join("\n") : null;
 }
 
+/**
+ * Render the SPEC-section guidance block for the planner.
+ *
+ * Two modes:
+ *   • the task contains numbered headings (`## 1.`, `### 2.1`, `§5`) →
+ *     spec_section becomes a HARD requirement and the detected
+ *     sections are echoed back as a checklist. LLMs (Sonnet, Codex)
+ *     consistently skipped the soft "preferred" wording, so the only
+ *     reliable lever is to (a) escalate the rule to MUST and (b) hand
+ *     them the literal list of section refs they're allowed to cite.
+ *   • no numbered headings detected → spec_section stays optional
+ *     and the prompt simply explains the field for completeness.
+ */
+function renderSpecSectionRules(specInfo) {
+  if (!specInfo.hasSpec) {
+    return [
+      "### `spec_section` (optional)",
+      "The task does not look like a structured SPEC, so this field may be `null`. If you do cite a section, use a short ref like `\"5.3\"` or `\"§5 Initial Scope\"`.",
+    ].join("\n");
+  }
+  const checklist = specInfo.sectionList
+    .map(({ section, title }) => `  - "${section}" — ${title}`)
+    .join("\n");
+  return [
+    "### `spec_section` (REQUIRED — the task is a structured SPEC)",
+    `Detected ${specInfo.sections.length} numbered SPEC heading(s) in the task. Every \`step\` MUST set \`spec_section\` to one of the refs below — string, exactly as listed. NEVER \`null\`, NEVER omitted, NEVER a free-form paraphrase.`,
+    "",
+    "Allowed values:",
+    checklist,
+    "",
+    "If a step covers multiple sections, pick the most specific one (e.g. prefer `\"2.1\"` over `\"2\"`). If a step does not map to any section, refactor the step so it does — the SPEC is the source of truth for what work belongs in this plan.",
+  ].join("\n");
+}
+
+/**
+ * Render the acceptance_tests guidance block — same contract as
+ * planner-role.js (the orchestrator path) so both entry points
+ * produce comparable plans.
+ */
+function renderAcceptanceTestsRules() {
+  return [
+    "### `acceptance_tests` (REQUIRED — at least one test per step)",
+    "Each step MUST include 2-4 executable tests. Mix `gherkin` (observable behaviour) and `shell` (concrete commands that exit 0).",
+    "",
+    "Shape:",
+    "```json",
+    '"acceptance_tests": [',
+    '  { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+    '  { "type": "shell",   "content": "<bash command that exits 0 on success>" }',
+    "]",
+    "```",
+    "",
+    "Rules:",
+    "- Tests are written BEFORE the step is implemented — they should fail until the step is done, pass afterwards.",
+    "- Cover at least one happy path and one edge case / failure mode.",
+    "- Do NOT use the placeholder `\"npx vitest run\"` — every test must assert something specific to the step.",
+  ].join("\n");
+}
+
 export function buildPlannerPrompt({ task, context, architectContext, productContext = null, domainContext = null }) {
+  const specInfo = detectSpecSections(task);
+
   const parts = [
     "You are an expert software architect. Create an implementation plan for the following task.",
     "",
@@ -93,10 +156,24 @@ export function buildPlannerPrompt({ task, context, architectContext, productCon
   parts.push(
     "## Output format",
     "Respond with a JSON object containing:",
-    "- `approach`: A concise paragraph describing the overall strategy",
-    "- `steps`: An array of objects, each with `description` (what to do) and `commit` (conventional commit message). Each step should correspond to a single commit.",
-    "- `risks`: An array of strings describing potential risks or challenges",
-    "- `outOfScope`: An array of strings listing what is explicitly NOT included",
+    "- `approach`: A concise paragraph describing the overall strategy.",
+    "- `steps`: An array of step objects (see shape below). Each step = one commit.",
+    "- `risks`: An array of strings describing potential risks or challenges.",
+    "- `outOfScope`: An array of strings listing what is explicitly NOT included.",
+    "",
+    "Each step in `steps` has this shape:",
+    "```json",
+    "{",
+    '  "description": "<what this step achieves, one sentence>",',
+    '  "commit": "<conventional commit message>",',
+    '  "spec_section": "<see rules below>",',
+    '  "acceptance_tests": [ /* see rules below */ ]',
+    "}",
+    "```",
+    "",
+    renderSpecSectionRules(specInfo),
+    "",
+    renderAcceptanceTestsRules(),
     "",
     "Respond ONLY with valid JSON, no markdown fences or extra text."
   );

package/src/review/diff-generator.js

@@ -1,5 +1,11 @@
 import { runCommand } from "../utils/process.js";
 import { generateSnapshotDiff } from "./snapshot-diff.js";
+import { getRunContext } from "../utils/run-context.js";
+
+// Module-scope back-compat state for callers outside a `withRunContext`
+// scope. When inside a pipeline, `getRunContext()` provides per-run
+// isolation (TSK-0338) — the module-level values below are only consulted
+// as a last resort.
 
 /** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
 let _runner = null;
@@ -10,35 +16,39 @@ let _snapshot = null;
 /** @type {string|null} — project directory scope for git diff (prevents leaking unrelated changes) */
 let _projectDir = null;
 
-/**
- * Set the project directory scope. When set, all diffs are scoped to this directory.
- * Call once at pipeline start when projectDir differs from repo root.
- * @param {string|null} dir
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ projectDir })` for isolation. */
 export function setProjectDir(dir) {
   _projectDir = dir;
 }
 
-/**
- * Store a filesystem snapshot for git-free diff fallback.
- * Call before the coder runs. If git is available, this is unused.
- * @param {Map<string, string>} snapshot
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ snapshot })` for isolation. */
 export function setSnapshot(snapshot) {
   _snapshot = snapshot;
 }
 
-/**
- * Inject an RTK-aware runner so all git operations in this module benefit from token savings.
- * Call once at pipeline start when RTK is available.
- * @param {(command: string, args?: string[], options?: object) => Promise<object>} runner
- */
+/** Retained for back-compat; pipelines should use `withRunContext({ runner })` for isolation. */
 export function setRunner(runner) {
   _runner = runner;
 }
 
+function resolveRunner() {
+  return getRunContext()?.runner || _runner || runCommand;
+}
+
+function resolveProjectDir() {
+  const ctx = getRunContext();
+  if (ctx && "projectDir" in ctx) return ctx.projectDir;
+  return _projectDir;
+}
+
+function resolveSnapshot() {
+  const ctx = getRunContext();
+  if (ctx && "snapshot" in ctx) return ctx.snapshot;
+  return _snapshot;
+}
+
 function run(command, args, ...rest) {
-  return (_runner || runCommand)(command, args, ...rest);
+  return resolveRunner()(command, args, ...rest);
 }
 
 export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
@@ -61,8 +71,9 @@ export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
 }
 
 export async function generateDiff({ baseRef, stageNewFiles = false, projectDir = null }) {
-  // Auto-resolve projectDir from config if not passed explicitly
-  const scopeDir = projectDir || _projectDir || null;
+  // Auto-resolve projectDir from run context (TSK-0338) or module fallback
+  const scopeDir = projectDir || resolveProjectDir() || null;
+  const snapshot = resolveSnapshot();
 
   // Try git diff first
   try {
@@ -80,14 +91,16 @@ export async function generateDiff({ baseRef, stageNewFiles = false, projectDir
   } catch { /* git not available or failed */ }
 
   // Fallback: snapshot-based diff (no git needed)
-  if (_snapshot) {
+  if (snapshot) {
     const dir = projectDir || process.cwd();
-    return generateSnapshotDiff(_snapshot, null, dir);
+    return generateSnapshotDiff(snapshot, null, dir);
   }
 
-  // No git and no snapshot — generate diff of all files as new
+  // No git and no snapshot — generate diff of all files as new.
+  // TSK-0340: dropped a stray `const { takeSnapshot } = await import(...)`
+  // that was never used in this branch (we synthesize an empty Map and
+  // let generateSnapshotDiff do the file walk itself).
   const dir = projectDir || process.cwd();
-  const { takeSnapshot } = await import("./snapshot-diff.js");
   const emptySnapshot = new Map();
   return generateSnapshotDiff(emptySnapshot, null, dir);
 }

package/src/review/snapshot-diff.js

@@ -67,7 +67,7 @@ export async function generateSnapshotDiff(before, after, rootDir) {
   const lines = [];
 
   // New files (in after but not before)
-  for (const [path, hash] of after) {
+  for (const [path, _hash] of after) {
     if (!before.has(path)) {
       const content = await safeRead(join(rootDir, path));
       if (content !== null) {

package/src/roles/coder-role.js

@@ -22,19 +22,41 @@ export class CoderRole extends AgentRole {
   }
 
   extractInput(input) {
-    if (typeof input === "string") return { task: input, reviewerFeedback: null, sonarSummary: null, deferredContext: null, onOutput: null };
+    if (typeof input === "string") {
+      return {
+        task: input,
+        reviewerFeedback: null, sonarSummary: null, deferredContext: null,
+        acceptanceTests: null,
+        adrs: null, specSection: null, reviewerFindings: null, huId: null,
+        onOutput: null
+      };
+    }
     return {
       task: input?.task || this.context?.task || "",
       reviewerFeedback: input?.reviewerFeedback || null,
       sonarSummary: input?.sonarSummary || null,
       deferredContext: input?.deferredContext || null,
+      // Tests-first (v2.7.5): the coder reads these as the gate it
+      // must satisfy. Only the plan-backed HU path populates this;
+      // the standard single-task `kj run` flow leaves it null.
+      acceptanceTests: input?.acceptanceTests || null,
+      // PR F (v2.7.5): per-HU planning context. ADRs constrain HOW,
+      // specSection ties this HU to a SPEC heading, reviewerFindings
+      // are filtered to entries that mention this HU. All four are
+      // null for non-plan-backed runs, which keeps the legacy flow
+      // byte-for-byte identical.
+      adrs: Array.isArray(input?.adrs) ? input.adrs : null,
+      specSection: input?.specSection || null,
+      reviewerFindings: input?.reviewerFindings || null,
+      huId: input?.huId || null,
       onOutput: input?.onOutput || null
     };
   }
 
-  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext }) {
+  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId }) {
     const prompt = await buildCoderPrompt({
-      task, reviewerFeedback, sonarSummary, deferredContext,
+      task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
+      adrs, specSection, reviewerFindings, huId,
       coderRules: this.instructions,
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled),

package/src/roles/planner-role.js

@@ -65,7 +65,48 @@ export class PlannerRole extends AgentRole {
 
     const sections = [];
     if (this.instructions) sections.push(this.instructions, "");
-    sections.push("Create an implementation plan for this task.", "Return concise numbered steps focused on execution order and risk.", "");
+    // Tests-first planning (v2.7.5):
+    // The planner MUST emit structured acceptance tests for every step.
+    // These are the contract the coder is handed (phase 2 of the
+    // tests-first flow); the tester role later runs them as the
+    // pass/fail gate. Without them the coder has no executable spec.
+    sections.push(
+      "Create an implementation plan for this task as structured JSON.",
+      "",
+      "Output MUST be a JSON object with this exact shape:",
+      "",
+      "```json",
+      "{",
+      '  "approach": "<2-3 sentence high-level plan>",',
+      '  "risks": ["<risk 1>", "<risk 2>"],',
+      '  "outOfScope": ["<excluded item>"],',
+      '  "steps": [',
+      "    {",
+      '      "description": "<what this step achieves, one sentence>",',
+      '      "spec_section": "<short reference to the SPEC section this implements, e.g. \\"5.3\\" or \\"§5 Initial Scope\\". Optional but strongly preferred.>",',
+      '      "acceptance_tests": [',
+      '        { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+      '        { "type": "shell", "content": "<bash command that must exit 0>" }',
+      "      ]",
+      "    }",
+      "  ]",
+      "}",
+      "```",
+      "",
+      "Rules for acceptance_tests (CRITICAL — this is the contract the coder must satisfy):",
+      '- EVERY step MUST have at least one acceptance_test. No empty arrays.',
+      '- "gherkin" tests describe observable behaviour in natural language. Use them for end-to-end or user-facing assertions.',
+      '- "shell" tests are bash commands that exit 0 on success. Use them for concrete verifications (file exists, lint passes, specific exit code, HTTP status).',
+      '- Write tests BEFORE the step is implemented — they should fail until the step is done, pass afterwards.',
+      '- Prefer 2-4 tests per step: one happy-path, at least one edge case / failure path.',
+      '- Do NOT use the generic fallback "npx vitest run" (pre-v2.7.5 placeholder). Each test must assert something specific to the step.',
+      "",
+      "spec_section: when the task includes a structured SPEC (numbered headings like '## 5. Initial Scope'), every step MUST cite the section it implements. Becomes traceability metadata for the coder and reviewer.",
+      "",
+      "Steps must be ordered so that each depends only on previous steps (the first step has no prerequisites).",
+      "Return ONLY the JSON — no prose, no markdown fences around it.",
+      ""
+    );
     if (this.config?.productContext) sections.push("## Product Context", this.config.productContext, "");
     if (this.config?.domainContext) sections.push("## Domain Context", this.config.domainContext, "");
     appendDecompositionSection(sections, triageDecomposition);