@salesforce/afv-skills 1.67.0 → 1.68.0

package/skills/platform-policy-rule-generate/references/examples/LastCharactersFieldMasking/policyRuleDefinitions/LastCharactersFieldMasking_Rule_1.policyRuleDefinition

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <action>Read</action>
+    <category>TRANSFORM_POLICY_RULE_DEFINITION</category>
+    <effect>Transform</effect>
+    <label>Rule 1</label>
+    <policyRuleDefinitionSetName>LastCharactersFieldMasking</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceExpression>
+        <transformExpression>
+            <argument>
+                <type>STRING</type>
+                <value>12</value>
+            </argument>
+        </transformExpression>
+        <type>ARGLIST</type>
+        <version>1</version>
+    </resourceExpression>
+    <resourceScopeType>FIELD</resourceScopeType>
+    <resourceTransform>LAST_N_CHARS_RESOURCE_TRANSFORM</resourceTransform>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <policyRuleValueSet>
+                <valueText>FIELD</valueText>
+            </policyRuleValueSet>
+            <resourcePath>ENTITYTYPE</resourcePath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_NONE</operator>
+            <policyRuleValueSet>
+                <valueReference>cust_perm1</valueReference>
+                <valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>
+            </policyRuleValueSet>
+            <principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>EQUALS</operator>
+            <policyRuleValueSet>
+                <valueText>ewstrdthfg</valueText>
+            </policyRuleValueSet>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Division</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <principalPath>SCALAR_ATTRIBUTE</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <policyRuleValueSet>
+                <valueReference>DataGovernanceTags.EthicalAiStandards.EthicalAI.Caste</valueReference>
+                <valueReferenceType>STANDARD_TAG</valueReferenceType>
+            </policyRuleValueSet>
+            <resourcePath>TAG</resourcePath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <policyRuleValueSet>
+                <valueReference>DataGovernanceClassifications.DataCategorization.DataSensitivity.DataSensitivity</valueReference>
+                <valueReferenceType>STANDARD_CLASSIFICATION</valueReferenceType>
+            </policyRuleValueSet>
+            <resourcePath>CLASSIFICATION</resourcePath>
+        </conditions>
+        <conjunctionExpression>(AND 1 (OR 2 3) (OR 4 5))</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>

package/skills/platform-policy-rule-generate/references/examples/PrincipalFieldMatchRLS/package.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>PrincipalFieldMatchRLS_Rule_1</members>
+        <name>PolicyRuleDefinition</name>
+    </types>
+    <types>
+        <members>PrincipalFieldMatchRLS</members>
+        <name>PolicyRuleDefinitionSet</name>
+    </types>
+    <version>{API_VERSION}</version>
+</Package>

package/skills/platform-policy-rule-generate/references/examples/PrincipalFieldMatchRLS/policyRuleDefinitionSets/PrincipalFieldMatchRLS.policyRuleDefinitionSet

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinitionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <builderCompatible>false</builderCompatible>
+    <builderValidated>false</builderValidated>
+    <label>PrincipalFieldMatchRLS</label>
+</PolicyRuleDefinitionSet>

package/skills/platform-policy-rule-generate/references/examples/PrincipalFieldMatchRLS/policyRuleDefinitions/PrincipalFieldMatchRLS_Rule_1.policyRuleDefinition

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <action>Read</action>
+    <category>RECORD_POLICY_RULE_DEFINITION</category>
+    <effect>Permit</effect>
+    <label>Rule 1</label>
+    <policyRuleDefinitionSetName>PrincipalFieldMatchRLS</policyRuleDefinitionSetName>
+    <policyRuleResourceDomains>
+        <resourceDomain>contacts_to_importcsv__dlm</resourceDomain>
+    </policyRuleResourceDomains>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>RECORD</resourceScopeType>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>EQUALS</operator>
+            <policyRuleValueSet>
+                <valueText>qsdfad</valueText>
+            </policyRuleValueSet>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Division</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <principalPath>SCALAR_ATTRIBUTE</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>NOT_EQUALS</operator>
+            <policyRuleValueSet>
+                <valueText>qwefasdf</valueText>
+            </policyRuleValueSet>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Department</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <principalPath>SCALAR_ATTRIBUTE</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>EQUALS</operator>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Email</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <resourcePath>RECORDFIELD</resourcePath>
+            <valueDomain>contacts_to_importcsv__dlm:EMAIL__c</valueDomain>
+            <valuePrincipalPath>SCALAR_ATTRIBUTE</valuePrincipalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>EQUALS</operator>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Title</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <resourcePath>RECORDFIELD</resourcePath>
+            <valueDomain>contacts_to_importcsv__dlm:FNAME__c</valueDomain>
+            <valuePrincipalPath>SCALAR_ATTRIBUTE</valuePrincipalPath>
+        </conditions>
+        <conjunctionExpression>(AND (OR 1 2) (AND 3 4))</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>

package/skills/platform-policy-rule-generate/references/examples/TaggedObjectAccess/package.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>TaggedObjectAccess_Rule_1</members>
+        <name>PolicyRuleDefinition</name>
+    </types>
+    <types>
+        <members>TaggedObjectAccess</members>
+        <name>PolicyRuleDefinitionSet</name>
+    </types>
+    <version>{API_VERSION}</version>
+</Package>

package/skills/platform-policy-rule-generate/references/examples/TaggedObjectAccess/policyRuleDefinitionSets/TaggedObjectAccess.policyRuleDefinitionSet

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinitionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>TaggedObjectAccess</label>
+</PolicyRuleDefinitionSet>

package/skills/platform-policy-rule-generate/references/examples/TaggedObjectAccess/policyRuleDefinitions/TaggedObjectAccess_Rule_1.policyRuleDefinition

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <action>TupleRead</action>
+    <category>GOVERNANCE_POLICY_RULE_DEFINITION</category>
+    <effect>Permit</effect>
+    <label>Rule 1</label>
+    <policyRuleDefinitionSetName>TaggedObjectAccess</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>ANY</resourceScopeType>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <policyRuleValueSet>
+                <valueText>OBJECT</valueText>
+            </policyRuleValueSet>
+            <resourcePath>ENTITYTYPE</resourcePath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <policyRuleValueSet>
+                <valueText>FIELD</valueText>
+            </policyRuleValueSet>
+            <resourcePath>ENTITYTYPE</resourcePath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <policyRuleValueSet>
+                <valueReference>cust_perm1</valueReference>
+                <valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>
+            </policyRuleValueSet>
+            <principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>EQUALS</operator>
+            <policyRuleValueSet>
+                <valueText>Finance</valueText>
+            </policyRuleValueSet>
+            <principalExpression>
+                <soqlTarget>
+                    <select>Department</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
+            <principalPath>SCALAR_ATTRIBUTE</principalPath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <policyRuleValueSet>
+                <valueReference>DataGovernanceTags.FinancialData.AccountInfo.AccountInfo</valueReference>
+                <valueReferenceType>STANDARD_TAG</valueReferenceType>
+            </policyRuleValueSet>
+            <resourcePath>TAG</resourcePath>
+        </conditions>
+        <conjunctionExpression>(AND (OR 1 2) (AND 3 4) (AND 5))</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>

package/skills/platform-policy-rule-generate/references/headless-transport.md

@@ -0,0 +1,87 @@
+# Headless Transport — `/headless/metadata` MD-CRUD
+
+The transport for H360 policy-rule **create / read / update** is the headless-360 MCP server's `/headless/metadata` MD-CRUD endpoint, called through `dispatch` (for CREATE/UPDATE) and `dispatch_readonly` (for the GET read-back). **DELETE is a different surface**: Core has no real metadata delete (a `/headless/metadata` DELETE 405s or no-ops), so a policy is deleted over the Data 360 MCP Data Governance Access Policy tool `d360_data_governance_access_policy_delete` (see the DELETE section below). There is no `sf`/MDAPI fallback — when the headless path is unavailable or a type/op is not onboarded, surface the gap to the operator.
+
+Always `discover` and `describe` the operation before calling it; the shapes below are the confirmed request/response contract, not a substitute for checking `describe` against the connected server version.
+
+**Exception for `PolicyRuleDefinition`/`PolicyRuleDefinitionSet`:** these two types have no dedicated MD-CRUD operation to describe — `discover` only surfaces the `platform-policy-rule-generate` SOR itself, whose `describe` shows `"steps": []` and `"referenced_operation_ids": []`. There is nothing to describe for this specific pair. Treat that empty result as expected, not as a blocker or an error: fall through to the request/response contract documented in this file, which is authoritative for these two types. Still run `discover`/`describe` first for any other metadata type this skill might touch.
+
+## Request Shapes
+
+All four requests target a **bare** `/headless/metadata` URL, with no version segment:
+
+```text
+url: /headless/metadata
+```
+
+The server resolves the API version automatically — `ORG_API_VERSION` is NOT required for this MCP path (confirmed: a bare-URL dispatch response echoed `v67.0` without the caller ever supplying it). A versioned URL (`/services/data/v{ORG_API_VERSION}/headless/metadata`) also works if `ORG_API_VERSION` is already known, but is not required on the MCP path — prefer the bare URL and let the server resolve it. Do not attempt an unversioned `dispatch_readonly GET /services/data` to discover the version over MCP — that route is not MCP-reachable (`ROUTE_NOT_FOUND`).
+
+### CREATE — `dispatch`, `method: POST`
+
+```json
+{
+  "method": "POST",
+  "url": "/headless/metadata",
+  "body": {
+    "type": "PolicyRuleDefinitionSet",
+    "fullName": "<name>",
+    "xmlRep": "<single-line XML>"
+  }
+}
+```
+
+Response: `{"results":[{"success":true,"id":"...","fullName":"...","errors":[],...}]}`.
+
+### UPDATE — `dispatch`, `method: PUT`
+
+Identical body shape to CREATE, with `"method": "PUT"`.
+
+### READ / verify — `dispatch_readonly`, `method: GET`
+
+```json
+{
+  "method": "GET",
+  "url": "/headless/metadata",
+  "queryParams": { "type": "<Type>", "fullName": "<name>" }
+}
+```
+
+The response body contains `xmlRep` with the persisted XML. Use this as the verification step after every CREATE/UPDATE, and to confirm the UI-renderable-contract check (see `SKILL.md` step 12): the parent set's `xmlRep` must carry server-added `<builderCompatible>false</builderCompatible>` and `<builderValidated>false</builderValidated>` even though neither was authored.
+
+### DELETE — Data 360 MCP `d360_data_governance_access_policy_delete` (NOT `/headless/metadata`)
+
+Delete is **not** a `/headless/metadata` verb. Core has no real metadata delete — a `/headless/metadata` DELETE `405`s, and the metadata team's interim delete is a no-op `200` that removes nothing. Route deletes over the Data 360 MCP **Data Governance Access Policy** surface instead:
+
+```text
+Data 360 MCP: execute(tool=d360_data_governance_access_policy_delete, params={ "name": "<setDeveloperName>" })
+```
+
+A `PolicyRuleDefinitionSet` created via this skill surfaces as an **Access Policy** keyed by its developer name. `access_policy_delete` is a **whole-policy delete** — one call removes the policy **and every embedded rule** (its `PolicyRuleDefinition` members). Consequences:
+
+- There is **no leaf-before-parent ordering** and **no discrete single-rule delete**. To drop a single rule while keeping the policy, re-author the surviving rule set via `d360_data_governance_access_policy_rule_replace`.
+- Hand-authored sets are `builderCompatible: false`, so `d360_data_governance_access_policy_list` needs `includeIncompatible: true` to enumerate them; `access_policy_get` and `access_policy_delete` address them by `name` regardless.
+- Confirm the delete with `d360_data_governance_access_policy_get` by `name`: a not-found result (or the policy being absent from an `includeIncompatible` list) is the success signal.
+
+There is no `sf` CLI fallback. On the off-core Data Cloud path this delete can fail on DC connectivity — surface that as a provisioning gap to the operator.
+
+## `xmlRep` Newlines — Flatten Defensively
+
+The skill's generated `.policyRuleDefinition`/`.policyRuleDefinitionSet` XML is pretty-printed with newlines. Whether a multi-line `xmlRep` survives depends on the caller's transport: when the `dispatch` tool takes `body` as a structured JSON object and the client serializes the newlines as proper `\n` string escapes, a multi-line `xmlRep` is accepted and persists cleanly (confirmed live: a pretty-printed set POSTed through the headless-360 MCP `dispatch` tool returned `success:true` and read back intact — the server normalizes formatting on storage regardless). The `'body' must be a JSON object, got an unexpected type` 400 comes from a client/transport that lets a raw, unescaped newline reach the JSON body, not from the server rejecting multi-line XML per se.
+
+Because that failure mode is transport-dependent and invisible from inside the skill, flatten `xmlRep` to a single line as the last step before dispatch anyway — it is always accepted and sidesteps any client that mangles newlines. Flatten (e.g. strip newlines and collapse redundant whitespace between tags) without otherwise altering the XML content.
+
+## Transient Retry
+
+The `'body' must be a JSON object` error can also appear spuriously on an otherwise-valid body. Treat a single occurrence as a flaky tool-arg serialization glitch: retry the identical clean body once before concluding the shape is unsupported.
+
+## HTTP Error Taxonomy
+
+| Status / error | Meaning | Action |
+|---|---|---|
+| `400 FIELD_INTEGRITY_EXCEPTION "Not available for deploy for this organization"` | Type/op is on the MD-CRUD allowlist, but the org lacks the feature/perm provisioning to deploy this metadata type | Org setup gap, not a skill or transport problem — surface it to the operator; do not fall back to CLI on this error alone (CLI will hit the same org gate). |
+| `400 UNSUPPORTED_OPERATION` | The type/op is genuinely not on the MD-CRUD allowlist | Onboarding gap — surface it to the operator; there is no CLI fallback for this workflow. |
+| `404` (on GET) | Type/op is allowlisted; the named member does not exist | Expected result for a not-yet-created component — not an error. |
+| `405` / no-op `200` (on a `/headless/metadata` DELETE) | Core has no real metadata delete — the verb 405s, and the interim delete is a no-op 200 that removes nothing | Do not delete via `/headless/metadata`. Route the delete over the Data 360 MCP `d360_data_governance_access_policy_delete` tool instead (see the DELETE section above). |
+| DC-connectivity error (on the Data 360 Access Policy delete) | The off-core Data Cloud delete path failed on DC connectivity | Provisioning gap — surface it to the operator; there is no `sf` CLI fallback. |
+
+See `references/deploy-errors.md` for the full server-side error taxonomy (all errors surface on the `dispatch` path).

package/skills/platform-policy-rule-generate/references/policy-schema-full.md

@@ -4,7 +4,7 @@
 
 ## Path Enums
 
-> **Surface principle.** The MDAPI surface is a narrower set of `*Type` enums (`RulePrincipalPathType`, `RuleResourcePathType`, `RuleContextPathType`) than what the runtime honors at evaluation time. Values that appear at runtime but are not in the MDAPI `*Type` enums are **not authorable via MDAPI** — use a runtime RuleProvider for those.
+> **Surface principle.** Prefer shapes that have been retrieved and round-trip validated at the target API version. Enum lists alone do not establish authorability.
 
 ### `<principalPath>` / `<valuePrincipalPath>` — `RulePrincipalPathType` (6 values)
 
@@ -17,7 +17,7 @@
 | `USER_ROLE_ID` | Principal role ID |
 | `RBAC_TAGS` | Principal RBAC tags |
 
-Outside contract (not in `RulePrincipalPathType`): `IS_INTERNAL`, `CONTACT_ID`, `SCALAR_ATTRIBUTE`, `PLURAL_ATTRIBUTE`, `PLACEHOLDER`. Use a runtime RuleProvider for these.
+`SCALAR_ATTRIBUTE` is not listed in the six-value table above, but it is a confirmed, deployable, Policy Builder-compatible principal path: it is how the Data Governance UI itself creates principal scalar-attribute conditions, which is why it appears throughout retrieved API 69.0 OLS, FLS, masking, and RLS evidence when paired with `SOQLTARGETLISTEXPR`. Generate it directly in normal author mode whenever the request needs a principal-attribute comparison. The other unpublished values — `IS_INTERNAL`, `CONTACT_ID`, `PLURAL_ATTRIBUTE`, `PLACEHOLDER` — remain unconfirmed; do not generate those unless the target release publishes them or a separate approved creation path establishes authorability.
 
 ### `<resourcePath>` / `<valueResourcePath>` — `RuleResourcePathType` (16 values)
 
@@ -26,7 +26,7 @@ Outside contract (not in `RulePrincipalPathType`): `IS_INTERNAL`, `CONTACT_ID`,
 | `NAMESPACE` | Resource namespace |
 | `ENTITY` | Entity (object) reference |
 | `FIELD` | Field reference |
-| `ENTITYTYPE` | Entity type — pair with `IS` operator and `{"t":"Text","v":"FIELD"}` literal |
+| `ENTITYTYPE` | Entity type — pair with `IS` and `valueText` set to `OBJECT` or `FIELD` as shown in retrieved examples |
 | `ENTITYKIND` | Entity kind bits |
 | `FIELDKIND` | Field kind bits |
 | `DATASPACE` | Resource dataspace |
@@ -48,7 +48,7 @@ Outside contract (not in `RulePrincipalPathType`): `IS_INTERNAL`, `CONTACT_ID`,
 
 Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERSION_ID` (IDENTIFIED_RECORD / agentic — runtime RuleProvider only).
 
-> `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` in `<valuePrincipalPath>` are outside `RulePrincipalPathType` — not authorable via MDAPI for new work.
+`SCALAR_ATTRIBUTE` is confirmed deployable and UI-compatible per DG UI source (this is how the builder itself authors the condition, not established by a per-shape round-trip) for principal scalar-attribute comparisons even though it is absent from the published enum table above; generate it directly in normal author mode.
 
 ---
 
@@ -96,9 +96,16 @@ Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERS
 
 Three fields (all optional at schema level, but a non-empty value set needs at least one):
 
-### Literal values — `<valueString>`
+### Literal values — `<valueText>` and `<valueString>`
 
-For typed literals, embed JSON (escape `"` to `&quot;`):
+Retrieved API 69.0 policies use `valueText` for entity type and scalar text:
+
+```xml
+<valueText>FIELD</valueText>
+<valueText>Toxico</valueText>
+```
+
+Older fixture-only typed literals use JSON in `valueString` (escape `"` to `&quot;`):
 ```xml
 <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;FIELD&quot;}</valueString>
 <valueString>{&quot;t&quot;:&quot;Boolean&quot;,&quot;v&quot;:true}</valueString>
@@ -122,7 +129,7 @@ For plain string equality:
 | `CUSTOM_PERMISSION` | Custom permission | `principalPath=ASSIGNED_PERMISSIONS_PATH` |
 | `DATASPACE` | Dataspace | `resourcePath=DATASPACE` or `contextPath=SESSION_DATASPACE` |
 
-> **Tag/classification dev names are NOT free-form.** The deploy-time validator checks `<valueReference>` against the org's taxonomy. To find the exact string: `sf project retrieve start --target-org <alias> --metadata "PolicyRuleDefinition:<existing-rule-name>"` and copy `<valueReference>` verbatim.
+> **Tag/classification dev names are NOT free-form.** The deploy-time validator checks `<valueReference>` against the org's taxonomy. Build the `<valueReference>` from a Data 360 MCP tag/classification lookup per `reference-resolution.md#constructing-valuereference-for-standard_tag--standard_classification`, or read a known-good rule back with `dispatch_readonly` GET `/headless/metadata?type=PolicyRuleDefinition&fullName=<existing-rule-name>` and copy `<valueReference>` from the returned `xmlRep`. Never use the `sf` CLI.
 
 Multiple `<policyRuleValueSet>` siblings inside one condition are OR-combined.
 
@@ -146,14 +153,14 @@ Multiple `<policyRuleValueSet>` siblings inside one condition are OR-combined.
     <version>1</version>
     <transformExpression>
         <argument>
-            <type>NUMBER</type>
+            <type>STRING</type>
             <value>4</value>
         </argument>
     </transformExpression>
 </resourceExpression>
 ```
 
-`TransformExpressionArgumentType` = `STRING` or `NUMBER`. Use when `<resourceTransform>` takes parameters (e.g. `LAST_N_CHARS_RESOURCE_TRANSFORM` needs N).
+`TransformExpressionArgumentType` = `STRING` or `NUMBER`. The retrieved `LAST_N_CHARS_RESOURCE_TRANSFORM` evidence uses `STRING` even for numeric text. Other transforms may use a different type; require a retrieved or documented shape rather than inferring it.
 
 ### PROJECTION — RLS join
 
@@ -207,7 +214,7 @@ Plural (use a set operator: `CONTAINS_ANY` / `CONTAINS_NONE` / `CONTAINS_ALL`):
 </principalExpression>
 ```
 
-> `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` principal expressions are outside MDAPI contract. Fixture-only.
+The retrieved API 69.0 examples persist `SCALAR_ATTRIBUTE` with `SOQLTARGETLISTEXPR`. Treat plural targets as unsupported until a real-org policy is retrieved and round-trip validated.
 
 ---
 

package/skills/platform-policy-rule-generate/references/policy-shapes.md

@@ -0,0 +1,74 @@
+# Policy Shapes
+
+Choose the shape before constructing conditions. Do not mix top-level fields between shapes.
+
+## Every renderable rule needs at least one resource condition
+
+A DC Data Governance UI-renderable rule MUST carry **at least one resource condition** — a `<conditions>` whose left operand is resource-side (`resourcePath` = `ENTITYTYPE`, `TAG`, `CLASSIFICATION`, `RECORDFIELD`, `EXPRESSION`, or `DATASPACE`). Principal conditions (`ASSIGNED_PERMISSIONS_PATH`, `SCALAR_ATTRIBUTE`) are **optional**. A rule with **zero `<conditions>`**, or with only principal conditions and no resource condition, is **not deployable and not renderable** — do not author it.
+
+Per shape, the mandatory resource condition is:
+
+- **OLS** — the `(OR OBJECT FIELD)` entity-type group.
+- **FLS / Masking** — the `FIELD` entity-type condition.
+- **RLS** — a `RECORDFIELD` comparison or an `EXPRESSION` (`EXISTS` join) row criterion. `policyRuleResourceDomains` scopes the rule to the object but is **not** a condition and does not satisfy this requirement. "Read the whole object, no row filter" therefore has no resource condition and is **not** a renderable RLS policy — obtain a row criterion, or route object-wide read to the permission-set path (`platform-dataspace-access-configure`).
+
+## Selecting the shape (deterministic — do not ask the user)
+
+Route from the request signal. Only ask when there is genuinely no signal (see SKILL.md routing for the policy-vs-permission-set case) — do not turn a clear signal into a clarifying question. The single human checkpoint is the preview-and-confirm before the create/update dispatch, not a mid-flow shape question.
+
+| Request signal | Shape |
+|---|---|
+| Grant or deny **read of a specific named object's data** (a DMO/DLO/CIO named or clearly implied) | **RLS** — `RECORD_POLICY_RULE_DEFINITION`, `resourceScopeType=RECORD`, `policyRuleResourceDomains` = that object, **plus a row criterion** |
+| **Hide or deny a specific field** | **FLS** — `Forbid` / `Read` / `FIELD` |
+| **Mask or transform a field's value** | **Masking** — `TRANSFORM_POLICY_RULE_DEFINITION` |
+| Object access gated by **tag / classification across the tenant** (no single named object) | **OLS** — `TupleRead` + tag/classification conditions |
+
+Naming a specific object is the decisive RLS signal: `policyRuleResourceDomains` scopes a RECORD rule to that object. An OLS `TupleRead` rule does **not** scope to a named object — see the OLS warning below.
+
+| Shape | Category | Effect | Action | Scope | Required entity-type group |
+|---|---|---|---|---|---|
+| OLS Permit | `GOVERNANCE_POLICY_RULE_DEFINITION` | `Permit` | `TupleRead` | `ANY` | `(OR OBJECT FIELD)` |
+| FLS deny | `GOVERNANCE_POLICY_RULE_DEFINITION` | `Forbid` | `Read` | `ANY` | `FIELD` only |
+| Masking | `TRANSFORM_POLICY_RULE_DEFINITION` | `Transform` | `Read` | `FIELD` | `FIELD` only |
+| RLS | `RECORD_POLICY_RULE_DEFINITION` | `Permit` | `Read` | `RECORD` | Exact resource DMO |
+
+## OLS
+
+Start with two conditions in this exact order: entity type `OBJECT`, entity type `FIELD`. Group them as `(OR 1 2)`, and always combine that group under a top-level `AND` — never leave `(OR 1 2)` bare at the top level (see `ui-compatibility.md` / `conjunction-expression.md`). Add principal and resource condition groups afterward.
+
+> **An OLS rule applies tenant-wide unless a resource condition narrows it.** The entity-type conditions (`ENTITYTYPE IS OBJECT` / `IS FIELD`) match *every* object and field in the org — they satisfy the mandatory-resource-condition rule but are **not** a scoping mechanism. Without a `TAG` / `CLASSIFICATION` / `DATASPACE` gate, an OLS Permit is an allow-all. `policyRuleResourceDomains` does **not** confine a GOVERNANCE rule — it is a RECORD (RLS) scoping mechanism only. To grant read access scoped to one named object, use **RLS**, not OLS.
+
+## FLS
+
+The validated FLS example uses `Forbid`. Condition 1 is entity type `FIELD`; it has no `OBJECT` condition. Add requested principal conditions and tag/classification resource conditions after it. Construct the conjunction from the requested semantics rather than copying the example's grouping blindly. This evidence does not establish whether a Permit FLS variant is valid.
+
+## Masking
+
+Use category `TRANSFORM_POLICY_RULE_DEFINITION`, effect `Transform`, action `Read`, and resource scope `FIELD`. Set `resourceTransform` to the requested transform. Condition 1 is entity type `FIELD`. Do not add an `OBJECT` condition.
+
+For the retrieved `LAST_N_CHARS_RESOURCE_TRANSFORM`, add one top-level `resourceExpression`:
+
+```xml
+<resourceExpression>
+    <transformExpression>
+        <argument>
+            <type>STRING</type>
+            <value>12</value>
+        </argument>
+    </transformExpression>
+    <type>ARGLIST</type>
+    <version>1</version>
+</resourceExpression>
+```
+
+The retrieved example uses one `STRING` argument even though its value is numeric text. Copy a retrieved shape for the selected transform; do not infer argument type or count.
+
+## RLS
+
+Use category `RECORD_POLICY_RULE_DEFINITION`, effect `Permit`, action `Read`, and resource scope `RECORD`. Add one `policyRuleResourceDomains` block containing the exact target DMO API name. These are MDAPI persistence-validated shapes; runtime row-filter behavior requires separate positive and negative data-access tests.
+
+Every RLS rule needs **at least one resource (row) condition** — a `RECORDFIELD` comparison or an `EXISTS`/`EXPRESSION` join (see "Every renderable rule needs at least one resource condition" above). A `RECORD` rule with zero conditions is not deployable/renderable; `policyRuleResourceDomains` scopes the rule but is not a condition.
+
+The retrieved direct-comparison evidence uses `resourcePath=RECORDFIELD`, a `valueDomain` in `DMO_API_NAME:FIELD_API_NAME` form, a version-1 `SOQLTARGETLISTEXPR`, and `valuePrincipalPath=SCALAR_ATTRIBUTE`. This is the confirmed normal-author-mode shape for a record-field-to-principal-attribute comparison; generate it directly, resolving the exact DMO, field, and principal attribute in the target org.
+
+For an `EXISTS` join, use `resourcePath=EXPRESSION`, a version-1 `PROJECTION`, one or more nested `policyRuleDefinitionCondition` elements, and a `whereClauseConjunction` that indexes those nested conditions independently of the top-level rule conditions. Use the complete semantic `ExistsJoinRLS` example; do not invent joins or relationship direction.

package/skills/platform-policy-rule-generate/references/principal-expression.md

@@ -0,0 +1,31 @@
+# Principal Expressions
+
+Retrieved server evidence can contain a principal attribute selected from the principal record using `SOQLTARGETLISTEXPR`:
+
+```xml
+<conditions>
+    <clause>WHEN</clause>
+    <operator>EQUALS</operator>
+    <policyRuleValueSet>
+        <valueText>EXPECTED_VALUE</valueText>
+    </policyRuleValueSet>
+    <principalExpression>
+        <soqlTarget>
+            <select>PrincipalField</select>
+        </soqlTarget>
+        <type>SOQLTARGETLISTEXPR</type>
+        <version>1</version>
+    </principalExpression>
+    <principalPath>SCALAR_ATTRIBUTE</principalPath>
+</conditions>
+```
+
+Construction:
+
+1. Resolve the principal field name from the target org.
+2. Put that field in `<soqlTarget><select>`.
+3. Use `SOQLTARGETLISTEXPR`, version `1`.
+4. Put the comparison value in the right-side `policyRuleValueSet`.
+5. Use the operator appropriate to the value.
+
+`SCALAR_ATTRIBUTE` paired with `SOQLTARGETLISTEXPR` is the normal-author-mode mechanism for a principal scalar-attribute comparison (for example, `Department`, `Title`, `Division`). It is not in the shorter enum table published for other principal paths, but it is a confirmed, deployable, Policy Builder-compatible construct per DG UI source: it is how the Data Governance UI itself creates user-attribute conditions (not established by a per-shape round-trip), which is why it appears throughout retrieved API 69.0 evidence for OLS, FLS, masking, and RLS. Generate it directly in normal author mode — resolve the requested attribute against the target org's supported-attribute table in `consumer-datacloud-ui.md` and use the exact field name in `<soqlTarget><select>`. Do not replace it with `ASSIGNED_PERMISSIONS_PATH`; permission membership and scalar principal attributes are different operands.

package/skills/platform-policy-rule-generate/references/reference-resolution.md

@@ -0,0 +1,51 @@
+# Reference Resolution
+
+Resolve exact values in the target org before generating XML. User requests may identify a reference by developer name, fully qualified name, display label, or a natural-language description. Treat those forms as lookup inputs, not as deployable values. Required references include:
+
+- Standard tag developer names
+- Standard classification names
+- Custom permission developer names
+- DMO / DLO / calculated-insight-object (CIO) API names
+- DMO / DLO / CIO field (and measure/dimension) API names
+- Principal fields selected by `principalExpression`
+- ID-valued principal comparisons, including profiles
+- Schemas and fields used by resource projections
+
+Use a read-only metadata or Data 360 lookup to map every requested label or description to one exact target-org reference. This applies equally to standard and custom tags, standard and custom classifications, custom permissions, DMO/DLOs, fields, resource domains, join fields, and principal fields. If the lookup returns multiple matches, stop and ask for clarification; do not choose heuristically. If no match exists, stop and report the unresolved reference. Never shorten a dotted tag/classification name, infer a developer name from a label, reuse an ID from an evidence package, or guess a DMO/DLO field. Preserve resolved spelling exactly in `<valueReference>`, `<valueDomain>`, `<select>`, and projection elements.
+
+## Data 360 MCP lookup operations
+
+When a Data 360 MCP session is available, use it for read-only reference lookup only — never for policy mutation. The MCP client exposes three facade tools: `search(query)` to discover the operation, `payload_examples(toolName)` to see that operation's expected input shape, and `execute(toolName, paramsJson)` to invoke it. Resolve the concrete tool name for each operation below through `search`/`payload_examples` before calling `execute`, since the exact binding (a single generic `execute` versus a per-operation tool name) varies by client.
+
+| Reference type | Lookup operation | Notes |
+|---|---|---|
+| Standard tag | `d360_data_governance_tag_list` | Filter by `searchString`/`taxonomyName`/`parentTagFullyQualifiedName` (no `limit`/`offset` beyond the schema's own paging fields — see call notes below). The record's `id` is the D360 policy-JSON reference value, not the MDAPI one — see the `<valueReference>` construction rule below. |
+| Standard classification | `d360_data_governance_classification_list` | Same pattern as tags, via `parentClassificationFullyQualifiedName`. |
+| **Custom / mapped / derived DMO and fields** (most `resourceDomains` targets, `__dlm` suffix) | `d360_dmo_list` / `d360_dmo_get` | **PRIMARY resource path — family `DataModelObject`** (distinct from the standard-only `DataModelObjectCatalog` below). `d360_dmo_list` lists customer-created **and derived** DMOs (custom, SQL/transform, segment-membership, calculated-insight); pass `includeFields:"true"` to return each DMO's field definitions, and optionally filter with `dataSpaceName` / `dataObjectCategory` / `isEnabled` (`limit` defaults to 50). `d360_dmo_get` takes `dataModelObjectName` and returns one DMO **with all field definitions**. Note: `isEnabled=false` does NOT mean the DMO is unusable — it can still back a policy/mapping. Confirmed live: a custom `__dlm` DMO that is absent from the sObject-describe surface resolves cleanly here. This is the correct Data 360 MCP path for the `__dlm` targets that most `resourceDomains`/`valueDomain` entries reference. |
+| Standard (out-of-box / canonical) DMO and fields | `d360_data_model_objects_list` / `d360_data_model_object_get` | Family `DataModelObjectCatalog` — Salesforce-provided **standard/canonical** models only, NOT org-specific custom/derived DMOs (use `d360_dmo_list`/`d360_dmo_get` above for those). Depends on the org having the Schema Interface Connect API enabled; if it errors (`Schema Interface API is not enabled for this organization`), that is an org capability gap, not a lookup-input mistake. |
+| Raw ingested DLO and fields (`__dll`) | `d360_dlo_list` / `d360_dlo_get` | Family `DataLakeObject`. `d360_dlo_list` enumerates the raw ingested source objects; `d360_dlo_get` takes `recordIdOrDeveloperName` and returns one DLO with all field API names. Use when a rule targets the **pre-mapping** `__dll` object rather than the mapped `__dlm` DMO. |
+| Calculated Insight Object (CIO) and its measures/dimensions | `d360_ci_list` / `d360_ci_get` | Family `CalculatedInsight`. `d360_ci_list` enumerates calculated insights (optional `definitionType` filter: CalculatedMetric / StreamingMetric / ExternalMetric / GraphMetric / HistoryMetric); `d360_ci_get` takes `apiName` and returns the full definition including dimensions, measures, and SQL. Use to resolve a CIO name and its measure/dimension field API names before authoring a rule that targets it. |
+| Custom DMO/DLO fields when the Data 360 MCP session is unreachable (last-resort fallback only) | `dispatch_readonly` sObject describe | Use ONLY when no Data 360 MCP session is available — the tools above are the preferred path. GET `/services/data/vXX/sobjects/<name>/describe` and confirm the field name from the describe output before authoring `resourceDomain`/`valueDomain`. Caveat: some custom `__dlm` DMOs are **not present** in `/services/data/vXX/sobjects` at all (confirmed live), so this fallback can miss them entirely — resolve through `d360_dmo_get` above whenever the Data 360 MCP session is reachable. Never use the `sf` CLI. |
+| Dataspace | `d360_dataspace_list` / `d360_dataspace_get` | Only needed when the request names a non-default dataspace. |
+| Custom permission | `dispatch_readonly` SOQL | No Data 360 MCP lookup exists for `CustomPermission`. Resolve read-only via `dispatch_readonly` GET `/services/data/vXX/query?q=SELECT+DeveloperName+FROM+CustomPermission+WHERE+…`. Never use the `sf` CLI. |
+| ID-valued principal comparisons (e.g. `ProfileId`) | `dispatch_readonly` SOQL | Resolve read-only via `dispatch_readonly` GET `/services/data/vXX/query` against the owning standard object (e.g. `Profile`); these are not exposed through a Data 360 MCP lookup tool. Never use the `sf` CLI. |
+
+The D360 policy-JSON authoring path (a separate, MCP-mutating skill) persists a tag/classification lookup's `id` as its `reference` value. This skill's MDAPI XML persists the resolved **developer/API name**, not the `id` — take the `id` only when the target field is itself ID-typed (`ProfileId` and similar), and otherwise construct the MDAPI `<valueReference>` from the lookup record as follows.
+
+### Constructing `<valueReference>` for STANDARD_TAG / STANDARD_CLASSIFICATION
+
+The lookup record's `fullyQualifiedName` is a Connect API path (`<taxonomy>.<tag/classification path>`) and is **not** a direct copy for the MDAPI value — it is missing the MDAPI root namespace, and (for a tag/classification with no parent) missing a category segment that MDAPI still requires. Build the value as:
+
+1. Root literal: `DataGovernanceTags` for a tag, `DataGovernanceClassifications` for a classification. `<valueReferenceType>` is `STANDARD_TAG` or `STANDARD_CLASSIFICATION` respectively.
+2. If the record has a `parentTag` (tags) or `parentClassification` (classifications) — i.e. it is nested under a category — its `fullyQualifiedName` is already `<taxonomy>.<category>.<leaf>`; the value is `<Root>.<fullyQualifiedName>`.
+3. If the record has **no** parent (it sits directly under its taxonomy, `fullyQualifiedName` is only `<taxonomy>.<leaf>`) — MDAPI still requires a 3-segment path after the root, so **repeat the leaf `name` as the missing category segment**: `<Root>.<fullyQualifiedName>.<name>`.
+
+Both shapes are confirmed against live org lookups and persisted evidence: a top-level tag (`FinancialData.AccountInfo`, no `parentTag`) persists as `DataGovernanceTags.FinancialData.AccountInfo.AccountInfo`; a top-level classification (`DataCategorization.DataSensitivity`, no `parentClassification`) persists as `DataGovernanceClassifications.DataCategorization.DataSensitivity.DataSensitivity`; a nested tag (`EthicalAiStandards.EthicalAI.Caste`, has `parentTag`) persists as-is with only the root prepended: `DataGovernanceTags.EthicalAiStandards.EthicalAI.Caste`.
+
+`search` only accepts a `query` argument — do not pass a `limit` field to it (the live server rejects unrecognized fields); pass `limit`/`offset` to the resolved lookup tool itself (e.g. `d360_data_governance_tag_list`) if needed for paging.
+
+Every reference above resolves through MCP only — Data 360 MCP for tags / classifications / dataspaces AND every resource-side object schema: custom/derived DMOs (`d360_dmo_list`/`d360_dmo_get`), standard DMOs (`d360_data_model_objects_list`/`d360_data_model_object_get`), DLOs (`d360_dlo_list`/`d360_dlo_get`), and calculated insight objects (`d360_ci_list`/`d360_ci_get`). Read-only headless-360 `dispatch_readonly` is used only for the references Data 360 MCP has no lookup for — custom permissions and ID-valued comparisons (SOQL `/query`) — and, strictly as a last resort when no Data 360 MCP session is reachable, a custom-DMO sObject describe (which can miss `__dlm` objects). There is no `sf` CLI resolution path. If neither MCP session can resolve a reference, stop and report the unresolved reference to the operator rather than routing around it.
+
+Serialize XML structurally. XML-escape text values and validate developer names, API names, fields, operators, aliases, and reference types against their expected grammar or enum before interpolation.
+
+The semantic evidence packages demonstrate exact resolved source-org values. In normal author mode, resolve every value again in the target org. In explicit evidence-recreation mode, exact fidelity to the named API 69.0 evidence package takes precedence: preserve its evidence values rather than substituting current target-org values, and do not deploy that fixture as though it were newly resolved authored output.