@kaddo/cli 3.124.2 → 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 +169 -14
  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;
@@ -21975,10 +21993,12 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
21975
21993
  }
21976
21994
  const ownershipOverlaps = gaps.ownership_overlaps.length;
21977
21995
  let g;
21996
+ let graphHintEntries = [];
21978
21997
  const config = loadConfig(dir);
21979
21998
  if (config) {
21980
21999
  const graph = buildGraph(dir, config, { scope: resolvedScope }, now);
21981
22000
  const hints = buildGraphHints(dir, graph, now);
22001
+ graphHintEntries = hints.hints;
21982
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 };
21983
22003
  } else {
21984
22004
  g = { available: false, scope: resolvedScope, scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
@@ -22051,6 +22071,37 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22051
22071
  ai_context_readiness: aiReady,
22052
22072
  maintenance_readiness: levelFromRatio((coverageRatio(withOwnership) + (deliveryTraceable ? 1 : 0)) / 2)
22053
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));
22054
22105
  let score = null;
22055
22106
  let score_breakdown = null;
22056
22107
  if (total > 0) {
@@ -22089,16 +22140,18 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22089
22140
  if (exp.roadmap.remaining > 0) actions.push(`Materialize the ${exp.roadmap.remaining} remaining roadmap candidate(s) with \`kaddo create --from roadmap\`.`);
22090
22141
  for (const a of [
22091
22142
  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")
22143
+ groupedAction(gaps.missing_source, "Add `source`/`source_id` to")
22096
22144
  ]) if (a) actions.push(a);
22097
22145
  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`).");
22146
+ for (const finding of findings) {
22147
+ if (!actions.includes(finding.suggested_action)) actions.push(finding.suggested_action);
22148
+ }
22099
22149
  if (skills.length === 0) actions.push("Install reusable skills with `kaddo add skills`.");
22100
22150
  actions.push("Run `kaddo guard` before committing to catch knowledge drift.");
22101
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
+ }
22102
22155
  if (total > 0) summary.push(`${withOwnership}/${total} Work Items include code ownership.`);
22103
22156
  if (g.available) summary.push(`The knowledge graph is ${g.quality} with ${g.nodes} nodes and ${g.edges} edges (${g.scope} scope).`);
22104
22157
  else summary.push("The knowledge graph has not been exported yet.");
@@ -22120,6 +22173,15 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22120
22173
  default_scope: "all",
22121
22174
  scope_source: scopeSource,
22122
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,
22123
22185
  knowledge_health,
22124
22186
  knowledge_coverage,
22125
22187
  ownership_coverage: {
@@ -22183,6 +22245,27 @@ function renderImpactMarkdown(r) {
22183
22245
  L.push("## Executive Summary", "");
22184
22246
  for (const s2 of r.executive_summary) L.push(`- ${s2}`);
22185
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("");
22186
22269
  L.push("## Evidence and Applicability", "");
22187
22270
  for (const item of r.evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22188
22271
  L.push("");
@@ -22282,12 +22365,7 @@ function renderImpactMarkdown(r) {
22282
22365
  L.push("");
22283
22366
  };
22284
22367
  gapSection("Work Items missing source", gp.missing_source);
22285
- gapSection("Work Items missing initiative", gp.missing_initiative);
22286
22368
  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
22369
  if (gp.broad_ownership_globs.length > 0) {
22292
22370
  L.push("### Broad ownership globs", "");
22293
22371
  for (const b of gp.broad_ownership_globs) {
@@ -22306,10 +22384,26 @@ function renderImpactMarkdown(r) {
22306
22384
  }
22307
22385
  L.push("");
22308
22386
  }
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;
22387
+ const anyGaps = gp.missing_source.length + gp.missing_code_ownership.length + gp.broad_ownership_globs.length;
22310
22388
  if (anyGaps === 0) {
22311
22389
  L.push("No actionable knowledge gaps detected. \u{1F389}", "");
22312
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("");
22313
22407
  if (r.score_breakdown) {
22314
22408
  L.push("## Score Breakdown", "");
22315
22409
  const b = r.score_breakdown;
@@ -22502,6 +22596,16 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22502
22596
  } else {
22503
22597
  actions.push("Use drift history to calibrate `rework_hours_avoided_per_resolved_drift`.");
22504
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: [] };
22505
22609
  return {
22506
22610
  generated_at: now.toISOString(),
22507
22611
  project: impact.project,
@@ -22553,6 +22657,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
22553
22657
  },
22554
22658
  total: { estimated_hours_saved: observedHours, estimated_value: observedValue, currency: a.currency },
22555
22659
  confidence: { level, reasons },
22660
+ calibration_opportunities: calibrationOpportunities,
22556
22661
  suggested_actions: actions
22557
22662
  };
22558
22663
  }
@@ -22634,6 +22739,17 @@ function renderSavingsMarkdown(r) {
22634
22739
  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
22635
22740
  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
22636
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("");
22637
22753
  L.push("## Suggested Actions", "");
22638
22754
  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
22639
22755
  L.push("");
@@ -22688,10 +22804,24 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22688
22804
  const deprecationFindings = plans.flatMap((plan) => getDeprecationPlan(dir, plan.id)?.targets.flatMap(validateTarget) ?? []);
22689
22805
  const config = loadConfig(dir);
22690
22806
  const topology = config ? buildGraph(dir, config, { scope: "all" }, now) : null;
22691
- 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
+ ];
22692
22822
  const actions = [];
22693
22823
  if (!h.available) {
22694
- 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.");
22695
22825
  } else {
22696
22826
  if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
22697
22827
  actions.push("Run `kaddo guard --record` before important commits.");
@@ -22707,6 +22837,11 @@ function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
22707
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.` },
22708
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).` }
22709
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
+ },
22710
22845
  guard_history: {
22711
22846
  available: h.available,
22712
22847
  total_runs: h.total_runs,
@@ -22732,6 +22867,24 @@ function renderDriftMarkdown(r) {
22732
22867
  L.push("## Consistency Evidence", "");
22733
22868
  for (const item of r.consistency_evidence) L.push(`- ${item.label}: ${item.classification} \u2014 ${item.reason}`);
22734
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("");
22735
22888
  if (!r.guard_history.available) {
22736
22889
  L.push("## Guard History", "");
22737
22890
  L.push("No guard history recorded yet.");
@@ -22803,6 +22956,8 @@ function serializeDriftJson(r) {
22803
22956
  project: r.project,
22804
22957
  project_context: r.project_context,
22805
22958
  consistency_evidence: r.consistency_evidence,
22959
+ current_consistency_findings: r.current_consistency_findings,
22960
+ structural_consistency: r.structural_consistency,
22806
22961
  guard_history: r.guard_history,
22807
22962
  drift_warnings: r.drift_warnings,
22808
22963
  hotspots: r.hotspots,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.124.2",
3
+ "version": "3.124.3",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {