@salesforce/afv-skills 1.46.0 → 1.47.0

package/skills/platform-dsar-policy-manage/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: platform-dsar-policy-manage
+description: "Configure, run, and audit DsarPolicy Right-to-Portability exports end to end: author the data map over a subject's related records, resolve a request's subject (email/name/id) to a root-entity record, run an export against an ACTIVE policy (poll a couple of times, then ask before continuing; download once terminal), and read run history. Use when the user needs to set up, edit, execute, or inspect a DsarPolicy or Right-to-Portability (RTP) export, or audit which personal data a policy does not cover yet. TRIGGER when: the user configures a DsarPolicy or RTP data map, authors DsarPolicyPath or DsarPolicyField metadata, runs or exports a subject's portable data, downloads an RTP export file, reviews DsarPolicy run history, or asks what personal data the policy does not cover yet (coverage gap analysis). DO NOT TRIGGER when: the user wants to erase, delete, or remove a subject's records (RTP is portability export, not erasure — this skill deletes nothing), mask sandbox PII, or deploy unrelated metadata."
+metadata:
+  version: "1.7"
+  domains: ["Platform"]
+  minApiVersion: "68.0"
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# platform-dsar-policy-manage: DsarPolicy Right to Portability, end to end
+
+Operate a **`DsarPolicy`** — the metadata driving a **Right-to-Portability (RTP)** export — across
+its lifecycle: **configure** the tree, **run** an export, **audit** runs. A `DsarPolicy` is a
+*read/export map*: it names which of a subject's records an export collects. It **never deletes
+anything**. The value here is **judgment**, not XML plumbing.
+
+> **FIRST LINE OF EVERY RESPONSE — do not narrate the skill.** Your first output token is *work or
+> the answer*, never a play-by-play. Do **not** open with "This is a coverage-gap audit / Workflow
+> D…", "Let me read the skill's guide/mechanics…", "Per rule #1…", or "Let me discover the SOR…".
+> Don't name the workflow, announce which reference files you're about to read, or describe your
+> method before doing it — just start doing it (call the tool) and, when done, present the result.
+> This is load-bearing call #8, stated up front because it governs your very first token. A
+> plain-language sentence about *the user's data/org* is fine; a sentence about *the skill, its
+> workflows, rules, tools, or files* is not.
+
+## Load-bearing calls (get these right or the task fails)
+
+These override any leading phrasing in the request. Read them first, every time. **Call #1 is the
+literal first action of every task — before you pick a workflow, before any `sf` command.**
+
+1. **Route through the SOR tool FIRST — before any `sf`/endpoint call, no exceptions.** The very
+   first action of *every* task here — including a trivial read-only "does a policy exist / list the
+   policies" lookup — is to scan **this run's available tools** for a capability-routing tool exposing
+   **discover / describe / dispatch** verbs (project-codey / Headless 360 today; any host prefix such
+   as `mcp__<host>__discover`; **match the verb shape, not a fixed name**). If one is present, that is
+   the entry move: `discover → describe → dispatch` the **`DsarPolicyManager`** SOR (owner Privacy
+   Center; `isActive` gates execute/edit/delete) and reject look-alikes (data mask, generic consent,
+   subject *erasure*). Do **not** reach for `sf` first — grabbing `sf` on reflex because the task
+   "looks like a quick lookup" is the top recurring miss, and it is wrong even when it would work.
+   `sf` is the fallback **only** when no routing tool is in reach (checking `sf org list` to see which
+   orgs are authenticated locally is fine — that is a client-side auth check, not a SOR call). Every
+   `sf`/`salesforce-api-context` command shown in the workflows below is the *no-routing-tool*
+   spelling; when the routing tool is present, dispatch the equivalent operation through it instead.
+   Detail: `references/headless-sor.md`.
+2. **Export, never erasure.** A run produces an **export file**; it does not erase/redact/delete the
+   subject. If the request frames it as deletion ("remove them", "erase", "clear out"), **correct
+   that first** and never report the subject as erased. Erasure is a separate mechanism — if that's
+   the goal, say so and stop. You may still export if authorization is clear, after correcting the
+   premise.
+3. **Do not guess personal data.** Which objects/relationships hold *the subject's* data is the
+   **admin's** classification call. If the request delegates it ("figure out what counts", "wire the
+   whole thing up"), **do not author a guessed tree** — enumerate the decisions the admin must make
+   (roots; per-relationship follow/stop; fields), mark any proposal *pending admin disposition*. An
+   over-broad guess exports other people's records.
+4. **Caps are hard — name the cap and stop; don't graph-walk.** Tree caps: **10 children/path, depth
+   10, 200 nodes**. An unbounded request ("everything", "the whole graph") cannot fit. Do **not**
+   enumerate the object graph to "try" (never finishes, burns the turn). Name the specific cap
+   exceeded and offer a bounded alternative (split policies, prune branches). Never silently truncate.
+5. **Poll a couple of times, then ask — don't block on terminal.** The run handle serves status
+   **and** file. An early *getfile* returns `NOT_FOUND` / `"This file isn't ready yet"` — the
+   contract working, not a failure. Poll ≈2–3×; if still not terminal, **stop and ask the user
+   whether to keep polling** — don't loop. A run can sit non-terminal indefinitely on downstream
+   async processing — **platform / Tool Factory territory, not this skill's to diagnose or reach
+   into**; report status in plain terms (**running / completed / errored**) and let the user decide.
+   Never download before terminal. A **failed run can return HTTP 201** — read the **envelope /
+   `RequestStatus`** in the body, not the HTTP code. getfile segment is **`dsr`**, not `dsar`.
+6. **History is a read.** Run history = a **SOQL query over `DsarPolicyLog`**. Not `installListView`,
+   not a UI list; it starts no run.
+7. **Never auto-activate or republish.** Activation is a deliberate, human-confirmed step. Editing an
+   ACTIVE policy needs it deactivated first — **deactivate → edit → stop, report, get explicit user
+   confirmation before reactivating**. New policies stay INACTIVE until the user activates.
+   Auto-republishing breaks the reviewable audit trail disputes depend on.
+8. **Work silently — never narrate the skill's internals (applies to every workflow; see the
+   masthead above).** The user asked a domain question; answer it, don't describe how the skill
+   answers it. Run the tools and present the result — **no intermediate narration** of: that you are
+   about to read / are reading the skill's guide, mechanics, or reference files ("let me read the
+   skill's guide and mechanics"); **which workflow this is** ("this is a coverage-gap audit / Workflow
+   D", "Workflow C-style read") — the user does not think in workflow letters, so never name one;
+   which SOR/routing tool you're using or that you're "loading schemas / discovering / dispatching";
+   the load-bearing rule numbers ("per rule #1"); the reject-look-alikes step; the operation graph or
+   GET-vs-dispatch plumbing (`getAccessInfo`, `dispatch_readonly`, etc.). These steer *how you work* —
+   they are not status updates. (The harness still shows its own plain tool-call lines; that is fine —
+   just don't add your own play-by-play.) **What the user DOES see:** the final answer, and — where a
+   call requires it — a plain-language question (`AskUserQuestion`) or a short scope/consent line about
+   *their org* ("I only listed policies; I changed nothing", "this exports, it doesn't delete"). Rule
+   of thumb: a sentence about **their data/org** can be user-facing; a sentence about **the skill, its
+   workflows, steps, tools, rules, or files** stays internal. Workflow D's method preamble is the one
+   allowed "here's how I'll do it" line, and even it must be plain-language about *the audit approach*
+   ("I'll look one level out from your policy's objects and flag fields that might hold personal
+   data") — it names **no** workflow letter, rule, tool, or file. That preamble is *not* a licence to
+   say "this is Workflow D" or "let me read the mechanics".
+
+## The DsarPolicy object model
+
+Each entity is reached a **different** way — guessing the surface is the top time-sink.
+
+| Entity | What it is | How you reach it |
+|--------|-----------|------------------|
+| `DsarPolicy` | Policy shell + lifecycle (ACTIVE/INACTIVE) | **Metadata API** |
+| `DsarPolicyPath` | A tree node: a root object, or a parent→related relationship | **Metadata API** (child of `DsarPolicy`) |
+| `DsarPolicyField` | A field collected at a path | **Metadata API** (child of a path) |
+| `DsarPolicyLog` | Run log (one row per run) | **Standard SOQL** |
+| Execute an export | — | **Connect DSR endpoint** (`POST`) |
+| Status / getfile | — | **Connect DSR endpoint** on the handle; getfile segment `dsr` |
+
+Resolve the exact Connect route/version at run time via `salesforce-api-context` (or `sf`). Don't
+`sf sobject describe DsarPolicy*` — the tree is metadata; only `DsarPolicyLog` answers standard
+SOQL. On an MCP surface, each row is one `DsarPolicyManager` operation.
+
+## Pick the workflow (by the verb)
+
+| Want to… | Run | Ends when |
+|---|---|---|
+| Set up / edit a policy tree | **A — Configure** | Bounded policy authored INACTIVE; or an unbounded request's cap is named / an under-specified one's decisions enumerated — and stops |
+| Run an export for a subject | **B — Export** | Subject resolved to a root Id, run status read (running/completed/errored), file located on success — or, if still running after a couple polls, the user is asked whether to continue |
+| See past runs | **C — History** | Prior runs reported from `DsarPolicyLog`, no run started |
+| Find PII not yet covered | **D — Coverage gap** | Candidates surfaced with per-field reasons, disposition left to the admin — read-only |
+
+Mixed request → do the one asked; don't add an export to a configure, or a run to a history.
+
+**Every workflow below assumes call #1 is already done** — you have routed through the discover/
+describe/dispatch SOR tool (or confirmed none is in reach). The `sf`/`salesforce-api-context`
+commands in each workflow are the *no-routing-tool* spelling; with the routing tool present, dispatch
+the equivalent operation through it.
+
+## Workflow A — Configure
+
+Recipe (metadata shape, relationship/field resolution, lifecycle transitions): `references/configure.md`.
+
+1. **Classify first — short-circuit before any describe.** Three shapes; two never reach authoring:
+   - **Unbounded** ("everything", "whole graph") — can't fit caps. Don't describe/walk. Write the
+     **cap-refusal report** (call #3), stop.
+   - **Under-specified** — delegates classification, no root/field named. Don't author a guess.
+     Write the **elicitation report** (the admin's decisions; support **multiple roots**; proposals
+     *pending disposition*), stop.
+   - **Bounded & specified** — named roots/relationships/fields fitting the caps → continue.
+2. **Confirm type + describe named objects only** (don't assume names, don't expand beyond what's named):
+   ```bash
+   sf org list metadata --metadata-type DsarPolicy --target-org <alias> --json
+   sf sobject describe --sobject <NamedObject> --target-org <alias> --json
+   ```
+   If `DsarPolicy` can't be listed/described, surface it and stop (accepted terminal outcome).
+3. **Validate the tree** (don't eyeball caps/names):
+   ```bash
+   python3 scripts/validate-policy-tree.py <tree.json>
+   ```
+   Checks children≤10, depth≤10, nodes≤200, and devname `[a-zA-Z]+[a-zA-Z0-9_]*`.
+4. **Author metadata INACTIVE** under `${outputDir}`, faithful to the sanctioned strategy — add no
+   unapproved path, drop none approved.
+   > **Lifecycle gate:** INACTIVE to edit/delete, ACTIVE to execute. Change an ACTIVE policy by
+   > **deactivate → edit → STOP**; get explicit user confirmation before reactivating (call #7).
+5. **Deploy (best effort):** `sf project deploy start --source-dir <outputDir> --target-org <alias> --json`.
+   Deploy may fail where the type isn't fully enabled — surface the raw error + prerequisite; don't
+   fake success. The classification work is valid regardless.
+6. **Report** the outcome reached — **cap-refusal** / **elicitation** / **authored** — per
+   `references/report-format.md`. Never a truncated tree called "complete".
+
+## Workflow B — Run an export
+
+Endpoints, sample envelopes, poll/download sequence: `references/export-and-history.md`.
+
+- **B0. Resolve the subject.** Requests arrive as **email / name / id**, not a `dataSubjectId`.
+  Resolve to the **Id of a record whose type is a ROOT** of the chosen policy (Account / Contact /
+  Individual / Lead / User) — e.g. SOQL `Lead`/`Contact` by `Email`. Confirm the type **is a policy
+  root** (execute matches only the root subtree of the subject's type — a non-root subject exports
+  nothing). On **0 / many / non-root** matches, stop and report; never execute a guessed Id.
+- **B1. Preconditions.** Policy must be **ACTIVE** (else route to A). Resolve DSR routes via
+  `salesforce-api-context`.
+  - **Pick the policy deliberately:** named → use it; else the in-context policy; if none is
+    established or **multiple ACTIVE could match**, **ask to confirm** (e.g. *"Run `<policy>` for
+    `<subject>` — confirm?"*). Never pick silently.
+  - **Access:** on `401`/`403`, name the guard and stop — user perm `Consent.CAN_EXECUTE_DSAR_POLICY`,
+    org feature `Consent.hasDsarPortability`. State the poll-then-download ordering even on this
+    error path (accepted terminal outcome; don't retry blindly).
+- **B2. Consent gate + correct deletion framing (call #2).** If framed as deletion, correct it first
+  (export, not erasure). If authorization is ambiguous, **ask** via `AskUserQuestion`; clear
+  authorization → proceed.
+- **B3. Execute — trust the envelope, not the HTTP code.** POST execute, capture the **run handle**.
+  A failed run can return **HTTP 201** — read the envelope status; report failure if it says so.
+- **B4. Poll ≈2–3×, then ask; download only after terminal (call #5).** Poll the handle (or
+  `DsarPolicyLog.RequestStatus`). Early `NOT_FOUND` / "not ready" is expected. Still not terminal
+  after a couple polls → **stop and ask** whether to keep polling; don't loop (non-terminal =
+  downstream async, not this skill's to diagnose). Report **running / completed / errored**.
+- **B5. Download (terminal-success only) — segment `dsr`.** A `dsar` segment 404s. Report where the
+  export landed.
+- **B6. Report** per `references/report-format.md`: resolved subject (id + type) and policy chosen
+  (+ that you asked if ambiguous); consent confirmed; **export not deletion**; outcome from the
+  envelope / run status in plain terms; file location on success; poll ordering explicit (couple of
+  polls, file only after terminal, asked if still running). State the ordering even if preconditions
+  blocked the run.
+
+## Workflow C — History (a read)
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, DsarPolicyId, RequestStatus, CreatedDate FROM DsarPolicyLog WHERE DsarPolicyId = '<POLICY_ID>' ORDER BY CreatedDate DESC"
+```
+Report prior runs (when, status); "no prior runs" is valid. On absent log / `401`/`403`/`404`,
+surface the raw error + prerequisite. Don't execute the policy; don't use `installListView` / a UI list.
+
+## Workflow D — Coverage gap analysis (read-only audit)
+
+*"What personal data isn't covered yet?"* Read-only, deterministic — surfaces **candidates** for the
+admin; classifies nothing, adds/activates nothing. Script + rubric: `references/gap-analysis-guide.md`;
+mechanics: `references/gap-scan.md`.
+
+1. **Open with the plain-language method line (call #8)** — one sentence in the user's terms: from
+   the policy's objects, look **one level** out and flag fields that *may* be PII, **with a reason
+   each**; the admin decides. Do **not** say "Workflow D", "coverage-gap audit", or "let me read the
+   mechanics" — just state the approach in plain words and start.
+2. **Read current coverage** (read-only) — gaps are relative to it.
+3. **Scan one hop only, and cap the breadth** — describe each root + **at most ~5** of its
+   most privacy-relevant one-hop objects; depth-1 default, don't recurse. **Never read a raw
+   `--json` describe into the turn** — a full describe is ~100KB and the accumulated payloads
+   overflow the event stream, truncating the run before it writes the report (the top failure here).
+   Project every describe to `{name,type,label}` first (see `references/gap-scan.md`). If the
+   policy/type can't be read (feature off — the accepted env path), **stop at a single projected
+   root describe**; don't fan out. Write the report from the root + a couple of one-hop describes,
+   name the objects you skipped, offer them via the depth gate. **The written report is the
+   deliverable — draft it early and write it; don't gather everything first.**
+4. **Flag candidates with a per-field reason** — compliance metadata > field type > name semantics.
+   Never "this *is* PII" (call #3).
+5. **Report transparently** — objects scanned, each candidate + reason, covered vs newly surfaced,
+   and the **one-level limit** stated (even when empty).
+6. **Gate depth** — go deeper only on explicit confirmation (warn: large output, heavy cost).
+7. **Disposition, don't mutate** — ask which to add; adding routes to Workflow A (INACTIVE, stops for
+   confirmation before reactivating — call #7).
+
+## Quick rules & gotchas
+
+| Situation | Do |
+|---|---|
+| **Starting ANY task (even a trivial "list/does-a-policy-exist" read)** | **FIRST** scan this run's tools for a discover/describe/dispatch routing tool (project-codey/Headless 360; any `mcp__<host>__…` name — match the verb shape). Present → `discover`/`describe`/`dispatch` the `DsarPolicyManager` SOR. Do NOT open with `sf` on reflex. `sf` only when no routing tool is in reach (`sf org list` for local auth is exempt) |
+| "Capture everything / whole graph" | Exceeds caps (10/10/200) — name the cap, offer split/prune; don't walk the graph |
+| "What PII are we missing?" | Workflow D — read-only depth-1; candidates + reason; disposition to admin; add/activate nothing |
+| Subject given by email/name, no Id | Resolve first (B0): query the policy's root entities; confirm a root type; 0 / many / non-root → stop |
+| Multiple ACTIVE policies could match | Confirm which with the user before running — never silent |
+| Run stuck `In Progress` after a couple polls | Downstream async (Tool Factory / platform), not the skill's to diagnose — report *still running*, ask whether to keep polling; don't loop |
+| getfile "not ready" / `NOT_FOUND` | Expected pre-terminal — poll again; not a failure |
+| HTTP 201 on execute | Not success — read the envelope status |
+| getfile 404 | Segment must be `dsr`, not `dsar` |
+| Just edited an ACTIVE policy | Don't auto-reactivate — stop, report, get explicit confirmation (call #6) |
+| `sf sobject describe DsarPolicy` empty | Tree is Metadata-API; only `DsarPolicyLog` answers SOQL |
+| `DsarPolicy` type absent | Surface + stop; don't fabricate |
+| `401`/`403`/`404` or missing type | Name the prerequisite and stop; no blind retries |
+
+## Output (write to `${outputDir}/report.md`)
+
+Report only the workflow you ran; each command once; the key result in the first screenful.
+**Be concise** — state each load-bearing point (poll ordering, export-not-deletion, the
+one-level limit) **once**, not restated across an intro, an aside, and a next-steps list; keep it
+well under ~150 lines and don't paste exhaustive per-object dumps. On a preflight-error path (feature
+/ policy / subject absent), name the blocker + prerequisite, state the ordering once, and stop —
+short. Per-workflow contracts (incl. the INACTIVE / confirmed-reactivation lifecycle and the poll
+ordering): `references/report-format.md`.
+
+## Reference index
+
+| File | When |
+|---|---|
+| `references/headless-sor.md` | MCP surface: discover→describe→dispatch the SOR, reject look-alikes, `sf` fallback |
+| `references/configure.md` | Metadata shape, root/relationship resolution, `<tree.json>` input, lifecycle, multi-root |
+| `references/export-and-history.md` | DSR execute/status/getfile routes, envelopes, poll sequence, `dsr` segment, history query |
+| `references/report-format.md` | Per-workflow report contracts |
+| `references/gap-analysis-guide.md` | Workflow D: audit script, steps, candidate-flagging rubric |
+| `references/gap-scan.md` | Workflow D mechanics: one-hop enumeration, diff, depth gate, report shape |
+| `scripts/validate-policy-tree.py` | Deterministic cap + devname check before authoring |

package/skills/platform-dsar-policy-manage/references/configure.md

@@ -0,0 +1,106 @@
+# Configure a DsarPolicy — authoring reference
+
+Deep detail for **Workflow A**. Read this when you actually author the policy tree. The judgment
+(refuse-to-guess, cap-and-stop) lives in `SKILL.md`; this file is the mechanics.
+
+## The object model you author
+
+A `DsarPolicy` is a **tree** of paths rooted on the object(s) that identify the data subject.
+
+```text
+DsarPolicy                     (the shell: DeveloperName, MasterLabel, lifecycle state)
+└── DsarPolicyPath  (root)     (a root object the subject is identified on, e.g. Contact)
+    ├── DsarPolicyField        (a field collected at this path)
+    ├── DsarPolicyField
+    └── DsarPolicyPath (child) (a relationship FROM this object TO a related object)
+        └── DsarPolicyField
+```
+
+- **`DsarPolicyPath`** is either a **root** (a top-level object the subject is identified on) or a
+  **relationship edge** from a parent object to a related object. Multiple roots are allowed — a
+  subject identified on both `Contact` and `Lead` gets one root path each.
+- **`DsarPolicyField`** names a field to include in the export at its parent path.
+- All three are **Metadata API** entities. `DsarPolicyLog` (run history) is **not** part of this
+  tree — it is standard SOQL (see `export-and-history.md`).
+
+## Hard caps (the validator enforces these)
+
+| Cap | Value |
+|-----|-------|
+| Children per path | **10** |
+| Tree depth | **10** |
+| Total nodes (paths) | **200** |
+| Developer name | must match `[a-zA-Z]+[a-zA-Z0-9_]*` |
+
+An unbounded request ("everything reachable from Account", "follow every relationship") will
+exceed one of these. **Name the specific cap and stop** — do not start walking the object graph to
+prove it (that times the turn out). Offer a bounded alternative: split into multiple policies, or
+prune to the branches that actually hold the subject's data.
+
+## Resolve names — never assume
+
+Before authoring, resolve the real relationship and field API names against the org schema:
+
+```bash
+sf sobject describe --sobject Contact --target-org <alias> --json      # fields + child relationships
+sf sobject describe --sobject Account --target-org <alias> --json
+```
+
+Use the `relationshipName`/`field` values from the describe output verbatim. A path that names a
+relationship the org does not have will fail deploy.
+
+## The `<tree.json>` shape for the validator
+
+`scripts/validate-policy-tree.py` takes a JSON file describing the tree you intend to author. It
+checks the caps and name regex **before** you write metadata, so a bad tree fails fast and cheap.
+
+```json
+{
+  "developerName": "CustomerPortability",
+  "roots": [
+    {
+      "developerName": "ContactRoot",
+      "object": "Contact",
+      "fields": ["FirstName", "LastName", "Email"],
+      "children": [
+        {
+          "developerName": "ContactCases",
+          "relationship": "Cases",
+          "object": "Case",
+          "fields": ["Subject", "Description"],
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `developerName` on every node → checked against `[a-zA-Z]+[a-zA-Z0-9_]*`.
+- `children` nesting → depth check (root = depth 1).
+- child count per node → 10-per-path check.
+- total node count (roots + all descendants) → 200-node check.
+
+The script exits non-zero and prints the first violation. Fix the tree and re-run until it exits 0,
+then author metadata that mirrors it exactly.
+
+## Lifecycle
+
+- A policy is authored **INACTIVE**. It must be **ACTIVE** to execute (Workflow B).
+- **INACTIVE** to **edit or delete**; **ACTIVE** to **execute**.
+- To change an ACTIVE policy: **deactivate → edit → stop.** Never edit in place while ACTIVE, and
+  **never reactivate on your own** — report the edit and get **explicit user confirmation** before
+  reactivating/publishing. Auto-republishing breaks the reviewable audit trail that
+  portability/erasure disputes rely on.
+- Authoring, editing, or deleting the *policy* **never** touches the data subject's records — it
+  only changes the export map. This is the export-not-deletion guardrail restated for configure.
+
+## Deploy
+
+```bash
+sf project deploy start --source-dir <outputDir> --target-org <alias> --json
+```
+
+Deploy can legitimately fail where `DsarPolicy`/sub-entities are not fully enabled on the org.
+Surface the raw error and name the prerequisite; the classification strategy and validated tree are
+still the deliverable and belong in the report regardless of deploy outcome.

package/skills/platform-dsar-policy-manage/references/export-and-history.md

@@ -0,0 +1,123 @@
+# Run an export & read history — reference
+
+Deep detail for **Workflow B** (export) and **Workflow C** (history). Judgment (export-not-erasure,
+consent, poll-before-download) lives in `SKILL.md`; this file is the mechanics.
+
+## Resolve the DSR routes at run time
+
+The execute / status / getfile routes are Connect DSR endpoints. Resolve them against the running
+org — do not hardcode a version segment.
+
+```text
+salesforce-api-context   # MCP: resolve the current DSR execute/status/getfile routes + API version
+```
+
+Or discover via `sf`:
+
+```bash
+sf api request rest '/services/data' --target-org <alias>        # available API versions
+```
+
+## Resolve the subject (B0) — before anything else
+
+A portability request names the subject by **email / name / external id**, not a `dataSubjectId`.
+Resolve it to a record whose entity type is a **ROOT** of the policy you will run
+(Account / Contact / Individual / Lead / User). Query the roots for the identifier, e.g.:
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Name, Email FROM Lead WHERE Email = '<subject-email>'"
+```
+
+Confirm the match is a **root type of the chosen policy** — execute matches only the root subtree of
+the subject's type, so a subject whose type is not a policy root exports nothing. On **0 matches,
+multiple matches, or a non-root type**, stop and report — never execute against a guessed Id.
+
+## Pick the policy
+
+If the request names a policy, use it; if not, use the policy established in the working context. If
+none is established or **more than one ACTIVE policy could match the subject**, ask the user to
+confirm which to run (surface the best match as a confirmation) before executing — never pick
+silently.
+
+## Preconditions
+
+- Policy must be **ACTIVE** (INACTIVE cannot execute — route to Workflow A to activate).
+- Run guards (name the missing one and stop on `401`/`403`; do not loop):
+  - user permission `Consent.CAN_EXECUTE_DSAR_POLICY`
+  - org feature `Consent.hasDsarPortability`
+
+## Execute — capture the handle, trust the envelope
+
+```bash
+sf api request rest '<DSR_EXECUTE_ROUTE>' --method POST \
+  --body '{"policy":"<POLICY_DEVNAME>","subject":"<SUBJECT_IDENTIFIER>"}' \
+  --target-org <alias>
+```
+
+- Capture the **run handle** from the response — you need it for both status and getfile.
+- **A failed run can return HTTP 201.** The real outcome is the **status field inside the
+  envelope**, not the HTTP code. Parse the body; if it reports failure, report failure.
+- This is an **export**, not a deletion. It produces a file; it removes nothing. If the request
+  framed it as erasure, you have already corrected that (SKILL.md call #1) before reaching here.
+
+Example failure envelope on a 201:
+
+```json
+{ "status": "FAILED", "message": "…", "runId": "…" }   // HTTP 201, but FAILED — report the failure
+```
+
+## Poll a couple of times — then ask; download only after terminal
+
+Poll the **same handle** (or `DsarPolicyLog.RequestStatus` for the run) for a terminal status
+(`COMPLETED` / `FAILED` or the org's equivalents). Only a terminal-success run has a downloadable
+file.
+
+```bash
+sf api request rest '<DSR_STATUS_ROUTE_FOR_HANDLE>' --method GET --target-org <alias>
+# or, by handle, over the run log:
+sf data query --target-org <alias> \
+  --query "SELECT Id, RequestStatus, CompletionDatetime, DsarError FROM DsarPolicyLog WHERE Id = '<handle>'"
+```
+
+Poll a **small, fixed number of times** (≈2–3). If the run is still not terminal, **stop and ask the
+user whether to keep polling** — do **not** loop to terminal. A run can sit non-terminal
+indefinitely on downstream async processing; **that is platform / Tool Factory territory, not this
+skill's to diagnose or reach into** (don't go hunting message-queue internals). Report the status in
+plain terms — **running / completed / errored** — from the run row; the user does not need to know
+which internal entity or queue backs it.
+
+**Do not quote a completion time (e.g. "~1s") — even if a data source suggests one.** Runtime
+varies by org provisioning; poll to terminal or hand off the handle. Never promise a duration.
+
+An early *getfile* returns `NOT_FOUND` / `"This file isn't ready yet"`. **That is the contract
+working, not a failure** — poll again; do not treat it as a completed or errored run.
+
+## Download the export file — segment is `dsr`
+
+Only after terminal-success:
+
+```bash
+sf api request rest '<DSR_GETFILE_ROUTE_FOR_HANDLE>' --method GET --target-org <alias>
+```
+
+- The getfile path segment is **`dsr`**, not `dsar`. A `dsar` segment 404s. Double-check the
+  segment before concluding the file is missing.
+- Report where the export landed.
+
+## Workflow C — history is a SOQL read
+
+Run history lives in `DsarPolicyLog`, a standard object. Read it with SOQL — it is **not** an
+`installListView` call, not a UI list, and it **never** starts a run.
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, DsarPolicyId, RequestStatus, CreatedDate, CompletionDatetime \
+           FROM DsarPolicyLog \
+           WHERE DsarPolicyId = '<POLICY_ID>' \
+           ORDER BY CreatedDate DESC"
+```
+
+- Report each prior run (when it ran, its status). "No prior runs" is a valid, correct result.
+- If `DsarPolicyLog` is absent or the query returns `401`/`403`/`404`, surface the raw error and
+  name the prerequisite — an accepted terminal outcome. Do not fall back to executing the policy.

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.