karajan-code 2.7.2 → 2.7.4

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

@@ -726,6 +726,12 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
 
   let updatedConfig = resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags });
 
+  // Deprecation warnings recorded at config load time. Done here, after
+  // policies are resolved, so the message lands in context: if the user's
+  // legacy `sonarqube.enabled: false` is being ignored, this is the right
+  // moment for them to see it.
+  emitConfigDeprecations(updatedConfig, logger, emitter, eventBase);
+
   // --- Preflight environment checks ---
   const preflightResult = await runPreflightChecks({
     config: updatedConfig, logger, emitter, eventBase,
@@ -920,6 +926,46 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
  * Setting skills.addyosmani.enabled = false, or removing "addyosmani" from
  * skills.sources, disables this step entirely (reverts to OpenSkills-only).
  */
+/**
+ * Print one-time deprecation warnings for config keys / CLI flags that
+ * Karajan no longer honours. Called once per run, after policy resolution
+ * so the message lands in context (the user sees what's being ignored
+ * RIGHT before the preflight that would have been affected).
+ *
+ * Currently surfaces:
+ *   - `sonarqube.enabled` set in user config → ignored since v2.7.4
+ *   - `--no-sonar` CLI flag → ignored since v2.7.4
+ */
+function emitConfigDeprecations(config, logger, emitter, eventBase) {
+  const dep = config?._deprecated;
+  if (!dep) return;
+
+  if (dep.sonarqubeEnabledKey) {
+    const m =
+      "DEPRECATED: `sonarqube.enabled` in kj.config.yml is ignored 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. " +
+      "Remove the key from your config to silence this warning.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { key: "sonarqube.enabled", since: "v2.7.4" },
+    }));
+  }
+
+  if (dep.noSonarFlag) {
+    const m =
+      "DEPRECATED: `--no-sonar` flag is ignored since v2.7.4. Sonar runs for code " +
+      "tasks by policy. To skip Sonar on a one-off run, use a non-code task type " +
+      "(e.g. `--task-type doc`) or rely on Solomon's runtime override.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { flag: "--no-sonar", since: "v2.7.4" },
+    }));
+  }
+}
+
 async function ensureAddyosmaniSkills({ task, config, logger, session, emitter, eventBase }) {
   const skillsConfig = config?.skills || {};
   const sources = Array.isArray(skillsConfig.sources) ? skillsConfig.sources : ["addyosmani", "openskills", "local"];
@@ -1173,9 +1219,17 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
 
-  const skipSonarForTaskType = new Set(["infra", "doc", "no-code"]);
-  const effectiveTaskType = session.resolved_policies?.taskType || null;
-  if (config.sonarqube.enabled && !skipSonarForTaskType.has(effectiveTaskType)) {
+  // Sonar runs for code tasks per policy. Since v2.7.4 it is NOT
+  // toggleable via config — that's intrinsic to Karajan. The taskType
+  // policy (resolved_policies.sonar) is the single source of truth.
+  // Solomon may skip a single iteration via rule alerts; that's a
+  // runtime decision, not a config option.
+  //
+  // Test-only escape hatch: globalThis.__KJ_DISABLE_SONAR_STAGE forces
+  // the sonar stage off so tests don't have to spin up Docker. Set in
+  // tests/setup.js by default; production code never sees it.
+  const sonarStageDisabledForTest = globalThis.__KJ_DISABLE_SONAR_STAGE === true;
+  if (!sonarStageDisabledForTest && session.resolved_policies?.sonar !== false) {
     const sonarResult = await runSonarStage({
       config, logger, emitter, eventBase, session, trackBudget, iteration: i,
       repeatDetector, budgetSummary, sonarState, askQuestion, task, brainCtx
@@ -1864,7 +1918,11 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   } catch (initError) {
     // Pre-loop stage failure → Solomon decides
     logger.warn(`Init/pre-loop error — escalating to Solomon: ${initError.message}`);
-    const tempSession = { id: "init-error", task, status: "failed" };
+    // tempSession needs `checkpoints` because invokeSolomon → addCheckpoint
+    // pushes into it. Pre-v2.7.4 this lacked the array and crashed with
+    // "Cannot read properties of undefined (reading 'push')" the moment
+    // Solomon was consulted on a preflight failure.
+    const tempSession = { id: "init-error", task, status: "failed", checkpoints: [] };
     const solomonResult = await invokeSolomon({
       config, logger, emitter, eventBase: { sessionId: "init-error", iteration: 0, stage: "init", startedAt: Date.now() },
       stage: "init_error", askQuestion, session: tempSession, iteration: 0,

package/src/orchestrator/preflight-checks.js

@@ -168,7 +168,21 @@ async function checkSecurityAgent(config) {
  * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[], errors: object[] }}
  */
 export async function runPreflightChecks({ config, logger, emitter, eventBase, resolvedPolicies, securityEnabled }) {
-  const sonarEnabled = Boolean(config.sonarqube?.enabled) && resolvedPolicies.sonar !== false;
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests).
+  // Since v2.7.4 it is NOT toggleable via `config.sonarqube.enabled` —
+  // that field is ignored (deprecation warning emitted at config load).
+  // The taskType policy (resolved_policies.sonar from DEFAULT_POLICIES in
+  // src/guards/policy-resolver.js) is the single source of truth: sw /
+  // refactor / add-tests run Sonar, audit / doc / infra / analysis /
+  // no-code skip it. Solomon may decide to skip a single iteration via
+  // rule alerts — that's a runtime decision, not a config option.
+  //
+  // Test-only escape hatch: globalThis.__KJ_DISABLE_SONAR_STAGE === true
+  // forces sonar OFF in preflight too, so tests that don't want sonar
+  // events in their expected sequence don't have to set up Docker mocks.
+  // Set in tests/setup.js by default; production code never sees it.
+  const sonarStageDisabledForTest = globalThis.__KJ_DISABLE_SONAR_STAGE === true;
+  const sonarEnabled = !sonarStageDisabledForTest && resolvedPolicies.sonar !== false;
   const isExternalSonar = Boolean(config.sonarqube?.external);
   const sonarHost = resolveSonarHost(config.sonarqube?.host);
 

package/src/session-store.js

@@ -44,6 +44,12 @@ export async function loadSession(sessionId) {
 }
 
 export async function addCheckpoint(session, checkpoint) {
+  // Defensive: any caller that builds a stub session (e.g. the init-error
+  // path in flow-runner.js, where `tempSession = { id, task, status }` has
+  // no checkpoints array) would otherwise crash with
+  // "Cannot read properties of undefined (reading 'push')". Guard once here
+  // so the bug class is gone instead of fixing every call site.
+  if (!Array.isArray(session.checkpoints)) session.checkpoints = [];
   session.checkpoints.push({ at: new Date().toISOString(), ...checkpoint });
   await saveSession(session);
 }

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();
+}