@karajan-family/code 4.21.0

package/src/plan/adr-generator.js

@@ -0,0 +1,170 @@
+/**
+ * Architecture Decision Records (ADRs) — distill the architect role's
+ * tradeoffs[] output into the canonical "Context · Decision ·
+ * Consequences · Status" markdown format.
+ *
+ * Why ADRs as a first-class artifact (v2.7.5):
+ *   - The architect already analyses the task and produces a
+ *     `tradeoffs[]` list with `{ decision, rationale, alternatives }`.
+ *     That data is exactly what an ADR captures, just unformatted.
+ *   - An ADR persists the WHY of an architectural choice. Coder and
+ *     reviewer in the next `kj run` can pull the active ADRs into
+ *     their prompt for context.
+ *   - It's also a deliverable in its own right — projects benefit
+ *     from a `docs/adr/` history regardless of Karajan.
+ *
+ * Storage: per-plan under `~/.kj/plans/<slug>/adrs/<adr-id>.md` (so
+ * an ADR's lifecycle matches its plan's). When the orchestrator runs
+ * a plan, the coder gets the ADRs as context. When a plan is removed
+ * (`kj plan delete`) the ADRs go with it.
+ *
+ * Format follows Michael Nygard's classic structure (the most widely
+ * adopted in the industry, used by GitHub, Spotify, AWS docs, etc.).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { plansDir } from "./plan-store.js";
+
+const VALID_ADR_STATUSES = new Set(["proposed", "accepted", "deprecated", "superseded"]);
+
+/**
+ * Slugify a decision title into a filesystem-safe ADR id fragment.
+ * "Use SQLite for plan storage" → "use-sqlite-for-plan-storage".
+ */
+function slugifyTitle(title) {
+  return String(title || "")
+    .toLowerCase()
+    // Decompose accents (NFD) then strip combining marks so "versión"
+    // → "version", keeping the ADR id ASCII-only and filesystem-safe.
+    .normalize("NFD")
+    .replaceAll(/[̀-ͯ]/g, "")
+    .replaceAll(/[^a-z0-9\s-]/g, "")
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "")
+    .slice(0, 80) || "untitled";
+}
+
+/**
+ * Turn the architect's `architecture.tradeoffs[]` into an array of
+ * ADR objects. Each tradeoff carries `{ decision, rationale,
+ * alternatives }`; we map them to the four ADR sections plus
+ * metadata.
+ *
+ * Numbering: 1-based, zero-padded to 4 digits ("0001-…"). Stable per
+ * call — callers should treat `id` as opaque (filename) and `number`
+ * as ordinal.
+ *
+ * @param {object} architecture - parsed architect output
+ * @param {object} [opts]
+ * @param {string} [opts.status] - default "accepted" (architect runs imply the decision is taken)
+ * @returns {Array<{ number: number, id: string, title: string, status: string,
+ *                   context: string, decision: string, consequences: string,
+ *                   alternatives: string[] }>}
+ */
+export function extractAdrsFromArchitecture(architecture, opts = {}) {
+  const tradeoffs = Array.isArray(architecture?.tradeoffs) ? architecture.tradeoffs : [];
+  const status = VALID_ADR_STATUSES.has(opts.status) ? opts.status : "accepted";
+  const adrs = [];
+  let n = 0;
+  for (const t of tradeoffs) {
+    if (!t || (typeof t !== "object" && typeof t !== "string")) continue;
+    const title = typeof t === "string" ? t : (t.decision || t.title || "");
+    if (!title.trim()) continue;
+    n += 1;
+    const number = n;
+    const slug = slugifyTitle(title);
+    const id = `${String(number).padStart(4, "0")}-${slug}`;
+    adrs.push({
+      number,
+      id,
+      title: title.trim(),
+      status,
+      context: typeof t === "object" && t.context ? String(t.context) : "",
+      decision: typeof t === "object" && t.decision ? String(t.decision) : title.trim(),
+      consequences: typeof t === "object" && t.rationale ? String(t.rationale) : "",
+      alternatives: typeof t === "object" && Array.isArray(t.alternatives) ? t.alternatives.map(String) : [],
+    });
+  }
+  return adrs;
+}
+
+/**
+ * Render an ADR to markdown using Nygard's format. Newline-stable so
+ * tests can do exact-match assertions.
+ *
+ * @param {object} adr
+ * @param {object} [opts]
+ * @param {Date} [opts.date]
+ * @returns {string}
+ */
+export function renderAdrMarkdown(adr, opts = {}) {
+  const date = (opts.date || new Date()).toISOString().slice(0, 10);   // YYYY-MM-DD
+  const lines = [
+    `# ${String(adr.number).padStart(4, "0")}. ${adr.title}`,
+    "",
+    `**Status:** ${adr.status}  `,
+    `**Date:** ${date}  `,
+    "",
+    "## Context",
+    "",
+    adr.context || "_(architect role did not provide an explicit context — see Decision below.)_",
+    "",
+    "## Decision",
+    "",
+    adr.decision,
+    "",
+  ];
+  if (adr.alternatives?.length > 0) {
+    lines.push("**Alternatives considered:**");
+    lines.push("");
+    for (const alt of adr.alternatives) lines.push(`- ${alt}`);
+    lines.push("");
+  }
+  lines.push(
+    "## Consequences",
+    "",
+    adr.consequences || "_(no consequences captured by the architect role.)_",
+    ""
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Write the ADRs to disk under the plan's adrs/ directory. Returns
+ * the list of absolute paths written so callers can surface them in
+ * the CLI output.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir
+ * @param {string} args.planId        - used to scope ADRs to a plan; falls
+ *                                      back to "_loose" when this came
+ *                                      from `kj architect` standalone
+ * @param {Array} args.adrs           - output of extractAdrsFromArchitecture
+ * @returns {Promise<string[]>} absolute paths written
+ */
+export async function writeAdrsToDisk({ projectDir, planId, adrs }) {
+  if (!Array.isArray(adrs) || adrs.length === 0) return [];
+  if (!projectDir) throw new Error("writeAdrsToDisk: projectDir is required");
+  const planSlug = planId || "_loose";
+  const dir = join(plansDir(projectDir), planSlug, "adrs");
+  await mkdir(dir, { recursive: true });
+  const paths = [];
+  for (const adr of adrs) {
+    const filePath = join(dir, `${adr.id}.md`);
+    await writeFile(filePath, renderAdrMarkdown(adr), "utf-8");
+    paths.push(filePath);
+  }
+  return paths;
+}
+
+/**
+ * Convenience: extract + write in one call. Used by `kj architect`
+ * and (later) the orchestrator's architect stage.
+ */
+export async function persistAdrsFromArchitecture({ projectDir, planId, architecture }) {
+  const adrs = extractAdrsFromArchitecture(architecture);
+  const paths = await writeAdrsToDisk({ projectDir, planId, adrs });
+  return { adrs, paths };
+}

package/src/plan/adr-loader.js

@@ -0,0 +1,60 @@
+/**
+ * Counterpart to `adr-generator.js`: reads back the persisted ADRs
+ * for a given plan so the coder / reviewer can pull them into their
+ * prompt context. PR F of the v2.7.5 multi-step planning roadmap.
+ *
+ * ADRs live at `~/.kj/plans/<slug>/<planId>/adrs/<id>.md` (per
+ * `adr-generator.js::writeAdrsToDisk`). On read we surface the raw
+ * markdown to the caller — they decide how much of it to render.
+ *
+ * Returns an empty array (not an error) when the directory doesn't
+ * exist: not every plan has ADRs (architect role is optional).
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { plansDir } from "./plan-store.js";
+
+/**
+ * @typedef {Object} Adr
+ * @property {string} id           - "0001-use-vitest"
+ * @property {string} markdown     - full file contents
+ */
+
+/**
+ * @param {string} projectDir
+ * @param {string|null} planId  - null falls back to the "_loose" bucket
+ *                                used by `kj architect` standalone
+ * @returns {Promise<Adr[]>}
+ */
+export async function loadActiveAdrs(projectDir, planId) {
+  if (!projectDir) return [];
+  const slug = planId || "_loose";
+  const dir = join(plansDir(projectDir), slug, "adrs");
+  let files;
+  try {
+    const s = await stat(dir);
+    if (!s.isDirectory()) return [];
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+  // Audit follow-up: was a sequential `for ... await readFile(...)`. ADRs
+  // are independent files; the loop has no inter-iteration state. Parallel
+  // reads cut typical 5-ADR loads from ~5 ms (sequential FS RTT) to a
+  // single ~1 ms burst, and the cost grows with ADR count. Filter the
+  // markdown files first so we don't fire reads against junk.
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  const settled = await Promise.all(
+    mdFiles.map(async (file) => {
+      try {
+        const md = await readFile(join(dir, file), "utf-8");
+        return { id: file.replace(/\.md$/, ""), markdown: md };
+      } catch { return null; /* skip unreadable file */ }
+    })
+  );
+  const adrs = settled.filter(Boolean);
+  // Numeric prefix in id ("0001-…") sorts naturally.
+  adrs.sort((a, b) => a.id.localeCompare(b.id));
+  return adrs;
+}

package/src/plan/plan-executor.js

@@ -0,0 +1,100 @@
+/**
+ * Plan Executor — bridge between v2 plans and hu-sub-pipeline.
+ * Converts plan.hus into the format expected by runHuSubPipeline,
+ * and syncs execution results back to the plan file.
+ */
+
+import { isPlanV2 } from "./plan-schema.js";
+import { updateHuStatus, updateHu, computePlanOutcome, setPlanOutcome } from "./plan-hu-ops.js";
+
+/**
+ * Convert a v2 plan's HUs into the stageResults.huReviewer format
+ * expected by needsSubPipeline + runHuSubPipeline.
+ * @param {object} plan - v2 plan with plan.hus
+ * @returns {object} { ok, stories, total, certified, batchSessionId, planId }
+ */
+export function planToHuBatch(plan) {
+  if (!isPlanV2(plan) || !plan.hus?.length) {
+    return { ok: false, stories: [], total: 0, certified: 0 };
+  }
+
+  const stories = plan.hus.map(hu => ({
+    id: hu.id,
+    title: hu.title,
+    task_type: hu.task_type || "sw",
+    status: hu.status === "certified" ? "certified" : hu.status,
+    blocked_by: hu.blocked_by || [],
+    // KJC-BUG-0110: scope must survive as its own field — the parallel
+    // scheduler treats a scopeless story as exclusive, so dropping it
+    // silently degrades --parallel N to sequential.
+    scope: hu.scope || null,
+    certified: { text: hu.scope || hu.title },
+    acceptance_criteria: hu.acceptance_criteria || [],
+    acceptance_tests: hu.acceptance_tests || [],
+    // PR F (v2.7.5): forward the SPEC section pointer into the story
+    // so the per-HU loop in flow-runner can hand it to the coder
+    // prompt without having to re-load the plan from disk.
+    spec_section: hu.spec_section || null,
+    original: { text: hu.scope || hu.title }
+  }));
+
+  const certified = stories.filter(s => s.status === "certified").length;
+
+  return {
+    ok: certified > 0,
+    stories,
+    total: stories.length,
+    certified,
+    batchSessionId: `plan-${plan.planId}`,
+    planId: plan.planId,
+    // PR F (v2.7.5): plan-wide reviewer findings ride along the batch
+    // so the coder can be told about issues that touch its HU. The
+    // shape mirrors plan-reviewer.js output (missing_dependencies,
+    // scope_overlaps, order_issues, …) — null when the reviewer
+    // never ran for this plan.
+    review: plan.review || null,
+    auto_generated: false,
+    source: { plan: true, planId: plan.planId }
+  };
+}
+
+/**
+ * Sync execution results from hu-sub-pipeline back to the plan file.
+ * Updates each HU's status based on the sub-pipeline results.
+ * @param {object} plan - v2 plan (mutated in place)
+ * @param {object} subPipelineResult - { results: [{huId, approved}], blockedIds }
+ */
+export function syncResultsToPlan(plan, subPipelineResult) {
+  if (!isPlanV2(plan)) return;
+
+  // KJC-TSK-0403: status/result ortogonal. HU fallida queda en status=pending
+  // con result=fail (no status=failed) para que el usuario pueda relanzarla
+  // con el contexto del fallo previo. El plan se considera failed si CUALQUIER
+  // HU tiene result=fail.
+  for (const r of subPipelineResult.results || []) {
+    if (r.approved) {
+      updateHuStatus(plan, r.huId, "done");
+      updateHu(plan, r.huId, { result: "pass" });
+    } else {
+      updateHuStatus(plan, r.huId, "pending");
+      updateHu(plan, r.huId, { result: "fail" });
+    }
+  }
+
+  for (const blockedId of subPipelineResult.blockedIds || []) {
+    updateHuStatus(plan, blockedId, "blocked");
+  }
+
+  const allDone = plan.hus.every(h => h.status === "done");
+  const anyFailed = plan.hus.some(h => h.result === "fail");
+  plan.status = allDone ? "done" : anyFailed ? "failed" : "running";
+  plan.updatedAt = new Date().toISOString();
+
+  // PR3: stamp the plan-level rollup so the board can show the
+  // "Plan finalizado · X done · Y failed · Z blocked · D min" banner
+  // without recomputing it on every render. Built from the per-HU
+  // outcomes that hu-sub-pipeline already wrote on the way through.
+  const duration_ms = subPipelineResult.duration_ms ?? null;
+  const rollup = computePlanOutcome(plan, { duration_ms });
+  setPlanOutcome(plan, rollup);
+}

package/src/plan/plan-fixer.js

@@ -0,0 +1,192 @@
+/**
+ * Plan fixer (KJC-BUG-0045 / P4) — self-fix loop after plan-reviewer.
+ *
+ * The reviewer is flag-only by contract. This module asks the planner
+ * to PATCH the plan with the missing pieces and applies the patch
+ * in-process. Patch shape:
+ *   - additions:    new HUs (planner-step shape, id is auto-assigned)
+ *   - deps_to_add:  blocked_by edges to declare on existing HUs
+ *   - deletions:    HU ids to drop (used for overlap resolution)
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+import { addHu } from "./plan-hu-ops.js";
+import { normaliseAcceptanceTests } from "./plan-schema.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+export function buildFixerPrompt({ task, hus, findings }) {
+  const huSummary = hus.map((h) => {
+    const deps = Array.isArray(h.blocked_by) && h.blocked_by.length > 0
+      ? ` ← blocked_by: ${h.blocked_by.join(", ")}` : "";
+    return `- ${h.id}: ${h.title || "(untitled)"}${deps}`;
+  }).join("\n");
+
+  const missingHus = (findings?.missing_hus || [])
+    .map(m => `  - §${m.spec_section}: ${m.rationale}`).join("\n");
+  const missingDeps = (findings?.missing_dependencies || [])
+    .map(d => `  - ${d.from} should be blocked_by ${d.on} (${d.rationale})`).join("\n");
+  const overlaps = (findings?.scope_overlaps || [])
+    .map(o => `  - ${o.between.join(" ↔ ")}: ${o.rationale}`).join("\n");
+
+  return [
+    "A reviewer flagged the issues listed under \"Findings\". Your ONLY",
+    "job is to PATCH the plan to fix EXACTLY those issues:",
+    "- missing_hus → MUST add one HU each",
+    "- missing_dependencies → MUST declare each edge",
+    "- scope_overlaps → MUST drop one of the pair or merge them",
+    "Do NOT propose new features outside the findings list. Do not add new",
+    "tests/logging/refactors. The fixer is scoped to the report ONLY.",
+    "",
+    "Output MUST be a JSON object:",
+    "```json",
+    "{",
+    '  "additions": [',
+    '    { "id": "<symbolic>", "description": "<sentence>",',
+    '      "spec_section": "<ref>", "dependencies": ["<huId>"],',
+    '      "acceptance_tests": [ { "type":"gherkin","content":"…" } ],',
+    '      "reuse": [] }',
+    "  ],",
+    '  "deps_to_add": [ { "huId": "<huId>", "on": "<huId>" } ],',
+    '  "deletions": [ "<huId>" ]',
+    "}",
+    "```",
+    "Reference existing HUs by exact id. Empty arrays OK. JSON only.",
+    "",
+    "## Original Task",
+    task,
+    "",
+    "## Current plan",
+    huSummary,
+    "",
+    "## Findings to address",
+    missingHus ? `### missing_hus (MUST add)\n${missingHus}` : "",
+    missingDeps ? `### missing_dependencies (MUST declare)\n${missingDeps}` : "",
+    overlaps ? `### scope_overlaps (MUST drop or merge)\n${overlaps}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+function normalisePatch(raw) {
+  const out = { additions: [], deps_to_add: [], deletions: [] };
+  if (!raw || typeof raw !== "object") return out;
+  if (Array.isArray(raw.additions)) {
+    out.additions = raw.additions
+      .filter(a => a && typeof a === "object" && typeof a.description === "string" && a.description.trim())
+      .map(a => ({
+        id: typeof a.id === "string" ? a.id.trim() : null,
+        description: String(a.description).trim(),
+        spec_section: typeof a.spec_section === "string" ? a.spec_section.trim() || null : null,
+        dependencies: Array.isArray(a.dependencies) ? a.dependencies.map(String) : [],
+        acceptance_tests: normaliseAcceptanceTests(a.acceptance_tests),
+        reuse: Array.isArray(a.reuse) ? a.reuse.map(String) : [],
+      }));
+  }
+  if (Array.isArray(raw.deps_to_add)) {
+    out.deps_to_add = raw.deps_to_add
+      .filter(d => d && typeof d.huId === "string" && typeof d.on === "string")
+      .map(d => ({ huId: d.huId.trim(), on: d.on.trim() }));
+  }
+  if (Array.isArray(raw.deletions)) {
+    out.deletions = raw.deletions.filter(d => typeof d === "string" && d.trim()).map(d => d.trim());
+  }
+  return out;
+}
+
+export async function applyReviewerFeedback({ agent, task, hus, findings, onOutput, silenceTimeoutMs, timeoutMs, emitter, eventBase, logger }) {
+  const prompt = buildFixerPrompt({ task, hus, findings });
+  const runArgs = { prompt, role: "planner" };
+  if (onOutput) runArgs.onOutput = onOutput;
+  if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
+  if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+  // KJC-TSK-0413: Brain Recovery — fix loop ya no muere silencioso.
+  const result = await withBrainRecovery({
+    agent, taskArgs: runArgs, role: "plan-fixer",
+    emitter, eventBase, logger,
+  });
+  if (!result.ok) return { ok: false, error: result.error || `fixer agent failed (${result.recovery?.class || "unknown"})`, recovery: result.recovery, action: result.action };
+  const parsed = extractFirstJson(result.output || "");
+  if (!parsed || typeof parsed !== "object") {
+    return { ok: false, error: "fixer returned no JSON object" };
+  }
+  return { ok: true, patch: normalisePatch(parsed) };
+}
+
+export function applyFixerPatch(plan, patch) {
+  const counts = { added: 0, depsAdded: 0, archived: 0 };
+  // KJC-TSK-0669 (absolute rule): HUs are NEVER deleted — not even by the
+  // fix loop. Overlap resolutions ARCHIVE in place (status skipped +
+  // provenance), so history survives and ids stay referenceable. The
+  // references are cleaned exactly like removeHu used to, because a
+  // skipped dependency never satisfies the scheduler (deadlock otherwise).
+  for (const huId of patch.deletions || []) {
+    const hu = plan.hus.find(h => h.id === huId);
+    if (!hu) continue;
+    if (hu.status !== "skipped") {
+      hu.status = "skipped";
+      hu.archived_by = "plan-reviewer";
+      hu.archive_reason = "scope overlap resolved by the plan-review fix loop";
+      hu.updatedAt = new Date().toISOString();
+      counts.archived += 1;
+    }
+    for (const other of plan.hus) {
+      if (other.id === huId) continue;
+      if (Array.isArray(other.blocked_by) && other.blocked_by.includes(huId)) {
+        other.blocked_by = other.blocked_by.filter(d => d !== huId);
+      }
+      if (Array.isArray(other.reuse) && other.reuse.includes(huId)) {
+        other.reuse = other.reuse.filter(d => d !== huId);
+      }
+    }
+  }
+  // KJC-BUG-0053: las HUs añadidas por el fixer dejaban `short_id` y
+  // `blocked_by` vacíos porque addHu no recibía esos campos. Resultado:
+  // HUs huérfanas con id largo críptico y sin orden de ejecución.
+  //
+  // Fix: (1) pasar `short_id: a.id` (el id simbólico que el fixer LLM
+  // asigna a cada addition). (2) resolver `a.dependencies` simbólicas
+  // → hu.id largos contra el plan ya existente + el mapa de símbolos
+  // recién añadidos. La resolución necesita 2 pasadas (primera crea
+  // las HUs y registra el mapping, segunda asigna deps) para que
+  // additions que se referencian entre sí funcionen.
+  const symbolicToHuId = new Map();
+  for (const hu of plan.hus) {
+    if (hu.short_id) symbolicToHuId.set(hu.short_id, hu.id);
+  }
+  const addedHus = []; // {hu, depsSymbolic}
+  for (const a of patch.additions || []) {
+    const symbolicId = typeof a.id === "string" && a.id.trim() ? a.id.trim() : null;
+    const hu = addHu(plan, {
+      title: (a.description || "").slice(0, 80),
+      scope: a.description,
+      short_id: symbolicId,
+      spec_section: a.spec_section,
+      acceptance_tests: a.acceptance_tests,
+      reuse: a.reuse || [],
+    });
+    hu.created_by = "plan-reviewer"; // KJC-TSK-0661: provenance stamp
+    if (symbolicId) symbolicToHuId.set(symbolicId, hu.id);
+    const depsSymbolic = Array.isArray(a.dependencies) ? a.dependencies : [];
+    addedHus.push({ hu, depsSymbolic });
+    counts.added += 1;
+  }
+  // Pasada 2: resolver deps simbólicas de las additions a ids largos.
+  for (const { hu, depsSymbolic } of addedHus) {
+    const resolved = depsSymbolic
+      .map((s) => typeof s === "string" ? symbolicToHuId.get(s.trim()) : null)
+      .filter(Boolean);
+    if (resolved.length > 0) hu.blocked_by = resolved;
+  }
+  const knownIds = new Set(plan.hus.map(h => h.id));
+  for (const { huId, on } of patch.deps_to_add || []) {
+    if (!knownIds.has(huId) || !knownIds.has(on)) continue;
+    const hu = plan.hus.find(h => h.id === huId);
+    if (!hu) continue;
+    const blocked = Array.isArray(hu.blocked_by) ? hu.blocked_by : [];
+    if (blocked.includes(on)) continue;
+    hu.blocked_by = [...blocked, on];
+    counts.depsAdded += 1;
+  }
+  if (counts.added + counts.depsAdded + counts.archived > 0) {
+    plan.updatedAt = new Date().toISOString();
+  }
+  return counts;
+}

package/src/plan/plan-hu-ops.js

@@ -0,0 +1,16 @@
+// Shim: plan-hu-ops now lives in karajan-core/plan-hu-ops so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR5.
+export {
+  addHu,
+  removeHu,
+  updateHu,
+  updateHuStatus,
+  setHuOutcome,
+  setPlanOutcome,
+  autoCertifyPendingHus,
+  assertPlanRunnable,
+  computePlanOutcome,
+  certifyAllHus,
+  reorderHus,
+} from "karajan-core/plan-hu-ops";

package/src/plan/plan-id.js

@@ -0,0 +1,4 @@
+// Shim: plan-id primitives now live in karajan-core/plan-id so the
+// hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR5.
+export { generatePlanId, generateHuId, normaliseAlias } from "karajan-core/plan-id";

package/src/plan/plan-migrate-result.js

@@ -0,0 +1,24 @@
+/**
+ * KJC-TSK-0394 step 4: migration helper para plan files existentes.
+ * Siembra `result` en las HUs vía inferResultFromLegacyStatus.
+ * Idempotente. NO toca `status` (eso será step 5).
+ */
+import { inferResultFromLegacyStatus } from "./plan-schema.js";
+
+/** Pura. Devuelve {plan: nuevo, changes: [...]}, sin mutar el input. */
+export function migratePlanResult(plan) {
+  if (!plan || !Array.isArray(plan.hus)) return { plan, changes: [] };
+  const changes = [];
+  const hus = plan.hus.map((hu) => {
+    // Sembrar explícito (incluso null) marca el HU como migrado para
+    // pasadas posteriores. hasOwnProperty distingue "no migrado" de
+    // "migrado a null".
+    const already = Object.prototype.hasOwnProperty.call(hu, "result") && hu.result !== undefined;
+    if (already) return hu;
+    const inferred = inferResultFromLegacyStatus(hu);
+    changes.push({ huId: hu.id, result: inferred });
+    return { ...hu, result: inferred };
+  });
+  if (changes.length === 0) return { plan, changes };
+  return { plan: { ...plan, hus, updatedAt: new Date().toISOString() }, changes };
+}