karajan-code 2.7.3 → 2.8.0

package/src/orchestrator/verification-gate.js

@@ -1,7 +1,7 @@
 // Verification gate: checks whether the coder actually produced changes.
 // Prevents advancing the pipeline when coder iterations produce 0 file changes.
 
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 
 /**
  * @typedef {Object} VerificationResult
@@ -16,14 +16,20 @@ import { execSync } from "node:child_process";
 /**
  * Count files and lines changed since a base reference.
  * Uses git diff --numstat to get both file and line counts.
+ *
+ * Audit follow-up: was using execSync with template-string interpolation
+ * of `baseRef` and `projectDir`. Both come ultimately from session
+ * state / config — not user shell input — but the shape was a known
+ * shell-injection vector. Switched to execFileSync with arg arrays so
+ * no interpolation reaches /bin/sh.
  */
 export function countChangesSince(baseRef, projectDir = null) {
   try {
-    const scope = projectDir ? `-- ${projectDir}` : "";
-    const output = execSync(
-      `git diff --numstat ${baseRef} ${scope}`,
-      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
-    ).trim();
+    const args = ["diff", "--numstat", String(baseRef)];
+    if (projectDir) args.push("--", String(projectDir));
+    const output = execFileSync("git", args, {
+      encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
 
     if (!output) return { files: [], filesChanged: 0, linesAdded: 0, linesDeleted: 0 };
 
@@ -48,14 +54,16 @@ export function countChangesSince(baseRef, projectDir = null) {
 
 /**
  * Also count untracked files (new files not yet added to git).
+ *
+ * Audit follow-up: same execSync→execFileSync change as countChangesSince.
  */
 export function countUntrackedFiles(projectDir = null) {
   try {
-    const scope = projectDir || ".";
-    const output = execSync(
-      `git ls-files --others --exclude-standard ${scope}`,
-      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
-    ).trim();
+    const args = ["ls-files", "--others", "--exclude-standard"];
+    if (projectDir) args.push(String(projectDir));
+    const output = execFileSync("git", args, {
+      encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
 
     if (!output) return [];
     return output.split("\n").filter(Boolean);
@@ -111,7 +119,7 @@ export function verifyCoderOutput({ baseRef, projectDir = null, minFiles = 1, mi
 /**
  * Build a retry strategy based on the verification failure.
  */
-function buildRetryStrategy(filesChanged, linesChanged) {
+function buildRetryStrategy(filesChanged, _linesChanged) {
   if (filesChanged === 0) {
     return "Rephrase the feedback with explicit file paths. List specific files to create/modify. Include example code snippets.";
   }

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")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/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

@@ -5,7 +5,7 @@
  */
 
 import { isPlanV2 } from "./plan-schema.js";
-import { updateHuStatus } from "./plan-hu-ops.js";
+import { updateHuStatus, computePlanOutcome, setPlanOutcome } from "./plan-hu-ops.js";
 
 /**
  * Convert a v2 plan's HUs into the stageResults.huReviewer format
@@ -27,6 +27,10 @@ export function planToHuBatch(plan) {
     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 }
   }));
 
@@ -39,6 +43,12 @@ export function planToHuBatch(plan) {
     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 }
   };
@@ -66,4 +76,12 @@ export function syncResultsToPlan(plan, subPipelineResult) {
   const anyFailed = plan.hus.some(h => h.status === "failed");
   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-hu-ops.js

@@ -37,6 +37,12 @@ export function addHu(plan, huData) {
     scope: huData.scope || null,
     acceptance_criteria: huData.acceptance_criteria || [],
     acceptance_tests: huData.acceptance_tests || [],
+    // Spec mapping (v2.7.5 PR C): the SPEC.md section / heading this
+    // HU implements. Lets the coder cite "this implements SPEC §5.3"
+    // in PRs and the reviewer trace coverage gaps when the SPEC is
+    // re-read. Free-form string — typically "5.3", "§5.3 Initial
+    // Scope", or whatever the planner extracted from the source spec.
+    spec_section: huData.spec_section || null,
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString()
   };
@@ -71,7 +77,7 @@ export function removeHu(plan, huId) {
 export function updateHu(plan, huId, patch) {
   const hu = plan.hus.find(h => h.id === huId);
   if (!hu) return null;
-  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by"];
+  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "spec_section"];
   for (const key of allowed) {
     if (patch[key] !== undefined) hu[key] = patch[key];
   }
@@ -93,6 +99,169 @@ export function updateHuStatus(plan, huId, status) {
   return true;
 }
 
+/**
+ * Stamp the per-HU outcome — what actually happened during execution.
+ * Written ONCE per HU, at the end of runSingleHu in hu-sub-pipeline.
+ * Consumed by the board to render the per-HU summary indicator and
+ * by `kj report` for retrospective inspection.
+ *
+ * Shape (every field optional except status + finishedAt):
+ *   {
+ *     status:       "done" | "failed" | "blocked",
+ *     iterations:   number,        // how many coder→reviewer rounds
+ *     duration_ms:  number,        // wall-clock for this HU
+ *     branch:       string|null,   // git branch the coder used
+ *     commits:      string[],      // SHA list captured during the run
+ *     pr_url:       string|null,
+ *     blockers:     string[],      // why it failed/was blocked, plain
+ *     summary:      string,        // 1-2 sentence human summary
+ *     finishedAt:   ISO timestamp
+ *   }
+ *
+ * @returns {boolean} true if the HU was found and the outcome stored
+ */
+export function setHuOutcome(plan, huId, outcome) {
+  const hu = plan.hus.find(h => h.id === huId);
+  if (!hu) return false;
+  hu.outcome = {
+    status: outcome.status || hu.status || null,
+    iterations: outcome.iterations ?? null,
+    duration_ms: outcome.duration_ms ?? null,
+    branch: outcome.branch ?? null,
+    commits: Array.isArray(outcome.commits) ? outcome.commits : [],
+    pr_url: outcome.pr_url ?? null,
+    blockers: Array.isArray(outcome.blockers) ? outcome.blockers : [],
+    summary: outcome.summary || "",
+    finishedAt: outcome.finishedAt || new Date().toISOString(),
+  };
+  hu.updatedAt = new Date().toISOString();
+  plan.updatedAt = new Date().toISOString();
+  return true;
+}
+
+/**
+ * Stamp the plan-level rollup once every HU has finished. Built from
+ * the per-HU outcomes so the board can show "Plan finished · 8 done
+ * · 2 failed · 1 blocked · 15 min" in one banner.
+ *
+ *   {
+ *     status:       "done" | "partial" | "failed",
+ *     total:        number,
+ *     counts:       { done, failed, blocked, pending },
+ *     duration_ms:  number,
+ *     prs:          string[],            // unique pr_url across HUs
+ *     blockers:     string[],            // dedup'd blockers
+ *     finishedAt:   ISO timestamp,
+ *   }
+ */
+export function setPlanOutcome(plan, outcome) {
+  plan.outcome = {
+    status: outcome.status || "partial",
+    total: outcome.total ?? (plan.hus?.length || 0),
+    counts: outcome.counts || { done: 0, failed: 0, blocked: 0, pending: 0 },
+    duration_ms: outcome.duration_ms ?? null,
+    prs: Array.isArray(outcome.prs) ? [...new Set(outcome.prs.filter(Boolean))] : [],
+    blockers: Array.isArray(outcome.blockers) ? [...new Set(outcome.blockers.filter(Boolean))] : [],
+    finishedAt: outcome.finishedAt || new Date().toISOString(),
+  };
+  plan.updatedAt = new Date().toISOString();
+}
+
+/**
+ * PR-E: auto-promote every pending HU with at least one acceptance
+ * test to "certified". The intermediate "certified" state was an
+ * invisible wall — there's no UI button for it and the user had no
+ * way to discover `kj plan ready`. Treating pending-with-tests as
+ * runnable removes the wall while keeping the test contract gate.
+ *
+ * Mutates plan in place. HUs in done / failed / blocked are left
+ * alone so re-runs stay explicit (use --hu <id>).
+ *
+ * @returns {number} how many HUs were promoted (0 if nothing changed).
+ */
+export function autoCertifyPendingHus(plan) {
+  if (!plan?.hus?.length) return 0;
+  let promoted = 0;
+  const now = new Date().toISOString();
+  for (const hu of plan.hus) {
+    if (hu.status === "pending" && Array.isArray(hu.acceptance_tests) && hu.acceptance_tests.length > 0) {
+      hu.status = "certified";
+      hu.updatedAt = now;
+      promoted += 1;
+    }
+  }
+  if (promoted > 0) plan.updatedAt = now;
+  return promoted;
+}
+
+/**
+ * PR-E: assert that the plan has at least one HU that's actually
+ * going to run. Throws with a plain-Spanish message otherwise so
+ * `kj run --plan` can never silently fall back to single-task mode
+ * and burn tokens for nothing.
+ *
+ * The set of "runnable" statuses matches the sub-pipeline filter
+ * (today: certified). The caller should run autoCertifyPendingHus()
+ * BEFORE this so pending-with-tests get a chance.
+ *
+ * @throws {Error} when no HU is runnable.
+ */
+export function assertPlanRunnable(plan, planId) {
+  if (!plan?.hus?.length) {
+    throw new Error(
+      `El plan ${planId} no contiene ninguna HU. `
+      + `Edita el plan o vuelve a generarlo con \`kj plan\`. `
+      + `Aborto para no malgastar tokens en un fallback de "single task".`
+    );
+  }
+  const certified = plan.hus.filter((h) => h.status === "certified").length;
+  if (certified > 0) return;
+  const counts = plan.hus.reduce((acc, h) => {
+    const k = h.status || "pending";
+    acc[k] = (acc[k] || 0) + 1;
+    return acc;
+  }, {});
+  const summary = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ");
+  throw new Error(
+    `Plan ${planId}: 0 HU(s) listas para ejecutar (estados: ${summary}). `
+    + `Si las HU(s) están en done/failed/blocked y quieres relanzarlas, usa --hu <id>. `
+    + `Aborto para no malgastar tokens en un fallback de "single task".`
+  );
+}
+
+/**
+ * Compute the rollup from the per-HU outcomes already stamped on the
+ * plan. Invoked by syncResultsToPlan in plan-executor when the run
+ * ends so the caller doesn't have to assemble the counts by hand.
+ */
+export function computePlanOutcome(plan, { duration_ms = null } = {}) {
+  const hus = plan.hus || [];
+  const counts = { done: 0, failed: 0, blocked: 0, pending: 0 };
+  const prs = [];
+  const blockers = [];
+  for (const hu of hus) {
+    const status = hu.outcome?.status || hu.status || "pending";
+    if (counts[status] !== undefined) counts[status] += 1;
+    else counts.pending += 1;
+    if (hu.outcome?.pr_url) prs.push(hu.outcome.pr_url);
+    if (Array.isArray(hu.outcome?.blockers)) blockers.push(...hu.outcome.blockers);
+  }
+  let status = "done";
+  if (counts.failed > 0 || counts.blocked > 0) status = counts.done > 0 ? "partial" : "failed";
+  if (counts.done === 0 && counts.failed === 0 && counts.blocked === 0) status = "pending";
+  return {
+    status,
+    total: hus.length,
+    counts,
+    duration_ms,
+    // Dedupe at the rollup boundary — same PR / blocker reported by
+    // multiple HUs is noise in the banner.
+    prs: [...new Set(prs.filter(Boolean))],
+    blockers: [...new Set(blockers.filter(Boolean))],
+    finishedAt: new Date().toISOString(),
+  };
+}
+
 /**
  * Mark all pending HUs as certified (ready to execute).
  * Sets plan status to "ready".