@salesforce/afv-skills 1.45.0 → 1.47.0

package/skills/platform-dsar-policy-manage/references/gap-analysis-guide.md

@@ -0,0 +1,150 @@
+# Gap-analysis guide prompt — coverage audit for a DsarPolicy
+
+> This is the guidance the agent follows when an admin asks *"what personal data are we missing
+> from this policy?"*. It is the script for **Workflow D — Coverage gap analysis**: a **read-only**
+> audit that surfaces **candidate** objects/fields for the admin to disposition — it never
+> classifies data authoritatively, never adds a path on its own, and never activates a policy.
+
+## Contents
+
+- [What this is and is not](#what-this-is-and-is-not)
+- [The deterministic steps](#the-deterministic-steps)
+- [How fields are flagged as candidate personal data (and why)](#how-fields-are-flagged-as-candidate-personal-data-and-why)
+- [User-facing output (canonical)](#user-facing-output-canonical--use-verbatim-structure)
+- [Guardrails](#guardrails)
+
+## What this is and is not
+
+The gap analysis answers **"which objects/fields that may hold this subject's personal data are
+not yet covered by the policy?"** It is deliberately **structured and deterministic** — the same
+request produces the same steps and the same transparency, not an open-ended graph walk that
+varies run to run.
+
+- **It is:** a read-only audit that (1) states its own method up front, (2) shows exactly which
+  objects it looked at, (3) flags **candidate** personal-data fields **with a reason for each**,
+  (4) states its search limit, and (5) hands the admin a disposition choice.
+- **It is not:** an authoritative classification of what counts as personal data (that decision is
+  the **admin's** — load-bearing call #2), an automatic edit to the policy, or an activation. The
+  agent proposes; the admin disposes.
+
+## Internal vs. user-facing (read before running)
+
+This is the Workflow-D-specific application of **SKILL.md load-bearing call #8 (work silently — never
+narrate the skill's internals)**. Workflow D has two layers; keep them apart in what you *say*:
+
+- **Internal — never narrated to the user:** the step numbers and step names below, the `sf`/describe
+  mechanics in `gap-scan.md`, and every author-facing note about truncation, event-message limits,
+  token cost, or how the audit is "scored." These steer *how you work*; they are not status updates.
+  Do not say "running Workflow D, step 2", "describing the root to avoid truncation", or "this keeps
+  the run from scoring 0." Just do the work and present the result.
+- **User-facing — the ONLY things the user sees:** the four blocks in
+  [User-facing output (canonical — use verbatim structure)](#user-facing-output-canonical--use-verbatim-structure)
+  — method preamble, findings, depth offer, disposition. Nothing else.
+
+If the environment blocks the scan (feature off / policy unreadable), say so in one plain sentence
+inside the findings block — not by narrating the mechanics that failed.
+
+## The deterministic steps
+
+Run these in order. Do not skip the method preamble (step 0) — transparency is the point. **These
+step numbers/names are internal scaffolding — do the work, don't announce the scaffolding** (see
+[Internal vs. user-facing](#internal-vs-user-facing-read-before-running)).
+
+0. **Open with the plain-language method line.** Before scanning, tell the admin in **plain words**
+   how you'll answer and its limits (see the script). This is the one allowed "here's how I'll do
+   this" sentence — it must **not** name the workflow ("Workflow D", "coverage-gap audit"), announce
+   that you're about to read the guide/mechanics, or cite a rule/tool (call #8). State the approach,
+   then start.
+1. **Read current coverage.** Load the policy's existing roots and paths (read-only). These are
+   already-covered objects — the audit reports gaps *relative to* this set.
+2. **Enumerate candidate objects — one level only.** For each policy **root** object, describe it
+   and list its **immediately related** objects (exactly **one relationship hop** away). This
+   depth-1 default is a hard limit that keeps performance and token cost bounded — do **not**
+   recurse further without explicit confirmation (step 5).
+3. **Flag candidate fields with reasoning.** On the root and each one-hop object, mark the fields
+   that **may** hold the subject's personal data, and record **why** for each (see the flagging
+   rubric). Candidates only — never "this *is* PII."
+4. **Report transparently.** Present: the objects you scanned, the candidate fields with the
+   per-field reason, the fields already covered vs newly surfaced, and an explicit statement of the
+   **one-level search limit**.
+5. **Offer to go deeper — only on explicit confirmation.** Ask whether the admin wants to look
+   beyond one level. Warn plainly that going deeper produces **a large volume of output and burns
+   significantly more tokens**. Expand only if they say yes, and only by the depth they approve.
+6. **Disposition, don't mutate.** Ask which candidates the admin wants to add. Nothing is added
+   automatically. Adding routes to **Workflow A (Configure)**, which authors the change INACTIVE
+   and — per the activation rule — **stops for explicit user confirmation before reactivating**.
+
+## How fields are flagged as candidate personal data (and why)
+
+The reason string is mandatory — every flagged field says *why*. Use these signals, strongest
+first, and name the signal you used:
+
+- **Compliance metadata on the field** (e.g. a field's data-sensitivity / compliance-group /
+  PII classification from the describe). Reason: *"marked <classification> in field metadata."*
+  This is the strongest signal and the least subjective.
+- **Field type semantics** — `email`, `phone`, `address` compound components, `date` used for
+  birthdate. Reason: *"<type> field, commonly personal contact/identity data."*
+- **Name/label semantics** — tokens like Name, First/Last, Email, Phone, Mobile, SSN, Passport,
+  DOB/Birth, Address/Street/City/Postal, IP, DeviceId, TaxId. Reason: *"name/label suggests
+  <category>."*
+- **Already-covered elsewhere** — the same value appears on an already-mapped object. Reason:
+  *"duplicate of a field already in the policy; flagged for the admin to decide canonical source."*
+
+State the rubric's limits honestly: this is a **heuristic**, not a legal determination. A field
+the rubric misses can still be personal data, and a flagged field may not be — the admin confirms.
+When compliance metadata is absent on the org, say so (the audit leans on name/type semantics only).
+
+## User-facing output (canonical — use verbatim structure)
+
+**This is the output contract for Workflow D — the four blocks below are the only thing the user
+sees, and their structure is fixed.** Use these four blocks, in this order, with this formatting
+(the blockquote framing and the `Object | Field | Why I flagged it | In policy?` table columns);
+do not improvise a different layout run to run. The *prose wording* may be adapted to the specific
+policy/org, but the **blocks, their order, and the table columns are not optional** — stable
+structure is what keeps the presentation clean instead of randomly formatted. Do not surface any of
+the internal step numbers, mechanics, or scoring/truncation notes here (see
+[Internal vs. user-facing](#internal-vs-user-facing-read-before-running)).
+
+**Method preamble (step 0):**
+
+> Here's how I can answer this. I'll start from your policy's root objects, look **one level out**
+> at the objects directly related to them, and flag the fields that *might* contain this person's
+> data — and I'll tell you **why** I flagged each one. I won't decide what counts as personal data
+> for you, and I won't change the policy: you'll pick what to add. I stop at one level by default;
+> I can go deeper if you ask, but that gets large and token-heavy, so I'll check with you first.
+
+**Findings (step 4):**
+
+> **Objects I looked at:** `<root objects>` and their immediately-related objects: `<one-hop list>`.
+> **Already covered by the policy:** `<covered fields>`.
+> **Candidate fields that may hold personal data (not yet covered):**
+> | Object | Field | Why I flagged it | In policy? |
+> |--------|-------|------------------|------------|
+> | Contact | Email | email field, common contact PII | no |
+> | Contact | Birthdate | date used as date of birth (name/type) | no |
+> **Search limit:** I only looked **one level** out from your roots. Deeper relationships are not
+> in this list.
+
+**Depth gate (step 5):**
+
+> Want me to look **beyond one level**? Heads up: it produces a lot more output and uses
+> considerably more tokens. If yes, tell me how deep (e.g. one more level) and I'll continue.
+
+**Disposition (step 6):**
+
+> Which of these do you want added to the policy? I'll author the change and leave it **inactive**
+> for your review — I won't reactivate or publish until you confirm.
+
+## Guardrails
+
+- **Candidates, never verdicts.** Every flag is a suggestion pending the admin's disposition.
+- **Depth 1 by default.** Never recurse past one level without explicit, warned confirmation.
+- **Read-only.** The audit changes nothing; adding is a separate, admin-driven Workflow A step.
+- **No auto-activation.** Any resulting edit stops for explicit user confirmation before
+  reactivation/publish (the activation rule).
+- **Transparency is mandatory.** Always report what was scanned, why each field was flagged, and
+  the search limit — even when the list is short or empty.
+- **Transparency ≠ narrating internals.** Show *what* you scanned and *why* each field is flagged
+  (the findings block). Do **not** narrate *how* — step numbers, describe mechanics, truncation /
+  token / scoring notes stay internal. Transparency is about the audit's coverage and reasoning, not
+  the skill's plumbing.

package/skills/platform-dsar-policy-manage/references/gap-scan.md

@@ -0,0 +1,129 @@
+# Coverage gap analysis — mechanics (Workflow D)
+
+The mechanics for **Workflow D**. The judgment (read-only, candidates-not-verdicts, depth-1,
+disposition-to-admin) and the user-facing script live in `references/gap-analysis-guide.md`; this
+file is the *how*. Everything here is **read-only** — Workflow D never writes metadata.
+
+> **This entire file is INTERNAL — never narrated to the user.** The describe commands, the ~5-object
+> bound, and every note about truncation / event-message limits / token cost / "scored 0" steer *how
+> you work*; they are not status updates. Do the work quietly and present only the four user-facing
+> blocks from `gap-analysis-guide.md`. See its *Internal vs. user-facing* section.
+
+## Contents
+
+- [1. Read current coverage](#1-read-current-coverage)
+- [2. Enumerate one-hop candidate objects](#2-enumerate-one-hop-candidate-objects)
+- [3. Flag candidate fields (the rubric)](#3-flag-candidate-fields-the-rubric)
+- [4. Diff against the current tree](#4-diff-against-the-current-tree)
+- [5. The depth gate](#5-the-depth-gate)
+- [6. The transparency report shape](#6-the-transparency-report-shape)
+
+## 1. Read current coverage
+
+Load the policy's existing roots and paths so gaps are reported *relative to* them. On a plain `sf`
+surface the tree is Metadata API:
+
+```bash
+sf project retrieve start --metadata DsarPolicy:<PolicyDeveloperName> --target-org <alias>
+```
+
+On an MCP / SOR surface, read it with the `DsarPolicyManager` `list`/`describe` operation instead.
+Record the set of `{object → [fields]}` already covered — that set is subtracted in step 4.
+
+## 2. Enumerate one-hop candidate objects
+
+For **each root** object in the policy, describe it once and read two things from the result:
+
+```bash
+# A full object describe is ~100KB+ of JSON. Do NOT read it raw into the turn — the accumulated
+# describe payloads overflow the agent's event-message size limit and the run TRUNCATES before it
+# writes the report. Always project to just the fields you reason over, so only a few KB enters context:
+sf sobject describe --sobject <RootObject> --target-org <alias> --json \
+  | python3 -c 'import json,sys; d=json.load(sys.stdin)["result"]; \
+print(json.dumps({"fields":[{"name":f["name"],"type":f["type"],"label":f["label"]} for f in d["fields"]], \
+"children":[c["childSObject"] for c in d["childRelationships"]][:40]}, indent=1))'
+```
+
+- **`fields[]`** — the root's own fields (candidate personal-data fields live here).
+- **one relationship hop out** — the objects directly related to the root:
+  - `childRelationships[]` → child objects (e.g. Contact → Cases, Contact → ContactPointEmails);
+  - reference/lookup `fields[]` (`type: "reference"`) → parent objects the root points to.
+
+**Never read a raw `--json` describe into the turn.** Project every describe (root and one-hop)
+through the field-name/type/label filter above. This is the single most important guard against the
+`Truncated event message received` failure — the describe JSON, not the number of objects, is what
+overruns the stream.
+
+Describe each one-hop object once to read *its* `fields[]`. **Stop there.** Do not describe the
+objects *those* relate to — that is level 2, gated behind explicit confirmation (step 5). The
+one-hop rule is what keeps the scan bounded and cheap; it is also the tree-cap discipline (skill
+call #3) applied to discovery.
+
+**Hard bound — describe at most ~5 one-hop objects, then stop and report.** A standard root such as
+`Contact` exposes dozens of `childRelationships[]`; describing all of them floods the context and
+the run can truncate before it ever writes the report (a failed audit, not a thorough one). Pick the
+**most privacy-relevant** related objects (contact points, cases/activities carrying supplied
+contact data, the parent account) — describe those few, and **name in the report the related objects
+you did *not* describe** so the omission is transparent, offering them under the depth gate (step 5).
+The root's own describe plus a couple of one-hop objects is enough for a correct, complete audit;
+**describing more than ~5 objects adds no value and risks truncation.**
+
+**Policy/type unreadable (the accepted environment path) → stop at the root describe.** If
+`DsarPolicy` can't be read (Metadata/Tooling/Connect all 404 — the feature isn't enabled on this
+org), do **not** fan out to one-hop objects at all: a single **projected** `Contact` describe is
+enough to demonstrate the depth-1 candidate reasoning. Flag the candidate fields on the root, state
+that the policy/type couldn't be read and that you therefore reasoned from the root alone, name the
+one-hop objects you *would* scan next (without describing them), and write the report. Casting wider
+here only adds truncation risk for no benefit — the gap-analysis *method* is what matters, not breadth.
+
+**Write incrementally; never let discovery starve the report.** The report file is the deliverable —
+an audit that describes many objects but never writes is a failed, incomplete audit — strictly worse
+than one that scans fewer objects and writes. Create `${outputDir}` and draft the report early, fill it in
+as you describe, and once you have the root + a couple of one-hop objects **write it** — then offer
+more depth, rather than gathering everything first and writing last.
+
+## 3. Flag candidate fields (the rubric)
+
+On the root and each one-hop object, mark fields that **may** hold the subject's personal data.
+Every flag carries a **reason**; use the strongest available signal and name it:
+
+| Signal (strongest first) | How to read it | Reason string |
+|--------------------------|----------------|---------------|
+| Field compliance metadata | describe field's `complianceGroup` / `securityClassification` (when populated) | `marked <value> in field metadata` |
+| Field type | `type` = `email` / `phone` / `address`; `date` used as birthdate | `<type> field, common personal data` |
+| Name / label semantics | tokens: Name, First/Last, Email, Phone, Mobile, SSN, Passport, DOB/Birth, Address/Street/City/Postal, IP, DeviceId, TaxId | `name/label suggests <category>` |
+| Duplicate of a covered value | same value already mapped on another object | `duplicate of a covered field; admin picks canonical source` |
+
+**These are candidates, not classifications.** A field the rubric misses can still be personal
+data; a flagged field may not be. The admin confirms (skill call #2). When `complianceGroup` /
+`securityClassification` come back empty on the org, say so — the scan then rests on type and name
+semantics only, which is weaker; state that limitation in the report.
+
+## 4. Diff against the current tree
+
+Candidate = flagged in step 3 **and not** in the covered set from step 1. Group the result by
+object. Also list, per scanned object, the fields **already** covered — the report shows covered vs
+newly-surfaced side by side so the admin sees what the policy already handles.
+
+## 5. The depth gate
+
+After presenting the one-hop findings, offer to go deeper — but only expand on **explicit
+confirmation**, and warn first:
+
+> Going beyond one level produces a large volume of output and uses considerably more tokens.
+
+If the admin confirms, repeat steps 2–4 for exactly the depth they approved (usually one more hop),
+then stop and re-offer. Never recurse unprompted; never "just keep going down the tree."
+
+## 6. The transparency report shape
+
+The report must make the method and its limits visible (skill call: transparency). Include:
+
+- **Objects scanned** — the roots and the one-hop objects, by name (so the admin sees the actual
+  surface examined, not just conclusions).
+- **Candidate fields** — a table of `object | field | reason | already in policy?`.
+- **Covered vs surfaced** — what the policy already maps, alongside the new candidates.
+- **Search limit** — an explicit line that only one level was scanned, and the offer to go deeper.
+- **Disposition prompt** — which candidates to add; adding routes to Workflow A (authored INACTIVE,
+  no auto-reactivation). Report even when nothing new was found ("no uncovered candidates at one
+  level").

package/skills/platform-dsar-policy-manage/references/headless-sor.md

@@ -0,0 +1,59 @@
+# Find the right SOR when a routing tool is in reach (discover → describe → dispatch)
+
+**Detect by tool shape, not by host name.** Check the tools available to you this run for a generic
+capability-routing tool exposing **`discover` / `describe` / `dispatch`** verbs. The name may carry a
+host prefix (`mcp__<host>__discover`, a bare `discover`, etc.) — **match the verb shape**. Such tools
+are provided by SOR-routing surfaces (project-codey / Headless 360, Vibes / `vibes-cli`, Tool Factory
+today; treat these as examples — the names change, the verb shape is the stable signal).
+
+When one is in reach, the entry move for any DsarPolicy task is to **locate the SOR that covers the
+capability**, then let it route the call. You supply judgment (which SOR, which operation, is the
+request bounded / consented / an export-not-erasure); the SOR supplies the plumbing.
+
+## 1. Discover — find the SOR, don't guess its name
+
+Search the **capability**, not a guessed identifier:
+
+- "manage DSAR / data-subject portability policies"
+- "execute a DSAR policy against a data subject"
+- "DSAR policy run history"
+
+The SOR that owns this steel thread is **`DsarPolicyManager`** (owning team **Privacy Center**,
+complexity SIMPLE). Its `agent_description` names DSAR policies + Right-to-Portability and the full
+lifecycle:
+
+```text
+getAccessInfo → list policies → save (create / full-tree update) → activate
+  → execute against a dataSubjectId → deactivate → delete
+```
+
+`isActive` is the load-bearing gate: **execute** needs ACTIVE; **edit / delete** need INACTIVE.
+
+If several SORs surface, pick the one whose `agent_description` names **DSAR + Right-to-Portability**.
+**Reject look-alikes:** data mask, generic consent, or anything framed as subject *erasure* — RTP
+is a portability export, it deletes nothing. If none matches, say so and stop; do not fabricate a
+SOR.
+
+## 2. Describe — the contract comes from describe, not memory
+
+`describe` the specific operation before calling it. The exact inputs — `policyName` (must match
+`[a-zA-Z]+[a-zA-Z0-9_]*`), `description`, `isActive`, `relatedTrees` (UI-serialized node keys), and
+`dataSubjectId` for execute — come from the operation's schema, not recall.
+
+## 3. Dispatch — the SOR routes to the backend
+
+`dispatch` the operation. The SOR picks the backend (the DsarPolicy config tree, the RTP execute
+endpoint, the `DsarPolicyLog` read); you never hand-assemble the route.
+
+## No routing tool in reach?
+
+If no discover/describe/dispatch tool is available this run, fall back to the metadata / Connect /
+SOQL routes in the SKILL.md object-model table. The judgment in the skill is identical either way —
+the skill never changes *what* is correct, only *which tool* executes it.
+
+## Related
+
+- `../SKILL.md` — the object-model table (the plain-`sf` equivalents) and the three workflows
+- The routing tool's own `discover` verb — "which SORs cover `<capability>`?" is answered by the
+  discover/describe verbs described at the top of this file (project-codey / Headless 360), not by a
+  separate skill.

package/skills/platform-dsar-policy-manage/references/report-format.md

@@ -0,0 +1,59 @@
+# Report format — per-workflow report contracts
+
+Write the report to `${outputDir}/report.md`, reporting only **the workflow you ran**. The
+length/concision rules (say each load-bearing point once, well under ~150 lines, no exhaustive
+per-object dumps) live in SKILL.md's `## Output` section — they are not repeated here. **This file
+adds only what SKILL.md does not: the per-workflow section contracts below.** The expected-content
+lists are a ceiling, not a checklist to pad toward.
+
+## Workflow A (configure)
+
+**Bounded request:** (1) the classification strategy — subject, root(s), per-relationship
+follow/stop and why; (2) the tree — roots, paths, fields, with node count vs 200, max depth vs 10,
+max children vs 10; (3) lifecycle — authored INACTIVE, must be activated to run, ACTIVE edits need
+deactivate→edit→then **explicit user-confirmed** reactivation (never auto-reactivated); (4) the
+guardrail — authoring/editing/deleting the policy never deletes the subject's records; (5) deploy
+outcome — deployed, or the raw error + prerequisite.
+
+**Unbounded request:** instead state the caps, name the specific cap the request would exceed, and
+offer the bounded alternative (split/prune) — never a silently truncated "complete" map.
+
+**Under-specified request:** instead enumerate the classification decisions the admin must make
+(roots; per-relationship follow/stop; fields) and mark any proposal disposition-pending — never an
+authoritative map of guessed personal data.
+
+## Workflow B (export)
+
+(1) the **resolved subject** — identifier (email/name/id) → root-entity Id + type — and the
+**policy chosen** (noting if it was ambiguous and you asked); (2) consent confirmed, or the run
+withheld as ambiguous; (3) that this was an **export, not a deletion**; (4) the **poll ordering**
+made explicit — a couple of polls, the file retrieved only after the run reaches a terminal state,
+an early not-ready response is expected, and if still non-terminal you **asked** the user before
+continuing (never looped); stated even on the accepted preflight-error path; (5) outcome from the
+**envelope / run status** in plain terms — running / completed / errored — not the HTTP code; (6)
+file location on success (from the `dsr` getfile route, after terminal); (7) any missing
+permission/feature named with the raw error. A non-terminal run is a valid stopping point — report
+it as *still running* and defer to the user, don't diagnose the async backend.
+
+**Preflight-error path (feature/policy/subject absent — the run never started):** keep it short.
+Lead with the blocker(s) and the prerequisite to unblock each; state export-not-deletion **once**;
+state the poll-then-download ordering **once** (a single short paragraph — this is item 4, not a
+recurring theme). Do **not** add a separate essay re-explaining "grab it right away," and do **not**
+enumerate every subject-search query — one representative command and the outcome is enough. Two
+blockers → two short entries, not two full-screen tables.
+
+## Workflow C (history)
+
+The prior runs from the `DsarPolicyLog` SOQL read (or an explicit "no prior runs"), and that **no
+new run was started**.
+
+## Workflow D (coverage gap analysis)
+
+(1) the **method** stated once up front — from the policy root(s), one relationship hop out,
+candidate fields flagged with a reason each, admin disposes; (2) the **objects scanned** by name
+(roots + the one-hop objects); (3) a **candidate table** — `object | field | reason | in policy?`;
+(4) **covered vs newly surfaced**; (5) the **one-level search limit** stated explicitly, plus the
+offer to go deeper only on confirmation (with the token-cost warning); (6) a **disposition prompt** —
+which to add (adding routes to Workflow A: authored INACTIVE, no auto-reactivation) — and that the
+audit deletes nothing. "No uncovered candidates at one level" is a valid result. Keep the candidate
+table to the roots + one hop; don't append further-hop objects to look thorough.

package/skills/platform-dsar-policy-manage/scripts/tests/test_validate_policy_tree.py

@@ -0,0 +1,76 @@
+"""Unit tests for validate-policy-tree.py.
+
+Pure, deterministic cap/name checks on a DsarPolicy tree JSON — unit tested here
+rather than via evals (evals score the LLM-authored artifact against a gold; they
+do not assert the validator's fail-closed behavior).
+
+The filename has hyphens, so it is loaded by path via importlib rather than a
+normal import.
+"""
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import unittest
+
+_SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "validate-policy-tree.py"
+_spec = importlib.util.spec_from_file_location("validate_policy_tree", _SCRIPT)
+vpt = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(vpt)
+
+
+def _root(name="ContactRoot", **over):
+    node = {"developerName": name, "object": "Contact", "fields": ["Email"], "children": []}
+    node.update(over)
+    return node
+
+
+def _tree(dev="CustomerPortability", roots=None):
+    return {"developerName": dev, "roots": roots if roots is not None else [_root()]}
+
+
+class NameValidationTests(unittest.TestCase):
+    def test_plain_name_ok(self):
+        vpt.check_name("ContactRoot", "where")  # does not raise
+
+    def test_trailing_newline_rejected(self):
+        # Regression: ^...$ with .match() accepted "Foo\n" because $ matches
+        # before a final newline. \A...\Z must reject it.
+        with self.assertRaises(vpt.TreeError):
+            vpt.check_name("ContactRoot\n", "where")
+
+    def test_embedded_newline_rejected(self):
+        with self.assertRaises(vpt.TreeError):
+            vpt.check_name("Contact\nRoot", "where")
+
+    def test_leading_digit_rejected(self):
+        with self.assertRaises(vpt.TreeError):
+            vpt.check_name("1Contact", "where")
+
+    def test_empty_or_nonstring_rejected(self):
+        with self.assertRaises(vpt.TreeError):
+            vpt.check_name("", "where")
+        with self.assertRaises(vpt.TreeError):
+            vpt.check_name(None, "where")
+
+
+class TreeValidationTests(unittest.TestCase):
+    def test_minimal_valid_tree(self):
+        self.assertEqual(vpt.validate(_tree()), 1)
+
+    def test_trailing_newline_devname_fails_end_to_end(self):
+        with self.assertRaises(vpt.TreeError):
+            vpt.validate(_tree(roots=[_root(name="ContactRoot\n")]))
+
+    def test_too_many_children_rejected(self):
+        kids = [_root(name=f"Child{i}") for i in range(vpt.MAX_CHILDREN + 1)]
+        with self.assertRaises(vpt.TreeError):
+            vpt.validate(_tree(roots=[_root(children=kids)]))
+
+    def test_empty_roots_rejected(self):
+        with self.assertRaises(vpt.TreeError):
+            vpt.validate(_tree(roots=[]))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/platform-dsar-policy-manage/scripts/validate-policy-tree.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Validate a DsarPolicy tree against the hard caps before authoring metadata.
+
+Checks (exits non-zero on the FIRST violation, printing it):
+  - children per path <= 10
+  - tree depth        <= 10   (a root path is depth 1)
+  - total nodes       <= 200  (roots + every descendant path)
+  - every developerName matches  [a-zA-Z]+[a-zA-Z0-9_]*
+
+Input: a JSON file describing the tree. Shape (see references/configure.md):
+
+  {
+    "developerName": "CustomerPortability",
+    "roots": [
+      {
+        "developerName": "ContactRoot",
+        "object": "Contact",
+        "fields": ["FirstName", "Email"],
+        "children": [
+          { "developerName": "ContactCases", "relationship": "Cases",
+            "object": "Case", "fields": ["Subject"], "children": [] }
+        ]
+      }
+    ]
+  }
+
+Usage:  python3 validate-policy-tree.py <tree.json>
+"""
+
+import json
+import re
+import sys
+
+MAX_CHILDREN = 10
+MAX_DEPTH = 10
+MAX_NODES = 200
+# \A ... \Z (not ^ ... $): $ also matches just before a trailing "\n", so a
+# developerName like "Foo\n" would slip through .match(). \Z anchors the true
+# end of the string and rejects any trailing newline.
+NAME_RE = re.compile(r"\A[a-zA-Z]+[a-zA-Z0-9_]*\Z")
+
+
+class TreeError(Exception):
+    pass
+
+
+def check_name(name, where):
+    if not isinstance(name, str) or not name:
+        raise TreeError(f"{where}: developerName is missing or not a string")
+    if not NAME_RE.match(name):
+        raise TreeError(
+            f"{where}: developerName {name!r} does not match [a-zA-Z]+[a-zA-Z0-9_]*"
+        )
+
+
+def walk(node, depth, path):
+    """Return the node count for this subtree; raise on the first violation."""
+    where = f"{path}"
+    check_name(node.get("developerName"), where)
+
+    if depth > MAX_DEPTH:
+        raise TreeError(
+            f"{where}: depth {depth} exceeds the {MAX_DEPTH}-level cap"
+        )
+
+    children = node.get("children") or []
+    if not isinstance(children, list):
+        raise TreeError(f"{where}: 'children' must be a list")
+    if len(children) > MAX_CHILDREN:
+        raise TreeError(
+            f"{where}: {len(children)} children exceeds the {MAX_CHILDREN}-per-path cap"
+        )
+
+    count = 1
+    for i, child in enumerate(children):
+        child_name = child.get("developerName", f"[{i}]") if isinstance(child, dict) else f"[{i}]"
+        if not isinstance(child, dict):
+            raise TreeError(f"{where} > child {i}: not an object")
+        count += walk(child, depth + 1, f"{path} > {child_name}")
+    return count
+
+
+def validate(tree):
+    if not isinstance(tree, dict):
+        raise TreeError("top-level JSON must be an object")
+    check_name(tree.get("developerName"), "DsarPolicy")
+
+    roots = tree.get("roots")
+    if not isinstance(roots, list) or not roots:
+        raise TreeError("'roots' must be a non-empty list of root paths")
+
+    total = 0
+    for i, root in enumerate(roots):
+        if not isinstance(root, dict):
+            raise TreeError(f"roots[{i}]: not an object")
+        root_name = root.get("developerName", f"[{i}]")
+        total += walk(root, 1, f"{root_name}")
+
+    if total > MAX_NODES:
+        raise TreeError(f"total nodes {total} exceeds the {MAX_NODES}-node cap")
+
+    return total
+
+
+def main(argv):
+    if len(argv) != 2:
+        print(f"usage: {argv[0]} <tree.json>", file=sys.stderr)
+        return 2
+    try:
+        with open(argv[1], "r", encoding="utf-8") as fh:
+            tree = json.load(fh)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: cannot read/parse {argv[1]}: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        total = validate(tree)
+    except TreeError as exc:
+        print(f"INVALID: {exc}", file=sys.stderr)
+        return 1
+
+    print(
+        f"OK: tree valid — {total} node(s), within caps "
+        f"(<= {MAX_CHILDREN} children/path, depth <= {MAX_DEPTH}, <= {MAX_NODES} nodes)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/skills/platform-flexipage-generate/SKILL.md

@@ -11,6 +11,10 @@ metadata:
       semver: ">=3.10.0"
     - tool: ["sf"]
       semver: ">=2.126.4"
+  mcpTools:
+    metadata-experts:
+      tools: ["execute_metadata_action"]
+      semver: ">=1.0.0"
 ---
 
 ## When to Use This Skill

package/skills/platform-list-view-generate/SKILL.md

@@ -4,6 +4,7 @@ description: "Use this skill when users need to create, generate, or validate Sa
 metadata:
   version: "1.0"
   domains: ["Platform"]
+  minApiVersion: "51.0"
 ---
 
 ## When to Use This Skill