@kaddo/mcp 3.97.0 → 3.99.0

package/dist/index.js

@@ -5107,6 +5107,89 @@ actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED |
 Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
 `
 );
+var LEGACY_RISK_ASSESSMENT = skill(
+  "legacy-risk-assessment",
+  "Legacy Risk Assessment Skill",
+  "delivery",
+  ["legacy-agent", "implementation-agent", "work-item-agent"],
+  `
+# Legacy Risk Assessment Skill
+
+## Purpose
+
+Evaluate a planned change against known legacy risks, unknowns and modernization candidates
+to identify which findings require additional consideration before or after implementation.
+
+## When to use
+
+Before or during implementation of a Work Item in a legacy project \u2014 especially when the
+Work Item touches areas flagged in \`knowledge/legacy/risks.md\`.
+
+## Inputs
+
+- The Work Item (id, ACs, affected_modules, affected areas).
+- \`knowledge/legacy/risks.md\` \u2014 known risks with RISK-xxx identifiers.
+- \`knowledge/legacy/unknowns.md\` \u2014 known unknowns with UNK-xxx identifiers.
+- \`knowledge/legacy/modernization-candidates.md\` \u2014 MOD-xxx candidates.
+- System Graph (\`.kaddo/graph.json\`) when available.
+- Implementation Handoff or Implementation Evidence when available.
+
+## Output
+
+A risk assessment report listing which legacy findings are relevant to the planned change,
+their intersection with the affected areas, and recommended actions.
+
+### Output template
+
+\`\`\`markdown
+# Legacy Risk Assessment \u2014 <WI id>
+
+## Relevant Risks
+
+### RISK-xxx: <title>
+- **Intersection:** <how this risk relates to the planned change>
+- **Action:** mitigate before | monitor during | verify after | not applicable
+- **Notes:** <additional context>
+
+## Relevant Unknowns
+
+### UNK-xxx: <question>
+- **Impact on this WI:** <how this unknown affects implementation>
+- **Recommended:** investigate before | accept as assumption | defer
+
+## Relevant Modernization Candidates
+
+### MOD-xxx: <title>
+- **Alignment:** <how this WI relates to the modernization target>
+- **Recommendation:** advance | defer | not relevant
+
+## Summary
+
+- Risks requiring pre-implementation mitigation: <count>
+- Unknowns requiring investigation: <count>
+- Modernization candidates advanced by this WI: <count>
+- Overall risk posture: low | medium | high
+\`\`\`
+
+## Rules
+
+- Reference findings by their stable identifiers \u2014 do not copy full content.
+- Assess intersection based on affected areas (file paths, modules, system entities).
+- Not every legacy finding is relevant \u2014 filter to those that intersect the change.
+- Do not block implementation solely because legacy risks exist \u2014 provide context for
+  informed decision-making.
+- When the System Graph is available, use entity relationships to discover indirect risk
+  intersections.
+
+## Quality checklist
+
+- Every referenced finding uses its stable identifier (RISK-xxx, UNK-xxx, MOD-xxx).
+- Each relevant finding has an explicit action recommendation.
+- Findings not relevant to the change are excluded, not listed as "not applicable".
+- Overall risk posture is stated.
+- The assessment is proportional \u2014 a small change gets a brief assessment.
+`
+);
 var SKILLS = [
   ADR_WRITING,
   WORK_ITEM_REFINEMENT,
@@ -5116,10 +5199,11 @@ var SKILLS = [
   LEARNING_CAPTURE,
   IMPLEMENTATION_PLANNING,
   MODULE_CONTEXT_REFINEMENT,
-  EVIDENCE_VERIFICATION
+  EVIDENCE_VERIFICATION,
+  LEGACY_RISK_ASSESSMENT
 ];
 var SKILL_GROUPS = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -5868,7 +5952,11 @@ Adapt priorities to the project state from the context pack:
 - **new** \u2014 prioritize foundational capabilities and initial product direction.
 - **pre-ai** \u2014 prioritize organizing existing capabilities and reducing knowledge gaps.
 - **legacy** \u2014 prioritize risk reduction, unknowns and safe modernization before feature
-  delivery.
+  delivery. **Explicitly consult** \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\`
+  and \`knowledge/legacy/modernization-candidates.md\` when they exist. Every legacy risk
+  (RISK-xxx) and modernization candidate (MOD-xxx) should be considered as a source signal
+  for roadmap candidates. Reference them by their stable identifiers so downstream Work Items
+  can trace back to the original finding.
 
 ## Grounding rules (VS-077)
 
@@ -5880,7 +5968,7 @@ Every candidate initiative must be **grounded** in the knowledge base \u2014 nev
 - **Related capabilities** \u2014 one or more existing/partial capabilities.
 - **Source signals** \u2014 at least one traceable reason: Capability Gap, Roadmap Candidate Signal, Risk,
   Open Question, Assumption, Deferred Decision, Tech Decision Candidate, ADR, Business Goal,
-  Operational Need or Legacy Modernization Signal.
+  Operational Need, Legacy Modernization Signal, Legacy Risk (RISK-xxx) or Legacy Unknown (UNK-xxx).
 - **Expected value**, **Risks**, **Dependencies**, and **Suggested Work Items** (candidates only).
 
 Do **not** emit a candidate with no source signal. Keep initiatives at initiative granularity (small
@@ -5995,10 +6083,13 @@ var LEGACY_AGENT = `# Legacy Agent
 ## Role
 
 You are the Kaddo Legacy Agent. Your job is to analyze a legacy or risky project before
-anyone changes it, using a Kaddo Context Pack.
+anyone changes it, using a Kaddo Context Pack enriched with scan signals and system
+topology.
 
 You do not write code. You surface risk, unknowns and safe first steps, marking
-assumptions clearly.
+assumptions clearly. Your output feeds the downstream Kaddo lifecycle \u2014 roadmap, Work
+Items, Implementation Handoff, Evidence, Verification and Learning \u2014 so findings must be
+structured and traceable.
 
 ## When to Use
 
@@ -6009,26 +6100,45 @@ before planning modernization or changes.
 
 Provide \`.kaddo/context-pack.md\` as the primary input.
 
-Optionally provide: incident history, known pain points, dependency manifests.
+Additionally consult (use whatever is available; mark missing sources as assumptions):
+
+- \`.kaddo/scan.json\` \u2014 scan signals (auth, payments, webhooks, storage, background_jobs,
+  email, database, migrations, api_routes, tests, security, infrastructure).
+- System Graph (\`.kaddo/graph.json\` / \`.kaddo/graph.mmd\`) \u2014 entity relationships and
+  topology when available.
+- \`knowledge/tech/current-state.md\` \u2014 existing architecture baseline.
+- \`knowledge/product/capabilities.md\` \u2014 capability inventory with statuses and domains.
+- Incident history, known pain points, dependency manifests (if provided by the user).
 
 ## Expected Output
 
-Markdown artifacts intended to be saved as:
+Three structured Markdown artifacts intended to be saved as:
 
 - \`knowledge/legacy/risks.md\`
 - \`knowledge/legacy/unknowns.md\`
 - \`knowledge/legacy/modernization-candidates.md\`
 
-## Instructions
+Each artifact uses Kaddo template format with front matter and structured entries that
+downstream agents (roadmap-agent, work-item-agent, implementation-agent) can reference.
 
-Analyze the context pack and identify:
+## Instructions
 
-1. Unknowns.
-2. Risky areas.
-3. Dependencies.
-4. Modernization candidates.
-5. Safe first steps.
-6. Areas requiring human validation.
+1. **Ingest available signals.** Read scan results, context pack, system graph and any
+   existing knowledge. Do not skip available sources.
+2. **Identify risks.** For each risk, provide a stable identifier (RISK-001, RISK-002, ...),
+   the affected area (file paths, modules, or system components), why it is risky, blast
+   radius (local / module / cross-cutting / system-wide), confidence (high / medium / low),
+   related scan signals, and a mitigation suggestion.
+3. **Identify unknowns.** For each unknown, provide a stable identifier (UNK-001, UNK-002, ...),
+   the question, why it matters, how to find out, and related risks (RISK-xxx references).
+4. **Identify modernization candidates.** For each candidate, provide a stable identifier
+   (MOD-001, MOD-002, ...), current state, target state, value, risk, suggested Knowledge
+   Level (K1\u2013K4), related risks and unknowns, and affected system entities when the Graph
+   is available.
+5. **Identify dependencies** \u2014 external and internal dependencies that constrain changes.
+6. **Propose safe first steps** \u2014 small, low-risk actions that reduce unknowns or risk.
+7. **Flag areas requiring human validation** \u2014 decisions, assumptions or trade-offs that
+   only a human can resolve.
 
 ## Constraints
 
@@ -6036,33 +6146,78 @@ Analyze the context pack and identify:
 - Prefer small, low-risk first steps.
 - Mark assumptions and confidence clearly.
 - Do not write code.
+- Every risk, unknown and modernization candidate must have a stable identifier (RISK-xxx,
+  UNK-xxx, MOD-xxx) so downstream artifacts can reference them.
+- When System Graph topology is available, reference affected entities by their graph id.
+- Do not duplicate capability inventory work \u2014 reference \`capabilities.md\` when it exists.
 
 ## Output Format
 
+### knowledge/legacy/risks.md
+
 \`\`\`markdown
-# Legacy Analysis
+---
+type: legacy-risks
+generated_by: legacy-agent
+---
 
-Generated from Kaddo Context Pack.
+# Legacy Risks
 
-## Risks
+## RISK-001: <Short title>
 
-### <Risk>
+- **Area:** <file paths, modules, or components>
+- **Why risky:** <explanation>
+- **Blast radius:** local | module | cross-cutting | system-wide
+- **Confidence:** high | medium | low
+- **Scan signals:** <related signals from scan.json, or "none detected">
+- **Graph entities:** <related system graph entities, or "Graph unavailable">
+- **Mitigation:** <suggested approach>
 
-**Area:**
+## RISK-002: ...
+\`\`\`
 
-**Why it is risky:**
+### knowledge/legacy/unknowns.md
 
-**Confidence:**
+\`\`\`markdown
+---
+type: legacy-unknowns
+generated_by: legacy-agent
+---
 
-## Unknowns
+# Legacy Unknowns
 
-## Dependencies
+## UNK-001: <Question>
+
+- **Why it matters:** <impact if left unresolved>
+- **How to find out:** <investigation steps>
+- **Related risks:** RISK-001, RISK-003
+- **Blocking:** yes | no | unknown
 
-## Modernization Candidates
+## UNK-002: ...
+\`\`\`
 
-## Safe First Steps
+### knowledge/legacy/modernization-candidates.md
 
-## Areas Requiring Human Validation
+\`\`\`markdown
+---
+type: modernization-candidates
+generated_by: legacy-agent
+---
+
+# Modernization Candidates
+
+## MOD-001: <Short title>
+
+- **Current state:** <what exists today>
+- **Target state:** <desired outcome>
+- **Value:** <why this modernization matters>
+- **Risk:** low | medium | high
+- **Suggested Knowledge Level:** K1 | K2 | K3 | K4
+- **Related risks:** RISK-xxx
+- **Related unknowns:** UNK-xxx
+- **Affected entities:** <system graph entities, or "Graph unavailable">
+
+## MOD-002: ...
 \`\`\`
 
 ## Where to Save the Result
@@ -6073,10 +6228,15 @@ Save risks as \`knowledge/legacy/risks.md\`, unknowns as
 
 ## Quality Checklist
 
-- Risks are backed by evidence.
+- Every risk has a stable RISK-xxx identifier, blast radius, and confidence level.
+- Every unknown has a stable UNK-xxx identifier and related risk references.
+- Every modernization candidate has a stable MOD-xxx identifier and Knowledge Level.
+- Scan signals are referenced when available \u2014 findings are grounded in detected signals.
+- System Graph entities are referenced when topology is available.
 - Safe first steps are small and low-risk.
-- Unknowns are explicit.
+- Assumptions are marked explicitly with confidence.
 - Areas needing human validation are flagged.
+- Identifiers are unique and sequential within each artifact.
 `;
 var ADR_AGENT = `# ADR Agent
 
@@ -6298,6 +6458,14 @@ the decision is still a candidate in knowledge/tech/decision-candidates.md with
 that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and record
 \`decision_candidates: [<title>]\` \u2014 do not implement work that depends on an unformalized decision
 without surfacing it. -->
+
+**Related legacy findings:** <!-- for legacy projects (WI-012): when
+\`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\` or
+\`knowledge/legacy/modernization-candidates.md\` exist, check whether any findings (RISK-xxx,
+UNK-xxx, MOD-xxx) are relevant to this Work Item's scope. Add \`legacy_risks: [RISK-001, ...]\`
+and \`legacy_unknowns: [UNK-001, ...]\` to the front matter when applicable. Do NOT copy the full
+finding content \u2014 reference by identifier. Include relevant findings in the Scope unknowns
+section when they affect implementation decisions. -->
 \`\`\`
 
 ### Preserve roadmap metadata (VS-077 / VS-078)
@@ -10519,6 +10687,42 @@ var RESOURCES = [
       return [{ uri: "kaddo://project-route", text: JSON.stringify(buildProjectRoute(root), null, 2), mimeType: "application/json" }];
     }
   },
+  {
+    uri: "kaddo://legacy-risks",
+    name: "Kaddo legacy risks",
+    description: "Known legacy risks (RISK-xxx) from `knowledge/legacy/risks.md` \u2014 blast radius, confidence, mitigation (WI-012). Read-only.",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://legacy-risks",
+      "knowledge/legacy/risks.md",
+      "No legacy risks found. Run the `legacy-agent` in a legacy project to generate `knowledge/legacy/risks.md`."
+    )
+  },
+  {
+    uri: "kaddo://legacy-unknowns",
+    name: "Kaddo legacy unknowns",
+    description: "Known legacy unknowns (UNK-xxx) from `knowledge/legacy/unknowns.md` \u2014 open questions about legacy system behavior (WI-012). Read-only.",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://legacy-unknowns",
+      "knowledge/legacy/unknowns.md",
+      "No legacy unknowns found. Run the `legacy-agent` in a legacy project to generate `knowledge/legacy/unknowns.md`."
+    )
+  },
+  {
+    uri: "kaddo://modernization-candidates",
+    name: "Kaddo modernization candidates",
+    description: "Modernization candidates (MOD-xxx) from `knowledge/legacy/modernization-candidates.md` \u2014 current state, target state, risk, Knowledge Level (WI-012). Read-only.",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://modernization-candidates",
+      "knowledge/legacy/modernization-candidates.md",
+      "No modernization candidates found. Run the `legacy-agent` in a legacy project to generate `knowledge/legacy/modernization-candidates.md`."
+    )
+  },
   {
     uri: "kaddo://scan-signals",
     name: "Kaddo scan signals",
@@ -13106,6 +13310,89 @@ actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED |
 Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
 `
 );
+var LEGACY_RISK_ASSESSMENT2 = skill2(
+  "legacy-risk-assessment",
+  "Legacy Risk Assessment Skill",
+  "delivery",
+  ["legacy-agent", "implementation-agent", "work-item-agent"],
+  `
+# Legacy Risk Assessment Skill
+
+## Purpose
+
+Evaluate a planned change against known legacy risks, unknowns and modernization candidates
+to identify which findings require additional consideration before or after implementation.
+
+## When to use
+
+Before or during implementation of a Work Item in a legacy project \u2014 especially when the
+Work Item touches areas flagged in \`knowledge/legacy/risks.md\`.
+
+## Inputs
+
+- The Work Item (id, ACs, affected_modules, affected areas).
+- \`knowledge/legacy/risks.md\` \u2014 known risks with RISK-xxx identifiers.
+- \`knowledge/legacy/unknowns.md\` \u2014 known unknowns with UNK-xxx identifiers.
+- \`knowledge/legacy/modernization-candidates.md\` \u2014 MOD-xxx candidates.
+- System Graph (\`.kaddo/graph.json\`) when available.
+- Implementation Handoff or Implementation Evidence when available.
+
+## Output
+
+A risk assessment report listing which legacy findings are relevant to the planned change,
+their intersection with the affected areas, and recommended actions.
+
+### Output template
+
+\`\`\`markdown
+# Legacy Risk Assessment \u2014 <WI id>
+
+## Relevant Risks
+
+### RISK-xxx: <title>
+- **Intersection:** <how this risk relates to the planned change>
+- **Action:** mitigate before | monitor during | verify after | not applicable
+- **Notes:** <additional context>
+
+## Relevant Unknowns
+
+### UNK-xxx: <question>
+- **Impact on this WI:** <how this unknown affects implementation>
+- **Recommended:** investigate before | accept as assumption | defer
+
+## Relevant Modernization Candidates
+
+### MOD-xxx: <title>
+- **Alignment:** <how this WI relates to the modernization target>
+- **Recommendation:** advance | defer | not relevant
+
+## Summary
+
+- Risks requiring pre-implementation mitigation: <count>
+- Unknowns requiring investigation: <count>
+- Modernization candidates advanced by this WI: <count>
+- Overall risk posture: low | medium | high
+\`\`\`
+
+## Rules
+
+- Reference findings by their stable identifiers \u2014 do not copy full content.
+- Assess intersection based on affected areas (file paths, modules, system entities).
+- Not every legacy finding is relevant \u2014 filter to those that intersect the change.
+- Do not block implementation solely because legacy risks exist \u2014 provide context for
+  informed decision-making.
+- When the System Graph is available, use entity relationships to discover indirect risk
+  intersections.
+
+## Quality checklist
+
+- Every referenced finding uses its stable identifier (RISK-xxx, UNK-xxx, MOD-xxx).
+- Each relevant finding has an explicit action recommendation.
+- Findings not relevant to the change are excluded, not listed as "not applicable".
+- Overall risk posture is stated.
+- The assessment is proportional \u2014 a small change gets a brief assessment.
+`
+);
 var SKILLS2 = [
   ADR_WRITING2,
   WORK_ITEM_REFINEMENT2,
@@ -13115,10 +13402,11 @@ var SKILLS2 = [
   LEARNING_CAPTURE2,
   IMPLEMENTATION_PLANNING2,
   MODULE_CONTEXT_REFINEMENT2,
-  EVIDENCE_VERIFICATION2
+  EVIDENCE_VERIFICATION2,
+  LEGACY_RISK_ASSESSMENT2
 ];
 var SKILL_GROUPS2 = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification", "legacy-risk-assessment"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -13860,7 +14148,11 @@ Adapt priorities to the project state from the context pack:
 - **new** \u2014 prioritize foundational capabilities and initial product direction.
 - **pre-ai** \u2014 prioritize organizing existing capabilities and reducing knowledge gaps.
 - **legacy** \u2014 prioritize risk reduction, unknowns and safe modernization before feature
-  delivery.
+  delivery. **Explicitly consult** \`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\`
+  and \`knowledge/legacy/modernization-candidates.md\` when they exist. Every legacy risk
+  (RISK-xxx) and modernization candidate (MOD-xxx) should be considered as a source signal
+  for roadmap candidates. Reference them by their stable identifiers so downstream Work Items
+  can trace back to the original finding.
 
 ## Grounding rules (VS-077)
 
@@ -13872,7 +14164,7 @@ Every candidate initiative must be **grounded** in the knowledge base \u2014 nev
 - **Related capabilities** \u2014 one or more existing/partial capabilities.
 - **Source signals** \u2014 at least one traceable reason: Capability Gap, Roadmap Candidate Signal, Risk,
   Open Question, Assumption, Deferred Decision, Tech Decision Candidate, ADR, Business Goal,
-  Operational Need or Legacy Modernization Signal.
+  Operational Need, Legacy Modernization Signal, Legacy Risk (RISK-xxx) or Legacy Unknown (UNK-xxx).
 - **Expected value**, **Risks**, **Dependencies**, and **Suggested Work Items** (candidates only).
 
 Do **not** emit a candidate with no source signal. Keep initiatives at initiative granularity (small
@@ -13987,10 +14279,13 @@ var LEGACY_AGENT2 = `# Legacy Agent
 ## Role
 
 You are the Kaddo Legacy Agent. Your job is to analyze a legacy or risky project before
-anyone changes it, using a Kaddo Context Pack.
+anyone changes it, using a Kaddo Context Pack enriched with scan signals and system
+topology.
 
 You do not write code. You surface risk, unknowns and safe first steps, marking
-assumptions clearly.
+assumptions clearly. Your output feeds the downstream Kaddo lifecycle \u2014 roadmap, Work
+Items, Implementation Handoff, Evidence, Verification and Learning \u2014 so findings must be
+structured and traceable.
 
 ## When to Use
 
@@ -14001,26 +14296,45 @@ before planning modernization or changes.
 
 Provide \`.kaddo/context-pack.md\` as the primary input.
 
-Optionally provide: incident history, known pain points, dependency manifests.
+Additionally consult (use whatever is available; mark missing sources as assumptions):
+
+- \`.kaddo/scan.json\` \u2014 scan signals (auth, payments, webhooks, storage, background_jobs,
+  email, database, migrations, api_routes, tests, security, infrastructure).
+- System Graph (\`.kaddo/graph.json\` / \`.kaddo/graph.mmd\`) \u2014 entity relationships and
+  topology when available.
+- \`knowledge/tech/current-state.md\` \u2014 existing architecture baseline.
+- \`knowledge/product/capabilities.md\` \u2014 capability inventory with statuses and domains.
+- Incident history, known pain points, dependency manifests (if provided by the user).
 
 ## Expected Output
 
-Markdown artifacts intended to be saved as:
+Three structured Markdown artifacts intended to be saved as:
 
 - \`knowledge/legacy/risks.md\`
 - \`knowledge/legacy/unknowns.md\`
 - \`knowledge/legacy/modernization-candidates.md\`
 
-## Instructions
+Each artifact uses Kaddo template format with front matter and structured entries that
+downstream agents (roadmap-agent, work-item-agent, implementation-agent) can reference.
 
-Analyze the context pack and identify:
+## Instructions
 
-1. Unknowns.
-2. Risky areas.
-3. Dependencies.
-4. Modernization candidates.
-5. Safe first steps.
-6. Areas requiring human validation.
+1. **Ingest available signals.** Read scan results, context pack, system graph and any
+   existing knowledge. Do not skip available sources.
+2. **Identify risks.** For each risk, provide a stable identifier (RISK-001, RISK-002, ...),
+   the affected area (file paths, modules, or system components), why it is risky, blast
+   radius (local / module / cross-cutting / system-wide), confidence (high / medium / low),
+   related scan signals, and a mitigation suggestion.
+3. **Identify unknowns.** For each unknown, provide a stable identifier (UNK-001, UNK-002, ...),
+   the question, why it matters, how to find out, and related risks (RISK-xxx references).
+4. **Identify modernization candidates.** For each candidate, provide a stable identifier
+   (MOD-001, MOD-002, ...), current state, target state, value, risk, suggested Knowledge
+   Level (K1\u2013K4), related risks and unknowns, and affected system entities when the Graph
+   is available.
+5. **Identify dependencies** \u2014 external and internal dependencies that constrain changes.
+6. **Propose safe first steps** \u2014 small, low-risk actions that reduce unknowns or risk.
+7. **Flag areas requiring human validation** \u2014 decisions, assumptions or trade-offs that
+   only a human can resolve.
 
 ## Constraints
 
@@ -14028,33 +14342,78 @@ Analyze the context pack and identify:
 - Prefer small, low-risk first steps.
 - Mark assumptions and confidence clearly.
 - Do not write code.
+- Every risk, unknown and modernization candidate must have a stable identifier (RISK-xxx,
+  UNK-xxx, MOD-xxx) so downstream artifacts can reference them.
+- When System Graph topology is available, reference affected entities by their graph id.
+- Do not duplicate capability inventory work \u2014 reference \`capabilities.md\` when it exists.
 
 ## Output Format
 
+### knowledge/legacy/risks.md
+
 \`\`\`markdown
-# Legacy Analysis
+---
+type: legacy-risks
+generated_by: legacy-agent
+---
 
-Generated from Kaddo Context Pack.
+# Legacy Risks
 
-## Risks
+## RISK-001: <Short title>
 
-### <Risk>
+- **Area:** <file paths, modules, or components>
+- **Why risky:** <explanation>
+- **Blast radius:** local | module | cross-cutting | system-wide
+- **Confidence:** high | medium | low
+- **Scan signals:** <related signals from scan.json, or "none detected">
+- **Graph entities:** <related system graph entities, or "Graph unavailable">
+- **Mitigation:** <suggested approach>
 
-**Area:**
+## RISK-002: ...
+\`\`\`
 
-**Why it is risky:**
+### knowledge/legacy/unknowns.md
 
-**Confidence:**
+\`\`\`markdown
+---
+type: legacy-unknowns
+generated_by: legacy-agent
+---
 
-## Unknowns
+# Legacy Unknowns
 
-## Dependencies
+## UNK-001: <Question>
 
-## Modernization Candidates
+- **Why it matters:** <impact if left unresolved>
+- **How to find out:** <investigation steps>
+- **Related risks:** RISK-001, RISK-003
+- **Blocking:** yes | no | unknown
 
-## Safe First Steps
+## UNK-002: ...
+\`\`\`
 
-## Areas Requiring Human Validation
+### knowledge/legacy/modernization-candidates.md
+
+\`\`\`markdown
+---
+type: modernization-candidates
+generated_by: legacy-agent
+---
+
+# Modernization Candidates
+
+## MOD-001: <Short title>
+
+- **Current state:** <what exists today>
+- **Target state:** <desired outcome>
+- **Value:** <why this modernization matters>
+- **Risk:** low | medium | high
+- **Suggested Knowledge Level:** K1 | K2 | K3 | K4
+- **Related risks:** RISK-xxx
+- **Related unknowns:** UNK-xxx
+- **Affected entities:** <system graph entities, or "Graph unavailable">
+
+## MOD-002: ...
 \`\`\`
 
 ## Where to Save the Result
@@ -14065,10 +14424,15 @@ Save risks as \`knowledge/legacy/risks.md\`, unknowns as
 
 ## Quality Checklist
 
-- Risks are backed by evidence.
+- Every risk has a stable RISK-xxx identifier, blast radius, and confidence level.
+- Every unknown has a stable UNK-xxx identifier and related risk references.
+- Every modernization candidate has a stable MOD-xxx identifier and Knowledge Level.
+- Scan signals are referenced when available \u2014 findings are grounded in detected signals.
+- System Graph entities are referenced when topology is available.
 - Safe first steps are small and low-risk.
-- Unknowns are explicit.
+- Assumptions are marked explicitly with confidence.
 - Areas needing human validation are flagged.
+- Identifiers are unique and sequential within each artifact.
 `;
 var ADR_AGENT2 = `# ADR Agent
 
@@ -14290,6 +14654,14 @@ the decision is still a candidate in knowledge/tech/decision-candidates.md with
 that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and record
 \`decision_candidates: [<title>]\` \u2014 do not implement work that depends on an unformalized decision
 without surfacing it. -->
+
+**Related legacy findings:** <!-- for legacy projects (WI-012): when
+\`knowledge/legacy/risks.md\`, \`knowledge/legacy/unknowns.md\` or
+\`knowledge/legacy/modernization-candidates.md\` exist, check whether any findings (RISK-xxx,
+UNK-xxx, MOD-xxx) are relevant to this Work Item's scope. Add \`legacy_risks: [RISK-001, ...]\`
+and \`legacy_unknowns: [UNK-001, ...]\` to the front matter when applicable. Do NOT copy the full
+finding content \u2014 reference by identifier. Include relevant findings in the Scope unknowns
+section when they affect implementation decisions. -->
 \`\`\`
 
 ### Preserve roadmap metadata (VS-077 / VS-078)
@@ -16792,6 +17164,37 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
   }
   return node;
 }
+var RISKS_PATH = "knowledge/legacy/risks.md";
+var UNKNOWNS_PATH = "knowledge/legacy/unknowns.md";
+var CANDIDATES_PATH = "knowledge/legacy/modernization-candidates.md";
+function hasLegacyKnowledge(dir) {
+  return exists2(join3(dir, RISKS_PATH)) || exists2(join3(dir, UNKNOWNS_PATH)) || exists2(join3(dir, CANDIDATES_PATH));
+}
+var ID_PATTERN = /^##\s+(RISK-\d+|UNK-\d+|MOD-\d+)/gm;
+function extractIdentifiers(content, prefix) {
+  const ids = [];
+  for (const m2 of content.matchAll(ID_PATTERN)) {
+    if (m2[1].startsWith(prefix)) ids.push(m2[1]);
+  }
+  return ids;
+}
+function readArtifact(dir, rel, prefix) {
+  const abs = join3(dir, rel);
+  if (!exists2(abs)) return { path: rel, exists: false, identifiers: [] };
+  const content = readFile2(abs);
+  return { path: rel, exists: true, identifiers: extractIdentifiers(content, prefix) };
+}
+function getLegacyKnowledgeSummary(dir) {
+  const risks = readArtifact(dir, RISKS_PATH, "RISK-");
+  const unknowns = readArtifact(dir, UNKNOWNS_PATH, "UNK-");
+  const candidates = readArtifact(dir, CANDIDATES_PATH, "MOD-");
+  return {
+    available: risks.exists || unknowns.exists || candidates.exists,
+    risks,
+    unknowns,
+    candidates
+  };
+}
 var RECOMMENDED_AGENT = "work-item-agent";
 var RECOMMENDED_SKILL = "work-item-refinement";
 function buildRefinementHandoff(dir, workItemId) {
@@ -16839,6 +17242,19 @@ function buildRefinementHandoff(dir, workItemId) {
       "repository, Knowledge and mapped modules \u2014 the Graph is enrichment, not a prerequisite."
     );
   }
+  if (hasLegacyKnowledge(dir)) {
+    lines.push(
+      "",
+      "This is a legacy project with existing legacy analysis. When refining, consult:",
+      "- `knowledge/legacy/risks.md` \u2014 known risks (RISK-xxx identifiers).",
+      "- `knowledge/legacy/unknowns.md` \u2014 known unknowns (UNK-xxx identifiers).",
+      "- `knowledge/legacy/modernization-candidates.md` \u2014 modernization candidates (MOD-xxx identifiers).",
+      "",
+      "Reference only the findings relevant to this Work Item's scope \u2014 do not copy all legacy",
+      "knowledge into the Work Item. Add `legacy_risks` and `legacy_unknowns` to the front matter",
+      "when applicable, using the stable identifiers (e.g. `legacy_risks: [RISK-001, RISK-003]`)."
+    );
+  }
   lines.push(
     "",
     `Update the canonical Work Item ${wi.id} with:`,
@@ -16951,6 +17367,37 @@ function buildImplementationHandoff(dir, workItemId) {
       "4. inspect the actual implementation in the repository for each candidate."
     );
   }
+  const legacy = getLegacyKnowledgeSummary(dir);
+  if (legacy.available) {
+    lines.push(
+      "",
+      "--- Legacy Context ---",
+      "",
+      "This project has legacy analysis knowledge. Before implementing, consult the relevant",
+      "legacy findings for the areas this Work Item will modify:"
+    );
+    if (legacy.risks.exists) {
+      lines.push(
+        `- Risks (${legacy.risks.identifiers.length} findings): \`${legacy.risks.path}\``
+      );
+    }
+    if (legacy.unknowns.exists) {
+      lines.push(
+        `- Unknowns (${legacy.unknowns.identifiers.length} findings): \`${legacy.unknowns.path}\``
+      );
+    }
+    if (legacy.candidates.exists) {
+      lines.push(
+        `- Modernization candidates (${legacy.candidates.identifiers.length} findings): \`${legacy.candidates.path}\``
+      );
+    }
+    lines.push(
+      "",
+      "Reference relevant findings by their stable identifiers (RISK-xxx, UNK-xxx, MOD-xxx).",
+      "Highlight risks that intersect with the areas to be modified in the Design Deliberation.",
+      "Do not copy all legacy knowledge \u2014 assemble proportionally to scope."
+    );
+  }
   lines.push(
     "",
     "--- Implementation Plan ---",

package/package.json

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