@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/investigating-agentforce-architecture/scripts/render_architecture.py

@@ -1,1043 +0,0 @@
-"""Render architecture.md from metadata_tree.json.
-
-Phase 2 Batch 2.2: 8-section architecture document with up to 3 Mermaid
-diagrams (2 core + 1 conditional dependency graph). Generation-aware:
-classic/ReAct, classic/SequentialPlannerIntentClassifier, NGA/
-ConcurrentMultiAgentOrchestration, search/BYOP all produce distinct
-structural output on the same fixture schema.
-
-Consumers
----------
-- `main.py` phase 10 — called with the finalized tree_path + a target
-  out_path under the agent data_dir.
-- Tests — `scripts/tests/test_render_architecture.py` exercises every
-  per-generation branch and the cap/partial/cycle edge cases.
-
-Template loader
----------------
-`load_mermaid(name, **params)` mirrors `soql_loader.load_soql`'s
-substitution shape (single-pass `str.replace` on `{{KEY}}` tokens) but
-deliberately does NOT run `fs_guard.validate_api_name` on the values.
-Mermaid strings are not SQL, not a filesystem path, and not a shell
-argument — there is no injection surface downstream. We only guard
-against a *substituted* value itself containing `{{` / `}}`, which would
-confuse readers of the rendered diff if it silently chained into a
-second substitution pass; the loader logs a warning and proceeds.
-Template filenames are validated — they flow into a `Path.is_file()`
-check on disk, same traversal surface as `load_soql`.
-"""
-from __future__ import annotations
-
-import json
-import logging
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-from config import MERMAID_DIR, SKILL_ROOT, fs_guard  # fs_guard re-exported by config.py from _shared/
-
-logger = logging.getLogger(__name__)
-
-# P2.2-1: per-diagram-type node caps. Above cap -> summary placeholder.
-DEFAULT_MAX_MERMAID_NODES: Dict[str, int] = {
-    "flowchart": 200,
-    "stateDiagram": 40,
-    "sequenceDiagram": 60,
-    "graph": 100,
-}
-
-
-def _display_name(node: Dict[str, Any]) -> str:
-    """Return the node's rendered label.
-
-    For STANDARD_ACTION nodes, append the invocation-type qualifier
-    (e.g. `streamKnowledgeSearch (standardinvocableaction)`) so the
-    rendered tree distinguishes a real Salesforce-owned builtin from
-    a flow-element STANDARD_ACTION whose action-name equals its
-    invocation-target. Canonical key is `invocation_type` (schema
-    3.1); legacy `raw_invocation_type` / `raw_action_type` fall
-    back for caches built by an older parse_wave.
-    """
-    name = node.get("api_name") or node.get("element_name") or "?"
-    if node.get("kind") == "STANDARD_ACTION":
-        inv = (
-            node.get("invocation_type")
-            or node.get("raw_invocation_type")
-            or node.get("raw_action_type")
-        )
-        if inv:
-            return f"{name} ({inv})"
-    return name
-
-
-# ---------------------------------------------------------------------------
-# Template loader
-# ---------------------------------------------------------------------------
-
-
-def load_mermaid(name: str, **params: str) -> str:
-    """Read assets/mermaid/<name>.mmd and substitute {{PARAM}} values.
-
-    P2.2-1: template name is regex-validated BEFORE any filesystem access.
-    Traversal via `../../etc/...` is blocked by `fs_guard.validate_api_name`.
-    Param *values* are NOT validated — mermaid strings don't flow into
-    SOQL, REST, or filesystem paths and carry no injection surface.
-    We DO check for nested `{{`/`}}` in substituted values and log a
-    warning (the first-pass substitute call won't re-trigger, but a
-    stray `{{OTHER}}` inside a value makes the rendered markdown
-    confusing to diff). Raises `FileNotFoundError` with the template
-    name (no absolute-path leak) when the template file is missing.
-    """
-    try:
-        fs_guard.validate_api_name(name, label="mermaid_template_name")
-    except fs_guard.ValidationError as e:
-        # Template name is attacker-controlled in theory (a caller could
-        # source it from a config file). Don't leak the full SKILL_ROOT
-        # via the default FileNotFoundError message.
-        raise FileNotFoundError(
-            f"Mermaid template name rejected: {e.reason}"
-        ) from None
-
-    path = MERMAID_DIR / f"{name}.mmd"
-    if not path.is_file():
-        # Match soql_loader's SoqlTemplateNotFound hygiene — carry only
-        # the template *name*, not the absolute MERMAID_DIR path, so
-        # error text surfacing in logs doesn't disclose filesystem layout.
-        raise FileNotFoundError(f"Mermaid template not found: {name}")
-
-    template = path.read_text()
-    # the `%%` header-comment block in each template is kept
-    # verbatim in the rendered output. Mermaid treats `%%` lines as
-    # comments and ignores them at render time, and keeping them aids
-    # debuggability (rendered diff still carries the author's contract
-    # notes). Templates MUST document placeholder names as bare tokens
-    # (e.g. `NODES placeholder:`) rather than `{{NODES}}` — otherwise
-    # the single-pass `str.replace` below would substitute the comment's
-    # placeholder reference and corrupt the header.
-
-    for key, value in params.items():
-        if not isinstance(value, str):
-            # Fail loud rather than produce a literal 'None' or '[<Node>...]'
-            # in the rendered markdown.
-            raise TypeError(
-                f"Mermaid param {key!r} must be str, got {type(value).__name__}"
-            )
-        if "{{" in value or "}}" in value:
-            # Defensive log; single-pass `str.replace` still renders safely.
-            logger.warning(
-                "load_mermaid(%s): param %r contains nested placeholder tokens; "
-                "rendered output may be confusing",
-                name, key,
-            )
-        template = template.replace(f"{{{{{key}}}}}", value)
-    return template.strip()
-
-
-# ---------------------------------------------------------------------------
-# Public entry point
-# ---------------------------------------------------------------------------
-
-
-def render(
-    tree_path: Path,
-    out_path: Path,
-    *,
-    max_mermaid_nodes: Optional[Dict[str, int]] = None,
-) -> None:
-    """Read metadata_tree.json and write architecture.md to out_path.
-
-    The renderer walks the tree once to collect catalog data (topics,
-    actions, flows, apex, prompts, unresolved refs, cycles) then emits
-    8 sections in document order. Generation-aware branches live at the
-    section-level helpers below.
-
-    Note: `_render_invocation_sequence` and `_render_planner_state`
-    remain defined and tested but are no longer part of the default
-    pipeline (heuristics distrusted by reviewers as of 2026-05).
-    Uncomment the relevant `parts.append` calls below to re-enable.
-    """
-    caps = dict(DEFAULT_MAX_MERMAID_NODES)
-    if max_mermaid_nodes:
-        caps.update(max_mermaid_nodes)
-
-    tree = json.loads(Path(tree_path).read_text())
-    agent = tree.get("agent") or {}
-    generation = (agent.get("generation") or "classic").lower()
-
-    walker = _TreeWalker(tree)
-    walker.walk()
-
-    parts: List[str] = []
-    parts.append(_render_header(tree, agent))
-    parts.append(_render_anatomy_summary(tree, walker))
-    # parts.append(_render_invocation_sequence(tree, agent, walker, caps))
-    # ^ Disabled 2026-05: heuristic over-simplified real orchestration
-    # paths. Function + template retained; re-enable by uncommenting.
-    parts.append(_render_action_tree(tree, walker, caps))
-    parts.append(_render_topic_anatomy(walker))
-    parts.append(_render_action_catalog(walker))
-    # parts.append(_render_planner_state(agent, generation, caps))
-    # ^ Disabled 2026-05: generation-specific state diagram added more
-    # noise than signal in review. Function + template retained; re-enable
-    # by uncommenting.
-    parts.append(_render_data_flow(tree, walker, caps))
-    parts.append(_render_artifact_catalogs(walker))
-    parts.append(_render_unresolved(tree, walker))
-
-    # Conditional dependency-graph section — emitted only if there are
-    # unresolved refs or cycles detected. Not counted as one of the 9.
-    if tree.get("_unresolved") or walker.cycles:
-        parts.append(_render_dependency_graph(tree, walker, caps))
-
-    Path(out_path).write_text("\n\n".join(parts).rstrip() + "\n")
-
-
-# ---------------------------------------------------------------------------
-# Tree walker — single pass over the tree to collect catalog data
-# ---------------------------------------------------------------------------
-
-
-class _TreeWalker:
-    """Collects nodes, edges, topics, cycles in a single depth-first pass.
-
-    P2.2-1: BFS-equivalent visit budget already enforced by parse_wave
-    (MAX_BFS_DEPTH=5), so we don't need a depth cap here — the tree is
-    already bounded. We DO guard against a malformed tree with a
-    self-referential `children` ring by tracking id()'s.
-    """
-
-    def __init__(self, tree: Dict[str, Any]) -> None:
-        self.tree = tree
-        self.topics: List[Dict[str, Any]] = []
-        # actions = top-level children of each topic plus planner-level actions
-        self.actions: List[Dict[str, Any]] = []
-        self.flows: Dict[str, Dict[str, Any]] = {}
-        self.apex: Dict[str, Dict[str, Any]] = {}
-        self.prompts: Dict[str, Dict[str, Any]] = {}
-        self.standard_actions: Dict[str, Dict[str, Any]] = {}
-        # tree edges: parent api_name -> list of child api_name
-        self.edges: List[Tuple[str, str, str]] = []  # (parent, child, kind)
-        # fan-out map for summary-placeholder top-5
-        self.fanout: Dict[str, int] = {}
-        # cycle-back annotations: list of (node_label, cycle_back_to)
-        self.cycles: List[Tuple[str, str]] = []
-        # depth-cap truncations (subset of self.cycles surfaced by
-        # the unified _truncated annotation with reason="max-depth").
-        # Kept separate so downstream renderers can distinguish the two
-        # truncation classes without re-walking the tree.
-        self.depth_capped: List[Tuple[str, str]] = []
-        self._seen_py_ids: set[int] = set()
-
-    def walk(self) -> None:
-        root = self.tree.get("root") or {}
-        for child in root.get("children") or []:
-            self._visit(child, parent_label=root.get("api_name") or "ROOT",
-                        topic=None)
-
-    def _visit(
-        self,
-        node: Dict[str, Any],
-        *,
-        parent_label: str,
-        topic: Optional[Dict[str, Any]],
-    ) -> None:
-        if not isinstance(node, dict):
-            return
-        nid = id(node)
-        if nid in self._seen_py_ids:
-            return
-        self._seen_py_ids.add(nid)
-
-        kind = node.get("kind") or "UNKNOWN"
-        api_name = node.get("api_name") or node.get("element_name") or ""
-
-        # Top-level children of a BOT_DEFINITION with kind TOPIC feed the
-        # topic list. Non-topic top-level children (planner-level actions)
-        # attach to a synthetic `_plannerActions` bucket.
-        if kind == "TOPIC" and topic is None:
-            topic_rec = {
-                "api_name": api_name,
-                "label": node.get("master_label") or api_name,
-                "actions": [],
-                "raw": node,
-            }
-            self.topics.append(topic_rec)
-            topic = topic_rec
-        elif topic is None and kind == "GEN_AI_FUNCTION":
-            # plannerAction (classic Sequential / NGA) — no parent topic.
-            self.actions.append({
-                "kind": kind,
-                "api_name": api_name,
-                "topic": None,
-                "raw": node,
-            })
-        elif topic is not None and kind == "GEN_AI_FUNCTION":
-            action_rec = {
-                "kind": kind,
-                "api_name": api_name,
-                "topic": topic["api_name"],
-                "raw": node,
-            }
-            topic["actions"].append(action_rec)
-            self.actions.append(action_rec)
-
-        # Per-kind catalog buckets. We key on api_name; dupes collapse.
-        if kind == "FLOW" and api_name:
-            self.flows.setdefault(api_name, node)
-        elif kind == "APEX" and api_name:
-            self.apex.setdefault(api_name, node)
-        elif kind == "PROMPT_TEMPLATE" and api_name:
-            self.prompts.setdefault(api_name, node)
-        elif kind == "STANDARD_ACTION" and api_name:
-            self.standard_actions.setdefault(api_name, node)
-
-        # per-node truncation annotation (cycle OR depth-cap).
-        # Prefer the unified `_truncated` sub-object; fall back to the
-        # deprecated `_cycle_back_to` string for trees produced by
-        # older parse_wave versions.
-        trunc = node.get("_truncated") or {}
-        cycle_to = trunc.get("target") or node.get("_cycle_back_to")
-        reason = trunc.get("reason") or ("cycle" if cycle_to else None)
-        if cycle_to:
-            self.cycles.append((api_name or parent_label, str(cycle_to)))
-            # Optional: downstream renderers may want to distinguish
-            # the two truncation classes. We keep that open by stashing
-            # `reason` when present.
-            if reason and reason != "cycle":
-                self.depth_capped.append((api_name or parent_label, str(cycle_to)))
-
-        # Edge + fanout bookkeeping
-        children = node.get("children") or []
-        if api_name and parent_label and parent_label != api_name:
-            self.edges.append((parent_label, api_name, kind))
-            self.fanout[parent_label] = self.fanout.get(parent_label, 0) + 1
-
-        for child in children:
-            self._visit(child, parent_label=api_name or parent_label,
-                        topic=topic)
-
-    # ---- helpers -----------------------------------------------------
-
-    def total_nodes(self) -> int:
-        counts = self.tree.get("_kind_counts") or {}
-        return sum(counts.values()) or self.tree.get("node_count", 0)
-
-    def top_fanout(self, n: int = 5) -> List[Tuple[str, int]]:
-        return sorted(self.fanout.items(), key=lambda kv: (-kv[1], kv[0]))[:n]
-
-
-# ---------------------------------------------------------------------------
-# Section renderers
-# ---------------------------------------------------------------------------
-
-
-def _md_escape(value: Any) -> str:
-    if value is None:
-        return "-"
-    s = str(value)
-    # Escape the two characters that break markdown tables.
-    return s.replace("|", r"\|").replace("\n", " ")
-
-
-def _render_header(tree: Dict[str, Any], agent: Dict[str, Any]) -> str:
-    # P2.2-1: section 1 — kv table. No input is trusted (agent fields
-    # come from SOQL + metadata retrieve), but we escape pipes anyway.
-    lines = ["# Architecture — `{}` `{}`".format(
-        _md_escape(agent.get("api_name") or "?"),
-        _md_escape(agent.get("version") or "?"),
-    )]
-    lines.append("")
-    lines.append("| Field | Value |")
-    lines.append("|---|---|")
-    rows = [
-        ("Master label", agent.get("master_label")),
-        ("Description", agent.get("description")),
-        ("Agent type", agent.get("agent_type")),
-        ("Type", agent.get("type")),
-        ("Template", agent.get("agent_template")),
-        ("Bot source", agent.get("bot_source")),
-        ("Generation", agent.get("generation")),
-        ("Planner name", agent.get("planner_name")),
-        ("Planner type", agent.get("planner_type")),
-        ("Bot id", agent.get("bot_id")),
-        ("Schema version", tree.get("_schema_version")),
-    ]
-    for label, value in rows:
-        lines.append(f"| {label} | {_md_escape(value)} |")
-    return "\n".join(lines)
-
-
-def _render_anatomy_summary(tree: Dict[str, Any], walker: _TreeWalker) -> str:
-    # P2.2-1: section 2 renders health callout when _partial=true.
-    kc = tree.get("_kind_counts") or {}
-    lines = ["## 2. Anatomy summary", ""]
-    topic_count = kc.get("TOPIC", len(walker.topics))
-    action_count = kc.get("GEN_AI_FUNCTION", len(walker.actions))
-    flow_count = kc.get("FLOW", len(walker.flows))
-    apex_count = kc.get("APEX", len(walker.apex))
-    prompt_count = kc.get("PROMPT_TEMPLATE", len(walker.prompts))
-    stdaction_count = kc.get("STANDARD_ACTION", len(walker.standard_actions))
-
-    lines.append(
-        "Agent exposes **{} topics** and **{} declared actions** "
-        "spanning **{} flows**, **{} apex classes**, **{} prompt templates**, "
-        "and **{} standard actions**. Tree depth is {} across {} total nodes.".format(
-            topic_count, action_count, flow_count, apex_count,
-            prompt_count, stdaction_count,
-            tree.get("depth", "?"), walker.total_nodes(),
-        )
-    )
-
-    if tree.get("_partial"):
-        pending = tree.get("_pending_fetches") or {}
-        pending_count = sum(len(v) for v in pending.values())
-        reason = tree.get("_partial_reason") or "unspecified"
-        lines.append("")
-        lines.append("> **Health: PARTIAL.** The tree did not fully converge.")
-        lines.append(f"> - Reason: `{_md_escape(reason)}`")
-        lines.append(f"> - Pending fetches: {pending_count}")
-        if pending:
-            for key, items in pending.items():
-                if items:
-                    lines.append(
-                        f">   - `{_md_escape(key)}`: {len(items)} outstanding"
-                    )
-
-    # P2.2-1: health callout when planner_name is missing.
-    agent = tree.get("agent") or {}
-    if not agent.get("planner_name"):
-        lines.append("")
-        lines.append(
-            "> **Health: WARN.** `planner_name` missing from agent metadata — "
-            "downstream sections render best-effort from tree shape alone."
-        )
-
-    if tree.get("_unresolved"):
-        lines.append("")
-        lines.append(
-            "> **Health: WARN.** {} unresolved references — see section 8.".format(
-                len(tree["_unresolved"])
-            )
-        )
-
-    return "\n".join(lines)
-
-
-def _render_invocation_sequence(
-    tree: Dict[str, Any],
-    agent: Dict[str, Any],
-    walker: _TreeWalker,
-    caps: Dict[str, int],
-) -> str:
-    # P2.2-1: section 3 — sequenceDiagram with cap check.
-    lines = ["## 3. Invocation sequence", ""]
-    generation = (agent.get("generation") or "classic").lower()
-
-    participants = ["participant User", "    participant Planner"]
-    if generation == "nga":
-        participants.append("    participant Orchestrator")
-        participants.append("    participant SubAgent")
-    else:
-        participants.append("    participant TopicClassifier")
-    participants.append("    participant ActionExecutor")
-
-    messages: List[str] = []
-    messages.append("    User->>+Planner: utterance")
-    if generation == "nga":
-        messages.append("    Planner->>+Orchestrator: plan")
-        messages.append("    Orchestrator->>+SubAgent: dispatch (par/and)")
-        messages.append("    SubAgent->>+ActionExecutor: invoke action")
-        messages.append("    ActionExecutor-->>-SubAgent: result")
-        messages.append("    SubAgent-->>-Orchestrator: subresult")
-        messages.append("    Orchestrator-->>-Planner: aggregated")
-    elif (agent.get("planner_type") or "").endswith("SequentialPlannerIntentClassifier"):
-        messages.append("    Planner->>+ActionExecutor: direct intent->action")
-        messages.append("    ActionExecutor-->>-Planner: result")
-    else:
-        # Classic ReAct — one round-trip per topic (sampled at :5 for
-        # readability). The cap check below counts the ACTUAL rendered
-        # messages, so a 30-topic bot whose ReAct branch only emits 12
-        # lines is correctly NOT truncated.
-        for topic in walker.topics[:5]:  # sample for readability
-            label = _md_escape(topic["api_name"])
-            messages.append(f"    Planner->>+TopicClassifier: classify → {label}")
-            messages.append(f"    TopicClassifier-->>-Planner: topic={label}")
-        messages.append("    Planner->>+ActionExecutor: invoke action")
-        messages.append("    ActionExecutor-->>-Planner: result")
-
-    messages.append("    Planner-->>-User: response")
-
-    # cap against ACTUAL rendered message count, not a
-    # potential / over-estimated figure. The prior implementation used
-    # `2 * len(walker.topics) + len(walker.actions) + 2`, which false-
-    # tripped on large bots because the ReAct branch only emits
-    # `2 * min(len(walker.topics), 5) + 2` lines (topics[:5] sampling).
-    # The rendered-list length is the single source of truth.
-    msg_count = len(messages)
-    if msg_count > caps.get("sequenceDiagram", 60):
-        lines.append(_truncation_placeholder(
-            kind="sequenceDiagram", total=msg_count,
-            cap=caps["sequenceDiagram"],
-            top_fanout=walker.top_fanout(5),
-            catalog_pointer="section 5 (action catalog)",
-        ))
-        return "\n".join(lines)
-
-    rendered = load_mermaid(
-        "invocation_sequence",
-        PARTICIPANTS="\n".join(participants).lstrip(),
-        MESSAGES="\n".join(messages).lstrip(),
-    )
-    lines.append("```mermaid")
-    lines.append(rendered)
-    lines.append("```")
-    return "\n".join(lines)
-
-
-def _render_action_tree(
-    tree: Dict[str, Any],
-    walker: _TreeWalker,
-    caps: Dict[str, int],
-) -> str:
-    # P2.2-1: section 3 — flowchart + subgraphs per topic; cycle back-edges.
-    lines = ["## 3. Action tree", ""]
-    total_nodes = walker.total_nodes()
-    if total_nodes > caps.get("flowchart", 200):
-        lines.append(_truncation_placeholder(
-            kind="flowchart", total=total_nodes,
-            cap=caps["flowchart"],
-            top_fanout=walker.top_fanout(5),
-            catalog_pointer="section 5 (action catalog) and section 7 (artifact catalogs)",
-        ))
-        lines.append("")
-        lines.append(_render_action_tree_ascii(walker))
-        return "\n".join(lines)
-
-    # Build subgraphs and edges
-    subgraphs: List[str] = []
-    for topic in walker.topics:
-        sg_id = _safe_id(topic["api_name"])
-        sg_lines = [f"    subgraph {sg_id}[\"{_md_escape(topic['label'])}\"]"]
-        for action in topic["actions"]:
-            node_id = _safe_id(action["api_name"])
-            label = _display_name(action.get("raw") or action)
-            sg_lines.append(f"        {node_id}[\"{_md_escape(label)}\"]")
-        sg_lines.append("    end")
-        subgraphs.append("\n".join(sg_lines))
-
-    # Planner-level actions (no topic)
-    planner_actions = [a for a in walker.actions if a.get("topic") is None]
-    if planner_actions:
-        sg_lines = ["    subgraph _plannerActions[\"(plannerActions)\"]"]
-        for action in planner_actions:
-            node_id = _safe_id(action["api_name"])
-            label = _display_name(action.get("raw") or action)
-            sg_lines.append(f"        {node_id}[\"{_md_escape(label)}\"]")
-        sg_lines.append("    end")
-        subgraphs.append("\n".join(sg_lines))
-
-    edges: List[str] = []
-    for parent, child, kind in walker.edges:
-        pid = _safe_id(parent)
-        cid = _safe_id(child)
-        edges.append(f"    {pid} --> {cid}")
-
-    # Cycle back-edges (dotted)
-    for node_label, cycle_to in walker.cycles:
-        nid = _safe_id(node_label)
-        tid = _safe_id(cycle_to)
-        edges.append(f"    {nid} -.->|cycle_back_to: {_md_escape(cycle_to)}| {tid}")
-
-    rendered = load_mermaid(
-        "action_tree",
-        SUBGRAPHS="\n\n".join(subgraphs).lstrip() if subgraphs else "%% no topics",
-        EDGES="\n".join(edges).lstrip() if edges else "%% no edges",
-    )
-    lines.append("```mermaid")
-    lines.append(rendered)
-    lines.append("```")
-    lines.append("")
-    lines.append("**ASCII appendix**")
-    lines.append("")
-    lines.append("```")
-    lines.append(_render_action_tree_ascii(walker))
-    lines.append("```")
-    return "\n".join(lines)
-
-
-def _render_action_tree_ascii(walker: _TreeWalker) -> str:
-    out: List[str] = []
-    root = walker.tree.get("root") or {}
-    out.append(f"{root.get('api_name', 'ROOT')} ({root.get('kind', 'BOT_DEFINITION')})")
-    _ascii_recurse(root.get("children") or [], out, depth=1, seen=set())
-    return "\n".join(out)
-
-
-def _ascii_recurse(
-    children: List[Dict[str, Any]],
-    out: List[str],
-    depth: int,
-    seen: set[int],
-) -> None:
-    for child in children:
-        if not isinstance(child, dict):
-            continue
-        nid = id(child)
-        if nid in seen:
-            continue
-        seen.add(nid)
-        name = _display_name(child)
-        kind = child.get("kind") or "?"
-        # surface BOTH cycle AND max-depth truncation in the ASCII
-        # tree view. Prefer `_truncated["reason"]`; fall back to the
-        # legacy `_cycle_back_to` string (older parse_wave output).
-        trunc = child.get("_truncated") or {}
-        if trunc.get("reason") == "max-depth":
-            marker = " [depth-capped]"
-        elif trunc.get("reason") == "cycle" or child.get("_cycle_back_to"):
-            marker = " [cycle]"
-        else:
-            marker = ""
-        out.append(f"{'  ' * depth}├── [{kind}] {name}{marker}")
-        grand = child.get("children") or []
-        if grand:
-            _ascii_recurse(grand, out, depth + 1, seen)
-
-
-def _render_topic_anatomy(walker: _TreeWalker) -> str:
-    # P2.2-1: section 4 — H3 per topic + kv list. Empty-case: 0 topics is
-    # valid for SequentialPlannerIntentClassifier.
-    lines = ["## 4. Topic anatomy", ""]
-    if not walker.topics:
-        lines.append("_No topics defined (planner exposes actions directly)._")
-        return "\n".join(lines)
-    for topic in walker.topics:
-        lines.append(f"### `{_md_escape(topic['api_name'])}`")
-        lines.append("")
-        lines.append(f"- Label: {_md_escape(topic['label'])}")
-        lines.append(f"- Action count: {len(topic['actions'])}")
-        if topic["actions"]:
-            lines.append("- Actions:")
-            for action in topic["actions"]:
-                label = _display_name(action.get("raw") or action)
-                lines.append(f"  - `{_md_escape(label)}`")
-        lines.append("")
-    return "\n".join(lines).rstrip()
-
-
-def _render_action_catalog(walker: _TreeWalker) -> str:
-    # P2.2-1: section 5 — markdown table of actions.
-    lines = ["## 5. Action catalog", ""]
-    if not walker.actions:
-        lines.append("_No actions declared._")
-        return "\n".join(lines)
-    lines.append("| Action | Topic | Unwraps to |")
-    lines.append("|---|---|---|")
-    for action in walker.actions:
-        raw = action.get("raw") or {}
-        unwrap = raw.get("unwraps_to") or {}
-        unwrap_str = "-"
-        if unwrap:
-            unwrap_str = "{} `{}`".format(
-                unwrap.get("kind", "?"),
-                _display_name(unwrap),
-            )
-        lines.append("| `{}` | {} | {} |".format(
-            _md_escape(action["api_name"]),
-            _md_escape(action.get("topic") or "(plannerAction)"),
-            _md_escape(unwrap_str),
-        ))
-    return "\n".join(lines)
-
-
-def _planner_state_for_generation(
-    agent: Dict[str, Any], generation: str,
-) -> Tuple[List[str], List[str]]:
-    """Return (states, transitions) for the planner state machine."""
-    planner_type = (agent.get("planner_type") or "").lower()
-    if generation == "nga":
-        states = [
-            "[*] --> Planning",
-            "    state Planning",
-            "    state Orchestration {",
-            "        direction LR",
-            "        [*] --> Dispatch",
-            "        Dispatch --> SubAgentA",
-            "        Dispatch --> SubAgentB",
-            "        --",
-            "        SubAgentA --> Aggregate",
-            "        SubAgentB --> Aggregate",
-            "    }",
-            "    state Respond",
-        ]
-        transitions = [
-            "    Planning --> Orchestration: par/and dispatch",
-            "    Orchestration --> Respond: aggregated",
-            "    Respond --> [*]",
-        ]
-        return states, transitions
-    if planner_type.endswith("sequentialplannerintentclassifier"):
-        states = [
-            "[*] --> Classify",
-            "    state Classify",
-            "    state Execute",
-            "    state Respond",
-        ]
-        transitions = [
-            "    Classify --> Execute: intent",
-            "    Execute --> Respond: result",
-            "    Respond --> [*]",
-        ]
-        return states, transitions
-    # Default: classic ReAct
-    states = [
-        "[*] --> Thought",
-        "    state Thought",
-        "    state Action",
-        "    state Observation",
-        "    state Respond",
-    ]
-    transitions = [
-        "    Thought --> Action: pick tool",
-        "    Action --> Observation: tool result",
-        "    Observation --> Thought: more reasoning",
-        "    Observation --> Respond: done",
-        "    Respond --> [*]",
-    ]
-    return states, transitions
-
-
-def _render_planner_state(
-    agent: Dict[str, Any],
-    generation: str,
-    caps: Dict[str, int],
-) -> str:
-    # P2.2-1: section 6 — stateDiagram-v2 with generation-aware branches.
-    lines = ["## 6. Planner state machine", ""]
-
-    if generation in ("search", "byop"):
-        lines.append(
-            "_Custom planner — structure depends on the planner's Apex class_ "
-            f"(`{_md_escape(agent.get('planner_type') or '?')}`). State "
-            "diagram skipped; see section 7 for the backing Apex class body."
-        )
-        return "\n".join(lines)
-
-    states, transitions = _planner_state_for_generation(agent, generation)
-    total = len(states) + len(transitions)
-    if total > caps.get("stateDiagram", 40):
-        lines.append(_truncation_placeholder(
-            kind="stateDiagram", total=total,
-            cap=caps["stateDiagram"],
-            top_fanout=[],
-            catalog_pointer="section 7 (artifact catalogs)",
-        ))
-        return "\n".join(lines)
-
-    rendered = load_mermaid(
-        "planner_state",
-        STATES="\n".join(states).lstrip(),
-        TRANSITIONS="\n".join(transitions).lstrip(),
-    )
-    lines.append("```mermaid")
-    lines.append(rendered)
-    lines.append("```")
-    return "\n".join(lines)
-
-
-def _render_data_flow(
-    tree: Dict[str, Any],
-    walker: _TreeWalker,
-    caps: Dict[str, int],
-) -> str:
-    # P2.2-1: section 6 — flowchart LR with labeled param edges.
-    lines = ["## 6. Data flow / context propagation", ""]
-
-    # Build node list — User, Planner, each topic, each action.
-    nodes: List[str] = ["    User([User utterance])", "    Planner[Planner]"]
-    for topic in walker.topics:
-        nodes.append(f"    {_safe_id(topic['api_name'])}[Topic: {_md_escape(topic['api_name'])}]")
-
-    edges: List[str] = ["    User --> Planner"]
-    for topic in walker.topics:
-        edges.append(f"    Planner --> {_safe_id(topic['api_name'])}")
-        for action in topic["actions"]:
-            label = _display_name(action.get("raw") or action)
-            nodes.append(
-                f"    {_safe_id(action['api_name'])}[[Action: {_md_escape(label)}]]"
-            )
-            # Labeled edge when the planner attr metadata declares a
-            # parameter hand-off; fall back to a bare edge otherwise.
-            attr = (action.get("raw") or {}).get("planner_attr") or {}
-            var_name = attr.get("variable_name") or attr.get("name")
-            var_type = attr.get("data_type") or attr.get("type")
-            if var_name:
-                label = _md_escape(var_name)
-                if var_type:
-                    label = f"{label}: {_md_escape(var_type)}"
-                edges.append(
-                    f"    {_safe_id(topic['api_name'])} -->|{label}| "
-                    f"{_safe_id(action['api_name'])}"
-                )
-            else:
-                edges.append(
-                    f"    {_safe_id(topic['api_name'])} --> "
-                    f"{_safe_id(action['api_name'])}"
-                )
-
-    total = len(nodes) + len(edges)
-    if total > caps.get("flowchart", 200):
-        lines.append(_truncation_placeholder(
-            kind="flowchart", total=total,
-            cap=caps["flowchart"],
-            top_fanout=walker.top_fanout(5),
-            catalog_pointer="section 7 (artifact catalogs)",
-        ))
-        return "\n".join(lines)
-
-    rendered = load_mermaid(
-        "data_flow",
-        NODES="\n".join(nodes).lstrip(),
-        EDGES="\n".join(edges).lstrip(),
-    )
-    lines.append("```mermaid")
-    lines.append(rendered)
-    lines.append("```")
-    return "\n".join(lines)
-
-
-def _render_artifact_catalogs(walker: _TreeWalker) -> str:
-    # P2.2-1: section 7 — H3 per flow / apex / prompt + signature.
-    lines = ["## 7. Flow / Apex / Prompt catalogs", ""]
-
-    if walker.flows:
-        lines.append("### Flows")
-        lines.append("")
-        for name in sorted(walker.flows):
-            node = walker.flows[name]
-            sig = node.get("signature") or node.get("_signature")
-            # Gap 2 fix (2026-05-05): main._stamp_signatures stamps
-            # `_signature_reason` on flows whose body we can't retrieve
-            # (managed package, no active version, metadata fetch miss).
-            # Surface the reason so the rendered markdown distinguishes
-            # a known limitation from a silent hole.
-            reason = node.get("_signature_reason")
-            lines.append(f"#### `{_md_escape(name)}`")
-            lines.append("")
-            if sig:
-                lines.append("```")
-                lines.append(str(sig))
-                lines.append("```")
-            elif reason:
-                lines.append(f"_Signature not captured — {_md_escape(reason)}._")
-            else:
-                lines.append("_Signature not captured._")
-            lines.append("")
-
-    if walker.apex:
-        lines.append("### Apex classes")
-        lines.append("")
-        for name in sorted(walker.apex):
-            node = walker.apex[name]
-            sig = node.get("signature") or node.get("_signature")
-            lines.append(f"#### `{_md_escape(name)}`")
-            lines.append("")
-            if sig:
-                lines.append("```")
-                lines.append(str(sig))
-                lines.append("```")
-            else:
-                lines.append("_Signature not captured._")
-            lines.append("")
-
-    if walker.prompts:
-        lines.append("### Prompt templates")
-        lines.append("")
-        for name in sorted(walker.prompts):
-            node = walker.prompts[name]
-            sig = node.get("signature") or node.get("_signature")
-            prompt_type = node.get("prompt_type")
-            # Gap C (2026-05-05): retrieve_prompt_templates stamps
-            # master_label / content / inputs / _body_available onto
-            # each PROMPT_TEMPLATE leaf. Emit the real body when
-            # available; fall back to the stub only when `_body_available`
-            # is explicitly False (retrieve failed / not requested) AND
-            # there's no signature/type to show.
-            master_label = node.get("master_label")
-            content = node.get("content")
-            inputs = node.get("inputs") or []
-            body_available = node.get("_body_available")
-            lines.append(f"#### `{_md_escape(name)}`")
-            lines.append("")
-            if master_label:
-                lines.append(f"_Label: {_md_escape(master_label)}_")
-                lines.append("")
-            if prompt_type:
-                lines.append(f"- Type: `{_md_escape(prompt_type)}`")
-            if inputs:
-                lines.append("**Inputs**:")
-                for inp in inputs:
-                    if not isinstance(inp, dict):
-                        continue
-                    iname = inp.get("name") or "?"
-                    itype = inp.get("dataType")
-                    if itype:
-                        lines.append(
-                            f"- `{_md_escape(iname)}`: "
-                            f"`{_md_escape(itype)}`"
-                        )
-                    else:
-                        lines.append(f"- `{_md_escape(iname)}`")
-                lines.append("")
-            if content:
-                lines.append("```text")
-                lines.append(str(content))
-                lines.append("```")
-            elif sig:
-                lines.append("```")
-                lines.append(str(sig))
-                lines.append("```")
-            if (
-                not content and not sig and not prompt_type
-                and not master_label and not inputs
-            ):
-                if body_available is False:
-                    lines.append("_Body not retrieved._")
-                else:
-                    lines.append("_Details not captured._")
-            lines.append("")
-
-    if not (walker.flows or walker.apex or walker.prompts):
-        lines.append("_No backing artifacts in tree._")
-
-    return "\n".join(lines).rstrip()
-
-
-def _render_unresolved(tree: Dict[str, Any], walker: _TreeWalker) -> str:
-    # P2.2-1: section 8 — unresolved refs + artifact pointers.
-    lines = ["## 8. Unresolved refs + artifact pointers", ""]
-    unresolved = tree.get("_unresolved") or []
-    if unresolved:
-        lines.append("> **{} unresolved refs.**".format(len(unresolved)))
-        lines.append("")
-        lines.append("| Kind | Api name | Reason |")
-        lines.append("|---|---|---|")
-        for ref in unresolved:
-            lines.append("| {} | `{}` | {} |".format(
-                _md_escape(ref.get("kind") or "?"),
-                _md_escape(ref.get("api_name") or "?"),
-                _md_escape(ref.get("reason") or "?"),
-            ))
-    else:
-        lines.append("_No unresolved references._")
-    lines.append("")
-    lines.append("### Artifact pointers")
-    lines.append("")
-    lines.append(
-        "- Full tree JSON: same directory as this file (`metadata_tree.json`)"
-    )
-    lines.append("- Build manifest: cache dir / `manifest.json`")
-    return "\n".join(lines)
-
-
-def _render_dependency_graph(
-    tree: Dict[str, Any],
-    walker: _TreeWalker,
-    caps: Dict[str, int],
-) -> str:
-    # P2.2-1: conditional — render only on unresolved or cycles.
-    lines = ["## Dependency graph (conditional)", ""]
-    unresolved = tree.get("_unresolved") or []
-
-    nodes: List[str] = []
-    edges: List[str] = []
-    seen: set[str] = set()
-
-    def add_node(label: str, unresolved_flag: bool) -> None:
-        nid = _safe_id(label)
-        if nid in seen:
-            return
-        seen.add(nid)
-        suffix = ":::unresolved" if unresolved_flag else ""
-        nodes.append(f"    {nid}[{_md_escape(label)}]{suffix}")
-
-    for parent, child, _ in walker.edges:
-        add_node(parent, False)
-        add_node(child, False)
-        edges.append(f"    {_safe_id(parent)} --> {_safe_id(child)}")
-
-    for ref in unresolved:
-        name = ref.get("api_name") or "?"
-        add_node(name, True)
-
-    for node_label, cycle_to in walker.cycles:
-        add_node(node_label, False)
-        add_node(cycle_to, False)
-        edges.append(
-            f"    {_safe_id(node_label)} -.->|cycle| {_safe_id(cycle_to)}"
-        )
-
-    total = len(nodes)
-    if total > caps.get("graph", 100):
-        lines.append(_truncation_placeholder(
-            kind="graph", total=total,
-            cap=caps["graph"],
-            top_fanout=walker.top_fanout(5),
-            catalog_pointer="section 8 (unresolved refs)",
-        ))
-        return "\n".join(lines)
-
-    rendered = load_mermaid(
-        "dependency_graph",
-        NODES="\n".join(nodes).lstrip() if nodes else "%% no nodes",
-        EDGES="\n".join(edges).lstrip() if edges else "%% no edges",
-    )
-    lines.append("```mermaid")
-    lines.append(rendered)
-    lines.append("```")
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _truncation_placeholder(
-    *,
-    kind: str,
-    total: int,
-    cap: int,
-    top_fanout: List[Tuple[str, int]],
-    catalog_pointer: str,
-) -> str:
-    # P2.2-1: explicit visual placeholder. Mentions the diagram kind, the
-    # over-cap count, and points at the catalog section.
-    lines = [
-        f"> **[diagram truncated: {kind} — {total} elements exceed cap of {cap}]**",
-    ]
-    if top_fanout:
-        lines.append(">")
-        lines.append("> Top 5 nodes by fan-out:")
-        for name, count in top_fanout:
-            lines.append(f"> - `{_md_escape(name)}` ({count})")
-    lines.append(">")
-    lines.append(f"> See {catalog_pointer} for the full listing.")
-    return "\n".join(lines)
-
-
-def _safe_id(value: str) -> str:
-    """Return a mermaid-safe identifier. Mermaid node ids must be
-    alphanumeric + underscore; anything else breaks the parser."""
-    if not value:
-        return "n_empty"
-    out = []
-    for ch in str(value):
-        if ch.isalnum() or ch == "_":
-            out.append(ch)
-        else:
-            out.append("_")
-    # Prefix digit-leading ids so they don't collide with mermaid syntax.
-    result = "".join(out)
-    if result and result[0].isdigit():
-        result = f"n_{result}"
-    return result or "n_empty"