@karajan-family/code 4.21.0

package/src/orchestrator/integrations.js

@@ -0,0 +1,81 @@
+/**
+ * Integrations registry — single site the orchestrator consults to talk to
+ * external task trackers (Planning Game, future: GitHub Projects, Jira, …).
+ *
+ * TSK-0339 (KJC-PCS-0040) removes the direct coupling between
+ * `src/orchestrator/` and `src/planning-game/`: pre-v2.7.5 there were 8
+ * dynamic `await import("../../planning-game/…")` callsites scattered
+ * across flow-runner, ci-integration, drivers, and architect-stage. Now
+ * the orchestrator calls the registry instead of importing trackers:
+ *
+ *   const tracker = getIntegration("tracker");
+ *   await tracker?.onCommit?.(session, commit);
+ *
+ * `src/planning-game/pipeline-adapter.js` registers itself once at
+ * bootstrap (gated by `config.planning_game.enabled`). Adding a new
+ * tracker means writing a single file under `src/adapters/…` with the
+ * same hook surface; zero orchestrator edits.
+ */
+
+/**
+ * Hook contract (all optional — callers use `adapter?.hook?.(args)`):
+ *
+ *   onSessionStart({ session, config, logger, pgTaskId, pgProject })
+ *     → { pgCard } | void
+ *   onCommit(session, commit)                              — fire-and-forget
+ *   onSessionApproved({ session, config, gitResult, logger, pgCard, pgProject })
+ *     → void
+ *   buildHuStoriesFromCard(card)                           → HuStory[] | null
+ *   handleDecomposition({ triageResult, ... })             → void
+ *   createAdr({ title, context, decision, consequences })  → string | null
+ *
+ * No adapter is required to implement every hook — orchestrator callsites
+ * use optional chaining so missing hooks are a silent skip.
+ *
+ * The registry itself is process-scoped (one map, mutated at bootstrap).
+ * That's fine: adapter identity doesn't vary per-run — the same PG/Jira
+ * backend serves every run in the process. Per-run tracker CONFIG (e.g.
+ * different PG projects) is passed through the hook call, not by
+ * swapping adapters.
+ */
+
+/** @type {Map<string, object>} */
+const registry = new Map();
+
+/**
+ * Register an adapter under `name`. Idempotent: re-registering overwrites
+ * the previous entry (tests use this to swap in fakes).
+ *
+ * @param {string} name
+ * @param {object} adapter
+ */
+export function registerIntegration(name, adapter) {
+  if (!name || typeof name !== "string") {
+    throw new Error("registerIntegration: name must be a non-empty string");
+  }
+  registry.set(name, adapter);
+}
+
+/**
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function getIntegration(name) {
+  return registry.get(name);
+}
+
+/**
+ * Remove an adapter. Tests use this to clear state between cases.
+ * @param {string} name
+ */
+export function unregisterIntegration(name) {
+  registry.delete(name);
+}
+
+/**
+ * List registered integration names. Useful for bootstrap logging.
+ * @returns {string[]}
+ */
+export function listIntegrations() {
+  return [...registry.keys()];
+}

package/src/orchestrator/iteration-gate.js

@@ -0,0 +1,73 @@
+/**
+ * iteration-gate — opt-in per-iteration supervision (KJC-TSK-0628, épica
+ * KJC-PCS-0062). With `--step` (or session.iteration_gate in config) the
+ * pipeline pauses after EVERY iteration with a compact report — what
+ * happened, what the next iteration will do, spend vs cap — and asks the
+ * user: continue, stop, or continue WITH instructions. Free-text answers
+ * are appended to the reviewer feedback the coder reads next iteration
+ * (same channel Solomon's human guidance uses), never overwriting the
+ * reviewer's own must-fix list.
+ */
+
+import { markSessionStatus } from "../session/store.js";
+import { setReviewerFeedback } from "../session/mutators.js";
+
+const STOP_ANSWERS = new Set(["stop", "parar", "para", "no", "n", "4"]);
+const CONTINUE_ANSWERS = new Set(["", "s", "si", "sí", "y", "yes", "1", "continue", "continuar"]);
+
+/** Compact human report of the iteration that just finished. */
+export function buildIterationReport({ i, maxIterations, stageResults = {}, budgetTracker, maxBudgetUsd, reviewVerdict }) {
+  const lines = [`Iteration ${i}/${maxIterations} finished.`];
+  const stages = Object.keys(stageResults);
+  if (stages.length > 0) lines.push(`Stages so far: ${stages.join(", ")}`);
+
+  const review = reviewVerdict ?? stageResults.reviewer ?? null;
+  const mustFix = review?.must_fix ?? review?.issues ?? [];
+  if (review?.approved === true) {
+    lines.push("Reviewer: APPROVED");
+  } else if (mustFix.length > 0) {
+    const shown = mustFix.slice(0, 3).map((f) => `  • ${typeof f === "string" ? f : f.title || f.description || JSON.stringify(f)}`);
+    lines.push(`Reviewer: rejected with ${mustFix.length} must-fix:`, ...shown);
+    if (mustFix.length > 3) lines.push(`  … and ${mustFix.length - 3} more`);
+    lines.push(`Next iteration: the coder tackles those ${mustFix.length} must-fix.`);
+  } else {
+    lines.push("Next iteration: the coder retries against the pending feedback.");
+  }
+
+  const spent = budgetTracker?.total?.().cost_usd ?? 0;
+  const cap = maxBudgetUsd != null ? ` / cap $${Number(maxBudgetUsd).toFixed(2)}` : "";
+  lines.push(`Spend: $${spent.toFixed(2)}${cap}`);
+  return lines.join("\n");
+}
+
+/** Append a user directive without clobbering the reviewer's feedback. */
+export function appendUserDirective(session, text) {
+  const existing = session.last_reviewer_feedback || "";
+  const block = `## User directive (iteration gate)\n${text}`;
+  setReviewerFeedback(session, existing ? `${existing}\n\n${block}` : block);
+}
+
+/**
+ * Ask the user at the gate. Returns { action: "continue" | "stop",
+ * injected?: string }. Disabled gate, missing askQuestion (nobody to ask)
+ * or unattended autonomous runs pass straight through.
+ */
+export async function handleIterationGate({ enabled, askQuestion, session, logger, report }) {
+  if (!enabled || !askQuestion || askQuestion.unattended === true) return { action: "continue" };
+
+  const answer = await askQuestion(
+    `${report}\n\nContinue? [Enter = yes | "stop" = stop | anything else = instructions for the next iteration]`,
+  );
+  const trimmed = (answer || "").trim();
+  const lower = trimmed.toLowerCase();
+
+  if (STOP_ANSWERS.has(lower)) {
+    await markSessionStatus(session, "stopped");
+    return { action: "stop" };
+  }
+  if (CONTINUE_ANSWERS.has(lower)) return { action: "continue" };
+
+  appendUserDirective(session, trimmed);
+  logger?.info?.("Iteration gate: user directive injected for the next iteration.");
+  return { action: "continue", injected: trimmed };
+}

package/src/orchestrator/iteration-stages.js

@@ -0,0 +1,9 @@
+/**
+ * Iteration stage functions.
+ * Implementations have been extracted into ./stages/ sub-modules.
+ * This file re-exports everything for backward compatibility.
+ */
+
+export { runCoderStage, runRefactorerStage, runTddCheckStage } from "./stages/coder-stage.js";
+export { runSonarStage, runSonarCloudStage } from "./stages/sonar-stage.js";
+export { runReviewerStage, fetchReviewDiff } from "./stages/reviewer-stage.js";

package/src/orchestrator/parallel-limiter.js

@@ -0,0 +1,74 @@
+/**
+ * parallel-limiter — shared concurrency coordinator for parallel HU
+ * execution (KJC-TSK-0624, épica KJC-PCS-0065). One instance per plan run,
+ * shared by every HU lane:
+ *
+ *   - Semaphore: at most maxParallel HUs hold a slot (acquire/release).
+ *   - Plan budget: the whole run shares ONE BudgetTracker; the launch gate
+ *     refuses new lanes once aggregated spend reaches the plan ceiling
+ *     (maxParallel × max_budget_usd — parallelism scales the cap, it never
+ *     multiplies it silently).
+ *   - Cooldown: when any lane hits a provider rate limit it calls
+ *     notifyCooldown(ms); NEW launches pause until it expires while lanes
+ *     already flying finish their work — parallel retry stampedes are the
+ *     fastest way to burn a quota.
+ */
+
+export function createParallelLimiter({ maxParallel = 1, budgetTracker = null, planBudgetUsd = null, now = Date.now } = {}) {
+  let inUse = 0;
+  let cooldownUntil = 0;
+  const waiters = [];
+
+  const overPlanBudget = () => {
+    if (planBudgetUsd == null || !budgetTracker) return false;
+    return (budgetTracker.total?.().cost_usd ?? 0) >= Number(planBudgetUsd);
+  };
+
+  const grantNext = () => {
+    while (waiters.length > 0 && inUse < maxParallel) {
+      inUse += 1;
+      waiters.shift()();
+    }
+  };
+
+  return {
+    /** Why a new lane may not launch right now; null = clear to go. */
+    launchBlockReason() {
+      if (overPlanBudget()) {
+        return `plan budget exhausted ($${(budgetTracker.total().cost_usd).toFixed(2)} ≥ $${Number(planBudgetUsd).toFixed(2)})`;
+      }
+      const waitMs = cooldownUntil - now();
+      if (waitMs > 0) return `provider cooldown for ${Math.ceil(waitMs / 1000)}s`;
+      return null;
+    },
+
+    /** Wait for a free slot. Resolves when this lane may run. */
+    acquire() {
+      if (inUse < maxParallel) {
+        inUse += 1;
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+
+    release() {
+      inUse = Math.max(0, inUse - 1);
+      grantNext();
+    },
+
+    /** A lane hit a rate limit: pause NEW launches until it expires. */
+    notifyCooldown(ms) {
+      cooldownUntil = Math.max(cooldownUntil, now() + Math.max(0, ms));
+    },
+
+    stats() {
+      return { inUse, waiting: waiters.length, maxParallel, cooldownUntil };
+    },
+  };
+}
+
+/** Plan-level ceiling: parallelism scales the per-run cap, explicitly. */
+export function planBudgetUsd({ maxBudgetUsd, maxParallel = 1 }) {
+  if (maxBudgetUsd == null) return null;
+  return Number(maxBudgetUsd) * Math.max(1, maxParallel);
+}

package/src/orchestrator/pipeline-context.js

@@ -0,0 +1,72 @@
+/**
+ * Shared context object for pipeline execution.
+ * Replaces destructured parameter objects across orchestrator functions.
+ *
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("../types/session.js").Session} Session
+ * @typedef {import("../types/stage.js").Logger} Logger
+ * @typedef {import("../types/stage.js").Emitter} Emitter
+ * @typedef {import("../types/stage.js").EventBase} EventBase
+ * @typedef {import("../types/config.js").PipelineFlags} PipelineFlags
+ * @typedef {import("../types/stage.js").StageContext} StageContext
+ */
+export class PipelineContext {
+  /**
+   * @param {Object} args
+   * @param {KarajanConfig} args.config
+   * @param {Session} args.session
+   * @param {Logger} args.logger
+   * @param {Emitter|null} args.emitter
+   * @param {string} args.task
+   * @param {Object} [args.flags]
+   */
+  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;
+
+    // Product context (loaded from .karajan/context.md or product-vision.md)
+    this.productContext = null;
+
+    // Domain context (synthesized by Domain Curator from ~/.karajan/domains/ and .karajan/domains/)
+    this.domainContext = null;
+
+    // Planned task (may differ from original task after planner)
+    this.plannedTask = null;
+
+    // Karajan Brain runtime context (feedback queue, verification tracker, compression stats)
+    this.brainCtx = null;
+
+    // Timing
+    this.startedAt = null;
+  }
+}