@salesforce/afv-skills 1.29.0 → 1.31.0

package/skills/platform-policy-rule-generate/references/deploy-errors.md

@@ -0,0 +1,54 @@
+# Deploy Error Reference
+
+When `sf project deploy start` fails, it prints a per-component status table. Below are the most common error families for `PolicyRuleDefinition` / `PolicyRuleDefinitionSet` metadata.
+
+For verbose output when scripting:
+```bash
+sf project deploy start --target-org <alias> --source-dir … --json --verbose \
+  | jq '.result.details.componentFailures'
+```
+
+---
+
+## Error Table
+
+| Error fragment | Likely cause | Fix |
+|---|---|---|
+| `Not available for deploy for this organization` | Org has `EnforceOMatic` perm (entities visible) but lacks `PolicyRuleMDAPI` org perm | Internal license/feature provisioning — surface to the operator. Both `EnforceOMatic` AND `PolicyRuleMDAPI` are required (see §11.1 of policy.md). |
+| `Cannot find … PolicyRuleDefinition` (older orgs) | Org missing `EnforceOMatic` entirely, or API version too low | Confirm both `EnforceOMatic` and `PolicyRuleMDAPI` perms; ensure `<version>` ≥ 64.0 in package.xml |
+| `INVALIDFORCATEGORY` / `Resource scope … not valid for category …` | Scope × category mismatch (e.g., ACCESS/GOVERNANCE + RECORD scope, or TRANSFORM + ANY scope) | Match scope to category per the §4 matrix in SKILL.md. For OLS/FLS on tagged objects: use `ANY`/`FIELD` scope + tag/classification condition — **not** `<resourceDomain>`. |
+| `Identified record category should use record field …` | Attempted to author an `IDENTIFIED_RECORD` policy with a non-`RECORDFIELD` resource path | Do not author `IDENTIFIED_RECORD` via MDAPI — use a runtime `RuleProvider` instead. |
+| `Invalid resource domain - <name>` | `<resourceDomain>` references an entity that doesn't exist in the target org | Pre-deploy the DMO/entity, or remove the rule until the target is available. Namespaced DMOs (e.g. `ssot__Account__dlm`) need the namespace prefix in the XML. |
+| `An unexpected error occurred. Please include this ErrorId… (-116061062)` (opaque gack on RLS deploy) | RLS rule references a `<valueDomain>` DMO field that exists in metadata but is **not mapped** in the target org's data streams. Server-side NPE instead of a clean validation error. | Verify each `<valueDomain>` field is mapped in Setup → Data Cloud → Data Explorer. Build the rule in the UI first — the UI surfaces field-mapping issues with usable errors where MDAPI doesn't. |
+| `Metadata API received improper input. … Load of metadata from db failed for metadata of type:PolicyRuleDefinition and file name:<name>` (on **retrieve**) | UI-saved RLS rules can fail to round-trip back through MDAPI retrieve in some org states | No clean fix. Use the UI as source of truth for that rule, or hand-author from a known-deployable RLS template. |
+| `Use the principal … with external record category.` | `EXTERNAL_RECORD` rule used a non-`IS_AUTHENTICATED`/`IS_INTERNAL` `principalPath` | Switch principal path or change category |
+| `Unsupported … contextPath` | Used a context path outside `RuleContextPathType.SESSION_DATASPACE` | Not authorable via MDAPI XML — use a runtime `RuleProvider` |
+
+---
+
+## OrgPerm Gating
+
+Two org permissions are **both** required for MDAPI authoring:
+
+| Permission | Gate | Effect if missing |
+|---|---|---|
+| `EnforceOMatic` | `@WsdlGuard` master switch | Entities not visible in UI/Tooling API at all |
+| `PolicyRuleMDAPI` | `orgCanUsePolicyRuleMDAPI` WSDL layer | Deploy fails with `Not available for deploy for this organization` |
+
+`EnforcOMaticMDAPI` is a separate **packaging** gate (`isMdAPIAllowedInternal`) — only required for packaging/change sets, not for DX CLI deploys. After PR #98647 (merged 2026-06-08) the predicate is `DBContext.get().isDoingPackageInstall()`, so DX CLI deploys work with just the two perms above.
+
+---
+
+## Dry-Run First
+
+Always validate before deploying to a long-lived org:
+
+```bash
+sf project deploy start \
+  --target-org <alias> \
+  --source-dir force-app/main/default \
+  --dry-run \
+  --wait 10
+```
+
+A `--dry-run` failure runs the full server-side validation hooks (including the `IDENTIFIED_RECORD` constraint at `PolicyRuleDefinitionCondObject.java:332-339`) without persisting. This catches all of the errors in the table above before they affect a real org.

package/skills/platform-policy-rule-generate/references/fixtures-index.md

@@ -0,0 +1,29 @@
+# Fixtures Index
+
+> **For human maintainers only.** This index requires a checkout of `enforce-o-matic-impl`. The agent should rely on [`templates.md`](templates.md), which reproduces the relevant XML shapes inline.
+
+Quick lookup from "what I need" to "fixture that already does it".
+
+All fixtures are under `enforce-o-matic-impl/test/func/filemetadata/<name>/`.
+
+| If you need… | Fixture |
+|---|---|
+| Bare permit rule, no conditions | `baseSteelthread`, `steelthreadPayload` |
+| Custom conjunction `(AND 1 2)` over UNLESS | `conjunctionExpressionSteelthread` |
+| Tag check | `conditionTagValidSteelthread`, `conditionCustomTagValidDataMaskingSteelthread` |
+| Classification check | `conditionClassificationValidClauseSteelthread`, `conditionClassificationValidDataMaskingSteelthread` |
+| Dataspace / session dataspace | `conditionDataspaceValidSteelthread`, `conditionSessionDataspaceValidSteelthread` |
+| Custom permission gate | `conditionAssignedPermPathValidSteelthread` |
+| Plain RLS (record field = user ID) | `conditionRLSValidSteelthread` (1st condition), `conditionStandardIdRLSValidSteelthread` |
+| RLS via PROJECTION join | `conditionRLSValidSteelthread` (2nd condition) |
+| Scalar / plural SOQL principal (out-of-contract) | `conditionScalarAttributeValidSteelThread`, `conditionPluralAttributeValidSteelthread` |
+| Hierarchy traversal | `conditionWithHierarchy` |
+| Field masking transform | `conditionClassificationValidDataMaskingSteelthread`, `conditionInvalidDataMaskingSteelthread` (negative) |
+| Field-scoped resource domain | `resourceDomainWithField` |
+| Core standard object policy (Case) | `coreObjectCaseWithPolicy` (persistence-layer only; not a working IDENTIFIED_RECORD shape — see §8.4 of policy.md) |
+| Extended steelthread (set referenced from sibling package) | `extendedSteelthread` |
+| Negative: missing operator | `conditionMissingOperatorSteelthread` |
+| Negative: missing path | `conditionMissingPathSteelthread` |
+| Negative: invalid context path | `conditionInvalidContextPathSteelthread` |
+| Negative: invalid data masking shape | `conditionInvalidDataMaskingSteelthread` |
+| Negative: invalid payload | `invalidPayload` |

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

@@ -0,0 +1,250 @@
+# Policy Schema — Full Element Reference
+
+Source: `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/`
+
+---
+
+## Path Enums
+
+> **Surface principle.** The MDAPI surface is the narrower `*Type` enum in `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/`. The wider runtime enums (`RulePrincipalPath`, `RuleResourcePath`, `RuleContextPath` in `enforce-o-matic-api/.../enums/`) drive Cedar evaluation and DAO behavior; values absent from the `*Type` enums are **not authorable via MDAPI**.
+
+### `<principalPath>` / `<valuePrincipalPath>` — `RulePrincipalPathType` (6 values)
+
+| Value | Meaning |
+|-------|---------|
+| `IS_AUTHENTICATED_USER_PATH` | Boolean "is principal an authenticated user" |
+| `ASSIGNED_PERMISSIONS_PATH` | Principal's assigned permissions (pair with `valueReferenceType=CUSTOM_PERMISSION`) |
+| `USER_ID` | Principal user ID |
+| `ORGANIZATION_ID` | Principal org ID |
+| `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.
+
+### `<resourcePath>` / `<valueResourcePath>` — `RuleResourcePathType` (16 values)
+
+| Value | Meaning |
+|-------|---------|
+| `NAMESPACE` | Resource namespace |
+| `ENTITY` | Entity (object) reference |
+| `FIELD` | Field reference |
+| `ENTITYTYPE` | Entity type — pair with `IS` operator and `{"t":"Text","v":"FIELD"}` literal |
+| `ENTITYKIND` | Entity kind bits |
+| `FIELDKIND` | Field kind bits |
+| `DATASPACE` | Resource dataspace |
+| `TAG` | Custom or standard tag |
+| `OBJECT_TAG` | Object-level tag |
+| `CLASSIFICATION` | Custom or standard classification |
+| `IMPLICITTAG` | Implicit tag |
+| `RECORDFIELD` | Field of the record being evaluated (RLS) — pair with `<valueDomain>Schema:field</valueDomain>` |
+| `OBJECT_CLASSIFICATION` | Object-level classification |
+| `EXPRESSION` | Compound expression — pair with `<resourceExpression>` PROJECTION |
+| `OBJECT_DATASPACE` | Object-level dataspace |
+| `RECORDFIELDTYPE` | Type of a record field |
+
+### `<contextPath>` / `<valueContextPath>` — `RuleContextPathType` (1 value)
+
+| Value | Cedar attribute | Use case |
+|-------|-----------------|----------|
+| `SESSION_DATASPACE` | `context.sessionDataspace` | Session-scoped dataspace check |
+
+Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERSION_ID` (IDENTIFIED_RECORD / agentic — runtime RuleProvider only).
+
+> Some steelthread fixtures use `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` in `<valuePrincipalPath>` (`conditionScalarAttributeValidSteelThread`). They deploy in the ftest harness because the entity object is type-tolerant, but these values are outside `RulePrincipalPathType` — not sanctioned for new work.
+
+---
+
+## `<operator>` — `RuleDefinitionOperatorType`
+
+| Operator | Use with |
+|----------|----------|
+| `EQUALS` / `NOT_EQUALS` | Scalar equality |
+| `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUALS` | Numeric / date |
+| `IN` | Scalar IN set |
+| `LIKE` | String pattern |
+| `CONTAINS_ANY` | Set has at least one of |
+| `CONTAINS_ALL` | Set has all of |
+| `CONTAINS_NONE` | Set has none of |
+| `IS` | Type / kind check (pair with `ENTITYTYPE` + `{"t":"Text","v":"FIELD"}` literal) |
+| `EXISTS` | RLS join exists (pair with `resourcePath=EXPRESSION` + PROJECTION) |
+| `HIERARCHICALLY_ABOVE` / `HIERARCHICALLY_BELOW` | Hierarchy traversal — pair with `valueReferenceType=HIERARCHY` |
+
+---
+
+## `<conditions>` — Full Schema (`PolicyRuleDefinitionCondition.java`)
+
+| Element | Notes |
+|---------|-------|
+| `<clause>` | `WHEN` or `UNLESS` — match the wrapper |
+| `<operator>` | Always required |
+| `<resourcePath>` | What about the resource to inspect |
+| `<principalPath>` | What about the principal to inspect |
+| `<contextPath>` | Context attribute (SESSION_DATASPACE only) |
+| `<valueDomain>` | `Schema:field` — for RECORDFIELD comparisons |
+| `<resourceAlias>` | Used in PROJECTION join expressions |
+| `<valueBit>` | Entity/field-kind bits |
+| `<valuePrincipalPath>` | Path the value comes from |
+| `<valueResourcePath>` | Path the value comes from |
+| `<valueContextPath>` | Path the value comes from |
+| `<policyRuleValueSet>` | Literal or named-reference values (see below) |
+| `<resourceExpression>` | `PolicyJsonExpression` type=PROJECTION (RLS join) |
+| `<principalExpression>` | `PolicyJsonExpression` type=SOQLTARGETLISTEXPR (SOQL principal) |
+| `<whereClauseConjunction>` | Sub-expression for nested conditions |
+| `<policyRuleDefinitionCondition>` | Nested children — used with `whereClauseConjunction` |
+
+---
+
+## `<policyRuleValueSet>` — `PolicyRuleValueSet.java`
+
+Three fields (all optional at schema level, but a non-empty value set needs at least one):
+
+### Literal values — `<valueString>`
+
+For typed literals, embed JSON (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>
+<valueString>{&quot;t&quot;:&quot;Number&quot;,&quot;v&quot;:42}</valueString>
+```
+
+For plain string equality:
+```xml
+<valueString>Toxico</valueString>
+```
+
+### Named references — `<valueReference>` + `<valueReferenceType>`
+
+| `valueReferenceType` | Refers to | Typical path pairing |
+|----------------------|-----------|----------------------|
+| `CUSTOM_TAG` | Custom tag by devName | `resourcePath=TAG` |
+| `STANDARD_TAG` | Standard tag — **fully qualified** (e.g. `DataGovernanceTags.ExternalData.Visibility.Public`) | `resourcePath=TAG` |
+| `CUSTOM_CLASSIFICATION` | Custom classification | `resourcePath=CLASSIFICATION` |
+| `STANDARD_CLASSIFICATION` | Standard classification — **fully qualified** (e.g. `DataGovernanceClassifications.DataCategorization.FieldUsage.Active`) | `resourcePath=CLASSIFICATION` |
+| `HIERARCHY` | Hierarchy definition | `operator=HIERARCHICALLY_BELOW/ABOVE`, `resourcePath=RECORDFIELD` |
+| `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.
+
+Multiple `<policyRuleValueSet>` siblings inside one condition are OR-combined.
+
+---
+
+## JSON Expressions — `PolicyJsonExpression.java` (min API 66.0)
+
+`<type>` must match the location:
+
+| Location | Required `type` |
+|----------|-----------------|
+| Top-level `<resourceExpression>` (TRANSFORM rule arg list) | `ARGLIST` |
+| `<conditions>` `<resourceExpression>` (RLS join) | `PROJECTION` |
+| `<conditions>` `<principalExpression>` (SOQL principal) | `SOQLTARGETLISTEXPR` |
+
+### ARGLIST — Transform argument list
+
+```xml
+<resourceExpression>
+    <type>ARGLIST</type>
+    <version>1</version>
+    <transformExpression>
+        <argument>
+            <type>NUMBER</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).
+
+### PROJECTION — RLS join
+
+Used inside `<conditions>` with `resourcePath=EXPRESSION` and `operator=EXISTS`:
+
+```xml
+<resourceExpression>
+    <type>PROJECTION</type>
+    <version>1</version>
+    <projection>
+        <join>
+            <schema>testDMO__dlm</schema>
+            <alias>test 1</alias>
+            <predicate>
+                <comparator>EQUALS</comparator>
+                <attribute>testDMO__dlm:name__c</attribute>
+                <on>
+                    <resourceAlias>resource</resourceAlias>
+                    <schema>testDMO__dlm</schema>
+                    <field>age__c</field>
+                </on>
+            </predicate>
+        </join>
+    </projection>
+</resourceExpression>
+```
+
+### SOQLTARGETLISTEXPR — Principal SOQL target
+
+Scalar:
+```xml
+<principalExpression>
+    <type>SOQLTARGETLISTEXPR</type>
+    <version>1</version>
+    <soqlTarget>
+        <select>age__c</select>
+    </soqlTarget>
+</principalExpression>
+```
+
+Plural (use a set operator: `CONTAINS_ANY` / `CONTAINS_NONE` / `CONTAINS_ALL`):
+```xml
+<principalExpression>
+    <type>SOQLTARGETLISTEXPR</type>
+    <version>1</version>
+    <soqlTarget>
+        <plural>true</plural>
+        <relationship>pluralAttributes__r</relationship>
+        <select>name__c</select>
+    </soqlTarget>
+</principalExpression>
+```
+
+> `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` principal expressions are outside MDAPI contract. Fixture-only.
+
+---
+
+## `<resourceTransform>` Enum (TRANSFORM rules only)
+
+| Value | Effect |
+|-------|--------|
+| `NULL_RESOURCE_TRANSFORM` | Replace with NULL |
+| `EMPTY_STRING_RESOURCE_TRANSFORM` | Replace with `""` |
+| `LAST_N_CHARS_RESOURCE_TRANSFORM` | Keep last N chars (N via ARGLIST) |
+| `FIRST_N_CHARS_RESOURCE_TRANSFORM` | Keep first N chars (N via ARGLIST) |
+| `ALL_BUT_LAST_N_CHARS_RESOURCE_TRANSFORM` | Mask last N |
+| `ALL_BUT_FIRST_N_CHARS_RESOURCE_TRANSFORM` | Mask first N |
+| `CLOSEST_ORDER_OF_MAGNITUDE_RESOURCE_TRANSFORM` | Round to nearest power of 10 |
+| `TRUNCATE_DATE_RESOURCE_TRANSFORM` | Truncate date precision |
+| `ROUND_RESOURCE_TRANSFORM` | Round number |
+| `REPLACE_ALL_CHARS_RESOURCE_TRANSFORM` | Replace each char |
+
+Pure transforms (NULL, EMPTY_STRING) need no `<resourceExpression>`. Parameterized transforms (FIRST_N, LAST_N, ROUND, REPLACE_ALL_CHARS, TRUNCATE_DATE) take args via ARGLIST.
+
+---
+
+## File Cross-References
+
+| Concern | File |
+|---------|------|
+| Rule wrapper | `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/PolicyRuleDefinition.java` |
+| Set wrapper | `…/PolicyRuleDefinitionSet.java` |
+| Conditions | `…/PolicyRuleDefinitionClauseConjunction.java`, `…/PolicyRuleDefinitionCondition.java` |
+| Value set | `…/PolicyRuleValueSet.java` + `…/PolicyRuleValueSetReferenceType.java` |
+| JSON expression | `…/PolicyJsonExpression.java` + `…/PolicyJsonExpressionType.java` |
+| ARGLIST | `…/TransformExpression.java` + `…/TransformExpressionArgument.java` |
+| PROJECTION | `…/ProjectionExpression.java` + `…/ProjectionJoin.java` + `…/PolicyJoinPredicate.java` |
+| SOQLTARGETLISTEXPR | `…/PrincipalExpression.java` |
+| Resource domain | `…/PolicyRuleResourceDomain.java` |
+| Enums | `Category.java`, `Effect.java`, `RuleConsumer.java`, `PrincipalAuthenticationLevel.java`, `RulePrincipalScopeType.java`, `RuleResourceScopeType.java`, `RulePrincipalPathType.java`, `RuleResourcePathType.java`, `RuleContextPathType.java`, `RuleDefinitionClauseType.java`, `RuleDefinitionOperatorType.java`, `ResourceTransform.java` |
+| IDENTIFIED_RECORD condition validator | `PolicyRuleDefinitionCondObject.java:332-339` |
+| Agentic RuleProvider canonical builder | `AgenticPolicyRuleProviderService.java:130-260` |

package/skills/platform-policy-rule-generate/references/templates-access.md

@@ -0,0 +1,132 @@
+# ACCESS / GOVERNANCE Templates
+
+Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+
+---
+
+## ACCESS — Simple Permit (no conditions)
+
+Source: `baseSteelthread`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <action>Read</action>
+    <category>ACCESS_POLICY_RULE_DEFINITION</category>
+    <effect>Permit</effect>
+    <label>Rule0</label>
+    <policyRuleDefinitionSetName>Set1</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>ANY</resourceScopeType>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+</PolicyRuleDefinition>
+```
+
+---
+
+## ACCESS / GOVERNANCE — "Objects AND all their fields" via TupleRead (UI-compatible)
+
+Source: see §8.2.1 of policy.md
+
+Three required pieces:
+1. `<action>TupleRead</action>` — cascades object-level condition to fields
+2. **OR-of-ENTITYTYPE clause** — required for UI editability (without it the builder crashes)
+3. The actual semantic gate (tag / classification / permission)
+
+```xml
+<?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>GrantPublicAccess</label>
+    <policyRuleDefinitionSetName>PublicAccessSet</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>ANY</resourceScopeType>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <!-- (1) and (2): OR-of-ENTITYTYPE clause — required for UI rendering -->
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <policyRuleValueSet>
+                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;OBJECT&quot;}</valueString>
+            </policyRuleValueSet>
+            <resourcePath>ENTITYTYPE</resourcePath>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <policyRuleValueSet>
+                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;FIELD&quot;}</valueString>
+            </policyRuleValueSet>
+            <resourcePath>ENTITYTYPE</resourcePath>
+        </conditions>
+        <!-- (3): actual semantic gate -->
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <resourcePath>TAG</resourcePath>
+            <policyRuleValueSet>
+                <valueReference>DataGovernanceTags.ExternalData.Visibility.Public</valueReference>
+                <valueReferenceType>STANDARD_TAG</valueReferenceType>
+            </policyRuleValueSet>
+        </conditions>
+        <!-- MUST use (AND N) not bare N for every top-level param — bare index crashes UI -->
+        <conjunctionExpression>(AND (OR 1 2) (AND 3))</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>
+```
+
+For **deny semantics**: `<effect>Forbid</effect>`. To add "deny unless permission Y", insert a 4th condition with `ASSIGNED_PERMISSIONS_PATH CONTAINS_NONE Y` and use `(AND (OR 1 2) (AND 3) (AND 4))`.
+
+---
+
+## ACCESS — Gated by Tag / Classification / Permission
+
+Source: `conditionTagValidSteelthread`, `conditionClassificationValidClauseSteelthread`, `conditionAssignedPermPathValidSteelthread`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<PolicyRuleDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <action>Read</action>
+    <category>ACCESS_POLICY_RULE_DEFINITION</category>
+    <effect>Permit</effect>
+    <label>Rule0</label>
+    <policyRuleDefinitionSetName>TagSet1</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>ANY</resourceScopeType>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <resourcePath>TAG</resourcePath>
+            <policyRuleValueSet>
+                <valueReference>CustomTagRef</valueReference>
+                <valueReferenceType>CUSTOM_TAG</valueReferenceType>
+            </policyRuleValueSet>
+        </conditions>
+        <conjunctionExpression>1</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>
+```
+
+Swap the inner condition for permission gating:
+```xml
+<conditions>
+    <clause>WHEN</clause>
+    <operator>CONTAINS_ANY</operator>
+    <principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>
+    <policyRuleValueSet>
+        <valueReference>testCustomPermission1</valueReference>
+        <valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>
+    </policyRuleValueSet>
+</conditions>
+```

package/skills/platform-policy-rule-generate/references/templates-advanced.md

@@ -0,0 +1,58 @@
+# Advanced Templates — Multi-Condition, Hierarchy, Unauthorable
+
+Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+
+---
+
+## Multi-Condition with Custom Conjunction (AND/OR mix)
+
+Source: `conjunctionExpressionSteelthread`
+
+```xml
+<unlessPolicyRuleDefinitionClauseConjunction>
+    <conditions>
+        <clause>UNLESS</clause>
+        <operator>CONTAINS_ANY</operator>
+        <resourcePath>TAG</resourcePath>
+    </conditions>
+    <conditions>
+        <clause>UNLESS</clause>
+        <operator>CONTAINS_NONE</operator>
+        <resourcePath>TAG</resourcePath>
+    </conditions>
+    <conjunctionExpression>(AND 1 2)</conjunctionExpression>
+</unlessPolicyRuleDefinitionClauseConjunction>
+```
+
+> Note: `<unlessPolicyRuleDefinitionClauseConjunction>` blocks are **not UI-editable** — silently dropped on first save. Prefer WHEN + negated operator for UI-compatible policies.
+
+---
+
+## Hierarchy Traversal
+
+Source: `conditionWithHierarchy`
+
+```xml
+<conditions>
+    <clause>WHEN</clause>
+    <operator>HIERARCHICALLY_BELOW</operator>
+    <resourcePath>RECORDFIELD</resourcePath>
+    <valueDomain>testDMO__dlm:name__c</valueDomain>
+    <policyRuleValueSet>
+        <valueReference>testHierarchyRLS</valueReference>
+        <valueReferenceType>HIERARCHY</valueReferenceType>
+    </policyRuleValueSet>
+</conditions>
+```
+
+> Not UI-editable (`HIERARCHICALLY_BELOW` and `valueReferenceType=HIERARCHY` are not in the UI dropdowns).
+
+---
+
+## IDENTIFIED_RECORD — Not Authorable via MDAPI
+
+`IDENTIFIED_RECORD` policies cannot be authored as XML. The required `RuleContextPath.SESSION_CONSUMER_ID` is not in `RuleContextPathType`.
+
+To author one: write a runtime `RuleProvider` using `AgenticPolicyRuleProviderService.java:130-260` as the canonical builder.
+
+**Do not** synthesize a placeholder XML using `<contextPath>SESSION_CONSUMER_ID</contextPath>` — the value is not in `RuleContextPathType` and the deploy will fail.

package/skills/platform-policy-rule-generate/references/templates-record.md

@@ -0,0 +1,75 @@
+# RECORD Templates
+
+Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+
+---
+
+## RECORD — Basic RLS (record field = user attribute)
+
+Source: `conditionRLSValidSteelthread` (first condition), `conditionStandardIdRLSValidSteelthread`
+
+> **RLS MDAPI round-trip is fragile in real orgs.** Deploy/retrieve can fail with opaque gacks if a DMO field in `<valueDomain>` is not mapped in the org's data streams. Build the rule in the UI first; use MDAPI templates as verification shapes, not first-try authoring. See §8.3 of policy.md.
+
+```xml
+<?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>Rule1</label>
+    <policyRuleDefinitionSetName>StandardFieldSet3</policyRuleDefinitionSetName>
+    <policyRuleResourceDomains>
+        <resourceDomain>testDMO__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>
+            <resourcePath>RECORDFIELD</resourcePath>
+            <valueDomain>testDMO__dlm:name__c</valueDomain>
+            <valuePrincipalPath>USER_ID</valuePrincipalPath>
+        </conditions>
+        <conjunctionExpression>1</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>
+```
+
+For literal-value RLS (e.g. `record.field == 'X'`), use `<policyRuleValueSet><valueString>X</valueString></policyRuleValueSet>` instead of `<valuePrincipalPath>`.
+
+---
+
+## RECORD — RLS via PROJECTION Join
+
+Source: `conditionRLSValidSteelthread` (second condition)
+
+```xml
+<conditions>
+    <clause>WHEN</clause>
+    <operator>EXISTS</operator>
+    <resourcePath>EXPRESSION</resourcePath>
+    <resourceExpression>
+        <type>PROJECTION</type>
+        <version>1</version>
+        <projection>
+            <join>
+                <schema>testDMO__dlm</schema>
+                <alias>test 1</alias>
+                <predicate>
+                    <comparator>EQUALS</comparator>
+                    <attribute>testDMO__dlm:name__c</attribute>
+                    <on>
+                        <resourceAlias>resource</resourceAlias>
+                        <schema>testDMO__dlm</schema>
+                        <field>age__c</field>
+                    </on>
+                </predicate>
+            </join>
+        </projection>
+    </resourceExpression>
+</conditions>
+```

package/skills/platform-policy-rule-generate/references/templates-transform.md

@@ -0,0 +1,70 @@
+# TRANSFORM Templates
+
+Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+
+---
+
+## TRANSFORM — Field Masking with Permission + Classification Gates
+
+Source: `conditionClassificationValidDataMaskingSteelthread`
+
+```xml
+<?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>Rule0</label>
+    <policyRuleDefinitionSetName>DataMasking1</policyRuleDefinitionSetName>
+    <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
+    <principalScopeType>ANY</principalScopeType>
+    <resourceScopeType>FIELD</resourceScopeType>
+    <resourceTransform>NULL_RESOURCE_TRANSFORM</resourceTransform>
+    <ruleConsumer>DATACLOUD</ruleConsumer>
+    <transformPrecedence>0</transformPrecedence>
+    <whenPolicyRuleDefinitionClauseConjunction>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>IS</operator>
+            <resourcePath>ENTITYTYPE</resourcePath>
+            <policyRuleValueSet>
+                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;FIELD&quot;}</valueString>
+            </policyRuleValueSet>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_NONE</operator>
+            <principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>
+            <policyRuleValueSet>
+                <valueReference>testCustomPermissionMasking</valueReference>
+                <valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>
+            </policyRuleValueSet>
+        </conditions>
+        <conditions>
+            <clause>WHEN</clause>
+            <operator>CONTAINS_ANY</operator>
+            <resourcePath>CLASSIFICATION</resourcePath>
+            <policyRuleValueSet>
+                <valueReference>DataGovernanceClassifications.DataCategorization.FieldUsage.Active</valueReference>
+                <valueReferenceType>STANDARD_CLASSIFICATION</valueReferenceType>
+            </policyRuleValueSet>
+        </conditions>
+        <conjunctionExpression>(AND 1 2 3)</conjunctionExpression>
+    </whenPolicyRuleDefinitionClauseConjunction>
+</PolicyRuleDefinition>
+```
+
+For parameterized masking (e.g. mask all but first 4 chars):
+```xml
+<resourceTransform>ALL_BUT_FIRST_N_CHARS_RESOURCE_TRANSFORM</resourceTransform>
+<resourceExpression>
+    <type>ARGLIST</type>
+    <version>1</version>
+    <transformExpression>
+        <argument>
+            <type>NUMBER</type>
+            <value>4</value>
+        </argument>
+    </transformExpression>
+</resourceExpression>
+```