@karajan-family/code 4.21.0

package/src/prompts/coder.js

@@ -0,0 +1,287 @@
+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.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Execute the task directly. Do NOT use any MCP tools. Focus only on coding."
+].join(" ");
+
+const SUBAGENT_PREAMBLE_SERENA = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Execute the task directly. Focus only on coding."
+].join(" ");
+
+const SUBPROCESS_CONSTRAINTS = [
+  "## Environment constraints",
+  "You run as a non-interactive subprocess (no stdin, no TTY).",
+  "- If the task requires a CLI wizard or interactive init (e.g. `create-react-app`, `pnpm create astro`, `npm init`), ALWAYS use non-interactive flags: `--yes`, `--no-input`, `--template <name>`, `--defaults`, etc.",
+  "- Never run a command that waits for user input — it will hang forever.",
+  "- If a task absolutely cannot be done non-interactively, say so explicitly instead of hanging."
+].join("\n");
+
+const SERENA_INSTRUCTIONS = [
+  "## Serena MCP — symbol-level code navigation",
+  "You have access to Serena MCP tools for efficient code navigation.",
+  "Prefer these over reading entire files to save tokens:",
+  "- `find_symbol(name)` — locate a function, class, or variable definition",
+  "- `find_referencing_symbols(name)` — find all code that references a symbol",
+  "- `insert_after_symbol(name, code)` — insert code precisely after a symbol",
+  "Use Serena for understanding existing code structure before making changes.",
+  "Fall back to reading files only when Serena tools are not sufficient."
+].join("\n");
+
+/**
+ * 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");
+}
+
+// KJC sesgo-de-stack: Karajan used to default every prompt to JS/TS
+// (vitest, npm install, console.log, JSDoc, httpOnly cookies). When
+// the project is Python / Go / Rust / Ruby, that produced absurd
+// outputs (e.g. installing vitest in a pure-python repo to satisfy a
+// hardcoded `npx vitest run` acceptance test). When we know the
+// stack we tell the coder explicitly so it stops assuming.
+function buildStackSection({ stack, testFramework }) {
+  if (!stack && !testFramework) return null;
+  const lines = ["## Project Stack — match this, don't assume JavaScript"];
+  if (stack?.language) lines.push(`- Language: **${stack.language}**`);
+  if (stack?.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+  if (testFramework?.hasTests && testFramework?.framework) {
+    lines.push(`- Test framework already in use: **${testFramework.framework}** (${testFramework.language || stack?.language || "unknown"}). Use it for new tests; do NOT add a JS test framework on top.`);
+  } else if (stack?.language && stack.language !== "javascript" && stack.language !== "typescript") {
+    lines.push(`- No test framework detected yet. Pick the canonical one for ${stack.language} (e.g. pytest for python, \`go test\` for go, \`cargo test\` for rust, rspec for ruby). Do NOT use vitest / jest / \`npm install\` in a non-JS project.`);
+  }
+  lines.push("");
+  lines.push("If an acceptance_test command on this HU points at a foreign framework (e.g. `npx vitest run` on a python project), REPLACE the command with the equivalent for the project's actual stack and use that to verify your work.");
+  return lines.join("\n");
+}
+
+/**
+ * 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…"
+  // 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 stackRule = buildStackSection({ stack, testFramework });
+  const rtkSnippet = buildRtkInstructions({ rtkAvailable });
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider });
+  }
+
+  // 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).
+  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;
+
+  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),
+  ]);
+}
+
+export async function buildCoderPrompt(options) {
+  return joinLayout(await buildCoderPromptLayout(options));
+}

package/src/prompts/diff-clip.js

@@ -0,0 +1,27 @@
+/**
+ * diff-clip — KJC-BUG-0134 (issue #1381). A bare [TRUNCATED] marker inside
+ * the diff body reads as file content: reviewers blamed whichever file the
+ * cut landed in and rejected complete, untouched code (each false positive
+ * costs a solomon round). The clip is DECLARED as the pipeline's own, kept
+ * OUTSIDE the diff body, cut on a line boundary, and the reviewer is told
+ * the diff is partial so it never reasons about the completeness of files
+ * it cannot fully see. Shared by every prompt that hands a diff to an AI.
+ */
+
+export const DIFF_CLIP_CHARS = 12000;
+
+/** @returns {{body: string, note: string|null}} note is null when no clip happened. */
+export function clipDiff(diff, limit = DIFF_CLIP_CHARS) {
+  if (!diff) return { body: "", note: null };
+  if (diff.length <= limit) return { body: diff, note: null };
+  const hard = diff.slice(0, limit);
+  const nl = hard.lastIndexOf("\n");
+  const body = nl > 0 ? hard.slice(0, nl) : hard;
+  const omittedLines = diff.slice(body.length).split("\n").filter(Boolean).length;
+  const note = [
+    `NOTE FROM THE KJ PIPELINE (not part of the diff): the diff above was clipped by kj at ~${limit} characters — ${omittedLines} more line(s) exist but are NOT shown.`,
+    "The cut is kj's, not the author's: no file in the working tree is truncated.",
+    "Do not raise issues about incomplete or cut-off content, and do not reason about the completeness of files you cannot fully see. Review only what is visible.",
+  ].join(" ");
+  return { body, note };
+}

package/src/prompts/discover.js

@@ -0,0 +1,222 @@
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on discovering gaps in the task specification."
+].join(" ");
+
+export const DISCOVER_MODES = ["gaps", "momtest", "wendel", "classify", "jtbd"];
+
+const VALID_VERDICTS = new Set(["ready", "needs_validation"]);
+const VALID_SEVERITIES = new Set(["critical", "major", "minor"]);
+const VALID_WENDEL_STATUSES = new Set(["pass", "fail", "unknown", "not_applicable"]);
+const VALID_CLASSIFY_TYPES = new Set(["START", "STOP", "DIFFERENT", "not_applicable"]);
+const VALID_ADOPTION_RISKS = new Set(["none", "low", "medium", "high"]);
+
+export function buildDiscoverPrompt({ task, instructions, mode = "gaps", context = null }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    "You are a task discovery agent for Karajan Code, a multi-agent coding orchestrator.",
+    "Analyze the following task and identify gaps, ambiguities, missing information, and implicit assumptions.",
+    "## Gap Detection Guidelines",
+    [
+      "- Look for missing acceptance criteria or requirements",
+      "- Identify implicit assumptions that need explicit confirmation",
+      "- Find ambiguities where multiple interpretations exist",
+      "- Check for contradictions between different parts of the spec",
+      "- Consider edge cases and error scenarios not addressed",
+      "- Classify each gap by severity: critical (blocks implementation), major (could cause rework), minor (reasonable default exists)"
+    ].join("\n")
+  );
+
+  if (mode === "momtest") {
+    sections.push(
+      "## Mom Test Rules",
+      [
+        "For each gap, generate questions that follow The Mom Test principles:",
+        "- ALWAYS ask about past behavior and real experiences, never hypothetical scenarios",
+        "- NEVER ask 'Would you...?', 'Do you think...?', 'Would it be useful if...?'",
+        "- ALWAYS ask 'When was the last time...?', 'How do you currently...?', 'What happened when...?'",
+        "- Ask about specifics, not generalities",
+        "- Each question must have a targetRole (who to ask) and rationale (why this matters)",
+        "",
+        "Examples of BAD questions (hypothetical/opinion):",
+        "  - 'Would you use this feature?' -> opinion, not data",
+        "  - 'Do you think users need this?' -> speculation",
+        "",
+        "Examples of GOOD questions (past behavior):",
+        "  - 'When was the last time you had to do X manually?' -> real experience",
+        "  - 'How are you currently handling Y?' -> current behavior",
+        "  - 'What happened the last time Z failed?' -> real consequence"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "wendel") {
+    sections.push(
+      "## Wendel Behavior Change Checklist",
+      [
+        "Evaluate whether the task implies a user behavior change. If it does, assess these 5 conditions:",
+        "",
+        "1. **CUE** — Is there a clear trigger that will prompt the user to take the new action?",
+        "2. **REACTION** — Will the user have a positive emotional reaction when they encounter the cue?",
+        "3. **EVALUATION** — Can the user quickly understand the value of the new behavior?",
+        "4. **ABILITY** — Does the user have the skill and resources to perform the new behavior?",
+        "5. **TIMING** — Is this the right moment to introduce this change?",
+        "",
+        "For each condition, set status to: pass, fail, unknown, or not_applicable",
+        "If the task does NOT imply behavior change (e.g., internal refactor, backend optimization), set ALL conditions to 'not_applicable'",
+        "If ANY condition is 'fail', set verdict to 'needs_validation'"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "classify") {
+    sections.push(
+      "## Behavior Change Classification",
+      [
+        "Classify the task by its impact on user behavior:",
+        "",
+        "- **START**: User must adopt a completely new behavior or workflow",
+        "- **STOP**: User must stop doing something they currently do (highest resistance risk)",
+        "- **DIFFERENT**: User must do something they already do, but differently",
+        "- **not_applicable**: Task has no user behavior impact (internal refactor, backend, infra)",
+        "",
+        "Assess adoption risk: none (no user impact), low, medium, high",
+        "STOP changes carry the highest risk of resistance — always flag them",
+        "Provide a frictionEstimate explaining the expected friction"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "jtbd") {
+    sections.push(
+      "## Jobs-to-be-Done Framework",
+      [
+        "Generate reinforced Jobs-to-be-Done from the task and any provided context (interview notes, field observations).",
+        "Each JTBD must include 5 layers:",
+        "",
+        "- **functional**: The practical job the user is trying to accomplish",
+        "- **emotionalPersonal**: How the user wants to feel personally",
+        "- **emotionalSocial**: How the user wants to be perceived by others",
+        "- **behaviorChange**: Type of change: START, STOP, DIFFERENT, or not_applicable",
+        "- **evidence**: Direct quotes or specific references from the context. If no context provided, set to 'not_available' and suggest what context is needed",
+        "",
+        "CRITICAL: evidence must contain real quotes or references from the provided context, NEVER invented assumptions",
+        "If no context is provided, mark evidence as 'not_available'"
+      ].join("\n")
+    );
+  }
+
+  const baseSchema = '{"verdict":"ready|needs_validation","gaps":[{"id":string,"description":string,"severity":"critical|major|minor","suggestedQuestion":string}]';
+  const momtestSchema = mode === "momtest"
+    ? ',"momTestQuestions":[{"gapId":string,"question":string,"targetRole":string,"rationale":string}]'
+    : "";
+  const wendelSchema = mode === "wendel"
+    ? ',"wendelChecklist":[{"condition":"CUE|REACTION|EVALUATION|ABILITY|TIMING","status":"pass|fail|unknown|not_applicable","justification":string}]'
+    : "";
+  const classifySchema = mode === "classify"
+    ? ',"classification":{"type":"START|STOP|DIFFERENT|not_applicable","adoptionRisk":"none|low|medium|high","frictionEstimate":string}'
+    : "";
+  const jtbdSchema = mode === "jtbd"
+    ? ',"jtbds":[{"id":string,"functional":string,"emotionalPersonal":string,"emotionalSocial":string,"behaviorChange":"START|STOP|DIFFERENT|not_applicable","evidence":string}]'
+    : "";
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: ${baseSchema}${momtestSchema}${wendelSchema}${classifySchema}${jtbdSchema},"summary":string}`
+  );
+
+  if (context) {
+    sections.push(`## Context\n${context}`);
+  }
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+function parseClassification(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const rawType = String(raw.type || "").toUpperCase();
+  let type;
+  if (rawType === "NOT_APPLICABLE") type = "not_applicable";
+  else if (VALID_CLASSIFY_TYPES.has(rawType)) type = rawType;
+  else type = "not_applicable";
+  const rawRisk = String(raw.adoptionRisk || "").toLowerCase();
+  return {
+    type,
+    adoptionRisk: VALID_ADOPTION_RISKS.has(rawRisk) ? rawRisk : "medium",
+    frictionEstimate: raw.frictionEstimate || ""
+  };
+}
+
+function parseGaps(rawGaps) {
+  return (Array.isArray(rawGaps) ? rawGaps : [])
+    .filter((g) => g?.id && g.description && g.suggestedQuestion)
+    .map((g) => ({
+      id: g.id,
+      description: g.description,
+      severity: VALID_SEVERITIES.has(String(g.severity).toLowerCase())
+        ? String(g.severity).toLowerCase()
+        : "major",
+      suggestedQuestion: g.suggestedQuestion
+    }));
+}
+
+function parseMomTestQuestions(rawQuestions) {
+  return (Array.isArray(rawQuestions) ? rawQuestions : [])
+    .filter((q) => q?.gapId && q.question && q.targetRole && q.rationale)
+    .map((q) => ({
+      gapId: q.gapId,
+      question: q.question,
+      targetRole: q.targetRole,
+      rationale: q.rationale
+    }));
+}
+
+function parseWendelChecklist(rawChecklist) {
+  return (Array.isArray(rawChecklist) ? rawChecklist : [])
+    .filter((c) => c?.condition && c.justification && c.status)
+    .map((c) => ({
+      condition: c.condition,
+      status: VALID_WENDEL_STATUSES.has(String(c.status).toLowerCase())
+        ? String(c.status).toLowerCase()
+        : "unknown",
+      justification: c.justification
+    }));
+}
+
+function parseJtbds(rawJtbds) {
+  return (Array.isArray(rawJtbds) ? rawJtbds : [])
+    .filter((j) => j?.id && j.functional && j.emotionalPersonal && j.emotionalSocial && j.behaviorChange && j.evidence)
+    .map((j) => ({
+      id: j.id,
+      functional: j.functional,
+      emotionalPersonal: j.emotionalPersonal,
+      emotionalSocial: j.emotionalSocial,
+      behaviorChange: j.behaviorChange,
+      evidence: j.evidence
+    }));
+}
+
+export function parseDiscoverOutput(raw) {
+  const parsed = extractFirstJson(raw);
+  if (!parsed) return null;
+
+  return {
+    verdict: VALID_VERDICTS.has(parsed.verdict) ? parsed.verdict : "ready",
+    gaps: parseGaps(parsed.gaps),
+    momTestQuestions: parseMomTestQuestions(parsed.momTestQuestions),
+    wendelChecklist: parseWendelChecklist(parsed.wendelChecklist),
+    classification: parseClassification(parsed.classification),
+    jtbds: parseJtbds(parsed.jtbds),
+    summary: parsed.summary || ""
+  };
+}