karajan-code 2.7.2 → 2.7.4

package/src/commands/audit.js

@@ -2,6 +2,7 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 function formatFindings(findings) {
   const lines = [];
@@ -66,34 +67,41 @@ function formatAudit(parsed) {
 }
 
 export async function auditCommand({ task, config, logger, dimensions, json }) {
-  const auditRole = resolveRole(config, "audit");
-  await assertAgentsAvailable([auditRole.provider]);
-  logger.info(`Audit (${auditRole.provider}) starting...`);
+  return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const auditRole = resolveRole(config, "audit");
+    await assertAgentsAvailable([auditRole.provider]);
+    logger.info(`Audit (${auditRole.provider}) starting...`);
+    runLog.logText(`[audit] provider=${auditRole.provider} dimensions=${dimensions || "all"}`);
 
-  const agent = createAgent(auditRole.provider, config, logger);
-  const dimList = dimensions && dimensions !== "all"
-    ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
-    : null;
+    const agent = createAgent(auditRole.provider, config, logger);
+    const dimList = dimensions && dimensions !== "all"
+      ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
+      : null;
 
-  const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "audit" });
+    const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "audit" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Audit failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Audit failed");
+    }
 
-  const parsed = parseAuditOutput(result.output);
+    const parsed = parseAuditOutput(result.output);
+    if (parsed?.summary) {
+      runLog.logText(`[audit] findings=${parsed.summary.totalFindings} (critical=${parsed.summary.critical}, high=${parsed.summary.high})`);
+    }
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.summary) {
-    console.log(formatAudit(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Audit completed.");
+    if (parsed?.summary) {
+      console.log(formatAudit(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Audit completed.");
+    return { ok: true };
+  });
 }

package/src/commands/code.js

@@ -3,32 +3,38 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { resolveRole } from "../config.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 export async function codeCommand({ task, config, logger }) {
-  const coderRole = resolveRole(config, "coder");
-  await assertAgentsAvailable([coderRole.provider]);
-  logger.info(`Coder (${coderRole.provider}) starting...`);
-  const coder = createAgent(coderRole.provider, config, logger);
-  let coderRules = null;
-  if (config.coder_rules) {
-    try {
-      coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* configured coder_rules path not found — try fallback */
-      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+  return withCliRunLog("code", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const coderRole = resolveRole(config, "coder");
+    await assertAgentsAvailable([coderRole.provider]);
+    logger.info(`Coder (${coderRole.provider}) starting...`);
+    runLog.logText(`[coder] provider=${coderRole.provider}`);
+    const coder = createAgent(coderRole.provider, config, logger);
+    let coderRules = null;
+    if (config.coder_rules) {
+      try {
+        coderRules = await fs.readFile(config.coder_rules, "utf8");
+      } catch { /* configured coder_rules path not found — try fallback */
+        try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+      }
     }
-  }
-  const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await coder.runTask({ prompt, onOutput, role: "coder" });
-  if (!result.ok) {
-    if (result.error) logger.error(result.error);
-    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
-  }
-  if (result.output) {
-    console.log(result.output);
-  }
-  if (result.error) {
-    logger.warn(result.error);
-  }
-  logger.info(`Coder completed (exit ${result.exitCode})`);
+    const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await coder.runTask({ prompt, onOutput, role: "coder" });
+    if (!result.ok) {
+      if (result.error) logger.error(result.error);
+      throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+    }
+    if (result.output) {
+      console.log(result.output);
+    }
+    if (result.error) {
+      logger.warn(result.error);
+    }
+    logger.info(`Coder completed (exit ${result.exitCode})`);
+    runLog.logText(`[coder] finished (exit=${result.exitCode})`);
+    return { ok: true };
+  });
 }

package/src/commands/discover.js

@@ -62,30 +62,35 @@ function formatDiscover(result, mode) {
 }
 
 export async function discoverCommand({ task, config, logger, mode, json }) {
-  const discoverRole = resolveRole(config, "discover");
-  await assertAgentsAvailable([discoverRole.provider]);
-  logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("discover", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const discoverRole = resolveRole(config, "discover");
+    await assertAgentsAvailable([discoverRole.provider]);
+    logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+    runLog.logText(`[discover] provider=${discoverRole.provider} mode=${mode || "gaps"}`);
 
-  const agent = createAgent(discoverRole.provider, config, logger);
-  const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "discover" });
+    const agent = createAgent(discoverRole.provider, config, logger);
+    const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "discover" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Discover failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Discover failed");
+    }
 
-  const parsed = parseDiscoverOutput(result.output);
+    const parsed = parseDiscoverOutput(result.output);
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.verdict) {
-    console.log(formatDiscover(parsed, mode || "gaps"));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Discover completed.");
+    if (parsed?.verdict) {
+      console.log(formatDiscover(parsed, mode || "gaps"));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Discover completed.");
+    return { ok: true };
+  });
 }

package/src/commands/plan.js

@@ -51,8 +51,16 @@ function formatHuTable(hus) {
  * kj plan "task" — generate plan + HUs
  */
 export async function planGenerateCommand({ task, config, logger, json, context }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("plan", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    return planGenerateImpl({ task, config, logger, json, context, runLog });
+  });
+}
+
+async function planGenerateImpl({ task, config, logger, json, context, runLog }) {
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
+  runLog.logText(`[planner] provider=${plannerRole.provider}`);
 
   const planner = createAgent(plannerRole.provider, config, logger);
   const prompt = buildPlannerPrompt({ task, context });
@@ -100,9 +108,11 @@ export async function planGenerateCommand({ task, config, logger, json, context
 
   const planId = await savePlan(projectDir, plan);
 
+  runLog.logText(`[planner] finished — hus=${plan.hus.length} plan=${planId}`);
+
   if (json) {
     console.log(JSON.stringify(plan, null, 2));
-    return;
+    return { ok: true };
   }
 
   if (parsed?.approach) {
@@ -116,6 +126,7 @@ export async function planGenerateCommand({ task, config, logger, json, context
   console.log(`Review:  kj plan show ${planId}`);
   console.log(`Approve: kj plan ready ${planId}`);
   console.log(`Execute: kj run --plan ${planId} "${task.slice(0, 40)}..."`);
+  return { ok: true };
 }
 
 /**

package/src/commands/researcher.js

@@ -20,21 +20,26 @@ function buildResearchPrompt(task) {
 }
 
 export async function researcherCommand({ task, config, logger }) {
-  const researcherRole = resolveRole(config, "researcher");
-  await assertAgentsAvailable([researcherRole.provider]);
-  logger.info(`Researcher (${researcherRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("researcher", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const researcherRole = resolveRole(config, "researcher");
+    await assertAgentsAvailable([researcherRole.provider]);
+    logger.info(`Researcher (${researcherRole.provider}) starting...`);
+    runLog.logText(`[researcher] provider=${researcherRole.provider}`);
 
-  const agent = createAgent(researcherRole.provider, config, logger);
-  const prompt = buildResearchPrompt(task);
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "researcher" });
+    const agent = createAgent(researcherRole.provider, config, logger);
+    const prompt = buildResearchPrompt(task);
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "researcher" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Researcher failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Researcher failed");
+    }
 
-  if (result.output) {
-    console.log(result.output);
-  }
-  logger.info("Researcher completed.");
+    if (result.output) {
+      console.log(result.output);
+    }
+    logger.info("Researcher completed.");
+    return { ok: true };
+  });
 }

package/src/commands/review.js

@@ -4,12 +4,15 @@ import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
 import { resolveReviewProfile } from "../review/profiles.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 export async function reviewCommand({ task, config, logger, baseRef }) {
-  const reviewerRole = resolveRole(config, "reviewer");
-  await assertAgentsAvailable([reviewerRole.provider]);
-  logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
-  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  return withCliRunLog("review", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const reviewerRole = resolveRole(config, "reviewer");
+    await assertAgentsAvailable([reviewerRole.provider]);
+    logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
+    runLog.logText(`[reviewer] provider=${reviewerRole.provider} baseRef=${baseRef || "(auto)"}`);
+    const reviewer = createAgent(reviewerRole.provider, config, logger);
 
   let diff;
   if (config.ci?.enabled) {
@@ -75,4 +78,7 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
       logger.warn(`CI dispatch failed (non-blocking): ${err.message}`);
     }
   }
+  runLog.logText(`[reviewer] finished (exit=${result.exitCode})`);
+  return { ok: true };
+  });
 }

package/src/commands/run.js

@@ -3,6 +3,7 @@ import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 import { printHeader } from "../utils/display/header.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { resolveRole } from "../config.js";
@@ -57,32 +58,41 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   // Quiet mode is the default; --verbose disables it
   const quietMode = config.output?.quiet !== false;
 
-  const emitter = new EventEmitter();
-  let activityLog = null;
+  return withCliRunLog("run", { projectDir: config?.projectDir, logger }, async ({ runLog, forwardProgress }) => {
+    runLog.logText(`[kj_run] task="${String(task).slice(0, 80)}..."`);
 
-  emitter.on("progress", (event) => {
-    if (!activityLog && event.sessionId) {
-      activityLog = createActivityLog(event.sessionId);
-      logger.onLog((entry) => activityLog.write(entry));
-    }
+    const emitter = new EventEmitter();
+    let activityLog = null;
 
-    if (activityLog) {
-      activityLog.writeEvent(event);
-    }
+    // Mirror every progress event into .kj/run.log so kj-tail works identically
+    // whether the command came from the MCP server or the CLI (KJC-TSK-0327 follow-up).
+    forwardProgress(emitter);
+
+    emitter.on("progress", (event) => {
+      if (!activityLog && event.sessionId) {
+        activityLog = createActivityLog(event.sessionId);
+        logger.onLog((entry) => activityLog.write(entry));
+      }
+
+      if (activityLog) {
+        activityLog.writeEvent(event);
+      }
+
+      if (!jsonMode) {
+        printEvent(event, { quiet: quietMode });
+      }
+    });
 
     if (!jsonMode) {
-      printEvent(event, { quiet: quietMode });
+      printHeader({ task: task, config });
     }
-  });
-
-  if (!jsonMode) {
-    printHeader({ task: task, config });
-  }
 
-  const askQuestion = createCliAskQuestion();
-  const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+    const askQuestion = createCliAskQuestion();
+    const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
-  if (jsonMode) {
-    console.log(JSON.stringify(result, null, 2));
-  }
+    if (jsonMode) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return { ok: !result?.paused && result?.approved !== false };
+  });
 }

package/src/commands/triage.js

@@ -34,30 +34,36 @@ function formatTriage(result) {
 }
 
 export async function triageCommand({ task, config, logger, json }) {
-  const triageRole = resolveRole(config, "triage");
-  await assertAgentsAvailable([triageRole.provider]);
-  logger.info(`Triage (${triageRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("triage", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const triageRole = resolveRole(config, "triage");
+    await assertAgentsAvailable([triageRole.provider]);
+    logger.info(`Triage (${triageRole.provider}) starting...`);
+    runLog.logText(`[triage] provider=${triageRole.provider}`);
 
-  const agent = createAgent(triageRole.provider, config, logger);
-  const prompt = buildTriagePrompt({ task });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "triage" });
+    const agent = createAgent(triageRole.provider, config, logger);
+    const prompt = buildTriagePrompt({ task });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "triage" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Triage failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Triage failed");
+    }
 
-  const parsed = parseMaybeJsonString(result.output);
+    const parsed = parseMaybeJsonString(result.output);
+    if (parsed?.level) runLog.logText(`[triage] level=${parsed.level} roles=${(parsed.roles || []).join(",")}`);
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.level) {
-    console.log(formatTriage(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Triage completed.");
+    if (parsed?.level) {
+      console.log(formatTriage(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Triage completed.");
+    return { ok: true };
+  });
 }

package/src/config.js

@@ -290,6 +290,20 @@ export async function loadConfig(projectDir) {
     throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
   }
 
+  // Deprecation tracking — `sonarqube.enabled` was a footgun: users would
+  // set it to `false` in their global ~/.karajan/kj.config.yml and then
+  // wonder why Sonar didn't run on a code task. Since v2.7.4 Sonar is
+  // intrinsic to Karajan for code tasks; the field is ignored. We surface
+  // a warning at run start (see emitConfigDeprecations in flow-runner.js)
+  // so users notice and clean up their config. Don't throw — keep
+  // back-compat so existing scripts keep working.
+  const userSetSonarEnabled = (globalConfig?.sonarqube?.enabled !== undefined)
+    || (projectConfig?.sonarqube?.enabled !== undefined);
+  if (userSetSonarEnabled) {
+    merged._deprecated = merged._deprecated || {};
+    merged._deprecated.sonarqubeEnabledKey = true;
+  }
+
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
@@ -423,7 +437,16 @@ function applyOutputModeOverrides(out, flags) {
 
 function applyMiscOverrides(out, flags) {
   if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
-  if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
+  // `--no-sonar` and `sonarqube.enabled: false` are deprecated since v2.7.4.
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and
+  // skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy.
+  // The flag is still accepted to avoid breaking scripts; it now emits a
+  // warning at run start and is otherwise ignored. See preflight-checks.js
+  // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  if (flags.noSonar || flags.sonar === false) {
+    out._deprecated = out._deprecated || {};
+    out._deprecated.noSonarFlag = true;
+  }
   out.sonarcloud = out.sonarcloud || {};
   if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
   if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;

package/src/mcp/direct-role-runner.js

@@ -53,6 +53,18 @@ export async function runDirectRole({
   await assertAgentsAvailable([role.provider]);
 
   const projectDir = await resolveProjectDir(server, args.projectDir);
+
+  // Allow taskFile as alternative to inline task — works for every direct
+  // role (discover/triage/researcher/architect/audit/impeccable/...) without
+  // per-handler wiring. The mutation is in-place on the role's runInput /
+  // initContext since they are already built with `task: a.task`.
+  if ((!runInput?.task || runInput.task === undefined) && args.taskFile) {
+    const { readTaskFile } = await import("../utils/task-file.js");
+    const loaded = await readTaskFile(args.taskFile, { projectDir });
+    if (runInput) runInput.task = loaded;
+    if (initContext) initContext.task = loaded;
+    args.task = loaded;
+  }
   const runLog = createRunLog(projectDir);
   const startMsg = logStartMsg || `[kj_${effectiveStage}] started`;
   runLog.logText(startMsg);

package/src/mcp/handlers/direct-handlers.js

@@ -56,6 +56,8 @@ export async function handlePlanDirect(a, server, extra) {
   await assertAgentsAvailable([plannerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
     ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
@@ -210,6 +212,8 @@ export async function handleCodeDirect(a, server, extra) {
   await assertAgentsAvailable([coderRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -261,6 +265,8 @@ export async function handleReviewDirect(a, server, extra) {
   await assertAgentsAvailable([reviewerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);

package/src/mcp/handlers/run-handler.js

@@ -267,8 +267,14 @@ export async function handleResume(a, server, extra) {
 }
 
 export async function handleRun(a, server, extra) {
+  const { ensureTaskFromFile, resolveProjectDir: _rpd } = await import("../shared-helpers.js");
+  try {
+    await ensureTaskFromFile(a, a.projectDir || (await _rpd(server, a.projectDir).catch(() => null)));
+  } catch (err) {
+    return failPayload(`taskFile read failed: ${err.message}`);
+  }
   if (!a.task) {
-    return failPayload("Missing required field: task");
+    return failPayload("Missing required field: task (or pass taskFile with a .md path)");
   }
   if (a.taskType) {
     const validTypes = new Set(["sw", "infra", "doc", "add-tests", "refactor"]);

package/src/mcp/shared-helpers.js

@@ -21,6 +21,29 @@ export { classifyError } from "./error-classifiers.js";
  * Resolve the user's project directory.
  * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
  */
+/**
+ * Resolve the `task` argument for MCP handlers. If the caller passed
+ * `a.taskFile` (instead of or in addition to `a.task`), read the file and
+ * set `a.task` to its trimmed content. When both are given, the explicit
+ * `a.task` wins (symmetric with CLI `resolveTaskInput`).
+ *
+ * Mutates `a` in place so downstream handlers keep reading `a.task`
+ * without any change. Returns `a` for convenience.
+ *
+ * @param {Object} a
+ * @param {string} [projectDir]  - used to resolve relative file paths
+ * @returns {Promise<Object>}    - the same `a`, with `a.task` filled in
+ */
+export async function ensureTaskFromFile(a, projectDir) {
+  if (!a) return a;
+  const hasTask = typeof a.task === "string" && a.task.trim().length > 0;
+  const hasFile = typeof a.taskFile === "string" && a.taskFile.trim().length > 0;
+  if (hasTask || !hasFile) return a;
+  const { readTaskFile } = await import("../utils/task-file.js");
+  a.task = await readTaskFile(a.taskFile, { projectDir });
+  return a;
+}
+
 export async function resolveProjectDir(server, explicitProjectDir) {
   if (explicitProjectDir) return explicitProjectDir;