karajan-code 2.7.4 → 2.8.0

package/src/orchestrator/drivers/post-loop.js

@@ -0,0 +1,370 @@
+/**
+ * Post-loop driver — extracted from src/orchestrator/flow-runner.js in
+ * TSK-0335 (Oleada 3 of the v2.7.4 audit refactor).
+ *
+ * Handlers for everything that happens AFTER the iteration loop decides
+ * an outcome (approved, max-iterations, or simple finalization):
+ *
+ *   - handlePostLoopStages:        run tester → security → final audit
+ *                                  after the reviewer has approved; any of
+ *                                  them can demand one more coder pass.
+ *   - finalizeApprovedSession:     commit/push/PR + PG card transition +
+ *                                  full session journal + session:end event.
+ *   - handleMaxIterationsReached:  Brain-owned decision at the iteration
+ *                                  cap (extend vs finalize vs escalate).
+ *                                  Legacy path delegates to Solomon.
+ *   - tryAutoStartBoard:           auto-launch HU Board when config opts in.
+ *   - writeHistoryRecord:          non-blocking HU history write on session end.
+ *
+ * Extracted verbatim; no behavior change. flow-runner.js now imports these
+ * instead of defining them. Part of breaking up the 2254-LOC god-module —
+ * see docs/ARCHITECTURE.md and the TSK-0335 acceptance criteria.
+ */
+
+import { generateDiff } from "../../review/diff-generator.js";
+import { finalizeGitAutomation } from "../../git/automation.js";
+import { saveSession, markSessionStatus } from "../../session/store.js";
+import {
+  setReviewerFeedback, setBudget, setRtkSavings, resetRetryCount,
+} from "../../session/mutators.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { runTesterStage, runSecurityStage, runFinalAuditStage } from "../post-loop-stages.js";
+import { invokeSolomon } from "../solomon-escalation.js";
+import { tryCiComment } from "../ci-integration.js";
+import { writeIterationsJournal } from "../session-journal.js";
+import { getIntegration } from "../integrations.js";
+
+export async function handlePostLoopStages({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, ciEnabled: _ciEnabled, testerEnabled, securityEnabled, askQuestion, logger, brainCtx }) {
+  const postLoopDiff = await generateDiff({ baseRef: session.session_start_sha });
+
+  if (testerEnabled) {
+    const testerResult = await runTesterStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task, diff: postLoopDiff, askQuestion
+    });
+    if (testerResult.action === "pause") return { action: "return", result: testerResult.result };
+    if (testerResult.action === "continue") {
+      const summary = testerResult.stageResult?.summary || "Tester found issues";
+      setReviewerFeedback(session, `Tester FAILED — fix these issues:\n${summary}`);
+      await saveSession(session);
+      if (testerResult.stageResult) stageResults.tester = testerResult.stageResult;
+      // Brain: push tester failure into feedback queue + compress for next coder iteration
+      if (brainCtx?.enabled) {
+        const { processRoleOutput } = await import("../brain-coordinator.js");
+        processRoleOutput(brainCtx, { roleName: "tester", output: testerResult.stageResult, iteration: i });
+      }
+      return { action: "continue" };
+    }
+    if (testerResult.stageResult) {
+      stageResults.tester = testerResult.stageResult;
+      await tryCiComment({ config, session, logger, agent: "Tester", body: `Tests: ${testerResult.stageResult.summary || "completed"}` });
+    }
+  }
+
+  if (securityEnabled) {
+    const securityResult = await runSecurityStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task, diff: postLoopDiff, askQuestion, brainCtx
+    });
+    if (securityResult.action === "pause") return { action: "return", result: securityResult.result };
+    if (securityResult.action === "continue") {
+      const summary = securityResult.stageResult?.summary || "Security found issues";
+      setReviewerFeedback(session, `Security FAILED — fix these issues:\n${summary}`);
+      await saveSession(session);
+      if (securityResult.stageResult) stageResults.security = securityResult.stageResult;
+      // Brain: push security findings into feedback queue + compress for next coder iteration
+      if (brainCtx?.enabled) {
+        const { processRoleOutput } = await import("../brain-coordinator.js");
+        processRoleOutput(brainCtx, { roleName: "security", output: securityResult.stageResult, iteration: i });
+      }
+      return { action: "continue" };
+    }
+    if (securityResult.stageResult) {
+      stageResults.security = securityResult.stageResult;
+      await tryCiComment({ config, session, logger, agent: "Security", body: `Security scan: ${securityResult.stageResult.summary || "completed"}` });
+    }
+  }
+
+  // Final audit — last quality gate before declaring success
+  const auditResult = await runFinalAuditStage({
+    config, logger, emitter, eventBase, session, coderRole, trackBudget,
+    iteration: i, task, diff: postLoopDiff
+  });
+  if (auditResult.stageResult) {
+    stageResults.audit = auditResult.stageResult;
+    await tryCiComment({ config, session, logger, agent: "Audit", body: `Final audit: ${auditResult.stageResult.summary || "completed"}` });
+  }
+  if (auditResult.action === "retry") {
+    // Audit found actionable issues — loop back to coder
+    setReviewerFeedback(session, auditResult.feedback);
+    await saveSession(session);
+    return { action: "continue" };
+  }
+
+  return { action: "proceed" };
+}
+
+export async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i, rtkTracker }) {
+  const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
+
+  // Accumulate final commits for PG card lifecycle tracking
+  if (gitResult?.commits?.length) {
+    const tracker = getIntegration("tracker");
+    for (const c of gitResult.commits) tracker?.onCommit?.(session, c);
+  }
+
+  if (stageResults.planner?.ok) {
+    stageResults.planner.completedSteps = [...(stageResults.planner.steps ?? [])];
+  }
+  setBudget(session, budgetSummary());
+  await markSessionStatus(session, "approved");
+
+  await getIntegration("tracker")?.onSessionApproved?.({ pgCard, pgProject, config, session, gitResult, logger });
+
+  const deferredIssues = session.deferred_issues || [];
+  const rtkSavings = rtkTracker?.hasData() ? rtkTracker.summary() : undefined;
+  if (rtkSavings) setRtkSavings(session, rtkSavings);
+  await saveSession(session);
+
+  // --- Journal: write final files ---
+  const journalDir = session._journalDir;
+  if (journalDir) {
+    try {
+      await writeIterationsJournal(journalDir, session._journalIterations || []);
+      // decisions.md: writes only when Solomon was invoked (AC of KJC-TSK-0287).
+      // Pulls structured data from session.solomonRulings + session.brainDecisions.
+      const { writeDecisionsJournal: writeDecisionsJournalV2 } =
+        await import("../../session/journal/decisions-writer.js");
+      const decisionsResult = await writeDecisionsJournalV2(session, { journalDir, logger });
+      // KJC-TSK-0288: use the new tree-writer with directory grouping
+      const { writeTreeJournal: writeTreeJournalV2 } =
+        await import("../../session/journal/tree-writer.js");
+      const treeResult = await writeTreeJournalV2(journalDir, session.session_start_sha, { logger });
+
+      const journalFiles = [...(session._journalFiles || [])];
+      if (session._journalIterations?.length) journalFiles.push("iterations.md");
+      if (decisionsResult.written) journalFiles.push("decisions.md");
+      if (treeResult.written) journalFiles.push("tree.txt");
+
+      // KJC-TSK-0289: use the richer summary writer (stages table, budget
+      // breakdown, brain/solomon counts, typed links to other journal files).
+      const { writeSummaryJournal: writeSummaryJournalV2 } =
+        await import("../../session/journal/summary-writer.js");
+      const startedAt = session._startedAt ? new Date(session._startedAt).toISOString() : undefined;
+      await writeSummaryJournalV2(journalDir, {
+        task: session.task,
+        result: "APPROVED",
+        sessionId: session.id,
+        iterations: i,
+        durationMs: Date.now() - (session._startedAt || Date.now()),
+        budget: budgetSummary(),
+        stages: stageResults,
+        commits: gitResult?.commits || [],
+        files: journalFiles,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        brainDecisions: Array.isArray(session.brainDecisions) ? session.brainDecisions.length : 0,
+        solomonInvocations: Array.isArray(session.solomonRulings) ? session.solomonRulings.length : 0,
+        // KJC-TSK-0327: surface skill-source decisions in the summary so the
+        // post-mortem shows which process skills (addyosmani) and stack skills
+        // (OpenSkills) actually shaped the role prompts.
+        skills: {
+          addyosmani: session.addyosmaniSkills,
+          installed: session.autoInstalledSkills,
+          recommended: session.skillsRecommended,
+        },
+      }, { logger });
+      logger.info(`Session journal written to ${journalDir}`);
+    } catch (err) {
+      logger.warn(`Journal write failed (non-blocking): ${err.message}`);
+    }
+  }
+
+  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues };
+  if (rtkSavings) endDetail.rtk_savings = rtkSavings;
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, stage: "done" }, {
+      message: deferredIssues.length > 0
+        ? `Session approved (${deferredIssues.length} deferred issue(s) tracked as tech debt)`
+        : "Session approved",
+      detail: endDetail
+    })
+  );
+  const result = { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
+  if (rtkSavings) result.rtk_savings = rtkSavings;
+  return result;
+}
+
+export async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults, logger, askQuestion, task, rtkTracker, brainCtx }) {
+  const budget = budgetSummary();
+
+  // Brain-owned decision: max_iterations is guidance, not a hard rule.
+  // Brain evaluates the feedback queue state to decide extend / finalize / escalate.
+  // Solomon is only consulted if Brain cannot decide on its own.
+  if (brainCtx?.enabled) {
+    const entries = brainCtx.feedbackQueue?.entries || [];
+    const pending = entries.map(e => ({ source: e.source, category: e.category, severity: e.severity, description: e.description }));
+    const hasSecurity = entries.some(e => e.category === "security" || e.source === "security");
+    const hasCorrectness = entries.some(e => ["correctness", "tests"].includes(e.category));
+
+    if (hasSecurity) {
+      // Brain: security issues unresolved → cannot finalize, escalate
+      logger.warn(`Brain: max_iterations reached with ${entries.filter(e => e.category === "security" || e.source === "security").length} unresolved security issue(s) — cannot finalize`);
+      return { paused: true, sessionId: session.id, question: "Brain: unresolved security issues at max_iterations. Review manually or extend pipeline.", context: "brain_security_block", pending };
+    }
+
+    if (hasCorrectness) {
+      // Brain: correctness/test issues pending. Cap at MAX_EXTENSIONS to avoid infinite extensions.
+      const MAX_EXTENSIONS = 2;
+      if (brainCtx.extensionCount >= MAX_EXTENSIONS) {
+        logger.warn(`Brain: ${brainCtx.extensionCount} extensions exhausted with correctness issues still pending — escalating to human`);
+        return { paused: true, sessionId: session.id, question: `Brain exhausted ${MAX_EXTENSIONS} extensions with correctness/tests still pending. Manual intervention needed.`, context: "brain_extension_cap", pending };
+      }
+      brainCtx.extensionCount += 1;
+      logger.info(`Brain: max_iterations reached with ${entries.filter(e => ["correctness", "tests"].includes(e.category)).length} correctness issue(s) pending — extending iterations (extension ${brainCtx.extensionCount}/${MAX_EXTENSIONS})`);
+      resetRetryCount(session, "reviewer");
+      await saveSession(session);
+      return { approved: false, sessionId: session.id, reason: "max_iterations_extended", extraIterations: Math.ceil(config.max_iterations / 2) };
+    }
+
+    if (entries.length === 0) {
+      // Brain: no pending feedback → last reviewer approved, finalize
+      logger.info("Brain: max_iterations reached with clean feedback queue — finalizing as approved");
+      return { approved: true, sessionId: session.id, reason: "brain_approved" };
+    }
+
+    // hasStyleOnly: genuine dilemma → Brain consults Solomon
+    logger.info(`Brain: max_iterations with ${entries.length} style-only issue(s) — consulting Solomon on dilemma`);
+    const solomonResult = await invokeSolomon({
+      config, logger, emitter, eventBase, stage: "max_iterations", askQuestion, session,
+      iteration: config.max_iterations,
+      conflict: {
+        stage: "brain-max-iterations",
+        task,
+        iterationCount: config.max_iterations,
+        maxIterations: config.max_iterations,
+        budget_usd: budget?.total_cost_usd || 0,
+        dilemma: `Max iterations reached with ${entries.length} style-only issue(s) pending. Accept as-is or request more work?`,
+        pendingIssues: pending,
+        history: [{ agent: "pipeline", feedback: session.last_reviewer_feedback || "Max iterations reached" }]
+      }
+    });
+    // Brain applies Solomon's decision
+    if (solomonResult.action === "approve") {
+      logger.info("Brain: Solomon advised approve for style-only pending — finalizing");
+      return { approved: true, sessionId: session.id, reason: "brain_solomon_approved" };
+    }
+    if (solomonResult.action === "continue") {
+      return { approved: false, sessionId: session.id, reason: "max_iterations_extended", extraIterations: solomonResult.extraIterations || Math.ceil(config.max_iterations / 2) };
+    }
+    if (solomonResult.action === "pause") {
+      return { paused: true, sessionId: session.id, question: solomonResult.question, context: "brain_solomon_dilemma" };
+    }
+    // Fallback: escalate to human
+    return { paused: true, sessionId: session.id, question: `Brain+Solomon cannot resolve: ${entries.length} pending issue(s) at max_iterations`, context: "max_iterations" };
+  }
+
+  // Legacy path (Brain disabled): original Solomon-driven flow
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "max_iterations", askQuestion, session,
+    iteration: config.max_iterations,
+    conflict: {
+      stage: "max_iterations",
+      task,
+      iterationCount: config.max_iterations,
+      maxIterations: config.max_iterations,
+      budget_usd: budget?.total_cost_usd || 0,
+      history: [{ agent: "pipeline", feedback: session.last_reviewer_feedback || "Max iterations reached without reviewer approval" }]
+    }
+  });
+
+  if (solomonResult.action === "approve") {
+    logger.info("Solomon approved coder's work at max_iterations checkpoint");
+    return { approved: true, sessionId: session.id, reason: "solomon_approved" };
+  }
+
+  if (solomonResult.action === "continue") {
+    if (solomonResult.humanGuidance) {
+      setReviewerFeedback(session, `Solomon guidance: ${solomonResult.humanGuidance}`);
+    }
+    resetRetryCount(session, "reviewer");
+    await saveSession(session);
+    const extraIterations = solomonResult.extraIterations || config.max_iterations;
+    return { approved: false, sessionId: session.id, reason: "max_iterations_extended", humanGuidance: solomonResult.humanGuidance, extraIterations };
+  }
+
+  if (solomonResult.action === "pause") {
+    return { paused: true, sessionId: session.id, question: solomonResult.question, context: "max_iterations" };
+  }
+
+  if (solomonResult.action === "subtask") {
+    return { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "max_iterations_subtask" };
+  }
+
+  // Solomon couldn't resolve — fail
+  setBudget(session, budgetSummary());
+  const rtkSavings = rtkTracker?.hasData() ? rtkTracker.summary() : undefined;
+  if (rtkSavings) setRtkSavings(session, rtkSavings);
+  await markSessionStatus(session, "failed");
+  const failDetail = { approved: false, reason: "max_iterations", iterations: config.max_iterations, stages: stageResults, budget: budgetSummary() };
+  if (rtkSavings) failDetail.rtk_savings = rtkSavings;
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, stage: "done" }, {
+      status: "fail",
+      message: "Max iterations reached (Solomon could not resolve)",
+      detail: failDetail
+    })
+  );
+  return { approved: false, sessionId: session.id, reason: "max_iterations" };
+}
+
+export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
+  // TSK-0273: gate on hu_board.auto_start alone. The previous double-gate
+  // (enabled && auto_start) was confusing because `enabled` was never the
+  // user-facing switch — only auto_start was. This matches the AC: "kj run
+  // auto-inicia el board server si hu_board.auto_start es true".
+  if (!config.hu_board?.auto_start) return;
+  // Never auto-start during vitest: races the PID file and starts a detached
+  // process that outlives the test run.
+  if (process.env.VITEST || process.env.NODE_ENV === "test") return;
+
+  try {
+    const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
+    const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
+    const boardPort = config.hu_board.port || 4000;
+    // Scope the board URL to the current run's project (`/p/<slug>`) so
+    // the user lands on a filtered view, not the global dashboard.
+    const slug = config.projectDir ? slugFor(config.projectDir) : null;
+    const boardResult = await startBoard(boardPort, { projectSlug: slug });
+    const status = boardResult.alreadyRunning ? "already running" : "started";
+    // Highlighted URL box — visible regardless of log level (matches the
+    // post-planner auto-HU banner so the user gets the same signal either
+    // way the board got started).
+    console.log(renderBoardBanner({ url: boardResult.url, status }));
+    logger.info(`HU Board ${status} at ${boardResult.url}`);
+    emitProgress(emitter, makeEvent("board:started", eventBase, {
+      message: `HU Board running at ${boardResult.url}`,
+      detail: { pid: boardResult.pid, port: boardPort, url: boardResult.url }
+    }));
+  } catch (err) {
+    logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
+  }
+}
+
+export async function writeHistoryRecord({ sessionId, task, result, logger }) {
+  try {
+    const { createHistoryRecord } = await import("../../hu/store.js");
+    const approved = Boolean(result?.approved);
+    const summary = result?.review?.summary || result?.reason || null;
+    await createHistoryRecord(sessionId, {
+      task,
+      result: JSON.stringify(result),
+      approved,
+      summary
+    });
+  } catch (err) {
+    logger.warn(`HU history record failed (non-blocking): ${err.message}`);
+  }
+}

package/src/orchestrator/drivers/pre-loop-phases/auto-hu-batch.js

@@ -0,0 +1,116 @@
+/**
+ * Extracted from `src/orchestrator/drivers/pre-loop.js` in TSK-0337
+ * (audit recommendation #6). Previously an internal helper inside
+ * pre-loop.js; moved here so the driver stays under 600 LOC.
+ * Behaviour unchanged.
+ *
+ * Auto-generates an HU batch from triage's decomposition recommendation
+ * when no manual `huFile` is present. Runs after researcher/architect/
+ * planner so context is available for better HU generation. Sets
+ * `stageResults.huReviewer` so `needsSubPipeline` picks it up later.
+ *
+ * Side effects:
+ *   - Persists `batch.json` to `~/.karajan/hu-stories/<batchSessionId>/`
+ *     so the sub-pipeline can update story status via `saveHuBatch`.
+ *   - Auto-starts the HU board (skipped under VITEST / NODE_ENV=test).
+ */
+
+import { emitProgress, makeEvent } from "#utils/events.js";
+
+export async function maybeGenerateAutoHuBatch({
+  flags, stageResults, task, logger, emitter, eventBase, projectDir, session,
+}) {
+  // Skip if user passed a manual hu-file
+  if (flags?.huFile) return;
+  // Skip if hu-reviewer already produced a batch (manual enable + PG stories)
+  if (stageResults.huReviewer) return;
+  // Need triage decomposition recommendation
+  const shouldDecompose = stageResults.triage?.shouldDecompose;
+  const subtasks = stageResults.triage?.subtasks;
+  if (!shouldDecompose || !Array.isArray(subtasks) || subtasks.length < 2) return;
+
+  const { generateHuBatch } = await import("#hu/auto-generator.js");
+
+  // Detect if project is new: empty dir or only .git/.karajan/.gitignore
+  let isNewProject = false;
+  try {
+    const fs = await import("node:fs/promises");
+    const entries = await fs.readdir(projectDir);
+    const relevant = entries.filter(e => !e.startsWith(".git") && e !== ".karajan" && e !== ".gitignore");
+    isNewProject = relevant.length === 0;
+  } catch { /* ignore */ }
+
+  // Extract stack hints from planner + architect output
+  const stackHints = [];
+  const combined = `${stageResults.planner?.plan || ""} ${stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : ""} ${task}`.toLowerCase();
+  const stackKeywords = ["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "fastapi", "django", "spring", "gin", "nestjs", "monorepo", "workspaces"];
+  for (const kw of stackKeywords) {
+    if (combined.includes(kw)) stackHints.push(kw);
+  }
+
+  const batch = generateHuBatch({
+    originalTask: task,
+    subtasks,
+    stackHints,
+    isNewProject,
+    researcherContext: stageResults.researcher?.summary || null,
+    architectContext: stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : null
+  });
+
+  // Persist batch to HU store so hu-sub-pipeline can update story status via saveHuBatch.
+  // Use session.id as batchSessionId.
+  const batchSessionId = `auto-${session.id}`;
+  try {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const { getKarajanHome } = await import("#utils/paths.js");
+    const huDir = path.join(getKarajanHome(), "hu-stories", batchSessionId);
+    await fs.mkdir(huDir, { recursive: true });
+    const persistBatch = {
+      session_id: batchSessionId,
+      project_id: batchSessionId,
+      project_name: batch.projectName,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      stories: batch.stories
+    };
+    await fs.writeFile(path.join(huDir, "batch.json"), JSON.stringify(persistBatch, null, 2));
+  } catch (err) {
+    logger.warn(`Auto-HU: failed to persist batch (${err.message}) — sub-pipeline will use in-memory fallback`);
+  }
+
+  // Wrap in format compatible with needsSubPipeline + runHuSubPipeline
+  stageResults.huReviewer = {
+    ok: true,
+    stories: batch.stories,
+    total: batch.total,
+    certified: batch.certified,
+    batchSessionId,
+    auto_generated: true,
+    source: batch.source
+  };
+
+  logger.info(`Auto-HU: generated ${batch.total} stories (${batch.source.triage_subtasks} subtasks${isNewProject ? ", new project" : ""}${stackHints.length ? `, stack: ${stackHints.join(",")}` : ""})`);
+  emitProgress(emitter, makeEvent("hu:auto-generated", { ...eventBase, stage: "hu-auto-gen" }, {
+    message: `Auto-generated ${batch.total} HU(s) from triage decomposition`,
+    detail: { total: batch.total, subtasks: batch.source.triage_subtasks, isNewProject, stackHints, projectName: batch.projectName }
+  }));
+
+  // Auto-start the board so the user can see the generated HUs.
+  // Always fires when auto-HU runs, independent of hu_board.auto_start flag.
+  // Never during vitest — would race the PID file and leave a detached
+  // node process around after the suite (TSK-0273).
+  if (process.env.VITEST || process.env.NODE_ENV === "test") return;
+  try {
+    const { startBoard, renderBoardBanner } = await import("../../../commands/board.js");
+    const desiredPort = session.config_snapshot?.hu_board?.port ?? 4000;
+    const boardResult = await startBoard(desiredPort);
+    const url = boardResult.url;
+    const status = boardResult.alreadyRunning ? "already running" : "started";
+    const projectName = batch.projectName || "Auto-generated HUs";
+    console.log(renderBoardBanner({ url, status, projectName }));
+    logger.info(`HU Board ${status} at ${url} (project: ${projectName})`);
+  } catch (err) {
+    logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
+  }
+}

package/src/orchestrator/drivers/pre-loop-phases/config-deprecations.js

@@ -0,0 +1,47 @@
+/**
+ * Extracted from `src/orchestrator/drivers/pre-loop.js` in TSK-0337
+ * (audit recommendation #6: continue pre-loop extraction). pre-loop.js
+ * had grown to 626 LOC, over the 600-LOC ceiling that the file's own
+ * docstring set. Splitting the deprecation warnings, addyosmani skill
+ * bootstrap, and auto-HU batch generation into their own modules brings
+ * the driver back to ~440 LOC.
+ *
+ * Behaviour unchanged. The function is exported with the same name and
+ * signature so the move is mechanical.
+ *
+ * Emits one-shot warnings for config keys ignored since v2.7.4. Currently:
+ *   - `sonarqube.enabled` (kj.config.yml) → ignored, sonar is intrinsic
+ *   - `--no-sonar` CLI flag → ignored
+ */
+
+import { emitProgress, makeEvent } from "#utils/events.js";
+
+export function emitConfigDeprecations(config, logger, emitter, eventBase) {
+  const dep = config?._deprecated;
+  if (!dep) return;
+
+  if (dep.sonarqubeEnabledKey) {
+    const m =
+      "DEPRECATED: `sonarqube.enabled` in kj.config.yml is ignored since v2.7.4. " +
+      "Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and " +
+      "skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy. " +
+      "Remove the key from your config to silence this warning.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { key: "sonarqube.enabled", since: "v2.7.4" },
+    }));
+  }
+
+  if (dep.noSonarFlag) {
+    const m =
+      "DEPRECATED: `--no-sonar` flag is ignored since v2.7.4. Sonar runs for code " +
+      "tasks by policy. To skip Sonar on a one-off run, use a non-code task type " +
+      "(e.g. `--task-type doc`) or rely on Solomon's runtime override.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { flag: "--no-sonar", since: "v2.7.4" },
+    }));
+  }
+}

package/src/orchestrator/drivers/pre-loop-phases/ensure-addyosmani-skills.js

@@ -0,0 +1,84 @@
+/**
+ * Extracted from `src/orchestrator/drivers/pre-loop.js` in TSK-0337
+ * (audit recommendation #6). Previously a 60-line export inside
+ * pre-loop.js; moved here to keep that driver under the 600-LOC
+ * ceiling its own docstring set. Behaviour and signature unchanged.
+ *
+ * Refreshes the addyosmani/agent-skills catalog (clones or pulls,
+ * gated by `refreshDays`) and resolves which slugs are relevant to
+ * the current task. Sets the result on the session via the
+ * `setAddyosmaniSkills` mutator so downstream stages can read it
+ * without re-running git.
+ *
+ * Failures are non-blocking: a missing git, a network blip, or an
+ * unparseable catalog all just mark the catalog unavailable and
+ * emit a `skills:addyosmani-unavailable` event. The pipeline keeps
+ * going — the addyosmani sources are an optional supplement.
+ */
+
+import {
+  refreshIfStale as refreshAddyosmaniCatalog,
+  listAvailableSlugs as listAddyosmaniSlugs,
+} from "#skills/addyosmani-catalog.js";
+import { resolveAddyosmaniSlugs } from "#skills/addyosmani-role-map.js";
+import { setAddyosmaniSkills } from "#session/mutators.js";
+import { emitProgress, makeEvent } from "#utils/events.js";
+
+export async function ensureAddyosmaniSkills({ task, config, logger, session, emitter, eventBase }) {
+  const skillsConfig = config?.skills || {};
+  const sources = Array.isArray(skillsConfig.sources) ? skillsConfig.sources : ["addyosmani", "openskills", "local"];
+  const addyConfig = skillsConfig.addyosmani || {};
+  // Test harness override: config.testHarness.defaultAddyosmaniEnabled=false
+  // prevents orchestrator tests from spawning git. Tests that need the real
+  // catalog opt in by setting config.skills.addyosmani.enabled = true.
+  // Post-v2.7.5 no longer reads globalThis directly — config.testHarness is
+  // populated by the loader from the global or the production default.
+  const harnessDefault = config?.testHarness?.defaultAddyosmaniEnabled;
+  const enabledFromConfig = addyConfig.enabled === true
+    || (addyConfig.enabled !== false && harnessDefault !== false);
+  const enabled = enabledFromConfig && sources.includes("addyosmani");
+  if (!enabled) return;
+
+  const refreshDays = Number.isFinite(addyConfig.refreshDays) ? addyConfig.refreshDays : 7;
+  const refreshMs = Math.max(0, refreshDays) * 24 * 60 * 60 * 1000;
+
+  try {
+    const refreshResult = await refreshAddyosmaniCatalog({
+      refreshMs,
+      repoUrl: addyConfig.repoUrl,
+      logger,
+    });
+
+    if (!refreshResult.ok) {
+      setAddyosmaniSkills(session, { available: false, reason: refreshResult.error || "refresh failed" });
+      emitProgress(emitter, makeEvent("skills:addyosmani-unavailable", { ...eventBase, stage: "skills" }, {
+        message: `addyosmani/agent-skills catalog unavailable: ${refreshResult.error || refreshResult.action}`,
+        detail: { action: refreshResult.action, hint: "Install git to enable process skills from addyosmani/agent-skills" },
+      }));
+      return;
+    }
+
+    const available = new Set(await listAddyosmaniSlugs());
+    const resolved = resolveAddyosmaniSlugs({ role: null, task }); // role resolution happens per-stage later
+    const valid = resolved.filter((slug) => available.has(slug));
+
+    setAddyosmaniSkills(session, {
+      available: true,
+      action: refreshResult.action,
+      resolvedSlugs: valid,
+      allAvailable: Array.from(available),
+    });
+
+    emitProgress(emitter, makeEvent("skills:addyosmani-ready", { ...eventBase, stage: "skills" }, {
+      message: `addyosmani/agent-skills ${refreshResult.action} — ${available.size} slug(s) available, ${valid.length} relevant to task`,
+      detail: {
+        action: refreshResult.action,
+        relevantSlugs: valid,
+        availableCount: available.size,
+      },
+    }));
+  } catch (err) {
+    logger.warn(`addyosmani catalog step failed (non-blocking): ${err.message}`);
+    setAddyosmaniSkills(session, { available: false, reason: err.message });
+  }
+}