karajan-code 4.70.4 → 5.0.1

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

@@ -1,140 +0,0 @@
-/**
- * PerfStage — webperf quality gate inside the iteration loop.
- *
- * KJC-TSK-0151. Wraps PerfRole and slots into the existing
- * runQualityGateStages flow alongside Sonar and Impeccable. Designed
- * to be the simplest possible quality gate:
- *
- *   - PASS verdict (cwv.pass === true) → return ok, iteration continues.
- *   - FAIL verdict → set reviewer feedback with the blocking metrics
- *     so the coder receives concrete guidance next iteration. Returns
- *     `continue` to retry the iteration loop. No repeat-detector +
- *     retry-limit machinery: rerunning Lighthouse on the same URL
- *     gives the same result unless the coder changes something, and
- *     the iteration limit (max_iterations) is the natural ceiling.
- *   - Scanner unavailable (lighthouse missing, URL unreachable, timeout)
- *     → log a warn and return ok-skipped. Best-effort, never blocks
- *     the pipeline by itself.
- *
- * The role surface (PerfRole) is responsible for persisting the result
- * to ~/.karajan/webperf/<slug>/last.json so subsequent `kj audit` runs
- * pick it up via the auto-discovery added in #602.
- */
-
-import { PerfRole } from "../../roles/perf-role.js";
-import { setReviewerFeedback } from "../../session/mutators.js";
-import { saveSession } from "../../session/store.js";
-import { emitProgress, makeEvent } from "../../utils/events.js";
-
-/**
- * Build the human-readable feedback line that goes back to the coder
- * on FAIL. Concrete enough that the LLM can act on it without re-reading
- * the whole report.
- */
-function buildFeedback(roleResult) {
-  const { result } = roleResult;
-  const score = typeof result.performanceScore === "number" ? result.performanceScore : null;
-  const blocking = (result.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)} (poor>${b.threshold})`);
-  const top = (result.issues || []).slice(0, 3).map(i => `${i.id}${i.savingsMs ? ` (~${Math.round(i.savingsMs)}ms)` : ""}`);
-
-  const lines = [`Webperf gate FAILED${score !== null ? ` (score ${score}/100)` : ""}.`];
-  if (blocking.length > 0) lines.push(`Blocking metrics: ${blocking.join(", ")}.`);
-  if (top.length > 0) lines.push(`Top opportunities: ${top.join(", ")}.`);
-  lines.push("Address the blocking metric(s) before the next iteration; rerunning without code changes will produce the same verdict.");
-  return lines.join(" ");
-}
-
-/**
- * Run the perf gate against config.webperf.url.
- *
- * @returns {Promise<{action: "ok"|"continue", stageResult?: object, summary?: string}>}
- */
-export async function runPerfStage({ config, logger, emitter, eventBase, session, trackBudget, iteration, task: _task, brainCtx }) {
-  if (!session) {
-    throw new Error("runPerfStage: `session` is required.");
-  }
-  logger.setContext({ iteration, stage: "perf" });
-  emitProgress(
-    emitter,
-    makeEvent("perf:start", { ...eventBase, stage: "perf" }, {
-      message: "WebPerf gate scanning",
-      detail: { url: config?.webperf?.url || null, preset: config?.webperf?.preset || "desktop" },
-    })
-  );
-
-  const role = new PerfRole({ config, logger, emitter });
-  const roleResult = await role.execute();
-
-  // Track budget — the role doesn't spawn an LLM but it does consume wall
-  // time; surface that in the budget summary alongside the agent calls.
-  if (trackBudget) {
-    try { trackBudget("perf", { tokens_in: 0, tokens_out: 0, cost_usd: 0 }); } catch { /* best-effort */ }
-  }
-
-  // Scanner unavailable → skip with warn. PerfRole returns ok=false for
-  // both "verdict FAIL" and "scanner failed", so we differentiate on the
-  // result.error field (set only by the second case).
-  if (!roleResult.ok && roleResult.result?.error) {
-    logger.warn(`Perf gate skipped: ${roleResult.result.error}`);
-    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
-      status: "warn",
-      message: `Perf gate skipped — ${roleResult.result.error}`,
-    }));
-    return { action: "ok", stageResult: { skipped: true, reason: roleResult.result.error } };
-  }
-
-  // PASS verdict
-  if (roleResult.ok === true) {
-    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
-      status: "ok",
-      message: roleResult.summary,
-    }));
-    return {
-      action: "ok",
-      stageResult: {
-        verdict: "PASS",
-        url: roleResult.result?.url,
-        performanceScore: roleResult.result?.performanceScore,
-        cwv: roleResult.result?.cwv,
-        savedPath: roleResult.result?.savedPath,
-        summary: roleResult.summary,
-      },
-    };
-  }
-
-  // FAIL verdict → push concrete feedback to the coder for next iteration.
-  const feedback = buildFeedback(roleResult);
-  setReviewerFeedback(session, feedback);
-  await saveSession(session);
-
-  // Brain: when enabled, surface perf feedback on the queue too.
-  if (brainCtx?.enabled) {
-    try {
-      const { processRoleOutput } = await import("../brain-coordinator.js");
-      processRoleOutput(brainCtx, {
-        roleName: "perf",
-        output: { verdict: "fail", summary: feedback },
-        iteration,
-      });
-    } catch (err) {
-      logger.warn(`Perf gate: brain queue push failed (non-blocking): ${err.message}`);
-    }
-  }
-
-  emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
-    status: "fail",
-    message: roleResult.summary,
-  }));
-
-  return {
-    action: "continue",
-    stageResult: {
-      verdict: "FAIL",
-      url: roleResult.result?.url,
-      performanceScore: roleResult.result?.performanceScore,
-      cwv: roleResult.result?.cwv,
-      issues: roleResult.result?.issues,
-      summary: feedback,
-    },
-  };
-}

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

@@ -1,85 +0,0 @@
-/**
- * Planner stage logic.
- * Extracted from pre-loop-stages.js for maintainability.
- */
-
-import { PlannerRole } from "../../roles/planner-role.js";
-import { createAgent } from "../../agents/index.js";
-import { addCheckpoint, markSessionStatus } from "../../session/store.js";
-import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
-import { parsePlannerOutput } from "../../prompts/planner.js";
-import { createStallDetector } from "../../utils/stall-detector.js";
-
-export async function runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, architectContext = null, triageDecomposition = null, trackBudget }) {
-  const task = session.task;
-  logger.setContext({ iteration: 0, stage: "planner" });
-  emitProgress(
-    emitter,
-    makeEvent("planner:start", { ...eventBase, stage: "planner" }, {
-      message: `Planner (${plannerRole.provider}) running`,
-      detail: { planner: plannerRole.provider, provider: plannerRole.provider, executorType: "agent" }
-    })
-  );
-
-  const plannerOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "planner", plannerRole.provider, payload);
-  const plannerStall = createStallDetector({
-    onOutput: plannerOnOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
-  });
-
-  const planRole = new PlannerRole({ config, logger, emitter, createAgentFn: createAgent });
-  planRole.context = { task, research: researchContext, architecture: architectContext, triageDecomposition };
-  await planRole.init();
-  const plannerStart = Date.now();
-  let planResult;
-  try {
-    planResult = await planRole.execute({ task, onOutput: plannerStall.onOutput });
-  } catch (err) {
-    logger.warn(`Planner threw: ${err.message}`);
-    planResult = { ok: false, result: { error: err.message }, summary: `Planner error: ${err.message}` };
-  } finally {
-    plannerStall.stop();
-  }
-  trackBudget({ role: "planner", provider: plannerRole.provider, model: plannerRole.model, result: planResult.result, duration_ms: Date.now() - plannerStart });
-  await addCheckpoint(session, {
-    stage: "planner",
-    iteration: 0,
-    ok: planResult.ok,
-    provider: plannerRole.provider,
-    model: plannerRole.model || null
-  });
-
-  if (!planResult.ok) {
-    await markSessionStatus(session, "failed");
-    const details = planResult.result?.error || planResult.summary || "unknown error";
-    emitProgress(
-      emitter,
-      makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
-        status: "fail",
-        message: `Planner failed: ${details}`,
-        detail: { provider: plannerRole.provider, executorType: "agent" }
-      })
-    );
-    throw new Error(`Planner failed: ${details}`);
-  }
-
-  const planOutput = planResult.result?.plan || "";
-  const plannedTask = planOutput ? `${task}\n\nExecution plan:\n${planOutput}` : task;
-  const parsedPlan = parsePlannerOutput(planOutput);
-  const stageResult = {
-    ok: true,
-    title: parsedPlan?.title || null,
-    approach: parsedPlan?.approach || null,
-    steps: parsedPlan?.steps || [],
-    completedSteps: []
-  };
-
-  emitProgress(
-    emitter,
-    makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
-      message: "Planner completed",
-      detail: { provider: plannerRole.provider, executorType: "agent" }
-    })
-  );
-
-  return { plannedTask, stageResult };
-}

package/src/orchestrator/stages/rag-context-stage.js

@@ -1,80 +0,0 @@
-// KJC-PCS-0049 Camino C — pre-loop RAG retrieval stage.
-// Runs between triage and domainCurator. When `config.rag.preload.enabled`
-// is true and the corpus has chunks, queries the retriever with the
-// task text and returns a markdown block ready to prepend to the task.
-// Failures degrade gracefully (warn + continue); the rest of the pipeline
-// never sees an exception from this stage.
-import { emitProgress, makeEvent } from "../../utils/events.js";
-import { countChunks } from "../../rag/vec-store.js";
-import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
-import { query } from "../../rag/retriever.js";
-import { openProjectStore } from "../../rag/project-store.js";
-
-const DEFAULT_TOP_K = 5;
-const DEFAULT_SCOPE = "all";
-const DEFAULT_SEARCH_MODE = "hybrid";
-const DEFAULT_SEARCH_ALPHA = 0.6;
-const MAX_CHUNK_CHARS = 600;
-
-// KJC-TSK-0463 — pull search-time knobs from config so the HU Board
-// modal (rag.search.{mode,alpha,rerank}) actually steers retrieval at
-// pipeline time. Returns the args object query() expects; unset fields
-// fall back to the retriever's own defaults.
-export function resolveSearchOpts(config) {
-  const s = config?.rag?.search ?? {};
-  const out = {
-    mode: typeof s.mode === "string" ? s.mode : DEFAULT_SEARCH_MODE,
-    alpha: Number.isFinite(s.alpha) ? s.alpha : DEFAULT_SEARCH_ALPHA,
-  };
-  if (s.rerank && typeof s.rerank === "object") out.rerankOpts = s.rerank;
-  else if (s.rerank === true) out.rerankOpts = {};
-  return out;
-}
-
-/**
- * Runs the RAG preload stage. Returns:
- *   { skipped: true, reason }                  — when disabled / empty / error
- *   { skipped: false, contextBlock, hits }     — markdown block + raw hits
- *
- * The caller decides whether to mutate `task` with the contextBlock. We
- * keep that responsibility at the call site so this module stays pure.
- */
-export async function runRagContextStage({ config, logger, emitter, eventBase, task }) {
-  const preload = config?.rag?.preload;
-  if (!preload?.enabled) return { skipped: true, reason: "disabled" };
-  if (typeof task !== "string" || task.length === 0) return { skipped: true, reason: "no-task" };
-  try {
-    const dim = config?.rag?.embedder?.dim || 768;
-    // KJC-TSK-0882: el preload que entra en el prompt del coder solo puede traer
-    // codigo de ESTE proyecto: antes abria el indice de la maquina sin filtrar.
-    const db = openProjectStore({ projectDir: config?.projectDir || process.cwd(), dim });
-    try {
-      if (countChunks(db) === 0) {
-        logger?.info?.("[rag-preload] corpus is empty, skipping (run `kj rag index` to seed)");
-        return { skipped: true, reason: "empty" };
-      }
-      const topK = preload.topK || DEFAULT_TOP_K;
-      const scope = preload.scope || DEFAULT_SCOPE;
-      const embedder = makeGovernedEmbedder(config);
-      const searchOpts = resolveSearchOpts(config);
-      const hits = await query(db, embedder, task, { topK, scope, ...searchOpts });
-      if (hits.length === 0) return { skipped: true, reason: "no-hits" };
-      const lines = hits.map((h) => {
-        const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(" > ") || "block";
-        const text = h.text.length > MAX_CHUNK_CHARS ? `${h.text.slice(0, MAX_CHUNK_CHARS)}…` : h.text;
-        return `### [${h.kind} · ${label}] ${h.source}\n\n${text}`;
-      });
-      const contextBlock = `## Prior context from RAG (auto-retrieved, top ${hits.length})\n\n${lines.join("\n\n")}`;
-      emitProgress(emitter, makeEvent("rag-preload:hits", { ...eventBase, stage: "rag-preload" }, {
-        message: `RAG preload: injected ${hits.length} chunk(s) into the task context`,
-        detail: { topK, scope, hits: hits.length, mode: searchOpts.mode, alpha: searchOpts.alpha, rerank: Boolean(searchOpts.rerankOpts) },
-      }));
-      return { skipped: false, contextBlock, hits };
-    } finally {
-      db.close();
-    }
-  } catch (err) {
-    logger?.warn?.(`[rag-preload] failed (non-blocking): ${err.message}`);
-    return { skipped: true, reason: "error", error: err.message };
-  }
-}

package/src/orchestrator/stages/rag-preload-decisor.js

@@ -1,58 +0,0 @@
-// KJC-TSK-0434 — RAG Camino D: Brain decisor heuristic for retrieval.
-// Decides WHETHER to pay the cost of running the RAG preload stage based
-// on signals from triage + task shape, instead of pre-fetching every run.
-//
-// Returns `{ pull: boolean, reason: string }`. The pre-loop driver
-// skips `runRagContextStage` when `pull === false`.
-//
-// Policies (config.rag.preload.policy):
-//   - "always"  : pull regardless (back-compat with v2.24.0 behaviour)
-//   - "never"   : never pull (useful for benchmarking, debugging)
-//   - "auto"    : heuristic — pull only when triage signals complexity,
-//                 decomposition, or when the task body is long enough
-//                 to suggest non-trivial scope. Default.
-
-const DEFAULT_POLICY = "auto";
-const COMPLEX_LEVELS = new Set(["complex", "high", "epic"]);
-const LONG_TASK_CHARS = 200;
-
-/**
- * @param {object} params
- * @param {object} [params.triage]   - triage stage result (may be null)
- * @param {string} [params.task]     - the user task text
- * @param {object} [params.config]   - full karajan config
- * @returns {{ pull: boolean, reason: string }}
- */
-export function shouldPreloadRag({ triage, task, config } = {}) {
-  const policy = config?.rag?.preload?.policy || DEFAULT_POLICY;
-
-  if (policy === "always") return { pull: true, reason: "policy:always" };
-  if (policy === "never") return { pull: false, reason: "policy:never" };
-
-  // policy === "auto" — apply heuristic.
-  // Brownfield is an explicit user signal — if onboarding produced a
-  // brief and config marks the project as brownfield, prior context is
-  // almost always worth pulling.
-  if (config?.rag?.preload?.brownfield === true) {
-    return { pull: true, reason: "auto:brownfield" };
-  }
-
-  // Triage said this is big enough to decompose → multi-HU run benefits
-  // from prior context fed to researcher/architect/planner.
-  if (triage?.shouldDecompose === true) {
-    return { pull: true, reason: "auto:decompose" };
-  }
-
-  // Triage classified the task as complex / high-effort.
-  if (triage?.level && COMPLEX_LEVELS.has(String(triage.level).toLowerCase())) {
-    return { pull: true, reason: "auto:complex" };
-  }
-
-  // Long task body usually means a brief with context, motivation and
-  // non-trivial scope — worth checking the RAG.
-  if (typeof task === "string" && task.length >= LONG_TASK_CHARS) {
-    return { pull: true, reason: "auto:long-task" };
-  }
-
-  return { pull: false, reason: "auto:low-value" };
-}

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

@@ -1,69 +0,0 @@
-/**
- * Researcher stage logic.
- * Extracted from pre-loop-stages.js for maintainability.
- */
-
-import { ResearcherRole } from "../../roles/researcher-role.js";
-import { addCheckpoint } from "../../session/store.js";
-import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
-import { createStallDetector } from "../../utils/stall-detector.js";
-
-export async function runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
-  logger.setContext({ iteration: 0, stage: "researcher" });
-
-  const researcherProvider = config?.roles?.researcher?.provider || coderRole.provider;
-  emitProgress(
-    emitter,
-    makeEvent("researcher:start", { ...eventBase, stage: "researcher" }, {
-      message: "Researcher investigating codebase",
-      detail: { researcher: researcherProvider, provider: researcherProvider, executorType: "agent" }
-    })
-  );
-
-  const researcherOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "researcher", researcherProvider, payload);
-  const researcherStall = createStallDetector({
-    onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherProvider
-  });
-
-  const researcher = new ResearcherRole({ config, logger, emitter });
-  await researcher.init({ task: session.task });
-  const researchStart = Date.now();
-  let researchOutput;
-  try {
-    researchOutput = await researcher.run({ task: session.task, onOutput: researcherStall.onOutput });
-  } catch (err) {
-    logger.warn(`Researcher threw: ${err.message}`);
-    researchOutput = { ok: false, summary: `Researcher error: ${err.message}`, result: { error: err.message } };
-  } finally {
-    researcherStall.stop();
-  }
-  trackBudget({
-    role: "researcher",
-    provider: config?.roles?.researcher?.provider || coderRole.provider,
-    model: config?.roles?.researcher?.model || coderRole.model,
-    result: researchOutput,
-    duration_ms: Date.now() - researchStart
-  });
-
-  await addCheckpoint(session, {
-    stage: "researcher",
-    iteration: 0,
-    ok: researchOutput.ok,
-    provider: config?.roles?.researcher?.provider || coderRole.provider,
-    model: config?.roles?.researcher?.model || coderRole.model || null
-  });
-
-  emitProgress(
-    emitter,
-    makeEvent("researcher:end", { ...eventBase, stage: "researcher" }, {
-      status: researchOutput.ok ? "ok" : "fail",
-      message: researchOutput.ok ? "Research completed" : `Research failed: ${researchOutput.summary}`,
-      detail: { provider: researcherProvider, executorType: "agent" }
-    })
-  );
-
-  const stageResult = { ok: researchOutput.ok, summary: researchOutput.summary || null };
-  const researchContext = researchOutput.ok ? researchOutput.result : null;
-
-  return { researchContext, stageResult };
-}