@karajan-family/code 4.21.0

package/src/orchestrator/stages/tdd-discipline-stage.js

@@ -0,0 +1,56 @@
+// TDD discipline stage (KJC-TSK-0398 PR3).
+// Runs the red-then-green check when `development.require_red_then_green`
+// is true. Wraps `verifyTddDiscipline` with the surgical stash helper and
+// the project's detected test framework. Gate is opt-in; an unsupported
+// framework reports a warning and does not block the iteration.
+
+import { detectTestFramework } from "../../utils/project-detect.js";
+import { verifyTddDiscipline } from "../../review/tdd-discipline.js";
+import { stashFilesAside, restoreFiles } from "../../review/git-stash-helper.js";
+import { runCommand } from "../../utils/process.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+const TDD_DISCIPLINE_COMMANDS = {
+  vitest: ["npx", ["vitest", "run", "--reporter=verbose"]],
+  jest: ["npx", ["jest", "--verbose"]],
+  pytest: ["pytest", ["--tb=short"]],
+};
+
+export async function runTddDisciplineStage({
+  config, logger, emitter, eventBase, sourceFiles = [], testFiles = [],
+  detectFramework = detectTestFramework,
+  runTestsImpl,
+  stashImpl = stashFilesAside,
+  restoreImpl = restoreFiles,
+} = {}) {
+  const projectDir = config?.projectDir || process.cwd();
+  const detection = await detectFramework(projectDir);
+  const framework = detection?.framework || null;
+
+  const runTests = runTestsImpl || (async () => {
+    const cmd = TDD_DISCIPLINE_COMMANDS[framework];
+    if (!cmd) return { exitCode: 0, output: "" };
+    const res = await runCommand(cmd[0], cmd[1], { cwd: projectDir, reject: false });
+    return { exitCode: res.exitCode ?? 0, output: `${res.stdout || ""}\n${res.stderr || ""}` };
+  });
+
+  const result = await verifyTddDiscipline({
+    projectDir, sourceFiles, testFiles, framework,
+    runTests,
+    stashFiles: (files) => stashImpl(files, { projectDir }),
+    restoreFiles: (token) => restoreImpl(token, { projectDir }),
+  });
+
+  emitProgress(emitter, makeEvent("tdd:discipline", { ...eventBase, stage: "tdd" }, {
+    status: result.ok ? "ok" : "fail",
+    message: result.message || `TDD discipline: ${result.reason}`,
+    detail: { reason: result.reason, framework },
+  }));
+
+  if (result.warning) logger?.warn?.(result.warning);
+  if (!result.ok) {
+    logger?.warn?.(`TDD discipline violation: ${result.reason}`);
+    return { action: "continue", result };
+  }
+  return { action: "ok", result };
+}

package/src/orchestrator/stages/tool-judge-stage.js

@@ -0,0 +1,53 @@
+// KJC-TSK-0375 PR3 — ToolJudgeStage.
+// Opt-in (`pipeline.tool_judge.enabled`). Scores the coder's tool calls
+// extracted from `session.last_coder_transcript`. Non-blocking: a low
+// score emits a warn event and surfaces in summary but never gates the
+// iteration loop. Wiring lives in `quality-gates.js`.
+
+import { ToolCorrectnessJudgeRole } from "../../roles/tool-correctness-judge-role.js";
+import { extractToolCalls } from "../../utils/tool-call-extractor.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+export async function runToolJudgeStage({
+  config, logger, emitter, eventBase, session, coderRole, trackBudget,
+  iteration, task,
+  extractFn = extractToolCalls,
+  RoleClass = ToolCorrectnessJudgeRole,
+} = {}) {
+  logger?.setContext?.({ iteration, stage: "tool-judge" });
+  emitProgress(emitter, makeEvent("toolJudge:start", { ...eventBase, stage: "tool-judge" }, {
+    message: "Tool-judge scoring coder tool calls",
+  }));
+
+  const transcript = session?.last_coder_transcript || "";
+  const provider = coderRole?.provider || "claude";
+  const toolCalls = extractFn({ transcript, provider });
+
+  const role = new RoleClass({ config, logger, emitter });
+  const roleResult = await role.execute({ task, toolCalls });
+
+  try { trackBudget?.("tool-judge", roleResult.usage || { tokens_in: 0, tokens_out: 0, cost_usd: 0 }); } catch { /* best-effort */ }
+
+  const r = roleResult.result;
+  const status = r?.skipped ? "skip" : r?.lowQuality ? "warn" : roleResult.ok ? "ok" : "fail";
+
+  emitProgress(emitter, makeEvent("toolJudge:end", { ...eventBase, stage: "tool-judge" }, {
+    status,
+    message: roleResult.summary || "tool-judge done",
+    detail: { score: r?.score ?? null, threshold: r?.threshold ?? null, skipped: Boolean(r?.skipped), callCount: toolCalls.length },
+  }));
+
+  return {
+    action: "ok",
+    stageResult: {
+      ok: roleResult.ok !== false,
+      score: r?.score ?? null,
+      lowQuality: Boolean(r?.lowQuality),
+      skipped: Boolean(r?.skipped),
+      threshold: r?.threshold ?? null,
+      summary: roleResult.summary || "",
+      breakdown: r?.breakdown || [],
+      callCount: toolCalls.length,
+    },
+  };
+}

package/src/orchestrator/stages/triage-stage.js

@@ -0,0 +1,172 @@
+/**
+ * Triage stage logic.
+ * Extracted from pre-loop-stages.js for maintainability.
+ */
+
+import { TriageRole } from "../../roles/triage-role.js";
+import { addCheckpoint } from "../../session/store.js";
+import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
+import { selectModelsForRoles } from "../../utils/model-selector.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+
+const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security", "impeccable"];
+
+// What each role is for. Used to explain — deterministically — why triage would
+// or would not turn a role on. These describe the role's trigger, never a claim
+// about the current task, so the rationale is never invented per run.
+const ROLE_PURPOSE = {
+  planner: "planificación multi-fichero",
+  researcher: "investigación de contexto externo",
+  architect: "decisiones de arquitectura",
+  refactorer: "refactor de código existente",
+  reviewer: "revisión de cambios",
+  tester: "cobertura de tests dedicada",
+  security: "auditoría de seguridad",
+  impeccable: "auditoría de diseño"
+};
+
+function buildRoleOverrides(recommendedRoles, pipelineConfig) {
+  const overrides = {};
+  for (const role of ROLE_NAMES) {
+    overrides[`${role}Enabled`] = recommendedRoles.has(role) || Boolean(pipelineConfig[role]?.enabled);
+  }
+  return overrides;
+}
+
+// Per-role explanation of the activate/skip decision, mirroring buildRoleOverrides.
+// When triage failed, recommendations are unavailable: roles resolve from config
+// alone and skipped ones get a neutral "sin datos de triage" reason.
+function buildRoleRationale(recommendedRoles, pipelineConfig, triageOk) {
+  return ROLE_NAMES.map((role) => {
+    const forced = Boolean(pipelineConfig[role]?.enabled);
+    const recommended = triageOk && recommendedRoles.has(role);
+    const purpose = ROLE_PURPOSE[role];
+
+    if (recommended) {
+      return { role, enabled: true, source: "triage", reason: `recomendado por triage — ${purpose}` };
+    }
+    if (forced) {
+      return { role, enabled: true, source: "config", reason: `forzado por configuración — ${purpose}` };
+    }
+    const reason = triageOk
+      ? `no recomendado — ${purpose} sin aplicar`
+      : `sin datos de triage — ${purpose} sin evaluar`;
+    return { role, enabled: false, source: "none", reason };
+  });
+}
+
+function applyModelSelection(triageOutput, config, emitter, eventBase) {
+  if (!triageOutput.ok || !config?.model_selection?.enabled) return null;
+  const level = triageOutput.result?.level;
+  if (!level) return null;
+
+  const { modelOverrides, reasoning } = selectModelsForRoles({ level, config });
+  for (const [role, model] of Object.entries(modelOverrides)) {
+    if (config.roles?.[role] && !config.roles[role].model) {
+      config.roles[role].model = model;
+    }
+  }
+  const modelSelection = { modelOverrides, reasoning };
+  emitProgress(
+    emitter,
+    makeEvent("model-selection:applied", { ...eventBase, stage: "triage" }, {
+      message: "Smart model selection applied",
+      detail: modelSelection
+    })
+  );
+  return modelSelection;
+}
+
+export async function runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
+  logger.setContext({ iteration: 0, stage: "triage" });
+
+  const triageProvider = config?.roles?.triage?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("triage:start", { ...eventBase, stage: "triage" }, {
+      message: "Triage classifying task complexity",
+      detail: { provider: triageProvider, executorType: "agent" }
+    })
+  );
+
+  const triageOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "triage", triageProvider, payload);
+  const triageStall = createStallDetector({
+    onOutput: triageOnOutput, emitter, eventBase, stage: "triage", provider: triageProvider
+  });
+
+  const triage = new TriageRole({ config, logger, emitter });
+  await triage.init({ task: session.task, sessionId: session.id, iteration: 0 });
+  const triageStart = Date.now();
+  let triageOutput;
+  try {
+    triageOutput = await triage.run({ task: session.task, onOutput: triageStall.onOutput });
+  } catch (err) {
+    logger.warn(`Triage threw: ${err.message}`);
+    triageOutput = { ok: false, summary: `Triage error: ${err.message}`, result: { error: err.message } };
+  } finally {
+    triageStall.stop();
+  }
+  trackBudget({
+    role: "triage",
+    provider: config?.roles?.triage?.provider || coderRole.provider,
+    model: config?.roles?.triage?.model || coderRole.model,
+    result: triageOutput,
+    duration_ms: Date.now() - triageStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "triage",
+    iteration: 0,
+    ok: triageOutput.ok,
+    provider: config?.roles?.triage?.provider || coderRole.provider,
+    model: config?.roles?.triage?.model || coderRole.model || null
+  });
+
+  const recommendedRoles = new Set(triageOutput.result?.roles || []);
+  const roleOverrides = triageOutput.ok
+    ? buildRoleOverrides(recommendedRoles, config.pipeline || {})
+    : {};
+
+  const shouldDecompose = triageOutput.result?.shouldDecompose || false;
+  const subtasks = triageOutput.result?.subtasks || [];
+
+  const domainHints = triageOutput.result?.domainHints || [];
+
+  const stageResult = {
+    ok: triageOutput.ok,
+    level: triageOutput.result?.level || null,
+    roles: Array.from(recommendedRoles),
+    reasoning: triageOutput.result?.reasoning || null,
+    taskType: triageOutput.result?.taskType || "sw",
+    shouldDecompose,
+    subtasks,
+    domainHints,
+    roleRationale: buildRoleRationale(recommendedRoles, config.pipeline || {}, triageOutput.ok)
+  };
+
+  const modelSelection = applyModelSelection(triageOutput, config, emitter, eventBase);
+  if (modelSelection) {
+    stageResult.modelSelection = modelSelection;
+  }
+
+  if (shouldDecompose && subtasks.length > 0) {
+    emitProgress(
+      emitter,
+      makeEvent("triage:decompose", { ...eventBase, stage: "triage" }, {
+        message: `Task decomposition recommended: ${subtasks.length} subtask${subtasks.length === 1 ? "" : "s"}`,
+        detail: { shouldDecompose, subtasks }
+      })
+    );
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("triage:end", { ...eventBase, stage: "triage" }, {
+      status: triageOutput.ok ? "ok" : "fail",
+      message: triageOutput.ok ? "Triage completed" : `Triage failed: ${triageOutput.summary}`,
+      detail: { ...stageResult, provider: triageProvider, executorType: "agent" }
+    })
+  );
+
+  return { roleOverrides, stageResult };
+}

package/src/orchestrator/standby.js

@@ -0,0 +1,71 @@
+import { emitProgress, makeEvent } from "../utils/events.js";
+import { setStatus } from "../session/mutators.js";
+
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_STANDBY_RETRIES = 5;
+const HEARTBEAT_INTERVAL_MS = 30 * 1000; // 30 seconds
+
+/**
+ * Wait for a rate limit cooldown, emitting heartbeat events.
+ * Returns when the cooldown expires.
+ *
+ * @param {object} options
+ * @param {number|null} options.cooldownMs - Milliseconds to wait (null = use default)
+ * @param {string|null} options.cooldownUntil - ISO timestamp when cooldown expires
+ * @param {string} options.agent - Agent that was rate-limited
+ * @param {number} options.retryCount - Current retry attempt (for backoff)
+ * @param {object} options.emitter - Event emitter
+ * @param {object} options.eventBase - Base event fields
+ * @param {object} options.logger
+ * @param {object} options.session
+ */
+export async function waitForCooldown({ cooldownMs, cooldownUntil, agent, retryCount, emitter, eventBase, logger, session }) {
+  // Calculate wait time with exponential backoff for retries without known cooldown
+  let waitMs = cooldownMs || DEFAULT_COOLDOWN_MS;
+  if (!cooldownMs && retryCount > 0) {
+    waitMs = Math.min(DEFAULT_COOLDOWN_MS * Math.pow(2, retryCount), MAX_COOLDOWN_MS);
+  }
+
+  const resumeAt = cooldownUntil || new Date(Date.now() + waitMs).toISOString();
+
+  logger.info(`Standby: waiting ${Math.round(waitMs / 1000)}s for ${agent} rate limit (retry ${retryCount + 1}/${MAX_STANDBY_RETRIES})`);
+
+  // Emit standby start event
+  emitProgress(emitter, makeEvent("coder:standby", { ...eventBase, stage: "standby" }, {
+    message: `Rate limited — standby until ${resumeAt} (attempt ${retryCount + 1}/${MAX_STANDBY_RETRIES})`,
+    detail: { agent, cooldownUntil: resumeAt, cooldownMs: waitMs, retryCount: retryCount + 1, maxRetries: MAX_STANDBY_RETRIES }
+  }));
+
+  // Update session status
+  setStatus(session, "standby");
+
+  // Wait with periodic heartbeats
+  const startTime = Date.now();
+  const endTime = startTime + waitMs;
+
+  while (Date.now() < endTime) {
+    const remaining = endTime - Date.now();
+    const sleepTime = Math.min(HEARTBEAT_INTERVAL_MS, remaining);
+
+    await new Promise(resolve => setTimeout(resolve, sleepTime));
+
+    if (Date.now() < endTime) {
+      const remainingSec = Math.round((endTime - Date.now()) / 1000);
+      emitProgress(emitter, makeEvent("coder:standby_heartbeat", { ...eventBase, stage: "standby" }, {
+        message: `Standby: ${remainingSec}s remaining`,
+        detail: { agent, remainingMs: endTime - Date.now(), retryCount: retryCount + 1 }
+      }));
+    }
+  }
+
+  // Emit resume event
+  emitProgress(emitter, makeEvent("coder:standby_resume", { ...eventBase, stage: "standby" }, {
+    message: `Cooldown expired — resuming with ${agent}`,
+    detail: { agent, retryCount: retryCount + 1 }
+  }));
+
+  setStatus(session, "running");
+}
+
+export { DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS, MAX_STANDBY_RETRIES, HEARTBEAT_INTERVAL_MS };

package/src/orchestrator/verification-gate.js

@@ -0,0 +1,183 @@
+// Verification gate: checks whether the coder actually produced changes.
+// Prevents advancing the pipeline when coder iterations produce 0 file changes.
+
+import { execFileSync } from "node:child_process";
+
+/**
+ * @typedef {Object} VerificationResult
+ * @property {boolean} passed - true if coder produced real changes
+ * @property {number} filesChanged - count of modified/added/deleted files
+ * @property {number} linesChanged - total lines added/deleted
+ * @property {string[]} files - list of changed file paths
+ * @property {string} reason - explanation when not passed
+ * @property {string} [retryStrategy] - suggested retry approach when not passed
+ */
+
+/**
+ * Count files and lines changed since a base reference.
+ * Uses git diff --numstat to get both file and line counts.
+ *
+ * Audit follow-up: was using execSync with template-string interpolation
+ * of `baseRef` and `projectDir`. Both come ultimately from session
+ * state / config — not user shell input — but the shape was a known
+ * shell-injection vector. Switched to execFileSync with arg arrays so
+ * no interpolation reaches /bin/sh.
+ */
+export function countChangesSince(baseRef, projectDir = null) {
+  try {
+    const args = ["diff", "--numstat", String(baseRef)];
+    if (projectDir) args.push("--", String(projectDir));
+    const output = execFileSync("git", args, {
+      encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    if (!output) return { files: [], filesChanged: 0, linesAdded: 0, linesDeleted: 0 };
+
+    const lines = output.split("\n");
+    const files = [];
+    let linesAdded = 0;
+    let linesDeleted = 0;
+
+    for (const line of lines) {
+      const [added, deleted, file] = line.split("\t");
+      if (!file) continue;
+      files.push(file);
+      linesAdded += Number(added) || 0;
+      linesDeleted += Number(deleted) || 0;
+    }
+
+    return { files, filesChanged: files.length, linesAdded, linesDeleted };
+  } catch (err) {
+    // Git itself failed (baseRef invalid, repo corrupt, git binary
+    // missing). Previously we returned `filesChanged: 0` silently —
+    // indistinguishable from "the coder did nothing". Surface the
+    // error so verifyCoderOutput stops blaming the agent for an
+    // infrastructure failure.
+    return {
+      files: [], filesChanged: 0, linesAdded: 0, linesDeleted: 0,
+      gitError: err?.stderr?.toString?.() || err?.message || String(err),
+    };
+  }
+}
+
+/**
+ * Also count untracked files (new files not yet added to git).
+ *
+ * Audit follow-up: same execSync→execFileSync change as countChangesSince.
+ */
+export function countUntrackedFiles(projectDir = null) {
+  try {
+    const args = ["ls-files", "--others", "--exclude-standard"];
+    if (projectDir) args.push(String(projectDir));
+    const output = execFileSync("git", args, {
+      encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    if (!output) return { files: [] };
+    return { files: output.split("\n").filter(Boolean) };
+  } catch (err) {
+    return {
+      files: [],
+      gitError: err?.stderr?.toString?.() || err?.message || String(err),
+    };
+  }
+}
+
+/**
+ * Verify that the coder produced real changes.
+ * Counts both tracked changes and untracked files.
+ *
+ * @param {Object} params
+ * @param {string} params.baseRef - git reference to compare against
+ * @param {string} [params.projectDir] - directory scope
+ * @param {number} [params.minFiles=1] - minimum files that must change
+ * @param {number} [params.minLines=1] - minimum lines that must change
+ * @returns {VerificationResult}
+ */
+export function verifyCoderOutput({ baseRef, projectDir = null, minFiles = 1, minLines = 1 }) {
+  const tracked = countChangesSince(baseRef, projectDir);
+  const untracked = countUntrackedFiles(projectDir);
+
+  // Git infra failure (bad baseRef, corrupt repo, git missing) — not
+  // the coder's fault. Bail out with `gitError` so the caller can log
+  // it and skip the "retry with explicit file paths" feedback that
+  // would otherwise blame the agent.
+  const gitError = tracked.gitError || untracked.gitError;
+  if (gitError) {
+    return {
+      passed: false,
+      filesChanged: 0,
+      linesChanged: 0,
+      files: [],
+      reason: `Git verification failed: ${gitError}`,
+      retryStrategy: null,
+      gitError,
+    };
+  }
+
+  const untrackedFiles = untracked.files || [];
+  const totalFiles = tracked.filesChanged + untrackedFiles.length;
+  const totalLines = tracked.linesAdded + tracked.linesDeleted;
+  const allFiles = [...tracked.files, ...untrackedFiles];
+
+  const passed = totalFiles >= minFiles && (untrackedFiles.length > 0 || totalLines >= minLines);
+
+  if (passed) {
+    return {
+      passed: true,
+      filesChanged: totalFiles,
+      linesChanged: totalLines,
+      files: allFiles,
+      reason: "",
+      retryStrategy: null
+    };
+  }
+
+  return {
+    passed: false,
+    filesChanged: totalFiles,
+    linesChanged: totalLines,
+    files: allFiles,
+    reason: totalFiles === 0
+      ? "Coder produced 0 file changes"
+      : `Only ${totalFiles} file(s) and ${totalLines} line(s) changed (below minimum)`,
+    retryStrategy: buildRetryStrategy(totalFiles, totalLines)
+  };
+}
+
+/**
+ * Build a retry strategy based on the verification failure.
+ */
+function buildRetryStrategy(filesChanged, _linesChanged) {
+  if (filesChanged === 0) {
+    return "Rephrase the feedback with explicit file paths. List specific files to create/modify. Include example code snippets.";
+  }
+  return "Expand the prompt with more specific instructions. Break the task into smaller concrete steps.";
+}
+
+/**
+ * Track consecutive verification failures to detect stuck loops.
+ */
+export class VerificationTracker {
+  constructor() {
+    this.consecutiveFailures = 0;
+    this.history = [];
+  }
+
+  record(result) {
+    this.history.push({ ...result, timestamp: Date.now() });
+    if (result.passed) {
+      this.consecutiveFailures = 0;
+    } else {
+      this.consecutiveFailures += 1;
+    }
+  }
+
+  isStuck(threshold = 2) {
+    return this.consecutiveFailures >= threshold;
+  }
+
+  getLastFailure() {
+    return [...this.history].reverse().find(h => !h.passed) || null;
+  }
+}

package/src/orchestrator.js

@@ -0,0 +1,22 @@
+/**
+ * Orchestrator public API — thin barrel over the implementation in
+ * src/orchestrator/flow-runner.js.
+ *
+ * Why this file is tiny: the 2 000-line monolith that used to live here was
+ * extracted in KJC-TSK-0315 so that adding a new stage or routing rule no
+ * longer requires touching a god-module. Consumers keep importing from
+ * `src/orchestrator.js` — only the internal layout changed.
+ *
+ * See also:
+ * - src/orchestrator/flow-runner.js         — runFlow + resumeFlow internals
+ * - src/orchestrator/stages/stage-executor.js — the StageExecutor contract
+ *   that individual stages can implement to register themselves with
+ *   StageRegistry.
+ */
+
+export { runFlow, resumeFlow } from "./orchestrator/flow-runner.js";
+export { loadProductContext } from "./orchestrator/config-init.js";
+export {
+  shouldAutoContinueCheckpoint,
+  parseCheckpointAnswer
+} from "./orchestrator/flow-control.js";