@karajan-family/code 4.21.0

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

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

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

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