@kaddo/cli 3.124.2 → 3.124.4

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 +267 -29
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -21848,6 +21848,29 @@ 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
+ const semantics = {
21854
+ "work-item": { classification: "coverage_gap", priority: "medium", action: "Review whether the active Work Item needs the missing declared relationship." },
21855
+ decision: { classification: "coverage_gap", priority: "low", action: "Review whether this decision should declare governed code paths." },
21856
+ capability: { classification: "coverage_gap", priority: "low", action: "Review whether this capability should connect to existing Work Items; the relationship is optional." },
21857
+ "knowledge-capsule": { classification: "review_hint", priority: "low", action: "Confirm whether this capsule is intended for direct contextual use or Work Item relationships." }
21858
+ };
21859
+ const semantic = semantics[hint.artifact_type];
21860
+ return {
21861
+ id: `graph-hint:${hint.artifact_id}:${hint.missing.join(",")}`,
21862
+ category: "topology",
21863
+ classification: semantic.classification,
21864
+ resolution_status: "open",
21865
+ source: "graph-hints",
21866
+ affected_artifacts: affected,
21867
+ // Graph Hints are intentionally non-blocking; their type determines priority and meaning.
21868
+ priority: semantic.priority,
21869
+ evidence: hint.reason,
21870
+ explanation: hint.message,
21871
+ suggested_action: semantic.action
21872
+ };
21873
+ }
21851
21874
  function reportingProjectContext(dir) {
21852
21875
  const config = loadConfig(dir);
21853
21876
  if (!config) return { state: "unknown", mode: "unknown", repository_structure: "unknown" };
@@ -21902,7 +21925,11 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21902
21925
  const projectContext = reportingProjectContext(dir);
21903
21926
  const wis = discoverWorkItems(dir);
21904
21927
  const total = wis.length;
21905
- const verifiedWorkItems = wis.filter((wi) => wi.validationStatus === "passed").length;
21928
+ const completedWis = wis.filter((wi) => wi.lifecycle === "completed");
21929
+ const verifiedWorkItems = completedWis.filter((wi) => wi.validationStatus === "passed").length;
21930
+ const failedValidationWorkItems = completedWis.filter((wi) => wi.validationStatus === "failed").length;
21931
+ const pendingValidationWorkItems = completedWis.filter((wi) => Boolean(wi.validationStatus) && !["passed", "failed"].includes(wi.validationStatus)).length;
21932
+ const notRecordedValidationWorkItems = completedWis.length - verifiedWorkItems - failedValidationWorkItems - pendingValidationWorkItems;
21906
21933
  let withOwnership = 0;
21907
21934
  let withSource = 0;
21908
21935
  let withInitiative = 0;
@@ -21975,10 +22002,12 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21975
22002
  }
21976
22003
  const ownershipOverlaps = gaps.ownership_overlaps.length;
21977
22004
  let g;
22005
+ let graphHintEntries = [];
21978
22006
  const config = loadConfig(dir);
21979
22007
  if (config) {
21980
22008
  const graph = buildGraph(dir, config, { scope: resolvedScope }, now);
21981
22009
  const hints = buildGraphHints(dir, graph, now);
22010
+ graphHintEntries = hints.hints;
21982
22011
  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 };
21983
22012
  } else {
21984
22013
  g = { available: false, scope: resolvedScope, scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
@@ -22051,6 +22080,56 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22051
22080
  ai_context_readiness: aiReady,
22052
22081
  maintenance_readiness: levelFromRatio((coverageRatio(withOwnership) + (deliveryTraceable ? 1 : 0)) / 2)
22053
22082
  };
22083
+ const baselineLayers = projectContext.mode === "poc" ? ["Tech", "Delivery"] : ["Business", "Product", "Tech", "Delivery"];
22084
+ const findings = [];
22085
+ for (const layer2 of baselineLayers) {
22086
+ const status = layerStatus(layer2);
22087
+ if (status !== "Weak" && status !== "Missing") continue;
22088
+ findings.push({
22089
+ id: `knowledge-health:${layer2.toLowerCase()}`,
22090
+ category: "knowledge",
22091
+ classification: "coverage_gap",
22092
+ resolution_status: "open",
22093
+ source: "knowledge-health",
22094
+ affected_artifacts: [layer2],
22095
+ priority: status === "Missing" ? "medium" : "low",
22096
+ evidence: `${layer2} knowledge maturity is ${status}.`,
22097
+ explanation: `This assesses documented ${layer2} knowledge, not the quality of the product or implementation.`,
22098
+ suggested_action: `Review ${layer2} knowledge coverage and the artifacts or relationships available for it.`
22099
+ });
22100
+ }
22101
+ for (const gap of gaps.missing_code_ownership) {
22102
+ findings.push({
22103
+ id: `ownership:${gap.id}`,
22104
+ category: "delivery",
22105
+ classification: "coverage_gap",
22106
+ resolution_status: "open",
22107
+ source: "work-item-ownership",
22108
+ affected_artifacts: [gap.id, gap.path],
22109
+ priority: "medium",
22110
+ evidence: "A corrective Work Item has no declared code ownership.",
22111
+ explanation: gap.title,
22112
+ suggested_action: "Review and add relevant code ownership declarations."
22113
+ });
22114
+ }
22115
+ for (const wi of completedWis) {
22116
+ if (!wi.validationStatus || !["not-started", "in-progress", "partial", "failed", "blocked"].includes(wi.validationStatus)) continue;
22117
+ findings.push({
22118
+ id: `completion-validation:${wi.id || wi.title}`,
22119
+ category: "delivery",
22120
+ classification: "review_hint",
22121
+ resolution_status: "open",
22122
+ source: "work-item-lifecycle",
22123
+ affected_artifacts: [wi.id || wi.title, wi.relPath],
22124
+ priority: "medium",
22125
+ evidence: `Lifecycle is completed while persisted validation is ${wi.validationStatus}.`,
22126
+ explanation: "This requires review against the Work Item completion contract; it is not automatically a failed or invalid completion.",
22127
+ suggested_action: "Review the validation evidence and confirm whether the completed lifecycle state is consistent with the Work Item completion contract."
22128
+ });
22129
+ }
22130
+ findings.push(...graphHintEntries.map(graphHintFinding));
22131
+ const priorityOrder = { high: 0, medium: 1, low: 2, unknown: 3 };
22132
+ findings.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority] || a.id.localeCompare(b.id));
22054
22133
  let score = null;
22055
22134
  let score_breakdown = null;
22056
22135
  if (total > 0) {
@@ -22088,17 +22167,18 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22088
22167
  else if (g.scope === "active" && g.quality === "empty") actions.push("Run `kaddo impact --scope all` to measure accumulated knowledge impact.");
22089
22168
  if (exp.roadmap.remaining > 0) actions.push(`Materialize the ${exp.roadmap.remaining} remaining roadmap candidate(s) with \`kaddo create --from roadmap\`.`);
22090
22169
  for (const a of [
22091
- groupedAction(gaps.missing_code_ownership, "Add `code:` ownership to"),
22092
- groupedAction(gaps.missing_source, "Add `source`/`source_id` to"),
22093
- groupedAction(gaps.missing_acceptance_criteria, "Add Acceptance Criteria to"),
22094
- groupedAction(gaps.missing_definition_of_done, "Add a Definition of Done to"),
22095
- groupedAction(gaps.missing_validation, "Add a validation (How to test it) section to")
22170
+ groupedAction(gaps.missing_source, "Add `source`/`source_id` to")
22096
22171
  ]) if (a) actions.push(a);
22097
22172
  if (gaps.broad_ownership_globs.length > 0) actions.push(`Narrow ${gaps.broad_ownership_globs.length} broad ownership glob(s) into specific paths.`);
22098
- if (g.available && g.hints > 0) actions.push("Review graph hints (`kaddo://graph-hints` or `.kaddo/graph-hints.md`).");
22173
+ for (const finding of findings) {
22174
+ if (!actions.includes(finding.suggested_action)) actions.push(finding.suggested_action);
22175
+ }
22099
22176
  if (skills.length === 0) actions.push("Install reusable skills with `kaddo add skills`.");
22100
22177
  actions.push("Run `kaddo guard` before committing to catch knowledge drift.");
22101
22178
  const summary = [];
22179
+ if (completedWis.length > 0) {
22180
+ summary.push(`Delivery evidence: ${completedWis.length} completed; ${verifiedWorkItems} validation passed; ${notRecordedValidationWorkItems} not confirmed by persisted validation.`);
22181
+ }
22102
22182
  if (total > 0) summary.push(`${withOwnership}/${total} Work Items include code ownership.`);
22103
22183
  if (g.available) summary.push(`The knowledge graph is ${g.quality} with ${g.nodes} nodes and ${g.edges} edges (${g.scope} scope).`);
22104
22184
  else summary.push("The knowledge graph has not been exported yet.");
@@ -22120,6 +22200,15 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22120
22200
  default_scope: "all",
22121
22201
  scope_source: scopeSource,
22122
22202
  executive_summary: summary,
22203
+ delivery_evidence: {
22204
+ completed: completedWis.length,
22205
+ validation_passed: verifiedWorkItems,
22206
+ validation_failed: failedValidationWorkItems,
22207
+ validation_pending: pendingValidationWorkItems,
22208
+ validation_not_recorded: notRecordedValidationWorkItems,
22209
+ completion_with_passed_validation_percent: completedWis.length > 0 ? Math.round(verifiedWorkItems / completedWis.length * 1e3) / 10 : null
22210
+ },
22211
+ findings,
22123
22212
  knowledge_health,
22124
22213
  knowledge_coverage,
22125
22214
  ownership_coverage: {
@@ -22165,7 +22254,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22165
22254
  function ratio(have, total) {
22166
22255
  return `${have}/${total}`;
22167
22256
  }
22168
- function renderImpactMarkdown(r) {
22257
+ function renderImpactMarkdown(r, opts = {}) {
22169
22258
  const L = [];
22170
22259
  L.push("# Kaddo Knowledge Impact Report", "");
22171
22260
  L.push(`Generated at: ${r.generated_at}`);
@@ -22183,6 +22272,27 @@ function renderImpactMarkdown(r) {
22183
22272
  L.push("## Executive Summary", "");
22184
22273
  for (const s2 of r.executive_summary) L.push(`- ${s2}`);
22185
22274
  L.push("");
22275
+ L.push("## Key Findings", "");
22276
+ if (r.findings.length === 0) L.push("No current findings detected by the executed deterministic checks.");
22277
+ if (r.findings.length > 0) {
22278
+ const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
22279
+ L.push("| Classification | Priority | Status | Source | Affected | Finding | Suggested action |");
22280
+ L.push("|---|---|---|---|---|---|---|");
22281
+ for (const finding of r.findings) {
22282
+ L.push(`| ${finding.classification} | ${finding.priority} | ${finding.resolution_status} | ${cell(finding.source)} | ${cell(finding.affected_artifacts.join(", ") || "not available")} | ${cell(finding.explanation)} Evidence: ${cell(finding.evidence)} | ${cell(finding.suggested_action)} |`);
22283
+ }
22284
+ }
22285
+ L.push("");
22286
+ L.push("## Delivery Evidence", "");
22287
+ const de = r.delivery_evidence;
22288
+ L.push(`- Completed Work Items: ${de.completed}`);
22289
+ L.push(`- Validation passed: ${de.validation_passed}`);
22290
+ L.push(`- Validation failed: ${de.validation_failed}`);
22291
+ L.push(`- Validation pending: ${de.validation_pending}`);
22292
+ L.push(`- Validation not recorded: ${de.validation_not_recorded}`);
22293
+ L.push(`- Completion with passed validation: ${de.completion_with_passed_validation_percent === null ? "not available" : `${de.completion_with_passed_validation_percent}%`}`);
22294
+ L.push("- \u201CNot recorded\u201D means persisted evidence is absent; it does not prove validation never happened.");
22295
+ L.push("");
22186
22296
  L.push("## Evidence and Applicability", "");
22187
22297
  for (const item of r.evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22188
22298
  L.push("");
@@ -22281,14 +22391,9 @@ function renderImpactMarkdown(r) {
22281
22391
  }
22282
22392
  L.push("");
22283
22393
  };
22284
- gapSection("Work Items missing source", gp.missing_source);
22285
- gapSection("Work Items missing initiative", gp.missing_initiative);
22286
- gapSection("Work Items missing code ownership", gp.missing_code_ownership);
22287
- gapSection("Work Items missing knowledge level", gp.missing_knowledge_level);
22288
- gapSection("Work Items missing acceptance criteria", gp.missing_acceptance_criteria);
22289
- gapSection("Work Items missing Definition of Done", gp.missing_definition_of_done);
22290
- gapSection("Work Items missing validation", gp.missing_validation);
22291
- if (gp.broad_ownership_globs.length > 0) {
22394
+ if (opts.details) gapSection("Work Items missing source", gp.missing_source);
22395
+ if (opts.details) gapSection("Work Items missing code ownership", gp.missing_code_ownership);
22396
+ if (opts.details && gp.broad_ownership_globs.length > 0) {
22292
22397
  L.push("### Broad ownership globs", "");
22293
22398
  for (const b of gp.broad_ownership_globs) {
22294
22399
  L.push(`- ${b.id} \u2014 ${b.title}`);
@@ -22299,17 +22404,43 @@ function renderImpactMarkdown(r) {
22299
22404
  }
22300
22405
  if (gp.ownership_overlaps.length > 0) {
22301
22406
  L.push("### Shared code-path history (review only)", "");
22302
- for (const o of gp.ownership_overlaps) {
22303
- L.push(`- \`${o.code_path}\``);
22304
- L.push(` - Owned by: ${o.work_items.join(", ")}`);
22305
- L.push(` - Suggested action: ${o.suggested_action}`);
22407
+ if (opts.details) {
22408
+ for (const o of gp.ownership_overlaps) {
22409
+ L.push(`- \`${o.code_path}\``);
22410
+ L.push(` - Owned by: ${o.work_items.join(", ")}`);
22411
+ L.push(` - Suggested action: ${o.suggested_action}`);
22412
+ }
22413
+ } else {
22414
+ L.push(`- ${gp.ownership_overlaps.length} shared path declaration(s) detected. These are historical relationships, not necessarily ownership conflicts.`);
22415
+ const areas = gp.ownership_overlaps.slice(0, 3).map((o) => `\`${o.code_path}\``);
22416
+ if (areas.length > 0) L.push(`- Most involved paths: ${areas.join(", ")}.`);
22417
+ L.push("- Run `kaddo impact --details` for the complete shared-path inventory.");
22306
22418
  }
22307
22419
  L.push("");
22308
22420
  }
22309
- 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;
22421
+ const anyGaps = gp.missing_source.length + gp.missing_code_ownership.length + gp.broad_ownership_globs.length;
22310
22422
  if (anyGaps === 0) {
22311
22423
  L.push("No actionable knowledge gaps detected. \u{1F389}", "");
22424
+ } else if (!opts.details) {
22425
+ L.push("- Current actionable items are listed in Key Findings. Run `kaddo impact --details` for the full artifact inventory.");
22426
+ L.push("");
22427
+ }
22428
+ const historical = [
22429
+ ["knowledge level", gp.missing_knowledge_level],
22430
+ ["Acceptance Criteria", gp.missing_acceptance_criteria],
22431
+ ["Definition of Done", gp.missing_definition_of_done],
22432
+ ["validation section", gp.missing_validation]
22433
+ ];
22434
+ L.push("## Historical Documentation Completeness", "");
22435
+ for (const [label, items] of historical) {
22436
+ const completed = items.filter((item) => item.status === "completed");
22437
+ if (completed.length > 0) L.push(`- Completed Work Items without detected ${label}: ${completed.length}`);
22438
+ }
22439
+ if (!historical.some(([, items]) => items.some((item) => item.status === "completed"))) {
22440
+ L.push("No historical documentation completeness gaps were detected.");
22312
22441
  }
22442
+ L.push("- This is an inventory for review, not a recommendation to rewrite historical Work Items merely to increase a metric.");
22443
+ L.push("");
22313
22444
  if (r.score_breakdown) {
22314
22445
  L.push("## Score Breakdown", "");
22315
22446
  const b = r.score_breakdown;
@@ -22336,7 +22467,7 @@ function runReportImpact(opts = {}) {
22336
22467
  requireConfig(dir);
22337
22468
  const scope = opts.scope === "active" ? "active" : opts.scope === "all" ? "all" : void 0;
22338
22469
  const report = buildImpactReport(dir, { scope });
22339
- const content = opts.json ? serializeImpactJson(report) : renderImpactMarkdown(report);
22470
+ const content = opts.json ? serializeImpactJson(report) : renderImpactMarkdown(report, { details: opts.details });
22340
22471
  if (opts.output) {
22341
22472
  intro("kaddo report impact");
22342
22473
  const rel = opts.output;
@@ -22502,6 +22633,16 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22502
22633
  } else {
22503
22634
  actions.push("Use drift history to calibrate `rework_hours_avoided_per_resolved_drift`.");
22504
22635
  }
22636
+ const calibrationOpportunities = !a.calibrated_at ? {
22637
+ available: true,
22638
+ reason: source2 === "default" ? "Default assumptions are uncalibrated estimates." : "Project assumptions are not marked as calibrated.",
22639
+ opportunities: [
22640
+ { area: "Context preparation", suggested_evidence: "Compare preparation effort on comparable tasks before and after using the knowledge artifacts." },
22641
+ { area: "Review effort", suggested_evidence: "Record a baseline for comparable reviews with similar ownership coverage." },
22642
+ { area: "Clarification reduction", suggested_evidence: "Estimate effort spent resolving repeated scope or context questions." },
22643
+ { area: "Architecture discovery", suggested_evidence: "Compare discovery time for similar dependency or relationship analyses." }
22644
+ ]
22645
+ } : { available: false, reason: `Assumptions are marked as calibrated on ${a.calibrated_at}.`, opportunities: [] };
22505
22646
  return {
22506
22647
  generated_at: now.toISOString(),
22507
22648
  project: impact.project,
@@ -22553,6 +22694,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22553
22694
  },
22554
22695
  total: { estimated_hours_saved: observedHours, estimated_value: observedValue, currency: a.currency },
22555
22696
  confidence: { level, reasons },
22697
+ calibration_opportunities: calibrationOpportunities,
22556
22698
  suggested_actions: actions
22557
22699
  };
22558
22700
  }
@@ -22587,7 +22729,7 @@ function renderSavingsMarkdown(r) {
22587
22729
  L.push("");
22588
22730
  L.push("## Evidence Used", "");
22589
22731
  const e = r.evidence;
22590
- L.push(`- Knowledge Impact Score: ${e.knowledge_impact_score ?? "not available"}${e.knowledge_impact_score !== null ? "/100" : ""}`);
22732
+ L.push(`- Legacy Knowledge Impact Score: ${e.knowledge_impact_score ?? "not available"}${e.knowledge_impact_score !== null ? "/100" : ""} (deprecated; informational only and not used for confidence)`);
22591
22733
  L.push(`- Completed Work Items: ${e.completed_work_items}`);
22592
22734
  L.push(`- Ownership coverage: ${e.ownership_coverage_percent}%`);
22593
22735
  L.push(`- Work Items with Acceptance Criteria: ${e.work_items_with_acceptance_criteria}`);
@@ -22634,6 +22776,17 @@ function renderSavingsMarkdown(r) {
22634
22776
  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
22635
22777
  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
22636
22778
  L.push("");
22779
+ L.push("## Calibration Opportunities", "");
22780
+ if (!r.calibration_opportunities.available) {
22781
+ L.push(`- ${r.calibration_opportunities.reason}`);
22782
+ } else {
22783
+ L.push(`- ${r.calibration_opportunities.reason}`);
22784
+ L.push("- Use external, aggregate project observations; do not collect or store personal data.");
22785
+ for (const opportunity of r.calibration_opportunities.opportunities) {
22786
+ L.push(`- ${opportunity.area}: ${opportunity.suggested_evidence}`);
22787
+ }
22788
+ }
22789
+ L.push("");
22637
22790
  L.push("## Suggested Actions", "");
22638
22791
  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
22639
22792
  L.push("");
@@ -22685,13 +22838,49 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22685
22838
  const workItems = discoverWorkItems(dir);
22686
22839
  const verificationEvidence = workItems.filter((wi) => wi.validationStatus && wi.validationStatus !== "not-started");
22687
22840
  const plans = getDeprecationPlans(dir);
22688
- const deprecationFindings = plans.flatMap((plan) => getDeprecationPlan(dir, plan.id)?.targets.flatMap(validateTarget) ?? []);
22841
+ const planDetails = plans.map((plan) => getDeprecationPlan(dir, plan.id)).filter((plan) => plan !== null);
22842
+ const plansWithoutTargets = planDetails.filter((plan) => plan.targets.length === 0);
22843
+ const plansWithTargets = planDetails.filter((plan) => plan.targets.length > 0);
22844
+ const targetFindingsByPlan = new Map(plansWithTargets.map((plan) => [
22845
+ plan.id,
22846
+ plan.targets.flatMap(validateTarget)
22847
+ ]));
22848
+ const deprecationFindings = [...targetFindingsByPlan.values()].flat();
22849
+ const plansWithoutStructuralFindings = plansWithTargets.filter((plan) => (targetFindingsByPlan.get(plan.id) ?? []).length === 0);
22689
22850
  const config = loadConfig(dir);
22690
22851
  const topology = config ? buildGraph(dir, config, { scope: "all" }, now) : null;
22691
- const topologyHints = topology ? buildGraphHints(dir, topology, now).summary.hints : null;
22852
+ const graphHints = topology ? buildGraphHints(dir, topology, now) : null;
22853
+ const topologyHints = graphHints?.summary.hints ?? null;
22854
+ const currentConsistencyFindings = [
22855
+ ...graphHints?.hints.map(graphHintFinding) ?? [],
22856
+ ...deprecationFindings.map((finding, index) => ({
22857
+ id: `deprecation-target:${index + 1}`,
22858
+ category: "consistency",
22859
+ classification: "consistency_violation",
22860
+ resolution_status: "open",
22861
+ source: "deprecation-target-validation",
22862
+ affected_artifacts: finding.target ? [finding.target] : [],
22863
+ priority: finding.severity === "error" ? "high" : "medium",
22864
+ evidence: finding.message,
22865
+ explanation: "A deterministic deprecation target consistency check reported a finding.",
22866
+ suggested_action: "Review the affected deprecation target and its declared lifecycle evidence."
22867
+ })),
22868
+ ...h.available && h.total_runs >= 2 ? h.threads.filter((thread) => thread.status === "open").map((thread) => ({
22869
+ id: `guard-history:${thread.code_path}`,
22870
+ category: "consistency",
22871
+ classification: "historical_drift",
22872
+ resolution_status: "open",
22873
+ source: "guard-history",
22874
+ affected_artifacts: [thread.code_path, ...thread.related_artifacts],
22875
+ priority: "medium",
22876
+ evidence: `Recorded Guard observations from ${thread.first_detected} through ${thread.last_seen} remain unresolved.`,
22877
+ explanation: "Comparable Guard runs observed a possible code/knowledge drift thread over time.",
22878
+ suggested_action: "Review the recorded drift thread and update the relevant knowledge or ownership evidence."
22879
+ })) : []
22880
+ ];
22692
22881
  const actions = [];
22693
22882
  if (!h.available) {
22694
- actions.push("Run `kaddo guard --record` to start recording guard history.");
22883
+ 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.");
22695
22884
  } else {
22696
22885
  if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
22697
22886
  actions.push("Run `kaddo guard --record` before important commits.");
@@ -22704,9 +22893,19 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22704
22893
  consistency_evidence: [
22705
22894
  { id: "guard-current-consistency", label: "Current Guard consistency", classification: h.available ? "observed" : "unknown", reason: h.available ? `${h.total_runs} recorded Guard run(s) provide deterministic consistency evidence.` : "No recorded Guard history is available." },
22706
22895
  { 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." },
22707
- { 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.` },
22896
+ { id: "deprecation-consistency", label: "Deprecation consistency", classification: plans.length === 0 ? "not_applicable" : plansWithTargets.length === 0 ? "unknown" : deprecationFindings.length === 0 ? "derived" : "observed", reason: plans.length === 0 ? "No deprecation plans exist in this project." : plansWithTargets.length === 0 ? `${plansWithoutTargets.length} plan(s) have no targets, so target consistency was not evaluated.` : deprecationFindings.length === 0 ? `${plansWithTargets.length} plan(s) with targets passed deterministic target consistency checks; ${plansWithoutTargets.length} plan(s) remain unevaluated because they have no targets.` : `${deprecationFindings.length} deterministic deprecation consistency finding(s) were detected.` },
22708
22897
  { 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).` }
22709
22898
  ],
22899
+ current_consistency_findings: currentConsistencyFindings,
22900
+ structural_consistency: {
22901
+ deprecation_target_checks: plans.length === 0 ? "not_applicable" : plansWithTargets.length === 0 ? "not_evaluated" : deprecationFindings.length === 0 ? "passed" : "findings_detected",
22902
+ plans_discovered: plans.length,
22903
+ plans_without_targets: plansWithoutTargets.length,
22904
+ plans_with_targets_evaluated: plansWithTargets.length,
22905
+ structural_findings: deprecationFindings.length,
22906
+ plans_without_structural_findings: plansWithoutStructuralFindings.length,
22907
+ 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."
22908
+ },
22710
22909
  guard_history: {
22711
22910
  available: h.available,
22712
22911
  total_runs: h.total_runs,
@@ -22732,6 +22931,43 @@ function renderDriftMarkdown(r) {
22732
22931
  L.push("## Consistency Evidence", "");
22733
22932
  for (const item of r.consistency_evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22734
22933
  L.push("");
22934
+ const findingGroups = [
22935
+ { classification: "consistency_violation", title: "Consistency Violations" },
22936
+ { classification: "coverage_gap", title: "Coverage Gaps" },
22937
+ { classification: "review_hint", title: "Review Hints" },
22938
+ { classification: "historical_drift", title: "Historical Drift" }
22939
+ ];
22940
+ L.push("## Current Findings Summary", "");
22941
+ for (const group of findingGroups) {
22942
+ const count = r.current_consistency_findings.filter((finding) => finding.classification === group.classification).length;
22943
+ const unavailable = group.classification === "historical_drift" && !r.guard_history.available;
22944
+ L.push(`- ${group.title}: ${unavailable ? "not available \u2014 no recorded Guard runs" : count}`);
22945
+ }
22946
+ L.push("");
22947
+ L.push("## Current Consistency Findings", "");
22948
+ if (r.current_consistency_findings.length === 0) L.push("No findings detected by the executed consistency checks.", "");
22949
+ const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
22950
+ for (const group of findingGroups) {
22951
+ const findings = r.current_consistency_findings.filter((finding) => finding.classification === group.classification);
22952
+ if (findings.length === 0) continue;
22953
+ L.push(`### ${group.title}`, "");
22954
+ L.push("| Classification | Priority | Status | Source | Affected | Finding | Suggested action |");
22955
+ L.push("|---|---|---|---|---|---|---|");
22956
+ for (const finding of findings) {
22957
+ L.push(`| ${finding.classification} | ${finding.priority} | ${finding.resolution_status} | ${cell(finding.source)} | ${cell(finding.affected_artifacts.join(", ") || "not available")} | ${cell(finding.explanation)} Evidence: ${cell(finding.evidence)} | ${cell(finding.suggested_action)} |`);
22958
+ }
22959
+ L.push("");
22960
+ }
22961
+ L.push("## Structural Consistency Boundaries", "");
22962
+ L.push(`- Deprecation target checks: ${r.structural_consistency.deprecation_target_checks}`);
22963
+ L.push(`- Plans discovered: ${r.structural_consistency.plans_discovered}`);
22964
+ L.push(`- Plans without targets: ${r.structural_consistency.plans_without_targets}`);
22965
+ L.push(`- Plans with targets evaluated: ${r.structural_consistency.plans_with_targets_evaluated}`);
22966
+ L.push(`- Structural findings: ${r.structural_consistency.structural_findings}`);
22967
+ L.push(`- Plans without structural findings: ${r.structural_consistency.plans_without_structural_findings}`);
22968
+ if (r.structural_consistency.plans_without_targets > 0) L.push("- Target consistency for plans without targets: not evaluated \u2014 no targets defined.");
22969
+ L.push(`- Note: ${r.structural_consistency.note}`);
22970
+ L.push("");
22735
22971
  if (!r.guard_history.available) {
22736
22972
  L.push("## Guard History", "");
22737
22973
  L.push("No guard history recorded yet.");
@@ -22803,6 +23039,8 @@ function serializeDriftJson(r) {
22803
23039
  project: r.project,
22804
23040
  project_context: r.project_context,
22805
23041
  consistency_evidence: r.consistency_evidence,
23042
+ current_consistency_findings: r.current_consistency_findings,
23043
+ structural_consistency: r.structural_consistency,
22806
23044
  guard_history: r.guard_history,
22807
23045
  drift_warnings: r.drift_warnings,
22808
23046
  hotspots: r.hotspots,
@@ -25773,10 +26011,10 @@ workItemCmd.command("import [file]").description("Import a Work Item from text o
25773
26011
  await runWorkItemImport(cwd(), file, opts);
25774
26012
  });
25775
26013
  var reportCmd = program.command("report").description("Generate Kaddo reports");
25776
- reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/impact-report.md)").action((opts) => {
26014
+ reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--details", "Include the complete Markdown inventory").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/impact-report.md)").action((opts) => {
25777
26015
  runReportImpact(opts);
25778
26016
  });
25779
- program.command("impact").description("Alias for `kaddo report impact`").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--output <path>", "Write the report to a file").action((opts) => {
26017
+ program.command("impact").description("Alias for `kaddo report impact`").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--details", "Include the complete Markdown inventory").option("--output <path>", "Write the report to a file").action((opts) => {
25780
26018
  runReportImpact(opts);
25781
26019
  });
25782
26020
  reportCmd.command("savings").description("Estimated Savings Report: evidence-based time/effort/value estimates (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default) or active").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/savings-report.md)").action((opts) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.124.2",
3
+ "version": "3.124.4",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {