@salesforce/afv-skills 1.46.0 → 1.48.0

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))