@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/platform-mcp-tool-widget-coordinate/references/validation-gates.md

@@ -44,13 +44,28 @@ Confirms the envelope→response typing the renderer depends on.
 
    Any output → `KEYWORDS: FAIL (<path>)`; empty → `KEYWORDS: ok`.
 
-4. **Nested-object response fields (if any) use `@apexClassType`, never a bare object.** For every response CLT property that is not a primitive leaf, print its `lightning:type`:
+4. **Nested-object response fields (if any) use `@apexClassType`, never a bare object or a CLT-level list.** For every response CLT property that is not a primitive leaf, print its `lightning:type`:
 
    ```bash
-   jq -r '.properties | to_entries[] | select(.value["lightning:type"] == null or (.value["lightning:type"] | test("^lightning__") | not)) | "\(.key): \(.value["lightning:type"])"' <pkgDir>/lightningTypes/<responseCLT>/schema.json
+   jq -r '.properties | to_entries[] | select(.value["lightning:type"] == null or (.value["lightning:type"] | test("^lightning__(text|integer|number|boolean|date|dateTime)Type$") | not)) | "\(.key): \(.value["lightning:type"])"' <pkgDir>/lightningTypes/<responseCLT>/schema.json
    ```
 
-   Every printed entry must match `@apexClassType/<ns>__<OuterClass>$<InnerClass>`. A bare `{"type":"object"}` (no `lightning:type`, or a `lightning:type` of `lightning__objectType` inlined on a *property* rather than the CLT root) → `NESTED_TYPE: FAIL (<key>: <actual>)`. All match or no such properties exist → `NESTED_TYPE: ok`.
+   Every printed entry must be a single nested object typed `@apexClassType/<ns>__<OuterClass>$<InnerClass>`. Two FAILs:
+   - A bare `{"type":"object"}` (no `lightning:type`, or a `lightning:type` of `lightning__objectType` inlined on a *property* rather than the CLT root) → `NESTED_TYPE: FAIL (<key>: <actual>)`.
+   - A `lightning__listType` on a **response CLT** property → `NESTED_TYPE: FAIL (<key>: lists ride inside an @apexClassType object; the CLT must not carry a lightning__listType — see references/two-clt-modeling.md "List of nested objects")`. Lists surface in the widget schema, not the CLT.
+
+   All entries are `@apexClassType/...` or no such properties exist → `NESTED_TYPE: ok`.
+
+5. **Response CLT property names trace to describe outputs (no invented wrapper).** The response CLT's top-level property names MUST equal the describe's `outputs[].name` set (for `apex`/`sample`, the response class's `@InvocableVariable` field names — the same set the describe surfaces). Print both:
+
+   ```bash
+   echo "OUTPUTS:"
+   sf api request rest '/services/data/v<APIVER>/actions/custom/apex/<ActionApiName>' -o <org> | jq -r '.outputs[].name' | sort -u
+   echo "RESPONSE_CLT_PROPS:"
+   jq -r '.properties | keys[]' <pkgDir>/lightningTypes/<responseCLT>/schema.json | sort -u
+   ```
+
+   A describe with **N sibling outputs** must yield **N flat properties** with matching names; a describe with **one output** yields **one property named after it** (`shipmentDetailsResponse`, `flightInfo`). A single property whose name is **not** among the describe outputs (e.g. `leadsListResponse` against a `leadCount`/`leads`/`message`/`status` describe) is an **invented wrapper** — it collapses N siblings into one key the describe never returns and is unresolvable under `action`. Any response CLT property name absent from the describe outputs → `PROP_GROUNDING: FAIL (<prop> not a describe output — model each sibling output as its own flat property; never collapse into an invented wrapper)`. All property names present in the outputs set → `PROP_GROUNDING: ok`.
 
 **Result:** all ok → `pass`. Otherwise `fail (<first failing check>)`.
 
@@ -109,6 +124,32 @@ Confirms the envelope CLT's default renderer assigns the widget and binds every
 
 ---
 
+### 3. `nested-list-coverage`
+
+Confirms every **nested-object** and **list** payload field discovered in Phase 2 is actually rendered — never dropped. The failure mode it guards against: a `List<...>` field declared "out of scope" and silently omitted, leaving the widget with only a scalar KPI. A nested-object or list field is **domain data** and MUST be rendered.
+
+> **A top-level list output is directly renderable — never reshape the Apex.** When the describe surfaces the list itself as an output (`apexClass` set + `maxOccurs > 1`, e.g. `GetLeadsList` → `leads`), the response CLT types it directly as `@apexClassType/c__<Outer>$<ElementClass>` and the renderer binds it at **two segments** `{!$attrs.outputValues.<listField>}` — no wrapper class, no Apex change. A list *inside* a wrapper object (the describe returns one `maxOccurs: 1` `apexClass` output and the list is a field the describe does not surface) binds at **three segments** `{!$attrs.outputValues.<wrapperField>.<listField>}` after reading the inner class to find the list field. Covering the field means binding it at the depth its describe position dictates — the skill must **never** normalize the action to a wrapper or drop the field.
+
+> **Key it off discovery, not the artifacts.** A field the skill silently dropped will be absent from BOTH the CLT and the widget — so this gate must compare against the Phase 2 discovery output (the Actions REST `outputs` with `apexClass`, or the response class's `@InvocableVariable` fields, or the sample's object/array values), NOT against what the generated files happen to contain. Recall from Phase 2: a list in a response CLT is always a plain `@apexClassType/...` reference — the CLT never carries a `lightning__listType` property (the list-ness lives in the *widget* schema). Do not look for a `lightning__listType` in the CLT.
+
+1. **List the nested-object and list fields DISCOVERED in Phase 2** (from the source, not the generated CLT). For `action`, these are `outputs[]` entries with an `apexClass` key (`maxOccurs: 1` → single object; `maxOccurs > 1` → list of objects). For `apex`, they are top-level `@InvocableVariable` fields whose type is an Apex class or `List<ApexClass>`, plus fields on any nested/referenced class the payload references — those inner fields are enumerated by the class's **public / `@AuraEnabled`** members, not `@InvocableVariable` (an inner class's list/object fields are `@AuraEnabled`, never surfaced in the describe). For `sample`, they are properties whose value is an object or an array of objects. Print the list with each field's kind (single-object vs list) and, for lists, the inner class name.
+
+   Empty (payload is all primitives) → `COVERAGE: ok (no nested/list fields)`.
+
+2. **For each single nested-object field** (`@apexClassType/...` in the CLT): confirm its inner class's leaf fields appear as widget schema properties (the flatten rule), and each is bound `{!$attrs.outputValues.<objectField>.<leaf>}` in the renderer. A nested-object field whose leaves are absent from the widget schema → `COVERAGE: FAIL (<objectField> flattened leaves missing from widget)`.
+
+3. **For each list field.** The list is a plain `@apexClassType/...` reference in the CLT — either a top-level list output typed directly as `c__<Outer>$<ElementClass>`, or a field inside a wrapper `@apexClassType` object (verify the corresponding CLT property exists). Two cross-skill checks — how the widget schema/body surfaces and iterates the list is owned and validated by `platform-widget-generate`, not re-specified here:
+   - **Rendered by the delegate.** Confirm the list field is present as a property in the widget schema handed off to / produced by `platform-widget-generate` (a list property, not dropped). A discovered list field absent from the widget entirely → `COVERAGE: FAIL (<listField> is a List<ApexClass> but the widget does not render it — never declare a list "out of scope")`.
+   - **Bound in the renderer at the correct depth.** The envelope renderer binds the list at the depth its describe position dictates: **two segments** `{!$attrs.outputValues.<listField>}` for a top-level list output, or **three segments** `{!$attrs.outputValues.<wrapperField>.<listField>}` for a list inside a wrapper object (never `.<leaf>`). A missing or wrong-depth binding → `COVERAGE: FAIL (<listField> not bound at correct depth in renderer)`.
+
+4. **No drop.** A discovered nested/list field is never absent. "Beta single-response flow" / "out of scope" / "list rendering not supported" are NOT valid rationales — the skill renders lists. If a discovered nested/list field is absent → **FAIL**.
+
+**Result:** all discovered nested/list fields rendered → `pass`. Otherwise `fail (<first failing field + reason>)`.
+
+**Failure → fix:** render the field per `references/two-clt-modeling.md` ("Nested-object and list payload fields") — do not drop it. If the list-element typing is uncertain, resolve it through `platform-custom-lightning-type-generate` and `platform-widget-generate`; do not fall back to omission.
+
+---
+
 ## Warn — advisory
 
 ### `field-trace`
@@ -139,7 +180,7 @@ Enforces: no invented widget fields (subset rule) and no silent omission of resp
 
    If grep misses multi-line annotations, read the `.cls` with the Read tool and list fields manually. For the `sample` source, use the `outputValues` keys instead.
 
-   **Nested-object fields (per `references/mcp-tool-output-discovery.md` "Nested-object payload fields") expand before comparison.** A field resolved to `@apexClassType/<ns>__<OuterClass>$<InnerClass>` is not itself compared against `WIDGET_PROPS` — the widget flattens to that class's own leaf fields, never the object field. Replace that field name in `INVOCABLE_FIELDS` with its referenced class's leaf field names (its own `@InvocableVariable`/public members) before running the diff in step 3. Note the substitution in the printed output, e.g. `INVOCABLE_FIELDS (expanded): flightInfo → flightId, origin, destination, departureTime, arrivalTime, price`.
+   **Nested-object fields (per `references/mcp-tool-output-discovery.md` "Nested-object and list payload fields") expand before comparison.** A field resolved to `@apexClassType/<ns>__<OuterClass>$<InnerClass>` (single object) is not itself compared against `WIDGET_PROPS` — the widget flattens to that class's own leaf fields, never the object field. Replace that field name in `INVOCABLE_FIELDS` with its referenced class's leaf field names — enumerated by the inner class's **public / `@AuraEnabled`** members, not `@InvocableVariable` (SKILL.md Hard Rule 6; grepping an inner class for `@InvocableVariable` yields zero leaves, so the trace would spuriously pass against an empty widget) — before running the diff in step 3. Note the substitution in the printed output, e.g. `INVOCABLE_FIELDS (expanded): flightInfo → flightId, origin, destination, departureTime, arrivalTime, price`. A **list** field (`List<ApexClass>`), by contrast, is NOT flattened away — it remains a single `WIDGET_PROPS` key (the `lightning__listType` widget property), so keep the list field name in `INVOCABLE_FIELDS` as-is; its per-item leaves are `{!$item.<leaf>}` bindings inside the widget body, not top-level widget schema keys. (Whether a list is actually rendered is enforced by the hard `nested-list-coverage` gate, not here.)
 
 2. **Extract widget schema property keys:**
 
@@ -159,8 +200,7 @@ Enforces: no invented widget fields (subset rule) and no silent omission of resp
 
 4. **Result classification:**
    - `INVENTED` non-empty → **fail** (subset rule violated). `fail (invented: <list>)`.
-   - `OMITTED` non-empty AND every omitted field is in the Phase 3 `Properties omitted:` → **pass**.
-   - `OMITTED` non-empty AND any omitted field is NOT in `Properties omitted:` → **warn** (silent omission). `warn (silent omission: <list>)`, surface before the summary.
+   - `OMITTED` non-empty → **warn** (a response data field absent from the widget). `warn (omitted: <list>)`, surface before the summary.
    - Both empty → **pass**.
 
 **Reporting `pass` without printing the two lists is a hard violation — report `not run` instead.**
@@ -169,10 +209,10 @@ Enforces: no invented widget fields (subset rule) and no silent omission of resp
 
 ## Direction of the subset rule
 
-The widget `schema.json` and the response CLT `properties` are a **subset** of the response `@InvocableVariable` fields.
+The widget `schema.json` and the response CLT `properties` are a **subset** of the fields the tool exposes — the top-level response class's `@InvocableVariable` outputs, plus (when a field resolves to `@apexClassType/...`) the referenced inner class's public/`@AuraEnabled` leaves.
 
 - **No invented fields (hard via `field-trace`).** The widget must not introduce properties the response class does not expose.
-- **No silent omissions (warn).** The widget MAY omit response fields, but every omission must appear in the Phase 3 `Properties omitted:` section with a rationale.
+- **Omissions surface as a warning.** A response data field absent from the widget is reported by `field-trace` as a warning, not silently accepted.
 
 ---
 

package/skills/platform-policy-rule-generate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: platform-policy-rule-generate
-description: "Use this skill when authoring PolicyRuleDefinition and PolicyRuleDefinitionSet metadata XML for the Salesforce Enforce-O-Matic MDAPI (Data Cloud governance policies), or when editing *.policyRuleDefinition / *.policyRuleDefinitionSet files. Covers the category decision tree, full schema for all policy variants (ACCESS, GOVERNANCE, RECORD, TRANSFORM), UI-compatibility rules for the Data Governance Policy Builder, and validation guardrails. Do NOT use this skill for UserAccessPolicy, AccessPolicy, SharingRules, PermissionSet, or any non-Enforce-O-Matic access-control metadata — those have their own types and live outside the PolicyRuleDefinition schema."
+description: "Use this skill when authoring PolicyRuleDefinition and PolicyRuleDefinitionSet metadata XML for Salesforce Data Cloud governance policies, or when editing *.policyRuleDefinition / *.policyRuleDefinitionSet files. Covers the category decision tree, full schema for all policy variants (ACCESS, GOVERNANCE, RECORD, TRANSFORM), UI-compatibility rules for the Data Governance Policy Builder, output hygiene for user-facing agent responses, and validation guardrails. Do NOT use this skill for UserAccessPolicy, AccessPolicy, SharingRules, PermissionSet, or any other access-control metadata type — those have their own types and live outside the PolicyRuleDefinition schema."
 metadata:
   version: "1.0"
   minApiVersion: "64.0"
@@ -13,12 +13,10 @@ metadata:
 
 # Authoring Policy Rule Definitions
 
-**Gating:** `@WsdlGuard("EnforceOMatic.orgCanUsePolicyRuleMDAPI")` = `OrgPermissions.EnforceOMatic && OrgPermissions.PolicyRuleMDAPI` 
-**Min API version:** 64.0 (66.0 for conditions using `PolicyJsonExpression`)
+**Gating:** requires the `EnforceOMatic` and `PolicyRuleMDAPI` org permissions. 
+**Min API version:** 64.0 (66.0 for conditions using `PolicyJsonExpression`).
 
-> **For human maintainers (not the agent):** the Java source-of-truth lives at `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/` and reference fixtures at `enforce-o-matic-impl/test/func/filemetadata/<name>/`. The agent should rely on the templates and reference docs in this skill bundle — those impl paths are not readable from the Vibes/MCP runtime.
-
-This skill covers the **on-disk metadata XML format** for authoring policies. Use it whenever a task asks to write a `*.policyRuleDefinition` or `*.policyRuleDefinitionSet` file, add a fixture under `test/func/filemetadata/`, or ship a metadata package. The runtime side (RuleProvider, hooks) is out of scope.
+This skill covers the **on-disk metadata XML format** for authoring policies. Use it whenever a task asks to write a `*.policyRuleDefinition` or `*.policyRuleDefinitionSet` file, or ship a metadata package containing them. The runtime side (RuleProvider, hooks) is out of scope.
 
 ---
 
@@ -100,13 +98,12 @@ A deployable package always contains:
 
 **Category names a domain (where in the platform's enforcement layers the rule applies). Effect names the action (allow / deny / transform). They are independent except for TRANSFORM.**
 
-The **only** Category × Effect rule the platform validates
-(`enforce-o-matic-api/java/src/enforce/o/matic/api/module/api/RuleBuilder.java`):
+The **only** Category × Effect rule the platform validates:
 
 - `effect=Transform` ⇔ `category=TRANSFORM_POLICY_RULE_DEFINITION` (bidirectional; mismatched throws `INVALIDFORCATEGORY`).
 - All other categories (`ACCESS`, `GOVERNANCE`, `RECORD`, `IDENTIFIED_RECORD`) accept either `Permit` or `Forbid`.
 
-> **Note on the platform's auto-fill default:** When `<category>` is omitted from authored XML, the impl-side save hook (`PolicyRuleDefinitionObject.saveHook_Validate`) fills it in from `effect`: `Permit→ACCESS`, `Forbid→GOVERNANCE`, `Transform→TRANSFORM`. **This is a default-fill, not a validation.** If you author an explicit category that contradicts this default, it is accepted and persisted as-is.
+> **Note on the platform's auto-fill default:** When `<category>` is omitted from authored XML, the server fills it in from `effect`: `Permit→ACCESS`, `Forbid→GOVERNANCE`, `Transform→TRANSFORM`. **This is a default-fill, not a validation.** If you author an explicit category that contradicts this default, it is accepted and persisted as-is.
 
 ### Picking the category
 
@@ -179,7 +176,7 @@ Every `<conditions>` block needs **all four**: `<clause>`, `<operator>`, one pat
 | Record field = user attribute | `<resourcePath>RECORDFIELD</resourcePath>` + `<valueDomain>Schema:field</valueDomain>` | `EQUALS` | `<valuePrincipalPath>USER_ID` \| `ORGANIZATION_ID` \| `USER_ROLE_ID</valuePrincipalPath>` |
 | Entity type check | `<resourcePath>ENTITYTYPE</resourcePath>` | `IS` | `<valueString>{"t":"Text","v":"FIELD"}</valueString>` |
 
-`<conjunctionExpression>` is 1-indexed prefix notation: `1`, `(AND 1 2)`, `(OR 1 2)`, `(AND (OR 1 2) (AND 3))`. A bare top-level index like `1` is valid for **deploy** (impl fixtures use it) but **crashes the Data Governance Policy Builder UI** — see §7 if UI editability matters.
+`<conjunctionExpression>` is 1-indexed prefix notation: `1`, `(AND 1 2)`, `(OR 1 2)`, `(AND (OR 1 2) (AND 3))`. A bare top-level index like `1` is valid for **deploy** but **crashes the Data Governance Policy Builder UI** — see §7 if UI editability matters.
 
 For full path enums (`RulePrincipalPathType`, `RuleResourcePathType`, `RuleContextPathType`), operators, and JSON expressions (PROJECTION / ARGLIST / SOQLTARGETLISTEXPR), see [`references/policy-schema-full.md`](references/policy-schema-full.md). 
 For copy-paste templates for all policy variants, see [`references/templates.md`](references/templates.md).
@@ -203,7 +200,7 @@ For copy-paste templates for all policy variants, see [`references/templates.md`
 13. Standard tag/classification dev names are fully-qualified dotted paths (e.g. `DataGovernanceTags.ExternalData.Visibility.Public`). Retrieve an existing rule to get the exact string before authoring.
 14. Min API versions: `PolicyRuleDefinition` = 64.0; `PolicyJsonExpression` conditions = 66.0; `<replicated>` = 260+; `<builderCompatible>` / `<builderValidated>` = 262+.
 
-> **Note on `<conjunctionExpression>` shape:** A bare top-level index (e.g. `<conjunctionExpression>1</conjunctionExpression>`) deploys cleanly — the impl-side parser accepts bare tokens at the top level, and most positive single-condition fixtures in `enforce-o-matic-impl/test/func/filemetadata/` use it. It is **not** a deploy-time validation error. It does, however, crash the Data Governance Policy Builder UI on load — see §7.
+> **Note on `<conjunctionExpression>` shape:** A bare top-level index (e.g. `<conjunctionExpression>1</conjunctionExpression>`) deploys cleanly — the server-side parser accepts bare tokens at the top level. It is **not** a deploy-time validation error. It does, however, crash the Data Governance Policy Builder UI on load — see §7.
 
 ---
 
@@ -247,12 +244,25 @@ For the full UI-compatibility checklist, round-trip rules, and operator support
 10. **Validate with dry-run** before any non-dry deploy to a persistent org. Surface errors using the error reference in [`references/deploy-errors.md`](references/deploy-errors.md).
 
 **Three-layer correctness check** before done:
-- **Runtime / Cedar** — does the rule enforce what's intended? (action choice, condition shape)
+- **Runtime enforcement** — does the rule enforce what's intended? (action choice, condition shape)
 - **MDAPI deploy validity** — does it deploy? (§6 guardrails, scope×category, tag dev names, org perms)
 - **UI editability** — can the builder render and re-save it? (§7 checklist, OR-of-ENTITYTYPE requirement)
 
 ---
 
+## 9. Output Hygiene — What the Agent Must NOT Say to the User
+
+The agent's user-facing chat response accompanies every generated file. Customers should never see internal engine or implementation details.
+
+- **Do NOT name the internal evaluation engine** in user-facing text — including but not limited to `Cedar`, `policy engine`, `AuthZ engine`, `evaluation engine`, `Rego`, `OPA`, or similar. The customer-facing surface is *Data Governance*, *Policy Builder*, *Data Cloud Governance* — use those terms only.
+- **Do NOT emit trailing "How it works at runtime" narratives** that describe evaluation flow, principal-resource matching semantics, or engine-internal condition ordering. The generated file is the artifact; a one-line summary of what deployed is enough. If the user explicitly asks how enforcement works, describe it in product terms (e.g. "Data Governance denies the read when …"), never in engine terms.
+- **Do NOT name internal packages, source directories, Java class names, method names, or line-number references** in user-facing text. Internal implementation identifiers are not customer-facing; refer to platform behavior in product terms only ("the server validates …", "Data Governance rejects …").
+- **Do NOT explain auto-fill / default-fill / fallback semantics** unless the user asks. Ship the rule; surface constraints only when they affect what the user has to do next (e.g. "the DMO tag must exist before deploy").
+
+If the user needs more context, they'll ask — respond then, in product language.
+
+---
+
 ## Reference Docs
 
 | Detail | File |

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

@@ -51,4 +51,4 @@ sf project deploy start \
   --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.
+A `--dry-run` failure runs the full server-side validation (including the `IDENTIFIED_RECORD` constraint) 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/policy-schema-full.md

@@ -1,12 +1,10 @@
 # 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**.
+> **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.
 
 ### `<principalPath>` / `<valuePrincipalPath>` — `RulePrincipalPathType` (6 values)
 
@@ -44,13 +42,13 @@ Outside contract (not in `RulePrincipalPathType`): `IS_INTERNAL`, `CONTACT_ID`,
 
 ### `<contextPath>` / `<valueContextPath>` — `RuleContextPathType` (1 value)
 
-| Value | Cedar attribute | Use case |
-|-------|-----------------|----------|
-| `SESSION_DATASPACE` | `context.sessionDataspace` | Session-scoped dataspace check |
+| Value | Use case |
+|-------|----------|
+| `SESSION_DATASPACE` | 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.
+> `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` in `<valuePrincipalPath>` are outside `RulePrincipalPathType` — not authorable via MDAPI for new work.
 
 ---
 
@@ -71,7 +69,7 @@ Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERS
 
 ---
 
-## `<conditions>` — Full Schema (`PolicyRuleDefinitionCondition.java`)
+## `<conditions>` — Full Schema
 
 | Element | Notes |
 |---------|-------|
@@ -94,7 +92,7 @@ Outside contract: `SESSION_CONSUMER_ID`, `CONTEXT_AGENT_ID`, `CONTEXT_AGENT_VERS
 
 ---
 
-## `<policyRuleValueSet>` — `PolicyRuleValueSet.java`
+## `<policyRuleValueSet>`
 
 Three fields (all optional at schema level, but a non-empty value set needs at least one):
 
@@ -130,7 +128,7 @@ Multiple `<policyRuleValueSet>` siblings inside one condition are OR-combined.
 
 ---
 
-## JSON Expressions — `PolicyJsonExpression.java` (min API 66.0)
+## JSON Expressions (min API 66.0)
 
 `<type>` must match the location:
 
@@ -229,22 +227,3 @@ Plural (use a set operator: `CONTAINS_ANY` / `CONTAINS_NONE` / `CONTAINS_ALL`):
 | `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-advanced.md

@@ -53,6 +53,6 @@ Source: `conditionWithHierarchy`
 
 `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.
+To author one: implement it as a runtime `RuleProvider` in the consuming service, not via MDAPI XML.
 
 **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-sharing-owd-configure/SKILL.md

@@ -2,7 +2,7 @@
 name: platform-sharing-owd-configure
 description: "Use when the user wants to retrieve or update Organization-Wide Default (OWD) sharing settings for Salesforce objects. TRIGGER when: user asks to check current OWD settings, view sharing defaults, change default access levels (Private, Public Read Only, Public Read/Write, Controlled by Parent), configure internal or external access for standard or custom objects, mentions org-wide defaults, wants to make records private or restrict who can see records, wants to control default record visibility for an object, or references .settings-meta.xml sharing fields or sharingModel in .object-meta.xml files. DO NOT TRIGGER when: user asks about sharing rules, criteria-based sharing, role hierarchy, or manual sharing — delegate to platform-sharing-rules-generate."
 metadata:
-  version: "1.1"
+  version: "1.2"
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
@@ -60,21 +60,30 @@ All steps are sequential. Do not skip or reorder.
 
 ### Phase 2 — Update Settings (if requested)
 
-4. **Validate the requested access level** — read `references/access_levels.md` to confirm the value is valid for the target object.
+4. **Check for immutable/fixed OWD** — read `references/access_levels.md` "Immutable / Fixed OWD Objects" section. If the requested change targets a fixed value (e.g., Price Book external OWD), **stop immediately** and explain to the user that this value is platform-fixed and cannot be changed by any means. Do not attempt a deploy.
 
-5. **Retrieve the object metadata** using the Metadata API (same command for both standard and custom objects): `sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`. This retrieves `<ObjectName>.object-meta.xml` containing `<sharingModel>` and `<externalSharingModel>`. See `references/metadata_api_approach.md` for the full procedure.
+5. **Validate the requested access level** — read `references/access_levels.md` to confirm the value is valid for the target object. If the value is not in the allowed set for that object, explain what values are valid and ask the user to choose one. Do not guess alternative values.
 
-6. **Modify the sharing settings** — update the `<sharingModel>` (internal access) and/or `<externalSharingModel>` (external access) in the object's `.object-meta.xml`. Read `references/metadata_api_approach.md` for details.
+6. **Retrieve the object metadata** using the Metadata API (same command for both standard and custom objects): `sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`. This retrieves `<ObjectName>.object-meta.xml` containing `<sharingModel>` and `<externalSharingModel>`. See `references/metadata_api_approach.md` for the full procedure.
 
-7. **Pre-deploy verification** — before deploying, confirm:
+7. **Modify the sharing settings** — update the `<sharingModel>` (internal access) and/or `<externalSharingModel>` (external access) in the object's `.object-meta.xml`. Read `references/metadata_api_approach.md` for details.
+
+8. **Pre-deploy verification** — before deploying, confirm:
    - [ ] External access is not more permissive than internal access
    - [ ] Objects with Master-Detail relationships use `ControlledByParent`
    - [ ] The requested access level is valid for the target object (see `references/access_levels.md`)
    - [ ] Cross-object constraints are satisfied (see "Cross-Object Constraints" in `references/access_levels.md`)
+   - [ ] The target field is not listed as immutable/fixed in `references/access_levels.md`
+
+9. **Deploy the updated settings:** `sf project deploy start --metadata CustomObject:<ObjectName> --target-org <org>`.
 
-8. **Deploy the updated settings:** `sf project deploy start --metadata CustomObject:<ObjectName> --target-org <org>`. If the deploy fails, check the error message for the specific cause (see Gotchas table). A failed deploy does not change the org. To discard local edits, re-retrieve from the org: `sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`.
+10. **Handle deploy failure (max 2 attempts):** If the deploy fails:
+    - Read the error message and identify the root cause.
+    - If the error indicates the value is invalid or unsupported for the object, **stop** — report the failure to the user with the exact error message and explain what is and isn't possible. Do not try alternative values unless the user explicitly requests a different valid value.
+    - If the error is transient (network timeout, auth expired), retry **once**.
+    - **Never attempt more than 2 total deploys for the same change.** After 2 failures, report the error, discard local edits (`sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`), and ask the user how to proceed.
 
-9. **Verify the change** by re-running the query from Step 1.
+11. **Verify the change** by re-running the query from Phase 1, Step 1.
 
 ---
 
@@ -84,11 +93,13 @@ All steps are sequential. Do not skip or reorder.
 |-----------|-----------|
 | Objects with Master-Detail relationships must use `ControlledByParent` | Platform enforces this — attempting other values fails |
 | External access cannot be more permissive than internal access | Salesforce rejects configurations where external > internal |
-| Some standard objects have fixed OWD (e.g., User, Activity) | Not all objects support OWD changes |
+| Some objects have immutable/fixed OWD (e.g., Price Book external, User, Activity external) | These are platform-enforced — explain impossibility upfront, never attempt a deploy |
+| Price Book only accepts `Use` (`ReadSelect`) or `No Access` (`None`) for internal OWD; external is always `None` | Standard access levels (Private/Read/ReadWrite) are invalid for Price Book |
 | Changing OWD to more restrictive triggers sharing recalculation | This can take significant time on large orgs — warn the user |
 | Custom objects default to `Public Read/Write` when created | Users may not realize the default is permissive |
 | For managed package custom objects, use the full API name including namespace prefix (e.g., `ns__Object__c`) | Namespace-prefixed objects require the prefix in both queries and metadata retrieval |
 | Always verify the org connection before querying | Prevents confusing error messages |
+| Maximum 2 deploy attempts per change | Prevents unbounded retry loops — after 2 failures, stop and report to the user |
 
 ---
 
@@ -102,6 +113,7 @@ All steps are sequential. Do not skip or reorder.
 | `ControlledByParent` not available | Object has no Master-Detail relationship — use Private, Public Read Only, or Public Read/Write |
 | External access field not showing | External sharing model only appears when external org-wide defaults are enabled |
 | Query returns no results | Object may not be customizable or API name may be incorrect — verify spelling |
+| Deploy fails with invalid value for Price Book | Price Book only accepts `Use`/`None` (internal) and external is fixed at `None` — do not retry with other values, explain to user |
 
 ---
 

package/skills/platform-sharing-owd-configure/references/access_levels.md

@@ -21,6 +21,7 @@
 | Case | Private, Read, ReadWrite, ReadWriteTransfer | Transfer is unique to Case |
 | Lead | Private, Read, ReadWrite, ReadWriteTransfer | Transfer is unique to Lead |
 | Campaign | Private, Read, ReadWrite, FullAccess | FullAccess is unique to Campaign |
+| Pricebook2 (Price Book) | Internal: ReadSelect (Use), Read (View Only), None (No Access) | **External is fixed at `None` — immutable, cannot be changed** |
 | Custom Objects | Private, Read, ReadWrite, ControlledByParent | ControlledByParent requires Master-Detail field |
 
 ## Cross-Object Constraints
@@ -29,9 +30,21 @@
 |-----------|--------|
 | Account = Private cascades | Setting Account to Private forces Contact, Case, and Opportunity to Private — all four recalculate together |
 | Contract tied to Account | Contract OWD cannot be set independently; it follows Account's OWD |
-| Pricebook | Only accepts `Use` or `No Access` (`ReadSelect` / `None` in API) — standard access levels do not apply |
+| Pricebook (internal) | Only accepts `Use`, `View Only`, or `No Access` (`ReadSelect` / `Read` / `None` in API) — standard access levels do not apply |
+| Pricebook (external) | **Fixed at `None` (No Access) — immutable, cannot be changed via Metadata API, Tooling API, or Setup UI** |
 | ControlledByParent cascade | If a child object uses ControlledByParent, changing the parent's OWD implicitly changes the child's effective access |
 
+## Immutable / Fixed OWD Objects
+
+Some objects have OWD values that are platform-fixed and **cannot be changed by any means** (Metadata API, Tooling API, or Setup UI). Attempting to deploy a change will always fail. If the user requests a change to one of these, **explain upfront that it is not possible** — do not attempt a deploy.
+
+| Object | Field | Fixed Value | Notes |
+|--------|-------|-------------|-------|
+| Pricebook2 (Price Book) | External OWD | `None` (No Access) | Platform-enforced; only internal OWD (`Use`/`View Only`/`No Access`) is configurable |
+| User | Internal & External | Read | Cannot be changed |
+| Activity (Task/Event) | External | Private | Only internal OWD is configurable via "Activity" settings |
+| Knowledge Article | External | Controlled by separate channel visibility | Not configurable as a standard OWD |
+
 ## Internal vs External Access
 
 - **Internal access**: Applies to users within the org (internal users)