@kaddo/cli 3.72.2 → 3.74.0

package/dist/core.js

@@ -116,8 +116,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path2 = i.path.join(".");
-      return path2 ? `  - ${path2}: ${i.message}` : `  - ${i.message}`;
+      const path3 = i.path.join(".");
+      return path3 ? `  - ${path3}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -352,11 +352,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path2 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path2)) return [];
+  const path3 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path3)) return [];
   let parsed;
   try {
-    parsed = parseYaml3(readFile(path2));
+    parsed = parseYaml3(readFile(path3));
   } catch {
     return [];
   }
@@ -1590,7 +1590,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path2, md) {
+function parseCapsule(id, path3, md) {
   const { data } = matter2(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -1600,7 +1600,7 @@ function parseCapsule(id, path2, md) {
   }
   return {
     id,
-    path: path2,
+    path: path3,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -2761,10 +2761,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path2 = agentInstallPath(file);
-    const installed = isFile(join(dir, path2));
+    const path3 = agentInstallPath(file);
+    const installed = isFile(join(dir, path3));
     const group = agentGroupOf(file);
-    return { agentPath: path2, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path3, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -3686,6 +3686,9 @@ var RECOMMENDED_SKILLS = [...SKILL_GROUPS.delivery, ...SKILL_GROUPS.tech];
 function skillInstallPath(id) {
   return `knowledge/skills/${id}/skill.md`;
 }
+function skillById(id) {
+  return SKILLS.find((s) => s.id === id);
+}
 
 // src/agents/responsibility.ts
 var RESPONSIBILITY_MATRIX = {
@@ -7715,18 +7718,757 @@ function parseRelatedKnowledge(fm, knowledgeById) {
   }
   return out;
 }
+
+// src/core/work-item-write.ts
+import fs2 from "fs";
+import path2 from "path";
+import crypto from "crypto";
+import matter7 from "gray-matter";
+var WORK_ITEMS_DIR = "knowledge/delivery/work-items";
+var WorkItemWriteError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "WorkItemWriteError";
+  }
+  code;
+};
+var VALID_COVERAGE = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
+var VALID_CONFIDENCE = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+var EDITABLE_STATES = ["draft"];
+function revisionOf(raw) {
+  return crypto.createHash("sha256").update(raw, "utf-8").digest("hex");
+}
+function slugify2(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
+}
+function nextWorkItemId(dir) {
+  const wiDir = join(dir, WORK_ITEMS_DIR);
+  let max = 0;
+  const walk = (d) => {
+    if (!exists(d)) return;
+    for (const entry of fs2.readdirSync(d)) {
+      const full = join(d, entry);
+      if (isFile(full)) {
+        const m = entry.match(/WI-(\d+)/);
+        if (m) max = Math.max(max, parseInt(m[1], 10));
+      } else if (!entry.startsWith(".")) {
+        walk(full);
+      }
+    }
+  };
+  walk(wiDir);
+  return `WI-${String(max + 1).padStart(3, "0")}`;
+}
+function atomicWrite(filePath, content) {
+  fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs2.writeFileSync(tmp, content, "utf-8");
+  try {
+    fs2.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs2.rmSync(tmp, { force: true });
+    } catch {
+    }
+    throw err;
+  }
+}
+function findArtifact(dir, id) {
+  const match = discoverWorkItems(dir).find((a) => (a.id || a.title) === id);
+  if (!match) throw new WorkItemWriteError("WORK_ITEM_NOT_FOUND", `Work Item "${id}" was not found.`);
+  return { filePath: match.filePath, relPath: match.relPath };
+}
+function validModuleIds(dir) {
+  const ids = /* @__PURE__ */ new Set(["core"]);
+  for (const m of loadMappedModules(dir)) ids.add(m.id);
+  return ids;
+}
+var SECTION_ORDER = [
+  "Actor",
+  "Outcome",
+  "Current behavior",
+  "Target behavior",
+  "Entry points",
+  "End-to-end flow",
+  "Scope unknowns",
+  "Acceptance criteria"
+];
+var KNOWN_HEADINGS = new Set(SECTION_ORDER.map((s) => s.toLowerCase()));
+function parseBody(content) {
+  const lines = content.split(/\r?\n/);
+  const preamble = [];
+  const sections = [];
+  let current = null;
+  let buffer = [];
+  let seenHeading = false;
+  const flush = () => {
+    if (current) {
+      current.body = buffer.join("\n").trim();
+      sections.push(current);
+    }
+    buffer = [];
+  };
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.*?)\s*$/);
+    if (m) {
+      seenHeading = true;
+      flush();
+      current = { heading: m[1].trim(), normalized: m[1].trim().toLowerCase(), body: "" };
+    } else if (!seenHeading) {
+      preamble.push(line);
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+  return { preamble, sections };
+}
+function renderList(items) {
+  return items.map((i) => `- ${i.trim()}`).filter((l) => l.trim() !== "-").join("\n");
+}
+function renderCriteria(items) {
+  return items.filter((c) => c.text.trim()).map((c) => c.checked === true ? `- [x] ${c.text.trim()}` : c.checked === false ? `- [ ] ${c.text.trim()}` : `- ${c.text.trim()}`).join("\n");
+}
+function desiredSections(input) {
+  const d = /* @__PURE__ */ new Map();
+  const put = (heading, value) => d.set(heading.toLowerCase(), value.trim() ? value.trim() : null);
+  put("Actor", input.actor ?? "");
+  put("Outcome", input.outcome ?? "");
+  put("Current behavior", input.currentBehavior ?? "");
+  put("Target behavior", input.targetBehavior ?? "");
+  put("Entry points", input.entryPoints ?? "");
+  put("End-to-end flow", input.endToEndFlow ?? "");
+  d.set("scope unknowns", input.scopeUnknowns.some((u) => u.trim()) ? renderList(input.scopeUnknowns) : null);
+  d.set("acceptance criteria", input.acceptanceCriteria.some((c) => c.text.trim()) ? renderCriteria(input.acceptanceCriteria) : null);
+  return d;
+}
+function headingFor(normalized) {
+  return SECTION_ORDER.find((s) => s.toLowerCase() === normalized) ?? normalized;
+}
+function mergeBody(existing, input) {
+  const { preamble, sections } = parseBody(existing);
+  const desired = desiredSections(input);
+  const handled = /* @__PURE__ */ new Set();
+  const preambleLines = [...preamble];
+  const h1Index = preambleLines.findIndex((l) => /^#\s+/.test(l));
+  if (h1Index >= 0) preambleLines[h1Index] = `# ${input.title}`;
+  const out = [];
+  for (const s of sections) {
+    if (KNOWN_HEADINGS.has(s.normalized)) {
+      handled.add(s.normalized);
+      const body = desired.get(s.normalized);
+      if (body != null) out.push(`## ${headingFor(s.normalized)}
+
+${body}`);
+    } else {
+      out.push(`## ${s.heading}${s.body ? `
+
+${s.body}` : ""}`);
+    }
+  }
+  for (const heading of SECTION_ORDER) {
+    const norm = heading.toLowerCase();
+    if (handled.has(norm)) continue;
+    const body = desired.get(norm);
+    if (body != null) out.push(`## ${heading}
+
+${body}`);
+  }
+  const preambleText = preambleLines.join("\n").trim();
+  return `${preambleText}
+
+${out.join("\n\n")}
+`;
+}
+function freshBody(input) {
+  const preamble = `# ${input.title}
+
+> Type: ${input.type}`;
+  const out = [];
+  const desired = desiredSections(input);
+  for (const heading of SECTION_ORDER) {
+    const body = desired.get(heading.toLowerCase());
+    if (body != null) out.push(`## ${heading}
+
+${body}`);
+  }
+  return `${preamble}
+
+${out.join("\n\n")}
+`.replace(/\n{3,}/g, "\n\n");
+}
+function applyFrontmatter(data, input) {
+  const next = { ...data };
+  next.title = input.title;
+  next.type = input.type;
+  next.work_type = input.type;
+  if (input.summary != null) next.summary = input.summary;
+  next.affected_modules = [...input.affectedModules];
+  if (input.scopeConfidence && VALID_CONFIDENCE.has(input.scopeConfidence.level)) {
+    next.scope_confidence = { level: input.scopeConfidence.level, reasons: input.scopeConfidence.reasons.filter((r) => r.trim()) };
+  } else {
+    delete next.scope_confidence;
+  }
+  const coverage = {};
+  for (const c of input.moduleCoverage) {
+    if (!VALID_COVERAGE.has(c.status)) continue;
+    coverage[c.id] = c.reason?.trim() ? { status: c.status, reason: c.reason.trim() } : { status: c.status };
+  }
+  if (Object.keys(coverage).length > 0) next.module_coverage = coverage;
+  else delete next.module_coverage;
+  const surfaces = {};
+  for (const s of input.impactAnalysis) {
+    if (!VALID_COVERAGE.has(s.status)) continue;
+    const entry = { status: s.status };
+    if (s.reason?.trim()) entry.reason = s.reason.trim();
+    if (s.question?.trim()) entry.question = s.question.trim();
+    surfaces[s.surface] = entry;
+  }
+  if (Object.keys(surfaces).length > 0) next.impact_analysis = { surfaces };
+  else delete next.impact_analysis;
+  if (input.decisions.length > 0) next.decisions = [...input.decisions];
+  else delete next.decisions;
+  if (input.relatedKnowledge.length > 0) next.related_knowledge = [...input.relatedKnowledge];
+  else delete next.related_knowledge;
+  return next;
+}
+function serialize(data, body) {
+  return matter7.stringify(`
+${body.trim()}
+`, data);
+}
+function toInput(data, content) {
+  const { sections } = parseBody(content);
+  const sec = (name) => {
+    const s = sections.find((x) => x.normalized === name);
+    return s && s.body.trim() ? s.body.trim() : void 0;
+  };
+  const bullets = (name) => {
+    const body = sec(name);
+    if (!body) return [];
+    return body.split(/\r?\n/).map((l) => l.replace(/^\s*[-*+]\s+(\[[ xX]\]\s*)?/, "").trim()).filter(Boolean);
+  };
+  const criteria = (() => {
+    const body = sec("acceptance criteria");
+    if (!body) return [];
+    const out = [];
+    for (const line of body.split(/\r?\n/)) {
+      const m = line.match(/^\s*[-*+]\s+(.*)$/);
+      if (!m) continue;
+      let text3 = m[1].trim();
+      let checked = null;
+      const cb = text3.match(/^\[([ xX])\]\s*(.*)$/);
+      if (cb) {
+        checked = cb[1].toLowerCase() === "x";
+        text3 = cb[2].trim();
+      }
+      if (text3) out.push({ text: text3, checked });
+    }
+    return out;
+  })();
+  const sc = data.scope_confidence;
+  const mc = data.module_coverage;
+  const ia = data.impact_analysis?.surfaces;
+  return {
+    title: String(data.title ?? ""),
+    type: String(data.type ?? "feature"),
+    summary: data.summary ? String(data.summary) : void 0,
+    actor: sec("actor"),
+    outcome: sec("outcome"),
+    currentBehavior: sec("current behavior"),
+    targetBehavior: sec("target behavior"),
+    entryPoints: sec("entry points"),
+    endToEndFlow: sec("end-to-end flow"),
+    scopeConfidence: sc && sc.level ? { level: String(sc.level), reasons: Array.isArray(sc.reasons) ? sc.reasons.map(String) : [] } : null,
+    scopeUnknowns: bullets("scope unknowns"),
+    affectedModules: Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [],
+    moduleCoverage: mc ? Object.entries(mc).map(([id, v]) => ({ id, status: String(v.status ?? ""), ...v.reason ? { reason: String(v.reason) } : {} })) : [],
+    impactAnalysis: ia ? Object.entries(ia).map(([surface, v]) => ({ surface, status: String(v.status ?? ""), ...v.reason ? { reason: String(v.reason) } : {}, ...v.question ? { question: String(v.question) } : {} })) : [],
+    acceptanceCriteria: criteria,
+    decisions: Array.isArray(data.decisions) ? data.decisions.map(String) : [],
+    relatedKnowledge: Array.isArray(data.related_knowledge) ? data.related_knowledge.map(String) : []
+  };
+}
+function getWorkItemForEdit(dir, id) {
+  const { filePath, relPath } = findArtifact(dir, id);
+  const raw = readFile(filePath);
+  const { data, content } = matter7(raw);
+  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
+  const input = toInput(data, content);
+  const editable = EDITABLE_STATES.includes(status);
+  return {
+    ...input,
+    id,
+    status,
+    revision: revisionOf(raw),
+    path: relPath,
+    editable,
+    ...editable ? {} : { editableReason: status === "ready" ? "This Work Item is Ready. Reopen it as Draft to edit its scope." : `This Work Item is ${status} and cannot be edited from the structured editor.` }
+  };
+}
+var CAPTURE_SECTIONS = [
+  { field: "problem", heading: "Problem" },
+  { field: "expected_result", heading: "Expected result" },
+  { field: "impact", heading: "Impact" },
+  { field: "acceptance_criteria", heading: "Acceptance criteria", list: true },
+  { field: "design", heading: "Design" },
+  { field: "risks", heading: "Risks" }
+];
+function captureBody(title, type, answers) {
+  const out = [`# ${title}`, "", `> Type: ${type}`];
+  for (const { field, heading, list: list2 } of CAPTURE_SECTIONS) {
+    const value = answers[field]?.trim();
+    if (!value) continue;
+    if (list2) {
+      const items = value.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l) => /^[-*+]\s/.test(l) ? l : `- ${l}`);
+      out.push("", `## ${heading}`, "", items.join("\n"));
+    } else {
+      out.push("", `## ${heading}`, "", value);
+    }
+  }
+  return out.join("\n") + "\n";
+}
+function createWorkItem(dir, opts) {
+  const intent = opts.intent.trim();
+  if (!intent) throw new WorkItemWriteError("INVALID_INPUT", "An intent or summary is required.");
+  const type = opts.type.trim() || "feature";
+  if (!WORK_ITEM_TYPES.has(type)) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${type}".`);
+  const id = nextWorkItemId(dir);
+  const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const data = {
+    type,
+    id,
+    title,
+    status: "draft",
+    work_type: type,
+    created_at: today,
+    source: { type: "manual", inferred: false },
+    generated_by: "kaddo-admin",
+    affected_modules: [],
+    summary: intent
+  };
+  const answers = opts.answers ?? {};
+  const hasAnswers = Object.values(answers).some((v) => v?.trim());
+  const body = hasAnswers ? captureBody(title, type, answers) : freshBody({
+    title,
+    type,
+    summary: intent,
+    scopeUnknowns: [],
+    affectedModules: [],
+    moduleCoverage: [],
+    impactAnalysis: [],
+    acceptanceCriteria: [],
+    decisions: [],
+    relatedKnowledge: [],
+    scopeConfidence: null
+  });
+  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify2(title)}.md`;
+  const filePath = join(dir, relPath);
+  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
+  const raw = serialize(data, body);
+  atomicWrite(filePath, raw);
+  return { id, path: relPath, revision: revisionOf(raw) };
+}
+function validateInput(input) {
+  if (!input.title.trim()) throw new WorkItemWriteError("INVALID_INPUT", "Title is required.");
+  if (!WORK_ITEM_TYPES.has(input.type)) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${input.type}".`);
+}
+function updateWorkItem(dir, id, input, expectedRevision) {
+  validateInput(input);
+  const { filePath, relPath } = findArtifact(dir, id);
+  const raw = readFile(filePath);
+  if (revisionOf(raw) !== expectedRevision) {
+    throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before saving.");
+  }
+  const { data, content } = matter7(raw);
+  const status = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
+  if (!EDITABLE_STATES.includes(status)) {
+    throw new WorkItemWriteError("WORK_ITEM_NOT_EDITABLE", `A ${status} Work Item cannot be edited. Reopen it as Draft first.`);
+  }
+  const nextData = applyFrontmatter(data, input);
+  const nextBody = mergeBody(content, input);
+  const nextRaw = serialize(nextData, nextBody);
+  atomicWrite(filePath, nextRaw);
+  return { revision: revisionOf(nextRaw), path: relPath };
+}
+function validateWorkItem(dir, id) {
+  const { filePath } = findArtifact(dir, id);
+  const raw = readFile(filePath);
+  const { data, content } = matter7(raw);
+  const input = toInput(data, content);
+  const findings = [];
+  const modules = validModuleIds(dir);
+  for (const c of input.moduleCoverage) {
+    if (c.status === "affected" && !input.affectedModules.includes(c.id)) {
+      findings.push({ level: "blocking", message: `${c.id} is marked affected in module coverage but is missing from affected_modules.` });
+    }
+  }
+  for (const m of input.affectedModules) {
+    if (!modules.has(m)) findings.push({ level: "blocking", message: `Module "${m}" is not registered in this project.` });
+  }
+  if (!input.targetBehavior?.trim()) findings.push({ level: "warning", message: "Target behavior is not defined." });
+  if (input.acceptanceCriteria.length === 0) findings.push({ level: "warning", message: "No acceptance criteria have been defined." });
+  if (input.scopeConfidence?.level === "low") findings.push({ level: "warning", message: "Scope confidence is Low." });
+  if (!input.scopeConfidence) findings.push({ level: "warning", message: "Scope confidence has not been assessed." });
+  for (const c of input.moduleCoverage) {
+    if (c.status === "reviewed-not-affected") findings.push({ level: "fyi", message: `${c.id} was reviewed and is not affected.` });
+  }
+  for (const s of input.impactAnalysis) {
+    if (s.status === "unknown") findings.push({ level: "fyi", message: `Impact on ${s.surface} is unknown.` });
+  }
+  const canMarkReady = !findings.some((f) => f.level === "blocking");
+  return { findings, canMarkReady };
+}
+var ALLOWED = { draft: ["ready"], ready: ["draft"] };
+function transitionWorkItem(dir, id, to, expectedRevision) {
+  const { filePath } = findArtifact(dir, id);
+  const raw = readFile(filePath);
+  if (revisionOf(raw) !== expectedRevision) {
+    throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
+  }
+  const { data, content } = matter7(raw);
+  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
+  if (!(ALLOWED[from] ?? []).includes(to)) {
+    throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
+  }
+  if (to === "ready") {
+    const { canMarkReady } = validateWorkItem(dir, id);
+    if (!canMarkReady) throw new WorkItemWriteError("INVALID_TRANSITION", "This Work Item has blocking issues and cannot be marked Ready.");
+  }
+  const nextData = { ...data, status: to };
+  const nextRaw = serialize(nextData, content);
+  const filename = path2.basename(filePath);
+  const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
+  const targetPath = join(dir, targetRel);
+  atomicWrite(targetPath, nextRaw);
+  if (path2.resolve(targetPath) !== path2.resolve(filePath)) {
+    try {
+      fs2.rmSync(filePath, { force: true });
+    } catch {
+    }
+  }
+  return { revision: revisionOf(nextRaw), status: to, path: targetRel };
+}
+
+// src/core/knowledge-levels.ts
+var WORK_ITEM_TYPES2 = ["feature", "bugfix", "hotfix", "spike", "chore"];
+var LEVELS = {
+  K0: {
+    level: "K0",
+    description: "Trivial change. No formal knowledge required.",
+    questions: [],
+    qualityGate: []
+  },
+  K1: {
+    level: "K1",
+    description: "Simple fix or hotfix.",
+    questions: [
+      {
+        id: "problem",
+        prompt: "What problem does this fix?",
+        placeholder: "e.g. Button is not clickable on mobile",
+        frontMatterField: "problem",
+        required: true
+      },
+      {
+        id: "expected_result",
+        prompt: "What is the expected result after the fix?",
+        placeholder: "e.g. Button works correctly on all screen sizes",
+        frontMatterField: "expected_result",
+        required: true
+      }
+    ],
+    qualityGate: ["Problem is clear.", "Expected result is defined."]
+  },
+  K2: {
+    level: "K2",
+    description: "Feature or bugfix with functional impact.",
+    questions: [
+      {
+        id: "problem",
+        prompt: "What problem does this solve?",
+        placeholder: "e.g. Users cannot complete checkout without email verification",
+        frontMatterField: "problem",
+        required: true
+      },
+      {
+        id: "expected_result",
+        prompt: "What is the expected result?",
+        placeholder: "e.g. Users can verify email inline during checkout",
+        frontMatterField: "expected_result",
+        required: true
+      },
+      {
+        id: "impact",
+        prompt: "What is the impact if this is not done?",
+        placeholder: "e.g. ~30% of users drop off at checkout",
+        frontMatterField: "impact",
+        required: true
+      },
+      {
+        id: "acceptance_criteria",
+        prompt: "What are the acceptance criteria? (one per line, press Enter twice to finish)",
+        placeholder: "e.g. Email is verified before payment step",
+        frontMatterField: "acceptance_criteria",
+        required: true
+      }
+    ],
+    qualityGate: [
+      "Problem is clear.",
+      "Expected result is defined.",
+      "Impact of not doing it is stated.",
+      "Acceptance criteria are verifiable."
+    ]
+  },
+  K3: {
+    level: "K3",
+    description: "Capability, integration, or significant functional change.",
+    questions: [
+      {
+        id: "problem",
+        prompt: "What problem does this solve?",
+        placeholder: "e.g. Payments need to support multiple providers",
+        frontMatterField: "problem",
+        required: true
+      },
+      {
+        id: "impact",
+        prompt: "What is the impact if this is not done?",
+        placeholder: "e.g. We are locked into a single provider with no fallback",
+        frontMatterField: "impact",
+        required: true
+      },
+      {
+        id: "acceptance_criteria",
+        prompt: "What are the acceptance criteria?",
+        placeholder: "e.g. System routes to provider B when provider A fails",
+        frontMatterField: "acceptance_criteria",
+        required: true
+      },
+      {
+        id: "design",
+        prompt: "What is the proposed design or approach?",
+        placeholder: "e.g. Abstract provider interface + strategy pattern",
+        frontMatterField: "design",
+        required: true
+      }
+    ],
+    qualityGate: [
+      "Problem is clear.",
+      "Impact is stated.",
+      "Acceptance criteria are verifiable.",
+      "Design is sufficient to start."
+    ]
+  },
+  K4: {
+    level: "K4",
+    description: "Architecture change, migration, or high-risk decision.",
+    questions: [
+      {
+        id: "problem",
+        prompt: "What problem does this solve?",
+        placeholder: "e.g. Current auth system does not support SSO",
+        frontMatterField: "problem",
+        required: true
+      },
+      {
+        id: "impact",
+        prompt: "What is the impact if this is not done?",
+        placeholder: "e.g. Enterprise clients cannot onboard",
+        frontMatterField: "impact",
+        required: true
+      },
+      {
+        id: "design",
+        prompt: "What is the proposed design or approach?",
+        placeholder: "e.g. Replace JWT-only auth with OIDC + JWT hybrid",
+        frontMatterField: "design",
+        required: true
+      },
+      {
+        id: "risks",
+        prompt: "What are the main risks?",
+        placeholder: "e.g. Existing sessions may be invalidated during migration",
+        frontMatterField: "risks",
+        required: true
+      }
+    ],
+    qualityGate: [
+      "Problem is clear.",
+      "Impact is stated.",
+      "Design is documented.",
+      "Risks are identified.",
+      "ADR is created or linked if applicable."
+    ]
+  }
+};
+var TYPE_TO_LEVEL = {
+  hotfix: "K1",
+  bugfix: "K2",
+  feature: "K2",
+  spike: "K3",
+  // Chores are maintenance/config/tooling work — low ceremony (problem + expected result).
+  chore: "K1"
+};
+function getLevel(level) {
+  return LEVELS[level];
+}
+function getLevelForType(type) {
+  return TYPE_TO_LEVEL[type];
+}
+
+// src/core/work-item-refinement.ts
+function toCapture(q) {
+  return { id: q.id, prompt: q.prompt, placeholder: q.placeholder, field: q.frontMatterField, required: q.required };
+}
+function getWorkItemCaptureDefinition() {
+  const questions = {};
+  for (const type of WORK_ITEM_TYPES2) {
+    questions[type] = getLevel(getLevelForType(type)).questions.map(toCapture);
+  }
+  return {
+    types: WORK_ITEM_TYPES2.map((t) => ({ value: t, label: t.charAt(0).toUpperCase() + t.slice(1) })),
+    questions
+  };
+}
+function getWorkItemAgentAssets() {
+  const agent = AGENT_PROMPTS.find((p2) => p2.fileName === "work-item-agent.md");
+  const skill2 = skillById("work-item-refinement");
+  return { agentPrompt: agent?.content ?? "", skill: skill2?.content ?? null };
+}
+function assembleRefinementContext(dir, workItemId) {
+  const edit = getWorkItemForEdit(dir, workItemId);
+  const config = loadConfig(dir);
+  const knowledgeArtifacts = discoverKnowledge(dir).filter(
+    (a) => !a.isWorkItem && a.type !== "skill" && a.type !== "agent" && a.layer !== "unknown"
+  );
+  const decisions = knowledgeArtifacts.filter((a) => a.type === "adr" || /^adr-/i.test(a.id)).map((a) => ({ id: a.id, title: a.title || a.id }));
+  const knowledge = knowledgeArtifacts.filter((a) => !(a.type === "adr" || /^adr-/i.test(a.id))).map((a) => ({ id: a.id || a.relPath, title: a.title || a.id, layer: a.layer, type: a.type || void 0, summary: a.summary || void 0 }));
+  const modules = ["core", ...loadMappedModules(dir).map((m) => m.id)].filter((v, i, arr) => arr.indexOf(v) === i);
+  return {
+    workItem: { id: edit.id, title: edit.title, status: edit.status, intent: edit.summary ?? edit.title, current: stripEdit(edit) },
+    project: { name: config?.project.name ?? "unknown", state: config?.project.state ?? "unknown", structure: config?.project.structure ?? "unknown" },
+    modules,
+    knowledge,
+    decisions,
+    revision: edit.revision
+  };
+}
+function stripEdit(edit) {
+  const { id: _i, status: _s, revision: _r, path: _p, editable: _e, editableReason: _er, ...input } = edit;
+  return input;
+}
+var VALID_COVERAGE2 = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
+var VALID_CONFIDENCE2 = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : void 0;
+}
+function strList(v) {
+  return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
+}
+function normalizeAndValidateProposal(dir, workItemId, proposal) {
+  const ctx = assembleRefinementContext(dir, workItemId);
+  const knownModules = new Set(ctx.modules);
+  const knownDecisions = new Set(ctx.decisions.map((d) => d.id));
+  const knownKnowledge = new Set(ctx.knowledge.map((k) => k.id));
+  const extraFindings = [];
+  const input = { ...ctx.workItem.current };
+  if (str(proposal.title)) input.title = str(proposal.title);
+  const o = proposal.outcome ?? {};
+  if (str(o.actor) !== void 0) input.actor = str(o.actor);
+  if (str(o.observableOutcome) !== void 0) input.outcome = str(o.observableOutcome);
+  if (str(o.currentBehavior) !== void 0) input.currentBehavior = str(o.currentBehavior);
+  if (str(o.targetBehavior) !== void 0) input.targetBehavior = str(o.targetBehavior);
+  const j = proposal.journey ?? {};
+  if (j.entryPoints) input.entryPoints = strList(j.entryPoints).join("\n");
+  if (j.flow) input.endToEndFlow = strList(j.flow).map((s) => `- ${s}`).join("\n");
+  if (proposal.moduleCoverage) {
+    input.moduleCoverage = proposal.moduleCoverage.filter((c) => {
+      if (!knownModules.has(c.id)) {
+        extraFindings.push({ level: "warning", message: `Proposed module "${c.id}" is not registered and was not included.` });
+        return false;
+      }
+      return VALID_COVERAGE2.has(c.status);
+    }).map((c) => ({ id: c.id, status: c.status, ...str(c.reason) ? { reason: str(c.reason) } : {} }));
+  }
+  const affected = /* @__PURE__ */ new Set();
+  for (const m of proposal.affectedModules ?? []) if (knownModules.has(m)) affected.add(m);
+  for (const c of input.moduleCoverage) if (c.status === "affected") affected.add(c.id);
+  if (proposal.affectedModules || proposal.moduleCoverage) input.affectedModules = [...affected];
+  if (proposal.impactAnalysis) {
+    input.impactAnalysis = proposal.impactAnalysis.filter((s) => VALID_COVERAGE2.has(s.status) && str(s.surface)).map((s) => ({ surface: str(s.surface), status: s.status, ...str(s.reason) ? { reason: str(s.reason) } : {}, ...str(s.question) ? { question: str(s.question) } : {} }));
+  }
+  if (proposal.scopeConfidence && VALID_CONFIDENCE2.has(proposal.scopeConfidence.level)) {
+    input.scopeConfidence = { level: proposal.scopeConfidence.level, reasons: strList(proposal.scopeConfidence.reasons) };
+  }
+  if (proposal.scopeUnknowns) input.scopeUnknowns = strList(proposal.scopeUnknowns);
+  if (proposal.acceptanceCriteria) input.acceptanceCriteria = strList(proposal.acceptanceCriteria).map((t) => ({ text: t, checked: null }));
+  if (proposal.linkedDecisions) {
+    input.decisions = proposal.linkedDecisions.filter((id) => {
+      if (!knownDecisions.has(id)) {
+        extraFindings.push({ level: "warning", message: `Proposed decision "${id}" does not exist and was not linked.` });
+        return false;
+      }
+      return true;
+    });
+  }
+  if (proposal.relatedKnowledge) {
+    input.relatedKnowledge = proposal.relatedKnowledge.filter((id) => {
+      if (!knownKnowledge.has(id)) {
+        extraFindings.push({ level: "warning", message: `Proposed knowledge "${id}" could not be resolved and was not linked.` });
+        return false;
+      }
+      return true;
+    });
+  }
+  const findings = [...extraFindings, ...evaluate(input, knownModules)];
+  const blocking = findings.filter((f) => f.level === "blocking").length;
+  const warning = findings.filter((f) => f.level === "warning").length;
+  const fyi = findings.filter((f) => f.level === "fyi").length;
+  return { input, validation: { findings, blocking, warning, fyi, canApply: true } };
+}
+function evaluate(input, knownModules) {
+  const findings = [];
+  for (const c of input.moduleCoverage) {
+    if (c.status === "affected" && !input.affectedModules.includes(c.id)) {
+      findings.push({ level: "blocking", message: `${c.id} is marked affected in module coverage but is missing from affected_modules.` });
+    }
+  }
+  for (const m of input.affectedModules) {
+    if (!knownModules.has(m)) findings.push({ level: "blocking", message: `Module "${m}" is not registered in this project.` });
+  }
+  if (!input.targetBehavior?.trim()) findings.push({ level: "warning", message: "Target behavior is not defined." });
+  if (input.acceptanceCriteria.length === 0) findings.push({ level: "warning", message: "No acceptance criteria have been defined." });
+  if (input.scopeConfidence?.level === "low") findings.push({ level: "warning", message: "Scope confidence is Low." });
+  if (!input.scopeConfidence) findings.push({ level: "warning", message: "Scope confidence has not been assessed." });
+  for (const s of input.impactAnalysis) if (s.status === "unknown") findings.push({ level: "fyi", message: `Impact on ${s.surface} is unknown.` });
+  return findings;
+}
+function applyRefinement(dir, workItemId, proposal, expectedRevision) {
+  const { input } = normalizeAndValidateProposal(dir, workItemId, proposal);
+  return updateWorkItem(dir, workItemId, input, expectedRevision);
+}
 export {
   WorkItemNotFoundError,
+  WorkItemWriteError,
   analyzeCrossRepoEvidence,
   analyzeScopeCoverage,
+  applyRefinement,
+  assembleRefinementContext,
   buildProjectExplanation,
   buildProjectRoute,
   buildReadinessReport,
+  createWorkItem,
   cwd,
   discoverKnowledge,
   discoverWorkItems,
   exists,
   getWorkItem,
+  getWorkItemAgentAssets,
+  getWorkItemCaptureDefinition,
+  getWorkItemForEdit,
   getWorkItems,
   getWorkItemsSummary,
   isActiveState,
@@ -7737,5 +8479,9 @@ export {
   lifecycleStateOf,
   loadConfig,
   loadMappedModules,
-  readFile
+  normalizeAndValidateProposal,
+  readFile,
+  transitionWorkItem,
+  updateWorkItem,
+  validateWorkItem
 };