karajan-code 2.7.4 → 2.9.0

package/src/planning-game/pipeline-adapter.js

@@ -12,7 +12,8 @@
  */
 
 import { emitProgress, makeEvent } from "../utils/events.js";
-import { addCheckpoint, saveSession } from "../session-store.js";
+import { addCheckpoint } from "../session/store.js";
+import { appendPgCommits } from "../session/mutators.js";
 import { getLang } from "../utils/messages.js";
 
 /**
@@ -28,7 +29,7 @@ import { getLang } from "../utils/messages.js";
  * @param {string|null} opts.pgProject - Planning Game project ID
  * @returns {{ pgCard: object|null }} The fetched PG card (or null)
  */
-export async function initPgAdapter({ session, config, logger, pgTaskId, pgProject }) {
+export async function initPgAdapter({ session: _session, config, logger, pgTaskId, pgProject }) {
   if (!pgTaskId || !pgProject || config.planning_game?.enabled === false) {
     return { pgCard: null };
   }
@@ -41,7 +42,7 @@ export async function initPgAdapter({ session, config, logger, pgTaskId, pgProje
  * Handle PG task decomposition after triage.
  * Creates subtask cards in PG when triage recommends decomposition.
  */
-export async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger }) {
+async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger }) {
   const shouldDecompose = triageResult.stageResult?.shouldDecompose
     && triageResult.stageResult.subtasks?.length > 1
     && pgTaskId
@@ -183,13 +184,12 @@ export function buildHuStoriesFromPgCard(pgCard) {
  */
 export function accumulateCommit(session, commitInfo) {
   if (!session || !commitInfo?.hash) return;
-  if (!session.pg_commits) session.pg_commits = [];
-  session.pg_commits.push({
+  appendPgCommits(session, [{
     hash: commitInfo.hash,
     message: commitInfo.message || "",
     date: commitInfo.date || new Date().toISOString(),
     author: commitInfo.author || "Karajan"
-  });
+  }]);
 }
 
 // --- Internal helpers ---
@@ -218,3 +218,34 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
     return null;
   }
 }
+
+/**
+ * TSK-0339: integration adapter shape — the orchestrator consumes tracker
+ * hooks via this neutral interface, not via direct imports. `registerPgAdapter`
+ * is called once at bootstrap when `config.planning_game.enabled` is true,
+ * wiring these hooks into `src/orchestrator/integrations.js` under the
+ * "tracker" slot.
+ *
+ * Adding a new tracker (GitHub Projects, Jira, Linear, …) means creating
+ * a sibling `src/adapters/<name>/adapter.js` with the same hook surface,
+ * nothing else in the orchestrator changes.
+ */
+export const planningGameAdapter = {
+  name: "planning-game",
+  async onSessionStart(opts) { return initPgAdapter(opts); },
+  onCommit(session, commit) { accumulateCommit(session, commit); },
+  async onSessionApproved(opts) { return markPgCardToValidate(opts); },
+  buildHuStoriesFromCard(card) { return buildHuStoriesFromPgCard(card); },
+  async handleDecomposition(opts) { return handlePgDecomposition(opts); },
+  async createAdrsFromTradeoffs({ tradeoffs, pgTaskId, pgProject, taskTitle }) {
+    // Lazy-loaded to avoid pulling createArchitectADRs into every import.
+    const { createArchitectADRs } = await import("./architect-adrs.js");
+    const pgClient = await import("./client.js");
+    return createArchitectADRs({ tradeoffs, pgTaskId, pgProject, taskTitle, mcpClient: pgClient });
+  },
+};
+
+export async function registerPgAdapter() {
+  const { registerIntegration } = await import("../orchestrator/integrations.js");
+  registerIntegration("tracker", planningGameAdapter);
+}

package/src/prompts/audit.js

@@ -1,4 +1,12 @@
 import { extractFirstJson } from "../utils/json-extract.js";
+import { groupIssuesBySeverity } from "../audit/sonar-findings.js";
+import { groupVulnerabilitiesBySeverity } from "../audit/osv-findings.js";
+import { groupFindingsBySeverity as groupSemgrepBySeverity } from "../audit/semgrep-findings.js";
+import { formatCwvVerdict } from "../audit/webperf-input.js";
+
+const MAX_SONAR_ISSUES_IN_PROMPT = 50;
+const MAX_OSV_VULNS_IN_PROMPT = 50;
+const MAX_SEMGREP_FINDINGS_IN_PROMPT = 50;
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -7,14 +15,20 @@ const SUBAGENT_PREAMBLE = [
   "DO NOT modify any files — this is a read-only analysis. Only use: Read, Grep, Glob, Bash (for analysis commands like wc, find, git log, du, npm ls)."
 ].join(" ");
 
-export const AUDIT_DIMENSIONS = ["security", "codeQuality", "performance", "architecture", "testing"];
+export const AUDIT_DIMENSIONS = ["security", "codeQuality", "performance", "architecture", "testing", "accessibility"];
+
+// Dimensions that only apply to frontend / fullstack projects. Auto-dropped
+// from the default dimension list when stack detection knows the project
+// is backend-only — preserves activation when the user explicitly opts in
+// via --dimensions=accessibility (KJC-TSK-0359).
+const FRONTEND_ONLY_DIMENSIONS = new Set(["accessibility"]);
 
 const VALID_HEALTH = new Set(["good", "fair", "poor", "critical"]);
 const VALID_SCORES = new Set(["A", "B", "C", "D", "F"]);
 const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low"]);
 const VALID_IMPACT = new Set(["high", "medium", "low"]);
 
-export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null }) {
+export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null, stack = null, sonarFindings = null, webperf = null, osvFindings = null, semgrepFindings = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -27,9 +41,46 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     "DO NOT modify any files. This is a READ-ONLY analysis."
   );
 
-  const activeDimensions = dimensions
-    ? dimensions.filter(d => AUDIT_DIMENSIONS.includes(d))
-    : AUDIT_DIMENSIONS;
+  // Stack hint — when detected, tells the LLM what kind of project this is
+  // so it can filter out irrelevant heuristics (e.g. don't flag bundle size
+  // in an Express-only API; don't flag N+1 queries in a static Astro site).
+  // Detected by src/utils/stack-detect.js — KJC-TSK-0358.
+  if (stack && (stack.frameworks?.length > 0 || stack.language || stack.isFrontend || stack.isBackend)) {
+    const stackLines = ["## Project Stack"];
+    if (stack.language) stackLines.push(`- Language: ${stack.language}`);
+    if (stack.frameworks?.length) stackLines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+    const tier = stack.isFullstack
+      ? "fullstack (frontend + backend)"
+      : stack.isFrontend
+        ? "frontend-only"
+        : stack.isBackend
+          ? "backend-only"
+          : "unknown";
+    stackLines.push(`- Tier: ${tier}`);
+    if (stack.isFullstack) {
+      stackLines.push("Apply BOTH backend heuristics (queries, sync I/O, caching) AND frontend heuristics (bundle size, lazy loading, render-blocking) where each layer applies.");
+    } else if (stack.isFrontend) {
+      stackLines.push("This project is frontend-only. SKIP findings about N+1 queries, sync file I/O in request handlers, missing pagination on list endpoints, and other backend-specific patterns. Focus on bundle size, lazy loading, render-blocking resources, image optimisation, and accessibility hints.");
+    } else if (stack.isBackend) {
+      stackLines.push("This project is backend-only. SKIP findings about bundle size, lazy loading, render-blocking resources, image optimisation, and frontend accessibility. Focus on queries, sync I/O, pagination, caching, auth/authz, and dependency hygiene.");
+    }
+    sections.push(stackLines.join("\n"));
+  }
+
+  // When dimensions are explicit, honour them verbatim — even frontend-only
+  // dimensions on a backend project (the user knows what they want).
+  // When dimensions are absent, default to all but drop frontend-only
+  // dimensions if the stack is provably backend-only. Unknown stack falls
+  // back to the full list (no false negatives — better an extra section
+  // than a missing one).
+  let activeDimensions;
+  if (dimensions) {
+    activeDimensions = dimensions.filter(d => AUDIT_DIMENSIONS.includes(d));
+  } else if (stack && stack.isBackend && !stack.isFrontend) {
+    activeDimensions = AUDIT_DIMENSIONS.filter(d => !FRONTEND_ONLY_DIMENSIONS.has(d));
+  } else {
+    activeDimensions = AUDIT_DIMENSIONS;
+  }
 
   if (activeDimensions.includes("security")) {
     sections.push(
@@ -105,9 +156,32 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     );
   }
 
+  if (activeDimensions.includes("accessibility")) {
+    sections.push(
+      "## Accessibility Analysis (WCAG 2.x)",
+      [
+        "- Missing alt text on <img> tags (decorative images need empty alt=\"\", not absent)",
+        "- Form inputs without associated <label> or aria-label",
+        "- Heading hierarchy violations (h1 → h3 skipping h2; multiple h1 per page)",
+        "- Buttons / links containing only icons without aria-label or visually-hidden text",
+        "- Interactive elements built from <div>/<span> without role + keyboard handlers",
+        "- ARIA roles misused (presentation on focusable elements, redundant on native semantics)",
+        "- Focus management gaps (modals without focus trap, no visible :focus styles, tabindex misuse)",
+        "- Colour-only signalling (status indicated by red/green only, no icon or text)",
+        "- Static contrast — flag suspicious low-contrast colour pairs in CSS variables / token files",
+        "- Missing lang attribute on <html>, missing skip-to-content link, missing landmarks"
+      ].join("\n"),
+      "Skip findings about colour contrast that require runtime rendering (e.g. computed styles); flag the suspect CSS values and recommend an axe-core/Lighthouse runtime check."
+    );
+  }
+
+  // JSON schema — keep the per-dimension entries in sync with AUDIT_DIMENSIONS.
+  const schemaDimensions = AUDIT_DIMENSIONS
+    .map(d => `"${d}":{"score":"A|B|C|D|F","findings":[]}`)
+    .join(",");
   sections.push(
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{"security":{"score":"A|B|C|D|F","findings":[]},"codeQuality":{"score":"A|B|C|D|F","findings":[]},"performance":{"score":"A|B|C|D|F","findings":[]},"architecture":{"score":"A|B|C|D|F","findings":[]},"testing":{"score":"A|B|C|D|F","findings":[]}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}',
+    `JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{${schemaDimensions}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}`,
     'Each finding: {"severity":"critical|high|medium|low","file":string,"line":number,"rule":string,"description":string,"recommendation":string}',
     `Only include dimensions you were asked to analyze: ${activeDimensions.join(", ")}`
   );
@@ -146,6 +220,132 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     sections.push(lines.join("\n"));
   }
 
+  // Sonar findings — KJC-TSK-0361. Deterministic input from a tool the
+  // codebase already runs (kj run + SonarStage). The audit reads existing
+  // open issues + quality-gate state instead of re-scanning. Capped at
+  // MAX_SONAR_ISSUES_IN_PROMPT total entries (50) across all severities to
+  // bound prompt size; the LLM is told the truncated count so it can
+  // prioritise.
+  if (sonarFindings?.available && (sonarFindings.total > 0 || sonarFindings.qualityGate)) {
+    const lines = ["## SonarQube Findings"];
+    if (sonarFindings.qualityGate?.status) {
+      lines.push(`- Quality gate: ${sonarFindings.qualityGate.status}`);
+    }
+    if (sonarFindings.total > 0) {
+      lines.push(`- Total open issues: ${sonarFindings.total}`);
+      const groups = groupIssuesBySeverity(sonarFindings.issues);
+      let remaining = MAX_SONAR_ISSUES_IN_PROMPT;
+      for (const [severity, issues] of Object.entries(groups)) {
+        if (issues.length === 0) continue;
+        lines.push("");
+        lines.push(`### ${severity} (${issues.length})`);
+        const slice = issues.slice(0, Math.max(0, remaining));
+        for (const issue of slice) {
+          const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+          const rule = issue.rule ? ` [${issue.rule}]` : "";
+          lines.push(`  - ${loc}${rule} ${issue.message || ""}`.trim());
+        }
+        if (issues.length > slice.length) {
+          lines.push(`  - ... and ${issues.length - slice.length} more in ${severity}`);
+        }
+        remaining -= slice.length;
+      }
+    }
+    lines.push("");
+    lines.push("Cross-reference these with your own findings. When your finding overlaps a Sonar rule, mention the rule ID in the `rule` field — that's a high-confidence match. Findings the LLM raises that Sonar can't see (architecture, naming, API design) are still valuable; mark them with rule names like \"AUDIT-ARCH-N\".");
+    sections.push(lines.join("\n"));
+  }
+
+  // WebPerf — KJC-TSK-0360. Two modes: a real CWV measurement when one is
+  // surfaced via config.webperf.lastResult (future `kj webperf` command)
+  // OR static frontend-perf hints for the LLM to look at the source code
+  // when no live measurement is available. Backend-only projects skip the
+  // section entirely (collectWebPerfInput returns available:false).
+  if (webperf?.available) {
+    const lines = ["## WebPerf — Frontend Performance"];
+    if (webperf.mode === "cwv-result") {
+      lines.push("Live Core Web Vitals measurement available — incorporate the verdict below into the performance dimension findings:");
+      lines.push("");
+      lines.push(formatCwvVerdict(webperf));
+      lines.push("");
+      lines.push("If a metric is `poor`, recommend a concrete code change (preconnect, lazy-load, image format, critical CSS, defer script). Cite the offending file or pattern when you can find it in the source.");
+    } else {
+      lines.push("No live CWV measurement was provided. Audit the source for these static frontend-perf patterns and include findings under the `performance` dimension:");
+      lines.push("");
+      lines.push("- Render-blocking `<link rel=\"stylesheet\">` or `<script>` without `defer`/`async` in `<head>`");
+      lines.push("- Large JavaScript bundles imported eagerly that could be `await import(...)` or split by route");
+      lines.push("- Non-modern image formats (only .jpg/.png) where webp/avif are widely supported");
+      lines.push("- `<img>` without `width`/`height` attributes (causes CLS)");
+      lines.push("- `<img>` without `loading=\"lazy\"` for off-screen images, or videos auto-playing without `preload=\"metadata\"`");
+      lines.push("- Web fonts loaded without `font-display: swap` or without `<link rel=\"preconnect\">` to the font origin");
+      lines.push("- Whole-library imports for one helper (e.g. `import _ from 'lodash'` instead of `lodash/get`)");
+      lines.push("- Missing critical CSS extraction or above-the-fold inlining strategy in build config");
+      lines.push("- Large third-party scripts (analytics, A/B, chat widgets) without defer + facade pattern");
+      lines.push("- Unbounded list rendering without virtualisation for very long collections");
+    }
+    sections.push(lines.join("\n"));
+  }
+
+  // OSV vulnerabilities — KJC-TSK-0365. Deterministic CVE/GHSA findings
+  // from osv-scanner across the dependency manifest. Capped at
+  // MAX_OSV_VULNS_IN_PROMPT entries; the LLM is told the truncated count.
+  // Findings fold into the `security` dimension with the upstream
+  // identifier (CVE-/GHSA-) as the rule.
+  if (osvFindings?.available && (osvFindings.total > 0)) {
+    const lines = ["## OSV Vulnerabilities"];
+    lines.push(`- Total open vulnerabilities in dependencies: ${osvFindings.total}`);
+    const groups = groupVulnerabilitiesBySeverity(osvFindings.vulnerabilities);
+    let remaining = MAX_OSV_VULNS_IN_PROMPT;
+    for (const [severity, vulns] of Object.entries(groups)) {
+      if (vulns.length === 0) continue;
+      lines.push("");
+      lines.push(`### ${severity} (${vulns.length})`);
+      const slice = vulns.slice(0, Math.max(0, remaining));
+      for (const vuln of slice) {
+        const where = vuln.package ? `${vuln.package}@${vuln.version || "?"}` : "(unknown package)";
+        const fixed = vuln.fixed ? ` → fixed in ${vuln.fixed}` : "";
+        lines.push(`  - ${vuln.id} ${where}${fixed}: ${vuln.summary || ""}`.trim());
+      }
+      if (vulns.length > slice.length) {
+        lines.push(`  - ... and ${vulns.length - slice.length} more in ${severity}`);
+      }
+      remaining -= slice.length;
+    }
+    lines.push("");
+    lines.push("These CVE/GHSA findings are GROUND TRUTH — incorporate them into the `security` dimension. Use the OSV id (CVE-XXXX-XXXX or GHSA-xxxx-xxxx-xxxx) as the `rule` field. Recommend the fixed version when available.");
+    sections.push(lines.join("\n"));
+  }
+
+  // Semgrep SAST findings — KJC-TSK-0366. Static analysis catches what
+  // sonar/CVE-DBs miss: SQL/Cmd injection, XSS, hardcoded secrets,
+  // taint flow, language-specific anti-patterns. Capped at
+  // MAX_SEMGREP_FINDINGS_IN_PROMPT entries; LLM is told these are
+  // deterministic and asked to use rule IDs as-is in findings.
+  if (semgrepFindings?.available && semgrepFindings.total > 0) {
+    const lines = ["## Semgrep SAST Findings"];
+    lines.push(`- Total findings: ${semgrepFindings.total}`);
+    const groups = groupSemgrepBySeverity(semgrepFindings.findings);
+    let remaining = MAX_SEMGREP_FINDINGS_IN_PROMPT;
+    for (const [severity, findings] of Object.entries(groups)) {
+      if (findings.length === 0) continue;
+      lines.push("");
+      lines.push(`### ${severity} (${findings.length})`);
+      const slice = findings.slice(0, Math.max(0, remaining));
+      for (const f of slice) {
+        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        const cwe = f.cwe ? ` (${Array.isArray(f.cwe) ? f.cwe.join(", ") : f.cwe})` : "";
+        lines.push(`  - ${loc} [${f.rule}]${cwe}: ${f.message || ""}`.trim());
+      }
+      if (findings.length > slice.length) {
+        lines.push(`  - ... and ${findings.length - slice.length} more in ${severity}`);
+      }
+      remaining -= slice.length;
+    }
+    lines.push("");
+    lines.push("These SAST findings are GROUND TRUTH — fold ERROR-severity ones into the `security` dimension as critical/high findings. Use the semgrep rule id (e.g. javascript.express.security.audit.xss.direct-response-write) verbatim in the `rule` field; that lets the developer look it up in the semgrep registry.");
+    sections.push(lines.join("\n"));
+  }
+
   if (context) {
     sections.push(`## Context\n${context}`);
   }

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/prompts/rtk-snippet.js

@@ -2,7 +2,7 @@
  * RTK (Rust Token Killer) prompt instruction snippet.
  * Injected into coder/reviewer prompts when RTK is detected.
  */
-export const RTK_INSTRUCTIONS = [
+const RTK_INSTRUCTIONS = [
   "## Token Optimization (RTK detected)",
   "RTK is installed. Prefix ALL Bash tool calls with `rtk` to reduce token usage:",
   "- Use `rtk git status` instead of `git status`",