@kaddo/cli 3.97.0 → 3.99.0

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 (3) hide show
  1. package/dist/core.js +275 -30
  2. package/dist/index.js +286 -30
  3. package/package.json +1 -1
package/dist/core.js CHANGED
@@ -4086,6 +4086,89 @@ actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED |
4086
4086
  Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
4087
4087
  `
4088
4088
  );
4089
+ var LEGACY_RISK_ASSESSMENT = skill(
4090
+ "legacy-risk-assessment",
4091
+ "Legacy Risk Assessment Skill",
4092
+ "delivery",
4093
+ ["legacy-agent", "implementation-agent", "work-item-agent"],
4094
+ `
4095
+ # Legacy Risk Assessment Skill
4096
+
4097
+ ## Purpose
4098
+
4099
+ Evaluate a planned change against known legacy risks, unknowns and modernization candidates
4100
+ to identify which findings require additional consideration before or after implementation.
4101
+
4102
+ ## When to use
4103
+
4104
+ Before or during implementation of a Work Item in a legacy project \u2014 especially when the
4105
+ Work Item touches areas flagged in \`knowledge/legacy/risks.md\`.
4106
+
4107
+ ## Inputs
4108
+
4109
+ - The Work Item (id, ACs, affected_modules, affected areas).
4110
+ - \`knowledge/legacy/risks.md\` \u2014 known risks with RISK-xxx identifiers.
4111
+ - \`knowledge/legacy/unknowns.md\` \u2014 known unknowns with UNK-xxx identifiers.
4112
+ - \`knowledge/legacy/modernization-candidates.md\` \u2014 MOD-xxx candidates.
4113
+ - System Graph (\`.kaddo/graph.json\`) when available.
4114
+ - Implementation Handoff or Implementation Evidence when available.
4115
+
4116
+ ## Output
4117
+
4118
+ A risk assessment report listing which legacy findings are relevant to the planned change,
4119
+ their intersection with the affected areas, and recommended actions.
4120
+
4121
+ ### Output template
4122
+
4123
+ \`\`\`markdown
4124
+ # Legacy Risk Assessment \u2014 <WI id>
4125
+
4126
+ ## Relevant Risks
4127
+
4128
+ ### RISK-xxx: <title>
4129
+ - **Intersection:** <how this risk relates to the planned change>
4130
+ - **Action:** mitigate before | monitor during | verify after | not applicable
4131
+ - **Notes:** <additional context>
4132
+
4133
+ ## Relevant Unknowns
4134
+
4135
+ ### UNK-xxx: <question>
4136
+ - **Impact on this WI:** <how this unknown affects implementation>
4137
+ - **Recommended:** investigate before | accept as assumption | defer
4138
+
4139
+ ## Relevant Modernization Candidates
4140
+
4141
+ ### MOD-xxx: <title>
4142
+ - **Alignment:** <how this WI relates to the modernization target>
4143
+ - **Recommendation:** advance | defer | not relevant
4144
+
4145
+ ## Summary
4146
+
4147
+ - Risks requiring pre-implementation mitigation: <count>
4148
+ - Unknowns requiring investigation: <count>
4149
+ - Modernization candidates advanced by this WI: <count>
4150
+ - Overall risk posture: low | medium | high
4151
+ \`\`\`
4152
+
4153
+ ## Rules
4154
+
4155
+ - Reference findings by their stable identifiers \u2014 do not copy full content.
4156
+ - Assess intersection based on affected areas (file paths, modules, system entities).
4157
+ - Not every legacy finding is relevant \u2014 filter to those that intersect the change.
4158
+ - Do not block implementation solely because legacy risks exist \u2014 provide context for
4159
+ informed decision-making.
4160
+ - When the System Graph is available, use entity relationships to discover indirect risk
4161
+ intersections.
4162
+
4163
+ ## Quality checklist
4164
+
4165
+ - Every referenced finding uses its stable identifier (RISK-xxx, UNK-xxx, MOD-xxx).
4166
+ - Each relevant finding has an explicit action recommendation.
4167
+ - Findings not relevant to the change are excluded, not listed as "not applicable".
4168
+ - Overall risk posture is stated.
4169
+ - The assessment is proportional \u2014 a small change gets a brief assessment.
4170
+ `
4171
+ );
4089
4172
  var SKILLS = [
4090
4173
  ADR_WRITING,
4091
4174
  WORK_ITEM_REFINEMENT,
@@ -4095,10 +4178,11 @@ var SKILLS = [
4095
4178
  LEARNING_CAPTURE,
4096
4179
  IMPLEMENTATION_PLANNING,
4097
4180
  MODULE_CONTEXT_REFINEMENT,
4098
- EVIDENCE_VERIFICATION
4181
+ EVIDENCE_VERIFICATION,
4182
+ LEGACY_RISK_ASSESSMENT
4099
4183
  ];
4100
4184
  var SKILL_GROUPS = {
4101
- delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
4185
+ delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
4102
4186
  tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
4103
4187
  integration: ["capsule-writing"]
4104
4188
  };
@@ -4847,7 +4931,11 @@ Adapt priorities to the project state from the context pack:
4847
4931
  - **new** \u2014 prioritize foundational capabilities and initial product direction.
4848
4932
  - **pre-ai** \u2014 prioritize organizing existing capabilities and reducing knowledge gaps.
4849
4933
  - **legacy** \u2014 prioritize risk reduction, unknowns and safe modernization before feature
4850
- delivery.
4934
+ delivery. **Explicitly consult** \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\`
4935
+ and \`knowledge/legacy/modernization-candidates.md\` when they exist. Every legacy risk
4936
+ (RISK-xxx) and modernization candidate (MOD-xxx) should be considered as a source signal
4937
+ for roadmap candidates. Reference them by their stable identifiers so downstream Work Items
4938
+ can trace back to the original finding.
4851
4939
 
4852
4940
  ## Grounding rules (VS-077)
4853
4941
 
@@ -4859,7 +4947,7 @@ Every candidate initiative must be **grounded** in the knowledge base \u2014 nev
4859
4947
  - **Related capabilities** \u2014 one or more existing/partial capabilities.
4860
4948
  - **Source signals** \u2014 at least one traceable reason: Capability Gap, Roadmap Candidate Signal, Risk,
4861
4949
  Open Question, Assumption, Deferred Decision, Tech Decision Candidate, ADR, Business Goal,
4862
- Operational Need or Legacy Modernization Signal.
4950
+ Operational Need, Legacy Modernization Signal, Legacy Risk (RISK-xxx) or Legacy Unknown (UNK-xxx).
4863
4951
  - **Expected value**, **Risks**, **Dependencies**, and **Suggested Work Items** (candidates only).
4864
4952
 
4865
4953
  Do **not** emit a candidate with no source signal. Keep initiatives at initiative granularity (small
@@ -4974,10 +5062,13 @@ var LEGACY_AGENT = `# Legacy Agent
4974
5062
  ## Role
4975
5063
 
4976
5064
  You are the Kaddo Legacy Agent. Your job is to analyze a legacy or risky project before
4977
- anyone changes it, using a Kaddo Context Pack.
5065
+ anyone changes it, using a Kaddo Context Pack enriched with scan signals and system
5066
+ topology.
4978
5067
 
4979
5068
  You do not write code. You surface risk, unknowns and safe first steps, marking
4980
- assumptions clearly.
5069
+ assumptions clearly. Your output feeds the downstream Kaddo lifecycle \u2014 roadmap, Work
5070
+ Items, Implementation Handoff, Evidence, Verification and Learning \u2014 so findings must be
5071
+ structured and traceable.
4981
5072
 
4982
5073
  ## When to Use
4983
5074
 
@@ -4988,26 +5079,45 @@ before planning modernization or changes.
4988
5079
 
4989
5080
  Provide \`.kaddo/context-pack.md\` as the primary input.
4990
5081
 
4991
- Optionally provide: incident history, known pain points, dependency manifests.
5082
+ Additionally consult (use whatever is available; mark missing sources as assumptions):
5083
+
5084
+ - \`.kaddo/scan.json\` \u2014 scan signals (auth, payments, webhooks, storage, background_jobs,
5085
+ email, database, migrations, api_routes, tests, security, infrastructure).
5086
+ - System Graph (\`.kaddo/graph.json\` / \`.kaddo/graph.mmd\`) \u2014 entity relationships and
5087
+ topology when available.
5088
+ - \`knowledge/tech/current-state.md\` \u2014 existing architecture baseline.
5089
+ - \`knowledge/product/capabilities.md\` \u2014 capability inventory with statuses and domains.
5090
+ - Incident history, known pain points, dependency manifests (if provided by the user).
4992
5091
 
4993
5092
  ## Expected Output
4994
5093
 
4995
- Markdown artifacts intended to be saved as:
5094
+ Three structured Markdown artifacts intended to be saved as:
4996
5095
 
4997
5096
  - \`knowledge/legacy/risks.md\`
4998
5097
  - \`knowledge/legacy/unknowns.md\`
4999
5098
  - \`knowledge/legacy/modernization-candidates.md\`
5000
5099
 
5001
- ## Instructions
5100
+ Each artifact uses Kaddo template format with front matter and structured entries that
5101
+ downstream agents (roadmap-agent, work-item-agent, implementation-agent) can reference.
5002
5102
 
5003
- Analyze the context pack and identify:
5103
+ ## Instructions
5004
5104
 
5005
- 1. Unknowns.
5006
- 2. Risky areas.
5007
- 3. Dependencies.
5008
- 4. Modernization candidates.
5009
- 5. Safe first steps.
5010
- 6. Areas requiring human validation.
5105
+ 1. **Ingest available signals.** Read scan results, context pack, system graph and any
5106
+ existing knowledge. Do not skip available sources.
5107
+ 2. **Identify risks.** For each risk, provide a stable identifier (RISK-001, RISK-002, ...),
5108
+ the affected area (file paths, modules, or system components), why it is risky, blast
5109
+ radius (local / module / cross-cutting / system-wide), confidence (high / medium / low),
5110
+ related scan signals, and a mitigation suggestion.
5111
+ 3. **Identify unknowns.** For each unknown, provide a stable identifier (UNK-001, UNK-002, ...),
5112
+ the question, why it matters, how to find out, and related risks (RISK-xxx references).
5113
+ 4. **Identify modernization candidates.** For each candidate, provide a stable identifier
5114
+ (MOD-001, MOD-002, ...), current state, target state, value, risk, suggested Knowledge
5115
+ Level (K1\u2013K4), related risks and unknowns, and affected system entities when the Graph
5116
+ is available.
5117
+ 5. **Identify dependencies** \u2014 external and internal dependencies that constrain changes.
5118
+ 6. **Propose safe first steps** \u2014 small, low-risk actions that reduce unknowns or risk.
5119
+ 7. **Flag areas requiring human validation** \u2014 decisions, assumptions or trade-offs that
5120
+ only a human can resolve.
5011
5121
 
5012
5122
  ## Constraints
5013
5123
 
@@ -5015,33 +5125,78 @@ Analyze the context pack and identify:
5015
5125
  - Prefer small, low-risk first steps.
5016
5126
  - Mark assumptions and confidence clearly.
5017
5127
  - Do not write code.
5128
+ - Every risk, unknown and modernization candidate must have a stable identifier (RISK-xxx,
5129
+ UNK-xxx, MOD-xxx) so downstream artifacts can reference them.
5130
+ - When System Graph topology is available, reference affected entities by their graph id.
5131
+ - Do not duplicate capability inventory work \u2014 reference \`capabilities.md\` when it exists.
5018
5132
 
5019
5133
  ## Output Format
5020
5134
 
5135
+ ### knowledge/legacy/risks.md
5136
+
5021
5137
  \`\`\`markdown
5022
- # Legacy Analysis
5138
+ ---
5139
+ type: legacy-risks
5140
+ generated_by: legacy-agent
5141
+ ---
5023
5142
 
5024
- Generated from Kaddo Context Pack.
5143
+ # Legacy Risks
5025
5144
 
5026
- ## Risks
5145
+ ## RISK-001: <Short title>
5027
5146
 
5028
- ### <Risk>
5147
+ - **Area:** <file paths, modules, or components>
5148
+ - **Why risky:** <explanation>
5149
+ - **Blast radius:** local | module | cross-cutting | system-wide
5150
+ - **Confidence:** high | medium | low
5151
+ - **Scan signals:** <related signals from scan.json, or "none detected">
5152
+ - **Graph entities:** <related system graph entities, or "Graph unavailable">
5153
+ - **Mitigation:** <suggested approach>
5029
5154
 
5030
- **Area:**
5155
+ ## RISK-002: ...
5156
+ \`\`\`
5031
5157
 
5032
- **Why it is risky:**
5158
+ ### knowledge/legacy/unknowns.md
5033
5159
 
5034
- **Confidence:**
5160
+ \`\`\`markdown
5161
+ ---
5162
+ type: legacy-unknowns
5163
+ generated_by: legacy-agent
5164
+ ---
5035
5165
 
5036
- ## Unknowns
5166
+ # Legacy Unknowns
5037
5167
 
5038
- ## Dependencies
5168
+ ## UNK-001: <Question>
5039
5169
 
5040
- ## Modernization Candidates
5170
+ - **Why it matters:** <impact if left unresolved>
5171
+ - **How to find out:** <investigation steps>
5172
+ - **Related risks:** RISK-001, RISK-003
5173
+ - **Blocking:** yes | no | unknown
5041
5174
 
5042
- ## Safe First Steps
5175
+ ## UNK-002: ...
5176
+ \`\`\`
5043
5177
 
5044
- ## Areas Requiring Human Validation
5178
+ ### knowledge/legacy/modernization-candidates.md
5179
+
5180
+ \`\`\`markdown
5181
+ ---
5182
+ type: modernization-candidates
5183
+ generated_by: legacy-agent
5184
+ ---
5185
+
5186
+ # Modernization Candidates
5187
+
5188
+ ## MOD-001: <Short title>
5189
+
5190
+ - **Current state:** <what exists today>
5191
+ - **Target state:** <desired outcome>
5192
+ - **Value:** <why this modernization matters>
5193
+ - **Risk:** low | medium | high
5194
+ - **Suggested Knowledge Level:** K1 | K2 | K3 | K4
5195
+ - **Related risks:** RISK-xxx
5196
+ - **Related unknowns:** UNK-xxx
5197
+ - **Affected entities:** <system graph entities, or "Graph unavailable">
5198
+
5199
+ ## MOD-002: ...
5045
5200
  \`\`\`
5046
5201
 
5047
5202
  ## Where to Save the Result
@@ -5052,10 +5207,15 @@ Save risks as \`knowledge/legacy/risks.md\`, unknowns as
5052
5207
 
5053
5208
  ## Quality Checklist
5054
5209
 
5055
- - Risks are backed by evidence.
5210
+ - Every risk has a stable RISK-xxx identifier, blast radius, and confidence level.
5211
+ - Every unknown has a stable UNK-xxx identifier and related risk references.
5212
+ - Every modernization candidate has a stable MOD-xxx identifier and Knowledge Level.
5213
+ - Scan signals are referenced when available \u2014 findings are grounded in detected signals.
5214
+ - System Graph entities are referenced when topology is available.
5056
5215
  - Safe first steps are small and low-risk.
5057
- - Unknowns are explicit.
5216
+ - Assumptions are marked explicitly with confidence.
5058
5217
  - Areas needing human validation are flagged.
5218
+ - Identifiers are unique and sequential within each artifact.
5059
5219
  `;
5060
5220
  var ADR_AGENT = `# ADR Agent
5061
5221
 
@@ -5277,6 +5437,14 @@ the decision is still a candidate in knowledge/tech/decision-candidates.md with
5277
5437
  that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and record
5278
5438
  \`decision_candidates: [<title>]\` \u2014 do not implement work that depends on an unformalized decision
5279
5439
  without surfacing it. -->
5440
+
5441
+ **Related legacy findings:** <!-- for legacy projects (WI-012): when
5442
+ \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\` or
5443
+ \`knowledge/legacy/modernization-candidates.md\` exist, check whether any findings (RISK-xxx,
5444
+ UNK-xxx, MOD-xxx) are relevant to this Work Item's scope. Add \`legacy_risks: [RISK-001, ...]\`
5445
+ and \`legacy_unknowns: [UNK-001, ...]\` to the front matter when applicable. Do NOT copy the full
5446
+ finding content \u2014 reference by identifier. Include relevant findings in the Scope unknowns
5447
+ section when they affect implementation decisions. -->
5280
5448
  \`\`\`
5281
5449
 
5282
5450
  ### Preserve roadmap metadata (VS-077 / VS-078)
@@ -9427,6 +9595,39 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
9427
9595
  return node;
9428
9596
  }
9429
9597
 
9598
+ // src/core/legacy-knowledge.ts
9599
+ var RISKS_PATH = "knowledge/legacy/risks.md";
9600
+ var UNKNOWNS_PATH = "knowledge/legacy/unknowns.md";
9601
+ var CANDIDATES_PATH = "knowledge/legacy/modernization-candidates.md";
9602
+ function hasLegacyKnowledge(dir) {
9603
+ return exists(join(dir, RISKS_PATH)) || exists(join(dir, UNKNOWNS_PATH)) || exists(join(dir, CANDIDATES_PATH));
9604
+ }
9605
+ var ID_PATTERN = /^##\s+(RISK-\d+|UNK-\d+|MOD-\d+)/gm;
9606
+ function extractIdentifiers(content, prefix) {
9607
+ const ids = [];
9608
+ for (const m of content.matchAll(ID_PATTERN)) {
9609
+ if (m[1].startsWith(prefix)) ids.push(m[1]);
9610
+ }
9611
+ return ids;
9612
+ }
9613
+ function readArtifact(dir, rel, prefix) {
9614
+ const abs = join(dir, rel);
9615
+ if (!exists(abs)) return { path: rel, exists: false, identifiers: [] };
9616
+ const content = readFile(abs);
9617
+ return { path: rel, exists: true, identifiers: extractIdentifiers(content, prefix) };
9618
+ }
9619
+ function getLegacyKnowledgeSummary(dir) {
9620
+ const risks = readArtifact(dir, RISKS_PATH, "RISK-");
9621
+ const unknowns = readArtifact(dir, UNKNOWNS_PATH, "UNK-");
9622
+ const candidates = readArtifact(dir, CANDIDATES_PATH, "MOD-");
9623
+ return {
9624
+ available: risks.exists || unknowns.exists || candidates.exists,
9625
+ risks,
9626
+ unknowns,
9627
+ candidates
9628
+ };
9629
+ }
9630
+
9430
9631
  // src/core/work-item-refinement.ts
9431
9632
  function toCapture(q) {
9432
9633
  return { id: q.id, prompt: q.prompt, placeholder: q.placeholder, field: q.frontMatterField, required: q.required };
@@ -9488,6 +9689,19 @@ function buildRefinementHandoff(dir, workItemId) {
9488
9689
  "repository, Knowledge and mapped modules \u2014 the Graph is enrichment, not a prerequisite."
9489
9690
  );
9490
9691
  }
9692
+ if (hasLegacyKnowledge(dir)) {
9693
+ lines.push(
9694
+ "",
9695
+ "This is a legacy project with existing legacy analysis. When refining, consult:",
9696
+ "- `knowledge/legacy/risks.md` \u2014 known risks (RISK-xxx identifiers).",
9697
+ "- `knowledge/legacy/unknowns.md` \u2014 known unknowns (UNK-xxx identifiers).",
9698
+ "- `knowledge/legacy/modernization-candidates.md` \u2014 modernization candidates (MOD-xxx identifiers).",
9699
+ "",
9700
+ "Reference only the findings relevant to this Work Item's scope \u2014 do not copy all legacy",
9701
+ "knowledge into the Work Item. Add `legacy_risks` and `legacy_unknowns` to the front matter",
9702
+ "when applicable, using the stable identifiers (e.g. `legacy_risks: [RISK-001, RISK-003]`)."
9703
+ );
9704
+ }
9491
9705
  lines.push(
9492
9706
  "",
9493
9707
  `Update the canonical Work Item ${wi.id} with:`,
@@ -9602,6 +9816,37 @@ function buildImplementationHandoff(dir, workItemId) {
9602
9816
  "4. inspect the actual implementation in the repository for each candidate."
9603
9817
  );
9604
9818
  }
9819
+ const legacy = getLegacyKnowledgeSummary(dir);
9820
+ if (legacy.available) {
9821
+ lines.push(
9822
+ "",
9823
+ "--- Legacy Context ---",
9824
+ "",
9825
+ "This project has legacy analysis knowledge. Before implementing, consult the relevant",
9826
+ "legacy findings for the areas this Work Item will modify:"
9827
+ );
9828
+ if (legacy.risks.exists) {
9829
+ lines.push(
9830
+ `- Risks (${legacy.risks.identifiers.length} findings): \`${legacy.risks.path}\``
9831
+ );
9832
+ }
9833
+ if (legacy.unknowns.exists) {
9834
+ lines.push(
9835
+ `- Unknowns (${legacy.unknowns.identifiers.length} findings): \`${legacy.unknowns.path}\``
9836
+ );
9837
+ }
9838
+ if (legacy.candidates.exists) {
9839
+ lines.push(
9840
+ `- Modernization candidates (${legacy.candidates.identifiers.length} findings): \`${legacy.candidates.path}\``
9841
+ );
9842
+ }
9843
+ lines.push(
9844
+ "",
9845
+ "Reference relevant findings by their stable identifiers (RISK-xxx, UNK-xxx, MOD-xxx).",
9846
+ "Highlight risks that intersect with the areas to be modified in the Design Deliberation.",
9847
+ "Do not copy all legacy knowledge \u2014 assemble proportionally to scope."
9848
+ );
9849
+ }
9605
9850
  lines.push(
9606
9851
  "",
9607
9852
  "--- Implementation Plan ---",
package/dist/index.js CHANGED
@@ -2901,6 +2901,89 @@ actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED |
2901
2901
  Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
2902
2902
  `
2903
2903
  );
2904
+ var LEGACY_RISK_ASSESSMENT = skill(
2905
+ "legacy-risk-assessment",
2906
+ "Legacy Risk Assessment Skill",
2907
+ "delivery",
2908
+ ["legacy-agent", "implementation-agent", "work-item-agent"],
2909
+ `
2910
+ # Legacy Risk Assessment Skill
2911
+
2912
+ ## Purpose
2913
+
2914
+ Evaluate a planned change against known legacy risks, unknowns and modernization candidates
2915
+ to identify which findings require additional consideration before or after implementation.
2916
+
2917
+ ## When to use
2918
+
2919
+ Before or during implementation of a Work Item in a legacy project \u2014 especially when the
2920
+ Work Item touches areas flagged in \`knowledge/legacy/risks.md\`.
2921
+
2922
+ ## Inputs
2923
+
2924
+ - The Work Item (id, ACs, affected_modules, affected areas).
2925
+ - \`knowledge/legacy/risks.md\` \u2014 known risks with RISK-xxx identifiers.
2926
+ - \`knowledge/legacy/unknowns.md\` \u2014 known unknowns with UNK-xxx identifiers.
2927
+ - \`knowledge/legacy/modernization-candidates.md\` \u2014 MOD-xxx candidates.
2928
+ - System Graph (\`.kaddo/graph.json\`) when available.
2929
+ - Implementation Handoff or Implementation Evidence when available.
2930
+
2931
+ ## Output
2932
+
2933
+ A risk assessment report listing which legacy findings are relevant to the planned change,
2934
+ their intersection with the affected areas, and recommended actions.
2935
+
2936
+ ### Output template
2937
+
2938
+ \`\`\`markdown
2939
+ # Legacy Risk Assessment \u2014 <WI id>
2940
+
2941
+ ## Relevant Risks
2942
+
2943
+ ### RISK-xxx: <title>
2944
+ - **Intersection:** <how this risk relates to the planned change>
2945
+ - **Action:** mitigate before | monitor during | verify after | not applicable
2946
+ - **Notes:** <additional context>
2947
+
2948
+ ## Relevant Unknowns
2949
+
2950
+ ### UNK-xxx: <question>
2951
+ - **Impact on this WI:** <how this unknown affects implementation>
2952
+ - **Recommended:** investigate before | accept as assumption | defer
2953
+
2954
+ ## Relevant Modernization Candidates
2955
+
2956
+ ### MOD-xxx: <title>
2957
+ - **Alignment:** <how this WI relates to the modernization target>
2958
+ - **Recommendation:** advance | defer | not relevant
2959
+
2960
+ ## Summary
2961
+
2962
+ - Risks requiring pre-implementation mitigation: <count>
2963
+ - Unknowns requiring investigation: <count>
2964
+ - Modernization candidates advanced by this WI: <count>
2965
+ - Overall risk posture: low | medium | high
2966
+ \`\`\`
2967
+
2968
+ ## Rules
2969
+
2970
+ - Reference findings by their stable identifiers \u2014 do not copy full content.
2971
+ - Assess intersection based on affected areas (file paths, modules, system entities).
2972
+ - Not every legacy finding is relevant \u2014 filter to those that intersect the change.
2973
+ - Do not block implementation solely because legacy risks exist \u2014 provide context for
2974
+ informed decision-making.
2975
+ - When the System Graph is available, use entity relationships to discover indirect risk
2976
+ intersections.
2977
+
2978
+ ## Quality checklist
2979
+
2980
+ - Every referenced finding uses its stable identifier (RISK-xxx, UNK-xxx, MOD-xxx).
2981
+ - Each relevant finding has an explicit action recommendation.
2982
+ - Findings not relevant to the change are excluded, not listed as "not applicable".
2983
+ - Overall risk posture is stated.
2984
+ - The assessment is proportional \u2014 a small change gets a brief assessment.
2985
+ `
2986
+ );
2904
2987
  var SKILLS = [
2905
2988
  ADR_WRITING,
2906
2989
  WORK_ITEM_REFINEMENT,
@@ -2910,10 +2993,11 @@ var SKILLS = [
2910
2993
  LEARNING_CAPTURE,
2911
2994
  IMPLEMENTATION_PLANNING,
2912
2995
  MODULE_CONTEXT_REFINEMENT,
2913
- EVIDENCE_VERIFICATION
2996
+ EVIDENCE_VERIFICATION,
2997
+ LEGACY_RISK_ASSESSMENT
2914
2998
  ];
2915
2999
  var SKILL_GROUPS = {
2916
- delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
3000
+ delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
2917
3001
  tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
2918
3002
  integration: ["capsule-writing"]
2919
3003
  };
@@ -3678,7 +3762,11 @@ Adapt priorities to the project state from the context pack:
3678
3762
  - **new** \u2014 prioritize foundational capabilities and initial product direction.
3679
3763
  - **pre-ai** \u2014 prioritize organizing existing capabilities and reducing knowledge gaps.
3680
3764
  - **legacy** \u2014 prioritize risk reduction, unknowns and safe modernization before feature
3681
- delivery.
3765
+ delivery. **Explicitly consult** \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\`
3766
+ and \`knowledge/legacy/modernization-candidates.md\` when they exist. Every legacy risk
3767
+ (RISK-xxx) and modernization candidate (MOD-xxx) should be considered as a source signal
3768
+ for roadmap candidates. Reference them by their stable identifiers so downstream Work Items
3769
+ can trace back to the original finding.
3682
3770
 
3683
3771
  ## Grounding rules (VS-077)
3684
3772
 
@@ -3690,7 +3778,7 @@ Every candidate initiative must be **grounded** in the knowledge base \u2014 nev
3690
3778
  - **Related capabilities** \u2014 one or more existing/partial capabilities.
3691
3779
  - **Source signals** \u2014 at least one traceable reason: Capability Gap, Roadmap Candidate Signal, Risk,
3692
3780
  Open Question, Assumption, Deferred Decision, Tech Decision Candidate, ADR, Business Goal,
3693
- Operational Need or Legacy Modernization Signal.
3781
+ Operational Need, Legacy Modernization Signal, Legacy Risk (RISK-xxx) or Legacy Unknown (UNK-xxx).
3694
3782
  - **Expected value**, **Risks**, **Dependencies**, and **Suggested Work Items** (candidates only).
3695
3783
 
3696
3784
  Do **not** emit a candidate with no source signal. Keep initiatives at initiative granularity (small
@@ -3805,10 +3893,13 @@ var LEGACY_AGENT = `# Legacy Agent
3805
3893
  ## Role
3806
3894
 
3807
3895
  You are the Kaddo Legacy Agent. Your job is to analyze a legacy or risky project before
3808
- anyone changes it, using a Kaddo Context Pack.
3896
+ anyone changes it, using a Kaddo Context Pack enriched with scan signals and system
3897
+ topology.
3809
3898
 
3810
3899
  You do not write code. You surface risk, unknowns and safe first steps, marking
3811
- assumptions clearly.
3900
+ assumptions clearly. Your output feeds the downstream Kaddo lifecycle \u2014 roadmap, Work
3901
+ Items, Implementation Handoff, Evidence, Verification and Learning \u2014 so findings must be
3902
+ structured and traceable.
3812
3903
 
3813
3904
  ## When to Use
3814
3905
 
@@ -3819,26 +3910,45 @@ before planning modernization or changes.
3819
3910
 
3820
3911
  Provide \`.kaddo/context-pack.md\` as the primary input.
3821
3912
 
3822
- Optionally provide: incident history, known pain points, dependency manifests.
3913
+ Additionally consult (use whatever is available; mark missing sources as assumptions):
3914
+
3915
+ - \`.kaddo/scan.json\` \u2014 scan signals (auth, payments, webhooks, storage, background_jobs,
3916
+ email, database, migrations, api_routes, tests, security, infrastructure).
3917
+ - System Graph (\`.kaddo/graph.json\` / \`.kaddo/graph.mmd\`) \u2014 entity relationships and
3918
+ topology when available.
3919
+ - \`knowledge/tech/current-state.md\` \u2014 existing architecture baseline.
3920
+ - \`knowledge/product/capabilities.md\` \u2014 capability inventory with statuses and domains.
3921
+ - Incident history, known pain points, dependency manifests (if provided by the user).
3823
3922
 
3824
3923
  ## Expected Output
3825
3924
 
3826
- Markdown artifacts intended to be saved as:
3925
+ Three structured Markdown artifacts intended to be saved as:
3827
3926
 
3828
3927
  - \`knowledge/legacy/risks.md\`
3829
3928
  - \`knowledge/legacy/unknowns.md\`
3830
3929
  - \`knowledge/legacy/modernization-candidates.md\`
3831
3930
 
3832
- ## Instructions
3931
+ Each artifact uses Kaddo template format with front matter and structured entries that
3932
+ downstream agents (roadmap-agent, work-item-agent, implementation-agent) can reference.
3833
3933
 
3834
- Analyze the context pack and identify:
3934
+ ## Instructions
3835
3935
 
3836
- 1. Unknowns.
3837
- 2. Risky areas.
3838
- 3. Dependencies.
3839
- 4. Modernization candidates.
3840
- 5. Safe first steps.
3841
- 6. Areas requiring human validation.
3936
+ 1. **Ingest available signals.** Read scan results, context pack, system graph and any
3937
+ existing knowledge. Do not skip available sources.
3938
+ 2. **Identify risks.** For each risk, provide a stable identifier (RISK-001, RISK-002, ...),
3939
+ the affected area (file paths, modules, or system components), why it is risky, blast
3940
+ radius (local / module / cross-cutting / system-wide), confidence (high / medium / low),
3941
+ related scan signals, and a mitigation suggestion.
3942
+ 3. **Identify unknowns.** For each unknown, provide a stable identifier (UNK-001, UNK-002, ...),
3943
+ the question, why it matters, how to find out, and related risks (RISK-xxx references).
3944
+ 4. **Identify modernization candidates.** For each candidate, provide a stable identifier
3945
+ (MOD-001, MOD-002, ...), current state, target state, value, risk, suggested Knowledge
3946
+ Level (K1\u2013K4), related risks and unknowns, and affected system entities when the Graph
3947
+ is available.
3948
+ 5. **Identify dependencies** \u2014 external and internal dependencies that constrain changes.
3949
+ 6. **Propose safe first steps** \u2014 small, low-risk actions that reduce unknowns or risk.
3950
+ 7. **Flag areas requiring human validation** \u2014 decisions, assumptions or trade-offs that
3951
+ only a human can resolve.
3842
3952
 
3843
3953
  ## Constraints
3844
3954
 
@@ -3846,33 +3956,78 @@ Analyze the context pack and identify:
3846
3956
  - Prefer small, low-risk first steps.
3847
3957
  - Mark assumptions and confidence clearly.
3848
3958
  - Do not write code.
3959
+ - Every risk, unknown and modernization candidate must have a stable identifier (RISK-xxx,
3960
+ UNK-xxx, MOD-xxx) so downstream artifacts can reference them.
3961
+ - When System Graph topology is available, reference affected entities by their graph id.
3962
+ - Do not duplicate capability inventory work \u2014 reference \`capabilities.md\` when it exists.
3849
3963
 
3850
3964
  ## Output Format
3851
3965
 
3966
+ ### knowledge/legacy/risks.md
3967
+
3852
3968
  \`\`\`markdown
3853
- # Legacy Analysis
3969
+ ---
3970
+ type: legacy-risks
3971
+ generated_by: legacy-agent
3972
+ ---
3854
3973
 
3855
- Generated from Kaddo Context Pack.
3974
+ # Legacy Risks
3856
3975
 
3857
- ## Risks
3976
+ ## RISK-001: <Short title>
3858
3977
 
3859
- ### <Risk>
3978
+ - **Area:** <file paths, modules, or components>
3979
+ - **Why risky:** <explanation>
3980
+ - **Blast radius:** local | module | cross-cutting | system-wide
3981
+ - **Confidence:** high | medium | low
3982
+ - **Scan signals:** <related signals from scan.json, or "none detected">
3983
+ - **Graph entities:** <related system graph entities, or "Graph unavailable">
3984
+ - **Mitigation:** <suggested approach>
3860
3985
 
3861
- **Area:**
3986
+ ## RISK-002: ...
3987
+ \`\`\`
3862
3988
 
3863
- **Why it is risky:**
3989
+ ### knowledge/legacy/unknowns.md
3864
3990
 
3865
- **Confidence:**
3991
+ \`\`\`markdown
3992
+ ---
3993
+ type: legacy-unknowns
3994
+ generated_by: legacy-agent
3995
+ ---
3866
3996
 
3867
- ## Unknowns
3997
+ # Legacy Unknowns
3868
3998
 
3869
- ## Dependencies
3999
+ ## UNK-001: <Question>
3870
4000
 
3871
- ## Modernization Candidates
4001
+ - **Why it matters:** <impact if left unresolved>
4002
+ - **How to find out:** <investigation steps>
4003
+ - **Related risks:** RISK-001, RISK-003
4004
+ - **Blocking:** yes | no | unknown
3872
4005
 
3873
- ## Safe First Steps
4006
+ ## UNK-002: ...
4007
+ \`\`\`
3874
4008
 
3875
- ## Areas Requiring Human Validation
4009
+ ### knowledge/legacy/modernization-candidates.md
4010
+
4011
+ \`\`\`markdown
4012
+ ---
4013
+ type: modernization-candidates
4014
+ generated_by: legacy-agent
4015
+ ---
4016
+
4017
+ # Modernization Candidates
4018
+
4019
+ ## MOD-001: <Short title>
4020
+
4021
+ - **Current state:** <what exists today>
4022
+ - **Target state:** <desired outcome>
4023
+ - **Value:** <why this modernization matters>
4024
+ - **Risk:** low | medium | high
4025
+ - **Suggested Knowledge Level:** K1 | K2 | K3 | K4
4026
+ - **Related risks:** RISK-xxx
4027
+ - **Related unknowns:** UNK-xxx
4028
+ - **Affected entities:** <system graph entities, or "Graph unavailable">
4029
+
4030
+ ## MOD-002: ...
3876
4031
  \`\`\`
3877
4032
 
3878
4033
  ## Where to Save the Result
@@ -3883,10 +4038,15 @@ Save risks as \`knowledge/legacy/risks.md\`, unknowns as
3883
4038
 
3884
4039
  ## Quality Checklist
3885
4040
 
3886
- - Risks are backed by evidence.
4041
+ - Every risk has a stable RISK-xxx identifier, blast radius, and confidence level.
4042
+ - Every unknown has a stable UNK-xxx identifier and related risk references.
4043
+ - Every modernization candidate has a stable MOD-xxx identifier and Knowledge Level.
4044
+ - Scan signals are referenced when available \u2014 findings are grounded in detected signals.
4045
+ - System Graph entities are referenced when topology is available.
3887
4046
  - Safe first steps are small and low-risk.
3888
- - Unknowns are explicit.
4047
+ - Assumptions are marked explicitly with confidence.
3889
4048
  - Areas needing human validation are flagged.
4049
+ - Identifiers are unique and sequential within each artifact.
3890
4050
  `;
3891
4051
  var ADR_AGENT = `# ADR Agent
3892
4052
 
@@ -4108,6 +4268,14 @@ the decision is still a candidate in knowledge/tech/decision-candidates.md with
4108
4268
  that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and record
4109
4269
  \`decision_candidates: [<title>]\` \u2014 do not implement work that depends on an unformalized decision
4110
4270
  without surfacing it. -->
4271
+
4272
+ **Related legacy findings:** <!-- for legacy projects (WI-012): when
4273
+ \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\` or
4274
+ \`knowledge/legacy/modernization-candidates.md\` exist, check whether any findings (RISK-xxx,
4275
+ UNK-xxx, MOD-xxx) are relevant to this Work Item's scope. Add \`legacy_risks: [RISK-001, ...]\`
4276
+ and \`legacy_unknowns: [UNK-001, ...]\` to the front matter when applicable. Do NOT copy the full
4277
+ finding content \u2014 reference by identifier. Include relevant findings in the Scope unknowns
4278
+ section when they affect implementation decisions. -->
4111
4279
  \`\`\`
4112
4280
 
4113
4281
  ### Preserve roadmap metadata (VS-077 / VS-078)
@@ -7696,6 +7864,57 @@ function recordGuardRun(dir, input, now = /* @__PURE__ */ new Date()) {
7696
7864
  return { run, runsPath: RUNS_PATH, summaryPath: SUMMARY_PATH };
7697
7865
  }
7698
7866
 
7867
+ // src/core/legacy-guard.ts
7868
+ import { minimatch as minimatch2 } from "minimatch";
7869
+ var RISKS_PATH = "knowledge/legacy/risks.md";
7870
+ function parseRisks(content) {
7871
+ const risks = [];
7872
+ const sections = content.split(/^## /gm).slice(1);
7873
+ for (const section3 of sections) {
7874
+ const headerMatch = section3.match(/^(RISK-\d+):\s*(.+)$/m);
7875
+ if (!headerMatch) continue;
7876
+ const id = headerMatch[1];
7877
+ const title = headerMatch[2].trim();
7878
+ const areaMatch = section3.match(/\*\*Area:\*\*\s*(.+)/i);
7879
+ const blastMatch = section3.match(/\*\*Blast radius:\*\*\s*(\w+)/i);
7880
+ const confMatch = section3.match(/\*\*Confidence:\*\*\s*(\w+)/i);
7881
+ const area = areaMatch?.[1]?.trim() ?? "";
7882
+ const blastRadius = blastMatch?.[1]?.trim() ?? "unknown";
7883
+ const confidence = confMatch?.[1]?.trim() ?? "unknown";
7884
+ const areaPatterns = area.split(/[,;]/).map((p2) => p2.trim()).filter((p2) => p2.length > 0).flatMap((p2) => {
7885
+ if (p2.includes("*")) return [p2];
7886
+ if (p2.includes("/")) return [`${p2}/**`, `${p2}*`];
7887
+ return [`**/${p2}/**`, `**/${p2}*`, `**/*${p2}*`];
7888
+ });
7889
+ risks.push({ id, title, area, blastRadius, confidence, areaPatterns });
7890
+ }
7891
+ return risks;
7892
+ }
7893
+ function analyzeLegacyRiskIntersections(dir, touchedFiles) {
7894
+ const risksPath = join(dir, RISKS_PATH);
7895
+ if (!exists(risksPath) || touchedFiles.length === 0) return [];
7896
+ const content = readFile(risksPath);
7897
+ const risks = parseRisks(content);
7898
+ const intersections = [];
7899
+ for (const risk of risks) {
7900
+ if (risk.areaPatterns.length === 0) continue;
7901
+ const matched = touchedFiles.filter(
7902
+ (f) => risk.areaPatterns.some((pattern) => minimatch2(f, pattern, { dot: true }))
7903
+ );
7904
+ if (matched.length > 0) {
7905
+ intersections.push({
7906
+ riskId: risk.id,
7907
+ title: risk.title,
7908
+ area: risk.area,
7909
+ blastRadius: risk.blastRadius,
7910
+ confidence: risk.confidence,
7911
+ matchedFiles: matched
7912
+ });
7913
+ }
7914
+ }
7915
+ return intersections;
7916
+ }
7917
+
7699
7918
  // src/commands/guard.ts
7700
7919
  var ARCH_DIR3 = "knowledge";
7701
7920
  var CONFIG_PATH2 = ".kaddo/config.yml";
@@ -7986,6 +8205,22 @@ async function runGuard(opts = {}) {
7986
8205
  }
7987
8206
  console.log("");
7988
8207
  }
8208
+ const legacyIntersections = analyzeLegacyRiskIntersections(dir, touchedFiles);
8209
+ if (legacyIntersections.length > 0) {
8210
+ console.log("Legacy risk context:");
8211
+ for (const li of legacyIntersections) {
8212
+ console.log(` \u26A0 ${li.riskId}: ${li.title}`);
8213
+ console.log(` Blast radius: ${li.blastRadius} \xB7 Confidence: ${li.confidence}`);
8214
+ console.log(` Touched files in risk area:`);
8215
+ for (const f of li.matchedFiles.slice(0, 5)) console.log(` - ${f}`);
8216
+ if (li.matchedFiles.length > 5) console.log(` \u2026and ${li.matchedFiles.length - 5} more`);
8217
+ }
8218
+ console.log("");
8219
+ console.log(" These files intersect known legacy risks. Consider consulting");
8220
+ console.log(" `knowledge/legacy/risks.md` and the legacy-risk-assessment skill");
8221
+ console.log(" before completing this change.");
8222
+ console.log("");
8223
+ }
7989
8224
  const registeredModuleIds = loadMappedModules(dir).map((m) => m.id);
7990
8225
  const modifiedRepoIds = workspaceScan ? [...new Set(workspaceScan.changedFiles.map((c) => c.repoId))] : [];
7991
8226
  const wiArtifacts = artifacts.filter((a) => a.isWorkItem && a.affectedModules.length > 0);
@@ -20907,6 +21142,14 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
20907
21142
  return node;
20908
21143
  }
20909
21144
 
21145
+ // src/core/legacy-knowledge.ts
21146
+ var RISKS_PATH2 = "knowledge/legacy/risks.md";
21147
+ var UNKNOWNS_PATH = "knowledge/legacy/unknowns.md";
21148
+ var CANDIDATES_PATH = "knowledge/legacy/modernization-candidates.md";
21149
+ function hasLegacyKnowledge(dir) {
21150
+ return exists(join(dir, RISKS_PATH2)) || exists(join(dir, UNKNOWNS_PATH)) || exists(join(dir, CANDIDATES_PATH));
21151
+ }
21152
+
20910
21153
  // src/core/work-item-refinement.ts
20911
21154
  var RECOMMENDED_AGENT = "work-item-agent";
20912
21155
  var RECOMMENDED_SKILL = "work-item-refinement";
@@ -20955,6 +21198,19 @@ function buildRefinementHandoff(dir, workItemId) {
20955
21198
  "repository, Knowledge and mapped modules \u2014 the Graph is enrichment, not a prerequisite."
20956
21199
  );
20957
21200
  }
21201
+ if (hasLegacyKnowledge(dir)) {
21202
+ lines.push(
21203
+ "",
21204
+ "This is a legacy project with existing legacy analysis. When refining, consult:",
21205
+ "- `knowledge/legacy/risks.md` \u2014 known risks (RISK-xxx identifiers).",
21206
+ "- `knowledge/legacy/unknowns.md` \u2014 known unknowns (UNK-xxx identifiers).",
21207
+ "- `knowledge/legacy/modernization-candidates.md` \u2014 modernization candidates (MOD-xxx identifiers).",
21208
+ "",
21209
+ "Reference only the findings relevant to this Work Item's scope \u2014 do not copy all legacy",
21210
+ "knowledge into the Work Item. Add `legacy_risks` and `legacy_unknowns` to the front matter",
21211
+ "when applicable, using the stable identifiers (e.g. `legacy_risks: [RISK-001, RISK-003]`)."
21212
+ );
21213
+ }
20958
21214
  lines.push(
20959
21215
  "",
20960
21216
  `Update the canonical Work Item ${wi.id} with:`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.97.0",
3
+ "version": "3.99.0",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {