@karajan-family/code 4.21.0

package/src/plan/plan-store.js

@@ -0,0 +1,260 @@
+/**
+ * Plan persistence — save, load, list, update, delete plans.
+ * Plans are stored at ~/.kj/plans/<projectSlug>/<planId>.json
+ * Supports v1 (text-only) and v2 (plans + HUs) schemas.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../utils/atomic-write.js";
+import { resolveHome } from "../utils/paths.js";
+import { getSharedPlansDir } from "../utils/shared-paths.js";
+import { generatePlanId, normaliseAlias } from "./plan-id.js";
+
+/**
+ * A plan JSON file failed to parse — typically an interrupted write
+ * leaves it truncated. Previously every read site swallowed this with
+ * a silent catch and the plan vanished from `kj plan list` and
+ * `kj plan load` as if it had never existed.
+ *
+ * Now: warn loudly so the user knows their plan is corrupt, and rename
+ * the file to `<name>.corrupt-<ts>` so it stops blocking subsequent
+ * reads of the same alias / planId (without destroying evidence).
+ * Best-effort: if the rename itself fails (read-only FS, permissions),
+ * we log and move on — never escalate to a throw, that would block the
+ * caller from reading the rest of the directory.
+ */
+async function handleCorruptPlanFile(filePath, error) {
+  const corruptPath = `${filePath}.corrupt-${Date.now()}`;
+  // eslint-disable-next-line no-console
+  console.warn(`[plan-store] Corrupt plan JSON at ${filePath}: ${error.message}`);
+  try {
+    await fs.rename(filePath, corruptPath);
+    // eslint-disable-next-line no-console
+    console.warn(`[plan-store] Renamed to ${path.basename(corruptPath)} so it stops blocking subsequent reads.`);
+  } catch (renameErr) {
+    // eslint-disable-next-line no-console
+    console.warn(`[plan-store] Could not rename ${filePath}: ${renameErr.message}`);
+  }
+}
+import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
+
+// Delegates to the unified resolver in src/utils/paths.js. PR 3 of
+// KJC-PCS-0047 flipped the default from `.kj` to `.karajan` — plans
+// now live under `~/.karajan/plans/`. The migrator (src/utils/
+// home-migration.js) auto-moves legacy `~/.kj/plans/` content on the
+// next `kj` invocation, so existing users are not stranded.
+export function getKjHome() {
+  return resolveHome({ defaultSegment: ".karajan" });
+}
+
+/**
+ * Deterministic slug for a project path — stable across plan-store writes,
+ * HU-board syncs and board URL routing. Keep in lockstep with
+ * `packages/hu-board/src/sync.js::deriveProjectIdFromDir`.
+ * @param {string} projectDir - absolute project path
+ * @returns {string}
+ */
+export function projectSlug(projectDir) {
+  return projectDir
+    .replace(/^\//, "")
+    .replace(/[/\\]/g, "_")
+    .replaceAll(/[^a-zA-Z0-9_.-]/g, "")
+    .slice(0, 120);
+}
+
+export function plansDir(projectDir) {
+  return path.join(getKjHome(), "plans", projectSlug(projectDir));
+}
+
+/**
+ * Save a plan to disk. Accepts both v1 and v2 schemas.
+ * @param {string} projectDir
+ * @param {object} planResult - v1 { task, plan, raw } or v2 { planId, version, hus, ... }
+ * @returns {Promise<string>} planId
+ */
+export async function savePlan(projectDir, planResult) {
+  const dir = plansDir(projectDir);
+  await fs.mkdir(dir, { recursive: true });
+
+  // v2 plans already have planId and full schema
+  if (isPlanV2(planResult)) {
+    const filePath = path.join(dir, `${planResult.planId}.json`);
+    planResult.updatedAt = new Date().toISOString();
+    // TSK-0341 / garbage-collector: stamp the absolute projectDir on every
+    // plan so the GC can check `fs.exists(projectDir)` reliably. Reverse-
+    // engineering it from the slug is lossy (underscores in the original
+    // name collide with underscores introduced by slash-substitution).
+    if (!planResult.projectDir && projectDir) planResult.projectDir = projectDir;
+    // Humanización IDs: si el plan no tiene alias todavía, derívalo de
+    // plan.name (lo que el planner pidió al usuario). Resuelve
+    // colisiones con sufijo -2, -3… leyendo el dir antes.
+    if (!planResult.alias && planResult.name) {
+      planResult.alias = await resolveUniqueAlias(dir, planResult.planId, normaliseAlias(planResult.name));
+    }
+    await writeJsonAtomic(filePath, planResult);
+    return planResult.planId;
+  }
+
+  // v1: generate planId and wrap
+  const planId = planResult.planId || generatePlanId();
+  const record = {
+    planId,
+    task: planResult.task || null,
+    researchContext: planResult.researchContext || null,
+    architectContext: planResult.architectContext || null,
+    plan: planResult.plan || null,
+    raw: planResult.raw || null,
+    createdAt: new Date().toISOString()
+  };
+
+  const filePath = path.join(dir, `${planId}.json`);
+  await writeJsonAtomic(filePath, record);
+  return planId;
+}
+
+/**
+ * Resuelve un alias único en `dir`. Si `base` ya está en uso por otro
+ * plan, intenta `base-2`, `base-3`… hasta encontrar libre.
+ * @param {string} dir
+ * @param {string} ownPlanId - planId del plan que se está guardando (su propio archivo se ignora en el lookup).
+ * @param {string|null} base
+ * @returns {Promise<string|null>}
+ */
+async function resolveUniqueAlias(dir, ownPlanId, base) {
+  if (!base) return null;
+  let files;
+  try { files = await fs.readdir(dir); } catch { return base; }
+  const taken = new Set();
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    const filePath = path.join(dir, f);
+    try {
+      const record = JSON.parse(await fs.readFile(filePath, "utf8"));
+      if (record.planId === ownPlanId) continue;
+      if (record.alias) taken.add(record.alias);
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
+  }
+  if (!taken.has(base)) return base;
+  for (let i = 2; i < 1000; i += 1) {
+    const candidate = `${base}-${i}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return `${base}-${ownPlanId.slice(-4)}`;  // fallback improbable
+}
+
+/**
+ * Load a plan by ID or alias. Auto-migrates v1 to v2 on read (lazy).
+ * Acepta tanto el planId canónico (plan-XXX-XX) como el alias humano
+ * (greta-app). Primero busca por filename exacto (planId.json), luego
+ * escanea el dir y matchea por alias.
+ *
+ * @returns {Promise<object|null>} v2 plan o null
+ */
+export async function loadPlan(projectDir, ref) {
+  if (!ref) return null;
+  // Local plans take precedence — if a teammate's shared copy and your
+  // working copy share a planId, your local edits win until you re-share.
+  const local = await loadPlanFromDir(plansDir(projectDir), ref);
+  if (local) return local;
+  // Fallback: shared plans committed by a teammate. KJC-PRP-0002 PR1.
+  return loadPlanFromDir(getSharedPlansDir(projectDir), ref);
+}
+
+async function loadPlanFromDir(dir, ref) {
+  // 1. Match exacto por planId.json (camino caliente).
+  const direct = path.join(dir, `${ref}.json`);
+  try {
+    const data = await fs.readFile(direct, "utf8");
+    const plan = JSON.parse(data);
+    if (!isPlanV2(plan)) return migratePlanV1toV2(plan);
+    return plan;
+  } catch (err) {
+    // ENOENT is expected (caller may have passed an alias, not a planId)
+    // → fall through to the alias scan. Anything else means the file is
+    // there but unreadable / corrupt; surface it instead of silently
+    // hiding the plan.
+    if (err.code !== "ENOENT") await handleCorruptPlanFile(direct, err);
+  }
+  // 2. Escaneo del dir por alias. Coste O(N) pero N suele ser <10.
+  let files;
+  try { files = await fs.readdir(dir); } catch { return null; }
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    const filePath = path.join(dir, f);
+    try {
+      const record = JSON.parse(await fs.readFile(filePath, "utf8"));
+      if (record.alias === ref || record.planId === ref) {
+        if (!isPlanV2(record)) return migratePlanV1toV2(record);
+        return record;
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
+  }
+  return null;
+}
+
+/**
+ * Delete a plan from disk.
+ * @returns {Promise<boolean>}
+ */
+export async function deletePlan(projectDir, planId) {
+  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List all plans for a project, sorted newest first.
+ */
+export async function listPlans(projectDir) {
+  const dir = plansDir(projectDir);
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const plans = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    if (file.includes(".corrupt-")) continue; // own renamed-aside files
+    const filePath = path.join(dir, file);
+    try {
+      const data = await fs.readFile(filePath, "utf8");
+      const record = JSON.parse(data);
+      plans.push({
+        planId: record.planId,
+        alias: record.alias || null,
+        task: record.task,
+        name: record.name || null,
+        status: record.status || "draft",
+        version: record.version || 1,
+        huCount: Array.isArray(record.hus) ? record.hus.length : 0,
+        createdAt: record.createdAt
+      });
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
+  }
+
+  plans.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+  return plans;
+}
+
+/**
+ * Get the most recent plan.
+ */
+export async function getLatestPlan(projectDir) {
+  const all = await listPlans(projectDir);
+  if (all.length === 0) return null;
+  return loadPlan(projectDir, all[0].planId);
+}

package/src/plan/plan-structural-pass.js

@@ -0,0 +1,122 @@
+// KJC-TSK-0399: deterministic post-review pass — cycles, orphan refs,
+// missing short_id. No LLM. Fix shape: { kind, huId?, ...details };
+// stored in plan.review.structural_fixes.
+
+export function runStructuralPass(plan) {
+  const fixes = [];
+  if (!plan || !Array.isArray(plan.hus) || plan.hus.length === 0) {
+    return { fixes, modified: false };
+  }
+  fixes.push(...removeOrphanRefs(plan));
+  fixes.push(...breakCycles(plan));
+  fixes.push(...assignMissingShortIds(plan));
+  const modified = fixes.length > 0;
+  if (modified) plan.updatedAt = new Date().toISOString();
+  return { fixes, modified };
+}
+
+export function removeOrphanRefs(plan) {
+  const fixes = [];
+  const known = new Set(plan.hus.map((h) => h.id));
+  for (const hu of plan.hus) {
+    const removed = [];
+    if (Array.isArray(hu.blocked_by) && hu.blocked_by.length > 0) {
+      hu.blocked_by = hu.blocked_by.filter((d) => {
+        if (known.has(d)) return true;
+        removed.push(d); return false;
+      });
+    }
+    if (removed.length > 0) fixes.push({ kind: "orphan_ref_removed", huId: hu.id, removed });
+  }
+  return fixes;
+}
+
+function breakCycles(plan) {
+  const fixes = [];
+  let cycles = findCycles(plan.hus);
+  let budget = plan.hus.length;
+  while (cycles.length > 0 && budget-- > 0) {
+    const cycle = cycles[0];
+    const dropped = breakCycle(plan, cycle);
+    if (!dropped) break;
+    fixes.push({ kind: "cycle_break", cycle: [...cycle], droppedEdge: dropped });
+    cycles = findCycles(plan.hus);
+  }
+  return fixes;
+}
+
+export function findCycles(hus) {
+  const graph = new Map();
+  for (const hu of hus) graph.set(hu.id, Array.isArray(hu.blocked_by) ? hu.blocked_by : []);
+  const cycles = [];
+  const seen = new Set();
+  const onStack = new Set();
+  const stack = [];
+  function dfs(node) {
+    onStack.add(node); stack.push(node); seen.add(node);
+    for (const dep of graph.get(node) || []) {
+      if (!graph.has(dep)) continue;
+      if (onStack.has(dep)) {
+        const idx = stack.indexOf(dep);
+        if (idx >= 0) {
+          const cycle = stack.slice(idx);
+          if (!cycles.some((c) => sameCycle(c, cycle))) cycles.push(cycle);
+        }
+      } else if (!seen.has(dep)) dfs(dep);
+    }
+    stack.pop(); onStack.delete(node);
+  }
+  for (const id of graph.keys()) if (!seen.has(id)) dfs(id);
+  return cycles;
+}
+
+function sameCycle(a, b) {
+  if (a.length !== b.length) return false;
+  return [...a].sort().join("|") === [...b].sort().join("|");
+}
+
+// Heurística: dropea arista cuyo origen tiene menos incoming. Tiebreak edge.to.
+export function breakCycle(plan, cycle) {
+  const incoming = new Map();
+  for (const hu of plan.hus) {
+    for (const dep of hu.blocked_by || []) incoming.set(dep, (incoming.get(dep) || 0) + 1);
+  }
+  const edges = [];
+  for (let i = 0; i < cycle.length; i++) {
+    const from = cycle[i];
+    const to = cycle[(i + 1) % cycle.length];
+    const hu = plan.hus.find((h) => h.id === from);
+    if (hu && Array.isArray(hu.blocked_by) && hu.blocked_by.includes(to)) edges.push({ from, to });
+  }
+  if (edges.length === 0) return null;
+  edges.sort((a, b) => {
+    const d = (incoming.get(a.from) || 0) - (incoming.get(b.from) || 0);
+    return d !== 0 ? d : a.to.localeCompare(b.to);
+  });
+  const drop = edges[0];
+  const hu = plan.hus.find((h) => h.id === drop.from);
+  hu.blocked_by = hu.blocked_by.filter((d) => d !== drop.to);
+  return drop;
+}
+
+export function assignMissingShortIds(plan) {
+  const fixes = [];
+  const used = new Set();
+  let maxAuto = 0;
+  for (const hu of plan.hus) {
+    if (!hu.short_id) continue;
+    used.add(hu.short_id);
+    const m = String(hu.short_id).match(/^AUTOFIX-(\d+)$/);
+    if (m) maxAuto = Math.max(maxAuto, Number(m[1]));
+  }
+  for (const hu of plan.hus) {
+    if (hu.short_id) continue;
+    maxAuto += 1;
+    const candidate = `AUTOFIX-${String(maxAuto).padStart(3, "0")}`;
+    if (used.has(candidate)) continue;
+    hu.short_id = candidate;
+    used.add(candidate);
+    fixes.push({ kind: "short_id_assigned", huId: hu.id, assigned: candidate });
+  }
+  return fixes;
+}

package/src/plan/plan-validation.js

@@ -0,0 +1,4 @@
+// Shim: plan-validation now lives in karajan-core/plan-validation so
+// the hu-board workspace can consume it without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR6.
+export { validateBlockedByChange } from "karajan-core/plan-validation";

package/src/plan/preflight-hu.js

@@ -0,0 +1,105 @@
+/**
+ * KJC-TSK-0397: auto-inject a [PREFLIGHT-000] HU at the top of every
+ * plan generated by `kj plan generate` so the sub-pipeline gates on a
+ * clean environment before burning tokens on functional HUs.
+ *
+ * Design points:
+ *   - Pure shell tests — no Karajan-specific runtime, just commands
+ *     that exit 0 when the environment is ready.
+ *   - Stack-aware: Node, Python and Firebase signals come straight
+ *     from detectProjectStack() + on-disk file probes. Adding a new
+ *     stack is one entry in `composePreflightTests`.
+ *   - Idempotent: re-running over a plan that already has a HU with
+ *     id `PREFLIGHT-000` or a title containing 'preflight' / 'verificar
+ *     entorno' returns the plan unchanged. Required because the same
+ *     planner output may flow through structural-pass + plan-fixer
+ *     before reaching savePlan.
+ *   - All other HUs' `blocked_by` get the PREFLIGHT-000 id appended
+ *     (unless they already have it, again idempotent). Their own
+ *     dependencies are preserved.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { detectProjectStack } from "../utils/stack-detect.js";
+
+const PREFLIGHT_ID = "PREFLIGHT-000";
+
+/**
+ * Compose stack-aware shell acceptance tests. Always includes a
+ * `git status --porcelain` clean-tree check; everything else is
+ * additive based on what the project actually uses.
+ */
+export function composePreflightTests(stack, projectDir = ".") {
+  const tests = [
+    { type: "shell", content: "git status --porcelain | (! grep -q .)" },
+  ];
+  const lang = stack?.language;
+  if (lang === "javascript" || lang === "typescript") {
+    tests.push({ type: "shell", content: "node --version | grep -qE '^v(2[0-9]|[3-9][0-9])'" });
+    if (existsSync(join(projectDir, "package.json"))) {
+      tests.push({ type: "shell", content: "npm install --no-audit --no-fund" });
+      tests.push({ type: "shell", content: "test -z \"$(npm run | grep -E '^  test$')\" || npm test" });
+      tests.push({ type: "shell", content: "test -z \"$(npm run | grep -E '^  lint$')\" || npm run lint" });
+    }
+  } else if (lang === "python") {
+    tests.push({ type: "shell", content: "python --version | grep -qE 'Python 3\\.(1[0-9]|[2-9][0-9])'" });
+    if (existsSync(join(projectDir, "requirements.txt"))) {
+      tests.push({ type: "shell", content: "pip install -r requirements.txt" });
+    } else if (existsSync(join(projectDir, "pyproject.toml"))) {
+      tests.push({ type: "shell", content: "test -f poetry.lock && poetry install || pip install -e ." });
+    }
+    tests.push({ type: "shell", content: "command -v pytest && pytest --collect-only || true" });
+  }
+  if (existsSync(join(projectDir, "firebase.json"))) {
+    tests.push({ type: "shell", content: "firebase projects:list" });
+  }
+  if (existsSync(join(projectDir, ".gcloudignore"))) {
+    tests.push({ type: "shell", content: "gcloud auth list --filter=status:ACTIVE --format='value(account)' | (! test -z \"$(cat)\")" });
+  }
+  return tests;
+}
+
+/**
+ * Return true when the plan already has a preflight-style HU (by id or
+ * title). Pattern-matches conservatively to avoid duplicate injection.
+ */
+export function hasPreflightHu(plan) {
+  if (!plan?.hus?.length) return false;
+  return plan.hus.some((hu) => {
+    if (hu.id === PREFLIGHT_ID) return true;
+    const title = (hu.title || hu.description || "").toLowerCase();
+    return title.includes("preflight-000") || title.includes("verificar entorno") || title.includes("preflight check");
+  });
+}
+
+/**
+ * Prepend a [PREFLIGHT-000] HU to the plan and append its id to the
+ * `blocked_by` of every other HU. Returns the mutated plan reference
+ * for convenience; mutation is in place so callers don't need to
+ * reassign. No-op when the plan already has a preflight HU.
+ */
+export async function prependPreflightHu(plan, projectDir) {
+  if (!plan?.hus) return plan;
+  if (hasPreflightHu(plan)) return plan;
+  const stack = await detectProjectStack(projectDir);
+  const preflight = {
+    id: PREFLIGHT_ID,
+    title: "[PREFLIGHT-000] Verificar entorno de desarrollo listo",
+    description: "[PREFLIGHT-000] Block functional HUs until the project's environment is reproducible: deps installed, build/test/lint passing, git tree clean, cloud auth ready when applicable.",
+    task_type: "infra",
+    // KJC-BUG-0108: without an explicit status, `kj plan ready` rejects the
+    // whole plan with "invalid status undefined".
+    status: "pending",
+    blocked_by: [],
+    reuse: [],
+    acceptance_tests: composePreflightTests(stack, projectDir),
+    spec_section: null,
+  };
+  for (const hu of plan.hus) {
+    if (!Array.isArray(hu.blocked_by)) hu.blocked_by = [];
+    if (!hu.blocked_by.includes(PREFLIGHT_ID)) hu.blocked_by.push(PREFLIGHT_ID);
+  }
+  plan.hus.unshift(preflight);
+  return plan;
+}

package/src/plan/spec-detector.js

@@ -0,0 +1,61 @@
+/**
+ * Detect numbered/sectioned headings in a task description so the
+ * planner prompt can demand `spec_section` per HU instead of leaving
+ * it as a soft "preferred" hint that LLMs ignore.
+ *
+ * Recognises three common shapes (kept intentionally narrow — false
+ * positives turn the planner prompt into noise):
+ *
+ *   ## 1. Overview              → section "1",   title "Overview"
+ *   ### 2.1 add                 → section "2.1", title "add"
+ *   ## §5 Initial Scope         → section "5",   title "Initial Scope"
+ *
+ * The matcher is anchored to markdown heading lines (`^#+`) so prose
+ * mentions of a number ("see version 4.2") never trigger detection.
+ *
+ * Returns `{ hasSpec, sections, sectionList }`:
+ *   - `hasSpec`     boolean — true when at least one heading matched.
+ *                   Prompt builders use this to switch language from
+ *                   "preferred" to "MUST".
+ *   - `sections`    string[] — bare section refs, dedup, in document
+ *                   order. e.g. ["1", "2", "2.1", "2.2", "3"].
+ *   - `sectionList` Array<{section, title}> — full list with titles
+ *                   so the prompt can echo the checklist back at the
+ *                   LLM. Keeps order, dedup by section ref.
+ *
+ * @param {string} text
+ * @returns {{ hasSpec: boolean, sections: string[], sectionList: Array<{section: string, title: string}> }}
+ */
+export function detectSpecSections(text) {
+  const empty = { hasSpec: false, sections: [], sectionList: [] };
+  if (!text || typeof text !== "string") return empty;
+
+  // Anchored to heading lines. Two regex shapes — numbered sections
+  // and §-prefixed sections — are both common in the wild.
+  //
+  //   ^#{1,6}\s*               ← markdown heading marker (any depth)
+  //   §?\s*                    ← optional "§"
+  //   (\d+(?:\.\d+){0,4})      ← section number, up to 5 levels deep
+  //   [.)]?\s+                 ← optional trailing "." or ")", then space
+  //   (.+?)\s*$                ← title (lazy, trim trailing whitespace)
+  const headingRe = /^#{1,6}\s*§?\s*(\d+(?:\.\d+){0,4})[.)]?\s+(.+?)\s*$/;
+
+  const seen = new Set();
+  const sectionList = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    const m = headingRe.exec(line);
+    if (!m) continue;
+    const section = m[1];
+    if (seen.has(section)) continue;
+    seen.add(section);
+    sectionList.push({ section, title: m[2].trim() });
+  }
+
+  if (sectionList.length === 0) return empty;
+  return {
+    hasSpec: true,
+    sections: sectionList.map((s) => s.section),
+    sectionList,
+  };
+}

package/src/plan/tests-synthesizer.js

@@ -0,0 +1,131 @@
+/**
+ * Tests-first second pass for `kj plan` (v2.7.5).
+ *
+ * The first planner call asks for steps + acceptance_tests in one
+ * shot. Modern LLMs (Claude, Codex) reliably produce the steps but
+ * frequently skip the acceptance_tests sub-instruction when the
+ * surrounding spec is dense — a known weakness of long single-shot
+ * prompts. Pre-v2.7.5 we papered over this with a generic `npx
+ * vitest run` placeholder that wasn't actually a per-HU contract.
+ *
+ * This module runs a focused SECOND pass that asks the LLM ONLY to
+ * fill in tests for the HUs that came back without them. Because the
+ * prompt is shorter and has a single deliverable, the hit rate is
+ * effectively 100% on the HUs that slipped through the first time.
+ *
+ * Returns a map `{ huId → acceptance_tests[] }` so the caller can
+ * patch the plan in place. The patch always normalises through
+ * `plan-schema::normaliseAcceptanceTests`, so any malformed entries
+ * the LLM produces are silently dropped (better than corrupting the
+ * plan with junk).
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+import { normaliseAcceptanceTests } from "./plan-schema.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+/**
+ * Build the focused-pass prompt asking ONLY for tests for the given
+ * HUs. Exported for unit-testing the prompt shape without an LLM.
+ *
+ * @param {object} args
+ * @param {string} args.task
+ * @param {Array<{ id: string, title?: string, scope?: string }>} args.husNeedingTests
+ * @returns {string}
+ */
+export function buildSynthesizerPrompt({ task, husNeedingTests, stack = null, testFramework = null }) {
+  const lines = [
+    "You previously generated an implementation plan for the task below, but some HUs were left without acceptance_tests.",
+    "Your ONLY job in this call is to fill that gap.",
+    "",
+    "Output MUST be a JSON object with this exact shape:",
+    "",
+    "```json",
+    "{",
+    '  "tests": {',
+    '    "<huId>": [',
+    '      { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+    '      { "type": "shell", "content": "<bash command that must exit 0>" }',
+    "    ]",
+    "  }",
+    "}",
+    "```",
+    "",
+    "Rules:",
+    "- The keys of `tests` are the HU ids EXACTLY as listed below.",
+    "- 2-4 tests per HU. At least one happy-path and one edge case.",
+    "- gherkin = behaviour spec; shell = concrete bash command exiting 0 on pass.",
+    "- Tests must be specific to the HU. Do NOT use generic fallbacks like `npx vitest run`.",
+    "- Tests must be writable BEFORE the HU is implemented (they should fail until done).",
+    "- Return ONLY the JSON — no prose, no markdown fences around it.",
+    "",
+  ];
+  // Stack-aware hint: tell the LLM what test framework / language to
+  // emit shell commands for. Without this it defaulted to vitest /
+  // npm even on Python / Go / Rust projects (sesgo-de-stack audit).
+  if (stack || testFramework) {
+    lines.push("## Project Stack — generate shell tests for THIS stack, not generic JS");
+    if (stack?.language) lines.push(`- Language: **${stack.language}**`);
+    if (stack?.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+    if (testFramework?.hasTests && testFramework?.framework) {
+      lines.push(`- Test framework already in use: **${testFramework.framework}** — use it for the shell commands.`);
+    } else if (stack?.language && stack.language !== "javascript" && stack.language !== "typescript") {
+      lines.push(`- Use the canonical test runner for ${stack.language} (pytest / go test / cargo test / rspec). Do NOT emit vitest, jest, or npm commands.`);
+    }
+    lines.push("");
+  }
+  lines.push("## Task", task, "", "## HUs that need acceptance_tests", "");
+  for (const hu of husNeedingTests) {
+    lines.push(`### ${hu.id}: ${hu.title || ""}`);
+    lines.push(hu.scope ? `Scope: ${hu.scope}` : "(no scope)");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Run the focused second pass. Pass an `agent` with a `runTask`
+ * method (Claude / Codex / Gemini wrappers all expose it).
+ *
+ * @param {object} args
+ * @param {object} args.agent
+ * @param {string} args.task
+ * @param {Array<{ id: string, title?: string, scope?: string }>} args.husNeedingTests
+ * @param {Function} [args.onOutput]
+ * @param {number} [args.silenceTimeoutMs]
+ * @param {number} [args.timeoutMs]
+ * @returns {Promise<{ ok: boolean, tests?: Record<string, object[]>, error?: string }>}
+ */
+export async function synthesizeMissingTests({ agent, task, husNeedingTests, onOutput, silenceTimeoutMs, timeoutMs, emitter, eventBase, logger }) {
+  if (!Array.isArray(husNeedingTests) || husNeedingTests.length === 0) {
+    return { ok: true, tests: {} };
+  }
+  const prompt = buildSynthesizerPrompt({ task, husNeedingTests });
+  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 wraps el agent call.
+  const result = await withBrainRecovery({
+    agent, taskArgs: runArgs, role: "tests-synthesizer",
+    emitter, eventBase, logger,
+  });
+  if (!result.ok) {
+    return { ok: false, error: result.error || `synthesizer agent failed (${result.recovery?.class || "unknown"})`, recovery: result.recovery, action: result.action };
+  }
+
+  const parsed = extractFirstJson(result.output || "");
+  const rawTests = parsed?.tests;
+  if (!rawTests || typeof rawTests !== "object") {
+    return { ok: false, error: "synthesizer returned no `tests` object" };
+  }
+
+  // Normalise per HU so junk entries don't slip into the plan.
+  const tests = {};
+  for (const [huId, list] of Object.entries(rawTests)) {
+    const cleaned = normaliseAcceptanceTests(list);
+    if (cleaned.length > 0) tests[huId] = cleaned;
+  }
+  return { ok: true, tests };
+}