karajan-code 4.70.4 → 5.0.0

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

@@ -1,137 +0,0 @@
-/**
- * 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";
-import { detectProjectStack } from "#utils/stack-detect.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 */ }
-
-  // Stack hints from planner + architect text. Now multi-ecosystem
-  // (was 13/16 JS keywords — Python/Go/Rust barely existed). Combined
-  // with `detectProjectStack(projectDir)` below to override the text
-  // heuristic with the actual filesystem reality when available.
-  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", "nestjs", "monorepo", "workspaces",
-    "pytest", "flask", "fastapi", "django", "numpy", "pandas",
-    "gin", "fiber", "go",
-    "cargo", "rust",
-    "spring",
-  ];
-  for (const kw of stackKeywords) {
-    if (combined.includes(kw)) stackHints.push(kw);
-  }
-
-  // Filesystem trumps text. detectProjectStack inspects package.json /
-  // pyproject.toml / go.mod / Cargo.toml, so a pure-python repo gets
-  // `language: "python"` regardless of what the task text says.
-  let detectedLanguage = null;
-  try {
-    const fsStack = await detectProjectStack(projectDir);
-    if (fsStack?.language) detectedLanguage = fsStack.language;
-  } catch { /* best-effort */ }
-
-  const batch = generateHuBatch({
-    originalTask: task,
-    subtasks,
-    stackHints,
-    isNewProject,
-    language: detectedLanguage,
-    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, boardSlug } = await import("../../../commands/board.js");
-    const desiredPort = session.config_snapshot?.hu_board?.port ?? 4000;
-    // KJC-TSK-0884: its project's scoped view, not the global dashboard.
-    const boardResult = await startBoard(desiredPort, { projectSlug: projectDir ? boardSlug(projectDir) : null });
-    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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * 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 });
-  }
-}

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -1,393 +0,0 @@
-/**
- * Pre-loop phase: load a persisted plan and inject it into stageResults.
- *
- * Extracted from `src/orchestrator/drivers/pre-loop.js` in PR-K (audit
- * follow-up) to drag runPreLoopStages out of god-function territory
- * (was 496 LOC; extracting this 189-LOC block brings it to ~310).
- *
- * Behaviour is byte-for-byte identical to the inlined version. The
- * extraction keeps the dynamic-import pattern (deferred load of
- * plan-store / plan-schema / plan-executor / plan-hu-ops) so the
- * dynamic-imports budget test stays unchanged.
- *
- * Returns { handled, plannedTask }:
- *   - handled=true  → caller short-circuits (plan was loaded; skip
- *                     researcher/architect/planner phases below).
- *   - handled=false → caller continues with the regular planning flow.
- *     Either flags.plan was unset OR loadPlan returned null OR the
- *     try/catch swallowed an error (logged as a warning).
- *
- * The function still mutates session via the existing mutators
- * (setPlanRef, setPlanSyncCallback, setLiveStatusUpdater,
- * setLiveOutcomeUpdater, setPreLoopContext) and stageResults
- * (researcher / architect / planner / huReviewer slots). That
- * mutation contract is unchanged from the inlined version — see
- * tests/architecture/session-write-boundary.test.js for the
- * mutator-routing invariant.
- */
-
-import { saveSession } from "#session/store.js";
-import {
-  setPlanRef, setPlanSyncCallback, setLiveStatusUpdater,
-  setLiveOutcomeUpdater, setPreLoopContext,
-} from "#session/mutators.js";
-import { emitProgress, makeEvent } from "#utils/events.js";
-import { listActiveRuns } from "../../../utils/run-registry.js";
-import { keepRoutingMetrics } from "../../../hu/routing-metrics.js";
-
-/**
- * @param {object} args
- * @param {object} args.flags        — runFlow flags (reads flags.plan, flags.hu)
- * @param {object} args.updatedConfig — the running config (reads projectDir)
- * @param {object} args.session
- * @param {object} args.stageResults — mutated: researcher / architect / planner / huReviewer slots
- * @param {object} args.eventBase
- * @param {object} args.emitter
- * @param {object} args.logger
- * @param {string} args.task         — original task description, used to build plannedTask
- * @returns {Promise<{handled: boolean, plannedTask: string|null}>}
- */
-export async function injectLoadedPlan({ flags, updatedConfig, session, stageResults, eventBase, emitter, logger, task }) {
-  if (!flags.plan) return { handled: false, plannedTask: null };
-
-  try {
-    const { loadPlan, savePlan: savePlanToDisk } = await import("../../../plan/plan-store.js");
-    const { isPlanV2 } = await import("../../../plan/plan-schema.js");
-    const { planToHuBatch, syncResultsToPlan } = await import("../../../plan/plan-executor.js");
-    const projectDir = updatedConfig.projectDir || process.cwd();
-    const loadedPlan = await loadPlan(projectDir, flags.plan);
-    if (!loadedPlan) {
-      logger.warn(`Plan ${flags.plan} not found — falling back to normal pipeline`);
-      return { handled: false, plannedTask: null };
-    }
-
-    logger.info(`Loaded persisted plan: ${flags.plan} (v${loadedPlan.version || 1})`);
-    emitProgress(emitter, makeEvent("plan:loaded", { ...eventBase, stage: "plan" }, {
-      message: `Plan loaded: ${flags.plan}`,
-      detail: { planId: flags.plan, task: loadedPlan.task, version: loadedPlan.version, huCount: loadedPlan.hus?.length || 0 }
-    }));
-
-    // Zombie reconciliation: a previous run may have died mid-flight,
-    // leaving HUs stuck in coding/reviewing/running. The board-side
-    // reaper only runs inside the board; without this, a headless
-    // `kj run --plan` would refuse to pick those HUs up.
-    const reaped = await reconcilePlanHuZombies({ loadedPlan, planId: flags.plan, logger });
-    if (reaped > 0) {
-      await savePlanToDisk(projectDir, loadedPlan);
-      emitProgress(emitter, makeEvent("plan:zombies-reaped", { ...eventBase, stage: "plan" }, {
-        message: `Reset ${reaped} stale HU(s) from a previous run that did not finish`,
-        detail: { planId: flags.plan, count: reaped }
-      }));
-    }
-    stageResults.researcher = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
-    stageResults.architect = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
-    stageResults.planner = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
-
-    // Tests-first gate (v2.7.5): refuse to run a plan when any HU
-    // has no acceptance_tests. Mirrors the gate in `kj plan ready`
-    // so the CLI path and the board's "▶ Run plan" button enforce
-    // the same contract.
-    if (isPlanV2(loadedPlan) && Array.isArray(loadedPlan.hus)) {
-      assertEveryHuHasTests({ loadedPlan, planId: flags.plan, eventBase, emitter, logger });
-
-      // PR-E (auto-certify + anomaly guards): the user expects
-      // pending HUs to be runnable; "certified" was an invisible
-      // wall. Helpers in plan-hu-ops.js so they can be unit-tested
-      // without spinning up the orchestrator. Pulled from the same
-      // dynamic import we use a few lines below for updateHuStatus +
-      // setHuOutcome — no extra import budget.
-      const planHuOps = await import("../../../plan/plan-hu-ops.js");
-      await autoCertifyAndAssertRunnable({ planHuOps, loadedPlan, planId: flags.plan, projectDir, savePlanToDisk, eventBase, emitter, logger });
-
-      // v2 plan with HUs → inject as huReviewer so sub-pipeline
-      // picks them up. Sets every callback (sync, live status, live
-      // outcome) and stamps plan.status = "running".
-      if (loadedPlan.hus?.length > 0) {
-        const huBatch = planToHuBatch(loadedPlan);
-        applyHuFilterIfRequested({ huBatch, flags, eventBase, emitter, logger });
-        if (huBatch.ok) {
-          stageResults.huReviewer = huBatch;
-          wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan, savePlanToDisk, planHuOps, logger });
-          logger.info(`Plan ${flags.plan}: ${huBatch.certified} HUs ready for execution`);
-          emitProgress(emitter, makeEvent("plan:hus-loaded", { ...eventBase, stage: "plan" }, {
-            message: `${huBatch.certified} HUs loaded from plan`,
-            detail: { planId: flags.plan, total: huBatch.total, certified: huBatch.certified }
-          }));
-          loadedPlan.status = "running";
-          await savePlanToDisk(projectDir, loadedPlan);
-        }
-      }
-    }
-
-    // Inject contexts that the legacy planning phases would have
-    // produced. Then build a plannedTask string for the non-HU /
-    // fallback iteration path.
-    const ctx = loadedPlan.context || {};
-    setPreLoopContext(session, {
-      research: ctx.researchContext || loadedPlan.researchContext || null,
-      architect: ctx.architectContext || loadedPlan.architectContext || null,
-      plan: loadedPlan.approach || loadedPlan.plan || null,
-    });
-    await saveSession(session);
-
-    return { handled: true, plannedTask: buildPlannedTaskFromLoadedPlan({ task, loadedPlan }) };
-  } catch (err) {
-    logger.warn(`Plan loading failed: ${err.message} — falling back to normal pipeline`);
-    return { handled: false, plannedTask: null };
-  }
-}
-
-/**
- * Reset HUs that look mid-execution but have no live run behind them.
- *
- * Resilience audit, Phase 3 (Hallazgo A1 / status-zombi). A previous
- * `kj run --plan` flipped HUs to `coding`/`reviewing`/`running` in the
- * plan JSON, then died (SIGKILL, terminal closed, OOM, crash). The
- * board-side `hu-zombie-reaper` only queries SQLite and only runs
- * inside the board process, so the plan JSON on disk kept stale
- * in-flight statuses forever. The next `kj run --plan` then refused to
- * pick those HUs up.
- *
- * Cross-check via `run-registry`: if there is a live run with our
- * planId, do NOT touch — that run owns the in-flight HUs. Otherwise
- * any in-flight status with no live owner is a zombie → reset to
- * `pending` so it can run again.
- *
- * Mutates `loadedPlan.hus` in place. Returns the number of HUs reset
- * so the caller can persist + emit a progress event.
- *
- * @param {object} args
- * @param {object} args.loadedPlan
- * @param {string} args.planId
- * @param {object} [args.logger]
- * @returns {number}
- */
-export function reconcilePlanHuZombies({ loadedPlan, planId, logger }) {
-  if (!Array.isArray(loadedPlan?.hus) || loadedPlan.hus.length === 0) return 0;
-  const activeRuns = listActiveRuns({ planId });
-  if (activeRuns.length > 0) return 0;
-  const ZOMBIE_STATES = new Set(["coding", "reviewing", "running"]);
-  let reaped = 0;
-  for (const hu of loadedPlan.hus) {
-    if (ZOMBIE_STATES.has(hu.status)) {
-      const previous = hu.status;
-      hu.status = "pending";
-      reaped += 1;
-      logger?.warn?.(`[plan] HU ${hu.id || hu.hu_id || "?"} was '${previous}' but no live run owns the plan — reset to 'pending'.`);
-    }
-  }
-  return reaped;
-}
-
-/**
- * Throws when any HU lacks an acceptance_tests array with at least
- * one entry. Logs + emits the same `plan:tests-missing` progress
- * event as the inlined version did.
- */
-function assertEveryHuHasTests({ loadedPlan, planId, eventBase, emitter, logger }) {
-  const missing = loadedPlan.hus.filter(
-    (h) => !Array.isArray(h.acceptance_tests) || h.acceptance_tests.length === 0
-  );
-  if (missing.length === 0) return;
-  const offenders = missing.map((h) => `  - ${h.id}  ${(h.title || "").slice(0, 60)}`).join("\n");
-  const msg =
-    `Refusing to run plan ${planId}: ${missing.length}/${loadedPlan.hus.length} HU(s) have no acceptance_tests.\n`
-    + `${offenders}\n\n`
-    + "Tests-first flow requires a test contract per HU. Edit each HU on the board\n"
-    + "(http://localhost:4000) via the ✎ Edit button, or re-run `kj plan` to regenerate.";
-  logger.error(msg);
-  emitProgress(emitter, makeEvent("plan:tests-missing", { ...eventBase, stage: "plan" }, {
-    status: "fail",
-    message: `Plan ${planId}: ${missing.length} HU(s) missing acceptance_tests`,
-    detail: { planId, missingHuIds: missing.map((h) => h.id) }
-  }));
-  throw new Error(`Plan ${planId} has ${missing.length} HU(s) with no acceptance_tests — see the run log for details.`);
-}
-
-/**
- * Promotes pending HUs with tests to certified, then asserts at
- * least one HU is runnable. Throws (with `plan:no-runnable` event)
- * when nothing is left to do, so the orchestrator never silently
- * falls back to single-task mode and burns tokens.
- */
-async function autoCertifyAndAssertRunnable({ planHuOps, loadedPlan, planId, projectDir, savePlanToDisk, eventBase, emitter, logger }) {
-  const { autoCertifyPendingHus, assertPlanRunnable } = planHuOps;
-  const promoted = autoCertifyPendingHus(loadedPlan);
-  if (promoted > 0) {
-    await savePlanToDisk(projectDir, loadedPlan);
-    logger.info(`Plan ${planId}: auto-certified ${promoted} pending HU(s) — ready to run`);
-    emitProgress(emitter, makeEvent("plan:auto-certified", { ...eventBase, stage: "plan" }, {
-      message: `Auto-certificadas ${promoted} HU(s) pendientes`,
-      detail: { planId, count: promoted }
-    }));
-  }
-  try {
-    assertPlanRunnable(loadedPlan, planId);
-  } catch (err) {
-    logger.error(err.message);
-    emitProgress(emitter, makeEvent("plan:no-runnable", { ...eventBase, stage: "plan" }, {
-      status: "fail", message: err.message,
-      detail: { planId }
-    }));
-    throw err;
-  }
-}
-
-/**
- * PR4: when --hu <ids> is set, narrow the batch to those HU ids by
- * marking the rest as `done` in memory. The plan JSON on disk is
- * NOT touched — this is a run-time filter only. Throws when none of
- * the requested ids exist.
- */
-function applyHuFilterIfRequested({ huBatch, flags, eventBase, emitter, logger }) {
-  if (!huBatch.ok || !flags.hu) return;
-  const requested = String(flags.hu).split(",").map((s) => s.trim()).filter(Boolean);
-  if (requested.length === 0) {
-    logger.warn(`--hu was empty after parsing — falling back to running every certified HU`);
-    return;
-  }
-  // Humanización IDs: resolver cada ref a un hu.id largo aceptando 3 formas:
-  //  1. `hu_<planId>_<NNN>` (id largo, exacto)
-  //  2. `INFRA-001` (short_id que el planner asignó)
-  //  3. `001` (sufijo numérico — busca un hu.id que termine en `_001`)
-  // El resolver es case-insensitive para short_id y sufijo.
-  const resolvedIds = new Set();
-  const unresolved = [];
-  for (const ref of requested) {
-    const id = resolveHuRef(ref, huBatch.stories);
-    if (id) resolvedIds.add(id);
-    else unresolved.push(ref);
-  }
-  const found = huBatch.stories.filter((s) => resolvedIds.has(s.id));
-  if (unresolved.length > 0) {
-    logger.warn(`--hu: ignored ${unresolved.length} unknown HU ref(s): ${unresolved.join(", ")}`);
-  }
-  if (found.length === 0) {
-    throw new Error(`--hu: none of the requested HU ref(s) exist in plan ${flags.plan}: ${requested.join(", ")}`);
-  }
-  for (const story of huBatch.stories) {
-    if (!resolvedIds.has(story.id)) story.status = "done";
-  }
-  huBatch.certified = found.length;
-  logger.info(`Plan ${flags.plan}: --hu filter active — ${found.length}/${huBatch.total} HU(s) will run (${found.map((s) => s.id).join(", ")})`);
-  emitProgress(emitter, makeEvent("plan:hu-filter", { ...eventBase, stage: "plan" }, {
-    message: `--hu filter: ${found.length} HU(s) selected, ${huBatch.total - found.length} skipped`,
-    detail: { planId: flags.plan, requested, ignored: unresolved, willRun: found.map((s) => s.id) }
-  }));
-}
-
-/**
- * Wire the four session-scoped callbacks the run will invoke as it
- * progresses: PR1 live status (per HU), PR3 live outcome (per HU
- * exit), and the syncResultsToPlan rollup (end-of-run).
- */
-function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan, savePlanToDisk, planHuOps, logger }) {
-  setPlanRef(session, { planId: loadedPlan.planId, projectDir });
-  setPlanSyncCallback(session, async (subResult) => {
-    syncResultsToPlan(loadedPlan, subResult);
-    await savePlanToDisk(projectDir, loadedPlan);
-  });
-  // PR1: live HU status. Without this the plan only updates at
-  // end-of-run and the board's Kanban looks frozen during execution.
-  // (`planHuOps` was loaded above for PR-E auto-certify — reuse the
-  // reference to stay under the dynamic-import budget.)
-  const { updateHuStatus: updateHuStatusFn, setHuOutcome: setHuOutcomeFn } = planHuOps;
-  setLiveStatusUpdater(session, async (huId, status) => {
-    try {
-      if (!updateHuStatusFn(loadedPlan, huId, status)) return;
-      await savePlanToDisk(projectDir, loadedPlan);
-    } catch (err) {
-      logger?.warn?.(`Live status update failed for ${huId}: ${err.message}`);
-    }
-  });
-  // PR3: per-HU outcome. Stamped once per HU at runSingleHu's exit
-  // so the board can show the 📄 indicator as soon as each HU
-  // finishes (iterations / duration / commits / blockers / summary).
-  //
-  // Cost D (KJC-TSK-0515): the outcome may carry `cost_usd` (USD
-  // spent on this HU). When present and finite, also persist it to
-  // board.db so the per-card badge (Cost F) and the project total
-  // chip (Cost G) have data to show — without this write, the
-  // `cost_usd` column would always stay NULL and the UI would render
-  // nothing. Lazy-import to keep the pre-loop phase free of board
-  // deps until we actually need them.
-  setLiveOutcomeUpdater(session, async (huId, outcome) => {
-    try {
-      if (!setHuOutcomeFn(loadedPlan, huId, outcome)) return;
-      keepRoutingMetrics(loadedPlan, huId, outcome); // KJC-TSK-0702: the measured fields core does not keep
-      await savePlanToDisk(projectDir, loadedPlan);
-      if (outcome && Number.isFinite(outcome.cost_usd)) {
-        try {
-          const { ensureDb, setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
-          ensureDb(); // KJC-BUG-0090: autorun/run may not have started the board
-          setStoryCost(huId, outcome.cost_usd);
-          // Φ0-G (KJC-TSK-0525): cached/in tokens travel in the same
-          // outcome blob as cost. Write them together so the board
-          // can render the "🎯 N% cached" badge on the same render.
-          // Either may be null (older runs, no cache) — setter handles it.
-          if (Number.isFinite(outcome.cached_tokens) || Number.isFinite(outcome.tokens_in)) {
-            setStoryCachedTokens(
-              huId,
-              Number.isFinite(outcome.cached_tokens) ? outcome.cached_tokens : null,
-              Number.isFinite(outcome.tokens_in) ? outcome.tokens_in : null,
-            );
-          }
-        } catch (err) {
-          logger?.warn?.(`Cost write failed for ${huId}: ${err.message}`);
-        }
-      }
-    } catch (err) {
-      logger?.warn?.(`Live outcome update failed for ${huId}: ${err.message}`);
-    }
-  });
-}
-
-/**
- * Resuelve una referencia humana a HU al `id` canónico largo. Acepta:
- *   - id largo exacto: `hu_<planId>_<NNN>` → match directo.
- *   - short_id: `INFRA-001`, `AUTH-SIGNUP` → match case-insensitive contra hu.short_id.
- *   - sufijo numérico: `001` → match contra hu.id terminado en `_001`.
- * Devuelve el hu.id largo o null si no resuelve.
- *
- * @param {string} ref
- * @param {Array<{id: string, short_id?: string|null}>} hus
- * @returns {string|null}
- */
-function resolveHuRef(ref, hus) {
-  if (!ref || !Array.isArray(hus)) return null;
-  // Match exacto contra id largo (camino caliente).
-  const exact = hus.find((s) => s.id === ref);
-  if (exact) return exact.id;
-  // Match case-insensitive contra short_id.
-  const lower = ref.toLowerCase();
-  const byShort = hus.find((s) => s.short_id && String(s.short_id).toLowerCase() === lower);
-  if (byShort) return byShort.id;
-  // Match por sufijo numérico (`001` → cualquier hu cuyo id termine en `_001`).
-  if (/^\d+$/.test(ref)) {
-    const padded = ref.padStart(3, "0");
-    const bySuffix = hus.find((s) => s.id.endsWith(`_${padded}`));
-    if (bySuffix) return bySuffix.id;
-  }
-  return null;
-}
-
-/**
- * Build a single plannedTask string for the non-HU / fallback
- * iteration path. The HU sub-pipeline doesn't read this; only the
- * legacy single-iteration loop does. Identical to the inlined
- * version's behaviour.
- */
-function buildPlannedTaskFromLoadedPlan({ task, loadedPlan }) {
-  const plan = loadedPlan.plan || (loadedPlan.approach ? { approach: loadedPlan.approach } : null);
-  if (plan && typeof plan === "object" && plan.steps) {
-    const stepList = plan.steps.map((s, idx) => `${idx + 1}. ${s.description || s}`).join("\n");
-    return `${task}\n\n## Implementation Plan\n${plan.approach || ""}\n\n## Steps\n${stepList}`;
-  }
-  if (typeof plan === "string") {
-    return `${task}\n\n## Implementation Plan\n${plan}`;
-  }
-  if (loadedPlan.approach) {
-    return `${task}\n\n## Approach\n${loadedPlan.approach}`;
-  }
-  return task;
-}