packet-tracer-skill 0.2.0 → 0.2.2

package/scripts/generate_pkt.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import copy
 from dataclasses import asdict, dataclass, field
+from functools import lru_cache
 import json
 import os
 from pathlib import Path
@@ -25,6 +26,7 @@ from coverage_matrix import (
     build_inventory_capability_report,
     select_capability_matrix_hits,
 )
+from feature_atlas import build_feature_gap_report
 from intent_parser import IntentPlan, parse_intent
 from packet_tracer_env import (
     get_packet_tracer_compatibility_donor,
@@ -107,6 +109,11 @@ if hasattr(sys.stdout, "reconfigure"):
         pass
 
 
+@lru_cache(maxsize=1)
+def _inspect_packet_tracer_compatibility_donor_cached():
+    return inspect_packet_tracer_compatibility_donor()
+
+
 class PlanningError(RuntimeError):
     def __init__(self, message: str, plan: IntentPlan) -> None:
         super().__init__(message)
@@ -139,7 +146,7 @@ STRICT_COMPATIBILITY_GAP = (
 
 
 def _compat_donor_details() -> tuple[Path | None, str | None]:
-    details = inspect_packet_tracer_compatibility_donor()
+    details = _inspect_packet_tracer_compatibility_donor_cached()
     return details.resolved_path, details.donor_version
 
 
@@ -327,28 +334,97 @@ def _preferred_donor_archetypes_for_plan(plan: IntentPlan, topology_tags: list[s
     }
     capabilities = set(plan.capabilities)
     tags = set(topology_tags or [])
-    if plan.department_groups or tags & {"chain", "core_access", "router_on_a_stick", "acl_policy"}:
-        preferred.append("campus/core")
-    elif device_families & {"routers", "switches", "multilayer switches"} and capabilities & {
-        "vlan",
-        "router_on_a_stick",
-        "management_vlan",
-        "telnet",
-    }:
-        preferred.append("campus/core")
-    if requested_services & {"dhcp", "dns", "http", "https", "ftp", "tftp", "email", "syslog", "aaa", "ntp"} or "servers" in device_families:
-        preferred.append("service-heavy")
-    if plan.wireless_mode or capabilities & {
+    prompt_lower = str(plan.prompt or "").lower()
+    explicit_home_gateway_prompt = any(
+        token in prompt_lower
+        for token in ["home gateway", "homegateway", "smart home", "iot "]
+    )
+    family_hints: list[str] = []
+    campus_signal = (
+        plan.network_style == "campus"
+        or "campus" in prompt_lower
+        or "kampus" in prompt_lower
+        or bool(plan.department_groups)
+        or bool(tags & {"chain", "core_access", "router_on_a_stick", "acl_policy"})
+        or bool(
+            device_families & {"routers", "switches", "multilayer switches"}
+            and capabilities & {"vlan", "router_on_a_stick", "management_vlan", "telnet", "acl", "trunk", "access_port"}
+        )
+    )
+    home_iot_signal = (
+        plan.network_style in {"home_iot", "smart_home"}
+        or explicit_home_gateway_prompt
+        or plan.wireless_mode == "home_router_edge"
+        or bool(capabilities & {"iot", "iot_registration", "iot_control"})
+        or bool("iot devices" in device_families)
+    )
+    wan_signal = (
+        plan.network_style == "wan_security"
+        or bool(device_families & {"wan/cloud/dsl/cable devices", "security devices"})
+        or bool(capabilities & {"vpn", "ipsec", "gre", "ppp", "multilayer_switching", "security_edge"})
+    )
+    ipv6_routing_signal = plan.network_style == "ipv6_routing" or bool(capabilities & {"ipv6_slaac", "dhcpv6_stateful", "dhcpv6_stateless", "ipv6_prefix_delegation", "ipv6_dns_aaaa", "ipv6_tunneling", "isatap", "ospfv3", "eigrp_ipv6", "ripng", "hsrp"})
+    l2_security_monitoring_signal = plan.network_style == "l2_security_monitoring" or bool(capabilities & {"dhcp_snooping", "dai", "dot1x", "lldp", "rep", "snmp", "netflow", "span", "qos", "port_security"})
+    wireless_advanced_signal = plan.network_style == "wireless_advanced" or bool(capabilities & {"wlc", "wpa_enterprise", "wep", "guest_wifi", "beamforming", "meraki", "cellular_5g", "bluetooth"})
+    automation_controller_signal = plan.network_style == "automation_controller" or bool(capabilities & {"network_controller", "python_programming", "javascript_programming", "blockly_programming", "tcp_udp_app", "vm_iox"})
+    voice_collaboration_signal = plan.network_style == "voice_collaboration" or bool(capabilities & {"voip", "ip_phone", "call_manager", "linksys_voice"})
+    industrial_iot_signal = plan.network_style == "industrial_iot" or bool(capabilities & {"mqtt", "real_http", "real_websocket", "visual_scripting", "ptp", "profinet", "l2nat", "cyberobserver", "industrial_firewall"})
+    wireless_signal = plan.wireless_mode or capabilities & {
         "wireless_ap",
         "wireless_client",
         "wireless_mutation",
         "wireless_client_association",
-    }:
-        preferred.append("wireless-heavy")
-    if capabilities & {"iot", "iot_registration", "iot_control"} or "iot devices" in device_families:
-        preferred.append("IoT/home gateway")
-    if device_families & {"wan/cloud/dsl/cable devices", "security devices"} or capabilities & {"vpn", "nat", "pat", "acl"}:
-        preferred.append("WAN/security edge")
+    }
+    service_signal = (
+        requested_services & {"dns", "dhcp", "http", "https", "ftp", "tftp", "email", "syslog", "aaa", "ntp"}
+        or capabilities & {"server_dns", "server_dhcp", "server_http", "server_https", "server_ftp", "server_tftp", "server_email", "server_syslog", "server_aaa"}
+        or "servers" in device_families
+    )
+
+    if industrial_iot_signal:
+        family_hints.append("industrial IoT")
+    elif automation_controller_signal:
+        family_hints.append("automation/controller")
+    elif voice_collaboration_signal:
+        family_hints.append("voice/collaboration")
+    elif wireless_advanced_signal:
+        family_hints.append("advanced wireless")
+    elif l2_security_monitoring_signal:
+        family_hints.append("L2 security/monitoring")
+    elif ipv6_routing_signal:
+        family_hints.append("IPv6/routing")
+    elif wan_signal:
+        family_hints.append("WAN/security edge")
+        if campus_signal and not bool(capabilities & {"vpn", "ipsec", "gre", "ppp", "security_edge"}):
+            family_hints.append("campus/core")
+    elif campus_signal:
+        family_hints.append("campus/core")
+        if wireless_signal:
+            family_hints.append("wireless-heavy")
+        if service_signal and requested_services & {"email", "syslog", "aaa", "http", "https", "ftp", "tftp"}:
+            family_hints.append("service-heavy")
+    elif home_iot_signal:
+        family_hints.append("IoT/home gateway")
+        if wireless_signal:
+            family_hints.append("wireless-heavy")
+    elif service_signal:
+        family_hints.append("service-heavy")
+    elif wireless_signal:
+        family_hints.append("wireless-heavy")
+
+    if not family_hints:
+        if service_signal:
+            family_hints.append("service-heavy")
+        if wireless_signal:
+            family_hints.append("wireless-heavy")
+        if home_iot_signal:
+            family_hints.append("IoT/home gateway")
+        if wan_signal:
+            family_hints.append("WAN/security edge")
+
+    for item in family_hints:
+        if item not in preferred:
+            preferred.append(item)
     return preferred
 
 
@@ -361,6 +437,16 @@ def _required_runtime_features_for_plan(plan: IntentPlan) -> list[str]:
         features.add("wireless_runtime")
     if capabilities & {"iot", "iot_registration", "iot_control"}:
         features.add("iot_runtime")
+    if capabilities & {"vpn", "ipsec", "gre"}:
+        features.add("tunnel_runtime")
+    if capabilities & {"ppp"}:
+        features.add("wan_runtime")
+    if capabilities & {"security_edge", "acl", "nat"}:
+        features.add("security_runtime")
+    if capabilities & {"multilayer_switching"}:
+        features.add("multilayer_runtime")
+    if capabilities & {"ipv6_slaac", "dhcpv6_stateful", "dhcpv6_stateless", "ospfv3", "eigrp_ipv6", "ripng", "hsrp"}:
+        features.add("ipv6_runtime")
     return sorted(features)
 
 
@@ -437,6 +523,20 @@ def _candidate_acceptance_penalty(candidate: SampleCandidate, blueprint: dict[st
         "wireless_mutation": 18,
         "wireless_client_association": 22,
         "end_device_mutation": 12,
+        "iot_registration": 26,
+        "iot_control": 24,
+        "vpn": 22,
+        "ipsec": 22,
+        "gre": 20,
+        "ppp": 18,
+        "security_edge": 20,
+        "multilayer_switching": 16,
+        "ipv6_slaac": 18,
+        "dhcpv6_stateful": 18,
+        "ospfv3": 18,
+        "eigrp_ipv6": 18,
+        "ripng": 16,
+        "hsrp": 16,
     }.items():
         if capability in requested_capabilities and capability not in supported_capabilities:
             penalty += penalty_value
@@ -507,13 +607,108 @@ def _summarize_candidate_pool(
                 break
         if len(top_rejection_reasons) >= 5:
             continue
+    primary_rejection_code = _primary_rejection_code(top_rejection_reasons)
+    primary_rejection_layer = _primary_rejection_layer(primary_rejection_code)
+    best_rejected_donor_class = (
+        next((str(item) for item in list(preferred_archetypes or []) if str(item).strip()), None)
+        if any(counts[key] > 0 for key in ("rejected", "filtered"))
+        else None
+    )
     return {
         "preferred_donor_archetypes": list(preferred_archetypes or []),
         "candidate_counts": counts,
         "best_adjusted_total_score": best_adjusted_score,
         "best_layout_reuse_score": best_layout_reuse_score,
         "top_rejection_reasons": top_rejection_reasons,
+        "best_rejected_donor_class": best_rejected_donor_class,
+        "primary_rejection_code": primary_rejection_code,
+        "primary_rejection_layer": primary_rejection_layer,
+    }
+
+
+def _primary_rejection_code(rejection_reasons: list[str]) -> str | None:
+    normalized = [str(item).strip().lower() for item in rejection_reasons if str(item).strip()]
+    if any("runtime subtree" in reason for reason in normalized):
+        return "runtime_subtree_missing"
+    if any("archetype_gap:" in reason or "archetype does not align" in reason for reason in normalized):
+        return "archetype_misaligned"
+    if any(
+        marker in reason
+        for reason in normalized
+        for marker in (
+            "missing_link_pairs:",
+            "no reusable link pairs",
+            "reuses too little of the requested link skeleton",
+            "cannot create new donor link pair",
+            "requires donor link reuse",
+            "port mismatch",
+            "media mismatch",
+            "ports/media",
+        )
+    ):
+        return "layout_reuse_too_weak"
+    if any(
+        marker in reason
+        for reason in normalized
+        for marker in (
+            "acceptance penalty",
+            "acceptance_gated",
+            "acceptance-gated",
+            "acceptance fixture",
+            "acceptance evidence",
+            "acceptance risk",
+        )
+    ):
+        return "acceptance_evidence_too_weak"
+    return None
+
+
+def _primary_rejection_layer(primary_rejection_code: str | None) -> str | None:
+    if primary_rejection_code == "acceptance_evidence_too_weak":
+        return "acceptance"
+    if primary_rejection_code in {
+        "layout_reuse_too_weak",
+        "archetype_misaligned",
+        "runtime_subtree_missing",
+    }:
+        return "donor"
+    return None
+
+
+def _best_rejected_donor_summary(
+    best_rejected_donor_class: str | None,
+    primary_rejection_code: str | None,
+    top_rejection_reasons: list[str],
+) -> str | None:
+    if not best_rejected_donor_class and not primary_rejection_code:
+        return None
+    reason_sentence_map = {
+        "layout_reuse_too_weak": "its reusable link skeleton is still too weak for the requested topology",
+        "acceptance_evidence_too_weak": "its acceptance evidence is still too weak for prompt-level generate",
+        "archetype_misaligned": "its donor shape does not align with the requested scenario archetype",
+        "runtime_subtree_missing": "the required runtime subtree is missing from the donor path",
+    }
+    next_shape_map = {
+        "layout_reuse_too_weak": "choose a donor with the same family but a stronger reusable router-switch-service skeleton",
+        "acceptance_evidence_too_weak": "choose a donor with explicit acceptance-backed coverage for the same scenario family",
+        "archetype_misaligned": "choose a donor whose archetype already matches the requested family",
+        "runtime_subtree_missing": "choose a donor that already contains the required runtime subtree and open-state structure",
     }
+    donor_class = best_rejected_donor_class or "the closest donor class"
+    reason = reason_sentence_map.get(primary_rejection_code or "", "it still did not satisfy strict donor selection")
+    next_shape = next_shape_map.get(primary_rejection_code or "", "choose a closer donor before prompt generate")
+    if donor_class == "WAN/security edge":
+        wan_next_shape_map = {
+            "layout_reuse_too_weak": "choose a WAN/security donor with reusable ASA/cloud/serial or tunnel skeleton",
+            "acceptance_evidence_too_weak": "choose a WAN/security donor with explicit VPN/IPSec/GRE/PPP acceptance evidence",
+            "archetype_misaligned": "choose a donor already tagged as WAN/security edge",
+            "runtime_subtree_missing": "choose a donor that already contains the WAN/security runtime subtree",
+        }
+        next_shape = wan_next_shape_map.get(primary_rejection_code or "", "choose a closer WAN/security donor before prompt generate")
+    summary = f"Best rejected donor class {donor_class} was closest, but {reason}; {next_shape}."
+    if top_rejection_reasons:
+        summary = f"{summary} Top rejection signal: {top_rejection_reasons[0]}."
+    return summary
 
 
 def _load_fixture_corpus() -> dict[str, object]:
@@ -699,6 +894,10 @@ def _filter_candidates_for_blueprint(
             filter_reasons.append("sample lacks donor-backed support for requested wireless mutation")
         if "end_device_mutation" in required_capabilities and "end_device_mutation" not in supported_capabilities:
             filter_reasons.append("sample lacks donor-backed support for requested end-device mutation")
+        if "iot_registration" in required_capabilities and "iot_registration" not in supported_capabilities:
+            filter_reasons.append("sample lacks donor-backed support for requested IoT registration")
+        if "iot_control" in required_capabilities and "iot_control" not in supported_capabilities:
+            filter_reasons.append("sample lacks donor-backed support for requested IoT control")
         if adjusted_total_score <= 0:
             filter_reasons.append("acceptance penalty reduced the donor score below zero")
         if filter_reasons:
@@ -2472,8 +2671,11 @@ def _augment_coverage_gap_actions(
         actions.append("For service-heavy prompts, prefer a donor that already contains the required server service family and core server layout.")
     if scenario_family == "home_iot" and scenario_status in {"donor_limited", "acceptance_gated", "unsupported"}:
         actions.append("For home IoT prompts, prefer a donor with Home Gateway plus existing IoT registration/control structure.")
+        actions.append("For donor-backed Home IoT generate, explicitly name the thing, gateway/server target, and wireless client or SSID targets.")
     if scenario_family == "wan_security_edge" and scenario_status in {"donor_limited", "acceptance_gated", "unsupported"}:
         actions.append("For WAN/security prompts, prefer a donor with reusable serial/WAN or security-edge skeleton before generating.")
+    if scenario_family in {"ipv6_routing", "l2_security_monitoring", "wireless_advanced", "automation_controller", "voice_collaboration", "industrial_iot", "physical_media_device"} and scenario_status in {"donor_limited", "acceptance_gated", "unsupported"}:
+        actions.append("This feature family is atlas/report-first; keep it out of strict generate until donor-backed proof and acceptance fixtures exist.")
     updated["recommended_next_actions"] = list(dict.fromkeys(actions))
     return updated
 
@@ -2524,12 +2726,26 @@ def _scenario_generate_decision(
         "service_heavy": "service-heavy",
         "home_iot": "home IoT",
         "wan_security_edge": "WAN/security edge",
+        "ipv6_routing": "IPv6/routing",
+        "l2_security_monitoring": "L2 security/monitoring",
+        "wireless_advanced": "advanced wireless",
+        "automation_controller": "automation/controller",
+        "voice_collaboration": "voice/collaboration",
+        "industrial_iot": "industrial IoT",
+        "physical_media_device": "physical/media device",
     }
     expected_archetype_map = {
         "campus": "campus/core",
         "service_heavy": "service-heavy",
         "home_iot": "IoT/home gateway",
         "wan_security_edge": "WAN/security edge",
+        "ipv6_routing": "IPv6/routing",
+        "l2_security_monitoring": "L2 security/monitoring",
+        "wireless_advanced": "advanced wireless",
+        "automation_controller": "automation/controller",
+        "voice_collaboration": "voice/collaboration",
+        "industrial_iot": "industrial IoT",
+        "physical_media_device": "physical/media device",
     }
     family_label = family_label_map.get(family, family)
     blocking_reasons: list[str] = []
@@ -2543,6 +2759,13 @@ def _scenario_generate_decision(
     expected_archetype = expected_archetype_map.get(family)
     sample_archetypes = [str(item) for item in list((selected_donor_summary or {}).get("sample_archetypes", [])) if str(item).strip()]
     donor_graph_summary = dict((selected_donor_summary or {}).get("donor_graph_summary") or {})
+    best_rejected_donor_class = str((donor_selection_summary or {}).get("best_rejected_donor_class") or "").strip() or None
+    primary_rejection_code = str((donor_selection_summary or {}).get("primary_rejection_code") or "").strip() or None
+    best_rejected_donor_summary = _best_rejected_donor_summary(
+        best_rejected_donor_class,
+        primary_rejection_code,
+        [str(item) for item in list((donor_selection_summary or {}).get("top_rejection_reasons", [])) if str(item).strip()],
+    )
     if expected_archetype and sample_archetypes:
         aligned = expected_archetype in sample_archetypes
         decision["selected_donor_aligned"] = aligned
@@ -2590,6 +2813,8 @@ def _scenario_generate_decision(
             blocking_reasons.append(
                 f"Scenario '{family_label}' depends on donor-limited safe-open coverage, but no compatible donor was selected."
             )
+        if best_rejected_donor_summary:
+            notes.append(best_rejected_donor_summary)
         layout_status = str(donor_graph_summary.get("layout_reuse_status") or "").strip()
         pair_coverage = donor_graph_summary.get("reusable_pair_coverage")
         if layout_status == "weak":
@@ -2600,6 +2825,18 @@ def _scenario_generate_decision(
             blocking_reasons.append(
                 f"Scenario '{family_label}' donor selection has no reusable link-pair coverage for prompt generate."
             )
+        if primary_rejection_code == "archetype_misaligned":
+            blocking_reasons.append(
+                f"Scenario '{family_label}' best donor class is still archetype-misaligned with the requested prompt shape."
+            )
+        elif primary_rejection_code == "runtime_subtree_missing":
+            blocking_reasons.append(
+                f"Scenario '{family_label}' donor candidates are missing required runtime subtree coverage for strict reuse."
+            )
+        elif primary_rejection_code == "acceptance_evidence_too_weak":
+            blocking_reasons.append(
+                f"Scenario '{family_label}' donor candidates still lack strong enough acceptance evidence for strict prompt generate."
+            )
         if layout_status in {"strong", "partial"} and isinstance(pair_coverage, int) and pair_coverage > 0:
             notes.append(f"selected donor provides {pair_coverage}% reusable link-pair coverage ({layout_status})")
         if selected_donor_summary and not blocking_reasons:
@@ -2668,12 +2905,6 @@ def _scenario_acceptance_summary(
         donor_state = "candidate_pool_blocked"
     if donor_state == "not_selected" and int(candidate_counts.get("selected", 0) or 0) > 0:
         donor_state = "selection_pending"
-    selection_failure_type = None
-    if not selected_donor_summary:
-        if donor_state in {"candidate_pool_blocked", "selection_pending"}:
-            selection_failure_type = "viable_donor_found_but_acceptance_weak"
-        else:
-            selection_failure_type = "no_viable_donor_found"
     key_reasons = [str(item) for item in decision.get("blocking_reasons", []) if str(item).strip()]
     if not key_reasons:
         key_reasons = [str(item) for item in decision.get("notes", []) if str(item).strip()]
@@ -2682,11 +2913,19 @@ def _scenario_acceptance_summary(
         None,
     )
     top_rejection_reasons = [str(item) for item in list((donor_selection_summary or {}).get("top_rejection_reasons", [])) if str(item).strip()]
+    primary_rejection_code = str((donor_selection_summary or {}).get("primary_rejection_code") or "").strip() or _primary_rejection_code(top_rejection_reasons)
+    primary_rejection_layer = str((donor_selection_summary or {}).get("primary_rejection_layer") or "").strip() or _primary_rejection_layer(primary_rejection_code)
+    best_rejected_donor_class = str((donor_selection_summary or {}).get("best_rejected_donor_class") or "").strip() or None
+    selection_failure_type = None
     if not selected_donor_summary:
-        if any("archetype_gap:" in reason for reason in top_rejection_reasons):
+        if primary_rejection_code == "archetype_misaligned":
             selection_failure_type = "viable_donor_found_but_archetype_misaligned"
-        elif any("runtime subtree" in reason.lower() for reason in top_rejection_reasons):
+        elif primary_rejection_code == "runtime_subtree_missing":
             selection_failure_type = "viable_donor_found_but_runtime_subtree_missing"
+        elif donor_state in {"candidate_pool_blocked", "selection_pending"}:
+            selection_failure_type = "viable_donor_found_but_acceptance_weak"
+        else:
+            selection_failure_type = "no_viable_donor_found"
     critical_capability_parity, critical_parity_mismatches = _critical_capability_parity(coverage_gap)
     best_available_donor_class = next(
         (
@@ -2696,11 +2935,39 @@ def _scenario_acceptance_summary(
         ),
         None,
     )
+    if best_available_donor_class is None:
+        family_donor_class_map = {
+            "campus": "campus/core",
+            "service_heavy": "service-heavy",
+            "home_iot": "IoT/home gateway",
+            "wan_security_edge": "WAN/security edge",
+            "ipv6_routing": "IPv6/routing",
+            "l2_security_monitoring": "L2 security/monitoring",
+            "wireless_advanced": "advanced wireless",
+            "automation_controller": "automation/controller",
+            "voice_collaboration": "voice/collaboration",
+            "industrial_iot": "industrial IoT",
+            "physical_media_device": "physical/media device",
+        }
+        best_available_donor_class = family_donor_class_map.get(str(readiness.get("family") or "").strip())
+    if selected_donor_summary:
+        best_rejected_donor_class = None
+        primary_rejection_code = None
+        primary_rejection_layer = None
+    elif best_rejected_donor_class is None:
+        best_rejected_donor_class = best_available_donor_class
     remediation_steps = [
         str(item)
         for item in list(coverage_gap.get("recommended_next_actions", []))
         if str(item).strip()
     ][:3]
+    best_rejected_donor_summary = _best_rejected_donor_summary(
+        best_rejected_donor_class,
+        primary_rejection_code,
+        top_rejection_reasons,
+    )
+    if best_rejected_donor_summary:
+        remediation_steps = [best_rejected_donor_summary, *remediation_steps][:3]
     missing_donor_classes = [best_available_donor_class] if selection_failure_type == "viable_donor_found_but_archetype_misaligned" and best_available_donor_class else []
     critical_runtime_requirements: list[str] = []
     if runtime_blocked:
@@ -2725,10 +2992,14 @@ def _scenario_acceptance_summary(
         "next_best_action": next_best_action,
         "remediation_steps": remediation_steps,
         "best_available_donor_class": best_available_donor_class,
+        "best_rejected_donor_class": best_rejected_donor_class,
+        "best_rejected_donor_summary": best_rejected_donor_summary,
         "missing_donor_classes": missing_donor_classes,
         "critical_runtime_requirements": critical_runtime_requirements,
         "decision_confidence": decision.get("decision_confidence"),
         "blocking_layer": decision.get("blocking_layer"),
+        "primary_rejection_layer": primary_rejection_layer,
+        "primary_rejection_code": primary_rejection_code,
     }
 
 
@@ -2808,6 +3079,7 @@ def _scenario_matrix_row(
         "decision_confidence": summary.get("decision_confidence"),
         "blocking_layer": summary.get("blocking_layer"),
         "best_available_donor_class": summary.get("best_available_donor_class"),
+        "primary_rejection_code": summary.get("primary_rejection_code"),
         "remediation_hint": next((str(item) for item in list(summary.get("remediation_steps", []) or []) if str(item).strip()), None),
     }
 
@@ -2984,7 +3256,7 @@ def generate_from_prompt(
     )
     coverage_gap = _augment_coverage_gap_actions(
         coverage_gap,
-        donor_blocking_reason=inspect_packet_tracer_compatibility_donor().blocking_reason,
+        donor_blocking_reason=_inspect_packet_tracer_compatibility_donor_cached().blocking_reason,
     )
     scenario_generate_decision = _scenario_generate_decision(coverage_gap)
     prepared_plan.remote_search_results = remote_results
@@ -3084,7 +3356,7 @@ def _explain_plan_payload(
     )
     plan = _apply_prompt_compatibility_requirements(raw_plan, resolved_donor_roots)
     plan.remote_search_results = remote_results
-    donor_details = inspect_packet_tracer_compatibility_donor()
+    donor_details = _inspect_packet_tracer_compatibility_donor_cached()
     compat_donor, compat_donor_version = donor_details.resolved_path, donor_details.donor_version
     topology_tags = _topology_tags_for_plan(plan, _choose_topology_archetype(plan))
     result: dict[str, object] = {
@@ -3213,8 +3485,22 @@ def _explain_plan_payload(
         try:
             if evaluation is None:
                 raise PlanningError("Prompt plan is incomplete; generation was skipped.", prepared)
-            adapted_plan, donor_archetype, donor_root, _ = evaluation
+            adapted_plan, donor_archetype, donor_root, selected_candidate = evaluation
             safe_plan, profiled_plan = _apply_safe_open_profile(donor_root, adapted_plan)
+            matrix_hits, coverage_gap, blueprint_plan = _build_support_reports(
+                profiled_plan,
+                blueprint=blueprint,
+                cisco_ranked=cisco_ranked,
+                curated_ranked=curated_ranked,
+                reference_catalog=reference_catalog,
+                selected_donor=selected_candidate.sample.relative_path,
+            )
+            coverage_gap = _augment_coverage_gap_actions(
+                coverage_gap,
+                donor_diagnostics=diagnostics,
+                donor_selection_summary=result["donor_selection_summary"],
+                donor_blocking_reason=donor_details.blocking_reason,
+            )
             profiled_plan.remote_search_results = remote_results
             profiled_plan.capability_matrix_hits = matrix_hits
             profiled_plan.coverage_gap_report = coverage_gap
@@ -3269,6 +3555,11 @@ def _explain_plan_payload(
                 result["scenario_acceptance_summary"],
                 selected_donor_summary=result["selected_donor_summary"],
             )
+            result["capability_matrix_hits"] = matrix_hits
+            result["unsupported_capabilities"] = coverage_gap.get("unsupported_capabilities", [])
+            result["coverage_gaps"] = coverage_gap
+            result["capability_parity"] = list(coverage_gap.get("capability_parity", []))
+            result["blueprint_plan"] = blueprint_plan
         except PlanningError as exc:
             if result["donor_rejection_reasons"]:
                 for item in result["donor_rejection_reasons"]:
@@ -3377,7 +3668,7 @@ def inventory_pkt(
     root = ET.fromstring(decode_pkt_modern(pkt_path.read_bytes()))
     payload = inventory_root(root)
     workspace = inspect_workspace_integrity(root)
-    donor_details = inspect_packet_tracer_compatibility_donor()
+    donor_details = _inspect_packet_tracer_compatibility_donor_cached()
     compat_donor, compat_donor_version = donor_details.resolved_path, donor_details.donor_version
     payload["workspace_validation"] = {
         "workspace_mode": workspace.workspace_mode,
@@ -3635,6 +3926,10 @@ def compare_scenarios(
     print(rendered)
 
 
+def feature_gap_report() -> None:
+    print(json.dumps(build_feature_gap_report(), indent=2, ensure_ascii=False))
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Generate or inspect Cisco Packet Tracer 9.0 .pkt files")
     parser.add_argument("--blueprint", help="Path to the topology blueprint JSON")
@@ -3658,6 +3953,7 @@ def main() -> None:
     parser.add_argument("--max-remote-results", type=int, default=10, help="Maximum number of remote search results to fetch/import")
     parser.add_argument("--blueprint-out", help="Optional JSON output path for the generated blueprint plan or refusal blueprint")
     parser.add_argument("--coverage-report", action="store_true", help="Print the aggregated capability coverage matrix")
+    parser.add_argument("--feature-gap-report", action="store_true", help="Print the Packet Tracer feature gap atlas report")
     parser.add_argument("--inventory-capabilities", action="store_true", help="Include inferred capability inventory when using --inventory")
     parser.add_argument("--inventory-out", help="Optional JSON output path when using --inventory")
     parser.add_argument("--matrix-out", help="Optional JSON output path when using --compare-scenarios")
@@ -3725,6 +4021,9 @@ def main() -> None:
     if args.coverage_report:
         coverage_report(reference_roots, donor_roots, device_family=args.device_family)
         return
+    if args.feature_gap_report:
+        feature_gap_report()
+        return
     if args.decode:
         if not args.xml_out:
             parser.error("--decode requires --xml-out")