karajan-code 1.52.0 → 1.53.0

package/package.json

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

package/src/cli.js

@@ -86,6 +86,7 @@ program
   .option("--enable-triage")
   .option("--enable-discover")
   .option("--enable-architect")
+  .option("--plan <planId>", "Plan ID from kj plan. Loads persisted plan context and skips researcher/architect/planner.")
   .option("--enable-hu-reviewer")
   .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
   .option("--enable-serena")

package/src/commands/plan.js

@@ -60,8 +60,26 @@ export async function planCommand({ task, config, logger, json, context }) {
 
   const parsed = parseMaybeJsonString(result.output);
 
+  // Persist plan
+  let planId = null;
+  try {
+    const { savePlan } = await import("../plan/plan-store.js");
+    const projectDir = config.projectDir || process.cwd();
+    planId = await savePlan(projectDir, {
+      task,
+      researchContext: null,
+      architectContext: null,
+      plan: parsed || result.output,
+      raw: result.output
+    });
+  } catch (err) {
+    logger.warn(`Plan persistence failed: ${err.message}`);
+  }
+
   if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
+    const jsonOutput = parsed || result.output;
+    const outputObj = typeof jsonOutput === "object" ? { ...jsonOutput, planId } : { plan: jsonOutput, planId };
+    console.log(JSON.stringify(outputObj, null, 2));
     return;
   }
 
@@ -70,4 +88,9 @@ export async function planCommand({ task, config, logger, json, context }) {
   } else {
     console.log(result.output);
   }
+
+  if (planId) {
+    console.log(`\nPlan saved: ${planId}`);
+    console.log(`Use it with: kj run --plan ${planId} "<task>"`);
+  }
 }

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

@@ -70,6 +70,76 @@ export async function handlePlanDirect(a, server, extra) {
   );
   const emitter = buildDirectEmitter(server, runLog, extra);
   const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+
+  // --- Phase 1: Researcher (codebase context) ---
+  let researchContext = null;
+  try {
+    const { ResearcherRole } = await import("../../roles/researcher-role.js");
+    const researcherRole = resolveRole(config, "researcher");
+    const researcherOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
+    };
+    const researcherStall = createStallDetector({
+      onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+    });
+
+    sendTrackerLog(server, "researcher", "running", researcherRole.provider);
+    runLog.logText(`[researcher] agent launched for plan context...`);
+    const researcher = new ResearcherRole({ config, logger, emitter });
+    await researcher.init({ task: a.task });
+    let researchOutput;
+    try {
+      researchOutput = await researcher.run({ task: a.task, onOutput: researcherStall.onOutput });
+    } finally {
+      researcherStall.stop();
+    }
+    if (researchOutput.ok) {
+      researchContext = researchOutput.result;
+      sendTrackerLog(server, "researcher", "done");
+      runLog.logText(`[researcher] completed — context available`);
+    } else {
+      sendTrackerLog(server, "researcher", "failed");
+      runLog.logText(`[researcher] failed: ${researchOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Researcher phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 2: Architect (solution design) ---
+  let architectContext = null;
+  try {
+    const { ArchitectRole } = await import("../../roles/architect-role.js");
+    const architectRole = resolveRole(config, "architect");
+    const architectOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
+    };
+    const architectStall = createStallDetector({
+      onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+    });
+
+    sendTrackerLog(server, "architect", "running", architectRole.provider);
+    runLog.logText(`[architect] agent launched for plan context...`);
+    const architect = new ArchitectRole({ config, logger, emitter });
+    await architect.init({ task: a.task });
+    let architectOutput;
+    try {
+      architectOutput = await architect.run({ task: a.task, researchContext, onOutput: architectStall.onOutput });
+    } finally {
+      architectStall.stop();
+    }
+    if (architectOutput.ok) {
+      architectContext = architectOutput.result;
+      sendTrackerLog(server, "architect", "done");
+      runLog.logText(`[architect] completed — context available`);
+    } else {
+      sendTrackerLog(server, "architect", "failed");
+      runLog.logText(`[architect] failed: ${architectOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Architect phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 3: Planner (with research + architecture context) ---
   const onOutput = ({ stream, line }) => {
     emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
   };
@@ -78,7 +148,7 @@ export async function handlePlanDirect(a, server, extra) {
   });
 
   const planner = createAgent(plannerRole.provider, config, logger);
-  const prompt = buildPlannerPrompt({ task: a.task, context: a.context });
+  const prompt = buildPlannerPrompt({ task: a.task, context: a.context, architectContext });
   sendTrackerLog(server, "planner", "running", plannerRole.provider);
   runLog.logText(`[planner] agent launched, waiting for response...`);
   let result;
@@ -111,7 +181,24 @@ export async function handlePlanDirect(a, server, extra) {
 
   sendTrackerLog(server, "planner", "done");
   const parsed = parseMaybeJsonString(result.output);
-  return { ok: true, plan: parsed || result.output, raw: result.output };
+
+  // --- Persist plan ---
+  let planId = null;
+  try {
+    const { savePlan } = await import("../../plan/plan-store.js");
+    planId = await savePlan(projectDir, {
+      task: a.task,
+      researchContext,
+      architectContext,
+      plan: parsed || result.output,
+      raw: result.output
+    });
+    runLog.logText(`[kj_plan] plan persisted — planId=${planId}`);
+  } catch (err) {
+    logger.warn(`Plan persistence failed (non-blocking): ${err.message}`);
+  }
+
+  return { ok: true, plan: parsed || result.output, raw: result.output, planId, researchContext, architectContext };
 }
 
 export async function handleCodeDirect(a, server, extra) {

package/src/mcp/tools.js

@@ -53,6 +53,7 @@ export const tools = [
       required: ["task"],
       properties: {
         task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        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." },
         pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },

package/src/orchestrator.js

@@ -984,6 +984,44 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
     pipelineFlags.securityEnabled = false;
   }
 
+  // --- Plan injection: skip researcher/architect/planner if a persisted plan is loaded ---
+  if (flags.plan) {
+    try {
+      const { loadPlan } = await import("./plan/plan-store.js");
+      const projectDir = updatedConfig.projectDir || process.cwd();
+      const loadedPlan = await loadPlan(projectDir, flags.plan);
+      if (loadedPlan) {
+        logger.info(`Loaded persisted plan: ${flags.plan}`);
+        emitProgress(emitter, makeEvent("plan:loaded", { ...eventBase, stage: "plan" }, {
+          message: `Plan loaded from kj_plan: ${flags.plan}`,
+          detail: { planId: flags.plan, task: loadedPlan.task, createdAt: loadedPlan.createdAt }
+        }));
+        stageResults.researcher = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        stageResults.architect = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        stageResults.planner = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        // Inject contexts into session for downstream stages
+        session.research_context = loadedPlan.researchContext || null;
+        session.architect_context = loadedPlan.architectContext || null;
+        session.loaded_plan = loadedPlan.plan || null;
+        await saveSession(session);
+
+        // Build the planned task from the plan steps
+        const plan = loadedPlan.plan;
+        let plannedTask = task;
+        if (plan && typeof plan === "object" && plan.steps) {
+          const stepList = plan.steps.map((s, idx) => `${idx + 1}. ${s.description || s}`).join("\n");
+          plannedTask = `${task}\n\n## Implementation Plan\n${plan.approach || ""}\n\n## Steps\n${stepList}`;
+        } else if (typeof plan === "string") {
+          plannedTask = `${task}\n\n## Implementation Plan\n${plan}`;
+        }
+        return { plannedTask, updatedConfig };
+      }
+      logger.warn(`Plan ${flags.plan} not found — falling back to normal pipeline`);
+    } catch (err) {
+      logger.warn(`Plan loading failed: ${err.message} — falling back to normal pipeline`);
+    }
+  }
+
   // --- Researcher → Planner ---
   const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion });
 

package/src/plan/plan-store.js

@@ -0,0 +1,116 @@
+/**
+ * Plan persistence — save, load, list plans generated by kj_plan.
+ * Plans are stored at ~/.kj/plans/<projectSlug>/<planId>.json
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+function getKjHome() {
+  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+}
+
+function projectSlug(projectDir) {
+  return projectDir
+    .replace(/^\//, "")
+    .replace(/[/\\]/g, "_")
+    .replace(/[^a-zA-Z0-9_.-]/g, "")
+    .slice(0, 120);
+}
+
+function plansDir(projectDir) {
+  return path.join(getKjHome(), "plans", projectSlug(projectDir));
+}
+
+function generatePlanId() {
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `plan-${ts}-${rand}`;
+}
+
+/**
+ * Save a plan result to disk.
+ * @param {string} projectDir - Absolute path to the project
+ * @param {object} planResult - { task, researchContext, architectContext, plan, raw }
+ * @returns {Promise<string>} planId
+ */
+export async function savePlan(projectDir, planResult) {
+  const dir = plansDir(projectDir);
+  await fs.mkdir(dir, { recursive: true });
+
+  const planId = generatePlanId();
+  const record = {
+    planId,
+    task: planResult.task || null,
+    researchContext: planResult.researchContext || null,
+    architectContext: planResult.architectContext || null,
+    plan: planResult.plan || null,
+    raw: planResult.raw || null,
+    createdAt: new Date().toISOString()
+  };
+
+  const filePath = path.join(dir, `${planId}.json`);
+  await fs.writeFile(filePath, JSON.stringify(record, null, 2), "utf8");
+  return planId;
+}
+
+/**
+ * Load a saved plan by ID.
+ * @param {string} projectDir
+ * @param {string} planId
+ * @returns {Promise<object|null>} { planId, task, researchContext, architectContext, plan, createdAt } or null
+ */
+export async function loadPlan(projectDir, planId) {
+  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+  try {
+    const data = await fs.readFile(filePath, "utf8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all plans for a project, sorted by creation time (newest first).
+ * @param {string} projectDir
+ * @returns {Promise<Array<{planId: string, task: string, createdAt: string}>>}
+ */
+export async function listPlans(projectDir) {
+  const dir = plansDir(projectDir);
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const plans = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const data = await fs.readFile(path.join(dir, file), "utf8");
+      const record = JSON.parse(data);
+      plans.push({
+        planId: record.planId,
+        task: record.task,
+        createdAt: record.createdAt
+      });
+    } catch { /* skip corrupt files */ }
+  }
+
+  plans.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+  return plans;
+}
+
+/**
+ * Get the most recent plan for a project.
+ * @param {string} projectDir
+ * @returns {Promise<object|null>}
+ */
+export async function getLatestPlan(projectDir) {
+  const all = await listPlans(projectDir);
+  if (all.length === 0) return null;
+  return loadPlan(projectDir, all[0].planId);
+}