karajan-code 1.15.0 → 1.16.0

package/package.json

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

package/src/cli.js

@@ -72,6 +72,7 @@ program
   .option("--enable-tester")
   .option("--enable-security")
   .option("--enable-triage")
+  .option("--enable-discover")
   .option("--enable-serena")
   .option("--mode <name>")
   .option("--max-iterations <n>")

package/src/config.js

@@ -16,7 +16,8 @@ const DEFAULTS = {
     researcher: { provider: null, model: null },
     tester: { provider: null, model: null },
     security: { provider: null, model: null },
-    triage: { provider: null, model: null }
+    triage: { provider: null, model: null },
+    discover: { provider: null, model: null }
   },
   pipeline: {
     planner: { enabled: false },
@@ -25,7 +26,8 @@ const DEFAULTS = {
     researcher: { enabled: false },
     tester: { enabled: true },
     security: { enabled: true },
-    triage: { enabled: true }
+    triage: { enabled: true },
+    discover: { enabled: false }
   },
   review_mode: "standard",
   max_iterations: 5,
@@ -245,6 +247,9 @@ export function applyRunOverrides(config, flags) {
   if (flags.tester) out.roles.tester.provider = flags.tester;
   if (flags.security) out.roles.security.provider = flags.security;
   if (flags.triage) out.roles.triage.provider = flags.triage;
+  if (flags.discover) out.roles.discover.provider = flags.discover;
+  if (flags.discoverModel) out.roles.discover.model = String(flags.discoverModel);
+  if (flags.enableDiscover !== undefined) out.pipeline.discover.enabled = Boolean(flags.enableDiscover);
   if (flags.plannerModel) out.roles.planner.model = String(flags.plannerModel);
   if (flags.coderModel) {
     out.roles.coder.model = String(flags.coderModel);
@@ -318,14 +323,14 @@ export function resolveRole(config, role) {
   let provider = roleConfig.provider ?? null;
   if (!provider && role === "coder") provider = legacyCoder;
   if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage")) {
+  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage" || role === "discover")) {
     provider = roles.coder?.provider || legacyCoder;
   }
 
   let model = roleConfig.model ?? null;
   if (!model && role === "coder") model = config?.coder_options?.model ?? null;
   if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
-  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage")) {
+  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "triage" || role === "discover")) {
     model = config?.coder_options?.model ?? null;
   }
 
@@ -344,6 +349,7 @@ function requiredRolesFor(commandName, config) {
     if (config?.pipeline?.security?.enabled) required.push("security");
     return required;
   }
+  if (commandName === "discover") return ["discover"];
   if (commandName === "plan") return ["planner"];
   if (commandName === "code") return ["coder"];
   if (commandName === "review") return ["reviewer"];

package/src/mcp/run-kj.js

@@ -43,6 +43,7 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.enableTester, "--enable-tester", args);
   normalizeBoolFlag(options.enableSecurity, "--enable-security", args);
   normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
+  normalizeBoolFlag(options.enableDiscover, "--enable-discover", args);
   normalizeBoolFlag(options.enableSerena, "--enable-serena", args);
   normalizeBoolFlag(options.autoCommit, "--auto-commit", args);
   normalizeBoolFlag(options.autoPush, "--auto-push", args);

package/src/mcp/server-handlers.js

@@ -428,6 +428,59 @@ export async function handleReviewDirect(a, server, extra) {
   return { ok: true, review: parsed || result.output, raw: result.output };
 }
 
+export async function handleDiscoverDirect(a, server, extra) {
+  const config = await buildConfig(a, "discover");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const discoverRole = resolveRole(config, "discover");
+  await assertAgentsAvailable([discoverRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_discover] started — mode=${a.mode || "gaps"}`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "discover", message: line, detail: { stream, agent: discoverRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "discover", provider: discoverRole.provider
+  });
+
+  const { DiscoverRole } = await import("../roles/discover-role.js");
+  const discover = new DiscoverRole({ config, logger, emitter });
+  await discover.init({ task: a.task });
+
+  // Build context from pgTask if provided
+  let context = a.context || null;
+  if (a.pgTask && a.pgProject) {
+    try {
+      const pgContext = `Planning Game card: ${a.pgTask} (project: ${a.pgProject})`;
+      context = context ? `${context}\n\n${pgContext}` : pgContext;
+    } catch { /* PG not available — proceed without */ }
+  }
+
+  sendTrackerLog(server, "discover", "running", discoverRole.provider);
+  runLog.logText(`[discover] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await discover.run({ task: a.task, mode: a.mode || "gaps", context, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[discover] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "discover", "failed");
+    throw new Error(result.result?.error || result.summary || "Discovery failed");
+  }
+
+  sendTrackerLog(server, "discover", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
 export async function handleToolCall(name, args, server, extra) {
   const a = asObject(args);
 
@@ -635,5 +688,16 @@ export async function handleToolCall(name, args, server, extra) {
     return handlePlanDirect(a, server, extra);
   }
 
+  if (name === "kj_discover") {
+    if (!a.task) {
+      return failPayload("Missing required field: task");
+    }
+    const validModes = ["gaps", "momtest", "wendel", "classify", "jtbd"];
+    if (a.mode && !validModes.includes(a.mode)) {
+      return failPayload(`Invalid mode "${a.mode}". Valid values: ${validModes.join(", ")}`);
+    }
+    return handleDiscoverDirect(a, server, extra);
+  }
+
   return failPayload(`Unknown tool: ${name}`);
 }

package/src/mcp/tools.js

@@ -70,6 +70,7 @@ export const tools = [
         enableTester: { type: "boolean" },
         enableSecurity: { type: "boolean" },
         enableTriage: { type: "boolean" },
+        enableDiscover: { type: "boolean" },
         enableSerena: { type: "boolean" },
         enableBecaria: { type: "boolean", description: "Enable BecarIA Gateway (early PR + dispatch comments/reviews)" },
         reviewerFallback: { type: "string" },
@@ -223,5 +224,21 @@ export const tools = [
         kjHome: { type: "string" }
       }
     }
+  },
+  {
+    name: "kj_discover",
+    description: "Analyze a task for gaps, ambiguities, and missing information before execution. Returns a verdict (ready/needs_validation) with structured gap list. Can read task details from Planning Game if pgTask is provided.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to analyze for gaps" },
+        mode: { type: "string", enum: ["gaps", "momtest", "wendel", "classify", "jtbd"], description: "Discovery mode: gaps (default), momtest (Mom Test questions), wendel (behavior change checklist), classify (START/STOP/DIFFERENT), or jtbd (Jobs-to-be-Done)" },
+        context: { type: "string", description: "Additional context for the analysis (e.g., research output)" },
+        pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as additional context." },
+        pgProject: { type: "string", description: "Planning Game project ID. Required when pgTask is used." },
+        kjHome: { type: "string" }
+      }
+    }
   }
 ];

package/src/orchestrator/pre-loop-stages.js

@@ -1,6 +1,7 @@
 import { TriageRole } from "../roles/triage-role.js";
 import { ResearcherRole } from "../roles/researcher-role.js";
 import { PlannerRole } from "../roles/planner-role.js";
+import { DiscoverRole } from "../roles/discover-role.js";
 import { createAgent } from "../agents/index.js";
 import { addCheckpoint, markSessionStatus } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
@@ -258,3 +259,68 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
 
   return { plannedTask, stageResult };
 }
+
+export async function runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
+  logger.setContext({ iteration: 0, stage: "discover" });
+  emitProgress(
+    emitter,
+    makeEvent("discover:start", { ...eventBase, stage: "discover" }, {
+      message: "Discover analyzing task for gaps"
+    })
+  );
+
+  const discoverProvider = config?.roles?.discover?.provider || coderRole.provider;
+  const discoverOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "discover" }, {
+      message: line,
+      detail: { stream, agent: discoverProvider }
+    }));
+  };
+  const discoverStall = createStallDetector({
+    onOutput: discoverOnOutput, emitter, eventBase, stage: "discover", provider: discoverProvider
+  });
+
+  const mode = config?.pipeline?.discover?.mode || "gaps";
+  const discover = new DiscoverRole({ config, logger, emitter });
+  await discover.init({ task: session.task, sessionId: session.id, iteration: 0 });
+  const discoverStart = Date.now();
+  let discoverOutput;
+  try {
+    discoverOutput = await discover.run({ task: session.task, mode, onOutput: discoverStall.onOutput });
+  } finally {
+    discoverStall.stop();
+  }
+  trackBudget({
+    role: "discover",
+    provider: discoverProvider,
+    model: config?.roles?.discover?.model || coderRole.model,
+    result: discoverOutput,
+    duration_ms: Date.now() - discoverStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "discover",
+    iteration: 0,
+    ok: discoverOutput.ok,
+    provider: discoverProvider,
+    model: config?.roles?.discover?.model || coderRole.model || null
+  });
+
+  const stageResult = {
+    ok: discoverOutput.ok,
+    verdict: discoverOutput.result?.verdict || null,
+    gaps: discoverOutput.result?.gaps || [],
+    mode
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("discover:end", { ...eventBase, stage: "discover" }, {
+      status: discoverOutput.ok ? "ok" : "fail",
+      message: discoverOutput.ok ? "Discovery completed" : `Discovery failed: ${discoverOutput.summary}`,
+      detail: stageResult
+    })
+  );
+
+  return { stageResult };
+}

package/src/orchestrator.js

@@ -26,7 +26,7 @@ import { applyPolicies } from "./guards/policy-resolver.js";
 import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
-import { runTriageStage, runResearcherStage, runPlannerStage } from "./orchestrator/pre-loop-stages.js";
+import { runTriageStage, runResearcherStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
@@ -44,6 +44,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   let testerEnabled = Boolean(config.pipeline?.tester?.enabled);
   let securityEnabled = Boolean(config.pipeline?.security?.enabled);
   let reviewerEnabled = config.pipeline?.reviewer?.enabled !== false;
+  let discoverEnabled = Boolean(config.pipeline?.discover?.enabled);
   // Triage is always mandatory — it classifies taskType for policy resolution
   const triageEnabled = true;
 
@@ -70,6 +71,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         refactorer: refactorerRole
       },
       pipeline: {
+        discover_enabled: discoverEnabled,
         triage_enabled: triageEnabled,
         planner_enabled: plannerEnabled,
         refactorer_enabled: refactorerEnabled,
@@ -213,6 +215,13 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   const stageResults = {};
   const sonarState = { issuesInitial: null, issuesFinal: null };
 
+  // --- Discover (pre-triage, opt-in) ---
+  if (flags.enableDiscover !== undefined) discoverEnabled = Boolean(flags.enableDiscover);
+  if (discoverEnabled) {
+    const discoverResult = await runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
+    stageResults.discover = discoverResult.stageResult;
+  }
+
   if (triageEnabled) {
     const triageResult = await runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
     if (triageResult.roleOverrides.plannerEnabled !== undefined) plannerEnabled = triageResult.roleOverrides.plannerEnabled;

package/src/prompts/discover.js

@@ -0,0 +1,227 @@
+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 = ["ready", "needs_validation"];
+const VALID_SEVERITIES = ["critical", "major", "minor"];
+const VALID_WENDEL_STATUSES = ["pass", "fail", "unknown", "not_applicable"];
+const VALID_CLASSIFY_TYPES = ["START", "STOP", "DIFFERENT", "not_applicable"];
+const VALID_ADOPTION_RISKS = ["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."
+  );
+
+  sections.push(
+    "## 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");
+}
+
+export function parseDiscoverOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch {
+    return null;
+  }
+
+  const verdict = VALID_VERDICTS.includes(parsed.verdict) ? parsed.verdict : "ready";
+
+  const rawGaps = Array.isArray(parsed.gaps) ? parsed.gaps : [];
+  const gaps = rawGaps
+    .filter((g) => g && g.id && g.description && g.suggestedQuestion)
+    .map((g) => ({
+      id: g.id,
+      description: g.description,
+      severity: VALID_SEVERITIES.includes(String(g.severity).toLowerCase())
+        ? String(g.severity).toLowerCase()
+        : "major",
+      suggestedQuestion: g.suggestedQuestion
+    }));
+
+  const rawQuestions = Array.isArray(parsed.momTestQuestions) ? parsed.momTestQuestions : [];
+  const momTestQuestions = rawQuestions
+    .filter((q) => q && q.gapId && q.question && q.targetRole && q.rationale)
+    .map((q) => ({
+      gapId: q.gapId,
+      question: q.question,
+      targetRole: q.targetRole,
+      rationale: q.rationale
+    }));
+
+  const rawChecklist = Array.isArray(parsed.wendelChecklist) ? parsed.wendelChecklist : [];
+  const wendelChecklist = rawChecklist
+    .filter((c) => c && c.condition && c.justification && c.status)
+    .map((c) => ({
+      condition: c.condition,
+      status: VALID_WENDEL_STATUSES.includes(String(c.status).toLowerCase())
+        ? String(c.status).toLowerCase()
+        : "unknown",
+      justification: c.justification
+    }));
+
+  const rawJtbds = Array.isArray(parsed.jtbds) ? parsed.jtbds : [];
+  const jtbds = rawJtbds
+    .filter((j) => 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
+    }));
+
+  let classification = null;
+  if (parsed.classification && typeof parsed.classification === "object") {
+    const rawType = String(parsed.classification.type || "").toUpperCase();
+    const type = rawType === "NOT_APPLICABLE" ? "not_applicable"
+      : VALID_CLASSIFY_TYPES.includes(rawType) ? rawType : "not_applicable";
+    const rawRisk = String(parsed.classification.adoptionRisk || "").toLowerCase();
+    classification = {
+      type,
+      adoptionRisk: VALID_ADOPTION_RISKS.includes(rawRisk) ? rawRisk : "medium",
+      frictionEstimate: parsed.classification.frictionEstimate || ""
+    };
+  }
+
+  return {
+    verdict,
+    gaps,
+    momTestQuestions,
+    wendelChecklist,
+    classification,
+    jtbds,
+    summary: parsed.summary || ""
+  };
+}

package/src/roles/discover-role.js

@@ -0,0 +1,130 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.discover?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildSummary(parsed, mode) {
+  const gapCount = parsed.gaps?.length || 0;
+  if (gapCount === 0 && mode !== "wendel" && mode !== "jtbd") return "Discovery complete: task is ready";
+  const parts = [];
+  if (gapCount > 0) parts.push(`${gapCount} gap${gapCount !== 1 ? "s" : ""} found`);
+  if (mode === "momtest") {
+    const qCount = parsed.momTestQuestions?.length || 0;
+    if (qCount > 0) parts.push(`${qCount} Mom Test question${qCount !== 1 ? "s" : ""}`);
+  }
+  if (mode === "wendel") {
+    const failCount = (parsed.wendelChecklist || []).filter(c => c.status === "fail").length;
+    if (failCount > 0) parts.push(`${failCount} Wendel condition${failCount !== 1 ? "s" : ""} failed`);
+    else if (gapCount === 0) return "Discovery complete: task is ready";
+  }
+  if (mode === "classify" && parsed.classification) {
+    parts.push(`type: ${parsed.classification.type}, risk: ${parsed.classification.adoptionRisk}`);
+  }
+  if (mode === "jtbd") {
+    const jCount = parsed.jtbds?.length || 0;
+    if (jCount > 0) parts.push(`${jCount} JTBD${jCount !== 1 ? "s" : ""} generated`);
+    else if (gapCount === 0) return "Discovery complete: task is ready";
+  }
+  return `Discovery complete: ${parts.join(", ")} (verdict: ${parsed.verdict})`;
+}
+
+export class DiscoverRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "discover", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const task = typeof input === "string"
+      ? input
+      : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const mode = (typeof input === "object" ? input?.mode : null) || "gaps";
+    const context = typeof input === "object" ? input?.context || null : null;
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildDiscoverPrompt({ task, instructions: this.instructions, mode, context });
+    const runArgs = { prompt, role: "discover" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "Discovery failed",
+          provider,
+          mode
+        },
+        summary: `Discovery failed: ${result.error || "unknown error"}`,
+        usage: result.usage
+      };
+    }
+
+    try {
+      const parsed = parseDiscoverOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: true,
+          result: {
+            verdict: "ready",
+            gaps: [],
+            mode,
+            raw: result.output,
+            provider
+          },
+          summary: "Discovery complete (unstructured output)",
+          usage: result.usage
+        };
+      }
+
+      const resultObj = {
+        verdict: parsed.verdict,
+        gaps: parsed.gaps,
+        mode,
+        provider
+      };
+      if (mode === "momtest") {
+        resultObj.momTestQuestions = parsed.momTestQuestions || [];
+      }
+      if (mode === "wendel") {
+        resultObj.wendelChecklist = parsed.wendelChecklist || [];
+      }
+      if (mode === "classify") {
+        resultObj.classification = parsed.classification || null;
+      }
+      if (mode === "jtbd") {
+        resultObj.jtbds = parsed.jtbds || [];
+      }
+
+      return {
+        ok: true,
+        result: resultObj,
+        summary: buildSummary(parsed, mode),
+        usage: result.usage
+      };
+    } catch {
+      return {
+        ok: true,
+        result: {
+          verdict: "ready",
+          gaps: [],
+          mode,
+          raw: result.output,
+          provider
+        },
+        summary: "Discovery complete (unstructured output)",
+        usage: result.usage
+      };
+    }
+  }
+}

package/src/roles/index.js

@@ -10,3 +10,4 @@ export { TriageRole } from "./triage-role.js";
 export { TesterRole } from "./tester-role.js";
 export { SecurityRole } from "./security-role.js";
 export { SolomonRole } from "./solomon-role.js";
+export { DiscoverRole } from "./discover-role.js";

package/templates/roles/discover.md

@@ -0,0 +1,167 @@
+# Discover Role
+
+You are the **Discover** role in a multi-role AI pipeline.
+
+Your job is to analyze a task description, ticket, or brief and identify **gaps** — missing information, implicit assumptions, ambiguities, and contradictions that could cause unnecessary iterations during implementation.
+
+## Responsibilities
+
+- Detect missing requirements or acceptance criteria
+- Identify implicit assumptions that need explicit confirmation
+- Find ambiguities where multiple interpretations are possible
+- Spot contradictions between different parts of the specification
+- Suggest specific questions that would resolve each gap
+
+## Severity Classification
+
+- **critical**: Blocks implementation entirely — cannot proceed without this information
+- **major**: Could lead to significant rework if assumed incorrectly
+- **minor**: Nice to clarify but a reasonable default exists
+
+## Verdict
+
+- **ready**: The task is well-defined and can proceed to implementation without further clarification
+- **needs_validation**: One or more gaps were found that should be resolved before implementation
+
+## Output format
+
+Return a single valid JSON object and nothing else.
+
+```json
+{
+  "verdict": "ready|needs_validation",
+  "gaps": [
+    {
+      "id": "gap-1",
+      "description": "What information is missing or ambiguous",
+      "severity": "critical|major|minor",
+      "suggestedQuestion": "A specific question to resolve this gap"
+    }
+  ],
+  "summary": "Brief human-readable summary of findings"
+}
+```
+
+If the task is well-defined with no gaps, return `verdict: "ready"` with an empty `gaps` array.
+
+## Mom Test Mode
+
+When running in **momtest** mode, for each gap generate questions following The Mom Test principles:
+
+- Ask about **past behavior** and real experiences, never hypothetical scenarios
+- Ask about **specifics**, not generalities
+- Focus on what people **actually do**, not what they say they would do
+
+### Good vs Bad Questions
+
+| Bad (hypothetical/opinion) | Good (past behavior) |
+|---|---|
+| "Would you use a notification system?" | "When was the last time you missed an important update?" |
+| "Do you think users need dark mode?" | "How many support tickets mentioned readability issues?" |
+| "Would it be useful to have X?" | "How are you currently handling X?" |
+
+### Mom Test Output Schema (additional fields for momtest mode)
+
+```json
+{
+  "momTestQuestions": [
+    {
+      "gapId": "gap-1",
+      "question": "Past-behavior question to validate this gap",
+      "targetRole": "Who should answer (end-user, developer, PM, etc.)",
+      "rationale": "Why this question matters for the gap"
+    }
+  ]
+}
+```
+
+## Wendel Mode
+
+When running in **wendel** mode, evaluate whether the task implies a **user behavior change** and assess 5 adoption conditions:
+
+| Condition | Question |
+|-----------|----------|
+| **CUE** | Is there a clear trigger that will prompt the user to take the new action? |
+| **REACTION** | Will the user have a positive emotional reaction when encountering the cue? |
+| **EVALUATION** | Can the user quickly understand the value of the new behavior? |
+| **ABILITY** | Does the user have the skill and resources to perform the new behavior? |
+| **TIMING** | Is this the right moment to introduce this change? |
+
+### Status Values
+
+- **pass**: Condition is clearly met based on the task specification
+- **fail**: Condition is NOT met — adoption risk identified
+- **unknown**: Not enough information to evaluate
+- **not_applicable**: Task does not imply user behavior change (e.g., refactor, backend optimization)
+
+If the task does NOT imply behavior change, set ALL conditions to `not_applicable` and verdict to `ready`.
+
+### Wendel Output Schema (additional fields for wendel mode)
+
+```json
+{
+  "wendelChecklist": [
+    {
+      "condition": "CUE|REACTION|EVALUATION|ABILITY|TIMING",
+      "status": "pass|fail|unknown|not_applicable",
+      "justification": "Why this condition passes or fails"
+    }
+  ]
+}
+```
+
+## Classify Mode
+
+When running in **classify** mode, classify the task by its impact on user behavior:
+
+| Type | Description | Risk Level |
+|------|-------------|------------|
+| **START** | User must adopt a completely new behavior or workflow | Medium-High |
+| **STOP** | User must stop doing something they currently do | **Highest** resistance risk |
+| **DIFFERENT** | User must do something they already do, but differently | Low-Medium |
+| **not_applicable** | No user behavior impact (internal refactor, backend, infra) | None |
+
+### Classify Output Schema (additional fields for classify mode)
+
+```json
+{
+  "classification": {
+    "type": "START|STOP|DIFFERENT|not_applicable",
+    "adoptionRisk": "none|low|medium|high",
+    "frictionEstimate": "Description of expected friction"
+  }
+}
+```
+
+## JTBD Mode
+
+When running in **jtbd** mode, generate reinforced Jobs-to-be-Done from the task and provided context (interview notes, field observations).
+
+Each JTBD must include 5 layers:
+
+| Layer | Description |
+|-------|-------------|
+| **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 references from context. Set to `not_available` if no context provided |
+
+**CRITICAL**: The `evidence` field must contain real quotes or specific references from the provided context. Never invent assumptions.
+
+### JTBD Output Schema (additional fields for jtbd mode)
+
+```json
+{
+  "jtbds": [
+    {
+      "id": "jtbd-1",
+      "functional": "The practical job",
+      "emotionalPersonal": "How the user wants to feel",
+      "emotionalSocial": "How the user wants to be perceived",
+      "behaviorChange": "START|STOP|DIFFERENT|not_applicable",
+      "evidence": "Direct quote or 'not_available'"
+    }
+  ]
+}
+```