@kaddo/mcp 3.117.0 → 3.119.0

package/dist/index.js

@@ -389,7 +389,7 @@ function join(...parts) {
 }
 
 // ../cli/src/core/impact-report.ts
-import matter10 from "gray-matter";
+import matter11 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
@@ -691,12 +691,12 @@ function classifyLayer(posixPath) {
   return "unknown";
 }
 function enrich(dir, a2) {
-  const posix = toPosix2(a2.filePath);
+  const posix3 = toPosix2(a2.filePath);
   const isWi = isWorkItemArtifact(a2);
   return {
     ...a2,
     relPath: relativeTo(dir, a2.filePath),
-    layer: classifyLayer(posix),
+    layer: classifyLayer(posix3),
     isWorkItem: isWi,
     lifecycle: isWi ? lifecycleStateOf({ status: a2.status, filePath: a2.filePath }) : void 0
   };
@@ -3914,8 +3914,8 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
   const project = loadConfig(dir)?.project.name ?? "unknown";
   const questions = [];
   let seq = 0;
-  for (const source of SOURCES) {
-    const p = join(dir, source);
+  for (const source3 of SOURCES) {
+    const p = join(dir, source3);
     if (!exists(p)) continue;
     let md;
     try {
@@ -3928,8 +3928,8 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
       const { classification, reason } = classifyQuestion(eq.text);
       questions.push({
         id: `OQ-${String(seq).padStart(3, "0")}`,
-        source,
-        sourcePath: source,
+        source: source3,
+        sourcePath: source3,
         line: eq.line,
         raw: eq.raw,
         section: "Open Questions",
@@ -4360,6 +4360,121 @@ function readPocSummary(dir) {
   };
 }
 
+// ../cli/src/core/poc-report.ts
+import { createHash } from "crypto";
+import matter8 from "gray-matter";
+var POC_REPORT_PREFIX = "poc-report-v";
+var SECRET_LINE = /(^|\s)(?:[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)|(?:token|secret|password|api[_-]?key))\s*[:=]\s*\S+/i;
+var reportName = /^poc-report-v(\d{3,})\.md$/;
+function sha(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function posix(value) {
+  return value.replace(/\\/g, "/");
+}
+function redactSecrets(value) {
+  return value.split(/\r?\n/).map((line) => {
+    if (!SECRET_LINE.test(line)) return line;
+    return line.replace(/([:=]\s*)\S+.*/, "$1[redacted]");
+  }).join("\n");
+}
+function source(dir, path9, kind) {
+  const absolute = join(dir, path9);
+  if (!exists(absolute)) return null;
+  const raw = readFile(absolute);
+  return { path: posix(path9), kind, digest: sha(raw), content: redactSecrets(raw) };
+}
+function reportFiles(dir) {
+  const delivery = join(dir, "knowledge", "delivery");
+  return readDir(delivery).flatMap((name) => {
+    const match = name.match(reportName);
+    if (!match) return [];
+    try {
+      const parsed = matter8(readFile(join(delivery, name)));
+      const fingerprint = typeof parsed.data.source_fingerprint === "string" ? parsed.data.source_fingerprint : "";
+      const manifest = parsed.data.source_manifest;
+      const sourceManifest = manifest && typeof manifest === "object" && !Array.isArray(manifest) ? Object.fromEntries(Object.entries(manifest).filter(([, digest]) => typeof digest === "string")) : {};
+      return [{ path: `knowledge/delivery/${name}`, version: Number(match[1]), sourceFingerprint: fingerprint, sourceManifest }];
+    } catch {
+      return [];
+    }
+  }).sort((a2, b2) => b2.version - a2.version);
+}
+function reportPath(version) {
+  return `knowledge/delivery/${POC_REPORT_PREFIX}${String(version).padStart(3, "0")}.md`;
+}
+function buildPocReportContext(dir) {
+  const poc = readPocSummary(dir);
+  const reports = reportFiles(dir);
+  const latestReport = reports[0] ?? null;
+  const nextPath = reportPath((latestReport?.version ?? 0) + 1);
+  if (!poc.exists || poc.conclusion === "pending") {
+    return {
+      eligible: false,
+      conclusion: poc.conclusion,
+      status: latestReport ? "stale" : "missing",
+      latestReport,
+      nextPath,
+      sourceFingerprint: "",
+      sources: [],
+      changesSinceLatest: [],
+      handoff: "POC conclusion is still pending. Record validated, rejected, or inconclusive before generating a final report."
+    };
+  }
+  const sources = [];
+  const add = (path9, kind) => {
+    if (sources.some((item2) => item2.path === posix(path9))) return;
+    const item = source(dir, path9, kind);
+    if (item) sources.push(item);
+  };
+  add(POC_ARTIFACT_PATH, "poc");
+  const pocText = readFile(join(dir, POC_ARTIFACT_PATH));
+  const knowledge = discoverKnowledge(dir);
+  const workItems = discoverWorkItems(dir);
+  const referencedWorkItems = workItems.filter((wi) => wi.lifecycle === "completed" && wi.id && new RegExp(`\\b${wi.id}\\b`).test(pocText));
+  const resourceIds = /* @__PURE__ */ new Set();
+  const decisionIds = /* @__PURE__ */ new Set();
+  for (const wi of referencedWorkItems) {
+    add(wi.relPath, "work-item");
+    for (const resource of parseWorkItemResources(wi.rawFrontmatter)) resourceIds.add(resource.id);
+    const decisions = wi.rawFrontmatter.decisions;
+    if (Array.isArray(decisions)) decisions.forEach((id) => decisionIds.add(String(id)));
+  }
+  for (const id of resourceIds) {
+    const resource = getResource(dir, id);
+    if (resource) add(resource.path, "resource");
+  }
+  for (const artifact of knowledge) {
+    if (artifact.isWorkItem || !artifact.id) continue;
+    if (decisionIds.has(artifact.id) || referencedWorkItems.some((wi) => new RegExp(`\\b${artifact.id}\\b`).test(readFile(wi.filePath)))) add(artifact.relPath, "knowledge");
+  }
+  sources.sort((a2, b2) => a2.path.localeCompare(b2.path));
+  const sourceFingerprint = sha(sources.map((item) => `${item.path}\0${item.digest}`).join("\n"));
+  const status = !latestReport ? "missing" : latestReport.sourceFingerprint === sourceFingerprint ? "current" : "stale";
+  const currentManifest = Object.fromEntries(sources.map((item) => [item.path, item.digest]));
+  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path9) => currentManifest[path9] !== latestReport?.sourceManifest[path9]).sort() : [];
+  const sourceList = sources.map((item) => `- ${item.path} (${item.kind})`).join("\n") || "- No sources selected.";
+  return {
+    eligible: true,
+    conclusion: poc.conclusion,
+    status,
+    latestReport,
+    nextPath,
+    sourceFingerprint,
+    sources,
+    changesSinceLatest,
+    handoff: [
+      "Create a POC Final Report from the supplied sources only. Do not explore the repository.",
+      `Canonical conclusion: ${poc.conclusion}. Do not contradict it.`,
+      "Use the 15 canonical sections. Mark missing evidence as Not evaluated, Not applicable, or No evidence available.",
+      "Distinguish measured, calculated, estimated, and projected values. Never include secret values.",
+      "",
+      "Selected sources:",
+      sourceList
+    ].join("\n")
+  };
+}
+
 // ../cli/src/core/next-step.ts
 function buildDeliveryState(dir) {
   const wis = discoverWorkItems(dir);
@@ -4450,7 +4565,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (projectMode(config) === "poc") {
     const poc = readPocSummary(dir);
     if (!poc.exists) {
-      return { id: "bootstrap", phase: "Setup", label: "Run `kaddo bootstrap` to create the POC knowledge baseline.", command: "kaddo bootstrap", reason: `Missing ${POC_ARTIFACT_PATH}.` };
+      return { id: "poc-artifact", phase: "POC Definition", label: "Create or restore the POC artifact.", command: "kaddo project mode poc", target: POC_ARTIFACT_PATH, reason: `Missing ${POC_ARTIFACT_PATH}.` };
     }
     if (!poc.hypothesisDefined) {
       return { id: "poc-hypothesis", phase: "POC Definition", label: "Define the POC hypothesis.", target: POC_ARTIFACT_PATH, reason: "The POC needs a testable hypothesis before work begins." };
@@ -4460,12 +4575,9 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     }
     const qCurrentState2 = analyzeKnowledgeArtifact(dir, CS);
     const qCodebase2 = analyzeKnowledgeArtifact(dir, CB);
-    if (qCurrentState2 !== "useful" || qCodebase2 !== "useful") {
+    if (exists(join(dir, ".kaddo", "scan.json")) && (qCurrentState2 !== "useful" || qCodebase2 !== "useful")) {
       return { id: "poc-technical-context", phase: "POC Discovery", label: "Document the minimal technical context for the experiment.", target: qCurrentState2 !== "useful" ? CS : CB, agent: "architecture-agent", reason: "The experiment surface and constraints are not yet sufficiently documented." };
     }
-    if (!exists(join(dir, "knowledge", "resources"))) {
-      return { id: "poc-resources", phase: "POC Discovery", label: "Identify the project resources relevant to the experiment.", command: "kaddo resources list", reason: "No project resource catalog is available for the experiment context." };
-    }
     const delivery = buildDeliveryState(dir);
     if (delivery.total_work_items === 0) {
       return { id: "poc-create-experiment", phase: "Experiment", label: "Create the first experiment Work Item (prefer `spike`).", command: "kaddo create spike", reason: "The POC has no Work Item to produce evidence." };
@@ -4479,7 +4591,11 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     if (poc.conclusion === "pending") {
       return { id: "poc-evaluate", phase: "Evaluation", label: "Evaluate the experiment evidence and record the POC conclusion.", target: POC_ARTIFACT_PATH, reason: "Experiment Work Items are complete but the POC conclusion is pending." };
     }
-    return { id: "poc-complete", phase: "Conclusion", label: `POC concluded: ${poc.conclusion}. Decide whether to graduate it to standard delivery.`, target: POC_ARTIFACT_PATH, reason: "The POC conclusion is recorded from experiment evidence." };
+    const report = buildPocReportContext(dir);
+    if (report.status !== "current") {
+      return { id: "poc-final-report", phase: "Conclusion", label: `POC concluded: ${poc.conclusion}. Generate a final report if it would help communicate the result.`, command: "kaddo poc report", target: POC_ARTIFACT_PATH, reason: report.status === "stale" ? "The latest final report is stale after source changes." : "A final report is optional and has not been generated." };
+    }
+    return { id: "poc-complete", phase: "Conclusion", label: `POC concluded: ${poc.conclusion}. Decide whether to graduate it to standard delivery.`, target: POC_ARTIFACT_PATH, reason: "The POC conclusion and final report are current." };
   }
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
@@ -4917,7 +5033,7 @@ function deriveDeliveryCompletedStatus(dir) {
 }
 
 // ../cli/src/core/assets.ts
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 
 // ../cli/src/core/version.ts
 import { fileURLToPath } from "url";
@@ -5593,6 +5709,50 @@ their intersection with the affected areas, and recommended actions.
 - The assessment is proportional \u2014 a small change gets a brief assessment.
 `
 );
+var POC_REPORT_WRITING = skill(
+  "poc-report-writing",
+  "POC Final Report Writing Skill",
+  "delivery",
+  ["implementation-agent", "work-item-agent"],
+  `
+# POC Final Report Writing Skill
+
+## Purpose
+
+Turn a supplied deterministic POC report context into a concise, traceable final report.
+
+## When to use
+
+After a POC has a canonical conclusion and Core has prepared its deterministic report context.
+
+## Rules
+
+- Use only the supplied context; do not scan the repository or infer missing results.
+- Treat \`poc.md\` as canonical for the conclusion. Never contradict it.
+- Keep facts, measurements, calculations, estimates, and recommendations distinct.
+- Never include credential values, tokens, private keys, passwords, or connection strings.
+- Use \`Not evaluated in this POC.\`, \`Not applicable.\`, or \`No evidence available.\` when sources do not support a section.
+- Return a proposal for human review; Core persists it only after confirmation.
+
+## Required structure
+
+1. Executive Summary
+2. Problem and Objective
+3. Hypothesis and Success Criteria
+4. Scope, Constraints and Non-goals
+5. Technical Approach and Architecture
+6. Infrastructure and Project Resources
+7. Implementation and Relevant Technical Decisions
+8. Experiments and Validation
+9. Results and Measurements
+10. Cost and Efficiency Analysis
+11. Observability and Operational Findings
+12. Findings, Learnings, Limitations and Risks
+13. Conclusion
+14. Recommendation and Next Steps
+15. Traceability and Sources
+`
+);
 var SKILLS = [
   ADR_WRITING,
   WORK_ITEM_REFINEMENT,
@@ -5603,10 +5763,11 @@ var SKILLS = [
   IMPLEMENTATION_PLANNING,
   MODULE_CONTEXT_REFINEMENT,
   EVIDENCE_VERIFICATION,
-  LEGACY_RISK_ASSESSMENT
+  LEGACY_RISK_ASSESSMENT,
+  POC_REPORT_WRITING
 ];
 var SKILL_GROUPS = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment", "poc-report-writing"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -8140,7 +8301,7 @@ function canonicalSkills() {
 }
 function versionOf(content) {
   try {
-    const v = matter8(content).data.version;
+    const v = matter9(content).data.version;
     return v === void 0 || v === null ? null : String(v);
   } catch {
     return null;
@@ -8402,9 +8563,9 @@ function parseWorkItemSource(frontmatter) {
     reason: "No source metadata found."
   };
 }
-function renderSourceCompact(source) {
-  const parts = [source.type];
-  if (source.id) parts.push(source.id);
+function renderSourceCompact(source3) {
+  const parts = [source3.type];
+  if (source3.id) parts.push(source3.id);
   return parts.join(" \xB7 ");
 }
 function optStr2(v) {
@@ -8740,6 +8901,11 @@ var definePocHypothesis = {
     return { status: poc.hypothesisDefined ? "done" : "current", evidence: poc.hypothesisDefined ? [POC_ARTIFACT_PATH] : void 0, reason: poc.hypothesisDefined ? void 0 : "A POC starts with one testable hypothesis." };
   }
 };
+var ensurePocArtifact = {
+  id: "poc-artifact",
+  label: "Create POC artifact",
+  evaluate: (ctx) => exists(join(ctx.dir, POC_ARTIFACT_PATH)) ? { status: "done", evidence: [POC_ARTIFACT_PATH] } : { status: "current", command: "kaddo project mode poc", reason: "Create the canonical POC artifact before defining the experiment." }
+};
 var definePocCriteria = {
   id: "poc-success-criteria",
   label: "Define success criteria",
@@ -8748,11 +8914,15 @@ var definePocCriteria = {
     return { status: poc.successCriteriaCount > 0 ? "done" : "pending", evidence: poc.successCriteriaCount > 0 ? [POC_ARTIFACT_PATH] : void 0, reason: poc.successCriteriaCount > 0 ? void 0 : "Define observable evidence for the hypothesis." };
   }
 };
-var describePocTech = { ...describeArchitecture, id: "poc-technical-context", label: "Document minimal technical context" };
+var describePocTech = {
+  id: "poc-technical-context",
+  label: "Document minimal technical context",
+  evaluate: (ctx) => ctx.hasScan ? describeArchitecture.evaluate(ctx) : { status: "optional", command: "kaddo scan", reason: "Add technical context only when the experiment needs to inspect existing code." }
+};
 var identifyPocResources = {
   id: "poc-resources",
   label: "Identify relevant resources",
-  evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "pending", command: "kaddo resources list" }
+  evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "optional", command: "kaddo resources list", reason: "Add Project Resources only when the experiment depends on external systems." }
 };
 var createPocExperiment = {
   id: "poc-create-experiment",
@@ -8772,7 +8942,17 @@ var concludePoc = {
     return conclusion === "pending" ? { status: "pending", reason: "Record validated, rejected, or inconclusive from the evidence." } : { status: "done", evidence: [POC_ARTIFACT_PATH], reason: `Conclusion: ${conclusion}.` };
   }
 };
-var POC_STEPS = [enableKaddo, bootstrapBaseline, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
+var finalPocReport = {
+  id: "poc-final-report",
+  label: "Generate final report (optional)",
+  evaluate: (ctx) => {
+    const report = buildPocReportContext(ctx.dir);
+    if (!report.eligible) return { status: "optional", reason: "Available after recording a POC conclusion." };
+    if (report.status === "current") return { status: "done", evidence: [report.latestReport.path] };
+    return { status: "optional", command: "kaddo poc report", reason: report.status === "stale" ? "Latest report is stale." : "A final report is optional." };
+  }
+};
+var POC_STEPS = [enableKaddo, ensurePocArtifact, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc, finalPocReport];
 function stepsForState(state) {
   switch (state) {
     case "new":
@@ -8876,6 +9056,7 @@ function mapNextStepId(id) {
     "poc-resources": "poc-resources",
     "poc-create-experiment": "poc-create-experiment",
     "poc-evaluate": "poc-evaluate",
+    "poc-final-report": "poc-final-report",
     "poc-complete": "poc-evaluate"
   };
   return MAP[id] ?? id;
@@ -8890,7 +9071,7 @@ function buildProjectRoute(dir) {
     return { id: d3.id, label: d3.label, ...result };
   });
   for (const s of steps) {
-    if (s.id === ctx.nextStepId && s.status !== "done") {
+    if (s.id === ctx.nextStepId && s.status !== "done" && s.status !== "optional") {
       s.status = "current";
     }
   }
@@ -8902,8 +9083,8 @@ function buildProjectRoute(dir) {
       break;
     }
   }
-  const completed = steps.filter((s) => s.status === "done").length;
-  const total = steps.length;
+  const completed = steps.filter((s) => s.status === "done" && s.status !== "optional").length;
+  const total = steps.filter((s) => s.status !== "optional").length;
   const progressPercent = total > 0 ? Math.round(completed / total * 100) : 0;
   return {
     type: state,
@@ -8960,7 +9141,7 @@ function renderRouteCompact(route) {
 }
 
 // ../cli/src/core/metadata-health.ts
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 var KNOWLEDGE_FILES2 = [
   "knowledge/business/business.md",
   "knowledge/product/product.md",
@@ -8980,7 +9161,7 @@ function analyzeMetadataHealth(dir) {
     let data;
     try {
       const raw = readFile(p);
-      data = matter9(raw).data;
+      data = matter10(raw).data;
     } catch {
       continue;
     }
@@ -9012,7 +9193,7 @@ function analyzeMetadataHealth(dir) {
         if (isFile(p) && entry.endsWith(".md")) {
           try {
             const raw = readFile(p);
-            const fm = matter9(raw).data;
+            const fm = matter10(raw).data;
             if (fm.status === "done") {
               const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
               findings.push({
@@ -9967,7 +10148,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter10(readFile(wi.filePath)).content;
+      const body = matter11(readFile(wi.filePath)).content;
       if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
       else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
       if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -10375,7 +10556,7 @@ function parseRatioNumerator(s) {
 }
 var SAVINGS_DISCLAIMER = "These are evidence-based estimates, not exact ROI. Adjust assumptions with real team data.";
 function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
-  const { assumptions: a2, source } = loadAssumptions(dir);
+  const { assumptions: a2, source: source3 } = loadAssumptions(dir);
   const impact = buildImpactReport(dir, { scope: opts.scope, scopeSource: opts.scopeSource }, now);
   const completed = impact.traceability.completed_work_items;
   const wiWithOwnership = parseRatioNumerator(impact.traceability.work_items_connected_to_code);
@@ -10415,7 +10596,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   if (impact.score === null || impact.score < 60 || graphQuality === "empty") {
     level = "Low";
     reasons.push("Impact score is low or the knowledge graph is empty.");
-  } else if (impact.score >= 85 && graphQuality === "good" && source === "file" && guard.available && guard.resolved > 0) {
+  } else if (impact.score >= 85 && graphQuality === "good" && source3 === "file" && guard.available && guard.resolved > 0) {
     level = "High";
     reasons.push("Strong evidence, custom assumptions and recorded drift resolution.");
   } else {
@@ -10429,9 +10610,9 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   } else {
     reasons.push("Guard history available, but no resolved drift warnings have been recorded yet.");
   }
-  reasons.push(source === "file" ? "Assumptions come from `.kaddo/savings.yml`." : "Savings assumptions are defaults and should be calibrated.");
+  reasons.push(source3 === "file" ? "Assumptions come from `.kaddo/savings.yml`." : "Savings assumptions are defaults and should be calibrated.");
   const actions = [];
-  if (source === "default") actions.push("Run `kaddo savings init` to customize assumptions.");
+  if (source3 === "default") actions.push("Run `kaddo savings init` to customize assumptions.");
   actions.push("Calibrate hourly cost and team assumptions with real team data.");
   actions.push("Run `kaddo impact` to verify the underlying evidence quality.");
   actions.push("Use this report as directional evidence, not accounting data.");
@@ -10449,7 +10630,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
     scope: impact.scope,
     currency: a2.currency,
     disclaimer: SAVINGS_DISCLAIMER,
-    assumptions_source: source,
+    assumptions_source: source3,
     assumptions: {
       hourly_cost: a2.hourly_cost,
       context_preparation_minutes_saved_per_work_item: a2.context_preparation_minutes_saved_per_work_item,
@@ -10680,7 +10861,7 @@ function serializeDriftJson(r2) {
 }
 
 // src/workitems.ts
-import matter11 from "gray-matter";
+import matter12 from "gray-matter";
 var VALID_SOURCES2 = /* @__PURE__ */ new Set(["manual", "roadmap", "jira", "github", "notion", "xlsx", "csv", "api", "external", "unknown"]);
 function optStr3(v) {
   return typeof v === "string" && v.trim() ? v.trim() : void 0;
@@ -10771,7 +10952,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter11(raw);
+      parsed = matter12(raw);
     } catch {
       continue;
     }
@@ -10780,8 +10961,8 @@ function listWorkItems(root) {
     const status = lifecycleOf(data, rel);
     const code = strArray2(data.code);
     const domains = strArray2(data.domains);
-    const source = parseSource(data);
-    const readiness = status === "draft" ? assessReadiness(data, parsed.content, code, domains, source) : void 0;
+    const source3 = parseSource(data);
+    const readiness = status === "draft" ? assessReadiness(data, parsed.content, code, domains, source3) : void 0;
     items.push({
       id: String(data.id ?? "") || rel,
       title: String(data.title ?? ""),
@@ -10794,7 +10975,7 @@ function listWorkItems(root) {
       capabilities: strArray2(data.capabilities),
       decisions: strArray2(data.decisions),
       capsules: strArray2(data.capsules),
-      source,
+      source: source3,
       domains,
       readiness,
       ...data.implementation_status ? { implementation_status: String(data.implementation_status) } : {},
@@ -10811,7 +10992,7 @@ function listWorkItems(root) {
   }
   return items.sort((a2, b2) => a2.id.localeCompare(b2.id));
 }
-function assessReadiness(data, content, code, domains, source) {
+function assessReadiness(data, content, code, domains, source3) {
   const body = content.trim();
   const lower = body.toLowerCase();
   const warnings = [];
@@ -10965,9 +11146,28 @@ var RESOURCES = [
       root,
       "kaddo://poc",
       "knowledge/delivery/poc.md",
-      "POC artifact not found. Set `project.mode: poc` and run `kaddo bootstrap` first."
+      "POC artifact not found. Initialize in POC mode or switch with `kaddo project mode poc`."
     )
   },
+  {
+    uri: "kaddo://poc-report",
+    name: "Kaddo final POC report",
+    description: "Latest final POC report, or deterministic report status and source selection.",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const context = buildPocReportContext(root);
+      if (context.latestReport) {
+        const saved = readText(root, context.latestReport.path);
+        if (saved) return text2("kaddo://poc-report", saved);
+      }
+      const lines = [
+        `Final POC report: ${context.status}`,
+        `Conclusion: ${context.conclusion}`,
+        context.handoff
+      ];
+      return text2("kaddo://poc-report", lines.join("\n\n"));
+    }
+  },
   {
     uri: "kaddo://capsules",
     name: "Kaddo knowledge capsules",
@@ -11251,14 +11451,14 @@ function getPrompt(root, name) {
 }
 
 // src/tools.ts
-import matter15 from "gray-matter";
+import matter16 from "gray-matter";
 
 // ../cli/dist/core.js
 import fs3 from "fs";
 import path3 from "path";
 import { z as z3 } from "zod";
 import { parse as parseYaml10, stringify as stringifyYaml5 } from "yaml";
-import matter12 from "gray-matter";
+import matter13 from "gray-matter";
 import matter22 from "gray-matter";
 import { parse as parseYaml62, stringify as stringifyYaml42 } from "yaml";
 import { parse as parseYaml22 } from "yaml";
@@ -11269,25 +11469,27 @@ import matter32 from "gray-matter";
 import matter42 from "gray-matter";
 import matter52 from "gray-matter";
 import { parse as parseYaml72 } from "yaml";
+import { createHash as createHash2 } from "crypto";
 import matter62 from "gray-matter";
+import matter72 from "gray-matter";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname2, join as join22, parse as parse2 } from "path";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import matter72 from "gray-matter";
 import matter82 from "gray-matter";
 import matter92 from "gray-matter";
+import matter102 from "gray-matter";
 import { parse as parseYaml82, stringify as stringifyYaml52 } from "yaml";
 import fs4 from "fs";
 import path4 from "path";
 import crypto2 from "crypto";
-import matter102 from "gray-matter";
+import matter112 from "gray-matter";
 import crypto3 from "crypto";
 import fs5 from "fs";
-import matter112 from "gray-matter";
 import matter122 from "gray-matter";
+import matter132 from "gray-matter";
 import { parse as parseYaml92, stringify as stringifyYaml6 } from "yaml";
 import { parse as parseYaml102, stringify as stringifyYaml7 } from "yaml";
-import matter13 from "gray-matter";
+import matter14 from "gray-matter";
 function exists2(p) {
   return fs3.existsSync(p);
 }
@@ -11463,7 +11665,7 @@ function parseImpactAnalysis2(data) {
 }
 function parseArtifact2(filePath, raw) {
   try {
-    const { data } = matter12(raw);
+    const { data } = matter13(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -11577,12 +11779,12 @@ function classifyLayer2(posixPath) {
   return "unknown";
 }
 function enrich2(dir, a2) {
-  const posix = toPosix7(a2.filePath);
+  const posix22 = toPosix7(a2.filePath);
   const isWi = isWorkItemArtifact2(a2);
   return {
     ...a2,
     relPath: relativeTo2(dir, a2.filePath),
-    layer: classifyLayer2(posix),
+    layer: classifyLayer2(posix22),
     isWorkItem: isWi,
     lifecycle: isWi ? lifecycleStateOf2({ status: a2.status, filePath: a2.filePath }) : void 0
   };
@@ -13612,6 +13814,177 @@ function buildTechDecisions2(dir) {
 function hasUnmaterializedDecisions(td) {
   return td.candidates > 0 && td.adrs === 0;
 }
+var POC_ARTIFACT_PATH2 = "knowledge/delivery/poc.md";
+var PLACEHOLDER2 = /^[_<].*[_>]$|^(describe|list|document|what|how)\b/i;
+function section3(markdown, heading) {
+  const match = markdown.match(new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im"));
+  return match?.[1] ?? "";
+}
+function meaningful2(text22) {
+  return text22.split(/\r?\n/).some((line) => {
+    const value = line.trim().replace(/^[-*]\s+(?:\[[^\]]+\]\s*)?/, "");
+    return Boolean(value) && !PLACEHOLDER2.test(value) && !/^status:\s*(pending|tbd)$/i.test(value);
+  });
+}
+function readPocSummary2(dir) {
+  const path52 = join3(dir, POC_ARTIFACT_PATH2);
+  if (!exists2(path52)) {
+    return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
+  }
+  let markdown = "";
+  try {
+    markdown = readFile2(path52);
+  } catch {
+    return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
+  }
+  const criteria = section3(markdown, "Success Criteria").split(/\r?\n/).filter((line) => /^\s*[-*]\s+(?:\[[ xX]\]\s+)?/.test(line)).filter((line) => meaningful2(line)).length;
+  const conclusionBody = section3(markdown, "Conclusion");
+  const conclusionMatch = conclusionBody.match(/\b(?:status|outcome)\s*:\s*(validated|rejected|inconclusive)\b/i);
+  return {
+    exists: true,
+    hypothesisDefined: meaningful2(section3(markdown, "Hypothesis")),
+    successCriteriaCount: criteria,
+    constraintsDefined: meaningful2(section3(markdown, "Constraints")),
+    nonGoalsDefined: meaningful2(section3(markdown, "Non-goals")),
+    conclusion: conclusionMatch ? conclusionMatch[1].toLowerCase() : "pending"
+  };
+}
+var POC_REPORT_PREFIX2 = "poc-report-v";
+var SECRET_LINE2 = /(^|\s)(?:[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)|(?:token|secret|password|api[_-]?key))\s*[:=]\s*\S+/i;
+var reportName2 = /^poc-report-v(\d{3,})\.md$/;
+function sha2(value) {
+  return createHash2("sha256").update(value).digest("hex");
+}
+function posix2(value) {
+  return value.replace(/\\/g, "/");
+}
+function redactSecrets2(value) {
+  return value.split(/\r?\n/).map((line) => {
+    if (!SECRET_LINE2.test(line)) return line;
+    return line.replace(/([:=]\s*)\S+.*/, "$1[redacted]");
+  }).join("\n");
+}
+function source2(dir, path52, kind) {
+  const absolute = join3(dir, path52);
+  if (!exists2(absolute)) return null;
+  const raw = readFile2(absolute);
+  return { path: posix2(path52), kind, digest: sha2(raw), content: redactSecrets2(raw) };
+}
+function reportFiles2(dir) {
+  const delivery = join3(dir, "knowledge", "delivery");
+  return readDir2(delivery).flatMap((name) => {
+    const match = name.match(reportName2);
+    if (!match) return [];
+    try {
+      const parsed = matter62(readFile2(join3(delivery, name)));
+      const fingerprint = typeof parsed.data.source_fingerprint === "string" ? parsed.data.source_fingerprint : "";
+      const manifest = parsed.data.source_manifest;
+      const sourceManifest = manifest && typeof manifest === "object" && !Array.isArray(manifest) ? Object.fromEntries(Object.entries(manifest).filter(([, digest]) => typeof digest === "string")) : {};
+      return [{ path: `knowledge/delivery/${name}`, version: Number(match[1]), sourceFingerprint: fingerprint, sourceManifest }];
+    } catch {
+      return [];
+    }
+  }).sort((a2, b2) => b2.version - a2.version);
+}
+function reportPath2(version) {
+  return `knowledge/delivery/${POC_REPORT_PREFIX2}${String(version).padStart(3, "0")}.md`;
+}
+function buildPocReportContext2(dir) {
+  const poc = readPocSummary2(dir);
+  const reports = reportFiles2(dir);
+  const latestReport = reports[0] ?? null;
+  const nextPath = reportPath2((latestReport?.version ?? 0) + 1);
+  if (!poc.exists || poc.conclusion === "pending") {
+    return {
+      eligible: false,
+      conclusion: poc.conclusion,
+      status: latestReport ? "stale" : "missing",
+      latestReport,
+      nextPath,
+      sourceFingerprint: "",
+      sources: [],
+      changesSinceLatest: [],
+      handoff: "POC conclusion is still pending. Record validated, rejected, or inconclusive before generating a final report."
+    };
+  }
+  const sources = [];
+  const add = (path52, kind) => {
+    if (sources.some((item2) => item2.path === posix2(path52))) return;
+    const item = source2(dir, path52, kind);
+    if (item) sources.push(item);
+  };
+  add(POC_ARTIFACT_PATH2, "poc");
+  const pocText = readFile2(join3(dir, POC_ARTIFACT_PATH2));
+  const knowledge = discoverKnowledge2(dir);
+  const workItems = discoverWorkItems2(dir);
+  const referencedWorkItems = workItems.filter((wi) => wi.lifecycle === "completed" && wi.id && new RegExp(`\\b${wi.id}\\b`).test(pocText));
+  const resourceIds = /* @__PURE__ */ new Set();
+  const decisionIds = /* @__PURE__ */ new Set();
+  for (const wi of referencedWorkItems) {
+    add(wi.relPath, "work-item");
+    for (const resource of parseWorkItemResources2(wi.rawFrontmatter)) resourceIds.add(resource.id);
+    const decisions = wi.rawFrontmatter.decisions;
+    if (Array.isArray(decisions)) decisions.forEach((id) => decisionIds.add(String(id)));
+  }
+  for (const id of resourceIds) {
+    const resource = getResource2(dir, id);
+    if (resource) add(resource.path, "resource");
+  }
+  for (const artifact of knowledge) {
+    if (artifact.isWorkItem || !artifact.id) continue;
+    if (decisionIds.has(artifact.id) || referencedWorkItems.some((wi) => new RegExp(`\\b${artifact.id}\\b`).test(readFile2(wi.filePath)))) add(artifact.relPath, "knowledge");
+  }
+  sources.sort((a2, b2) => a2.path.localeCompare(b2.path));
+  const sourceFingerprint = sha2(sources.map((item) => `${item.path}\0${item.digest}`).join("\n"));
+  const status = !latestReport ? "missing" : latestReport.sourceFingerprint === sourceFingerprint ? "current" : "stale";
+  const currentManifest = Object.fromEntries(sources.map((item) => [item.path, item.digest]));
+  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path52) => currentManifest[path52] !== latestReport?.sourceManifest[path52]).sort() : [];
+  const sourceList = sources.map((item) => `- ${item.path} (${item.kind})`).join("\n") || "- No sources selected.";
+  return {
+    eligible: true,
+    conclusion: poc.conclusion,
+    status,
+    latestReport,
+    nextPath,
+    sourceFingerprint,
+    sources,
+    changesSinceLatest,
+    handoff: [
+      "Create a POC Final Report from the supplied sources only. Do not explore the repository.",
+      `Canonical conclusion: ${poc.conclusion}. Do not contradict it.`,
+      "Use the 15 canonical sections. Mark missing evidence as Not evaluated, Not applicable, or No evidence available.",
+      "Distinguish measured, calculated, estimated, and projected values. Never include secret values.",
+      "",
+      "Selected sources:",
+      sourceList
+    ].join("\n")
+  };
+}
+function canonicalReport(context, proposal) {
+  const supersedes = context.latestReport?.path.split("/").pop();
+  const data = {
+    type: "poc-report",
+    report_version: Number(context.nextPath.match(/v(\d+)\.md$/)?.[1] ?? 1),
+    generated_at: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    poc_conclusion: context.conclusion,
+    source_fingerprint: context.sourceFingerprint,
+    sources: context.sources.map((item) => item.path),
+    source_manifest: Object.fromEntries(context.sources.map((item) => [item.path, item.digest]))
+  };
+  if (supersedes) data.supersedes = supersedes;
+  return matter62.stringify(redactSecrets2(proposal).trimEnd() + "\n", data);
+}
+function persistPocReport(dir, proposal, opts = {}) {
+  const context = buildPocReportContext2(dir);
+  if (!context.eligible) throw new Error(context.handoff);
+  if (context.status === "current" && !opts.force) return { status: "current", path: context.latestReport.path, message: "The current POC report already represents the latest evidence." };
+  if (!opts.confirm) return { status: "needs_confirmation", path: context.nextPath, content: canonicalReport(context, proposal), message: "Review the proposed report and confirm persistence." };
+  const output = join3(dir, context.nextPath);
+  if (exists2(output)) throw new Error(`POC report already exists: ${context.nextPath}`);
+  const content = canonicalReport(context, proposal);
+  writeFile2(output, content);
+  return { status: "persisted", path: context.nextPath, content };
+}
 function resolveVersion2() {
   try {
     let dir = dirname2(fileURLToPath2(import.meta.url));
@@ -14280,6 +14653,50 @@ their intersection with the affected areas, and recommended actions.
 - The assessment is proportional \u2014 a small change gets a brief assessment.
 `
 );
+var POC_REPORT_WRITING2 = skill2(
+  "poc-report-writing",
+  "POC Final Report Writing Skill",
+  "delivery",
+  ["implementation-agent", "work-item-agent"],
+  `
+# POC Final Report Writing Skill
+
+## Purpose
+
+Turn a supplied deterministic POC report context into a concise, traceable final report.
+
+## When to use
+
+After a POC has a canonical conclusion and Core has prepared its deterministic report context.
+
+## Rules
+
+- Use only the supplied context; do not scan the repository or infer missing results.
+- Treat \`poc.md\` as canonical for the conclusion. Never contradict it.
+- Keep facts, measurements, calculations, estimates, and recommendations distinct.
+- Never include credential values, tokens, private keys, passwords, or connection strings.
+- Use \`Not evaluated in this POC.\`, \`Not applicable.\`, or \`No evidence available.\` when sources do not support a section.
+- Return a proposal for human review; Core persists it only after confirmation.
+
+## Required structure
+
+1. Executive Summary
+2. Problem and Objective
+3. Hypothesis and Success Criteria
+4. Scope, Constraints and Non-goals
+5. Technical Approach and Architecture
+6. Infrastructure and Project Resources
+7. Implementation and Relevant Technical Decisions
+8. Experiments and Validation
+9. Results and Measurements
+10. Cost and Efficiency Analysis
+11. Observability and Operational Findings
+12. Findings, Learnings, Limitations and Risks
+13. Conclusion
+14. Recommendation and Next Steps
+15. Traceability and Sources
+`
+);
 var SKILLS2 = [
   ADR_WRITING2,
   WORK_ITEM_REFINEMENT2,
@@ -14290,10 +14707,11 @@ var SKILLS2 = [
   IMPLEMENTATION_PLANNING2,
   MODULE_CONTEXT_REFINEMENT2,
   EVIDENCE_VERIFICATION2,
-  LEGACY_RISK_ASSESSMENT2
+  LEGACY_RISK_ASSESSMENT2,
+  POC_REPORT_WRITING2
 ];
 var SKILL_GROUPS2 = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment", "poc-report-writing"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -17138,7 +17556,6 @@ var LEGACY_STEPS2 = [
   runGuard2,
   captureLearning2
 ];
-var describePocTech2 = { ...describeArchitecture2, id: "poc-technical-context", label: "Document minimal technical context" };
 var USER_FACING_KEYWORDS_EN = [
   "user",
   "visitor",
@@ -17542,7 +17959,7 @@ function parseOriginalSnapshot(fm) {
 function readBody(filePath) {
   try {
     const raw = readFile2(filePath);
-    return matter92(raw).content;
+    return matter102(raw).content;
   } catch {
     return "";
   }
@@ -17827,7 +18244,7 @@ function ensureH1(body, title) {
 ${trimmed}`;
 }
 function serialize2(data, body) {
-  return matter102.stringify(`
+  return matter112.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -17862,7 +18279,7 @@ function createWorkItem(dir, opts) {
   const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
   const today22 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = opts.summary?.trim() || intent;
-  const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
+  const source22 = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
   const data = {
     type,
     id,
@@ -17870,7 +18287,7 @@ function createWorkItem(dir, opts) {
     status: "draft",
     work_type: type,
     created_at: today22,
-    source,
+    source: source22,
     generated_by: "kaddo-admin",
     affected_modules: [],
     summary
@@ -18618,7 +19035,7 @@ function detectFormat(raw) {
   if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
   if (trimmed.startsWith("---")) {
     try {
-      const { data } = matter112(trimmed);
+      const { data } = matter122(trimmed);
       if (data && typeof data === "object" && Object.keys(data).length > 0) {
         const d3 = data;
         if (d3.type === "work-item" || d3.id && typeof d3.id === "string" && /^WI-\d+/.test(d3.id)) {
@@ -18640,7 +19057,7 @@ function parseContent(raw) {
   let bodyText = trimmed;
   if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
     try {
-      const parsed = matter112(trimmed);
+      const parsed = matter122(trimmed);
       frontmatterFields = parsed.data ?? {};
       bodyText = parsed.content.trim();
     } catch {
@@ -18712,12 +19129,12 @@ function normalizeImportFields(parsed, opts) {
   const intent = parsed.title;
   const body = hasRealBody ? parsed.body : void 0;
   const summary = hasRealBody ? deriveShortSummary(parsed) : parsed.title;
-  const source = {
+  const source22 = {
     type: opts.importSource === "chat" ? "chat" : "external",
     imported_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
   };
-  source.source_format = opts.sourceFormat;
-  source.source_hash = opts.sourceHash;
+  source22.source_format = opts.sourceFormat;
+  source22.source_hash = opts.sourceHash;
   const snapshot = { title: parsed.title };
   if (summary !== parsed.title) snapshot.description = summary;
   if (typeof parsed.candidateFields.type === "string") snapshot.type = parsed.candidateFields.type;
@@ -18726,7 +19143,7 @@ function normalizeImportFields(parsed, opts) {
     const labels = parsed.candidateFields.labels.filter((l2) => typeof l2 === "string");
     if (labels.length > 0) snapshot.labels = labels;
   }
-  return { type, intent, summary, body, source, snapshot, discardedFields };
+  return { type, intent, summary, body, source: source22, snapshot, discardedFields };
 }
 function computeContentHash(raw) {
   return crypto3.createHash("sha256").update(raw.trim(), "utf-8").digest("hex");
@@ -18737,10 +19154,10 @@ function findDuplicateByHash(dir, hash) {
     const raw = readFile2(item.filePath);
     if (!raw) continue;
     try {
-      const { data } = matter112(raw);
-      const source = data?.source;
-      if (source && typeof source === "object" && !Array.isArray(source)) {
-        const s = source;
+      const { data } = matter122(raw);
+      const source22 = data?.source;
+      if (source22 && typeof source22 === "object" && !Array.isArray(source22)) {
+        const s = source22;
         if (s.source_hash === hash) {
           return { workItemId: data.id ?? item.id ?? item.title, path: item.relPath };
         }
@@ -19632,7 +20049,7 @@ function buildInitiativeContent(id, input) {
   if (input.priority) data.priority = input.priority;
   if (input.source) data.source = input.source;
   if (input.sourceId) data.source_id = input.sourceId;
-  return matter13.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
+  return matter14.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
 }
 function createInitiative(dir, input) {
   if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -19656,10 +20073,10 @@ function transitionInitiative(dir, id, to) {
     throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
   }
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter13(raw, {});
+  const { data, content } = matter14(raw, {});
   data.status = to;
   if (to === "completed") data.completed_at = today2();
-  const newContent = matter13.stringify(content, data);
+  const newContent = matter14.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -19669,7 +20086,7 @@ function addCandidate(dir, id, candidate) {
   const ini = getInitiative(dir, id);
   if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter13(raw, {});
+  const { data, content } = matter14(raw, {});
   const existing = Array.isArray(data.candidates) ? data.candidates : [];
   const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
   const normalized = normalizeCandidate(candidate, fallbackId);
@@ -19677,7 +20094,7 @@ function addCandidate(dir, id, candidate) {
     throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
   }
   data.candidates = [...existing, candidateToData(normalized)];
-  const newContent = matter13.stringify(content, data);
+  const newContent = matter14.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
@@ -19687,7 +20104,7 @@ function updateInitiative(dir, id, patch) {
   const ini = getInitiative(dir, id);
   if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter13(raw, {});
+  const { data, content } = matter14(raw, {});
   if (patch.title !== void 0) {
     if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
     data.title = patch.title.trim();
@@ -19697,7 +20114,7 @@ function updateInitiative(dir, id, patch) {
   if (patch.knowledgeLevel !== void 0) data.knowledge_level = patch.knowledgeLevel;
   if (patch.domains !== void 0) data.domains = patch.domains;
   if (patch.relatedCapabilities !== void 0) data.related_capabilities = patch.relatedCapabilities;
-  const newContent = matter13.stringify(content, data);
+  const newContent = matter14.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
@@ -19715,10 +20132,10 @@ function addExternalLink(dir, id, link) {
     throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
   }
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter13(raw, {});
+  const { data, content } = matter14(raw, {});
   const existing = Array.isArray(data.external_links) ? data.external_links : [];
   data.external_links = [...existing, externalLinkToData(link)];
-  const newContent = matter13.stringify(content, data);
+  const newContent = matter14.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
@@ -19787,7 +20204,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
     "_What did we learn? Update after completion._",
     ""
   ].join("\n");
-  return matter13.stringify("\n" + body, data);
+  return matter14.stringify("\n" + body, data);
 }
 function materializeCandidate(dir, id, candidateId) {
   const ini = getInitiative(dir, id);
@@ -19804,13 +20221,13 @@ function materializeCandidate(dir, id, candidateId) {
   ensureDir2(join3(dir, DRAFT_DIR));
   writeFile2(join3(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter13(raw, {});
+  const { data, content } = matter14(raw, {});
   const cands = Array.isArray(data.candidates) ? data.candidates : [];
   for (const c of cands) {
     if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
   }
   data.candidates = cands;
-  const newContent = matter13.stringify(content, data);
+  const newContent = matter14.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -19924,7 +20341,7 @@ function evaluateInitiativeCompletion(dir, ini) {
 // ../cli/src/core/resource-write.ts
 import fs6 from "fs";
 import path5 from "path";
-import matter14 from "gray-matter";
+import matter15 from "gray-matter";
 var RESOURCES_DIR = "knowledge/tech/resources";
 var ResourceWriteError = class extends Error {
   constructor(code, message) {
@@ -20004,7 +20421,7 @@ function buildFrontmatter(id, input, base = {}) {
   return data;
 }
 function serialize(data, body) {
-  return matter14.stringify(`
+  return matter15.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -20044,7 +20461,7 @@ function updateResource(dir, id, input) {
     throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f3) => f3.level === "error").map((f3) => f3.message).join("; "));
   }
   const raw = readFile(match.filePath);
-  const parsed = matter14(raw);
+  const parsed = matter15(raw);
   const base = parsed.data ?? {};
   const data = buildFrontmatter(match.id || id, input, base);
   let body = parsed.content.trim();
@@ -20082,6 +20499,17 @@ function deleteResource(dir, id, opts = {}) {
 // src/tools.ts
 var ok = (data) => ({ ok: true, data });
 var fail = (message) => ({ ok: false, message });
+function preparePocReportTool(root) {
+  const context = buildPocReportContext2(root);
+  return context.eligible ? ok(context) : fail(context.handoff);
+}
+function persistPocReportTool(root, proposal, confirm2, force) {
+  try {
+    return ok(persistPocReport(root, proposal, { confirm: confirm2, force }));
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}
 function projectStatus(root) {
   const explain = readJson(root, ".kaddo/explain.json");
   const hints = readJson(root, ".kaddo/graph-hints.json");
@@ -20174,12 +20602,12 @@ function markWorkItemReady(root, id, confirm2) {
   }
   const raw = readText(root, item.path);
   if (!raw) return fail(`Could not read Work Item file: ${item.path}`);
-  const parsed = matter15(raw);
+  const parsed = matter16(raw);
   const data = { ...parsed.data };
   const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
   data.ready_at = today3;
-  const newContent = matter15.stringify(parsed.content, data);
+  const newContent = matter16.stringify(parsed.content, data);
   const posixPath = item.path.replace(/\\/g, "/");
   let newRelPath = item.path;
   if (posixPath.includes("/work-items/draft/")) {
@@ -20241,12 +20669,12 @@ function listGraphHints(root, filter = {}) {
   });
 }
 function importWorkItemTool(root, args) {
-  const source = args.source === "cli" || args.source === "admin" ? args.source : "chat";
+  const source3 = args.source === "cli" || args.source === "admin" ? args.source : "chat";
   const onConflict = args.onConflict === "replace" || args.onConflict === "new-id" ? args.onConflict : void 0;
   try {
     const result = importWorkItem(root, {
       content: args.content,
-      source,
+      source: source3,
       type: args.type,
       onConflict
     });
@@ -20407,7 +20835,7 @@ function deleteResourceTool(root, id, confirm2) {
 // src/multirepo.ts
 import fs7 from "fs";
 import path6 from "path";
-import matter16 from "gray-matter";
+import matter17 from "gray-matter";
 import { parse as parseYaml11, stringify as stringifyYaml8 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
@@ -20559,7 +20987,7 @@ function validateWorkItemModulesTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter16(raw);
+  const parsed = matter17(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -20612,7 +21040,7 @@ function getWorkItemContextTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter16(raw);
+  const parsed = matter17(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -20698,7 +21126,7 @@ function suggestBranchStrategyTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter16(raw);
+  const parsed = matter17(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -21307,10 +21735,10 @@ function getSystemNeighbors(dir, nodeId, opts = {}) {
   }
   return { seed: nodeId, nodes, relationships: rels, truncated };
 }
-function findSystemPaths(dir, source, target, opts = {}) {
+function findSystemPaths(dir, source3, target, opts = {}) {
   const projection = getSystemMapProjection2(dir);
   const byId = new Map(projection.nodes.map((n) => [n.id, n]));
-  if (!byId.has(source) || !byId.has(target)) return [];
+  if (!byId.has(source3) || !byId.has(target)) return [];
   const maxDepth = Math.max(1, opts.maxDepth ?? 4);
   const out = /* @__PURE__ */ new Map();
   for (const r2 of projection.relationships) {
@@ -21330,7 +21758,7 @@ function findSystemPaths(dir, source, target, opts = {}) {
       walk(nxt, [...path9, nxt]);
     }
   };
-  walk(source, [source]);
+  walk(source3, [source3]);
   return paths;
 }
 function getImpactCandidates(dir, seedIds, opts = {}) {
@@ -21458,14 +21886,14 @@ function systemImpactCandidatesTool(root, args) {
 }
 
 // ../cli/src/services/integrations.ts
-import matter18 from "gray-matter";
+import matter19 from "gray-matter";
 import { parse as parseYaml13, stringify as stringifyYaml10 } from "yaml";
 
 // ../cli/src/core/work-item-write.ts
 import fs9 from "fs";
 import path8 from "path";
 import crypto4 from "crypto";
-import matter17 from "gray-matter";
+import matter18 from "gray-matter";
 var SECTION_ORDER2 = [
   "Actor",
   "Outcome",
@@ -22513,7 +22941,7 @@ async function integrationsWorkItemTool(root, args) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter19 from "gray-matter";
+import matter20 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR4 = "knowledge";
 function readScanJson(dir) {
@@ -22526,7 +22954,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph4(markdown) {
-  const body = matter19(markdown).content.trim();
+  const body = matter20(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -23939,6 +24367,24 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => markWorkItemReady(root, args.id, args.confirm)))
   );
+  server.registerTool(
+    "kaddo_prepare_poc_report",
+    {
+      title: "Prepare final POC report context",
+      description: "Build a deterministic, source-attributed POC report context. Does not call an LLM or write a report.",
+      inputSchema: {}
+    },
+    async () => toolText(guarded(root, () => preparePocReportTool(root)))
+  );
+  server.registerTool(
+    "kaddo_persist_poc_report",
+    {
+      title: "Persist confirmed final POC report",
+      description: "Preview a proposed final POC report by default. With confirm=true, persist the next immutable version. Never provide credential values.",
+      inputSchema: { proposal: z4.string(), confirm: z4.boolean().optional(), force: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => persistPocReportTool(root, args.proposal, args.confirm, args.force)))
+  );
   server.registerTool(
     "kaddo_list_resources",
     { title: "List Project Resources", description: "List external systems the project uses (databases, cloud, APIs\u2026), read-only, no secrets.", inputSchema: {} },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.117.0",
+  "version": "3.119.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {