packet-tracer-skill 0.2.1 → 0.2.3

package/scripts/generate_pkt.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import argparse
 import copy
+from collections import Counter, defaultdict
 from dataclasses import asdict, dataclass, field
+from functools import lru_cache
 import json
 import os
 from pathlib import Path
@@ -25,6 +27,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,
@@ -35,7 +38,13 @@ from pkt_builder import build_packet_tracer_xml
 from pkt_codec import decode_pkt_file, decode_pkt_modern, encode_pkt_modern
 from pkt_editor import apply_plan_operations, decode_pkt_to_root, edit_pkt_file, inventory_devices, inventory_links, inventory_root
 from pkt_transformer import transform_from_blueprint
-from remote_search import asdict_list as remote_asdict_list, auto_import_remote_candidates, search_remote_candidates
+from remote_search import (
+    asdict_list as remote_asdict_list,
+    auto_import_remote_candidates,
+    candidate_is_curated_eligible,
+    search_remote_candidates,
+    write_remote_sample_audit,
+)
 from sample_catalog import ReferencePattern, SampleCandidate, SampleDescriptor, load_catalog, load_curated_donor_catalog, load_reference_catalog, summarize_pkt_descriptor
 from sample_selector import rank_curated_donor_samples, rank_reference_samples, rank_samples, select_best_sample
 from workspace_repair import inspect_donor_coherence, inspect_workspace_integrity, validate_donor_coherence, validate_workspace_integrity
@@ -81,6 +90,9 @@ DEVICE_FAMILY_MAP = {
     "Tablet": "end devices",
     "Smartphone": "end devices",
     "Printer": "end devices",
+    "IpPhone": "end devices",
+    "HomeVoip": "end devices",
+    "AnalogPhone": "end devices",
     "LightWeightAccessPoint": "access points",
     "WirelessRouter": "home/wireless routers",
     "WirelessRouterNewGeneration": "home/wireless routers",
@@ -107,6 +119,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 +156,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
 
 
@@ -244,6 +261,8 @@ def _resolve_remote_sources(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
 ) -> tuple[list[Path], list[Path], list[dict[str, object]]]:
     resolved_reference_roots = list(reference_roots or [])
     resolved_donor_roots = list(donor_roots or [])
@@ -251,13 +270,19 @@ def _resolve_remote_sources(
         return resolved_reference_roots, resolved_donor_roots, []
     remote_candidates = search_remote_candidates(plan, provider=remote_provider, max_results=max_remote_results)
     cache_root = import_cache_root or _default_import_cache_root()
-    imported_candidates = auto_import_remote_candidates(remote_candidates, cache_root, max_results=max_remote_results)
+    imported_candidates = auto_import_remote_candidates(
+        remote_candidates,
+        cache_root,
+        max_results=max_remote_results,
+        dry_run=remote_dry_run,
+    )
+    write_remote_sample_audit(imported_candidates, cache_root, remote_audit_out)
     for candidate in imported_candidates:
         if candidate.path:
             imported_root = Path(candidate.path)
             if imported_root not in resolved_reference_roots:
                 resolved_reference_roots.append(imported_root)
-            if imported_root not in resolved_donor_roots:
+            if candidate_is_curated_eligible(candidate) and imported_root not in resolved_donor_roots:
                 resolved_donor_roots.append(imported_root)
     return resolved_reference_roots, resolved_donor_roots, remote_asdict_list(imported_candidates)
 
@@ -327,28 +352,100 @@ 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"})
+    ipv4_routing_management_signal = plan.network_style == "ipv4_routing_management" or bool(capabilities & {"ospfv2", "eigrp_ipv4", "ripv2", "static_route", "default_route", "dhcp_relay", "nat_static", "nat_dynamic", "pat", "ssh_ios", "ntp_ios", "syslog_ios"})
+    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 ipv4_routing_management_signal:
+        family_hints.append("IPv4 routing/management")
+    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 +458,18 @@ 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")
+    if capabilities & {"ospfv2", "eigrp_ipv4", "ripv2", "static_route", "default_route", "dhcp_relay", "nat_static", "nat_dynamic", "pat", "ssh_ios", "ntp_ios", "syslog_ios"}:
+        features.add("ipv4_routing_management_runtime")
     return sorted(features)
 
 
@@ -437,6 +546,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,15 +630,110 @@ 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]:
     if not FIXTURE_CORPUS_PATH.exists():
         return {"fixture_registry_version": "missing", "fixtures": []}
@@ -594,12 +812,23 @@ def _critical_capability_parity(coverage_gap: dict[str, object]) -> tuple[list[d
 def _parity_counts(parity_entries: list[dict[str, object]]) -> dict[str, int]:
     return {
         "parity_supported_count": sum(1 for entry in parity_entries if bool(entry.get("inventory_supported"))),
+        "parity_donor_backed_ready_count": sum(1 for entry in parity_entries if bool(entry.get("donor_backed_ready"))),
         "parity_generate_ready_count": sum(1 for entry in parity_entries if bool(entry.get("generate_supported"))),
         "parity_acceptance_verified_count": sum(1 for entry in parity_entries if bool(entry.get("acceptance_verified"))),
         "parity_mismatch_count": sum(1 for entry in parity_entries if entry.get("generate_mismatch_reason")),
     }
 
 
+def _critical_parity_counts(critical_entries: list[dict[str, object]]) -> dict[str, int]:
+    return {
+        "critical_parity_supported_count": sum(1 for entry in critical_entries if bool(entry.get("inventory_supported"))),
+        "critical_parity_donor_backed_ready_count": sum(1 for entry in critical_entries if bool(entry.get("donor_backed_ready"))),
+        "critical_parity_generate_ready_count": sum(1 for entry in critical_entries if bool(entry.get("generate_supported"))),
+        "critical_parity_acceptance_verified_count": sum(1 for entry in critical_entries if bool(entry.get("acceptance_verified"))),
+        "critical_parity_mismatch_count": sum(1 for entry in critical_entries if entry.get("generate_mismatch_reason")),
+    }
+
+
 def _selected_donor_summary(
     diagnostics: list[dict[str, object]],
     donor_archetype: DonorArchetypePlan | None = None,
@@ -699,6 +928,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 +2705,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 +2760,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 +2793,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 +2847,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 +2859,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 +2939,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 +2947,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 +2969,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:
@@ -2721,14 +3022,19 @@ def _scenario_acceptance_summary(
         "missing_critical_capabilities": [str(item) for item in list(readiness.get("missing_critical_capabilities", [])) if str(item).strip()],
         "critical_capability_parity": critical_capability_parity,
         "critical_parity_mismatches": critical_parity_mismatches,
+        **_critical_parity_counts(critical_capability_parity),
         "key_reasons": key_reasons[:3],
         "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 +3114,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),
     }
 
@@ -2944,6 +3251,8 @@ def generate_from_prompt(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
     blueprint_out_path: Path | None = None,
 ) -> None:
     raw_plan = parse_intent(prompt)
@@ -2955,6 +3264,8 @@ def generate_from_prompt(
         remote_provider=remote_provider,
         import_cache_root=import_cache_root,
         max_remote_results=max_remote_results,
+        remote_dry_run=remote_dry_run,
+        remote_audit_out=remote_audit_out,
     )
     raw_plan.remote_search_results = remote_results
     if raw_plan.goal == "edit" and raw_plan.pkt_path:
@@ -2984,7 +3295,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
@@ -3071,6 +3382,8 @@ def _explain_plan_payload(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
 ) -> dict[str, object]:
     raw_plan = parse_intent(prompt)
     resolved_reference_roots, resolved_donor_roots, remote_results = _resolve_remote_sources(
@@ -3081,10 +3394,12 @@ def _explain_plan_payload(
         remote_provider=remote_provider,
         import_cache_root=import_cache_root,
         max_remote_results=max_remote_results,
+        remote_dry_run=remote_dry_run,
+        remote_audit_out=remote_audit_out,
     )
     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 +3528,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 +3598,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"]:
@@ -3336,6 +3670,8 @@ def _explain_plan_payload(
     result["scenario_matrix_row"]["fixture_name"] = _scenario_fixture_name(result["scenario_matrix_row"].get("family"))
     result["scenario_matrix_row"]["matrix_version"] = "2.1"
     result["scenario_matrix_row"].update(_parity_counts(_capability_parity_entries(result.get("coverage_gaps", {}))))
+    critical_capability_parity, _critical_parity_mismatches = _critical_capability_parity(dict(result.get("coverage_gaps") or {}))
+    result["scenario_matrix_row"].update(_critical_parity_counts(critical_capability_parity))
     fixture_status, fixture_gaps = _fixture_expectation_status(result)
     result["fixture_registry_version"] = _load_fixture_corpus().get("fixture_registry_version", "unknown")
     result["fixture_expectation_status"] = fixture_status
@@ -3352,6 +3688,8 @@ def explain_plan(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
     acceptance_json_out: Path | None = None,
 ) -> None:
     result = _explain_plan_payload(
@@ -3362,6 +3700,8 @@ def explain_plan(
         remote_provider=remote_provider,
         import_cache_root=import_cache_root,
         max_remote_results=max_remote_results,
+        remote_dry_run=remote_dry_run,
+        remote_audit_out=remote_audit_out,
     )
     _write_json_artifact(result, acceptance_json_out)
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -3377,7 +3717,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,
@@ -3552,6 +3892,8 @@ def parity_report(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
     acceptance_json_out: Path | None = None,
 ) -> None:
     payload = _explain_plan_payload(
@@ -3562,6 +3904,8 @@ def parity_report(
         remote_provider=remote_provider,
         import_cache_root=import_cache_root,
         max_remote_results=max_remote_results,
+        remote_dry_run=remote_dry_run,
+        remote_audit_out=remote_audit_out,
     )
     coverage_gap = dict(payload.get("coverage_gaps") or {})
     if "capability_parity" not in coverage_gap:
@@ -3574,6 +3918,7 @@ def parity_report(
         "critical_capability_parity": critical_capability_parity,
         "critical_parity_mismatches": critical_parity_mismatches,
         **_parity_counts(list(payload.get("capability_parity", []))),
+        **_critical_parity_counts(critical_capability_parity),
     }
     _write_json_artifact(result, acceptance_json_out)
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -3588,6 +3933,8 @@ def compare_scenarios(
     remote_provider: str = "github",
     import_cache_root: Path | None = None,
     max_remote_results: int = 10,
+    remote_dry_run: bool = False,
+    remote_audit_out: Path | None = None,
     matrix_out: Path | None = None,
     acceptance_json_out: Path | None = None,
 ) -> None:
@@ -3602,6 +3949,8 @@ def compare_scenarios(
             remote_provider=remote_provider,
             import_cache_root=import_cache_root,
             max_remote_results=max_remote_results,
+            remote_dry_run=remote_dry_run,
+            remote_audit_out=remote_audit_out,
         )
         fixture_status, fixture_gaps = _fixture_expectation_status(payload)
         payloads.append(
@@ -3635,6 +3984,94 @@ def compare_scenarios(
     print(rendered)
 
 
+def feature_gap_report() -> None:
+    print(json.dumps(build_feature_gap_report(), indent=2, ensure_ascii=False))
+
+
+LOCAL_AUDIT_PATTERNS = {
+    "ospfv2": r"(?mi)^\s*router\s+ospf\s+\d+",
+    "eigrp_ipv4": r"(?mi)^\s*router\s+eigrp\s+\d+",
+    "ripv2": r"(?mi)^\s*router\s+rip\s*$",
+    "static_route": r"(?mi)^\s*ip\s+route\s+\S+\s+\S+\s+\S+",
+    "default_route": r"(?mi)^\s*ip\s+route\s+0\.0\.0\.0\s+0\.0\.0\.0\s+\S+",
+    "dhcp_relay": r"(?mi)^\s*ip\s+helper-address\s+\d+\.\d+\.\d+\.\d+",
+    "nat_static": r"(?mi)^\s*ip\s+nat\s+inside\s+source\s+static\b",
+    "nat_dynamic": r"(?mi)^\s*ip\s+nat\s+inside\s+source\s+(?:list|route-map)\b",
+    "pat": r"(?mi)^\s*ip\s+nat\s+inside\s+source\s+list\s+\S+\s+interface\s+\S+\s+overload\b",
+    "ssh_ios": r"(?mi)^\s*(?:ip\s+ssh|crypto\s+key\s+generate|ip\s+domain-name)\b",
+    "ntp_ios": r"(?mi)^\s*ntp\s+server\s+\d+\.\d+\.\d+\.\d+",
+    "syslog_ios": r"(?mi)^\s*logging\s+host\s+\d+\.\d+\.\d+\.\d+",
+    "bgp": r"(?mi)^\s*router\s+bgp\s+\d+",
+    "stp": r"(?mi)^\s*spanning-tree\b",
+    "etherchannel": r"(?mi)^\s*(?:channel-group\s+\d+|interface\s+Port-channel)",
+    "hsrp": r"(?mi)^\s*standby\s+\d+",
+    "acl": r"(?mi)^\s*(?:access-list\s+\d+|ip\s+access-list\s+(?:standard|extended))\b",
+    "dhcp_pool": r"(?mi)^\s*ip\s+dhcp\s+pool\b",
+}
+
+
+def build_local_sample_audit(root: Path) -> dict[str, object]:
+    files = sorted([*root.rglob("*.pkt"), *root.rglob("*.pka")])
+    capability_counts: Counter[str] = Counter()
+    capability_examples: dict[str, list[str]] = defaultdict(list)
+    device_counts: Counter[str] = Counter()
+    decode_failures: list[dict[str, str]] = []
+    for pkt_path in files:
+        rel = str(pkt_path.relative_to(root))
+        try:
+            pkt_root = decode_pkt_to_root(pkt_path)
+        except Exception as exc:
+            decode_failures.append({"path": rel, "error_type": type(exc).__name__, "message": str(exc)[:200]})
+            continue
+        try:
+            inventory = inventory_root(pkt_root)
+            for device_type, count in inventory.get("topology_summary", {}).get("device_counts", {}).items():
+                device_counts[str(device_type)] += int(count)
+        except Exception:
+            pass
+        running = "\n".join(line.text or "" for line in pkt_root.findall(".//ENGINE/RUNNINGCONFIG/LINE"))
+        for capability, pattern in LOCAL_AUDIT_PATTERNS.items():
+            if re.search(pattern, running):
+                capability_counts[capability] += 1
+                if len(capability_examples[capability]) < 5:
+                    capability_examples[capability].append(rel)
+    promotion_candidates = [
+        {
+            "capability": capability,
+            "sample_count": count,
+            "candidate_status": "local_evidence_only",
+            "next_safe_action": "Add parser/inventory/editor roundtrip proof before public readiness promotion.",
+        }
+        for capability, count in capability_counts.most_common()
+    ]
+    return {
+        "audit_version": "1.0",
+        "source_root": str(root),
+        "policy": "Local user-supplied Packet Tracer files are evidence inputs only; raw .pkt/.pka files are not public package content.",
+        "total_files": len(files),
+        "decode_success_count": len(files) - len(decode_failures),
+        "decode_fail_count": len(decode_failures),
+        "decode_failures": decode_failures[:20],
+        "detected_config_capabilities": {
+            capability: {
+                "sample_count": count,
+                "examples": capability_examples.get(capability, []),
+            }
+            for capability, count in capability_counts.most_common()
+        },
+        "top_device_types": [{"device_type": device_type, "count": count} for device_type, count in device_counts.most_common(30)],
+        "promotion_candidates": promotion_candidates,
+    }
+
+
+def local_sample_audit(root: Path, audit_out: Path | None = None) -> None:
+    payload = build_local_sample_audit(root)
+    target = audit_out or (Path("output") / "local-sample-audit.json")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps(payload, 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")
@@ -3656,8 +4093,13 @@ def main() -> None:
     parser.add_argument("--remote-provider", default="github", help="Remote search provider name (default: github)")
     parser.add_argument("--import-cache-root", help="Local cache folder used for remote search auto-imports")
     parser.add_argument("--max-remote-results", type=int, default=10, help="Maximum number of remote search results to fetch/import")
+    parser.add_argument("--remote-dry-run", action="store_true", help="Preview remote GitHub sample candidates and write an audit without downloading archives")
+    parser.add_argument("--remote-audit-out", help="Optional JSON path for the local-only remote sample audit report")
     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("--local-sample-audit-root", help="Local user-supplied Packet Tracer sample folder to audit without importing raw files")
+    parser.add_argument("--local-sample-audit-out", help="Optional JSON path for --local-sample-audit-root output")
     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")
@@ -3669,6 +4111,7 @@ def main() -> None:
     reference_roots = [Path(path) for path in (args.reference_root or [])]
     donor_roots = [Path(path) for path in (args.donor_root or [])]
     import_cache_root = Path(args.import_cache_root) if args.import_cache_root else None
+    remote_audit_out = Path(args.remote_audit_out) if args.remote_audit_out else None
 
     if args.explain_plan:
         explain_plan(
@@ -3679,6 +4122,8 @@ def main() -> None:
             remote_provider=args.remote_provider,
             import_cache_root=import_cache_root,
             max_remote_results=args.max_remote_results,
+            remote_dry_run=args.remote_dry_run,
+            remote_audit_out=remote_audit_out,
             acceptance_json_out=Path(args.acceptance_json_out) if args.acceptance_json_out else None,
         )
         return
@@ -3691,6 +4136,8 @@ def main() -> None:
             remote_provider=args.remote_provider,
             import_cache_root=import_cache_root,
             max_remote_results=args.max_remote_results,
+            remote_dry_run=args.remote_dry_run,
+            remote_audit_out=remote_audit_out,
             matrix_out=Path(args.matrix_out) if args.matrix_out else None,
             acceptance_json_out=Path(args.acceptance_json_out) if args.acceptance_json_out else None,
         )
@@ -3704,6 +4151,8 @@ def main() -> None:
             remote_provider=args.remote_provider,
             import_cache_root=import_cache_root,
             max_remote_results=args.max_remote_results,
+            remote_dry_run=args.remote_dry_run,
+            remote_audit_out=remote_audit_out,
             acceptance_json_out=Path(args.acceptance_json_out) if args.acceptance_json_out else None,
         )
         return
@@ -3725,6 +4174,12 @@ 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.local_sample_audit_root:
+        local_sample_audit(Path(args.local_sample_audit_root), Path(args.local_sample_audit_out) if args.local_sample_audit_out else None)
+        return
     if args.decode:
         if not args.xml_out:
             parser.error("--decode requires --xml-out")
@@ -3756,6 +4211,8 @@ def main() -> None:
                 remote_provider=args.remote_provider,
                 import_cache_root=import_cache_root,
                 max_remote_results=args.max_remote_results,
+                remote_dry_run=args.remote_dry_run,
+                remote_audit_out=remote_audit_out,
                 blueprint_out_path=Path(args.blueprint_out) if args.blueprint_out else None,
             )
         except PlanningError as exc: