karajan-code 1.28.1 → 1.29.0

package/package.json

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

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

@@ -0,0 +1,100 @@
+/**
+ * Shared runner for direct role execution (discover, triage, researcher, architect, audit).
+ * Extracts the repeated boilerplate from server-handlers.js handleXxxDirect functions.
+ */
+
+import { createStallDetector } from "../utils/stall-detector.js";
+import { resolveRole } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { createRunLog } from "../utils/run-log.js";
+import { sendTrackerLog } from "./progress.js";
+
+/**
+ * Run a role-based tool directly (not through the orchestrator pipeline).
+ *
+ * @param {object} opts
+ * @param {string} opts.roleName     - Config role key (e.g. "discover", "triage")
+ * @param {string} [opts.stage]      - Stage label for events/logs (defaults to roleName)
+ * @param {Function} opts.importRole - Async fn returning { RoleClass } (dynamic import wrapper)
+ * @param {object} opts.initContext  - Object passed to role.init()
+ * @param {object} opts.runInput     - Object passed to role.run() (onOutput is injected automatically)
+ * @param {string} [opts.logStartMsg] - Custom "[kj_xxx] started" suffix (optional)
+ * @param {object} opts.args         - Raw tool arguments (for buildConfig overrides)
+ * @param {string} [opts.commandName] - Config command name (defaults to roleName)
+ * @param {object} opts.server       - MCP server instance
+ * @param {object} opts.extra        - MCP extra context (for progress notifier)
+ * @param {Function} opts.resolveProjectDir - Async fn(server, explicitDir) => projectDir
+ * @param {Function} opts.buildConfig       - Async fn(args, commandName) => config
+ * @param {Function} opts.buildDirectEmitter - fn(server, runLog, extra) => emitter
+ */
+export async function runDirectRole({
+  roleName,
+  stage,
+  importRole,
+  initContext,
+  runInput,
+  logStartMsg,
+  args,
+  commandName,
+  server,
+  extra,
+  resolveProjectDir,
+  buildConfig,
+  buildDirectEmitter
+}) {
+  const effectiveStage = stage || roleName;
+  const effectiveCommand = commandName || roleName;
+
+  const config = await buildConfig(args, effectiveCommand);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const role = resolveRole(config, roleName);
+  await assertAgentsAvailable([role.provider]);
+
+  const projectDir = await resolveProjectDir(server, args.projectDir);
+  const runLog = createRunLog(projectDir);
+  const startMsg = logStartMsg || `[kj_${effectiveStage}] started`;
+  runLog.logText(startMsg);
+
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", {
+      type: "agent:output",
+      stage: effectiveStage,
+      message: line,
+      detail: { stream, agent: role.provider }
+    });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: effectiveStage, provider: role.provider
+  });
+
+  const { RoleClass } = await importRole();
+  const roleInstance = new RoleClass({ config, logger, emitter });
+  await roleInstance.init(initContext);
+
+  sendTrackerLog(server, effectiveStage, "running", role.provider);
+  runLog.logText(`[${effectiveStage}] agent launched, waiting for response...`);
+
+  let result;
+  try {
+    result = await roleInstance.run({ ...runInput, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(
+      `[${effectiveStage}] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`
+    );
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, effectiveStage, "failed");
+    throw new Error(result.result?.error || result.summary || `${effectiveStage} failed`);
+  }
+
+  sendTrackerLog(server, effectiveStage, "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}

package/src/mcp/server-handlers.js

@@ -9,6 +9,7 @@ import { runKjCommand } from "./run-kj.js";
 import { normalizePlanArgs } from "./tool-arg-normalizers.js";
 import { buildProgressHandler, buildProgressNotifier, buildPipelineTracker, sendTrackerLog } from "./progress.js";
 import { createStallDetector } from "../utils/stall-detector.js";
+import { runDirectRole } from "./direct-role-runner.js";
 import { runFlow, resumeFlow } from "../orchestrator.js";
 import { loadConfig, applyRunOverrides, validateConfig, resolveRole } from "../config.js";
 import { createLogger } from "../utils/logger.js";
@@ -523,28 +524,6 @@ export async function handleReviewDirect(a, server, extra) {
 }
 
 export async function handleDiscoverDirect(a, server, extra) {
-  const config = await buildConfig(a, "discover");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const discoverRole = resolveRole(config, "discover");
-  await assertAgentsAvailable([discoverRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_discover] started — mode=${a.mode || "gaps"}`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "discover", message: line, detail: { stream, agent: discoverRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "discover", provider: discoverRole.provider
-  });
-
-  const { DiscoverRole } = await import("../roles/discover-role.js");
-  const discover = new DiscoverRole({ config, logger, emitter });
-  await discover.init({ task: a.task });
-
   // Build context from pgTask if provided
   let context = a.context || null;
   if (a.pgTask && a.pgProject) {
@@ -554,205 +533,76 @@ export async function handleDiscoverDirect(a, server, extra) {
     } catch { /* PG not available — proceed without */ }
   }
 
-  sendTrackerLog(server, "discover", "running", discoverRole.provider);
-  runLog.logText(`[discover] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await discover.run({ task: a.task, mode: a.mode || "gaps", context, onOutput: stallDetector.onOutput });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[discover] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "discover", "failed");
-    throw new Error(result.result?.error || result.summary || "Discovery failed");
-  }
-
-  sendTrackerLog(server, "discover", "done");
-  return { ok: true, ...result.result, summary: result.summary };
+  return runDirectRole({
+    roleName: "discover",
+    importRole: async () => {
+      const { DiscoverRole } = await import("../roles/discover-role.js");
+      return { RoleClass: DiscoverRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, mode: a.mode || "gaps", context },
+    logStartMsg: `[kj_discover] started — mode=${a.mode || "gaps"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
+  });
 }
 
 export async function handleTriageDirect(a, server, extra) {
-  const config = await buildConfig(a, "triage");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const triageRole = resolveRole(config, "triage");
-  await assertAgentsAvailable([triageRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_triage] started`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "triage", message: line, detail: { stream, agent: triageRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "triage", provider: triageRole.provider
+  return runDirectRole({
+    roleName: "triage",
+    importRole: async () => {
+      const { TriageRole } = await import("../roles/triage-role.js");
+      return { RoleClass: TriageRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
   });
-
-  const { TriageRole } = await import("../roles/triage-role.js");
-  const triage = new TriageRole({ config, logger, emitter });
-  await triage.init({ task: a.task });
-
-  sendTrackerLog(server, "triage", "running", triageRole.provider);
-  runLog.logText(`[triage] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await triage.run({ task: a.task, onOutput: stallDetector.onOutput });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[triage] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "triage", "failed");
-    throw new Error(result.result?.error || result.summary || "Triage failed");
-  }
-
-  sendTrackerLog(server, "triage", "done");
-  return { ok: true, ...result.result, summary: result.summary };
 }
 
 export async function handleResearcherDirect(a, server, extra) {
-  const config = await buildConfig(a, "researcher");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const researcherRole = resolveRole(config, "researcher");
-  await assertAgentsAvailable([researcherRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_researcher] started`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+  return runDirectRole({
+    roleName: "researcher",
+    importRole: async () => {
+      const { ResearcherRole } = await import("../roles/researcher-role.js");
+      return { RoleClass: ResearcherRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
   });
-
-  const { ResearcherRole } = await import("../roles/researcher-role.js");
-  const researcher = new ResearcherRole({ config, logger, emitter });
-  await researcher.init({ task: a.task });
-
-  sendTrackerLog(server, "researcher", "running", researcherRole.provider);
-  runLog.logText(`[researcher] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await researcher.run({ task: a.task, onOutput: stallDetector.onOutput });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[researcher] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "researcher", "failed");
-    throw new Error(result.result?.error || result.summary || "Researcher failed");
-  }
-
-  sendTrackerLog(server, "researcher", "done");
-  return { ok: true, ...result.result, summary: result.summary };
 }
 
 export async function handleAuditDirect(a, server, extra) {
-  const config = await buildConfig(a, "audit");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const auditRole = resolveRole(config, "audit");
-  await assertAgentsAvailable([auditRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_audit] started — dimensions=${a.dimensions || "all"}`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "audit", message: line, detail: { stream, agent: auditRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "audit", provider: auditRole.provider
+  const task = a.task || "Analyze the full codebase";
+  return runDirectRole({
+    roleName: "audit",
+    importRole: async () => {
+      const { AuditRole } = await import("../roles/audit-role.js");
+      return { RoleClass: AuditRole };
+    },
+    initContext: { task },
+    runInput: { task, dimensions: a.dimensions || null },
+    logStartMsg: `[kj_audit] started — dimensions=${a.dimensions || "all"}`,
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
   });
-
-  const { AuditRole } = await import("../roles/audit-role.js");
-  const audit = new AuditRole({ config, logger, emitter });
-  await audit.init({ task: a.task || "Analyze the full codebase" });
-
-  sendTrackerLog(server, "audit", "running", auditRole.provider);
-  runLog.logText(`[audit] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await audit.run({
-      task: a.task || "Analyze the full codebase",
-      dimensions: a.dimensions || null,
-      onOutput: stallDetector.onOutput
-    });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[audit] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "audit", "failed");
-    throw new Error(result.result?.error || result.summary || "Audit failed");
-  }
-
-  sendTrackerLog(server, "audit", "done");
-  return { ok: true, ...result.result, summary: result.summary };
 }
 
 export async function handleArchitectDirect(a, server, extra) {
-  const config = await buildConfig(a, "architect");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const architectRole = resolveRole(config, "architect");
-  await assertAgentsAvailable([architectRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_architect] started`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+  return runDirectRole({
+    roleName: "architect",
+    importRole: async () => {
+      const { ArchitectRole } = await import("../roles/architect-role.js");
+      return { RoleClass: ArchitectRole };
+    },
+    initContext: { task: a.task },
+    runInput: { task: a.task, researchContext: a.context || null },
+    args: a, server, extra,
+    resolveProjectDir, buildConfig, buildDirectEmitter
   });
-
-  const { ArchitectRole } = await import("../roles/architect-role.js");
-  const architect = new ArchitectRole({ config, logger, emitter });
-  await architect.init({ task: a.task });
-
-  sendTrackerLog(server, "architect", "running", architectRole.provider);
-  runLog.logText(`[architect] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await architect.run({ task: a.task, researchContext: a.context || null, onOutput: stallDetector.onOutput });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[architect] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "architect", "failed");
-    throw new Error(result.result?.error || result.summary || "Architect failed");
-  }
-
-  sendTrackerLog(server, "architect", "done");
-  return { ok: true, ...result.result, summary: result.summary };
 }
 
 /* ── Preflight helpers ─────────────────────────────────────────────── */

package/src/orchestrator/pipeline-context.js

@@ -0,0 +1,46 @@
+/**
+ * Shared context object for pipeline execution.
+ * Replaces destructured parameter objects across orchestrator functions.
+ */
+export class PipelineContext {
+  constructor({ config, session, logger, emitter, task, flags = {} }) {
+    this.config = config;
+    this.session = session;
+    this.logger = logger;
+    this.emitter = emitter;
+    this.task = task;
+    this.flags = flags;
+
+    // Pipeline state (set during execution)
+    this.eventBase = {};
+    this.pipelineFlags = {};
+    this.trackBudget = null;
+    this.budgetTracker = null;
+    this.budgetLimit = null;
+    this.budgetSummary = null;
+    this.askQuestion = null;
+    this.reviewRules = null;
+    this.repeatDetector = null;
+    this.sonarState = { issuesInitial: null, issuesFinal: null };
+    this.stageResults = {};
+    this.gitCtx = {};
+    this.iteration = 0;
+
+    // Roles (initialized during setup)
+    this.coderRole = null;
+    this.reviewerRole = null;
+    this.refactorerRole = null;
+    this.coderRoleInstance = null;
+
+    // Planning Game context
+    this.pgTaskId = null;
+    this.pgProject = null;
+    this.pgCard = null;
+
+    // Planned task (may differ from original task after planner)
+    this.plannedTask = null;
+
+    // Timing
+    this.startedAt = null;
+  }
+}

package/src/orchestrator/pre-loop-stages.js

@@ -333,6 +333,8 @@ export async function runArchitectStage({ config, logger, emitter, eventBase, se
 
   const architectContext = architectOutput.ok ? architectOutput.result : null;
 
+  // TODO: Move ADR creation to planning-game/pipeline-adapter.js (PG coupling still here because
+  // stageResult.adrs is consumed synchronously within runArchitectStage's return value).
   // Generate ADRs from architect tradeoffs when PG is linked
   const tradeoffs = architectOutput.result?.architecture?.tradeoffs;
   if (architectOutput.ok

package/src/orchestrator.js

@@ -29,6 +29,7 @@ import { classifyIntent } from "./guards/intent-guard.js";
 import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
+import { PipelineContext } from "./orchestrator/pipeline-context.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
@@ -178,33 +179,7 @@ async function initializeSession({ task, config, flags, pgTaskId, pgProject }) {
   return createSession(sessionInit);
 }
 
-async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
-  if (!pgTaskId || !pgProject || config.planning_game?.enabled === false) {
-    return null;
-  }
-  try {
-    const { fetchCard, updateCard } = await import("./planning-game/client.js");
-    const pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
-    if (pgCard && pgCard.status !== "In Progress") {
-      await updateCard({
-        projectId: pgProject,
-        cardId: pgTaskId,
-        firebaseId: pgCard.firebaseId,
-        updates: {
-          status: "In Progress",
-          startDate: new Date().toISOString(),
-          developer: "dev_016",
-          codeveloper: config.planning_game?.codeveloper || null
-        }
-      });
-      logger.info(`Planning Game: ${pgTaskId} → In Progress`);
-    }
-    return pgCard;
-  } catch (err) {
-    logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
-    return null;
-  }
-}
+// PG card "In Progress" logic moved to src/planning-game/pipeline-adapter.js → initPgAdapter()
 
 function applyTriageOverrides(pipelineFlags, roleOverrides) {
   const keys = ["plannerEnabled", "researcherEnabled", "architectEnabled", "refactorerEnabled", "reviewerEnabled", "testerEnabled", "securityEnabled", "impeccableEnabled"];
@@ -238,57 +213,7 @@ function applyAutoSimplify({ pipelineFlags, triageLevel, config, flags, logger,
   return true;
 }
 
-async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger }) {
-  const shouldDecompose = triageResult.stageResult?.shouldDecompose
-    && triageResult.stageResult.subtasks?.length > 1
-    && pgTaskId
-    && pgProject
-    && config.planning_game?.enabled !== false
-    && askQuestion;
-
-  if (!shouldDecompose) return;
-
-  try {
-    const { buildDecompositionQuestion, createDecompositionSubtasks } = await import("./planning-game/decomposition.js");
-    const { createCard, relateCards, fetchCard } = await import("./planning-game/client.js");
-
-    const question = buildDecompositionQuestion(triageResult.stageResult.subtasks, pgTaskId);
-    const answer = await askQuestion(question);
-
-    if (answer && (answer.trim().toLowerCase() === "yes" || answer.trim().toLowerCase() === "sí" || answer.trim().toLowerCase() === "si")) {
-      const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
-      const createdSubtasks = await createDecompositionSubtasks({
-        client: { createCard, relateCards },
-        projectId: pgProject,
-        parentCardId: pgTaskId,
-        parentFirebaseId: parentCard?.firebaseId || null,
-        subtasks: triageResult.stageResult.subtasks,
-        epic: parentCard?.epic || null,
-        sprint: parentCard?.sprint || null,
-        codeveloper: config.planning_game?.codeveloper || null
-      });
-
-      stageResults.triage.pgSubtasks = createdSubtasks;
-      logger.info(`Planning Game: created ${createdSubtasks.length} subtasks from decomposition`);
-
-      emitProgress(
-        emitter,
-        makeEvent("pg:decompose", { ...eventBase, stage: "triage" }, {
-          message: `Created ${createdSubtasks.length} subtasks in Planning Game`,
-          detail: { subtasks: createdSubtasks.map((s) => ({ cardId: s.cardId, title: s.title })) }
-        })
-      );
-
-      await addCheckpoint(session, {
-        stage: "pg-decompose",
-        subtasksCreated: createdSubtasks.length,
-        cardIds: createdSubtasks.map((s) => s.cardId)
-      });
-    }
-  } catch (err) {
-    logger.warn(`Planning Game decomposition failed: ${err.message}`);
-  }
-}
+// PG decomposition logic moved to src/planning-game/pipeline-adapter.js → handlePgDecomposition()
 
 function applyFlagOverrides(pipelineFlags, flags) {
   if (flags.enablePlanner !== undefined) pipelineFlags.plannerEnabled = Boolean(flags.enablePlanner);
@@ -713,6 +638,7 @@ async function finalizeApprovedSession({ config, gitCtx, task, logger, session,
   session.budget = budgetSummary();
   await markSessionStatus(session, "approved");
 
+  const { markPgCardToValidate } = await import("./planning-game/pipeline-adapter.js");
   await markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger });
 
   const deferredIssues = session.deferred_issues || [];
@@ -728,29 +654,7 @@ async function finalizeApprovedSession({ config, gitCtx, task, logger, session,
   return { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
 }
 
-async function markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger }) {
-  if (!pgCard || !pgProject) return;
-
-  try {
-    const { updateCard } = await import("./planning-game/client.js");
-    const { buildCompletionUpdates } = await import("./planning-game/adapter.js");
-    const pgUpdates = buildCompletionUpdates({
-      approved: true,
-      commits: gitResult?.commits || [],
-      startDate: session.pg_card?.startDate || session.created_at,
-      codeveloper: config.planning_game?.codeveloper || null
-    });
-    await updateCard({
-      projectId: pgProject,
-      cardId: session.pg_task_id,
-      firebaseId: pgCard.firebaseId,
-      updates: pgUpdates
-    });
-    logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
-  } catch (err) {
-    logger.warn(`Planning Game: could not update ${session.pg_task_id} on completion: ${err.message}`);
-  }
-}
+// PG card "To Validate" logic moved to src/planning-game/pipeline-adapter.js → markPgCardToValidate()
 
 async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion }) {
   session.last_reviewer_feedback = review.blocking_issues
@@ -835,6 +739,7 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   });
   if (simplified) stageResults.triage.autoSimplified = true;
 
+  const { handlePgDecomposition } = await import("./planning-game/pipeline-adapter.js");
   await handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger });
 
   applyFlagOverrides(pipelineFlags, flags);
@@ -1097,59 +1002,61 @@ async function handleMaxIterationsReached({ session, budgetSummary, emitter, eve
 }
 
 async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
-  const coderRole = resolveRole(config, "coder");
-  const reviewerRole = resolveRole(config, "reviewer");
-  const refactorerRole = resolveRole(config, "refactorer");
-  const pipelineFlags = resolvePipelineFlags(config);
-  const repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
-  const coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent, askHost: askQuestion });
-  const startedAt = Date.now();
-  const eventBase = { sessionId: null, iteration: 0, stage: null, startedAt };
-  const { budgetTracker, budgetLimit, budgetSummary, trackBudget } = createBudgetManager({ config, emitter, eventBase });
-
-  const session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
-  eventBase.sessionId = session.id;
-
-  const pgCard = await markPgCardInProgress({ pgTaskId, pgProject, config, logger });
-  session.pg_card = pgCard || null;
+  const ctx = new PipelineContext({ config, session: null, logger, emitter, task, flags });
+  ctx.askQuestion = askQuestion;
+  ctx.pgTaskId = pgTaskId;
+  ctx.pgProject = pgProject;
+
+  ctx.coderRole = resolveRole(config, "coder");
+  ctx.reviewerRole = resolveRole(config, "reviewer");
+  ctx.refactorerRole = resolveRole(config, "refactorer");
+  ctx.pipelineFlags = resolvePipelineFlags(config);
+  ctx.repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
+  ctx.coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent, askHost: askQuestion });
+  ctx.startedAt = Date.now();
+  ctx.eventBase = { sessionId: null, iteration: 0, stage: null, startedAt: ctx.startedAt };
+  const { budgetTracker, budgetLimit, budgetSummary, trackBudget } = createBudgetManager({ config, emitter, eventBase: ctx.eventBase });
+  ctx.budgetTracker = budgetTracker;
+  ctx.budgetLimit = budgetLimit;
+  ctx.budgetSummary = budgetSummary;
+  ctx.trackBudget = trackBudget;
+
+  ctx.session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
+  ctx.eventBase.sessionId = ctx.session.id;
+
+  const { initPgAdapter } = await import("./planning-game/pipeline-adapter.js");
+  const pgAdapterResult = await initPgAdapter({ session: ctx.session, config, logger, pgTaskId, pgProject });
+  ctx.pgCard = pgAdapterResult.pgCard;
+  ctx.session.pg_card = ctx.pgCard || null;
 
   emitProgress(
     emitter,
-    makeEvent("session:start", eventBase, {
+    makeEvent("session:start", ctx.eventBase, {
       message: "Session started",
-      detail: { task, coder: coderRole.provider, reviewer: reviewerRole.provider, maxIterations: config.max_iterations }
+      detail: { task, coder: ctx.coderRole.provider, reviewer: ctx.reviewerRole.provider, maxIterations: config.max_iterations }
     })
   );
 
-  const stageResults = {};
-  const sonarState = { issuesInitial: null, issuesFinal: null };
+  ctx.stageResults = {};
+  ctx.sonarState = { issuesInitial: null, issuesFinal: null };
 
-  const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults });
-  const { plannedTask } = preLoopResult;
-  const updatedConfig = preLoopResult.updatedConfig;
+  const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session, flags, pipelineFlags: ctx.pipelineFlags, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults: ctx.stageResults });
+  ctx.plannedTask = preLoopResult.plannedTask;
+  ctx.config = preLoopResult.updatedConfig;
 
-  const gitCtx = await prepareGitAutomation({ config: updatedConfig, task, logger, session });
-  const projectDir = updatedConfig.projectDir || process.cwd();
-  const { rules: reviewRules } = await resolveReviewProfile({ mode: updatedConfig.review_mode, projectDir });
-  await coderRoleInstance.init();
+  ctx.gitCtx = await prepareGitAutomation({ config: ctx.config, task, logger, session: ctx.session });
+  const projectDir = ctx.config.projectDir || process.cwd();
+  ctx.reviewRules = (await resolveReviewProfile({ mode: ctx.config.review_mode, projectDir })).rules;
+  await ctx.coderRoleInstance.init();
 
-  return {
-    coderRole, reviewerRole, refactorerRole, pipelineFlags, repeatDetector, coderRoleInstance,
-    startedAt, eventBase, budgetTracker, budgetLimit, budgetSummary, trackBudget,
-    session, pgCard, stageResults, sonarState, plannedTask, config: updatedConfig,
-    gitCtx, reviewRules
-  };
+  return ctx;
 }
 
 async function runSingleIteration(ctx) {
-  const {
-    coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase,
-    session, plannedTask, trackBudget, i, reviewerRole, reviewRules, task, repeatDetector,
-    budgetSummary, askQuestion, sonarState, stageResults, gitCtx, pgCard, pgProject
-  } = ctx;
+  const { config, logger, emitter, eventBase, session, task, iteration: i } = ctx;
 
   const iterStart = Date.now();
-  const becariaEnabled = Boolean(config.becaria?.enabled) && gitCtx?.enabled;
+  const becariaEnabled = Boolean(config.becaria?.enabled) && ctx.gitCtx?.enabled;
   logger.setContext({ iteration: i, stage: "iteration" });
 
   emitProgress(emitter, makeEvent("iteration:start", { ...eventBase, stage: "iteration" }, {
@@ -1158,18 +1065,34 @@ async function runSingleIteration(ctx) {
   }));
   logger.info(`Iteration ${i}/${config.max_iterations}`);
 
-  const crResult = await runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i });
+  const crResult = await runCoderAndRefactorerStages({
+    coderRoleInstance: ctx.coderRoleInstance, coderRole: ctx.coderRole, refactorerRole: ctx.refactorerRole,
+    pipelineFlags: ctx.pipelineFlags, config, logger, emitter, eventBase, session,
+    plannedTask: ctx.plannedTask, trackBudget: ctx.trackBudget, i
+  });
   if (crResult.action === "return" || crResult.action === "retry") return crResult;
 
   const guardResult = await runGuardStages({ config, logger, emitter, eventBase, session, iteration: i });
   if (guardResult.action === "return") return guardResult;
 
-  const qgResult = await runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags });
+  const qgResult = await runQualityGateStages({
+    config, logger, emitter, eventBase, session, trackBudget: ctx.trackBudget, i,
+    askQuestion: ctx.askQuestion, repeatDetector: ctx.repeatDetector, budgetSummary: ctx.budgetSummary,
+    sonarState: ctx.sonarState, task, stageResults: ctx.stageResults, coderRole: ctx.coderRole,
+    pipelineFlags: ctx.pipelineFlags
+  });
   if (qgResult.action === "return" || qgResult.action === "continue") return qgResult;
 
-  await handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i });
+  await handleBecariaEarlyPrOrPush({
+    becariaEnabled, config, session, emitter, eventBase, gitCtx: ctx.gitCtx, task, logger,
+    stageResults: ctx.stageResults, i
+  });
 
-  const revResult = await runReviewerGateStage({ pipelineFlags, reviewerRole, config, logger, emitter, eventBase, session, trackBudget, i, reviewRules, task, repeatDetector, budgetSummary, askQuestion });
+  const revResult = await runReviewerGateStage({
+    pipelineFlags: ctx.pipelineFlags, reviewerRole: ctx.reviewerRole, config, logger, emitter, eventBase,
+    session, trackBudget: ctx.trackBudget, i, reviewRules: ctx.reviewRules, task,
+    repeatDetector: ctx.repeatDetector, budgetSummary: ctx.budgetSummary, askQuestion: ctx.askQuestion
+  });
   if (revResult.action === "return" || revResult.action === "retry") return revResult;
   const review = revResult.review;
 
@@ -1179,20 +1102,27 @@ async function runSingleIteration(ctx) {
   }));
   session.standby_retry_count = 0;
 
-  const solomonResult = await handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, becariaEnabled, blockingIssues: review?.blocking_issues });
+  const solomonResult = await handleSolomonCheck({
+    config, session, emitter, eventBase, logger, task, i, askQuestion: ctx.askQuestion,
+    becariaEnabled, blockingIssues: review?.blocking_issues
+  });
   if (solomonResult.action === "pause") return { action: "return", result: solomonResult.result };
 
   await handleBecariaReviewDispatch({ becariaEnabled, config, session, review, i, logger });
 
   if (review.approved) {
-    const approvedResult = await handleApprovedReview({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, pipelineFlags, askQuestion, logger, gitCtx, budgetSummary, pgCard, pgProject, review });
+    const approvedResult = await handleApprovedReview({
+      config, session, emitter, eventBase, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, i, task,
+      stageResults: ctx.stageResults, pipelineFlags: ctx.pipelineFlags, askQuestion: ctx.askQuestion, logger,
+      gitCtx: ctx.gitCtx, budgetSummary: ctx.budgetSummary, pgCard: ctx.pgCard, pgProject: ctx.pgProject, review
+    });
     if (approvedResult.action === "return" || approvedResult.action === "continue") return approvedResult;
   }
 
-  // Solomon already evaluated the rejection in runReviewerStage → handleReviewerRejection
+  // Solomon already evaluated the rejection in runReviewerStage -> handleReviewerRejection
   // Only use retry counter as fallback if Solomon is disabled
   if (!config.pipeline?.solomon?.enabled) {
-    const retryResult = await handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion });
+    const retryResult = await handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion: ctx.askQuestion });
     if (retryResult.action === "return") return retryResult;
   } else {
     // Solomon is enabled — feed back the blocking issues for the next coder iteration
@@ -1213,37 +1143,36 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   }
 
   const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
-  config = ctx.config;
 
-  const checkpointIntervalMs = (config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
+  const checkpointIntervalMs = (ctx.config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
   let lastCheckpointAt = Date.now();
   let checkpointDisabled = false;
 
   let i = 0;
-  while (i < config.max_iterations) {
+  while (i < ctx.config.max_iterations) {
     i += 1;
     const elapsedMinutes = (Date.now() - ctx.startedAt) / 60000;
 
     const cpResult = await handleCheckpoint({
       checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes,
-      i, config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary
+      i, config: ctx.config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary
     });
     if (cpResult.action === "stop") return cpResult.result;
     checkpointDisabled = cpResult.checkpointDisabled;
     lastCheckpointAt = cpResult.lastCheckpointAt;
 
-    await checkSessionTimeout({ askQuestion, elapsedMinutes, config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetSummary: ctx.budgetSummary });
-    await checkBudgetExceeded({ budgetTracker: ctx.budgetTracker, config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetLimit: ctx.budgetLimit, budgetSummary: ctx.budgetSummary });
+    await checkSessionTimeout({ askQuestion, elapsedMinutes, config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetSummary: ctx.budgetSummary });
+    await checkBudgetExceeded({ budgetTracker: ctx.budgetTracker, config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetLimit: ctx.budgetLimit, budgetSummary: ctx.budgetSummary });
 
     ctx.eventBase.iteration = i;
-    ctx.i = i;
+    ctx.iteration = i;
 
-    const iterResult = await runSingleIteration({ ...ctx, config, logger, emitter, askQuestion, task, pgProject, i });
+    const iterResult = await runSingleIteration(ctx);
     if (iterResult.action === "return") return iterResult.result;
     if (iterResult.action === "retry") { i -= 1; }
   }
 
-  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config, stageResults: ctx.stageResults, logger, askQuestion, task });
+  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task });
 }
 
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {

package/src/planning-game/pipeline-adapter.js

@@ -0,0 +1,147 @@
+/**
+ * Planning Game pipeline adapter.
+ * Subscribes to pipeline events and handles PG card lifecycle updates.
+ * Decouples PG logic from the orchestrator — works as an event-driven plugin.
+ *
+ * Handles:
+ * - Marking card as "In Progress" at session start
+ * - Decomposing tasks into subtasks after triage
+ * - Marking card as "To Validate" on approved completion
+ *
+ * If PG is disabled or no pgTaskId is present, the adapter does nothing.
+ */
+
+import { emitProgress, makeEvent } from "../utils/events.js";
+import { addCheckpoint, saveSession } from "../session-store.js";
+
+/**
+ * Attach the PG adapter to a pipeline emitter.
+ * Call this once during runFlow() initialization.
+ *
+ * @param {object} opts
+ * @param {EventEmitter} opts.emitter - Pipeline event emitter
+ * @param {object} opts.session - Session object (mutated during pipeline)
+ * @param {object} opts.config - Resolved config
+ * @param {object} opts.logger - Logger instance
+ * @param {string|null} opts.pgTaskId - Planning Game card ID (e.g. "KJC-TSK-0099")
+ * @param {string|null} opts.pgProject - Planning Game project ID
+ * @returns {{ pgCard: object|null }} The fetched PG card (or null)
+ */
+export async function initPgAdapter({ session, config, logger, pgTaskId, pgProject }) {
+  if (!pgTaskId || !pgProject || config.planning_game?.enabled === false) {
+    return { pgCard: null };
+  }
+
+  const pgCard = await markPgCardInProgress({ pgTaskId, pgProject, config, logger });
+  return { pgCard };
+}
+
+/**
+ * Handle PG task decomposition after triage.
+ * Creates subtask cards in PG when triage recommends decomposition.
+ */
+export async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger }) {
+  const shouldDecompose = triageResult.stageResult?.shouldDecompose
+    && triageResult.stageResult.subtasks?.length > 1
+    && pgTaskId
+    && pgProject
+    && config.planning_game?.enabled !== false
+    && askQuestion;
+
+  if (!shouldDecompose) return;
+
+  try {
+    const { buildDecompositionQuestion, createDecompositionSubtasks } = await import("./decomposition.js");
+    const { createCard, relateCards, fetchCard } = await import("./client.js");
+
+    const question = buildDecompositionQuestion(triageResult.stageResult.subtasks, pgTaskId);
+    const answer = await askQuestion(question);
+
+    if (answer && (answer.trim().toLowerCase() === "yes" || answer.trim().toLowerCase() === "sí" || answer.trim().toLowerCase() === "si")) {
+      const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
+      const createdSubtasks = await createDecompositionSubtasks({
+        client: { createCard, relateCards },
+        projectId: pgProject,
+        parentCardId: pgTaskId,
+        parentFirebaseId: parentCard?.firebaseId || null,
+        subtasks: triageResult.stageResult.subtasks,
+        epic: parentCard?.epic || null,
+        sprint: parentCard?.sprint || null,
+        codeveloper: config.planning_game?.codeveloper || null
+      });
+
+      stageResults.triage.pgSubtasks = createdSubtasks;
+      logger.info(`Planning Game: created ${createdSubtasks.length} subtasks from decomposition`);
+
+      emitProgress(
+        emitter,
+        makeEvent("pg:decompose", { ...eventBase, stage: "triage" }, {
+          message: `Created ${createdSubtasks.length} subtasks in Planning Game`,
+          detail: { subtasks: createdSubtasks.map((s) => ({ cardId: s.cardId, title: s.title })) }
+        })
+      );
+
+      await addCheckpoint(session, {
+        stage: "pg-decompose",
+        subtasksCreated: createdSubtasks.length,
+        cardIds: createdSubtasks.map((s) => s.cardId)
+      });
+    }
+  } catch (err) {
+    logger.warn(`Planning Game decomposition failed: ${err.message}`);
+  }
+}
+
+/**
+ * Mark PG card as "To Validate" on approved session completion.
+ */
+export async function markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger }) {
+  if (!pgCard || !pgProject) return;
+
+  try {
+    const { updateCard } = await import("./client.js");
+    const { buildCompletionUpdates } = await import("./adapter.js");
+    const pgUpdates = buildCompletionUpdates({
+      approved: true,
+      commits: gitResult?.commits || [],
+      startDate: session.pg_card?.startDate || session.created_at,
+      codeveloper: config.planning_game?.codeveloper || null
+    });
+    await updateCard({
+      projectId: pgProject,
+      cardId: session.pg_task_id,
+      firebaseId: pgCard.firebaseId,
+      updates: pgUpdates
+    });
+    logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
+  } catch (err) {
+    logger.warn(`Planning Game: could not update ${session.pg_task_id} on completion: ${err.message}`);
+  }
+}
+
+// --- Internal helpers ---
+
+async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
+  try {
+    const { fetchCard, updateCard } = await import("./client.js");
+    const pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+    if (pgCard && pgCard.status !== "In Progress") {
+      await updateCard({
+        projectId: pgProject,
+        cardId: pgTaskId,
+        firebaseId: pgCard.firebaseId,
+        updates: {
+          status: "In Progress",
+          startDate: new Date().toISOString(),
+          developer: "dev_016",
+          codeveloper: config.planning_game?.codeveloper || null
+        }
+      });
+      logger.info(`Planning Game: ${pgTaskId} → In Progress`);
+    }
+    return pgCard;
+  } catch (err) {
+    logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
+    return null;
+  }
+}