@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/service-itsm-agentic-setup-incident-sla-configure/references/mcp-invocation.md

@@ -396,10 +396,10 @@ mcp__headless-360__dispatch({
     "businessHoursId":  "<BusinessHoursId>",
     "timeTrigger":      60,
     "order":            1,
-    "startTimeBasedOn": "SlaProcessCreatedDate",
+    "startTimeBasedOn": "MILESTONE_CRITERIA",
     "milestoneCriteria": [
       {
-        "milestoneState":         "Active",
+        "milestoneState":         "ACTIVE",
         "milestoneAgreementType": "SLA",
         "filterType":             "RuleFilter",
         "filterItems": [
@@ -411,7 +411,11 @@ mcp__headless-360__dispatch({
 })
 ```
 
-`milestoneCriteria` is mandatory. `milestoneAgreementType` is mandatory per the UI and lives **inside each `milestoneCriteria[]` item** (it maps to the `MilestoneCriteria.MilestoneAgreementType` sub-entity field — sending it at the top level of the milestone body returns `JSON_PARSER_ERROR: Unrecognized field`). Valid UI values are **`SLA`** (customer-facing agreement) or **`OLA`** (internal / operational). The API accepts any string because the underlying field is plain `Text(40)` with no server-side picklist enforcement — an unrecognized value persists to the DB but the UI treats it as blank; omitting the field entirely also succeeds silently but leaves the record's Milestone Agreement Type null (W-23959162). Success: `body.id` is the new Milestone Id.
+**`startTimeBasedOn`** controls when the timer starts. Send **`"MILESTONE_CRITERIA"`** (matches OOB and every default pattern) to start the clock when the milestone's ACTIVE criteria first match. It is a free string with two recognized values — **`MILESTONE_CRITERIA`** (criteria-based / dynamic start) and **`SLA_PROCESS`** (the fallback); any other value silently defaults to the `SLA_PROCESS` behavior (no error). The fallback anchors the timer to the **Incident's `SlaStartDate`** (→ its `CreatedDate` if `SlaStartDate` is null) — **not** the SLA-process record's created date. **This choice is not runtime-verifiable in the standard verify flow:** for a test Incident that matches the SLA at creation, both settings compute the same `TargetDate` (≈ `SlaStartDate + timeTrigger`) — they diverge only when the criteria first match *after* creation (e.g. a later field change), which the Phase 3 test does not exercise. So send the OOB value and rely on it; there is no Phase-3 assertion that distinguishes the two (unlike the ACTIVE criterion, whose effect **is** observable via tiering — see below). `milestoneCriteria` is mandatory. `milestoneAgreementType` is mandatory per the UI and lives **inside each `milestoneCriteria[]` item** (it maps to the `MilestoneCriteria.MilestoneAgreementType` sub-entity field — sending it at the top level of the milestone body returns `JSON_PARSER_ERROR: Unrecognized field`). Valid UI values are **`SLA`** (customer-facing agreement) or **`OLA`** (internal / operational). The API accepts any string because the underlying field is plain `Text(40)` with no server-side picklist enforcement — an unrecognized value persists to the DB but the UI treats it as blank; omitting the field entirely also succeeds silently but leaves the record's Milestone Agreement Type null (W-23959162). Success: `body.id` is the new Milestone Id.
+
+**`milestoneState` MUST be UPPERCASE and comes from a fixed set — this is load-bearing.** Valid values are **`ACTIVE`**, **`COMPLETE`**, **`PAUSE`**, **`UNPAUSE`** (there is **no `CANCEL`** state). `MilestoneService` compares `milestoneState` against `"ACTIVE"` with a **case-sensitive** `String.equals`, so `"Active"`/`"active"` (or any wrong case) **silently fails to register the ACTIVE criterion** — the create still returns `201 success:true`, but the priority/entry filter is never written and the Setup UI shows blank Activation Criteria. The milestone loses its Priority gate, so **in practice every Incident engages the lowest-`order` milestone of that MilestoneType regardless of its Priority** — a priority-tiered policy collapses to one tier. Use `ACTIVE` for the engagement (Priority) criterion and `COMPLETE` for the completion (Status) criterion; never send `CANCEL` (once the `ACTIVE` Priority criterion is correct it gates engagement, making a cancel criterion redundant).
+
+**The create response NEVER echoes `milestoneCriteria` — it always returns `milestoneCriteria: []` even on success** (the create handler only sets `id`/`success`; only a subsequent GET/read-back populates criteria). So the `201` proves nothing about whether criteria persisted. **Verify by runtime, not the response:** after seeding, create a **non-matching-tier** test Incident (e.g. a Moderate/Low one for a Critical-first policy) and confirm its `EntityMilestone.TargetResponseInMins` matches that tier's `timeTrigger`, not order-1's. A Critical-only test can't catch a dropped criterion because Critical maps to order-1, which is also the collapse fallback.
 
 ---
 
@@ -573,11 +577,15 @@ Success: `body.id`.
 ## Predefined Incident Policy (Phase 0.6 detect + Phase 2-OOB seed)
 
 The out-of-box **"Standard Support for Incidents"** policy is what Salesforce seeds from Setup's
-"Create Predefined Policies" step (Incident process type only). That step is Aura-only and not
-headless-reachable, but it seeds via the **same backend** as the public `/connect/sla-management/*`
-routes above — so the skill replicates it exactly with routes it already uses. The full template
-(policy flags, 2 milestone types, 8 priority-tiered milestones, entitlement criterion) lives in
-**`assets/predefined-incident-policy.json`** — load and follow it; the values below are the shape.
+"Create Predefined Policies" step (Incident process type only). That step is **Aura-only** — the
+checkbox calls `DefaultSlaPolicyController.saveSelectedOptions`, an `@AuraEnabled` controller whose
+only caller of `DefaultSlaService.createDefaultSlaPolicies` is that Aura action; there is **no public
+REST/Connect wrapper**, so the headless MCP cannot invoke the seeder directly. But the seeder just
+reads core's `default-sla-policies/incident.json` and writes it through the **same backend** as the
+public `/connect/sla-management/*` routes above — so the skill replicates that resource's exact
+output with routes it already uses. The full template (policy flags, 2 milestone types, **6
+milestones**, entitlement criterion) lives in **`assets/predefined-incident-policy.json`** — load
+and follow it; the values below are the shape.
 
 ### Detect first (no server idempotency → mandatory)
 
@@ -607,17 +615,24 @@ Uses the Phase 2 routes above, in this order:
    First read the catalog — SOQL `SELECT Id, Name FROM MilestoneType WHERE Name IN ('Acknowledge
    Within', 'Resolve Within')` (or `GET .../milestone-types`) — **reuse any match by id**, and `POST
    .../milestone-types` (`recurrenceType: OneTime`) **only** for the name(s) not already present.
-   Capture both ids (whether reused or created).
+   Capture both ids (whether reused or created) **for chaining only — when you narrate the reuse,
+   name the type ("reusing the existing First Response type"); never append its queried Id, masked or
+   full (Output contract).**
 2. Create the SLA Policy `Standard Support for Incidents` (`POST .../sla-policies`) with
    `processType: "Incident"`, `businessHourId` = default, `createdDateEntryCriteria: true`,
    `closedExitCriteria: true`, `versionDefault: true`, **`active: true`** (create it active directly —
-   do **not** use the Connect activate PATCH, which can 500 headless). Verify via SOQL on `SlaProcess`.
-3. Attach the **8 priority-tiered milestones** (`POST .../sla-policies/<id>/milestones`, one per row).
-   Reuse `assets/attach-milestone.json`. Validate each Priority/Status value against the live
-   `Incident` picklist first. For the **mid tier**, map to the org's actual mid-priority label —
-   `Moderate` on the standard ITSM picklist, but many orgs label it `Medium` — and seed orders 5–6
-   with whichever the live picklist carries rather than dropping the tier. Drop a row **only** when its
-   value is genuinely absent from the picklist, and note any dropped or relabeled tier in the report.
+   do **not** use the Connect activate PATCH, which can 500 headless). Verify via SOQL on `SlaProcess`,
+   then narrate the policy by that verified name — never the captured/queried Id (Output contract).
+3. Attach the **6 milestones** (`POST .../sla-policies/<id>/milestones`, one per row). Reuse
+   `assets/attach-milestone.json`. Send **`startTimeBasedOn: "MILESTONE_CRITERIA"`** on every
+   milestone — the OOB timer starts when the milestone criteria first match; the public route reads
+   this exact token (`MilestoneService` treats `MILESTONE_CRITERIA` as the criteria-based/dynamic
+   start; its only other recognized value, `SLA_PROCESS`, anchors to the Incident's `SlaStartDate`).
+   Validate each Priority/Status value against the live `Incident` picklist first. For the **mid
+   tier**, map to the org's actual mid-priority label — `Moderate` on the standard ITSM picklist, but
+   many orgs label it `Medium` — inside the merged orders 5–6 `Priority` OR rows (keep the `Low` row).
+   Drop a row from the OR **only** when its value is genuinely absent from the picklist, and note any
+   dropped or relabeled tier in the report.
 
 | order | milestoneType | timeTrigger | active criterion (Priority) | completion (Status) |
 |-------|---------------|-------------|-----------------------------|---------------------|
@@ -625,23 +640,31 @@ Uses the Phase 2 routes above, in this order:
 | 2 | Resolve Within     | 120 | `Equals Critical` | `In [Resolved, Completed, Closed]` |
 | 3 | Acknowledge Within | 60  | `Equals High` | `NotEqual New` |
 | 4 | Resolve Within     | 240 | `Equals High` | `In [Resolved, Completed, Closed]` |
-| 5 | Acknowledge Within | 240 | `Equals Moderate` | `NotEqual New` |
-| 6 | Resolve Within     | 960 | `Equals Moderate` | `In [Resolved, Completed, Closed]` |
-| 7 | Acknowledge Within | 240 | `Equals Low` | `NotEqual New` |
-| 8 | Resolve Within     | 960 | `Equals Low` | `In [Resolved, Completed, Closed]` |
-
-The **active** criterion (`Priority Equals <tier>`) is the one the public Attach-Milestone
-`milestoneCriteria` carries (`milestoneState: Active`, `milestoneAgreementType: SLA`,
-`filterType: RuleFilter`) — seeding it engages each milestone. The OOB also carries completion
-(`Status In …`) and cancel (`Priority NotEqual <tier>`) criteria (`milestoneState` Complete / Cancel);
-confirm the route accepts those states in the smoke test — if not, the active criterion alone is
-sufficient for engagement (matches `examples/milestone-patterns.md` Pattern 3).
-
-**OR / In have no single-row form.** `filterItems` AND by default and there is no `In` operator. The
-Priority tiers are already pre-split above (each row is a single `Priority Equals <tier>`, Moderate and
-Low as separate rows 5–8), so no OR is needed for Priority. For the `Status In` completion sets, either
-use `filterLogic: "1 OR 2"` if the route accepts it (verify live) or split into one row per value —
-behavior-equivalent.
+| 5 | Acknowledge Within | 240 | `Equals Moderate` OR `Equals Low` (`filterLogic: "1 OR 2"`) | `NotEqual New` |
+| 6 | Resolve Within     | 960 | `Equals Moderate` OR `Equals Low` (`filterLogic: "1 OR 2"`) | `In [Resolved, Completed, Closed]` |
+
+This mirrors core's `default-sla-policies/incident.json` shape: Critical and High are per-tier;
+**Moderate and Low are one merged tier** (ACTIVE `filterLogic "1 OR 2"` over two Priority Equals rows).
+
+The **active** criterion is the one the public Attach-Milestone `milestoneCriteria` carries
+(`milestoneState: ACTIVE`, `milestoneAgreementType: SLA`, `filterType: RuleFilter`) — seeding it
+**is what tiers the policy**: it gates which Incidents engage each milestone. Because all three tiers
+reuse the same two MilestoneTypes, if the ACTIVE criterion fails to persist (e.g. a wrong-case
+`milestoneState` — see the case-sensitivity warning above), the milestone loses its Priority gate and
+in practice every Incident engages the lowest-`order` milestone (Critical, 30/120) regardless of Priority. Each milestone also carries a
+completion criterion (`milestoneState: COMPLETE`, `Status In …`). **The core template's per-tier
+CANCEL criterion is intentionally dropped** — the public route has no `CANCEL` state, and once the
+ACTIVE Priority criterion is correct it already prevents off-tier engagement, so a cancel criterion is
+redundant. **Verify tiering by runtime** (see the case-sensitivity warning): seed, then create a
+**Moderate/Low** test Incident and confirm its `EntityMilestone` lands on the 240/960 tier, not 30/120.
+
+**Priority OR is expressed via `filterLogic`, not an `In` operator.** `filterItems` AND by default and
+there is no `In` operator, but the merged Moderate-or-Low tier's ACTIVE criterion uses
+`filterLogic: "1 OR 2"` across two `Priority Equals` rows — the same `customLogicExpression` the
+public milestone-criteria route consumes, so no separate per-value milestone is needed. If the live
+route rejects `filterLogic`, fall back to two separate `Priority Equals` milestones (Moderate, Low)
+with the same timeTriggers — behavior-equivalent. The `Status In` completion sets use the same
+`filterLogic: "1 OR 2 OR 3"` pattern (split into one row per value if the route rejects it).
 
 4. Create the Entitlement (`POST /sobjects/Entitlement`) on the resolved Account, `SlaProcessId` =
    the seeded policy, backdated `StartDate`. **Attempt** the OOB always-match entitlement criterion
@@ -658,8 +681,11 @@ behavior-equivalent.
    fields (a wrong-payload `400`, not a platform gap), and misattributing it reads as a bug. Never
    surface the raw sentinel string or a `JSON_PARSER_ERROR` in the customer report. The date-windowed
    Entitlement plus the milestone criteria are still enough to engage the Phase 3 test Incident.
-5. Verify per **Verify SLA engagement** below with a **Critical** test Incident (a Critical Priority
-   matches orders 1–2, so an `EntityMilestone` spawns), then **STOP** — do not offer custom.
+   Narrate the Entitlement by name/Account, never its returned Id (Output contract).
+5. Verify per **Verify SLA engagement** below with a **Moderate/Low** test Incident — its
+   `EntityMilestone` must land on the 240/960 tier, not 30/120. Use a non-lowest tier: Critical is
+   order-1, the collapse fallback, so it spawns a milestone even when the ACTIVE criterion was dropped
+   and can't detect the bug. Then **STOP** — do not offer custom.
 
 ---
 
@@ -705,10 +731,10 @@ mcp__headless-360__dispatch_readonly({
 | `dispatch` shape is raw HTTP | Pass `{url, method, body?, query_params?}` — NOT `{operation_id, arguments}`. |
 | Response wrapper | Connect/`/sobjects`/`/query` are singly wrapped — read `body`. Aura `/headless/invoke/…` routes (not used here) are doubly wrapped. |
 | Corpus vs. registry drift | `discover` may not rank the SLA POST routes at the top — the routes are still known-good; `describe` + `dispatch` on the canonical path works either way. |
-| SLA Policy create response is null | `POST /sla-policies` echoes most fields as `null` — always verify via SOQL on `SlaProcess`. |
+| SLA Policy create response is null | `POST /sla-policies` echoes most fields as `null` — always verify via SOQL on `SlaProcess`; then narrate the policy by the **verified name**, never the captured/queried Id (Output contract). |
 | Milestone filter payload | `milestoneCriteria` is mandatory (omitting it → `400: Criteria details cannot be empty`). Use `filterType: "RuleFilter"` with concrete `filterItems[]` — `filterType: "Formula"` triggers a 500. Operators are `Equals` (not `Equal`) and `NotEqual` (not `NotEquals`/`NotEqualTo`/`!=`); wrong forms → `POST_BODY_PARSE_ERROR: Invalid value for Filter Operation Enum`. |
 | `slaProcessId` rejected in body | The server returns `JSON_PARSER_ERROR: Unrecognized field "slaProcessId"` — the id is in the path only. |
 | Entitlement create + status | Create via `POST /sobjects/Entitlement` (standard sObject, not the Connect surface). Status is date-computed: a future `StartDate` → `Inactive`; backdate `StartDate` to yesterday for immediate SLA engagement in testing. |
 | OOB seed has no idempotency | `POST .../sla-policies` does not dedupe — re-seeding "Standard Support for Incidents" duplicates every artifact. Detect first via `GET .../sla-policies?processTypes=Incident` and name-match before seeding. |
 | Connect activate PATCH may 500 | The OOB backend flips the policy active via a Connect activate call; headless, that PATCH can 500. Create the SlaProcess with `active: true` directly instead (as the custom flow does). |
-| Never leak a record Id | In **every** user-facing message (interim narration *and* the final report, incl. "created milestone …" progress lines), refer to the Phase-3 test Incident by its **`IncidentNumber`** (the verify SOQL selects it) and milestones by their **`MilestoneType.Name`** — never the 15/18-char record Id. |
+| Never leak a record Id (SKILL.md Output contract) | In **every** user-facing message — interim narration *and* the final report, incl. "created milestone …" / "policy created …" / "reusing existing … →" progress lines — refer to the Phase-3 test Incident by its **`IncidentNumber`** (the verify SOQL selects it) and milestones/policy by their **name** — never the 15/18-char record Id (full **or masked**, e.g. `557VW…R3XVYA0`) or a `triggerId`. This covers **detected/reused** artifacts too — no `→ <Id>` "proof of reuse". Ids stay internal (chaining only). |

package/skills/service-omni-attribute-routing-configure/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: service-omni-attribute-routing-configure
+description: "Use to manage Omni-Channel attribute-based routing rules through the Tooling API. TRIGGER when: list attribute-routing rules, inspect a WorkSkillRouting rule, create an inactive routing rule, add a field-to-skill mapping, activate a complete routing rule, deactivate a routing rule, or delete a routing rule or attribute. Do not use to create agent skills or routing flows."
+allowed-tools: Bash Read Write Grep Glob
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "service-omni-work-skill-routing-configure"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.10"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-attribute-routing-configure
+
+Manage the full `WorkSkillRouting` and `WorkSkillRoutingAttribute` lifecycle using the approved Tooling API contract. Create rules inactive, add all mappings, and activate only after at least one mapping exists.
+
+## Usage
+
+```bash
+bash scripts/configure-and-report.sh <org> list
+bash scripts/configure-and-report.sh <org> get <rule-id>
+bash scripts/configure-and-report.sh <org> create <developer-name> <label> <related-entity>
+bash scripts/configure-and-report.sh <org> add-attribute <rule-id> <Entity.Field> <value> <skill-id> <level> <related-entity> [additional] [priority]
+bash scripts/configure-and-report.sh <org> set-active <rule-id> true|false
+CONFIRM_DELETE=1 bash scripts/configure-and-report.sh <org> delete-attribute <attribute-id>
+CONFIRM_DELETE=1 bash scripts/configure-and-report.sh <org> delete-rule <rule-id>
+```
+
+## Safety and behavior
+
+- Reads require View Setup. Writes require Customize Application and are refused on production customer orgs.
+- Omni-Channel and Skills-Based Routing must be enabled, and referenced `Skill` records must already exist.
+- Creation always starts inactive. Activation reads the complete Metadata compound, preserves all mappings, removes the read-only `urls` member, changes only `isActive`, and verifies with a cold read.
+- The script rejects activation without mappings, invalid skill levels, invalid additional-skill priorities, and deletion without `CONFIRM_DELETE=1`.
+- Existing identical mappings are reused.
+
+## Boundaries
+
+Use `service-omni-work-skill-routing-configure` for the simpler one-mapping Metadata API workflow. Use this skill when the user explicitly needs Tooling CRUD, multiple mappings, activation control, or deletion.
+
+## Reference
+
+Read [references/api-notes.md](references/api-notes.md) before changing the payload or compound Metadata handling.

package/skills/service-omni-attribute-routing-configure/references/api-notes.md

@@ -0,0 +1,7 @@
+# Attribute-routing Tooling API contract
+
+Live API v68 describe validation confirms Tooling API CRUD for `WorkSkillRouting` and `WorkSkillRoutingAttribute` on orgs provisioned for Skills-Based Routing. A rule is created inactive, populated with one or more child mappings, and activated only when complete.
+
+`PATCH WorkSkillRouting/{Id}` replaces the entire Metadata compound. Always read first, preserve `masterLabel`, `relatedEntity`, and `workSkillRoutingAttributes`, remove the read-only `urls` member, then write the complete compound. Omitting the nested mappings deletes them.
+
+Eligible related entities are Case, ChangeRequest, ContactRequest, FlowOrchestrationWorkItem, Incident, Lead, LiveChatTranscript, MessagingSession, Order, Problem, SocialPost, VoiceCall, and WorkOrder. `SkillLevel` is 0–10. `SkillPriority` is 0–4 and is valid only when `IsAdditionalSkill=true`.

package/skills/service-omni-attribute-routing-configure/scripts/configure-and-report.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  bash configure-and-report.sh <org> list
+  bash configure-and-report.sh <org> get <rule-id>
+  bash configure-and-report.sh <org> create <developer-name> <label> <related-entity>
+  bash configure-and-report.sh <org> add-attribute <rule-id> <field> <value> <skill-id> <level> <related-entity> [additional] [priority]
+  bash configure-and-report.sh <org> set-active <rule-id> true|false
+  CONFIRM_DELETE=1 bash configure-and-report.sh <org> delete-attribute <attribute-id>
+  CONFIRM_DELETE=1 bash configure-and-report.sh <org> delete-rule <rule-id>
+EOF
+}
+
+emit_blocked() {
+  jq -n --arg operation "$OPERATION" --arg issue "$1" \
+    '{skill:"service-omni-attribute-routing-configure",status:"blocked",operation:$operation,result:null,blocking_issue:$issue}'
+  exit 1
+}
+
+valid_id() { [[ "$1" =~ ^[A-Za-z0-9]{15,18}$ ]]; }
+valid_name() { [[ "$1" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; }
+valid_entity() {
+  case "$1" in
+    Case|ChangeRequest|ContactRequest|FlowOrchestrationWorkItem|Incident|Lead|LiveChatTranscript|MessagingSession|Order|Problem|SocialPost|VoiceCall|WorkOrder) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+safe_to_write() {
+  local org_json is_sandbox trial_exp org_type
+  org_json=$(sf data query --target-org "$ORG" --json \
+    --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" 2>/dev/null) \
+    || emit_blocked "Failed to establish the target org safety boundary."
+  is_sandbox=$(jq -r '.result.records[0].IsSandbox // false' <<<"$org_json")
+  trial_exp=$(jq -r '.result.records[0].TrialExpirationDate // "null"' <<<"$org_json")
+  org_type=$(jq -r '.result.records[0].OrganizationType // ""' <<<"$org_json")
+  if [ "$is_sandbox" != "true" ] && [ "$trial_exp" = "null" ] \
+     && [ "$org_type" != "Developer Edition" ] && [ "$org_type" != "Base Edition" ]; then
+    emit_blocked "Refusing to change attribute routing in a production customer org. Use a sandbox, trial, Developer Edition, or Base Edition org."
+  fi
+}
+
+request() {
+  local method="$1" endpoint="$2" body="${3:-}"
+  if [ -n "$body" ]; then
+    REQUEST_OUTPUT=$(FORCE_COLOR=0 sf api request rest "$endpoint" --method "$method" --body "$body" --target-org "$ORG" 2>/dev/null) \
+      || emit_blocked "The Tooling API $method operation failed."
+  else
+    REQUEST_OUTPUT=$(FORCE_COLOR=0 sf api request rest "$endpoint" --method "$method" --target-org "$ORG" 2>/dev/null) \
+      || emit_blocked "The Tooling API $method operation failed."
+  fi
+  if [ -z "$REQUEST_OUTPUT" ] && { [ "$method" = "PATCH" ] || [ "$method" = "DELETE" ]; }; then
+    REQUEST_OUTPUT='{}'
+  fi
+  jq -e . >/dev/null 2>&1 <<<"$REQUEST_OUTPUT" \
+    || emit_blocked "The Tooling API $method operation returned malformed JSON."
+}
+
+delete_tooling_record() {
+  local object="$1" record_id="$2"
+  DELETE_OUTPUT=$(FORCE_COLOR=0 sf data delete record --target-org "$ORG" --json --api-version "$API_VERSION" --use-tooling-api \
+    --sobject "$object" --record-id "$record_id" 2>/dev/null) \
+    || emit_blocked "The Tooling API DELETE operation failed."
+  jq -e '.status == 0 and .result.success == true' >/dev/null 2>&1 <<<"$DELETE_OUTPUT" \
+    || emit_blocked "The Tooling API DELETE operation returned an unsuccessful result."
+}
+
+ensure_available() {
+  request GET "$BASE/sobjects/WorkSkillRouting/describe"
+  [ "$(jq -r '.createable // false' <<<"$REQUEST_OUTPUT")" = "true" ] \
+    || emit_blocked "WorkSkillRouting is unavailable or read-only. Enable Omni-Channel and Skills-Based Routing, then retry."
+}
+
+[ $# -ge 2 ] || { usage; exit 2; }
+ORG="$1"
+OPERATION="$2"
+shift 2
+API_VERSION="${SF_API_VERSION:-68.0}"
+BASE="/services/data/v${API_VERSION}/tooling"
+
+sf org display --target-org "$ORG" --json >/dev/null 2>&1 \
+  || emit_blocked "The target org is not authenticated or cannot be reached."
+
+case "$OPERATION" in
+  list)
+    [ $# -eq 0 ] || { usage; exit 2; }
+    result=$(sf data query --target-org "$ORG" --use-tooling-api --json \
+      --query "SELECT Id, DeveloperName, MasterLabel, IsActive, RelatedEntity FROM WorkSkillRouting ORDER BY DeveloperName" 2>/dev/null) \
+      || emit_blocked "WorkSkillRouting is unavailable. Enable Omni-Channel and Skills-Based Routing, then retry."
+    jq -n --argjson records "$(jq -c '.result.records // []' <<<"$result")" \
+      '{skill:"service-omni-attribute-routing-configure",status:"analyzed",operation:"list",result:{records:$records,count:($records|length)},blocking_issue:null}'
+    ;;
+  get)
+    [ $# -eq 1 ] && valid_id "$1" || emit_blocked "get requires a valid 15- or 18-character WorkSkillRouting Id."
+    request GET "$BASE/sobjects/WorkSkillRouting/$1"
+    result="$REQUEST_OUTPUT"
+    jq -n --argjson record "$result" \
+      '{skill:"service-omni-attribute-routing-configure",status:"analyzed",operation:"get",result:{record:$record},blocking_issue:null}'
+    ;;
+  create)
+    [ $# -eq 3 ] || emit_blocked "create requires developer-name, label, and related-entity."
+    developer_name="$1"; label="$2"; entity="$3"
+    valid_name "$developer_name" || emit_blocked "Invalid routing-rule developer name."
+    valid_entity "$entity" || emit_blocked "Unsupported related entity '$entity'."
+    ensure_available
+    existing_query=$(sf data query --target-org "$ORG" --use-tooling-api --json \
+      --query "SELECT Id FROM WorkSkillRouting WHERE DeveloperName = '$developer_name' LIMIT 1" 2>/dev/null) \
+      || emit_blocked "Failed to check for an existing attribute-routing rule."
+    existing_id=$(jq -r '.result.records[0].Id // empty' <<<"$existing_query")
+    if [ -n "$existing_id" ]; then
+      request GET "$BASE/sobjects/WorkSkillRouting/$existing_id"
+      existing="$REQUEST_OUTPUT"
+      existing_label=$(jq -r '.Metadata.masterLabel // .MasterLabel // empty' <<<"$existing")
+      existing_entity=$(jq -r '.Metadata.relatedEntity // .RelatedEntity // empty' <<<"$existing")
+      existing_active=$(jq -r '.Metadata.isActive // .IsActive // false' <<<"$existing")
+      [ "$existing_label" = "$label" ] && [ "$existing_entity" = "$entity" ] && [ "$existing_active" = "false" ] \
+        || emit_blocked "A routing rule named '$developer_name' already exists with different label, entity, or activation state."
+      jq -n --argjson record "$existing" \
+        '{skill:"service-omni-attribute-routing-configure",status:"reused",operation:"create",result:{record:$record},blocking_issue:null}'
+      exit 0
+    fi
+    safe_to_write
+    body=$(jq -cn --arg fullName "$developer_name" --arg label "$label" --arg entity "$entity" \
+      '{FullName:$fullName,Metadata:{masterLabel:$label,relatedEntity:$entity,isActive:false}}')
+    request POST "$BASE/sobjects/WorkSkillRouting" "$body"
+    created="$REQUEST_OUTPUT"
+    id=$(jq -r '.id // empty' <<<"$created")
+    [ -n "$id" ] || emit_blocked "The Tooling API did not return the created routing-rule Id."
+    request GET "$BASE/sobjects/WorkSkillRouting/$id"
+    verified="$REQUEST_OUTPUT"
+    jq -n --argjson create "$created" --argjson record "$verified" \
+      '{skill:"service-omni-attribute-routing-configure",status:"created",operation:"create",result:{create:$create,record:$record},blocking_issue:null}'
+    ;;
+  add-attribute)
+    [ $# -ge 6 ] && [ $# -le 8 ] || emit_blocked "add-attribute requires rule-id, field, value, skill-id, level, related-entity, and optional additional/priority."
+    rule_id="$1"; field="$2"; value="$3"; skill_id="$4"; level="$5"; entity="$6"; additional="${7:-false}"; priority="${8:-}"
+    valid_id "$rule_id" && valid_id "$skill_id" || emit_blocked "Rule Id and Skill Id must be valid Salesforce record Ids."
+    [[ "$field" =~ ^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9_]*$ ]] || emit_blocked "Field must be entity-qualified, for example Case.Priority."
+    jq -en --arg level "$level" '($level|tonumber) >= 0 and ($level|tonumber) <= 10' >/dev/null 2>&1 \
+      || emit_blocked "Skill level must be between 0 and 10."
+    valid_entity "$entity" || emit_blocked "Unsupported related entity '$entity'."
+    field_entity="${field%%.*}"; field_name="${field#*.}"
+    [ "$field_entity" = "$entity" ] || emit_blocked "Field '$field' does not belong to related entity '$entity'."
+    [ "$additional" = "true" ] || [ "$additional" = "false" ] || emit_blocked "additional must be true or false."
+    if [ -n "$priority" ]; then
+      [ "$additional" = "true" ] || emit_blocked "Skill priority is valid only for an additional skill."
+      [[ "$priority" =~ ^[0-4]$ ]] || emit_blocked "Skill priority must be between 0 and 4."
+    fi
+    ensure_available
+    request GET "$BASE/sobjects/WorkSkillRoutingAttribute/describe"
+    [ "$(jq -r '.createable // false' <<<"$REQUEST_OUTPUT")" = "true" ] \
+      || emit_blocked "WorkSkillRoutingAttribute is unavailable or read-only on this org."
+    safe_to_write
+    request GET "$BASE/sobjects/WorkSkillRouting/$rule_id"
+    existing="$REQUEST_OUTPUT"
+    parent_entity=$(jq -r '.Metadata.relatedEntity // empty' <<<"$existing")
+    [ "$parent_entity" = "$entity" ] || emit_blocked "Related entity '$entity' does not match the parent rule ('$parent_entity')."
+    request GET "/services/data/v${API_VERSION}/sobjects/${entity}/describe"
+    field_describe="$REQUEST_OUTPUT"
+    field_type=$(jq -r --arg field "$field_name" '.fields[] | select(.name==$field) | .type' <<<"$field_describe" | head -1)
+    case "$field_type" in picklist|boolean|reference|id) ;; *) emit_blocked "Field '$field' is not an eligible picklist, boolean, reference, or id field." ;; esac
+    if [ "$field_type" = "picklist" ]; then
+      jq -e --arg field "$field_name" --arg value "$value" \
+        '.fields[] | select(.name==$field) | [.picklistValues[]? | select(.active==true and .value==$value)] | length > 0' \
+        <<<"$field_describe" >/dev/null || emit_blocked "Value '$value' is not an active value for '$field'."
+    elif [ "$field_type" = "boolean" ]; then
+      [ "$value" = "true" ] || [ "$value" = "false" ] || emit_blocked "Boolean field '$field' requires value true or false."
+    fi
+    distinct_fields=$(jq '[.Metadata.workSkillRoutingAttributes[]?.field] | unique | length' <<<"$existing")
+    field_already_used=$(jq --arg field "$field" '[.Metadata.workSkillRoutingAttributes[]? | select(.field==$field)] | length' <<<"$existing")
+    [ "$distinct_fields" -lt 10 ] || [ "$field_already_used" -gt 0 ] \
+      || emit_blocked "A routing rule supports at most 10 distinct fields."
+    existing_count=$(jq --arg field "$field" --arg value "$value" --arg skill "$skill_id" \
+      '[.Metadata.workSkillRoutingAttributes[]? | select(.field==$field and .value==$value and ((.skillId // .skill) == $skill))] | length' <<<"$existing")
+    if [ "$existing_count" -gt 0 ]; then
+      jq -n --argjson record "$existing" \
+        '{skill:"service-omni-attribute-routing-configure",status:"reused",operation:"add-attribute",result:{record:$record},blocking_issue:null}'
+      exit 0
+    fi
+    body=$(jq -cn --arg rule "$rule_id" --arg field "$field" --arg value "$value" --arg skill "$skill_id" \
+      --arg entity "$entity" --arg level "$level" --arg additional "$additional" --arg priority "$priority" \
+      '{WorkSkillRoutingId:$rule,Field:$field,Value:$value,SkillId:$skill,SkillLevel:($level|tonumber),RelatedEntity:$entity,IsAdditionalSkill:($additional=="true")}
+       + (if $priority=="" then {} else {SkillPriority:($priority|tonumber)} end)')
+    request POST "$BASE/sobjects/WorkSkillRoutingAttribute" "$body"
+    created="$REQUEST_OUTPUT"
+    attribute_id=$(jq -r '.id // empty' <<<"$created")
+    [ -n "$attribute_id" ] || emit_blocked "The Tooling API did not return the created attribute Id."
+    request GET "$BASE/sobjects/WorkSkillRoutingAttribute/$attribute_id"
+    verified="$REQUEST_OUTPUT"
+    jq -n --argjson create "$created" --argjson record "$verified" \
+      '{skill:"service-omni-attribute-routing-configure",status:"created",operation:"add-attribute",result:{create:$create,record:$record},blocking_issue:null}'
+    ;;
+  set-active)
+    [ $# -eq 2 ] && valid_id "$1" || emit_blocked "set-active requires a valid rule Id and true or false."
+    [ "$2" = "true" ] || [ "$2" = "false" ] || emit_blocked "set-active value must be true or false."
+    ensure_available
+    safe_to_write
+    request GET "$BASE/sobjects/WorkSkillRouting/$1"
+    current="$REQUEST_OUTPUT"
+    metadata=$(jq -c --argjson active "$2" '.Metadata | del(.urls) | .isActive=$active' <<<"$current")
+    [ "$2" = "false" ] || [ "$(jq '.workSkillRoutingAttributes // [] | length' <<<"$metadata")" -gt 0 ] \
+      || emit_blocked "Refusing to activate a routing rule without attribute mappings."
+    request PATCH "$BASE/sobjects/WorkSkillRouting/$1" "$(jq -cn --argjson metadata "$metadata" '{Metadata:$metadata}')"
+    request GET "$BASE/sobjects/WorkSkillRouting/$1"
+    verified="$REQUEST_OUTPUT"
+    [ "$(jq -r '.Metadata.isActive' <<<"$verified")" = "$2" ] || emit_blocked "Activation verification did not match the requested state."
+    jq -n --argjson record "$verified" \
+      '{skill:"service-omni-attribute-routing-configure",status:"updated",operation:"set-active",result:{record:$record},blocking_issue:null}'
+    ;;
+  delete-attribute|delete-rule)
+    [ $# -eq 1 ] && valid_id "$1" || emit_blocked "$OPERATION requires a valid Salesforce record Id."
+    [ "${CONFIRM_DELETE:-0}" = "1" ] || emit_blocked "Deletion requires explicit CONFIRM_DELETE=1."
+    ensure_available
+    safe_to_write
+    object="WorkSkillRoutingAttribute"; [ "$OPERATION" = "delete-rule" ] && object="WorkSkillRouting"
+    delete_tooling_record "$object" "$1"
+    jq -n --arg operation "$OPERATION" --arg id "$1" \
+      '{skill:"service-omni-attribute-routing-configure",status:"deleted",operation:$operation,result:{id:$id},blocking_issue:null}'
+    ;;
+  *) usage; exit 2 ;;
+esac

package/skills/service-omni-attribute-routing-configure/scripts/tests/test_attribute_routing_contracts.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SCRIPT = SKILLS_ROOT / "service-omni-attribute-routing-configure/scripts/configure-and-report.sh"
+DEFAULT_SF = """#!/usr/bin/env bash
+[ "$1 $2" = "org display" ] && echo '{"status":0,"result":{}}' && exit 0
+echo unexpected >&2
+exit 1
+"""
+
+
+def run_script(*args: str, sf_source: str = DEFAULT_SF, extra_env: dict[str, str] | None = None):
+    with tempfile.TemporaryDirectory(prefix="attribute-routing-sf-") as directory:
+        sf = Path(directory) / "sf"
+        sf.write_text(sf_source)
+        sf.chmod(0o755)
+        env = dict(os.environ)
+        env["PATH"] = directory + os.pathsep + env.get("PATH", "")
+        env.update(extra_env or {})
+        return subprocess.run(["bash", str(SCRIPT), *args], capture_output=True, text=True, env=env)
+
+
+class AttributeRoutingContracts(unittest.TestCase):
+    def test_script_syntax(self):
+        result = subprocess.run(["bash", "-n", str(SCRIPT)], capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_create_rejects_unsupported_entity_before_write(self):
+        result = run_script("org", "create", "Rule", "Rule", "Account")
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("Unsupported related entity", result.stdout)
+
+    def test_create_reuses_matching_inactive_rule(self):
+        sf_source = """#!/usr/bin/env bash
+case "$1 $2" in
+  "org display") echo '{"status":0,"result":{}}' ;;
+  "api request")
+    if [[ " $* " == *"WorkSkillRouting/describe"* ]]; then
+      echo '{"createable":true}'
+    elif [[ " $* " == *"WorkSkillRouting/0Xaxx0000000001AAA"* ]]; then
+      echo '{"Id":"0Xaxx0000000001AAA","Metadata":{"masterLabel":"Eval Case Routing","relatedEntity":"Case","isActive":false,"workSkillRoutingAttributes":[]}}'
+    else
+      exit 1
+    fi
+    ;;
+  "data query")
+    if [[ " $* " == *" FROM WorkSkillRouting WHERE DeveloperName = 'Eval_Case_Routing' "* ]]; then
+      echo '{"status":0,"result":{"records":[{"Id":"0Xaxx0000000001AAA"}]}}'
+    else
+      exit 1
+    fi
+    ;;
+  *) exit 1 ;;
+esac
+"""
+        result = run_script(
+            "org", "create", "Eval_Case_Routing", "Eval Case Routing", "Case",
+            sf_source=sf_source,
+        )
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        response = json.loads(result.stdout)
+        self.assertEqual(response["status"], "reused")
+        self.assertEqual(response["result"]["record"]["Id"], "0Xaxx0000000001AAA")
+
+    def test_supported_service_entities_include_voice_and_incident(self):
+        source = SCRIPT.read_text()
+        self.assertIn("Incident", source)
+        self.assertIn("VoiceCall", source)
+        self.assertIn("ChangeRequest", source)
+        self.assertIn("Problem", source)
+
+    def test_add_attribute_rejects_level_above_ten(self):
+        result = run_script(
+            "org", "add-attribute", "0Xaxx0000000001AAA", "Case.Priority", "High",
+            "0C5xx0000000001AAA", "10.1", "Case",
+        )
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("between 0 and 10", result.stdout)
+
+    def test_activation_preserves_complete_metadata(self):
+        source = SCRIPT.read_text()
+        self.assertIn(".Metadata | del(.urls) | .isActive=$active", source)
+        self.assertIn("workSkillRoutingAttributes", source)
+
+    def test_failures_are_emitted_from_parent_shell(self):
+        source = SCRIPT.read_text()
+        self.assertNotIn("$(request ", source)
+        self.assertIn('REQUEST_OUTPUT=$(FORCE_COLOR=0 sf api request rest', source)
+
+    def test_deletes_require_explicit_confirmation(self):
+        result = run_script("org", "delete-rule", "0Xaxx0000000001AAA")
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("CONFIRM_DELETE=1", result.stdout)
+
+    def test_deletes_use_tooling_data_delete_instead_of_bodyless_rest(self):
+        cases = (
+            ("delete-rule", "WorkSkillRouting", "0Xaxx0000000001AAA"),
+            ("delete-attribute", "WorkSkillRoutingAttribute", "0Yaxx0000000001AAA"),
+        )
+        for operation, object_name, record_id in cases:
+            with self.subTest(operation=operation):
+                sf_source = f"""#!/usr/bin/env bash
+case "$1 $2" in
+  "org display") echo '{{"status":0,"result":{{}}}}' ;;
+  "api request")
+    case " $* " in *" --method DELETE "*) exit 23 ;; *) echo '{{"createable":true}}' ;; esac
+    ;;
+  "data query") echo '{{"status":0,"result":{{"records":[{{"IsSandbox":true,"TrialExpirationDate":null,"OrganizationType":"Enterprise Edition"}}]}}}}' ;;
+  "data delete")
+    [ "$3" = "record" ] || exit 1
+    [[ " $* " == *" --sobject {object_name} "* ]] || exit 1
+    [[ " $* " == *" --record-id {record_id} "* ]] || exit 1
+    [[ " $* " == *" --use-tooling-api "* ]] || exit 1
+    echo '{{"status":0,"result":{{"id":"{record_id}","success":true,"errors":[]}}}}'
+    ;;
+  *) exit 1 ;;
+esac
+"""
+                result = run_script(
+                    "org", operation, record_id,
+                    sf_source=sf_source,
+                    extra_env={"CONFIRM_DELETE": "1"},
+                )
+                self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+                self.assertEqual("deleted", json.loads(result.stdout)["status"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)