@salesforce/afv-skills 1.14.0 → 1.16.0

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

@@ -0,0 +1,13 @@
+"""BFS graph builder — walks the cross-type reference graph.
+
+ (visited keys = (kind, canonical_name) tuples) +  (MAX_DEPTH=5 cap
+→ _partial + PARTIAL_OK) land in Batches 2 and 3.
+"""
+from __future__ import annotations
+
+
+def build_fetch_graph() -> dict:
+    """TODO  + BFS with per-kind visited tuples, cycle-safe,
+    MAX_DEPTH cap surfaces as _partial=true in the tree.
+    """
+    raise NotImplementedError("build_fetch_graph implements in P0 Batches 2+3")

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

@@ -0,0 +1,242 @@
+"""sf CLI recipe loader — reads assets/cli/*.yaml, runs argv via subprocess.
+
+Security: YAML recipes are loaded via yaml.safe_load only; yaml.load is banned.
+PyYAML's `yaml.load` deserializes arbitrary Python objects (including
+constructor-injected code in some tags) and must never run on attacker-reachable
+YAML. The recipes live inside this repo and are author-controlled, but we
+still use `safe_load` as defence in depth — a compromised dist/ or a botched
+copy-paste can't escalate to code execution.
+
+the `_SAFE_LOADER` module-level binding is THE loader used everywhere
+in this module; tests assert its identity against `yaml.safe_load`.
+
+every stringification of a subprocess.CalledProcessError or related
+exception is routed through `rest_client.redact_error` so stderr containing
+an access token (rare but observed on some `sf` failure paths) cannot leak
+into logs or RESULT blocks.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+from config import CLI_DIR
+# hoisted `redact_text` to module-top alongside
+# `redact_error`. Previously `_redact_subprocess_stderr` performed a lazy
+# import of the module-private `_redact_text` on every call, which (a)
+# tied this module to a name that could be renamed silently and (b) meant
+# an ImportError from rest_client would surface only at redaction time —
+# possibly in a frame whose locals held the raw, un-redacted stderr.
+# Hoisting is safe: rest_client does not import sf_cli (no cycle).
+from rest_client import redact_error, redact_text
+
+# the ONE allowed loader for this module. Test asserts identity.
+# NEVER change this to yaml.load (which can construct arbitrary Python
+# objects via tag hooks).
+_SAFE_LOADER = yaml.safe_load
+
+
+class AuthRequired(RuntimeError):
+    """sf CLI returned a known auth-failure pattern.
+
+    Carries a redacted stderr snippet — any bearer token in stderr is scrubbed
+    via redact_error before reaching this message.
+    """
+
+
+class SfCliError(RuntimeError):
+    """sf CLI returned non-zero exit or JSON status != 0.
+
+    Message is redacted  before construction.
+    """
+
+
+def _load_recipe(name: str) -> Dict[str, Any]:
+    """Read and parse a CLI recipe file with yaml.safe_load.
+
+    _SAFE_LOADER is bound to yaml.safe_load at module top; using it
+    here (instead of `yaml.safe_load` directly) makes the identity testable
+    and gives a single point to review if the loader ever changes.
+    """
+    path = CLI_DIR / f"{name}.yaml"
+    with path.open("r", encoding="utf-8") as fh:
+        recipe = _SAFE_LOADER(fh)
+    if not isinstance(recipe, dict):
+        raise SfCliError(
+            f"recipe {name!r} did not parse to a mapping (got {type(recipe).__name__})"
+        )
+    return recipe
+
+
+def _sub(arg: str, params: Dict[str, str]) -> str:
+    """Substitute {{KEY}} placeholders in a single argv element.
+
+    Input validation: `params` values are expected to be already-validated
+    strings (SKILL.md phase 1 runs fs_guard on every user-supplied input).
+    We do not revalidate here because argv substitution is shell-escape-safe
+    by construction — subprocess.run with a list argv never invokes a shell.
+    """
+    out = arg
+    for key, value in params.items():
+        out = out.replace(f"{{{{{key}}}}}", value)
+    return out
+
+
+def _parse_stdout_json(stdout: str) -> Dict[str, Any]:
+    """Parse sf CLI's --json stdout.
+
+    sf CLI emits `{"status": 0, "result": {...}}` on success; malformed
+    stdout (e.g. when the CLI crashes before JSON serialization) raises
+    SfCliError with a redacted message.
+    """
+    try:
+        return json.loads(stdout)
+    except json.JSONDecodeError as e:
+        # stdout could in theory contain a token on some crash paths;
+        # redact before surfacing.
+        raise SfCliError(
+            f"sf CLI stdout is not JSON: {redact_error(e)}"
+        ) from None
+
+
+_AUTH_LINE_PREFIX_RE = re.compile(r"^(?:Error|Warning):\s")  # @rule-suppress starter-sec-002 — re.compile, not python compile()
+
+
+def _stderr_matches_auth(stderr: str, patterns) -> bool:
+    """Check if any auth-failure pattern appears on an Error:/Warning: line.
+
+    previously a substring scan across the entire stderr, which
+    false-positived on Node ESM warnings ("Warning: @gthoppae/sf-cli-
+    plugin-data360 is a linked ESM module") if they happened to echo an
+    auth pattern substring. Now we only match on lines starting with
+    `Error:` or `Warning:` followed by whitespace. This keeps every
+    true-positive we care about (real sf auth errors always surface as
+    `Error: NoOrgAuthenticationError ...`) while pruning the noise.
+
+    Matching rules:
+      * Line starts with `Error:<ws>` or `Warning:<ws>` (anchored at
+        start-of-line, so embedded-in-prose mentions don't match).
+      * Pattern is a substring of the REST of that line (after the
+        prefix). We strip only the prefix — we do not re-scope to word
+        boundaries, since sf auth tokens like `NoOrgAuthenticationError`
+        are always well-formed identifiers without adjacent alphanum.
+      * Empty stderr / empty patterns → no match.
+    """
+    if not stderr or not patterns:
+        return False
+    for line in stderr.splitlines():
+        m = _AUTH_LINE_PREFIX_RE.match(line)
+        if not m:
+            continue
+        tail = line[m.end():]
+        if any(p in tail for p in patterns):
+            return True
+    return False
+
+
+def run_sf(name: str, **params: str) -> Dict[str, Any]:
+    """Execute a recipe-defined sf CLI command and return parsed stdout.
+
+    Steps:
+      1. Load recipe (yaml.safe_load).
+      2. Enforce required_params.
+      3. Substitute {{KEY}} into argv.
+      4. subprocess.run with list argv (no shell, no bash -c).
+      5. Parse stdout JSON; check `status == 0`.
+      6. On failure: classify as AuthRequired (stderr pattern match) or
+         SfCliError; every message is redacted via redact_error .
+
+    Exception semantics:
+      * AuthRequired — user needs to `sf org login`
+      * SfCliError   — anything else (timeout, non-zero exit, JSON parse,
+        status != 0)
+
+    NEVER uses shell=True. NEVER calls log.exception(). NEVER echoes raw
+    stderr without redaction .
+    """
+    recipe = _load_recipe(name)
+
+    required = set(recipe.get("required_params") or [])
+    missing = required - params.keys()
+    if missing:
+        raise SfCliError(f"missing required params for {name!r}: {sorted(missing)}")
+
+    argv_template = recipe.get("argv") or []
+    if not isinstance(argv_template, list):
+        raise SfCliError(f"recipe {name!r} argv must be a list")
+
+    argv = [_sub(str(e), params) for e in argv_template]
+    timeout = int(recipe.get("timeout_seconds", 60))
+    auth_patterns = recipe.get("auth_required_stderr_patterns") or []
+
+    # SF_TEMP_SHOW_SECRETS=true is required for `sf org display --verbose
+    # --json` to emit `accessToken` instead of the literal redaction string
+    # `"[REDACTED] Use 'sf org auth show-access-token' to view"` introduced
+    # in sf CLI v2. Without it, downstream callers receive the redaction
+    # string as the bearer token and every Tooling/REST call returns
+    # INVALID_AUTH_HEADER 401. Set on every recipe — recipes that don't
+    # touch tokens are unaffected.
+    env = {**os.environ, "SF_TEMP_SHOW_SECRETS": "true"}
+    try:
+        cp = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as e:
+        # timeout exceptions carry stderr via e.stderr — redact.
+        raise SfCliError(
+            f"sf CLI {name!r} timed out after {timeout}s: {redact_error(e)}"
+        ) from None
+    except (OSError, subprocess.SubprocessError) as e:
+        # any subprocess-layer error gets redacted.
+        raise SfCliError(
+            f"sf CLI {name!r} invocation failed: {redact_error(e)}"
+        ) from None
+
+    # Even on nonzero exit sf CLI usually still emits JSON on stdout; try
+    # to parse before deciding failure mode.
+    try:
+        data = _parse_stdout_json(cp.stdout) if cp.stdout else {}
+    except SfCliError:
+        data = {}
+
+    status_field = data.get("status", 0) if isinstance(data, dict) else 1
+    if cp.returncode != 0 or status_field != 0:
+        # stderr could contain a token on some failure paths; redact
+        # the ENTIRE string before deciding how to classify or what to show.
+        safe_stderr = _redact_subprocess_stderr(cp.stderr)
+        if _stderr_matches_auth(cp.stderr, auth_patterns):
+            raise AuthRequired(safe_stderr or "auth required")
+        # Include exit code + JSON status in the message (both are
+        # numeric/well-known, no token risk) plus the redacted stderr tail.
+        raise SfCliError(
+            f"sf CLI {name!r} failed "
+            f"(exit={cp.returncode}, json_status={status_field}): {safe_stderr}"
+        )
+
+    return data
+
+
+def _redact_subprocess_stderr(stderr: str) -> str:
+    """run stderr text through the rest_client redaction regexes.
+
+    stderr may contain `Authorization: Bearer ...` or `accessToken=...` if
+    the sf CLI echoes a failing request; scrub before surfacing.
+
+    calls the public `redact_text` (imported at module
+    top). Previously imported the module-private `_redact_text` lazily on
+    every call — a rename could have silently broken redaction, and an
+    ImportError would have propagated through `run_sf` with the raw stderr
+    still live in the traceback's frame locals.
+    """
+    return redact_text(stderr or "")

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

@@ -0,0 +1,253 @@
+"""SOQL template loader — reads assets/soql/*.soql and substitutes {{PARAM}} values.
+
+every value passed in via **params is regex-revalidated at the
+substitution boundary via `fs_guard.validate_api_name`. This is defence
+in depth — callers (SKILL.md phase 1, parse_bundle.extract_planner_name,
+parse_wave.discovered_names) already validate at their own boundaries, but
+centralizing the gate here guarantees that any future caller can't bypass
+it by forgetting to validate first.
+
+Why no escape function: `validate_api_name` restricts every substituted
+string to `^[A-Za-z0-9_]+$` — the legal character set for Salesforce
+DeveloperName / API-name identifiers. No quote, apostrophe, semicolon,
+parenthesis, or whitespace can ever reach the SOQL builder, so there is
+nothing to escape. Adding an escape step would be both dead code and a
+false reassurance that unvalidated input is somehow safe.
+
+`load_soql_in` adds support for `WHERE X IN (...)`
+list placeholders. The BFS fan-out passes across Apex/Flow/Plugin/Function
+discovery each need to batch-query by a list of ids or names; forcing
+one SOQL call per element would blow up both the query-count budget and
+the request-latency floor. The new function shares the `load_soql`
+validation path (every element goes through `fs_guard.validate_api_name`)
+so list inputs cannot widen the SOQL-injection surface — `'`, `;`, `--`,
+whitespace, and every other SOQL metachar remain unreachable. The
+existing `load_soql` signature is unchanged.
+
+SOQL-string-substitution loader with validation at the substitution
+boundary. Every value substituted into a `{{token}}` placeholder is
+regex-validated before insertion.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from config import SOQL_DIR, fs_guard  # fs_guard re-exported by config.py from _shared/
+
+
+class SoqlParamError(ValueError):
+    """Raised when a parameter value fails revalidation at the substitution site.
+
+    Carries the failing key + a 20-char preview of the rejected value. Callers
+    (parse_bundle, parse_wave, main.py) catch this and add the key to
+    `_unresolved[]` with `reason=invalid-soql-param:<key>` so the pipeline
+    continues with `STATUS=PARTIAL_OK` rather than aborting on a single
+    malformed name.
+    """
+
+    def __init__(self, key: str, value, reason: str) -> None:
+        self.key = key
+        self.reason = reason
+        # Preview is bounded to 20 chars to avoid echoing arbitrarily-long
+        # attacker-controlled strings into logs.
+        try:
+            preview = str(value)[:20]
+        except Exception:
+            preview = "<unreprable>"
+        self.preview = preview
+        super().__init__(
+            f"SOQL param {key!r} rejected: {reason} (preview={preview!r})"
+        )
+
+
+class SoqlTemplateNotFound(LookupError):
+    """Raised when `load_soql(name)` cannot locate a matching template file.
+
+    the message deliberately carries ONLY the requested
+    template name — never the absolute SOQL_DIR path. This prevents leaking
+    the filesystem layout of the skill install (which the attacker does not
+    otherwise need to know) via error messages that bubble up to logs or
+    RESULT blocks.
+
+    Distinct from `FileNotFoundError` so callers can tell "template missing"
+    apart from "filesystem I/O error" (permission denied, etc.) at the
+    except-clause layer.
+    """
+
+    def __init__(self, name: str) -> None:
+        # Preview bounds the echoed name at 60 chars. The validator forbids
+        # traversal characters anyway, but defence in depth against an
+        # arbitrarily-long attacker-controlled name ever reaching logs.
+        try:
+            preview = str(name)[:60]
+        except Exception:
+            preview = "<unreprable>"
+        self.name = preview
+        super().__init__(f"SOQL template not found: {preview!r}")
+
+
+def load_soql(name: str, **params) -> str:
+    """Read assets/soql/<name>.soql and substitute {{PARAM}} placeholders.
+
+    every value in `params` is revalidated via
+    `fs_guard.validate_api_name` before being substituted. Invalid values
+    (non-string, empty, or containing any character outside [A-Za-z0-9_])
+    raise `SoqlParamError`.
+
+    `name` itself is validated via the same
+    `fs_guard.validate_api_name` regex BEFORE any filesystem access.
+    Without this, a caller that sources `name` from data (config file,
+    user argument, etc.) could read `SOQL_DIR/../../../tmp/pwn.soql` via
+    traversal. All SOQL template filenames in this skill match
+    `^[A-Za-z0-9_]+$` (e.g. `bot_version_lookup`, `plugins_by_planner`),
+    so the regex is the correct gate.
+
+    Substitution is single-pass: `str.replace` does not re-scan the output,
+    so a value that contains `{{OTHER}}` cannot re-trigger substitution of
+    a different key. This is verified by test_soql_loader.
+    """
+    # validate the template name BEFORE touching the filesystem.
+    # A raw `../../../etc/passwd` would otherwise resolve via read_text().
+    try:
+        fs_guard.validate_api_name(name, label="soql_template_name")
+    except fs_guard.ValidationError as e:
+        raise SoqlParamError("soql_template_name", name, e.reason) from None
+
+    # revalidate every SOQL param before substitution. No exceptions,
+    # no "this caller already validated" shortcuts. Defence in depth.
+    for key, value in params.items():
+        try:
+            fs_guard.validate_api_name(value, label=key)
+        except fs_guard.ValidationError as e:
+            raise SoqlParamError(key, value, e.reason) from None
+
+    # translate FileNotFoundError into SoqlTemplateNotFound so the
+    # absolute SOQL_DIR path never bleeds into caller-visible error text.
+    # We intentionally do NOT chain the original exception (`from None`) —
+    # the original carries the full path in `filename`/`strerror`.
+    try:
+        soql = (SOQL_DIR / f"{name}.soql").read_text()
+    except FileNotFoundError:
+        raise SoqlTemplateNotFound(name) from None
+
+    for key, value in params.items():
+        # Plain str.replace: single-pass by construction. No re-substitution
+        # of placeholders that appear inside a substituted value (see test).
+        soql = soql.replace(f"{{{{{key}}}}}", value)
+    return soql.strip()
+
+
+def load_soql_in(
+    name: str,
+    *,
+    string_params: Optional[Dict[str, str]] = None,
+    list_params: Dict[str, List[str]],
+) -> str:
+    """Read assets/soql/<name>.soql and substitute both scalar and list placeholders.
+
+    the BFS fan-out builds `WHERE X IN (:list)` queries
+    (apex_class_bodies_by_names, flow_definition_by_ids, plugin_functions_
+    by_plugin_ids, etc.). The existing `load_soql` only handles scalar
+    string substitution; this sibling covers the list case without
+    touching that signature.
+
+    Parameters
+    ----------
+    name:
+        Template filename (without `.soql`). Validated via
+        `fs_guard.validate_api_name` BEFORE any filesystem access — same
+        defence-in-depth gate as `load_soql` .
+    string_params:
+        Optional scalar {{KEY}} → value map. Values revalidated through
+        `fs_guard.validate_api_name` — identical path to `load_soql`.
+        Useful for templates that mix a single scalar value with a list
+        in the same query. No active callers at present (retired with
+        `flow_definition_ids_by_name_with_ns.soql` on 2026-05-05); kept
+        on the signature as a stable extension point.
+    list_params:
+        Required. {{KEY}} → list-of-strings map. Each element is
+        revalidated through `fs_guard.validate_api_name`; any failure
+        aborts the whole call with `SoqlParamError(key=<list-key>, ...)`.
+        Empty lists raise — SOQL `WHERE X IN ()` is a syntax error in
+        Salesforce, fail fast rather than let the CLI surface an opaque
+        500.
+
+    Rendering
+    ---------
+    Lists render as `','.join(f"'{v}'" for v in sorted(set(list_value)))`:
+    single-quoted, comma-separated, no surrounding parens. The `.soql`
+    template supplies the parens around the `{{PLACEHOLDER}}` so the
+    result reads `WHERE Id IN ('A','B','C')`.
+
+    Deduplication is load-bearing: SOQL tolerates dupes but they waste
+    the 100k-char query-length budget. Sort is for deterministic order —
+    stable cache keys and diffable test output.
+
+    Returns
+    -------
+    Substituted, `.strip()`-ed SOQL string.
+    """
+    # validate template name BEFORE touching the filesystem.
+    try:
+        fs_guard.validate_api_name(name, label="soql_template_name")
+    except fs_guard.ValidationError as e:
+        raise SoqlParamError("soql_template_name", name, e.reason) from None
+
+    string_params = string_params or {}
+
+    # / revalidate scalar params — same path as `load_soql`.
+    for key, value in string_params.items():
+        try:
+            fs_guard.validate_api_name(value, label=key)
+        except fs_guard.ValidationError as e:
+            raise SoqlParamError(key, value, e.reason) from None
+
+    # validate list params first (deterministic failure order — we
+    # want the first bad element, not a partially-rendered string).
+    rendered_lists: Dict[str, str] = {}
+    for key, list_value in list_params.items():
+        if not isinstance(list_value, list):
+            raise SoqlParamError(
+                key,
+                list_value,
+                f"list_params[{key}] must be a list, got {type(list_value).__name__}",
+            )
+        if not list_value:
+            # Salesforce `WHERE X IN ()` is a hard syntax error — fail fast
+            # at the loader, not at the CLI. Callers should branch on the
+            # empty-list case upstream (e.g. skip the whole SOQL) rather
+            # than rely on an empty-clause fallback.
+            raise SoqlParamError(
+                key, "[]", "empty-list-would-produce-invalid-soql",
+            )
+        # Dedupe + sort: cache-key stable, query-length budget sparing.
+        # `sorted(set(...))` raises TypeError on non-hashable elements;
+        # validate_api_name below will surface the real cause for
+        # non-strings, so gate on type FIRST.
+        for element in list_value:
+            try:
+                fs_guard.validate_api_name(element, label=key)
+            except fs_guard.ValidationError as e:
+                raise SoqlParamError(key, element, e.reason) from None
+        unique_sorted = sorted(set(list_value))
+        # Single-quote each element, comma-join. The `.soql` template
+        # supplies the surrounding parens around `{{KEY}}`.
+        rendered_lists[key] = ",".join(f"'{v}'" for v in unique_sorted)
+
+    # translate FileNotFoundError into SoqlTemplateNotFound. Same
+    # hygiene contract as `load_soql` — the absolute SOQL_DIR path must
+    # not bleed into caller-visible error text.
+    try:
+        soql = (SOQL_DIR / f"{name}.soql").read_text()
+    except FileNotFoundError:
+        raise SoqlTemplateNotFound(name) from None
+
+    # Single-pass substitution, same semantics as `load_soql`. Scalars
+    # first, lists second — the order is only relevant if a scalar value
+    # could contain a list-placeholder token, which `validate_api_name`
+    # forbids (no `{` or `}` in `[A-Za-z0-9_]+`).
+    for key, value in string_params.items():
+        soql = soql.replace(f"{{{{{key}}}}}", value)
+    for key, rendered in rendered_lists.items():
+        soql = soql.replace(f"{{{{{key}}}}}", rendered)
+    return soql.strip()

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Render the declared action tree as a box-drawing summary.md.
+
+Called by finalize.py (cold path) and cache_check.py (hit path when the
+cached summary is missing). Mirrors the old agent Phase 7 render_tree()
+logic verbatim.
+
+Usage:
+    python3 summarize_tree.py <tree_json_path> <out_md_path> <built_at_utc>
+
+Inputs:
+    argv[1]   absolute path to declared_action_tree.json (or similar)
+    argv[2]   output .summary.md path (overwritten atomically)
+    argv[3]   ISO-8601 UTC built-at timestamp (e.g. 2026-04-25T14:00:00Z)
+
+Outputs:
+    argv[2]   rendered markdown
+    exit 0    success
+    exit 1    missing args, read failure, write failure
+"""
+import json
+import os
+import pathlib
+import sys
+
+KC_ORDER = [
+    "BOT_DEFINITION", "TOPIC", "GEN_AI_FUNCTION",
+    "FLOW", "APEX", "PROMPT_TEMPLATE",
+    "STANDARD_ACTION", "UNKNOWN",
+]
+
+
+def render_tree(node, prefix="", is_last=True, lines=None, agent_=None):
+    if lines is None:
+        lines = []
+    connector = "└── " if is_last else "├── "
+    kind = node.get("kind", "?")
+    api = node.get("api_name", "?")
+    elem = node.get("element_name")
+    if kind == "BOT_DEFINITION":
+        v = (agent_ or {}).get("version") or ""
+        label = f"[{kind}] {api}" + (f" ({v})" if v else "")
+    elif kind == "GEN_AI_FUNCTION":
+        unwraps = node.get("unwraps_to") or {}
+        uk = unwraps.get("kind")
+        un = unwraps.get("api_name")
+        arrow = f" → {uk}:{un}" if uk and un else ""
+        label = f"[{kind}] {api}{arrow}"
+    elif kind in ("STANDARD_ACTION", "UNKNOWN"):
+        # Canonical key is `invocation_type` (schema 3.1+); fall back to
+        # the two legacy keys so caches built by an older parse_wave still
+        # render the qualifier.
+        raw = (
+            node.get("invocation_type")
+            or node.get("raw_invocation_type")
+            or node.get("raw_action_type")
+            or ""
+        )
+        label = f"[{kind}] {api}" + (f" ({raw})" if raw else "")
+    else:
+        label = f"[{kind}] {api}"
+    if elem and kind != "BOT_DEFINITION":
+        label += f"  — element:{elem}"
+    lines.append(prefix + connector + label)
+    children = node.get("children") or []
+    child_prefix = prefix + ("    " if is_last else "│   ")
+    for i, c in enumerate(children):
+        render_tree(c, child_prefix, i == len(children) - 1, lines, agent_)
+    return lines
+
+
+def main() -> int:
+    if len(sys.argv) != 4:
+        sys.stderr.write(
+            "summarize_tree.py: usage: python3 summarize_tree.py <tree_json_path> "
+            "<out_md_path> <built_at_utc>\n"
+        )
+        return 1
+
+    tree_path = pathlib.Path(sys.argv[1])
+    out_path = pathlib.Path(sys.argv[2])
+    built_at = sys.argv[3]
+
+    try:
+        tree = json.loads(tree_path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        sys.stderr.write(f"summarize_tree.py: cannot read {tree_path}: {e}\n")
+        return 1
+
+    a = tree.get("agent", {}) or {}
+    kc = tree.get("_kind_counts", {}) or {}
+
+    lines = [
+        f"# {a.get('api_name', '?')} {a.get('version', '?')} — declared action tree",
+        "",
+        f"- **Bot ID:** `{a.get('bot_id', '?')}`",
+        f"- **Master label:** {a.get('master_label', '?')}",
+        f"- **Generation:** {a.get('generation', 'unknown')}",
+        f"- **Planner:** `{a.get('planner_name', '?')}` ({a.get('planner_type', '?')})",
+        f"- **Version auto-picked:** {a.get('_version_auto_picked', False)}",
+        f"- **Built at (UTC):** {built_at}",
+        f"- **Node count:** {tree.get('node_count', 0)}",
+        f"- **Depth:** {tree.get('depth', 0)}",
+        f"- **Partial:** {tree.get('_partial', False)}",
+        "",
+        "## Kind counts",
+        "",
+    ]
+    for k in KC_ORDER:
+        lines.append(f"- `{k}`: {kc.get(k, 0)}")
+
+    lines += [
+        "",
+        "## Declared action tree",
+        "",
+        "```",
+    ]
+    root = tree.get("root") or {"kind": "BOT_DEFINITION", "api_name": a.get("api_name", "?"), "children": []}
+    lines.extend(render_tree(root, "", True, None, a))
+    lines.append("```")
+
+    if tree.get("_unresolved"):
+        lines += ["", "## Unresolved", ""]
+        for u in tree["_unresolved"]:
+            lines.append(
+                f"- `{u.get('kind')}`/`{u.get('api_name')}` — {u.get('reason')}"
+            )
+
+    content = "\n".join(lines) + "\n"
+
+    try:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out_path.with_suffix(out_path.suffix + ".tmp")
+        tmp.write_text(content)
+        os.replace(tmp, out_path)
+    except OSError as e:
+        sys.stderr.write(f"summarize_tree.py: write failed: {e}\n")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/investigating-agentforce-architecture/scripts/tests/_bootstrap.py

@@ -0,0 +1,23 @@
+"""Shared sys.path bootstrap for the test suite.
+
+The scripts/ scripts expect to be imported as top-level modules (config,
+soql_loader, rest_client, sf_cli) — that's how they behave when main.py
+does `from config import ...`. Tests mirror that by inserting scripts/
+onto sys.path.
+
+fs_guard is now sourced via ``from config import fs_guard`` (config.py
+re-exports it from the plugin _shared/ package). No tools/ entry on
+sys.path is required — config.py's dev-fallback walks up to the repo's
+``plugins/investigating-agentforce-architecture/shared/`` when ``scripts/_shared/``
+hasn't yet been mirrored by install.sh / the build script.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+
+s = str(_SCRIPTS_DIR)
+if s not in sys.path:
+    sys.path.insert(0, s)