@kaddo/cli 3.124.1 → 3.124.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.js +196 -29
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -21848,6 +21848,20 @@ async function runIntegrationsImport(dir, id, externalId, opts) {
21848
21848
  import matter19 from "gray-matter";
21849
21849
 
21850
21850
  // src/core/reporting-evidence.ts
21851
+ function graphHintFinding(hint) {
21852
+ const affected = [hint.artifact_id, ...hint.path ? [hint.path] : []];
21853
+ return {
21854
+ id: `graph-hint:${hint.artifact_id}:${hint.missing.join(",")}`,
21855
+ category: "topology",
21856
+ source: "graph-hints",
21857
+ affected_artifacts: affected,
21858
+ // Graph Hints are intentionally informational; review is useful but not a blocking error.
21859
+ priority: "medium",
21860
+ evidence: hint.reason,
21861
+ explanation: hint.message,
21862
+ suggested_action: `Review the declared relationships for ${hint.artifact_id}${hint.path ? ` at ${hint.path}` : ""}.`
21863
+ };
21864
+ }
21851
21865
  function reportingProjectContext(dir) {
21852
21866
  const config = loadConfig(dir);
21853
21867
  if (!config) return { state: "unknown", mode: "unknown", repository_structure: "unknown" };
@@ -21902,7 +21916,11 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21902
21916
  const projectContext = reportingProjectContext(dir);
21903
21917
  const wis = discoverWorkItems(dir);
21904
21918
  const total = wis.length;
21905
- const verifiedWorkItems = wis.filter((wi) => wi.validationStatus === "passed").length;
21919
+ const completedWis = wis.filter((wi) => wi.lifecycle === "completed");
21920
+ const verifiedWorkItems = completedWis.filter((wi) => wi.validationStatus === "passed").length;
21921
+ const failedValidationWorkItems = completedWis.filter((wi) => wi.validationStatus === "failed").length;
21922
+ const pendingValidationWorkItems = completedWis.filter((wi) => Boolean(wi.validationStatus) && !["passed", "failed"].includes(wi.validationStatus)).length;
21923
+ const notRecordedValidationWorkItems = completedWis.length - verifiedWorkItems - failedValidationWorkItems - pendingValidationWorkItems;
21906
21924
  let withOwnership = 0;
21907
21925
  let withSource = 0;
21908
21926
  let withInitiative = 0;
@@ -21910,7 +21928,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21910
21928
  let withAcceptance = 0;
21911
21929
  let withDoD = 0;
21912
21930
  let withValidation = 0;
21913
- let connectedRoadmap = 0;
21931
+ const connectedRoadmapCandidates = /* @__PURE__ */ new Set();
21914
21932
  const globCounts = /* @__PURE__ */ new Map();
21915
21933
  const globOwners = /* @__PURE__ */ new Map();
21916
21934
  const gaps = {
@@ -21934,13 +21952,17 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21934
21952
  for (const wi of wis) {
21935
21953
  const id = wi.id || wi.title;
21936
21954
  if (wi.codeGlobs.length > 0) withOwnership++;
21937
- else gaps.missing_code_ownership.push(gapItem(wi, "Add `code:` globs to connect this Work Item to source paths (`kaddo owners suggest`)."));
21938
- const hasSource = Boolean(wi.sourceId) || wi.source === "roadmap";
21955
+ else if (wi.type === "bugfix" || wi.type === "hotfix") {
21956
+ gaps.missing_code_ownership.push(gapItem(wi, "Add `code:` globs to connect this corrective Work Item to source paths (`kaddo owners suggest`)."));
21957
+ }
21958
+ const roadmapOrigin = wi.source === "roadmap";
21959
+ const hasSource = Boolean(wi.source) || Boolean(wi.sourceId);
21939
21960
  if (hasSource) withSource++;
21940
- else gaps.missing_source.push(gapItem(wi, "Add `source` or `source_id` if this Work Item came from the roadmap."));
21941
- if (hasSource || wi.initiative) connectedRoadmap++;
21961
+ if (roadmapOrigin && !wi.sourceId) {
21962
+ gaps.missing_source.push(gapItem(wi, "Add `source_id` for this roadmap-originated Work Item."));
21963
+ }
21964
+ if (roadmapOrigin && wi.sourceId) connectedRoadmapCandidates.add(wi.sourceId);
21942
21965
  if (wi.initiative) withInitiative++;
21943
- else gaps.missing_initiative.push(gapItem(wi, "Add `initiative` to connect this Work Item to a delivery initiative."));
21944
21966
  if (wi.knowledgeLevel) withLevel++;
21945
21967
  else gaps.missing_knowledge_level.push(gapItem(wi, "Add `knowledge_level` (K0\u2013K4) to the front matter."));
21946
21968
  for (const g2 of wi.codeGlobs) {
@@ -21962,18 +21984,21 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21962
21984
  }
21963
21985
  }
21964
21986
  const ownedCodePaths = [...globCounts.values()].reduce((a, b) => a + b, 0);
21987
+ const connectedRoadmap = connectedRoadmapCandidates.size;
21965
21988
  const broadGlobs = [...globCounts.keys()].filter((g2) => isBroadGlob(g2)).length;
21966
21989
  for (const [glob, owners] of globOwners) {
21967
21990
  if (owners.length > 1) {
21968
- gaps.ownership_overlaps.push({ code_path: glob, work_items: [...new Set(owners)], suggested_action: "Review whether the overlap is expected or should be narrowed." });
21991
+ gaps.ownership_overlaps.push({ code_path: glob, work_items: [...new Set(owners)], suggested_action: "Shared historical modification path; it is not a conflict unless incompatible ownership is documented." });
21969
21992
  }
21970
21993
  }
21971
21994
  const ownershipOverlaps = gaps.ownership_overlaps.length;
21972
21995
  let g;
21996
+ let graphHintEntries = [];
21973
21997
  const config = loadConfig(dir);
21974
21998
  if (config) {
21975
21999
  const graph = buildGraph(dir, config, { scope: resolvedScope }, now);
21976
22000
  const hints = buildGraphHints(dir, graph, now);
22001
+ graphHintEntries = hints.hints;
21977
22002
  g = { available: true, scope: graph.scope, scopeReason: graph.scope_reason, nodes: graph.nodes.length, edges: graph.edges.length, quality: hints.quality, hints: hints.summary.hints, generatedAt: graph.generated_at };
21978
22003
  } else {
21979
22004
  g = { available: false, scope: resolvedScope, scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
@@ -22037,28 +22062,62 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22037
22062
  const deliveryTrace = levelFromRatio(
22038
22063
  coverageRatio(withOwnership) * 0.5 + (g.available && g.edges > 0 ? 1 : 0) * 0.25 + (exp.roadmap.present ? 1 : 0) * 0.25
22039
22064
  );
22065
+ const guardHistory = buildGuardHistory(dir);
22040
22066
  const impact_signals = {
22041
22067
  ambiguity_reduction: levelFromRatio(ambiguityRatio),
22042
- drift_prevention: withOwnership > 0 ? "Active" : "Limited",
22068
+ drift_prevention: guardHistory.available && guardHistory.resolved > 0 ? "Observed" : "Unknown",
22043
22069
  onboarding_support: onboarding,
22044
22070
  delivery_traceability: deliveryTrace,
22045
22071
  ai_context_readiness: aiReady,
22046
22072
  maintenance_readiness: levelFromRatio((coverageRatio(withOwnership) + (deliveryTraceable ? 1 : 0)) / 2)
22047
22073
  };
22074
+ const baselineLayers = projectContext.mode === "poc" ? ["Tech", "Delivery"] : ["Business", "Product", "Tech", "Delivery"];
22075
+ const findings = [];
22076
+ for (const layer2 of baselineLayers) {
22077
+ const status = layerStatus(layer2);
22078
+ if (status !== "Weak" && status !== "Missing") continue;
22079
+ findings.push({
22080
+ id: `knowledge-health:${layer2.toLowerCase()}`,
22081
+ category: "knowledge",
22082
+ source: "knowledge-health",
22083
+ affected_artifacts: [layer2],
22084
+ priority: status === "Missing" ? "high" : "medium",
22085
+ evidence: `${layer2} knowledge maturity is ${status}.`,
22086
+ explanation: `This assesses documented ${layer2} knowledge, not the quality of the product or implementation.`,
22087
+ suggested_action: `Review ${layer2} knowledge coverage and the artifacts or relationships available for it.`
22088
+ });
22089
+ }
22090
+ for (const gap of gaps.missing_code_ownership) {
22091
+ findings.push({
22092
+ id: `ownership:${gap.id}`,
22093
+ category: "delivery",
22094
+ source: "work-item-ownership",
22095
+ affected_artifacts: [gap.id, gap.path],
22096
+ priority: "medium",
22097
+ evidence: "A corrective Work Item has no declared code ownership.",
22098
+ explanation: gap.title,
22099
+ suggested_action: gap.suggested_action
22100
+ });
22101
+ }
22102
+ findings.push(...graphHintEntries.map(graphHintFinding));
22103
+ const priorityOrder = { high: 0, medium: 1, low: 2, unknown: 3 };
22104
+ findings.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority] || a.id.localeCompare(b.id));
22048
22105
  let score = null;
22049
22106
  let score_breakdown = null;
22050
22107
  if (total > 0) {
22051
- const healthPts = [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * 20;
22108
+ const layerMaturity = { Consolidated: 1, Structured: 0.8, Traceable: 0.75, Weak: 0.4, Missing: 0 };
22109
+ const healthPts = [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].reduce((sum, status) => sum + (layerMaturity[status] ?? 0), 0) / 4 * 20;
22052
22110
  const applicableCoverage = knowledge_coverage.filter((c) => c.label !== "Work Items using optional initiatives");
22053
22111
  const covAvg = applicableCoverage.reduce((a, c) => a + coverageRatio(c.have), 0) / applicableCoverage.length;
22054
22112
  const coveragePts = covAvg * 20;
22055
22113
  const ownPts = coverageRatio(withOwnership) * 15;
22056
- const traceBlend = (exp.roadmap.candidates > 0 ? exp.roadmap.materialized / exp.roadmap.candidates : 1) * 0.5 + coverageRatio(withOwnership) * 0.5;
22114
+ const roadmapTraceRatio = exp.roadmap.candidates > 0 ? Math.min(connectedRoadmap, exp.roadmap.candidates) / exp.roadmap.candidates : null;
22115
+ const traceSignals = [coverageRatio(withOwnership), ...roadmapTraceRatio === null ? [] : [roadmapTraceRatio]];
22116
+ const traceBlend = traceSignals.reduce((sum, value) => sum + value, 0) / traceSignals.length;
22057
22117
  const tracePts = traceBlend * 20;
22058
22118
  const qualityMap = { good: 1, partial: 0.6, sparse: 0.3, empty: 0, unknown: 0 };
22059
22119
  const graphPts = (g.available ? qualityMap[g.quality] ?? 0 : 0) * 15;
22060
22120
  const ctxPts = { Low: 0.25, Medium: 0.5, High: 0.8, "Very High": 1 }[ctxLevel] * 10;
22061
- score = Math.round(healthPts + coveragePts + ownPts + tracePts + graphPts + ctxPts);
22062
22121
  score_breakdown = {
22063
22122
  knowledge_health: { points: Math.round(healthPts), max: 20 },
22064
22123
  knowledge_coverage: { points: Math.round(coveragePts), max: 20 },
@@ -22067,6 +22126,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22067
22126
  graph_quality: { points: Math.round(graphPts), max: 15 },
22068
22127
  context_readiness: { points: Math.round(ctxPts), max: 10 }
22069
22128
  };
22129
+ score = Object.values(score_breakdown).reduce((sum, component) => sum + component.points, 0);
22070
22130
  }
22071
22131
  const idsOf = (items) => items.map((i) => i.id);
22072
22132
  const groupedAction = (items, verb) => {
@@ -22080,16 +22140,18 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22080
22140
  if (exp.roadmap.remaining > 0) actions.push(`Materialize the ${exp.roadmap.remaining} remaining roadmap candidate(s) with \`kaddo create --from roadmap\`.`);
22081
22141
  for (const a of [
22082
22142
  groupedAction(gaps.missing_code_ownership, "Add `code:` ownership to"),
22083
- groupedAction(gaps.missing_source, "Add `source`/`source_id` to"),
22084
- groupedAction(gaps.missing_acceptance_criteria, "Add Acceptance Criteria to"),
22085
- groupedAction(gaps.missing_definition_of_done, "Add a Definition of Done to"),
22086
- groupedAction(gaps.missing_validation, "Add a validation (How to test it) section to")
22143
+ groupedAction(gaps.missing_source, "Add `source`/`source_id` to")
22087
22144
  ]) if (a) actions.push(a);
22088
22145
  if (gaps.broad_ownership_globs.length > 0) actions.push(`Narrow ${gaps.broad_ownership_globs.length} broad ownership glob(s) into specific paths.`);
22089
- if (g.available && g.hints > 0) actions.push("Review graph hints (`kaddo://graph-hints` or `.kaddo/graph-hints.md`).");
22146
+ for (const finding of findings) {
22147
+ if (!actions.includes(finding.suggested_action)) actions.push(finding.suggested_action);
22148
+ }
22090
22149
  if (skills.length === 0) actions.push("Install reusable skills with `kaddo add skills`.");
22091
22150
  actions.push("Run `kaddo guard` before committing to catch knowledge drift.");
22092
22151
  const summary = [];
22152
+ if (completedWis.length > 0) {
22153
+ summary.push(`Delivery evidence: ${completedWis.length} completed; ${verifiedWorkItems} validation passed; ${notRecordedValidationWorkItems} not confirmed by persisted validation.`);
22154
+ }
22093
22155
  if (total > 0) summary.push(`${withOwnership}/${total} Work Items include code ownership.`);
22094
22156
  if (g.available) summary.push(`The knowledge graph is ${g.quality} with ${g.nodes} nodes and ${g.edges} edges (${g.scope} scope).`);
22095
22157
  else summary.push("The knowledge graph has not been exported yet.");
@@ -22105,12 +22167,21 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22105
22167
  { 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." },
22106
22168
  { 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." },
22107
22169
  ...deliveryCapabilityEvidence(dir, projectContext),
22108
- { 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." }
22170
+ { id: "guard-history", label: "Guard consistency history", classification: guardHistory.available ? "observed" : "unknown", reason: guardHistory.available ? "Recorded Guard runs provide current consistency evidence." : "No recorded Guard history is available." }
22109
22171
  ],
22110
22172
  scope: g.scope,
22111
22173
  default_scope: "all",
22112
22174
  scope_source: scopeSource,
22113
22175
  executive_summary: summary,
22176
+ delivery_evidence: {
22177
+ completed: completedWis.length,
22178
+ validation_passed: verifiedWorkItems,
22179
+ validation_failed: failedValidationWorkItems,
22180
+ validation_pending: pendingValidationWorkItems,
22181
+ validation_not_recorded: notRecordedValidationWorkItems,
22182
+ completion_with_passed_validation_percent: completedWis.length > 0 ? Math.round(verifiedWorkItems / completedWis.length * 1e3) / 10 : null
22183
+ },
22184
+ findings,
22114
22185
  knowledge_health,
22115
22186
  knowledge_coverage,
22116
22187
  ownership_coverage: {
@@ -22143,7 +22214,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22143
22214
  },
22144
22215
  graph_quality: g.available ? { available: true, scope: g.scope, quality: g.quality, nodes: g.nodes, edges: g.edges, hints: g.hints, reason: g.scopeReason, last_exported: g.generatedAt } : { available: false, suggestion: "Run `kaddo graph export --scope all`." },
22145
22216
  guard_activity: (() => {
22146
- const gh = buildGuardHistory(dir);
22217
+ const gh = guardHistory;
22147
22218
  return gh.available ? { available: true, runs_recorded: gh.total_runs, detected: gh.detected, open: gh.open, resolved: gh.resolved, resolution_rate: gh.resolution_rate } : { available: false, note: "Guard history is not persisted. Run `kaddo guard --record` to record runs for trend analysis." };
22148
22219
  })(),
22149
22220
  impact_signals,
@@ -22174,6 +22245,27 @@ function renderImpactMarkdown(r) {
22174
22245
  L.push("## Executive Summary", "");
22175
22246
  for (const s2 of r.executive_summary) L.push(`- ${s2}`);
22176
22247
  L.push("");
22248
+ L.push("## Key Findings", "");
22249
+ if (r.findings.length === 0) L.push("No current findings detected by the executed deterministic checks.");
22250
+ if (r.findings.length > 0) {
22251
+ const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
22252
+ L.push("| Priority | Source | Affected | Finding | Suggested action |");
22253
+ L.push("|---|---|---|---|---|");
22254
+ for (const finding of r.findings) {
22255
+ L.push(`| ${finding.priority} | ${cell(finding.source)} | ${cell(finding.affected_artifacts.join(", ") || "not available")} | ${cell(finding.explanation)} Evidence: ${cell(finding.evidence)} | ${cell(finding.suggested_action)} |`);
22256
+ }
22257
+ }
22258
+ L.push("");
22259
+ L.push("## Delivery Evidence", "");
22260
+ const de = r.delivery_evidence;
22261
+ L.push(`- Completed Work Items: ${de.completed}`);
22262
+ L.push(`- Validation passed: ${de.validation_passed}`);
22263
+ L.push(`- Validation failed: ${de.validation_failed}`);
22264
+ L.push(`- Validation pending: ${de.validation_pending}`);
22265
+ L.push(`- Validation not recorded: ${de.validation_not_recorded}`);
22266
+ L.push(`- Completion with passed validation: ${de.completion_with_passed_validation_percent === null ? "not available" : `${de.completion_with_passed_validation_percent}%`}`);
22267
+ L.push("- \u201CNot recorded\u201D means persisted evidence is absent; it does not prove validation never happened.");
22268
+ L.push("");
22177
22269
  L.push("## Evidence and Applicability", "");
22178
22270
  for (const item of r.evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22179
22271
  L.push("");
@@ -22254,7 +22346,7 @@ function renderImpactMarkdown(r) {
22254
22346
  L.push("## Impact Signals", "");
22255
22347
  const s = r.impact_signals;
22256
22348
  L.push(`- Ambiguity reduction: ${s.ambiguity_reduction}`);
22257
- L.push(`- Drift prevention: ${s.drift_prevention}`);
22349
+ L.push(`- Drift prevention evidence: ${s.drift_prevention}`);
22258
22350
  L.push(`- Onboarding support: ${s.onboarding_support}`);
22259
22351
  L.push(`- Delivery traceability: ${s.delivery_traceability}`);
22260
22352
  L.push(`- AI context readiness: ${s.ai_context_readiness}`);
@@ -22273,12 +22365,7 @@ function renderImpactMarkdown(r) {
22273
22365
  L.push("");
22274
22366
  };
22275
22367
  gapSection("Work Items missing source", gp.missing_source);
22276
- gapSection("Work Items missing initiative", gp.missing_initiative);
22277
22368
  gapSection("Work Items missing code ownership", gp.missing_code_ownership);
22278
- gapSection("Work Items missing knowledge level", gp.missing_knowledge_level);
22279
- gapSection("Work Items missing acceptance criteria", gp.missing_acceptance_criteria);
22280
- gapSection("Work Items missing Definition of Done", gp.missing_definition_of_done);
22281
- gapSection("Work Items missing validation", gp.missing_validation);
22282
22369
  if (gp.broad_ownership_globs.length > 0) {
22283
22370
  L.push("### Broad ownership globs", "");
22284
22371
  for (const b of gp.broad_ownership_globs) {
@@ -22289,7 +22376,7 @@ function renderImpactMarkdown(r) {
22289
22376
  L.push("");
22290
22377
  }
22291
22378
  if (gp.ownership_overlaps.length > 0) {
22292
- L.push("### Ownership overlaps", "");
22379
+ L.push("### Shared code-path history (review only)", "");
22293
22380
  for (const o of gp.ownership_overlaps) {
22294
22381
  L.push(`- \`${o.code_path}\``);
22295
22382
  L.push(` - Owned by: ${o.work_items.join(", ")}`);
@@ -22297,10 +22384,26 @@ function renderImpactMarkdown(r) {
22297
22384
  }
22298
22385
  L.push("");
22299
22386
  }
22300
- const anyGaps = gp.missing_source.length + gp.missing_initiative.length + gp.missing_code_ownership.length + gp.missing_knowledge_level.length + gp.missing_acceptance_criteria.length + gp.missing_definition_of_done.length + gp.missing_validation.length + gp.broad_ownership_globs.length + gp.ownership_overlaps.length;
22387
+ const anyGaps = gp.missing_source.length + gp.missing_code_ownership.length + gp.broad_ownership_globs.length;
22301
22388
  if (anyGaps === 0) {
22302
22389
  L.push("No actionable knowledge gaps detected. \u{1F389}", "");
22303
22390
  }
22391
+ const historical = [
22392
+ ["knowledge level", gp.missing_knowledge_level],
22393
+ ["Acceptance Criteria", gp.missing_acceptance_criteria],
22394
+ ["Definition of Done", gp.missing_definition_of_done],
22395
+ ["validation section", gp.missing_validation]
22396
+ ];
22397
+ L.push("## Historical Documentation Completeness", "");
22398
+ for (const [label, items] of historical) {
22399
+ const completed = items.filter((item) => item.status === "completed");
22400
+ if (completed.length > 0) L.push(`- Completed Work Items without detected ${label}: ${completed.length}`);
22401
+ }
22402
+ if (!historical.some(([, items]) => items.some((item) => item.status === "completed"))) {
22403
+ L.push("No historical documentation completeness gaps were detected.");
22404
+ }
22405
+ L.push("- This is an inventory for review, not a recommendation to rewrite historical Work Items merely to increase a metric.");
22406
+ L.push("");
22304
22407
  if (r.score_breakdown) {
22305
22408
  L.push("## Score Breakdown", "");
22306
22409
  const b = r.score_breakdown;
@@ -22493,6 +22596,16 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22493
22596
  } else {
22494
22597
  actions.push("Use drift history to calibrate `rework_hours_avoided_per_resolved_drift`.");
22495
22598
  }
22599
+ const calibrationOpportunities = !a.calibrated_at ? {
22600
+ available: true,
22601
+ reason: source2 === "default" ? "Default assumptions are uncalibrated estimates." : "Project assumptions are not marked as calibrated.",
22602
+ opportunities: [
22603
+ { area: "Context preparation", suggested_evidence: "Compare preparation effort on comparable tasks before and after using the knowledge artifacts." },
22604
+ { area: "Review effort", suggested_evidence: "Record a baseline for comparable reviews with similar ownership coverage." },
22605
+ { area: "Clarification reduction", suggested_evidence: "Estimate effort spent resolving repeated scope or context questions." },
22606
+ { area: "Architecture discovery", suggested_evidence: "Compare discovery time for similar dependency or relationship analyses." }
22607
+ ]
22608
+ } : { available: false, reason: `Assumptions are marked as calibrated on ${a.calibrated_at}.`, opportunities: [] };
22496
22609
  return {
22497
22610
  generated_at: now.toISOString(),
22498
22611
  project: impact.project,
@@ -22544,6 +22657,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22544
22657
  },
22545
22658
  total: { estimated_hours_saved: observedHours, estimated_value: observedValue, currency: a.currency },
22546
22659
  confidence: { level, reasons },
22660
+ calibration_opportunities: calibrationOpportunities,
22547
22661
  suggested_actions: actions
22548
22662
  };
22549
22663
  }
@@ -22625,6 +22739,17 @@ function renderSavingsMarkdown(r) {
22625
22739
  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
22626
22740
  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
22627
22741
  L.push("");
22742
+ L.push("## Calibration Opportunities", "");
22743
+ if (!r.calibration_opportunities.available) {
22744
+ L.push(`- ${r.calibration_opportunities.reason}`);
22745
+ } else {
22746
+ L.push(`- ${r.calibration_opportunities.reason}`);
22747
+ L.push("- Use external, aggregate project observations; do not collect or store personal data.");
22748
+ for (const opportunity of r.calibration_opportunities.opportunities) {
22749
+ L.push(`- ${opportunity.area}: ${opportunity.suggested_evidence}`);
22750
+ }
22751
+ }
22752
+ L.push("");
22628
22753
  L.push("## Suggested Actions", "");
22629
22754
  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
22630
22755
  L.push("");
@@ -22679,10 +22804,24 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22679
22804
  const deprecationFindings = plans.flatMap((plan) => getDeprecationPlan(dir, plan.id)?.targets.flatMap(validateTarget) ?? []);
22680
22805
  const config = loadConfig(dir);
22681
22806
  const topology = config ? buildGraph(dir, config, { scope: "all" }, now) : null;
22682
- const topologyHints = topology ? buildGraphHints(dir, topology, now).summary.hints : null;
22807
+ const graphHints = topology ? buildGraphHints(dir, topology, now) : null;
22808
+ const topologyHints = graphHints?.summary.hints ?? null;
22809
+ const currentConsistencyFindings = [
22810
+ ...graphHints?.hints.map(graphHintFinding) ?? [],
22811
+ ...deprecationFindings.map((finding, index) => ({
22812
+ id: `deprecation-target:${index + 1}`,
22813
+ category: "consistency",
22814
+ source: "deprecation-target-validation",
22815
+ affected_artifacts: [],
22816
+ priority: "medium",
22817
+ evidence: String(finding),
22818
+ explanation: "A deterministic deprecation target consistency check reported a finding.",
22819
+ suggested_action: "Review the affected deprecation target and its declared lifecycle evidence."
22820
+ }))
22821
+ ];
22683
22822
  const actions = [];
22684
22823
  if (!h.available) {
22685
- actions.push("Run `kaddo guard --record` to start recording guard history.");
22824
+ actions.push("Start recording Guard runs at relevant delivery checkpoints with `kaddo guard --record`; one run creates an observation, while multiple comparable runs are needed for a historical trend.");
22686
22825
  } else {
22687
22826
  if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
22688
22827
  actions.push("Run `kaddo guard --record` before important commits.");
@@ -22698,6 +22837,11 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22698
22837
  { 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.` },
22699
22838
  { 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).` }
22700
22839
  ],
22840
+ current_consistency_findings: currentConsistencyFindings,
22841
+ structural_consistency: {
22842
+ deprecation_target_checks: plans.length === 0 ? "not_applicable" : deprecationFindings.length === 0 ? "passed" : "findings_detected",
22843
+ note: plans.length === 0 ? "No deprecation plans exist in this project." : "Target consistency checks validate declared structural state only; they do not verify operational removal from infrastructure, production or external consumers."
22844
+ },
22701
22845
  guard_history: {
22702
22846
  available: h.available,
22703
22847
  total_runs: h.total_runs,
@@ -22723,10 +22867,31 @@ function renderDriftMarkdown(r) {
22723
22867
  L.push("## Consistency Evidence", "");
22724
22868
  for (const item of r.consistency_evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22725
22869
  L.push("");
22870
+ L.push("## Current Consistency Findings", "");
22871
+ if (r.current_consistency_findings.length === 0) {
22872
+ L.push("No findings detected by the executed consistency checks.");
22873
+ L.push("");
22874
+ }
22875
+ if (r.current_consistency_findings.length > 0) {
22876
+ const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
22877
+ L.push("| Priority | Source | Affected | Finding | Suggested action |");
22878
+ L.push("|---|---|---|---|---|");
22879
+ for (const finding of r.current_consistency_findings) {
22880
+ L.push(`| ${finding.priority} | ${cell(finding.source)} | ${cell(finding.affected_artifacts.join(", ") || "not available")} | ${cell(finding.explanation)} Evidence: ${cell(finding.evidence)} | ${cell(finding.suggested_action)} |`);
22881
+ }
22882
+ L.push("");
22883
+ }
22884
+ L.push("## Structural Consistency Boundaries", "");
22885
+ L.push(`- Deprecation target checks: ${r.structural_consistency.deprecation_target_checks}`);
22886
+ L.push(`- Note: ${r.structural_consistency.note}`);
22887
+ L.push("");
22726
22888
  if (!r.guard_history.available) {
22727
22889
  L.push("## Guard History", "");
22728
22890
  L.push("No guard history recorded yet.");
22729
22891
  L.push("");
22892
+ L.push("## Historical Drift Trend", "");
22893
+ L.push("Not available \u2014 no recorded Guard runs.");
22894
+ L.push("");
22730
22895
  L.push("Run `kaddo guard --record` to start recording drift evidence.");
22731
22896
  L.push("");
22732
22897
  L.push("## Suggested Actions", "");
@@ -22791,6 +22956,8 @@ function serializeDriftJson(r) {
22791
22956
  project: r.project,
22792
22957
  project_context: r.project_context,
22793
22958
  consistency_evidence: r.consistency_evidence,
22959
+ current_consistency_findings: r.current_consistency_findings,
22960
+ structural_consistency: r.structural_consistency,
22794
22961
  guard_history: r.guard_history,
22795
22962
  drift_warnings: r.drift_warnings,
22796
22963
  hotspots: r.hotspots,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.124.1",
3
+ "version": "3.124.3",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {