karajan-code 2.7.2 → 2.7.4

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.7.2 released** — Skills observability: `summary.md` now shows a "Skills Used" section listing the addyosmani slugs resolved per role + OpenSkills installed/recommended, and `kj-tail` v1.37.0 highlights `[skills:*]` events with a 🎯 icon (magenta on success, yellow on graceful-degradation). Carries the full v2.7 feature set: [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) as Karajan's first-source process catalog (20+ lifecycle workflows — TDD, code-review-and-quality, security-and-hardening, performance-optimization, git-workflow-and-versioning, CI/CD, debugging-and-error-recovery, spec-driven-development, planning-and-task-breakdown…) injected per role **before** OpenSkills stack skills, shallow-cloned into `~/.karajan/agent-skills/` and refreshed weekly via `git pull`. SEA platform binaries (`linux-x64`, `darwin-arm64`, `win-x64`) publish correctly again after the v2.7.1 workflow fix. New CLI: `kj skills sync-addyosmani`, `kj skills list-addyosmani`. New config: `skills.sources`, `skills.addyosmani.{enabled,refreshDays,repoUrl}`. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.7.4 released** — Three contract fixes: (1) **Sonar is now intrinsic** to Karajan for code tasks (`sw`/`refactor`/`add-tests`) — `sonarqube.enabled` config and `--no-sonar` flag are ignored with a deprecation warning; a code task without a quality gate is not a job Karajan calls complete, like TDD; Solomon still may skip an iteration at runtime via rules. (2) **Preflight no longer demands API keys Karajan doesn't use** — the bogus `ANTHROPIC_API_KEY not set` check was blocking every Claude Code MCP run; replaced with a real CLI availability check (`claude`, `codex`, `gemini` on PATH). (3) **Orchestrator no longer crashes** with `Cannot read properties of undefined (reading 'push')` on the Solomon init-error path. Adds two architectural invariants (`no-provider-apis`, `sonar-intrinsic`) to CI so the contracts can't silently drift back. New `docs/TESTS.md` test-suite guide with diagrams. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -297,9 +297,9 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 | Tool | Why |
 |------|-----|
 | [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues directly from the agent |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
+| [**Planning Game MCP**](https://github.com/manufosela/planning-game-xp-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
+| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Create PRs, manage issues directly from the agent |
+| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
 
 ## Contributing
 

package/bin/kj-tail

@@ -4,7 +4,7 @@
 
 set -euo pipefail
 
-VERSION="1.37.0"
+VERSION="1.38.0"
 
 # ── Colors ──────────────────────────────────────────────
 RED='\033[0;31m'
@@ -94,15 +94,42 @@ PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 LOG_FILE="${PROJECT_DIR}/.kj/run.log"
 
 # ── Locate log ──────────────────────────────────────────
+# When the log does not exist yet, kj-tail stays open and polls until any
+# `kj` / `kj_*` invocation creates it. Exit with Ctrl-C. This used to be a
+# hard exit, which forced the user to time `kj-tail` start vs. the command;
+# too easy to miss early lines. Follow-mode and snapshot mode both get this.
 if [[ ! -f "$LOG_FILE" ]]; then
-  echo -e "${RED}No run log found at ${LOG_FILE}${RESET}"
-  echo ""
-  echo "The run log is created when Karajan starts a pipeline."
-  echo "Make sure you're in the project directory, or pass it as argument:"
+  if [[ "$FOLLOW" == "false" ]]; then
+    # Snapshot mode (-s): nothing to print, say so and exit cleanly.
+    echo -e "${YELLOW}No run log at ${LOG_FILE} yet.${RESET}"
+    echo ""
+    echo "The log is created when Karajan starts a pipeline — run any of:"
+    echo "  kj run \"...\"    kj audit    kj code    kj review    kj plan"
+    echo "  mcp__karajan-mcp__kj_run / kj_audit / kj_code / kj_review / kj_plan ..."
+    echo ""
+    exit 0
+  fi
+
+  echo -e "${YELLOW}Waiting for run log to appear at ${LOG_FILE}${RESET}"
+  echo -e "${DIM}(It is created the moment you run any kj command that invokes the orchestrator or a role.${RESET}"
+  echo -e "${DIM} Ctrl-C to stop waiting. Triggers: kj run/audit/code/review/plan/discover/triage/researcher/architect, or the same via MCP.)${RESET}"
   echo ""
-  echo "  kj-tail /path/to/project"
+  # Ensure parent dir exists so we can poll even on a fresh project
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+  # Poll every 500ms until the file shows up (low CPU, visible responsiveness).
+  # Cap at 4h (28800 ticks) to avoid infinite stuck monitors; after the cap we
+  # exit 0 so tmux/screen panes don't linger as errors.
+  tick=0
+  while [[ ! -f "$LOG_FILE" ]]; do
+    sleep 0.5
+    tick=$((tick + 1))
+    if (( tick >= 28800 )); then
+      echo -e "${YELLOW}Still no run log after 4h — exiting. Re-run kj-tail when ready.${RESET}"
+      exit 0
+    fi
+  done
+  echo -e "${GREEN}Log appeared — streaming...${RESET}"
   echo ""
-  exit 1
 fi
 
 # ── Filter & colorize ──────────────────────────────────

package/package.json

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

package/src/checks/node.js

@@ -1,12 +1,18 @@
 /**
- * Node.js runtime version check. Requires Node >= 20 (minimum version that
- * ships structuredClone, Array.prototype.findLast, AbortSignal.timeout, and
- * stable fetch). Strategy: manual — we cannot auto-upgrade the runtime.
+ * Node.js runtime version check. Requires Node >= 18 — the LTS baseline that
+ * ships every runtime feature Karajan needs: ESM support, `fetch` (built-in),
+ * `structuredClone` (17+), `AbortSignal.timeout` (17.3+), and
+ * `Array.prototype.findLast` / `findLastIndex` (18+). Nothing in the runtime
+ * code path uses Node 20+ APIs (no `Promise.withResolvers`, no
+ * `Object.groupBy`, no `Set.prototype.union/intersection`, no
+ * `Array.prototype.toSorted`). Strategy: manual — we cannot auto-upgrade the
+ * runtime. Users on older Node get a clear upgrade instruction with nvm + brew
+ * hints instead of a silent runtime crash.
  */
 
 import { STRATEGY } from "./types.js";
 
-export const MIN_NODE_MAJOR = 20;
+export const MIN_NODE_MAJOR = 18;
 
 /**
  * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns

package/src/checks/ports.js

@@ -38,7 +38,18 @@ export function createSonarPortCheck() {
     name: "port:sonar",
     label: "SonarQube port",
     strategy: STRATEGY.MANUAL,
-    applies: (config) => config?.sonarqube?.enabled !== false,
+    // Since v2.7.4 Sonar is intrinsic to Karajan for code tasks, so the
+    // port check almost always applies. The only legitimate skip is when
+    // the user runs their own external Sonar instance (`external: true`),
+    // in which case the port is managed outside Karajan. The legacy
+    // `sonarqube.enabled` field is ignored (deprecation warning emitted
+    // at config load time — see emitConfigDeprecations in flow-runner.js).
+    applies: (config) => {
+      if (config?.sonarqube?.external === true) {
+        return { applies: false, reason: "sonarqube.external is true — port managed outside Karajan" };
+      }
+      return true;
+    },
     async detect({ config }) {
       const port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
       const free = await isPortAvailable(port);
@@ -73,7 +84,12 @@ export function createHuBoardPortCheck() {
     name: "port:hu-board",
     label: "HU Board port",
     strategy: STRATEGY.AUTO,
-    applies: (config) => config?.hu_board?.enabled !== false,
+    applies: (config) => {
+      if (config?.hu_board?.enabled === false) {
+        return { applies: false, reason: "hu_board.enabled is false in kj.config.yml — HU Board dashboard skipped" };
+      }
+      return true;
+    },
     describe: "Rebind HU Board to the next free port",
     async detect({ config }) {
       const port = config?.hu_board?.port || DEFAULT_HU_BOARD_PORT;

package/src/checks/runner.js

@@ -55,19 +55,35 @@ export async function runChecks(checks, ctx, options = {}) {
   const overrides = {};
 
   // Build applicable entries (skipped checks noted up front).
+  // A check.applies(config) may return:
+  //   - true / false — boolean form (back-compat).
+  //   - an object { applies: boolean, reason?: string } — when false, `reason`
+  //     is shown verbatim so users see WHY (e.g. "sonarqube.enabled is false
+  //     in kj.config.yml") instead of the opaque "Not applicable" message
+  //     that confused users debugging their config.
   for (const check of checks) {
-    if (typeof check.applies === "function" && !check.applies(config)) {
-      entries.push({
-        check,
-        status: STATUS.SKIPPED,
-        detail: "Not applicable for current configuration",
-        runMs: 0,
-        detectResult: null,
-        remediated: false,
-      });
-    } else {
+    if (typeof check.applies !== "function") {
+      entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
+    }
+    const verdict = check.applies(config);
+    const isObj = verdict && typeof verdict === "object" && "applies" in verdict;
+    const applies = isObj ? Boolean(verdict.applies) : Boolean(verdict);
+    if (applies) {
       entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
     }
+    const reason = (isObj && typeof verdict.reason === "string" && verdict.reason.trim())
+      ? verdict.reason.trim()
+      : "Not applicable for current configuration";
+    entries.push({
+      check,
+      status: STATUS.SKIPPED,
+      detail: reason,
+      runMs: 0,
+      detectResult: null,
+      remediated: false,
+    });
   }
 
   // Phase 1: detect in parallel with timeout.

package/src/checks/tokens.js

@@ -1,41 +1,83 @@
 /**
- * API token availability checks.
+ * Provider CLI availability checks (preflight).
  *
- * Provider tokens (ANTHROPIC_API_KEY / OPENAI_API_KEY / ...) are LAZY:
- * we only check them for providers that are actually used by at least one
- * active role in the current config.
+ * IMPORTANT — Karajan does NOT call provider APIs directly. There is no
+ * `@anthropic-ai/sdk`, no `openai`, no `@google/generative-ai` in
+ * package.json. Every active role spawns its agent CLI as a subprocess
+ * (`claude`, `codex`, `gemini`, `opencode`, `aider`). The CLI handles its
+ * own auth, typically via OAuth + on-disk token (Claude Code, Codex CLI,
+ * Gemini CLI). The user does NOT need to set ANTHROPIC_API_KEY etc. for
+ * Karajan to work.
  *
- * Strategy:
- *   - Required providers with no key → FAIL, strategy manual (we can't
- *     fetch an API key for the user). Fix hint includes the how-to URL.
- *   - Optional providers (opencode, aider) without key → WARN.
- *   - GH_TOKEN is checked when git.auto_pr=true, strategy prompt (we can
- *     launch `gh auth login` with user approval).
+ * Pre-v2.7.4 this module checked for ANTHROPIC_API_KEY / OPENAI_API_KEY /
+ * GEMINI_API_KEY env vars and FAILed preflight when missing — a false
+ * positive that blocked every user running Karajan as an MCP child of
+ * Claude Code (where `apiKeySource: "none"` is the norm). Replaced with a
+ * CLI-availability check that mirrors what the orchestrator actually does.
+ *
+ * GH_TOKEN is still checked when `git.auto_pr=true`, because that flow uses
+ * `git push` directly with the env var.
  */
 
 import { checkBinary } from "../utils/agent-detect.js";
-import { getRequiredProviderEnvs, hasEnvVar } from "../utils/provider-env.js";
+import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
 import { STRATEGY } from "./types.js";
 
 /**
- * A single provider env check. One is created per active provider.
+ * Map canonical provider name → the CLI binary Karajan actually spawns.
+ * Keep in sync with src/agents/index.js.
  */
-function createProviderTokenCheck(entry) {
+const PROVIDER_TO_CLI = Object.freeze({
+  anthropic: "claude",
+  openai: "codex",
+  google: "gemini",
+  opencode: "opencode",
+  aider: "aider",
+});
+
+/**
+ * Build a CLI-availability check for one provider.
+ *
+ * The check runs `<cli> --version`. If the binary is on PATH and exits 0,
+ * preflight passes — Karajan can spawn it. If the CLI is missing, preflight
+ * fails with the install URL we already track in PROVIDER_ENV.
+ *
+ * Note: we do NOT verify that the CLI is *authenticated*. Doing so would
+ * require provider-specific introspection (`claude doctor`, `codex login
+ * status`, ...), each with its own quirks and exit codes. If the CLI is
+ * present but not logged in, the agent will fail at the first request with
+ * a clear error — and the orchestrator surfaces that error already.
+ */
+function createProviderCliCheck(entry) {
+  const cli = PROVIDER_TO_CLI[entry.provider];
   return {
-    name: `token:${entry.provider}`,
-    label: `API token: ${entry.provider}`,
+    name: `cli:${entry.provider}`,
+    label: `${entry.provider} CLI (${cli})`,
     strategy: STRATEGY.MANUAL,
     async detect() {
-      const ok = hasEnvVar(entry);
-      if (ok) {
-        return { ok: true, severity: "info", detail: `${entry.envVars[0]} is set` };
+      if (!cli) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Unknown CLI for provider ${entry.provider}`,
+          extra: { provider: entry.provider },
+        };
+      }
+      const result = await checkBinary(cli);
+      if (result.ok) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `${cli} on PATH (${result.version || "version unknown"})`,
+          extra: { provider: entry.provider, cli, version: result.version, path: result.path },
+        };
       }
       return {
         ok: false,
         severity: entry.optional ? "warn" : "fail",
-        detail: `${entry.envVars.join(" / ")} not set`,
-        fix: `Get an API key at ${entry.howToGetUrl} and export ${entry.envVars[0]}=...`,
-        extra: { provider: entry.provider, envVars: entry.envVars, howToGetUrl: entry.howToGetUrl },
+        detail: `${cli} not found on PATH`,
+        fix: `Install the ${cli} CLI: see ${entry.howToGetUrl}`,
+        extra: { provider: entry.provider, cli, howToGetUrl: entry.howToGetUrl },
       };
     },
   };
@@ -43,6 +85,8 @@ function createProviderTokenCheck(entry) {
 
 /**
  * GH token check + auto-remediation via `gh auth login` when it's installed.
+ * Kept from the previous version: this one IS legitimate because Karajan
+ * uses `gh` (or raw `git push`) directly when auto_pr is on.
  */
 function createGhTokenCheck() {
   return {
@@ -82,15 +126,24 @@ function createGhTokenCheck() {
 }
 
 /**
- * Build the list of token checks for the active config. Each active provider
- * gets one, plus conditional GH token when auto_pr is on.
+ * Build the list of CLI/token checks for the active config.
+ * - One CLI availability check per active provider (claude / codex / gemini / ...).
+ * - One GH token check, conditional on git.auto_pr.
+ *
+ * Function name kept as `getTokenChecks` for backward compat with
+ * preflight-checks.js, even though the bulk of the checks no longer touch
+ * tokens at all. Tracked: rename to `getProviderChecks` in a follow-up
+ * once consumers are updated.
  *
  * @param {Object} config
  * @returns {import("./types.js").Check[]}
  */
 export function getTokenChecks(config) {
   const required = getRequiredProviderEnvs(config);
-  const checks = required.map(createProviderTokenCheck);
+  const checks = required.map(createProviderCliCheck);
   checks.push(createGhTokenCheck());
   return checks;
 }
+
+// Re-export for tests that need to introspect the mapping.
+export { PROVIDER_TO_CLI, normalizeProvider };

package/src/cli.js

@@ -76,7 +76,8 @@ program
 program
   .command("run")
   .description("Run coder+sonar+reviewer loop")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file to read from a .md file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
   .option("--planner <name>")
   .option("--coder <name>")
   .option("--reviewer <name>")
@@ -138,32 +139,40 @@ program
   .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
   .action(async (task, flags) => {
     await withConfig("run", flags, async ({ config, logger }) => {
-      await runCommandHandler({ task, config, logger, flags });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await runCommandHandler({ task: resolvedTask, config, logger, flags });
     });
   });
 
 program
   .command("code")
   .description("Run only coder")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--coder <name>")
   .option("--coder-model <name>")
   .action(async (task, flags) => {
     await withConfig("code", flags, async ({ config, logger }) => {
-      await codeCommand({ task, config, logger });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await codeCommand({ task: resolvedTask, config, logger });
     });
   });
 
 program
   .command("review")
   .description("Run only reviewer")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--reviewer <name>")
   .option("--reviewer-model <name>")
   .option("--base-ref <ref>")
   .action(async (task, flags) => {
     await withConfig("review", flags, async ({ config, logger }) => {
-      await reviewCommand({ task, config, logger, baseRef: flags.baseRef });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });
     });
   });
 
@@ -248,15 +257,18 @@ const plan = program.command("plan").description("Plan management (generate, rev
 plan
   .command("generate", { isDefault: true })
   .description("Generate implementation plan with HUs")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--planner <name>")
   .option("--planner-model <name>")
   .option("--context <text>", "Additional context for the planner")
   .option("--json", "Output raw JSON plan")
   .action(async (task, flags) => {
     await withConfig("plan", flags, async ({ config, logger }) => {
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
       const { planGenerateCommand } = await import("./commands/plan.js");
-      await planGenerateCommand({ task, config, logger, json: flags.json, context: flags.context });
+      await planGenerateCommand({ task: resolvedTask, config, logger, json: flags.json, context: flags.context });
     });
   });
 
@@ -317,65 +329,83 @@ plan.command("remove-hu").description("Remove HU from plan").argument("<planId>"
 program
   .command("discover")
   .description("Analyze task for gaps, ambiguities and missing info")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
   .option("--discover <name>", "Override discover agent")
   .option("--discover-model <name>", "Override discover model")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("discover", flags, async ({ config, logger }) => {
-      await discoverCommand({ task, config, logger, mode: flags.mode, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
     });
   });
 
 program
   .command("triage")
   .description("Classify task complexity and recommend pipeline roles")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--triage <name>", "Override triage agent")
   .option("--triage-model <name>", "Override triage model")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("triage", flags, async ({ config, logger }) => {
-      await triageCommand({ task, config, logger, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
     });
   });
 
 program
   .command("researcher")
   .description("Research codebase for a task (files, patterns, constraints)")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--researcher <name>", "Override researcher agent")
   .option("--researcher-model <name>", "Override researcher model")
   .action(async (task, flags) => {
     await withConfig("researcher", flags, async ({ config, logger }) => {
-      await researcherCommand({ task, config, logger });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await researcherCommand({ task: resolvedTask, config, logger });
     });
   });
 
 program
   .command("architect")
   .description("Design solution architecture (layers, patterns, contracts)")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--architect <name>", "Override architect agent")
   .option("--architect-model <name>", "Override architect model")
   .option("--context <text>", "Additional context (e.g. researcher output)")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("architect", flags, async ({ config, logger }) => {
-      await architectCommand({ task, config, logger, context: flags.context, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
     });
   });
 
 program
   .command("audit")
   .description("Analyze codebase health (read-only)")
-  .argument("[task]")
+  .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("audit", flags, async ({ config, logger }) => {
-      await auditCommand({ task: task || "Analyze the full codebase", config, logger, dimensions: flags.dimensions, json: flags.json });
+      let resolvedTask = task;
+      if (flags.taskFile) {
+        const { readTaskFile } = await import("./utils/task-file.js");
+        resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
+      }
+      await auditCommand({ task: resolvedTask || "Analyze the full codebase", config, logger, dimensions: flags.dimensions, json: flags.json });
     });
   });
 

package/src/commands/architect.js

@@ -58,30 +58,35 @@ function formatArchitect(result) {
 }
 
 export async function architectCommand({ task, config, logger, context, json }) {
-  const architectRole = resolveRole(config, "architect");
-  await assertAgentsAvailable([architectRole.provider]);
-  logger.info(`Architect (${architectRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("architect", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const architectRole = resolveRole(config, "architect");
+    await assertAgentsAvailable([architectRole.provider]);
+    logger.info(`Architect (${architectRole.provider}) starting...`);
+    runLog.logText(`[architect] provider=${architectRole.provider}`);
 
-  const agent = createAgent(architectRole.provider, config, logger);
-  const prompt = await buildArchitectPrompt({ task, researchContext: context });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "architect" });
+    const agent = createAgent(architectRole.provider, config, logger);
+    const prompt = await buildArchitectPrompt({ task, researchContext: context });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "architect" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Architect failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Architect failed");
+    }
 
-  const parsed = parseArchitectOutput(result.output);
+    const parsed = parseArchitectOutput(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(formatArchitect(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Architect completed.");
+    if (parsed?.verdict) {
+      console.log(formatArchitect(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Architect completed.");
+    return { ok: true };
+  });
 }