@karajan-family/code 4.21.0

package/src/plan/plan-reviewer.js

@@ -0,0 +1,236 @@
+/**
+ * Plan reviewer — third pass after `kj plan` (PR D of the v2.7.5
+ * tests-first roadmap). Asks the planner LLM five concrete
+ * questions about the plan it just produced. Returns structured
+ * findings, NOT free-form prose.
+ *
+ * The questions are intentionally closed-ended:
+ *
+ *   1. **Missing HUs** — sections of the SPEC the plan doesn't cover.
+ *      (Catches "the planner forgot module X".)
+ *   2. **Missing dependencies** — pairs of HUs that should have a
+ *      `blocked_by` edge but don't.
+ *      (Catches "HU 4 needs the schema HU 2 produces".)
+ *   3. **Scope overlap** — pairs of HUs that touch the same scope.
+ *      (Catches "the planner split one piece of work into two HUs
+ *      that step on each other".)
+ *   4. **Parallelisable** — sets of HUs that have no inter-deps and
+ *      could run side-by-side.
+ *      (Surface for the user, not auto-applied — `kj run --plan`
+ *      runs serially today.)
+ *   5. **Order issues** — HUs whose `blocked_by` chain is wrong or
+ *      circular.
+ *
+ * The output is purely advisory. The reviewer NEVER edits the plan.
+ * It reports findings; the user decides whether to apply them via
+ * the board's edit modal or another `kj plan` pass.
+ *
+ * Free-form "could we add logging?" suggestions are explicitly out
+ * of scope to avoid scope-creep noise — see the prompt rules.
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+/**
+ * Build the focused review prompt. Exported for unit-testing the
+ * shape without an LLM in the loop.
+ *
+ * @param {object} args
+ * @param {string} args.task
+ * @param {Array<object>} args.hus
+ * @returns {string}
+ */
+export function buildReviewerPrompt({ task, hus }) {
+  const huSummary = hus.map((h, i) => {
+    const deps = Array.isArray(h.blocked_by) && h.blocked_by.length > 0
+      ? ` ← blocked_by: ${h.blocked_by.join(", ")}`
+      : "";
+    const spec = h.spec_section ? ` [§${h.spec_section}]` : "";
+    return `${i + 1}. ${h.id}${spec}: ${h.title || "(untitled)"}${deps}\n   scope: ${h.scope || "(none)"}`;
+  }).join("\n\n");
+
+  return [
+    "You previously generated an implementation plan for the task below.",
+    "Your ONLY job in this call is to review it against five specific questions.",
+    "DO NOT propose new features, logging, monitoring, refactors, or anything",
+    "beyond what the SPEC explicitly requires. We're checking the plan for",
+    "completeness and correctness — NOT improving its scope.",
+    "",
+    "Output MUST be a JSON object with this exact shape:",
+    "",
+    "```json",
+    "{",
+    '  "missing_hus": [',
+    '    { "spec_section": "<section ref or short description>", "rationale": "<why it should exist>" }',
+    "  ],",
+    '  "missing_dependencies": [',
+    '    { "from": "<huId that should depend on>", "on": "<huId>", "rationale": "<why>" }',
+    "  ],",
+    '  "scope_overlaps": [',
+    '    { "between": ["<huId>", "<huId>"], "rationale": "<why they overlap>" }',
+    "  ],",
+    '  "parallelisable_groups": [',
+    '    { "his": ["<huId>", "<huId>"], "rationale": "<why these can run side-by-side>" }',
+    "  ],",
+    '  "order_issues": [',
+    '    { "hus": ["<huId>"], "issue": "<wrong order | circular | other>", "rationale": "<why>" }',
+    "  ],",
+    '  "summary": "<one sentence overall verdict>"',
+    "}",
+    "```",
+    "",
+    "Rules:",
+    "- Each array can be empty if there's nothing to flag for that question.",
+    "- Reference HUs by their EXACT id from the list below.",
+    "- Suggest at MOST 5 entries per array — only the most important ones.",
+    "- DO NOT propose tests / acceptance criteria — those are handled by other roles.",
+    "- DO NOT suggest renames / cosmetic changes — only structural issues.",
+    "- Return ONLY the JSON — no prose, no markdown fences around it.",
+    "",
+    "## Original Task",
+    task,
+    "",
+    "## Plan to review",
+    "",
+    huSummary,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Run the focused review pass.
+ *
+ * Pure-function side: parses the LLM JSON and normalises the shape
+ * (missing arrays default to `[]`, summary defaults to `""`). Junk
+ * entries (missing required fields) are dropped silently.
+ *
+ * @param {object} args
+ * @param {object} args.agent
+ * @param {string} args.task
+ * @param {Array<object>} args.hus
+ * @param {Function} [args.onOutput]
+ * @param {number} [args.silenceTimeoutMs]
+ * @param {number} [args.timeoutMs]
+ * @returns {Promise<{ ok: boolean, findings?: object, error?: string }>}
+ */
+export async function reviewPlan({ agent, task, hus, onOutput, silenceTimeoutMs, timeoutMs, emitter, eventBase, logger }) {
+  if (!Array.isArray(hus) || hus.length === 0) {
+    return { ok: true, findings: emptyFindings("Plan has no HUs to review.") };
+  }
+  const prompt = buildReviewerPrompt({ task, hus });
+  const runArgs = { prompt, role: "planner" };
+  if (onOutput) runArgs.onOutput = onOutput;
+  if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
+  if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+
+  // KJC-TSK-0413: el caso real del 2026-05-16 (plan-fix iter 2 "failed
+  // 219.3s" sin clase) entraba aquí. Ahora Brain clasifica el fallo y
+  // decide retry/standby/hibernate/abort.
+  const result = await withBrainRecovery({
+    agent, taskArgs: runArgs, role: "plan-reviewer",
+    emitter, eventBase, logger,
+  });
+  if (!result.ok) {
+    return { ok: false, error: result.error || `reviewer 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: "reviewer returned no JSON object" };
+  }
+  return { ok: true, findings: normaliseFindings(parsed) };
+}
+
+function emptyFindings(summary) {
+  return {
+    missing_hus: [],
+    missing_dependencies: [],
+    scope_overlaps: [],
+    parallelisable_groups: [],
+    order_issues: [],
+    summary: summary || "",
+  };
+}
+
+/**
+ * Coerce the raw LLM payload into the canonical shape. Each list is
+ * filtered to keep only entries with the required fields populated.
+ * @param {object} raw
+ */
+function normaliseFindings(raw) {
+  const f = emptyFindings(typeof raw.summary === "string" ? raw.summary : "");
+  if (Array.isArray(raw.missing_hus)) {
+    f.missing_hus = raw.missing_hus
+      .filter((m) => m && (m.spec_section || m.section || m.title) && m.rationale)
+      .map((m) => ({
+        spec_section: String(m.spec_section || m.section || m.title),
+        rationale: String(m.rationale),
+      }));
+  }
+  if (Array.isArray(raw.missing_dependencies)) {
+    f.missing_dependencies = raw.missing_dependencies
+      .filter((d) => d && d.from && d.on && d.rationale)
+      .map((d) => ({ from: String(d.from), on: String(d.on), rationale: String(d.rationale) }));
+  }
+  if (Array.isArray(raw.scope_overlaps)) {
+    f.scope_overlaps = raw.scope_overlaps
+      .filter((o) => o && Array.isArray(o.between) && o.between.length >= 2 && o.rationale)
+      .map((o) => ({ between: o.between.map(String), rationale: String(o.rationale) }));
+  }
+  if (Array.isArray(raw.parallelisable_groups)) {
+    f.parallelisable_groups = raw.parallelisable_groups
+      .filter((g) => g && Array.isArray(g.hus) && g.hus.length >= 2)
+      .map((g) => ({ hus: g.hus.map(String), rationale: g.rationale ? String(g.rationale) : "" }));
+  }
+  if (Array.isArray(raw.order_issues)) {
+    f.order_issues = raw.order_issues
+      .filter((o) => o && Array.isArray(o.hus) && o.hus.length >= 1 && o.issue)
+      .map((o) => ({ hus: o.hus.map(String), issue: String(o.issue), rationale: o.rationale ? String(o.rationale) : "" }));
+  }
+  return f;
+}
+
+/**
+ * Flatten findings into a count of actionable items (for the CLI
+ * banner: "Reviewer found 3 issues.").
+ */
+export function findingsCount(findings) {
+  if (!findings) return 0;
+  return (
+    (findings.missing_hus?.length || 0)
+    + (findings.missing_dependencies?.length || 0)
+    + (findings.scope_overlaps?.length || 0)
+    + (findings.order_issues?.length || 0)
+    // parallelisable_groups is informational, not an issue.
+  );
+}
+
+/**
+ * KJC-BUG-0054: count findings categorised por prioridad, para que
+ * el self-fix convergence guard pueda distinguir "regresión genuina"
+ * de "regresión por arreglar algo importante".
+ *
+ * Categorías:
+ *   - priority: ciclos (order_issues con issue=='circular') + missing_hus.
+ *     Estos NO pueden ignorarse — un ciclo deja el plan no ejecutable;
+ *     una HU faltante es feature missing.
+ *   - secondary: missing_dependencies + scope_overlaps + order_issues
+ *     no-circulares. Importantes pero recuperables.
+ *
+ * @param {object} findings
+ * @returns {{ priority: number, secondary: number, total: number, cycles: number }}
+ */
+export function findingsCountByType(findings) {
+  if (!findings) return { priority: 0, secondary: 0, total: 0, cycles: 0 };
+  const orderIssues = findings.order_issues || [];
+  const cycles = orderIssues.filter(
+    (i) => i && typeof i === "object" && i.issue === "circular"
+  ).length;
+  const orderNonCircular = orderIssues.length - cycles;
+  const missingHus = findings.missing_hus?.length || 0;
+  const missingDeps = findings.missing_dependencies?.length || 0;
+  const overlaps = findings.scope_overlaps?.length || 0;
+  const priority = cycles + missingHus;
+  const secondary = missingDeps + overlaps + orderNonCircular;
+  return { priority, secondary, total: priority + secondary, cycles };
+}

package/src/plan/plan-schema.js

@@ -0,0 +1,334 @@
+/**
+ * Plan v2 schema: plans with embedded HUs.
+ * v1 = text-only plans (approach + steps + risks)
+ * v2 = plans + executable HUs with acceptance tests
+ */
+
+import { generatePlanId } from "./plan-id.js";
+
+const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
+// KJC-TSK-0394 step 5: el modelo CANONICAL del lifecycle es
+// {pending, running, done}. Los valores certified/coding/reviewing/
+// failed/blocked/needs_context se mantienen como LEGACY (siguen
+// aceptados por validatePlan para no romper plans existentes ni el
+// runtime actual). El cleanup definitivo del runtime queda como
+// follow-up; mientras tanto la UI puede usar canonicalStatus +
+// effectiveResult para presentar el modelo de 3 estados sin tocar
+// la persistencia.
+//
+// needs_context se PATCHeaba vía /api/stories/:id (dropdown libre del
+// modal) sin que el enum lo aceptara → `kj plan validate` daba
+// false-negative tras un set manual. Incluido aquí para alinear.
+const VALID_HU_STATUSES = new Set([
+  // Canonical
+  "pending", "running", "done",
+  // Legacy
+  "certified", "coding", "reviewing", "failed", "blocked", "needs_context",
+]);
+export const CANONICAL_HU_STATUSES = new Set(["pending", "running", "done"]);
+// KJC-TSK-0394: nuevo campo `result` ortogonal a status. Reemplaza la
+// sobrecarga semántica del status (certified=pass, failed=fail) por una
+// distinción explícita entre lifecycle (status) y último resultado (result).
+// Vacío `null` significa "nunca ejecutado". Migración no-breaking: status
+// legacy sigue válido durante el período de transición.
+// Nota: usamos `result` y NO `outcome` porque el campo `outcome` ya existe
+// con otra semántica (blob JSON con iterations/duration/commits del run).
+export const VALID_HU_RESULTS = new Set([null, "pass", "fail", "partial"]);
+const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "nocode"]);
+const VALID_TEST_TYPES = new Set(["shell", "gherkin"]);
+
+/**
+ * KJC-TSK-0394 step 4: deduce `result` de un HU legacy. Idempotente.
+ * Heurística: done→pass (si hubiera fallado estaría en failed),
+ * failed→fail, resto→null. NO toca status (eso es step 5).
+ */
+export function inferResultFromLegacyStatus(hu) {
+  if (hu && hu.result != null) return hu.result;
+  if (hu?.status === "done") return "pass";
+  if (hu?.status === "failed") return "fail";
+  return null;
+}
+
+/**
+ * KJC-TSK-0394 step 5: mapea cualquier status (legacy o canonical) al
+ * modelo CANONICAL {pending, running, done}. Permite que la UI y los
+ * agregados (counts, kanban columns) trabajen contra un enum pequeño
+ * sin tener que conocer todas las variantes legacy.
+ *
+ *   certified | blocked | needs_context | pending → pending
+ *   coding | reviewing | running                  → running
+ *   done | failed                                 → done
+ *
+ * `failed` mapea a `done` porque conceptualmente es lifecycle terminal
+ * — el "falló" lo lleva el campo `result` ortogonal (step 1). Lo mismo
+ * para `certified`: no es un lifecycle, es "ready to run" que en el
+ * modelo canónico vive como `pending` + acceptance_tests no vacío.
+ */
+export function canonicalStatus(status) {
+  switch (status) {
+    case "running":
+    case "coding":
+    case "reviewing":
+      return "running";
+    case "done":
+    case "failed":
+      return "done";
+    default:
+      return "pending";
+  }
+}
+
+/**
+ * KJC-TSK-0394 step 5: result "efectivo" para la UI. Si el HU tiene
+ * `result` poblado (plans migrados), lo usa directamente. Si no
+ * (plans legacy pre-migración), lo deduce del status — equivalente a
+ * inferResultFromLegacyStatus pero llamable directamente sobre cada
+ * HU al renderizar.
+ *
+ * Permite a la UI mostrar badges ✓/✗ en plans antiguos sin esperar a
+ * que el usuario corra `kj plan migrate-result`.
+ */
+export function effectiveResult(hu) {
+  if (!hu) return null;
+  if (hu.result !== undefined && hu.result !== null) return hu.result;
+  return inferResultFromLegacyStatus(hu);
+}
+
+/**
+ * Map a legacy status to (newStatus, result) pair. Used by addHu() defaults
+ * and by the migration script in step 4. Idempotent: re-mapping a value that
+ * is already in the canonical {pending, running, done} set keeps it.
+ *
+ * @param {string|null|undefined} legacy
+ * @returns {{ status: string, result: string|null }}
+ */
+export function mapLegacyStatusToResult(legacy) {
+  switch (legacy) {
+    case "pending":
+    case "blocked":         // blocked es lifecycle no terminal → pending
+    case "needs_context":   // ídem
+    case undefined:
+    case null:
+      return { status: "pending", result: null };
+    case "coding":
+    case "reviewing":
+    case "running":
+      return { status: "running", result: null };
+    case "certified":
+      return { status: "done", result: "pass" };
+    case "failed":
+      // KJC-TSK-0403: HU fallida vuelve a Pending con result=fail
+      // (no a Done) para que el usuario pueda relanzarla con el
+      // contexto del fallo previo (KJC-TSK-0404).
+      return { status: "pending", result: "fail" };
+    case "done":
+      return { status: "done", result: null }; // sin result conocido (raro)
+    default:
+      return { status: "pending", result: null };
+  }
+}
+
+/**
+ * Structured acceptance-test shape introduced in v2.7.5 (tests-first):
+ *
+ *   { type: "shell",   content: "<bash command>", file?: "<optional path>" }
+ *   { type: "gherkin", content: "Given …\nWhen …\nThen …", file?: "<optional path>" }
+ *
+ * Legacy entries (plain strings) are accepted by validatePlan and get
+ * normalised to `{ type: "shell", content: <string> }` at read time by
+ * `normaliseAcceptanceTest`. New plans MUST emit the structured form.
+ *
+ * Why two types: shell tests are executable as-is (a bash command that
+ * exits 0 on pass); gherkin tests are human-readable specs that the
+ * tester role translates into real code tests during `kj run` — they
+ * are the contract the coder is expected to satisfy.
+ *
+ * @param {unknown} entry
+ * @returns {{ type: string, content: string, file?: string } | null}
+ */
+export function normaliseAcceptanceTest(entry) {
+  if (entry == null) return null;
+  if (typeof entry === "string") {
+    const trimmed = entry.trim();
+    if (!trimmed) return null;
+    return { type: "shell", content: trimmed };
+  }
+  if (typeof entry === "object" && typeof entry.content === "string") {
+    const content = entry.content.trim();
+    if (!content) return null;
+    const type = VALID_TEST_TYPES.has(entry.type) ? entry.type : "shell";
+    const out = { type, content };
+    if (typeof entry.file === "string" && entry.file.trim()) out.file = entry.file.trim();
+    return out;
+  }
+  return null;
+}
+
+/**
+ * Normalise an array of raw acceptance_tests, dropping empties.
+ * @param {unknown[]} list
+ * @returns {{ type: string, content: string, file?: string }[]}
+ */
+export function normaliseAcceptanceTests(list) {
+  if (!Array.isArray(list)) return [];
+  return list.map(normaliseAcceptanceTest).filter(Boolean);
+}
+
+/**
+ * Check if a plan uses v2 schema (has version field + hus array).
+ */
+export function isPlanV2(plan) {
+  return plan?.version === 2 && Array.isArray(plan.hus);
+}
+
+/**
+ * Create an empty v2 plan.
+ * @param {string} task - original task description
+ * @param {object} [context] - research/architect/triage context
+ * @returns {object} v2 plan with empty hus array
+ */
+export function createPlanV2(task, context = {}) {
+  const planId = generatePlanId();
+  return {
+    planId,
+    // KJC-TSK humanización IDs: alias legible (ej "greta-app"). Se
+    // asigna en savePlan a partir de plan.name. El planId sigue
+    // siendo la ID canónica interna (timestamp+random), pero la CLI
+    // y el board prefieren el alias para mostrar y aceptan ambos
+    // como referencia (--plan greta-app o --plan plan-XXX-XX).
+    alias: null,
+    version: 2,
+    task,
+    name: null, // set by caller via deriveProjectName or manually
+    status: "draft",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    createdBy: "planner",
+    context: {
+      researchContext: context.researchContext || null,
+      architectContext: context.architectContext || null,
+      triageLevel: context.triageLevel || null,
+      domain: context.domain || null
+    },
+    approach: null,
+    risks: [],
+    outOfScope: [],
+    hus: []
+  };
+}
+
+/**
+ * Migrate a v1 plan to v2 schema. Preserves all existing data.
+ * v1 plans have no HUs — they become v2 with empty hus array.
+ * @param {object} v1plan
+ * @returns {object} v2 plan
+ */
+export function migratePlanV1toV2(v1plan) {
+  if (isPlanV2(v1plan)) return v1plan; // already v2
+  return {
+    planId: v1plan.planId,
+    version: 2,
+    task: v1plan.task || null,
+    name: null,
+    status: "draft",
+    createdAt: v1plan.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    createdBy: "migrated",
+    context: {
+      researchContext: v1plan.researchContext || null,
+      architectContext: v1plan.architectContext || null,
+      triageLevel: null,
+      domain: null
+    },
+    approach: v1plan.plan?.approach || (typeof v1plan.plan === "string" ? v1plan.plan : null),
+    risks: v1plan.plan?.risks || [],
+    outOfScope: v1plan.plan?.outOfScope || [],
+    hus: [],
+    _v1: { raw: v1plan.raw, plan: v1plan.plan } // preserve original for reference
+  };
+}
+
+/**
+ * Validate a v2 plan. Returns { valid: true } or { valid: false, errors: string[] }.
+ */
+export function validatePlan(plan) {
+  const errors = [];
+
+  if (!plan.planId) errors.push("Missing planId");
+  if (plan.version !== 2) errors.push(`Expected version 2, got ${plan.version}`);
+  if (!plan.task) errors.push("Missing task");
+  if (!VALID_PLAN_STATUSES.has(plan.status)) errors.push(`Invalid status: ${plan.status}`);
+  if (!Array.isArray(plan.hus)) errors.push("hus must be an array");
+
+  const huIds = new Set();
+  for (const hu of plan.hus || []) {
+    if (!hu.id) { errors.push("HU missing id"); continue; }
+    if (huIds.has(hu.id)) errors.push(`Duplicate HU id: ${hu.id}`);
+    huIds.add(hu.id);
+    if (!hu.title) errors.push(`HU ${hu.id}: missing title`);
+    if (!VALID_HU_STATUSES.has(hu.status)) errors.push(`HU ${hu.id}: invalid status ${hu.status}`);
+    // KJC-TSK-0394: result es opcional. Si está presente, debe ser pass/fail/partial.
+    if (hu.result !== undefined && hu.result !== null && !VALID_HU_RESULTS.has(hu.result)) {
+      errors.push(`HU ${hu.id}: invalid result ${hu.result} (expected pass|fail|partial|null)`);
+    }
+    if (hu.task_type && !VALID_TASK_TYPES.has(hu.task_type)) errors.push(`HU ${hu.id}: invalid task_type ${hu.task_type}`);
+    // acceptance_tests: may be absent (legacy) or an array of either
+    // plain strings (legacy shell) or { type, content, file? } objects.
+    if (hu.acceptance_tests !== undefined) {
+      if (!Array.isArray(hu.acceptance_tests)) {
+        errors.push(`HU ${hu.id}: acceptance_tests must be an array`);
+      } else {
+        hu.acceptance_tests.forEach((entry, idx) => {
+          if (typeof entry === "string") return; // legacy form — OK
+          if (!entry || typeof entry !== "object") {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}] must be a string or { type, content } object`);
+            return;
+          }
+          if (entry.type && !VALID_TEST_TYPES.has(entry.type)) {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}].type must be one of ${[...VALID_TEST_TYPES].join("|")}`);
+          }
+          if (typeof entry.content !== "string" || !entry.content.trim()) {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}].content must be a non-empty string`);
+          }
+        });
+      }
+    }
+    // Check blocked_by references exist
+    for (const dep of hu.blocked_by || []) {
+      if (!huIds.has(dep) && !(plan.hus || []).some(h => h.id === dep)) {
+        errors.push(`HU ${hu.id}: blocked_by references unknown HU ${dep}`);
+      }
+    }
+  }
+
+  // Check for circular dependencies
+  try {
+    topoSort(plan.hus || []);
+  } catch {
+    errors.push("Circular dependency detected in HU blocked_by graph");
+  }
+
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}
+
+/** Simple topological sort for cycle detection. */
+function topoSort(hus) {
+  const visited = new Set();
+  const visiting = new Set();
+  const order = [];
+  const map = new Map(hus.map(h => [h.id, h]));
+
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) throw new Error("cycle");
+    visiting.add(id);
+    const hu = map.get(id);
+    for (const dep of hu?.blocked_by || []) visit(dep);
+    visiting.delete(id);
+    visited.add(id);
+    order.push(id);
+  }
+
+  for (const hu of hus) visit(hu.id);
+  return order;
+}