karajan-code 2.7.1 → 2.7.3

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/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;
 

package/src/mcp/tools.js

@@ -54,9 +54,9 @@ export const tools = [
       "Run the full Karajan pipeline. IMPORTANT: Pass the user's task description exactly as they wrote it. Do NOT group, split, reorder, or modify tasks yourself. Karajan handles decomposition, role activation, iteration, and quality gates internally. Do NOT override pipeline parameters (enableHuReviewer, mode, methodology) unless the user explicitly requested it. If you have observations about the task, use kj_suggest instead.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042). Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md (or any text file) whose contents become the task description. Relative paths resolve against projectDir." },
         plan: { type: "string", description: "Plan ID from kj_plan. Loads persisted plan context and skips researcher/architect/planner stages." },
         projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
@@ -195,9 +195,9 @@ export const tools = [
     description: "Run coder-only mode. Pass the user's task exactly as described. Do NOT split or reinterpret the task.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         coder: { type: "string" },
         coderModel: { type: "string" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
@@ -210,9 +210,9 @@ export const tools = [
     description: "Run reviewer-only mode against current diff. Do NOT filter or pre-process the diff before passing it.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         reviewer: { type: "string" },
         reviewerModel: { type: "string" },
         baseRef: { type: "string" },
@@ -236,9 +236,9 @@ export const tools = [
     description: "Generate implementation plan for a task. Pass the task as the user described it. Karajan's planner decides the approach.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         planner: { type: "string" },
         plannerModel: { type: "string" },
         coder: { type: "string", description: "Legacy alias for planner" },
@@ -253,9 +253,9 @@ export const tools = [
     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" },
+        task: { type: "string", description: "Task description to analyze for gaps. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         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." },
@@ -270,9 +270,9 @@ export const tools = [
     description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to classify" },
+        task: { type: "string", description: "Task description to classify. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
@@ -283,9 +283,9 @@ export const tools = [
     description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to research" },
+        task: { type: "string", description: "Task description to research. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
@@ -296,9 +296,9 @@ export const tools = [
     description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to architect" },
+        task: { type: "string", description: "Task description to architect. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         context: { type: "string", description: "Additional context (e.g., researcher output)" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
@@ -311,6 +311,8 @@ export const tools = [
     inputSchema: {
       type: "object",
       properties: {
+        task: { type: "string", description: "Optional focus for the audit. If absent (and no taskFile), defaults to a full-codebase analysis." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file with the audit focus." },
         projectDir: { type: "string", description: "Absolute path to the project to audit" },
         dimensions: { type: "string", description: "Comma-separated dimensions to analyze: security,codeQuality,performance,architecture,testing (default: all)" },
         kjHome: { type: "string" }

package/src/orchestrator/flow-runner.js

@@ -452,6 +452,14 @@ async function finalizeApprovedSession({ config, gitCtx, task, logger, session,
         finishedAt: new Date().toISOString(),
         brainDecisions: Array.isArray(session.brainDecisions) ? session.brainDecisions.length : 0,
         solomonInvocations: Array.isArray(session.solomonRulings) ? session.solomonRulings.length : 0,
+        // KJC-TSK-0327: surface skill-source decisions in the summary so the
+        // post-mortem shows which process skills (addyosmani) and stack skills
+        // (OpenSkills) actually shaped the role prompts.
+        skills: {
+          addyosmani: session.addyosmaniSkills,
+          installed: session.autoInstalledSkills,
+          recommended: session.skillsRecommended,
+        },
       }, { logger });
       logger.info(`Session journal written to ${journalDir}`);
     } catch (err) {

package/src/session/journal/summary-writer.js

@@ -26,6 +26,10 @@ import path from "node:path";
  * @property {string} [finishedAt]                 - ISO timestamp (optional)
  * @property {number} [solomonInvocations]
  * @property {number} [brainDecisions]
+ * @property {Object} [skills]                        - skill sources used this session (KJC-TSK-0327)
+ * @property {Object} [skills.addyosmani]             - { available, action, resolvedSlugs, reason }
+ * @property {string[]} [skills.installed]            - OpenSkills installed this run (session.autoInstalledSkills)
+ * @property {string[]} [skills.recommended]          - wouldHaveUsed when OpenSkills CLI missing
  */
 
 function esc(text) {
@@ -103,6 +107,48 @@ function renderBreakdownByRole(breakdown) {
   return ["| Role | Tokens | Cost |", "|---|---|---|", ...rows].join("\n");
 }
 
+/**
+ * Render the Skills section: which process skills (addyosmani) were resolved
+ * for the task, which OpenSkills were installed, and which skills would have
+ * helped but couldn't be installed (graceful-degradation path).
+ *
+ * Returns null when no skill activity happened (no addyosmani, no installs,
+ * no recommendations) so the section is elided.
+ */
+function renderSkills(skills) {
+  if (!skills || typeof skills !== "object") return null;
+  const addy = skills.addyosmani;
+  const installed = Array.isArray(skills.installed) ? skills.installed : [];
+  const recommended = Array.isArray(skills.recommended) ? skills.recommended : [];
+
+  const hasAddy = addy && (addy.available === true || addy.available === false);
+  if (!hasAddy && installed.length === 0 && recommended.length === 0) return null;
+
+  const lines = [];
+
+  if (hasAddy) {
+    if (addy.available) {
+      const action = addy.action || "ready";
+      const slugs = Array.isArray(addy.resolvedSlugs) ? addy.resolvedSlugs : [];
+      lines.push(`- **addyosmani/agent-skills** (process, 1st source): ${esc(action)}` +
+        (slugs.length > 0 ? ` — resolved slugs: ${slugs.map((s) => `\`${esc(s)}\``).join(", ")}` : " — no role/task-specific slugs resolved"));
+    } else {
+      const reason = addy.reason ? ` — ${esc(addy.reason)}` : "";
+      lines.push(`- **addyosmani/agent-skills**: unavailable${reason}`);
+    }
+  }
+
+  if (installed.length > 0) {
+    lines.push(`- **OpenSkills installed**: ${installed.map((s) => `\`${esc(s)}\``).join(", ")}`);
+  }
+
+  if (recommended.length > 0) {
+    lines.push(`- **OpenSkills recommended** (CLI missing, would-have-used): ${recommended.map((s) => `\`${esc(s)}\``).join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
 function renderJournalLinks(files) {
   if (!Array.isArray(files) || files.length === 0) return "_No additional journal files._";
   return files.map((f) => `- [${esc(f)}](./${f})`).join("\n");
@@ -146,6 +192,11 @@ export function buildSummaryMarkdown(input) {
     sections.push("", "## Budget breakdown (by role)", "", breakdown);
   }
 
+  const skillsSection = renderSkills(input.skills);
+  if (skillsSection) {
+    sections.push("", "## Skills Used", "", skillsSection);
+  }
+
   sections.push("", "## Commits", "", renderCommits(input.commits));
 
   sections.push("", "## Journal files", "", renderJournalLinks(input.files));

package/src/utils/cli-run-log.js

@@ -0,0 +1,83 @@
+/**
+ * Shared run.log wrapper for CLI commands.
+ *
+ * Every MCP handler (`kj_run`, `kj_audit`, `kj_code`, `kj_review`, ...) writes
+ * progress + lifecycle events to `<projectDir>/.kj/run.log` via
+ * `createRunLog()`. `kj-tail` reads that file in real time to show pipeline
+ * activity. Until this module, the CLI (`kj run`, `kj audit`, ...) did NOT
+ * write that log at all, so running the same command as a shell (vs MCP)
+ * produced silence in `kj-tail`. This helper closes that asymmetry: CLI
+ * commands that opt in get the same run.log behavior as MCP.
+ *
+ * Usage pattern:
+ *
+ *   import { withCliRunLog } from "../utils/cli-run-log.js";
+ *
+ *   export async function fooCommand({ task, config, logger }) {
+ *     return withCliRunLog("foo", { projectDir: config.projectDir }, async ({ runLog, forwardProgress }) => {
+ *       runLog.logText(`[kj_foo] args — task="${task.slice(0, 80)}"`);
+ *
+ *       const emitter = new EventEmitter();
+ *       forwardProgress(emitter);   // every emitter.emit("progress", event) also lands in run.log
+ *
+ *       // ... run the work ...
+ *       return { ok: true };
+ *     });
+ *   }
+ *
+ * The wrapper guarantees:
+ *   - `.kj/run.log` is created/truncated at the start.
+ *   - A `[kj_<cmd>] started` line is written immediately so kj-tail shows the
+ *     command began (even if no emitter events follow — e.g. `kj audit` which
+ *     streams agent output directly).
+ *   - A `[kj_<cmd>] finished` (or `failed — <error>`) line is written at the
+ *     end, even if the inner function throws.
+ *   - The file descriptor is always closed.
+ *   - `forwardProgress(emitter)` is a no-op when the command doesn't use an
+ *     EventEmitter (e.g. one-shot agent calls). Commands that do emit
+ *     progress events (like `kj run`) get the same per-event coverage as MCP.
+ */
+
+import { createRunLog } from "./run-log.js";
+
+/**
+ * Wrap a CLI command body with run.log lifecycle management.
+ *
+ * @template T
+ * @param {string} commandName         - short slug, e.g. "run", "audit", "code"
+ * @param {Object}  opts
+ * @param {string} [opts.projectDir]   - project root; defaults to `process.cwd()`
+ * @param {Object} [opts.logger]       - optional logger for close-time warnings
+ * @param {(ctx: {
+ *   runLog: ReturnType<typeof createRunLog>,
+ *   forwardProgress: (emitter: import("node:events").EventEmitter) => void,
+ * }) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withCliRunLog(commandName, opts, fn) {
+  const projectDir = opts?.projectDir || process.cwd();
+  const runLog = createRunLog(projectDir);
+
+  runLog.logText(`[kj_${commandName}] started (cli)`);
+
+  const forwardProgress = (emitter) => {
+    if (!emitter || typeof emitter.on !== "function") return;
+    emitter.on("progress", (event) => {
+      try {
+        runLog.logEvent(event);
+      } catch { /* best-effort */ }
+    });
+  };
+
+  try {
+    const result = await fn({ runLog, forwardProgress });
+    const ok = result && result.ok !== false;
+    runLog.logText(`[kj_${commandName}] finished — ok=${ok}`);
+    return result;
+  } catch (err) {
+    runLog.logText(`[kj_${commandName}] failed — ${err?.message || String(err)}`);
+    throw err;
+  } finally {
+    runLog.close();
+  }
+}

package/src/utils/task-file.js

@@ -0,0 +1,109 @@
+/**
+ * Load a task description from a file (.md / .txt / .markdown / any plain text).
+ *
+ * Motivation: for anything beyond a one-line task, writing a `kj run "long
+ * multi-paragraph prompt ..."` becomes painful — escaping quotes, losing
+ * markdown formatting, no history. `kj run --task-file my-task.md` reads the
+ * file's contents and uses them as the task description. Same for `kj plan`,
+ * `kj audit`, `kj code`, and their MCP counterparts (via the `taskFile`
+ * argument).
+ *
+ * Behaviour:
+ *   - `taskFile` may be relative (resolved against `process.cwd()` by default,
+ *     or against `projectDir` if supplied) or absolute.
+ *   - Accepts any text file; markdown is the expected common case but we do
+ *     not require a specific extension.
+ *   - Trimmed of leading/trailing whitespace so agents don't get empty lines
+ *     around the task.
+ *   - `maxBytes` (default 256 KiB) guards against accidentally passing a huge
+ *     file (log dumps, PDFs). Agents choke on very long prompts anyway.
+ *   - Precedence with the positional `task` arg is decided by the caller:
+ *     this helper only loads, never merges. Convention used across commands:
+ *     when BOTH are provided, the positional task wins and the file is a
+ *     fallback — with a log warning so the user notices.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_TASK_FILE_MAX_BYTES = 256 * 1024;
+
+/**
+ * @param {string} filePath                - relative or absolute
+ * @param {Object} [opts]
+ * @param {string} [opts.projectDir]       - base dir for relative paths; defaults to process.cwd()
+ * @param {number} [opts.maxBytes]         - size cap; default 256 KiB
+ * @returns {Promise<string>}              - the trimmed file contents (task text)
+ * @throws                                 - Error with a user-readable message when the file is
+ *                                           missing, unreadable, empty, or over the size cap.
+ */
+export async function readTaskFile(filePath, opts = {}) {
+  if (!filePath || typeof filePath !== "string") {
+    throw new Error("readTaskFile: path must be a non-empty string");
+  }
+  const { projectDir, maxBytes = DEFAULT_TASK_FILE_MAX_BYTES } = opts;
+  const base = projectDir || process.cwd();
+  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(base, filePath);
+
+  let stat;
+  try {
+    stat = await fs.stat(resolved);
+  } catch (err) {
+    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Task file is not a regular file: ${resolved}`);
+  }
+  if (stat.size > maxBytes) {
+    const kb = Math.round(stat.size / 1024);
+    const capKb = Math.round(maxBytes / 1024);
+    throw new Error(
+      `Task file is too large: ${resolved} (${kb} KiB > ${capKb} KiB cap). ` +
+      `Summarise the task or raise the limit with the caller's maxBytes option.`
+    );
+  }
+
+  const raw = await fs.readFile(resolved, "utf8");
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error(`Task file is empty (or whitespace-only): ${resolved}`);
+  }
+  return trimmed;
+}
+
+/**
+ * Resolve the task text a command should use, given both positional `task`
+ * and an optional `taskFile`. Single source of truth for precedence across
+ * CLI and MCP entry points.
+ *
+ * Rules:
+ *   - Neither provided → throw (caller decides the UX; typically propagates).
+ *   - Only `task` → returns it, untouched.
+ *   - Only `taskFile` → reads and returns it.
+ *   - Both → `task` wins; emits a warning through `logger.warn` (if given).
+ *
+ * @param {Object} args
+ * @param {string|undefined} args.task
+ * @param {string|undefined} args.taskFile
+ * @param {string} [args.projectDir]
+ * @param {Object} [args.logger]             - optional; uses `logger.warn(msg)` only
+ * @returns {Promise<string>}
+ */
+export async function resolveTaskInput({ task, taskFile, projectDir, logger } = {}) {
+  const hasTask = typeof task === "string" && task.trim().length > 0;
+  const hasFile = typeof taskFile === "string" && taskFile.trim().length > 0;
+
+  if (!hasTask && !hasFile) {
+    throw new Error("No task provided. Pass a task argument or --task-file <path>.");
+  }
+  if (hasTask && hasFile) {
+    logger?.warn?.(
+      `Both task and --task-file given; using the positional task and ignoring file: ${taskFile}`
+    );
+    return task.trim();
+  }
+  if (hasFile) {
+    return readTaskFile(taskFile, { projectDir });
+  }
+  return task.trim();
+}