@kaddo/mcp 3.123.0 → 3.124.1

package/dist/index.js

@@ -10403,6 +10403,39 @@ function buildGuardHistory(dir) {
   };
 }
 
+// ../cli/src/core/reporting-evidence.ts
+function reportingProjectContext(dir) {
+  const config = loadConfig(dir);
+  if (!config) return { state: "unknown", mode: "unknown", repository_structure: "unknown" };
+  return {
+    state: config.project.state,
+    mode: projectMode(config),
+    repository_structure: config.project.structure
+  };
+}
+function knowledgeLayerEvidence(context, layer2, present) {
+  const baseline = context.mode === "poc" ? ["Tech", "Delivery"] : ["Business", "Product", "Tech", "Delivery"];
+  if (!baseline.includes(layer2)) {
+    return { id: `knowledge.${layer2.toLowerCase()}`, label: `${layer2} knowledge`, classification: "not_applicable", reason: "This layer is outside the configured POC baseline." };
+  }
+  return {
+    id: `knowledge.${layer2.toLowerCase()}`,
+    label: `${layer2} knowledge`,
+    classification: present ? "observed" : "unknown",
+    reason: present ? "A structured knowledge artifact is present." : "No structured artifact was found; absence is not proof that knowledge does not exist."
+  };
+}
+function deliveryCapabilityEvidence(dir, context) {
+  const initiatives = discoverInitiatives(dir);
+  const resources = getResources(dir);
+  const modules = loadMappedModules(dir);
+  return [
+    { id: "initiatives", label: "Initiatives", classification: initiatives.length ? "observed" : "not_applicable", reason: initiatives.length ? `${initiatives.length} optional Initiative artifact(s) were discovered.` : "Initiatives are optional and no Initiative artifacts were discovered." },
+    { id: "resources", label: "Project Resources", classification: resources.length ? "observed" : "not_applicable", reason: resources.length ? `${resources.length} Project Resource artifact(s) were discovered.` : "Resources are optional and no Resource artifacts were discovered." },
+    { id: "multirepo", label: "Multirepo mapping", classification: context.repository_structure === "multirepo" ? modules.length ? "observed" : "unknown" : "not_applicable", reason: context.repository_structure === "multirepo" ? modules.length ? `${modules.length} module mapping(s) were discovered.` : "Project is multirepo but no module mappings were found." : "The project is configured as a monorepo." }
+  ];
+}
+
 // ../cli/src/core/impact-report.ts
 function isBroadGlob(glob) {
   if (!glob.endsWith("/**")) return false;
@@ -10422,8 +10455,10 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   const resolvedScope = opts.scope ?? "all";
   const scopeSource = opts.scopeSource ?? (opts.scope ? "explicit" : "default");
   const exp = buildProjectExplanation(dir);
+  const projectContext = reportingProjectContext(dir);
   const wis = discoverWorkItems(dir);
   const total = wis.length;
+  const verifiedWorkItems = wis.filter((wi) => wi.validationStatus === "passed").length;
   let withOwnership = 0;
   let withSource = 0;
   let withInitiative = 0;
@@ -10515,7 +10550,8 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   const knowledge_coverage = [
     { label: "Work Items with ownership", have: withOwnership, total },
     { label: "Work Items with source", have: withSource, total },
-    { label: "Work Items with initiative", have: withInitiative, total },
+    // Initiatives are optional: report their observed use, but do not use absence as a gap or score input.
+    { label: "Work Items using optional initiatives", have: withInitiative, total },
     { label: "Work Items with acceptance criteria", have: withAcceptance, total },
     { label: "Work Items with Definition of Done", have: withDoD, total },
     { label: "Work Items with knowledge level", have: withLevel, total }
@@ -10569,7 +10605,8 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   let score_breakdown = null;
   if (total > 0) {
     const healthPts = [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * 20;
-    const covAvg = knowledge_coverage.reduce((a2, c) => a2 + coverageRatio(c.have), 0) / knowledge_coverage.length;
+    const applicableCoverage = knowledge_coverage.filter((c) => c.label !== "Work Items using optional initiatives");
+    const covAvg = applicableCoverage.reduce((a2, c) => a2 + coverageRatio(c.have), 0) / applicableCoverage.length;
     const coveragePts = covAvg * 20;
     const ownPts = coverageRatio(withOwnership) * 15;
     const traceBlend = (exp.roadmap.candidates > 0 ? exp.roadmap.materialized / exp.roadmap.candidates : 1) * 0.5 + coverageRatio(withOwnership) * 0.5;
@@ -10600,7 +10637,6 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   for (const a2 of [
     groupedAction(gaps.missing_code_ownership, "Add `code:` ownership to"),
     groupedAction(gaps.missing_source, "Add `source`/`source_id` to"),
-    groupedAction(gaps.missing_initiative, "Add an `initiative` to"),
     groupedAction(gaps.missing_acceptance_criteria, "Add Acceptance Criteria to"),
     groupedAction(gaps.missing_definition_of_done, "Add a Definition of Done to"),
     groupedAction(gaps.missing_validation, "Add a validation (How to test it) section to")
@@ -10619,6 +10655,14 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   return {
     generated_at: now.toISOString(),
     project: exp.project.name,
+    project_context: projectContext,
+    evidence: [
+      ...["Business", "Product", "Tech", "Delivery"].map((layer2) => knowledgeLayerEvidence(projectContext, layer2, layerStatus(layer2) !== "Missing")),
+      { id: "work-items.lifecycle", label: "Work Item lifecycle", classification: total > 0 ? "observed" : "unknown", reason: total > 0 ? `${total} Work Item artifact(s) were discovered.` : "No Work Item artifacts were discovered." },
+      { id: "delivery.verification", label: "Verified delivery outcomes", classification: verifiedWorkItems > 0 ? "observed" : "unknown", reason: verifiedWorkItems > 0 ? `${verifiedWorkItems} Work Item(s) have persisted validation_status: passed.` : "Acceptance Criteria and Definition of Done sections show declared intent, not completed verification evidence." },
+      ...deliveryCapabilityEvidence(dir, projectContext),
+      { id: "guard-history", label: "Guard consistency history", classification: buildGuardHistory(dir).available ? "observed" : "unknown", reason: buildGuardHistory(dir).available ? "Recorded Guard runs provide current consistency evidence." : "No recorded Guard history is available." }
+    ],
     scope: g.scope,
     default_scope: "all",
     scope_source: scopeSource,
@@ -10673,9 +10717,10 @@ function renderImpactMarkdown(r2) {
   L.push("# Kaddo Knowledge Impact Report", "");
   L.push(`Generated at: ${r2.generated_at}`);
   L.push(`Project: ${r2.project}`);
+  L.push(`Project context: state=${r2.project_context.state}; mode=${r2.project_context.mode}; repositories=${r2.project_context.repository_structure}`);
   L.push(`Scope: ${r2.scope}`);
-  if (r2.score !== null) L.push(`Knowledge Impact Score: ${r2.score}/100`);
-  else L.push("Knowledge Impact Score: not available");
+  if (r2.score !== null) L.push(`Legacy Knowledge Impact Score: ${r2.score}/100 (deprecated; use Evidence and Applicability)`);
+  else L.push("Legacy Knowledge Impact Score: not available");
   if (r2.scope_source === "default") {
     L.push("Scope note: Impact reports use `all` by default to measure accumulated knowledge impact.");
   } else if (r2.scope === "active" && r2.graph_quality.available === false) {
@@ -10685,6 +10730,9 @@ function renderImpactMarkdown(r2) {
   L.push("## Executive Summary", "");
   for (const s2 of r2.executive_summary) L.push(`- ${s2}`);
   L.push("");
+  L.push("## Evidence and Applicability", "");
+  for (const item of r2.evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
+  L.push("");
   L.push("## Knowledge Health", "");
   for (const [k2, v] of Object.entries(r2.knowledge_health)) L.push(`- ${k2}: ${v}`);
   L.push("");
@@ -10856,6 +10904,7 @@ function loadAssumptions(dir) {
       source: "file",
       assumptions: {
         currency: raw?.currency ?? DEFAULT_ASSUMPTIONS.currency,
+        ...typeof raw?.calibrated_at === "string" && raw.calibrated_at.trim() ? { calibrated_at: raw.calibrated_at.trim() } : {},
         hourly_cost: num(raw?.hourly_cost, DEFAULT_ASSUMPTIONS.hourly_cost),
         context_preparation_minutes_saved_per_work_item: num(a2.context_preparation_minutes_saved_per_work_item, DEFAULT_ASSUMPTIONS.context_preparation_minutes_saved_per_work_item),
         rework_hours_avoided_per_resolved_drift: num(a2.rework_hours_avoided_per_resolved_drift, DEFAULT_ASSUMPTIONS.rework_hours_avoided_per_resolved_drift),
@@ -10882,6 +10931,7 @@ var SAVINGS_DISCLAIMER = "These are evidence-based estimates, not exact ROI. Adj
 function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   const { assumptions: a2, source: source3 } = loadAssumptions(dir);
   const impact = buildImpactReport(dir, { scope: opts.scope, scopeSource: opts.scopeSource }, now);
+  const projectContext = reportingProjectContext(dir);
   const completed = impact.traceability.completed_work_items;
   const wiWithOwnership = parseRatioNumerator(impact.traceability.work_items_connected_to_code);
   const acceptanceCov = impact.knowledge_coverage.find((c) => c.label.toLowerCase().includes("acceptance"));
@@ -10913,20 +10963,28 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       reason: "Guard history exists, but no resolved drift warnings have been recorded yet."
     };
   }
-  const totalHours = round2(ctxPrepH + reviewH + clarH + onboardH + archH + driftSavings.hours);
-  const totalValue = Math.round(totalHours * a2.hourly_cost);
+  const observedHours = round2(ctxPrepH + reviewH + clarH + driftSavings.hours);
+  const projectedHours = round2(onboardH + archH);
+  const observedValue = Math.round(observedHours * a2.hourly_cost);
+  const projectedValue = Math.round(projectedHours * a2.hourly_cost);
   const reasons = [];
   let level;
-  if (impact.score === null || impact.score < 60 || graphQuality === "empty") {
+  const verifiedDelivery = impact.evidence.some((item) => item.id === "delivery.verification" && item.classification === "observed");
+  const evidenceStrong = graphQuality === "good" && impact.ownership_coverage.coverage_percent >= 70 && verifiedDelivery;
+  if (!evidenceStrong || graphQuality === "empty") {
     level = "Low";
-    reasons.push("Impact score is low or the knowledge graph is empty.");
-  } else if (impact.score >= 85 && graphQuality === "good" && source3 === "file" && guard.available && guard.resolved > 0) {
+    reasons.push("Delivery, ownership or graph evidence is insufficient for a reliable estimate.");
+  } else if (evidenceStrong && source3 === "file" && Boolean(a2.calibrated_at) && guard.available && guard.resolved > 0) {
     level = "High";
-    reasons.push("Strong evidence, custom assumptions and recorded drift resolution.");
+    reasons.push("Strong evidence, calibrated assumptions and recorded drift resolution.");
   } else {
     level = "Medium";
     reasons.push("Strong knowledge and graph evidence.");
   }
+  if (!a2.calibrated_at && level === "High") {
+    level = "Medium";
+    reasons.push("Uncalibrated assumptions cannot support High confidence.");
+  }
   if (!guard.available) {
     reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
   } else if (guard.resolved > 0) {
@@ -10951,7 +11009,15 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   return {
     generated_at: now.toISOString(),
     project: impact.project,
+    project_context: projectContext,
     scope: impact.scope,
+    reporting_period: { observed: "all recorded project history", projected: "per month", note: "Historical estimates and future monthly projections are intentionally not added together." },
+    evidence_classification: [
+      { id: "completed-work-items", label: "Completed Work Items", classification: completed > 0 ? "observed" : "unknown", reason: completed > 0 ? "Lifecycle state is recorded in Work Items." : "No completed Work Items were recorded." },
+      { id: "guard-resolution", label: "Resolved drift warnings", classification: guard.available ? "observed" : "unknown", reason: guard.available ? "Derived from recorded Guard history." : "No Guard history was recorded." },
+      { id: "assumptions", label: "Savings assumptions", classification: "estimated", reason: a2.calibrated_at ? `Project assumptions were calibrated on ${a2.calibrated_at}.` : source3 === "file" ? "Project-provided assumptions are not marked as calibrated." : "Defaults are uncalibrated estimates." },
+      { id: "team-expectations", label: "Future team activity", classification: "projected", reason: "Monthly contributor and Work Item expectations model a future scenario." }
+    ],
     currency: a2.currency,
     disclaimer: SAVINGS_DISCLAIMER,
     assumptions_source: source3,
@@ -10985,7 +11051,11 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       architecture_discovery: { hours: archH, formula: `${a2.architecture_discovery_hours_saved_when_graph_good} h \xD7 ${graphMult.toFixed(2)} graph multiplier` },
       drift_prevention: driftSavings
     },
-    total: { estimated_hours_saved: totalHours, estimated_value: totalValue, currency: a2.currency },
+    totals: {
+      observed_history_estimate: { estimated_hours: observedHours, estimated_value: observedValue, currency: a2.currency },
+      monthly_projection: { estimated_hours: projectedHours, estimated_value: projectedValue, currency: a2.currency }
+    },
+    total: { estimated_hours_saved: observedHours, estimated_value: observedValue, currency: a2.currency },
     confidence: { level, reasons },
     suggested_actions: actions
   };
@@ -10995,14 +11065,18 @@ function renderSavingsMarkdown(r2) {
   L.push("# Kaddo Estimated Savings Report", "");
   L.push(`Generated at: ${r2.generated_at}`);
   L.push(`Project: ${r2.project}`);
+  L.push(`Project context: state=${r2.project_context.state}; mode=${r2.project_context.mode}; repositories=${r2.project_context.repository_structure}`);
   L.push(`Scope: ${r2.scope}`);
   L.push(`Currency: ${r2.currency}`);
   L.push("");
   L.push("## Disclaimer", "");
   L.push(r2.disclaimer, "");
+  L.push("## Evidence Classification", "");
+  for (const item of r2.evidence_classification) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
+  L.push("");
   L.push("## Executive Summary", "");
-  L.push(`- Estimated time saved: ${r2.total.estimated_hours_saved} hours`);
-  L.push(`- Estimated value: ${r2.total.estimated_value} ${r2.currency}`);
+  L.push(`- Historical estimate: ${r2.totals.observed_history_estimate.estimated_hours} hours`);
+  L.push(`- Monthly projection: ${r2.totals.monthly_projection.estimated_hours} hours`);
   L.push(`- Confidence: ${r2.confidence.level}`);
   if (r2.assumptions_source === "default") L.push("- Using default assumptions. Run `kaddo savings init` to customize them.");
   L.push("");
@@ -11055,9 +11129,10 @@ function renderSavingsMarkdown(r2) {
     L.push("- Not available yet.");
     L.push(`- Reason: ${s.drift_prevention.reason}`, "");
   }
-  L.push("## Total", "");
-  L.push(`- Estimated time saved: ${r2.total.estimated_hours_saved} h`);
-  L.push(`- Estimated value: ${r2.total.estimated_value} ${r2.currency}`);
+  L.push("## Total (Period-separated)", "");
+  L.push(`- Historical estimate (all recorded project history): ${r2.totals.observed_history_estimate.estimated_hours} h / ${r2.totals.observed_history_estimate.estimated_value} ${r2.currency}`);
+  L.push(`- Monthly projection: ${r2.totals.monthly_projection.estimated_hours} h / ${r2.totals.monthly_projection.estimated_value} ${r2.currency}`);
+  L.push(`- Note: ${r2.reporting_period.note}`);
   L.push("");
   L.push("## Confidence", "");
   L.push(`Confidence: ${r2.confidence.level}`, "", "Reason:");
@@ -11076,6 +11151,14 @@ function serializeSavingsJson(r2) {
 function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
   const h2 = buildGuardHistory(dir);
   const project = loadConfig(dir)?.project.name ?? "unknown";
+  const projectContext = reportingProjectContext(dir);
+  const workItems = discoverWorkItems(dir);
+  const verificationEvidence = workItems.filter((wi) => wi.validationStatus && wi.validationStatus !== "not-started");
+  const plans = getDeprecationPlans(dir);
+  const deprecationFindings = plans.flatMap((plan) => getDeprecationPlan(dir, plan.id)?.targets.flatMap(validateTarget) ?? []);
+  const config = loadConfig(dir);
+  const topology = config ? buildGraph(dir, config, { scope: "all" }, now) : null;
+  const topologyHints = topology ? buildGraphHints(dir, topology, now).summary.hints : null;
   const actions = [];
   if (!h2.available) {
     actions.push("Run `kaddo guard --record` to start recording guard history.");
@@ -11087,6 +11170,13 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
   return {
     generated_at: now.toISOString(),
     project,
+    project_context: projectContext,
+    consistency_evidence: [
+      { id: "guard-current-consistency", label: "Current Guard consistency", classification: h2.available ? "observed" : "unknown", reason: h2.available ? `${h2.total_runs} recorded Guard run(s) provide deterministic consistency evidence.` : "No recorded Guard history is available." },
+      { id: "lifecycle-consistency", label: "Lifecycle evidence consistency", classification: verificationEvidence.length > 0 ? "observed" : "unknown", reason: verificationEvidence.length > 0 ? `${verificationEvidence.length} Work Item(s) persist an implementation validation status.` : "No persisted Work Item validation status is available." },
+      { id: "deprecation-consistency", label: "Deprecation consistency", classification: plans.length === 0 ? "not_applicable" : deprecationFindings.length === 0 ? "derived" : "observed", reason: plans.length === 0 ? "No deprecation plans exist in this project." : deprecationFindings.length === 0 ? `${plans.length} plan(s) passed deterministic target consistency checks.` : `${deprecationFindings.length} deterministic deprecation consistency finding(s) were detected.` },
+      { id: "topology-consistency", label: "Knowledge topology consistency", classification: topology === null ? "unknown" : topologyHints === 0 ? "derived" : "observed", reason: topology === null ? "No project configuration is available to construct the topology." : topologyHints === 0 ? `The in-memory topology has ${topology.nodes.length} node(s) and no open deterministic hints.` : `The in-memory topology has ${topologyHints} open deterministic hint(s).` }
+    ],
     guard_history: {
       available: h2.available,
       total_runs: h2.total_runs,
@@ -11107,6 +11197,10 @@ function renderDriftMarkdown(r2) {
   L.push("# Kaddo Drift Trend Report", "");
   L.push(`Generated at: ${r2.generated_at}`);
   L.push(`Project: ${r2.project}`);
+  L.push(`Project context: state=${r2.project_context.state}; mode=${r2.project_context.mode}; repositories=${r2.project_context.repository_structure}`);
+  L.push("");
+  L.push("## Consistency Evidence", "");
+  for (const item of r2.consistency_evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
   L.push("");
   if (!r2.guard_history.available) {
     L.push("## Guard History", "");
@@ -11174,6 +11268,8 @@ function serializeDriftJson(r2) {
   const out = {
     generated_at: r2.generated_at,
     project: r2.project,
+    project_context: r2.project_context,
+    consistency_evidence: r2.consistency_evidence,
     guard_history: r2.guard_history,
     drift_warnings: r2.drift_warnings,
     hotspots: r2.hotspots,

package/package.json

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