karajan-code 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.14.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>")
@@ -87,6 +88,7 @@ program
   .option("--auto-pr")
   .option("--enable-becaria", "Enable BecarIA Gateway (early PR + dispatch comments/reviews)")
   .option("--branch-prefix <prefix>")
+  .option("--task-type <type>", "Explicit task type: sw, infra, doc, add-tests, refactor")
   .option("--methodology <name>")
   .option("--no-auto-rebase")
   .option("--no-sonar")

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,11 +43,13 @@ 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);
   normalizeBoolFlag(options.autoPr, "--auto-pr", args);
   if (options.autoRebase === false) args.push("--no-auto-rebase");
+  addOptionalValue(args, "--task-type", options.taskType);
   normalizeBoolFlag(options.noSonar, "--no-sonar", args);
   if (options.smartModels === true) args.push("--smart-models");
   if (options.smartModels === false) args.push("--no-smart-models");

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);
 
@@ -565,6 +618,12 @@ export async function handleToolCall(name, args, server, extra) {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
+    if (a.taskType) {
+      const validTypes = ["sw", "infra", "doc", "add-tests", "refactor"];
+      if (!validTypes.includes(a.taskType)) {
+        return failPayload(`Invalid taskType "${a.taskType}". Valid values: ${validTypes.join(", ")}`);
+      }
+    }
     if (!isPreflightAcked()) {
       const { config } = await loadConfig();
       const { listAgents } = await import("../commands/agents.js");
@@ -629,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" },
@@ -88,6 +89,7 @@ export const tools = [
         branchPrefix: { type: "string" },
         smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
         checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
+        taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
         noSonar: { type: "boolean" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
@@ -222,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";
@@ -56,12 +57,14 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
   const recommendedRoles = new Set(triageOutput.result?.roles || []);
   const roleOverrides = {};
   if (triageOutput.ok) {
-    roleOverrides.plannerEnabled = recommendedRoles.has("planner");
-    roleOverrides.researcherEnabled = recommendedRoles.has("researcher");
-    roleOverrides.refactorerEnabled = recommendedRoles.has("refactorer");
-    roleOverrides.reviewerEnabled = recommendedRoles.has("reviewer");
-    roleOverrides.testerEnabled = recommendedRoles.has("tester");
-    roleOverrides.securityEnabled = recommendedRoles.has("security");
+    // Triage can activate roles, but cannot deactivate roles explicitly enabled in pipeline config
+    const p = config.pipeline || {};
+    roleOverrides.plannerEnabled = recommendedRoles.has("planner") || Boolean(p.planner?.enabled);
+    roleOverrides.researcherEnabled = recommendedRoles.has("researcher") || Boolean(p.researcher?.enabled);
+    roleOverrides.refactorerEnabled = recommendedRoles.has("refactorer") || Boolean(p.refactorer?.enabled);
+    roleOverrides.reviewerEnabled = recommendedRoles.has("reviewer") || Boolean(p.reviewer?.enabled);
+    roleOverrides.testerEnabled = recommendedRoles.has("tester") || Boolean(p.tester?.enabled);
+    roleOverrides.securityEnabled = recommendedRoles.has("security") || Boolean(p.security?.enabled);
   }
 
   const shouldDecompose = triageOutput.result?.shouldDecompose || false;
@@ -72,6 +75,7 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     level: triageOutput.result?.level || null,
     roles: Array.from(recommendedRoles),
     reasoning: triageOutput.result?.reasoning || null,
+    taskType: triageOutput.result?.taskType || "sw",
     shouldDecompose,
     subtasks
   };
@@ -255,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,7 +44,9 @@ 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;
-  const triageEnabled = Boolean(config.pipeline?.triage?.enabled);
+  let discoverEnabled = Boolean(config.pipeline?.discover?.enabled);
+  // Triage is always mandatory — it classifies taskType for policy resolution
+  const triageEnabled = true;
 
   // --- Dry-run: return summary without executing anything ---
   if (flags.dryRun) {
@@ -69,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,
@@ -212,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;
@@ -282,8 +292,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   if (flags.enableSecurity !== undefined) securityEnabled = Boolean(flags.enableSecurity);
 
   // --- Policy resolver: gate stages by taskType ---
+  // Priority: explicit flag > config > triage classification > default (sw)
   const resolvedPolicies = applyPolicies({
-    taskType: flags.taskType || config.taskType || null,
+    taskType: flags.taskType || config.taskType || stageResults.triage?.taskType || null,
     policies: config.policies,
   });
   session.resolved_policies = resolvedPolicies;

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

@@ -47,10 +47,10 @@ export function buildTriagePrompt({ task, instructions, availableRoles }) {
   );
 
   sections.push(
-    "Classify the task complexity, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
+    "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
     "Keep the reasoning short and practical.",
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security"],"reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}'
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security"],"taskType":"sw|infra|doc|add-tests|refactor","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}'
   );
 
   sections.push(`## Task\n${task}`);

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/src/roles/triage-role.js

@@ -1,9 +1,11 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { buildTriagePrompt } from "../prompts/triage.js";
+import { VALID_TASK_TYPES } from "../guards/policy-resolver.js";
 
 const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
 const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security"]);
+const FALLBACK_TASK_TYPE = "sw";
 
 function resolveProvider(config) {
   return (
@@ -74,6 +76,7 @@ export class TriageRole extends BaseRole {
             level: "medium",
             roles: ["reviewer"],
             reasoning: "Unstructured output, using safe defaults.",
+            taskType: FALLBACK_TASK_TYPE,
             provider,
             raw: result.output
           },
@@ -87,11 +90,13 @@ export class TriageRole extends BaseRole {
       const reasoning = String(parsed.reasoning || "").trim() || "No reasoning provided.";
       const shouldDecompose = Boolean(parsed.shouldDecompose);
       const subtasks = normalizeSubtasks(parsed.subtasks);
+      const taskType = VALID_TASK_TYPES.includes(parsed.taskType) ? parsed.taskType : FALLBACK_TASK_TYPE;
 
       const triageResult = {
         level,
         roles,
         reasoning,
+        taskType,
         provider
       };
 
@@ -116,6 +121,7 @@ export class TriageRole extends BaseRole {
           level: "medium",
           roles: ["reviewer"],
           reasoning: "Failed to parse triage output, using safe defaults.",
+          taskType: FALLBACK_TASK_TYPE,
           provider,
           raw: result.output
         },

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'"
+    }
+  ]
+}
+```

package/templates/roles/triage.md

@@ -8,6 +8,7 @@ Return a single valid JSON object and nothing else:
 ```json
 {
   "level": "trivial|simple|medium|complex",
+  "taskType": "sw|infra|doc|add-tests|refactor",
   "roles": ["planner", "researcher", "refactorer", "reviewer", "tester", "security"],
   "reasoning": "brief practical justification",
   "shouldDecompose": false,
@@ -15,7 +16,14 @@ Return a single valid JSON object and nothing else:
 }
 ```
 
-## Classification guidance
+## Task type classification
+- `sw`: writing or modifying business logic, features, APIs, components, services.
+- `infra`: CI/CD, Docker, deploy scripts, build configuration, environment setup.
+- `doc`: documentation, README, CHANGELOG, comments-only changes.
+- `add-tests`: adding tests to existing code without changing functionality.
+- `refactor`: restructuring code without changing external behavior.
+
+## Complexity classification
 - `trivial`: tiny, low-risk, straightforward. Usually no extra roles.
 - `simple`: limited scope with low risk. Usually reviewer only.
 - `medium`: moderate scope/risk. Reviewer required; optional planner/researcher.