@karajan-family/code 4.70.3 → 5.0.0

package/src/plan/adr-generator.js

@@ -1,170 +0,0 @@
-/**
- * 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

@@ -1,60 +0,0 @@
-/**
- * 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, path: join(dir, file) };
-      } 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

@@ -1,100 +0,0 @@
-/**
- * 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-validation.js

@@ -1,4 +0,0 @@
-// 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/prompts/acceptance-coverage.js

@@ -1,32 +0,0 @@
-// KJC-TSK-0987 (issue #1894): the prompt of the acceptance-coverage judge. A run
-// ended approved with none of the card's three criteria implemented; this judge
-// reads each criterion against the diff and says, one by one, whether it is
-// covered and where.
-
-const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
-  + "Do NOT use any MCP tools, do NOT mention Karajan. "
-  + "Your job is to judge whether a diff covers a card's acceptance criteria.";
-
-/**
- * @param {{criteria: string[], diff: string, task?: string, instructions?: string|null}} opts
- * @returns {string}
- */
-export function buildAcceptanceCoveragePrompt({ criteria, diff, task = "", instructions = null }) {
-  const list = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
-  const body = [
-    "You are the AcceptanceCoverage judge for Karajan Code.",
-    "Input: (a) the acceptance criteria of the task's card, numbered, and (b) the diff the run produced.",
-    "For EACH criterion decide whether the diff implements it. Covered means the behavior the",
-    "criterion describes exists in the diff (code, config or tests that exercise it), not that",
-    "something related was touched. Point to the evidence: file and what it does. A criterion",
-    "with no evidence in the diff is NOT covered, whatever the task description says.",
-    "Return a single valid JSON object and nothing else.",
-    'Schema: {"criteria":[{"index":number,"covered":boolean,"evidence":string}]}',
-    "One entry per criterion, in order, index starting at 1. Do not add or drop criteria.",
-  ].join("\n");
-  const sections = [PREAMBLE];
-  if (instructions) sections.push(instructions);
-  if (task) sections.push(`## Task\n${task}`);
-  sections.push(body, `## Acceptance criteria (${criteria.length})\n${list}`, `## Diff\n${diff || "(empty diff)"}`);
-  return sections.join("\n\n");
-}

package/src/prompts/arbiter.js

@@ -1,38 +0,0 @@
-/**
- * Arbiter prompt (KJC-TSK-0573, design in docs/specs/autonomous-delivery.md §6).
- *
- * The Arbiter is Karajan's autonomous decision authority: given a conflict, it
- * picks the LEAST-BAD option from a closed set and moves forward — no human.
- */
-
-/** The closed set of conflict-resolution verdicts. BLOCK_AND_CONTINUE is safe. */
-export const VERDICTS = Object.freeze([
-  "ACCEPT_WITH_DEFECT",
-  "RETRY_DIFFERENT_APPROACH",
-  "DESCOPE_HU",
-  "BLOCK_AND_CONTINUE",
-  "PROCEED",
-]);
-
-export function buildArbiterPrompt({ question, options = [], context = null } = {}) {
-  const allowed = options.length ? options.map((o) => o.value) : VERDICTS;
-  return [
-    "You are the Arbiter — Karajan's autonomous decision authority. There is no human to ask.",
-    "Resolve the conflict below by choosing the LEAST-BAD option and moving forward.",
-    "",
-    "Ground-truth order (what wins when signals disagree):",
-    "  1. Acceptance tests passing — beats any reviewer opinion.",
-    "  2. Must-fix issues (security, correctness, data) — beat style.",
-    "  3. Nice-to-have (style, optional refactors) — never block; record as a defect if dropped.",
-    "Goal: maximize 'the ask is met', minimize irreversible risk. Imperfect-but-delivered beats blocked.",
-    "",
-    `Conflict: ${question}`,
-    context ? `Context: ${JSON.stringify(context)}` : "",
-    "",
-    `Choose exactly one verdict from: ${allowed.join(", ")}`,
-    "Respond with ONLY this JSON (no prose):",
-    '{"verdict":"<one of the allowed>","confidence":0.0,"rationale":"why it is the least-bad option","defect":"residual debt if any, else null","directive":"instruction to the coder when RETRY_DIFFERENT_APPROACH, else null"}',
-  ]
-    .filter(Boolean)
-    .join("\n");
-}

package/src/prompts/architect.js

@@ -1,103 +0,0 @@
-import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
-import { getLanguageInstruction } from "../utils/locale.js";
-import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
-
-const SUBAGENT_PREAMBLE = [
-  "IMPORTANT: You are running as a Karajan sub-agent.",
-  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
-  "Do NOT use any MCP tools. Focus only on designing the architecture for the task."
-].join(" ");
-
-export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
-
-/**
- * Build the architect prompt as a { stable, volatile } layout (Φ1,
- * KJC-PCS-0057): instructions, guidelines, schema, contexts and skills
- * are identical across invocations on the same project; research
- * context and the task itself go last.
- */
-export async function buildArchitectPromptLayout({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
-  const langInstruction = getLanguageInstruction(language);
-  let skillSection = null;
-  if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    skillSection = buildSkillSection(skills, { provider, role: "architect" });
-  }
-
-  return buildPromptLayout([
-    section(SUBAGENT_PREAMBLE, STABLE),
-    section(langInstruction, STABLE),
-    section(instructions, STABLE),
-    section("You are the architect in a multi-role AI pipeline.", STABLE),
-    section("Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.", STABLE),
-    section("## Architecture Guidelines", STABLE),
-    section([
-      "- Identify the architecture type (layered, microservices, event-driven, etc.)",
-      "- Define the layers and their responsibilities",
-      "- Identify design patterns to apply",
-      "- Define the data model with entities",
-      "- Specify API contracts (endpoints, events, interfaces)",
-      "- List external and internal dependencies",
-      "- Document tradeoffs and their rationale",
-      "- If critical decisions cannot be made without more information, list clarifying questions"
-    ].join("\n"), STABLE),
-    section("Return a single valid JSON object and nothing else.", STABLE),
-    section('JSON schema: {"verdict":"ready|needs_clarification","architecture":{"type":string,"layers":[string],"patterns":[string],"dataModel":{"entities":[string]},"apiContracts":[string],"dependencies":[string],"tradeoffs":[string]},"questions":[string],"summary":string}', STABLE),
-    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
-    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
-    section(skillSection, STABLE),
-    section(researchContext ? `## Research Context\n${researchContext}` : null, VOLATILE),
-    section(`## Task\n${task}`, VOLATILE),
-  ]);
-}
-
-export async function buildArchitectPrompt(options) {
-  return joinLayout(await buildArchitectPromptLayout(options));
-}
-
-function filterStrings(arr) {
-  if (!Array.isArray(arr)) return [];
-  return arr.filter((item) => typeof item === "string");
-}
-
-export function parseArchitectOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonMatch[0]);
-  } catch { /* architect output is not valid JSON */
-    return null;
-  }
-
-  const verdict = VALID_VERDICTS.has(parsed.verdict)
-    ? parsed.verdict
-    : "needs_clarification";
-
-  const arch = parsed.architecture && typeof parsed.architecture === "object"
-    ? parsed.architecture
-    : {};
-
-  const dataModel = arch.dataModel && typeof arch.dataModel === "object"
-    ? arch.dataModel
-    : {};
-
-  return {
-    verdict,
-    architecture: {
-      type: typeof arch.type === "string" ? arch.type : "",
-      layers: filterStrings(arch.layers),
-      patterns: filterStrings(arch.patterns),
-      dataModel: {
-        entities: filterStrings(dataModel.entities)
-      },
-      apiContracts: filterStrings(arch.apiContracts),
-      dependencies: filterStrings(arch.dependencies),
-      tradeoffs: filterStrings(arch.tradeoffs)
-    },
-    questions: filterStrings(parsed.questions),
-    summary: parsed.summary || ""
-  };
-}