@salesforce/afv-skills 1.66.0 → 1.68.0

package/skills/service-itsm-agentic-setup-incident-management/references/major-incident-management.md

@@ -1,162 +1,39 @@
-# Feature: Major Incident Management (inline execution)
-
-How the orchestrator executes the **Major Incident Management (MIM)** feature. MIM setup is **two surfaces**
-layered on top of base Incident Management: (1) the **major-incident approval group**, and (2) **two MIM org
-preferences**. This runs **inline** through the Salesforce-hosted
-**`headless-360`** MCP server (server key `headless-360`) via its four meta-tools (`discover`, `describe`,
-`dispatch_readonly`, `dispatch`). The org comes from the OAuth JWT on the MCP session — never handle an org
-id, alias, or credentials. Minimum API version **67.0**.
-
-## Delegate every operation to the MIM Setup Operation Recipe
-
-The **Major Incident Management Setup Operation Recipe (SOR)** is the single source of truth for **how**
-each step is done — the route, method, request/response shape, field names, per-step `status`, and
-`depends_on` ordering. It is **actively evolving**, so **never hardcode a route or request body**. Carry
-only the **goal, scope, ordering, and invariants**, and at runtime:
-
-1. `discover` the operation by intent (e.g. `"set major incident approval group"`, `"validate major
-   incident approval group users"`, `"toggle major incident org preference"`).
-2. `describe` the returned SOR / operation for its **current** route, method, argument schema, and `status`.
-3. `dispatch_readonly` (reads) / `dispatch` (writes) the route the SOR names.
-
-**Use what `describe` returns — not any shape written here. If `describe` and this file disagree, `describe`
-wins.** A `discover` miss does not prove a route is absent — generic `/query` and `/sobjects/...` REST
-routes are not always ranked first; only a `404` from the dispatch itself means a route is unavailable.
-Read each step's `status` from `describe`: `implemented` = live; `proposed` = not served on every org yet.
-
-> **MIM is configured by the two surfaces below.** The only feature that must be *on* first is **base**
-> Incident Management (the master-feature steps of the `IncidentMgmt` SOR) — see Preconditions.
-
-### Transports MIM uses (all via the same `dispatch*` tools)
-
-| Transport | Shape of the `url` | Used by |
-|-----------|--------------------|---------|
-| **Aura controller** | `/headless/invoke/platform/mim/<method>` | approval-group + org-preference + group-user-validation routes |
-| **sObject REST** | `/services/data/v67.0/sobjects/...` and `/services/data/v67.0/query` | license / public-group / member records used as **preconditions** |
-
-`dispatch` takes **raw HTTP** — a full `url`, `method`, and optional `body`/`queryParams`, not
-`{operation_id, arguments}`.
-
-## Scope
-
-- **In scope**: designating / clearing / reassigning the **major-incident approval group** (a User or a
-  public Group); **group-user validation**; reading and toggling the **two** MIM org preferences; and, as a
-  precondition, licensing approvers with the **Major Incident Manager permission-set license** and standing
-  up the approvers **public group**. Verify every write by read-back.
-- **Out of scope**: base Incident Management enablement
-  (the `IncidentMgmt` SOR's master-feature steps — a prerequisite); the Incident Fulfiller / Incident Manager
-  **persona** PSG (the orchestrator's **Persona** feature — see `references/incident-persona-psg.md`);
-  Problem / Change / Case Management; the Priority Matrix; SLA / entitlement setup; any MIM org preference
-  **other than** the two allowlisted.
-
-## Preconditions
-
-The acting user needs **ITSM setup access** (the SOR gates every MIM route on it), and:
-
-1. **Base Incident Management must be enabled** — MIM layers on it. The orchestrator first follows the
-   `IncidentMgmt` SOR's read/confirm/enable/verify prerequisite; stop if it cannot confirm ENABLED.
-2. **Approvers must hold the Major Incident Manager permission-set license.** This is a **LICENSE** —
-   granted via `PermissionSetLicenseAssign` (`{AssigneeId, PermissionSetLicenseId}`), **never** a
-   `PermissionSetAssignment`. Group-user validation requires every direct and transitive user of a group
-   approver to hold it. If a designated user lacks it (or the approvers group does not exist yet), prepare
-   that first — this is **precondition prep, not MIM activation**. A **Regular** public group; add each
-   **licensed** user; **license before membership**.
-
-If a `dispatch*` returns `401` / `403` / `404`, do **not** fabricate state — surface the raw error and
-stop. `403` usually means the acting user lacks ITSM setup access.
-
-## The two surfaces — SOR step map (targets for `describe`)
-
-Describe each before calling; the ids are stable handles, the shapes come from `describe`.
-
-### Surface 1 — approval group
-
-| Step id | Transport | Purpose |
-|---------|-----------|---------|
-| `validate-group-users` | Aura `PATCH .../validate-group-users` | Returns **true** only if every direct + transitive `005…` member of the group holds the Major Incident Manager license — **call before designating a Group** |
-| `create-major-incident-approval-group` | Aura `PATCH .../create-major-incident-approval-group` | Designate the approver — a **User (005…)** or **public Group (00G…)** — stored as `SrvcMgmntApprovalAssignment` with `OperationType=MAJOR_INCIDENT_APPROVAL`. **Idempotent** (silent no-op if one exists) |
-| `verify-approval-group` | Aura `GET .../get-major-incident-approval-group` | Read the designated approver back; expect it to equal the Id you set (null when none) |
-| `remove-major-incident-approval-group` | Aura `DELETE .../remove-major-incident-approval-group` | Clear the designation — **run first to reassign** |
-
-For a **Group** approver, run **group-user validation first**: it must return **true**. If false, fix
-licensing / membership and re-validate; do not designate a group that fails. Designation is **idempotent** —
-a create when one already exists is a **silent no-op**, so a "success" does not prove your approver is the
-one set — **verify by read-back**, and **remove-first to reassign**.
-
-### Surface 2 — org preferences
-
-| Step id | Transport | Purpose |
-|---------|-----------|---------|
-| `get-mim-setup-page-org-preference` | Aura `GET .../get-mimsetup-page-org-preference` | Read one MIM preference's current boolean value |
-| `toggle-mim-setup-page-org-preference` | Aura `PATCH .../toggle-mimsetup-page-org-preference` | Set one MIM preference on / off |
-
-**Preference allowlist — exactly two names:** **`AutoCreationOfProblem`** and **`AutoClosureChildIncidents`**.
-**Any other `prefName` raises a `ServiceException` without writing** — never pass a name outside this set.
-Require an explicit on/off direction from the user (do not infer it).
-
-## Ordering (follow the SOR's `depends_on`)
-
-1. **License before membership** — a user holds the Major Incident Manager license before being added to
-   the approvers group.
-2. **Validate before designating a group** — `validate-group-users` must return **true** before
-   `create-major-incident-approval-group` with a Group.
-3. **Remove before reassign** — `remove-major-incident-approval-group` before a second create.
-
-## Workflow
-
-Always **read before you write**, **confirm before every write**, and **verify every write by read-back**.
-
-1. **Preflight** — for each in-scope surface, `discover` and `describe` for the current route, schema, and
-   `status`. On `401` / `403` / `404`, surface and stop.
-2. **Prerequisites** — confirm base Incident Management is on (else hand off), and that the approver(s) hold
-   the Major Incident Manager license (prepare it, and the public group, if needed).
-3. **Read current state** — the current approval-group designation and each preference value.
-4. **Confirm** — present the exact plan (org, approver, preference + direction) via `AskUserQuestion`;
-   require an explicit yes. On no, stop with no writes.
-5. **Apply** — validate-before-designate (for a group), remove-before-reassign; toggle only allowlisted
-   preferences. Treat a duplicate / already-set as success.
-6. **Verify** — re-read the designation and each preference; report only what read-back confirms.
-
-## Clarifying questions
-
-Ask only what you cannot infer: **which surface** (approval group, preferences, or both); **who** the
-approver is (resolve to exactly one active User `005…` or a public Group `00G…`); **which preference and
-on/off**; and **which org** — state plainly this org will be **modified** (designation, license assignment
-which consumes a seat, group changes, preference writes). For production, get explicit confirmation.
-
-## Output expectations
+# Feature: Major Incident Management (delegated to the `MIM` SOR)
+
+How the orchestrator runs the **Major Incident Management** feature: the major-incident approval group and
+the two MIM preferences, on top of base Incident Management. The `MIM` SOR's own steps and guidance decide
+*how* — the approver license, the approvers group, group validation, the designation, and the two valid
+preference names; the orchestrator runs them itself under its **SOR hand-off protocol** and owns every
+user-facing gate. This file adds what is specific to MIM.
+
+1. `discover` the SOR by intent (e.g. "set up the major incident management approval group") and
+   `describe` the id `discover` returns (`MIM`). Its IT Service Enablement and Incident Management gates
+   fall under protocol step 2.
+2. **MIM must already be active.** Run the SOR's probe (`get-mim-setup-page-org-preference`) first. If it
+   doesn't return a boolean, stop and say Salesforce provisions MIM — nothing here can turn it on.
+3. Ask only what's missing (`AskUserQuestion`): the approval group, the preferences, or both; which public
+   group approves (the `MajorIncidentApprovers` group or an existing public group the user names — if they
+   name a person, offer to put them in a public group); and, for a preference, which one and on or off
+   (never infer the direction).
+4. **Approval group.** Read the current designation (`verify-approval-group`). Query for the
+   `MajorIncidentApprovers` group (`verify-approvers-public-group`) and reuse it if it exists; create it
+   only when none does. License and add only the members who still need it. Then run `validate-group-users`
+   on that exact group — it changes nothing, so it needs no confirmation of its own — and designate only
+   when it returns true. If it returns false, say the group isn't valid yet (every member needs the Major
+   Incident Manager license, and the group can't be empty) and offer to license the members or pick another
+   group.
+5. Confirm the full plan before any write — the licenses to assign (each uses a seat), the group changes,
+   the designation or reassignment, and each preference with its direction — and that this org is modified
+   (explicit confirmation for production). Read every write back through its verify step.
+6. Report with the block below, only what read-back confirmed, omitting the parts the user didn't choose.
+   In plain language: no Major Incident Manager license on the org means it lacks the MIM add-on; a full
+   license means a seat must free up first; a `403` means an admin with ITSM setup access must do it.
 
 ```text
 Major Incident Management
 
   Approvers licensed (N) ............ Licensed N | M already held
-  Approval group designated ......... <user/group> | Already designated | Reassigned
+  Approvers group ................... Created | Reused · N members added
+  Approval group designated ......... <group> | Already designated | Reassigned
   Preferences ....................... Auto-create problem: on/off · Auto-close child incidents: on/off
 ```
-
-Report only what read-back confirmed; omit lines for surfaces out of the requested scope. If base Incident
-Management cannot be confirmed on, say so and stop without configuring MIM.
-
-## Common failures (surface in plain language)
-
-| Symptom | Likely cause | What to tell the user |
-|---------|--------------|-----------------------|
-| Group validation returns false | A direct / nested member lacks the Major Incident Manager license | License every member first, then re-validate before designating the group |
-| Approval group "designated" but unchanged | A designation already existed — it is idempotent | To change the approver, the old designation is removed first, then the new one set |
-| Preference change rejected (`ServiceException`) | A preference name outside the allowlist was sent | Only auto-create problem and auto-close child incidents are configurable here |
-| Seat / limit error on the license | No free Major Incident Manager seats | A seat must free up (or more licenses added) before that user can be an approver |
-| `400 DUPLICATE_VALUE` on a license / group / member write | The record already exists | Idempotent success — report as already-done |
-| `403` on a MIM route | Acting user lacks ITSM setup access | An admin with ITSM setup access must perform this |
-| `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
-
-## Dead ends — do NOT do these
-
-- Hardcode any route / body — `describe` at runtime; the SOR is evolving.
-- Grant the Major Incident Manager license with a `PermissionSetAssignment` — it is a **license**
-  (`PermissionSetLicenseAssign`).
-- Add a user to the approvers group before licensing them.
-- Designate a **group** approver without `validate-group-users` returning **true** first.
-- Reassign without removing the existing designation first (create is a silent no-op).
-- Send any preference name other than `AutoCreationOfProblem` / `AutoClosureChildIncidents`.
-- Attempt MIM setup when base Incident Management is off — first complete the `IncidentMgmt` master-feature prerequisite.
-- Pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP.

package/skills/service-itsm-agentic-setup-incident-management/references/manage-incidents-with-ai.md

@@ -0,0 +1,45 @@
+# Feature: Manage Incidents with AI (delegated to the `service-itsm-manage-incidents-with-ai-configure` SOR)
+
+How the orchestrator runs the **Manage Incidents with AI** feature: the three switches in the *Manage
+Incidents with AI* section of Salesforce Go's IT Service Incident Management page — *Automatically Triage
+Incidents*, *Let Einstein Assign Incidents* and *Report Incidents from Chat or Voice Using AI*. The SOR's own
+steps and guidance decide *how*; the orchestrator runs them itself under its **SOR hand-off protocol** and
+owns every user-facing gate. This file adds what is specific to this feature.
+
+1. `discover` the SOR by intent (e.g. "manage incidents with AI") and `describe` the id `discover` returns.
+   Its own prerequisite checks fall under protocol step 2.
+2. If the request already says what to change, follow the SOR's rule: setting up the whole section turns
+   on all three switches, and a request about one switch changes only that one and leaves the other two as
+   they are. Otherwise read all three, show them with the block below, and ask which to change and in which
+   direction (`AskUserQuestion`) — never infer the direction from the current state. Read each switch before
+   changing it, and skip any already in the requested state.
+3. Confirm the exact change, write each chosen switch and read each back; mark the feature `Done` only
+   when every read-back matches.
+4. If triage or Einstein assignment can't be read or changed, the org lacks that switch's license (*IT
+   Services: Agentforce Features for Employees* for triage, *IT Services: Einstein Features* for Einstein
+   assignment): say so, skip it, and carry on with the others.
+5. When turning on the chat and voice switch, ask whether the org already captures transcripts (an active
+   messaging channel for chat, call transcription for voice); set one up only if the user asks, through the
+   SOR's channel hand-offs. Offer the SOR's smoke test only after that switch reads on — it drafts from one
+   conversation the user names and creates nothing.
+6. Triage and Einstein assignment are the same org preferences as the *Automatically Triage Incidents* and
+   *Assign Incidents with Einstein* toggles of **Incident Preferences**, so a switch set in either feature
+   reads as already set in the other.
+
+```text
+  Automatically Triage Incidents ................. On | Off
+  Let Einstein Assign Incidents .................. On | Off
+  Report Incidents from Chat or Voice Using AI ... On | Off
+
+Changed: <label> Off → On (SUCCEEDED | ALREADY-ON | FAILED)
+```
+
+## Rules
+
+- ALWAYS change only the switches the user chose, confirm before the write, and verify by read-back before
+  marking it `Done` (or verify the already-set state by live read with no write)
+
+## Before marking it `Done`
+
+- [ ] Only the chosen switches changed; any write was confirmed before it ran and verified by read-back,
+      and a no-write `Done` came from a live read

package/skills/service-itsm-agentic-setup-incident-management/references/priority-matrix.md

@@ -0,0 +1,32 @@
+# Feature: Priority Matrix (delegated to the `IncidentPriorityMatrix` SOR)
+
+How the orchestrator runs the **Priority Matrix** feature, which maps each Impact × Urgency combination on
+Incident to a Priority. The `IncidentPriorityMatrix` SOR's own steps and guidance decide *how*; the
+orchestrator runs them itself under its **SOR hand-off protocol** and owns every user-facing gate. This file
+adds what is specific to the Priority Matrix.
+
+1. `discover` the SOR by intent (e.g. "incident priority matrix impact urgency") and `describe` the id
+   `discover` returns (`IncidentPriorityMatrix`). Its own prerequisite checks fall under protocol step 2.
+2. Read first: the org's **active** Incident `Priority` values (`describe-incident-priority-picklist` —
+   never hardcode or invent them), the current rows (`fetch-priority-matrix`), both preferences
+   (`read-priority-matrix-prefs`, one call each: `IncPriorityMatrixEnabled`, the *Turn on Automatic
+   Priority Assignment for IT Service* toggle, and `IncPriorityOverrideEnabled`, the *Set priority
+   manually* checkbox), and the default priority (`get-default-priority`).
+3. Ask only for what's missing: which cells change, the default priority, and whether manual override
+   changes. Offer only active values, and flag a saved row whose Priority is no longer active rather than
+   dropping it. If the matrix is off, include turning it on in the plan — with it off, Incidents don't get
+   a priority from the matrix.
+4. **The save is a full replacement**: `save-priority-matrix` deletes every row it isn't sent. Build the
+   complete set from the fetched rows, change only the cells the user asked to change, and keep the
+   override as read unless asked. Show which cells are added, changed, or removed, the resulting default,
+   and the override state, and get an explicit yes. Re-run `describe-incident-priority-picklist` right
+   before the save and send only its active values. A change to only the matrix toggle or only the
+   override uses `update-priority-matrix-enablement` instead, one preference per call, confirmed the same
+   way.
+5. Read back with `verify-priority-matrix` (rows), `verify-default-priority`, and `verify-manual-override`
+   (or `verify-priority-matrix-enablement` after a toggle-only change). Mark it `Done` only when every part
+   matches.
+6. Only after a real write landed this run — never on a view or a no-op — mark the Salesforce Go *Define
+   Priority Matrix* step complete (`mark-priority-matrix-step-complete`, then
+   `verify-priority-matrix-step-complete`). A `404` there doesn't fail the feature: tell the user to tick
+   that step manually on the Salesforce Go page.

package/skills/service-itsm-agentic-setup-incident-management/references/service-mgmt-privilege.md

@@ -1,120 +1,31 @@
-# Feature: Service Management Privilege (inline execution)
-
-How the orchestrator executes the **Service Management Privilege** feature — ITSM **privilege escalation**
-setup: the org-wide **escalation level**, the **Service Management Privilege** definitions (each with a
-name, description, tag, access level, and function type), and **bulk employee ↔ privilege assignments**, all
-behind the **Enable Privilege Assignment** master toggle. This runs **inline** through the Salesforce-hosted
-**`headless-360`** MCP server (server key `headless-360`) via its four meta-tools (`discover`, `describe`,
-`dispatch_readonly`, `dispatch`). The org comes from the OAuth JWT on the MCP session — never handle an org
-id, alias, or credentials. Minimum API version **67.0**.
-
-## Delegate every operation to the Setup Operation Recipe
-
-The **Service Management Privilege Setup Operation Recipe (SOR)** is the single source of truth for **how**
-each step is done — the route, method, request/response shape, field names, per-step `status`, and
-`depends_on`. It is **draft and actively evolving**, so **never hardcode a route or request body**. Carry
-only the **goal, scope, ordering, and invariants**, and at runtime:
-
-1. `discover` the operation by intent (e.g. `"enable privilege assignment toggle"`, `"set ITSM escalation
-   level"`, `"create a service management privilege"`, `"assign employees to a service privilege"`).
-2. `describe` the returned SOR / operation for its **current** route, method, argument schema, and `status`.
-3. `dispatch_readonly` (reads) / `dispatch` (writes) the route the SOR names.
-
-**Use what `describe` returns — not any shape written here. If `describe` and this file disagree, `describe`
-wins.** Read each step's `status` from `describe`: `implemented` = live; `proposed` = not served on every org
-yet. **There is no public Connect / Tooling / Metadata / sObject substitute for this feature** — the setup
-controller is the only surface. So if `discover`/`describe` does not surface a step or a `dispatch` returns
-`404`, the surface is **not available on this org yet** — surface that plainly and stop; **never fabricate a
-fallback route.**
-
-## The four surfaces — SOR step map (targets for `describe`)
-
-Describe each before calling; the step ids are stable handles, the shapes come from `describe`.
-
-### Surface 1 — the Enable Privilege Assignment master toggle (`implemented`)
-
-Backed by the generic **SetupMetadata** org-preference batch operations (not the privilege controller),
-keyed on the org preference **`PrivilegeAssignmentEnabled`**.
-
-| Step id | Purpose |
-|---------|---------|
-| `check-privilege-assignment-enabled` | Read whether `PrivilegeAssignmentEnabled` is on |
-| `set-privilege-assignment-enabled` | Turn the feature on / off — **reversible** |
-| `verify-set-privilege-assignment-enabled` | Read `PrivilegeAssignmentEnabled` back to confirm the write |
-
-### Surface 2 — escalation level
-
-| Step id | Purpose |
-|---------|---------|
-| `fetch-escalation-level` | Read the org-wide ITSM escalation level |
-| `save-escalation-level` | Set the escalation level (`escalationLevel`) |
-| `verify-save-escalation-level` | Read the level back to confirm |
-
-### Surface 3 — Service Management Privilege definitions
-
-| Step id | Purpose |
-|---------|---------|
-| `get-service-privileges` | List every privilege (id, name, description, tag, access level, function type) — **drives verify** |
-| `create-service-privilege` | Add a privilege from a field map |
-| `update-service-privilege` | Edit a privilege (field map keyed by its id) |
-| `delete-service-privilege` | Remove a privilege by id — **destructive, no rollback** |
-
-### Surface 4 — employee assignments
-
-| Step id | Purpose |
-|---------|---------|
-| `save-privilege-assignments` | Bulk add / remove employees for one privilege (add-list + remove-list, both in one call) — **no read-back** |
-
-## Scope
-
-- **In scope**: read / set the **Enable Privilege Assignment** master toggle; read / set the org-wide
-  **escalation level**; list / create / update / delete **Service Management Privilege** definitions; bulk
-  **add / remove employee assignments** for a privilege; verify by read-back where one exists.
-- **Out of scope**: base Incident Management enablement (the `IncidentMgmt` SOR's master-feature steps); the
-  Incident Fulfiller / Incident Manager **persona** PSG (the orchestrator's **Persona** feature); the Major
-  Incident Manager approver licensing (the **Major Incident Management** feature); Problem / Change / Case
-  Management; the Priority Matrix; SLA setup.
-
-## Preconditions
-
-- **ITSM setup access** — the SOR gates every route on it (`IncidentMgmt.userHasITSMSetupAccess`). A `403`
-  means the acting user lacks it; an admin with ITSM setup access must perform this.
-- **The Enable Privilege Assignment master toggle is the UI entry gate**, not a server precondition. The
-  privilege controller does **not** re-check it, so turning it on is **workflow ordering** — enable it first
-  so the escalation and privilege-management surfaces are coherent, but it does not hard-block the other
-  writes. It is **reversible** (it can be turned back off — unlike the one-way incident preferences).
-
-## Ordering (follow the SOR's `depends_on`)
-
-1. **Toggle first** — if `PrivilegeAssignmentEnabled` is off and the user wants to configure the feature,
-   enable it before touching escalation level or privileges (workflow ordering, not a hard gate).
-2. **Read before every write** — the current toggle state, escalation level, or privilege list.
-3. **Verify definition writes** — re-read via `get-service-privileges` after each create / update / delete.
-4. **Assignments have no read-back** — you cannot confirm them by re-read; report them as **applied**, never
-   as verified.
-
-## Workflow
-
-Always **read before you write**, **confirm before every write**, and **verify every write by read-back**
-where a read-back exists.
-
-1. **Preflight** — for each in-scope surface, `discover` and `describe` for the current route, schema, and
-   `status`. On `401` / `403` / `404`, surface and stop.
-2. **Read current state** — the toggle, the escalation level, and/or the current privileges.
-3. **Confirm** — present the exact plan (org, toggle direction, escalation value, privilege change, or the
-   employees to add/remove) via `AskUserQuestion`; require an explicit yes. On no, stop with no writes.
-4. **Apply** — toggle first if needed; then the requested write. Treat a duplicate / already-set as success.
-5. **Verify** — re-read the toggle, the escalation level, and the privilege list; for assignments, state
-   plainly they were applied but cannot be read back.
-
-## Clarifying questions
-
-Ask only what you cannot infer: **which surface** (master toggle, escalation level, privilege definitions,
-or employee assignments); for a **privilege**, its fields (name, description, tag, access level, function
-type); for **assignments**, the target privilege and exactly which employees to add / remove; and **which
-org** — state plainly this org will be **modified**. For production, get explicit confirmation.
-
-## Output expectations
+# Feature: Service Management Privilege (delegated to the `ServiceMgmtPrivilegeSetup` SOR)
+
+How the orchestrator runs the **Service Management Privilege** feature — ITSM privilege escalation: the
+*Enable Privilege Assignment* toggle, the org-wide escalation level, the privilege definitions, and bulk
+employee assignments. The `ServiceMgmtPrivilegeSetup` SOR's own steps and guidance decide *how* — the
+toggle's place in the order, the privilege fields, Tag-first handling, and which writes can be read back;
+the orchestrator runs them itself under its **SOR hand-off protocol** and owns every user-facing gate. This
+file adds what is specific to this feature.
+
+1. `discover` the SOR by intent (e.g. "set up ITSM service management privilege escalation") and `describe`
+   the id `discover` returns (`ServiceMgmtPrivilegeSetup`). Its IT Service Enablement check falls under
+   protocol step 2. No other public API covers this feature: a `404` or a `discover` miss means it isn't
+   served on this org — say so and stop; never look for another route.
+2. Ask which part the user wants (`AskUserQuestion`): the escalation level, the privileges, or employee
+   assignments. Read the toggle (`check-privilege-assignment-enabled`) first. If it reads off, turn it on —
+   it's reversible — with the user's yes, before any escalation-level or privilege step, as the SOR orders
+   it; if they decline, stop.
+3. For a new privilege, ask its tag, access level, and description (the SOR sets the rest). If the tag isn't
+   on the Tag field yet (the SOR's `new-tag-needed` choice), the user adds it in Object Manager after their
+   explicit OK — never dispatch `add-privilege-tag-value`. For assignments, ask the privilege and exactly
+   which employees to add or remove.
+4. Confirm the full plan before any write — the toggle, the escalation value, each privilege change, and the
+   employees to add and remove — and that this org is modified (explicit confirmation for production). A
+   privilege delete is **irreversible**: confirm it on its own, and never delete to test.
+5. Read every write back: the toggle and the escalation level through their verify steps, and each
+   privilege create, update, or delete by re-listing the privileges (`get-service-privileges`). Employee
+   assignments have no read-back: report them as applied, never as verified. A `403` means an admin with
+   ITSM setup access (and, from API 68.0, Customize Application) must make the change.
 
 ```text
 Service Management Privilege
@@ -124,26 +35,5 @@ Service Management Privilege
   Employee assignments .............. Applied: +N / -M (not read-back verifiable)
 ```
 
-Report only what read-back confirmed; for assignments, report them as applied and say they cannot be
-verified by re-read. Omit lines for surfaces out of the requested scope.
-
-## Common failures (surface in plain language)
-
-| Symptom | Likely cause | What to tell the user |
-|---------|--------------|-----------------------|
-| `403` on any route | Acting user lacks ITSM setup access | An admin with ITSM setup access must perform this |
-| `404` / step not discoverable | The surface is `proposed`, not served on this org yet | This feature isn't available on this org yet — there is no alternative API path |
-| Delete rejected or unexpected | Wrong privilege id, or it no longer exists | Re-list privileges and confirm the exact one to remove |
-| Assignment "done" but can't confirm | Assignments have no read-back | The change was applied; it cannot be confirmed by re-reading — check in Setup if needed |
-| `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
-
-## Dead ends — do NOT do these
-
-- Hardcode any route / body — `discover` + `describe` at runtime; the SOR is draft and evolving.
-- Fabricate a Connect / Tooling / Metadata / sObject fallback — **none exists**; a `404` means the surface
-  isn't served on this org yet, so surface and stop.
-- Delete a Service Management Privilege to test, or without an explicit confirmation — it is **irreversible**.
-- Claim an employee assignment is **verified** — `save-privilege-assignments` has **no read-back**.
-- Treat the Enable Privilege Assignment toggle as a hard server gate — it is the UI entry gate (reversible)
-  and the controller does not re-check it; enabling it is workflow ordering.
-- Pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP.
+Report only what read-back confirmed, and omit the lines the user didn't choose. The persona PSGs, the
+Major Incident Manager license, and Problem / Change Management are outside this feature.

package/skills/service-itsm-agentic-setup-incident-management/references/sla-milestones.md

@@ -0,0 +1,110 @@
+# Feature: SLA & Milestones (delegated to the `SLASettings` and `sla-management-setup` SORs)
+
+How the orchestrator runs the **SLA & Milestones** feature: completing the **SLA Management for IT Service**
+setup item, then giving Incidents an SLA — Salesforce's **predefined** *Standard Support for Incidents*
+policy, or a **custom** Incident policy with its milestones, optional milestone actions (warn / escalate),
+and the activation that provisions its Entitlement. `SLASettings` owns the gate and the predefined seed;
+`sla-management-setup` and the write leaves its steps delegate to own the custom policy. Their own steps and
+guidance decide *how* — the bodies, the order, and the read-backs; the orchestrator runs them itself under
+its **SOR hand-off protocol** and owns every user-facing gate. This file adds what is specific to Incident
+SLAs.
+
+> **Casing override — load-bearing.** `SLASettings` lists the seed values and the existence-map keys as
+> `Incident` / `Problem` / `ChangeRequest`. The server uses **lowercase**: the map comes back keyed
+> `incident` / `problem` / `changeRequest`, and the seed must send `{"selectedOptions": ["incident"]}` —
+> the capitalized `Incident` fails with a server error. This is the one place this file overrides
+> `describe`.
+
+1. `discover` the SORs by intent (e.g. "turn on SLA management and SLA versioning, predefined incident SLA
+   policy"; "create an incident SLA policy with milestones") and `describe` the ids `discover` returns
+   (`SLASettings`, `sla-management-setup`, and each leaf a step delegates to). Their IT Service Enablement
+   checks fall under protocol step 2. Incident only: never seed or build a Case, Problem, or Change Request
+   policy.
+2. **The gate.** *SLA Management for IT Service* is set up only when both `get-sla-management-permission`
+   and `get-sla-versioning-permission` read `true` — then it passes with no question. Otherwise ask once
+   (`AskUserQuestion`): completing it turns on **SLA Management** (it can be turned off again later) and, as
+   a separate step, **SLA Versioning**, which **can't be turned off once enabled** — turning SLA Management
+   off later won't turn Versioning off. Options: **Enable** / **Stop — make no changes**. There is no
+   "without Versioning" option, and a bare or repeated "enable SLA" is not consent to the permanent switch.
+   On Enable, set only the switches that read `false` — SLA Management first, then Versioning — and require
+   each verify step to read `true` before the next write. *"Entitlements permission not enabled…"* means
+   Entitlement Management is off: point the user to **Setup → Entitlement Settings** and stop. Stop on
+   Stop, a failed write, or a re-read that isn't `true`; an SLA Management enable that already landed may
+   stand — say what is on.
+3. **Detect the predefined policy** (`get-existing-checkbox-states`). `incident: true` means *Standard
+   Support for Incidents* already exists: say so, **never re-seed** (the seed isn't idempotent — a second
+   run duplicates every artifact), and stop unless the user explicitly asks for a custom policy. Don't
+   upsell one.
+4. **Read what the choice needs** — from `IncidentPriorityMatrix`, only these two reads: the active Incident
+   `Priority` values (`describe-incident-priority-picklist`) and the matrix flag
+   (`read-priority-matrix-prefs`, `IncPriorityMatrixEnabled`). With the matrix off, every Incident gets the
+   default priority, so only that tier's milestones fire: warn plainly and point to the **Priority Matrix**
+   feature. A warning, never a gate — never turn the matrix on from here.
+5. **Predefined or custom.** Ask (`AskUserQuestion`): **Predefined — *Standard Support for Incidents*
+   (Recommended)** or **Custom**. The seed builds an **active** policy and its Entitlement in one step, with
+   no un-seed (a manual delete only): two milestone types (*Acknowledge Within*, *Resolve Within*) and six
+   milestones (Critical 30 / 120 min, High 60 / 240, Moderate or Low 240 / 960). Recommend Custom instead
+   when the org has active `Priority` values beyond those four (they'd get no milestone), or the user wants
+   specific Business Hours (the seed takes none) or milestone actions — this feature never edits an existing
+   policy. **Predefined:** confirm, run `save-selected-options` with the lowercase `incident`, then
+   `verify-save-selected-options` (expect `incident: true`), and stop.
+6. **Custom — plan.** The policy type is Incident (never ask), and there is no Account — an Incident engages
+   its SLA through its Entitlement. Skip the SOR's update, delete, and version steps: editing or versioning
+   an existing policy is outside this feature.
+   - **Name and hours.** The default name is *Incident SLA Policy*; if `get-sla-policies` shows it taken,
+     ask for another. No hours named → leave Business Hours empty (24×7), as `create-sla-policy` says.
+     Named hours → resolve them as that leaf's Business Hours input describes; if no active record
+     matches, offer 24×7 or stop so the user can create them in **Setup → Business Hours** — this feature
+     never creates them.
+   - **Milestones.** Skip the question when the request already gives a concrete shape ("60-minute first
+     response", "per-priority tiers"); otherwise ask (`AskUserQuestion`):
+
+     | # | Option | Milestones (minutes) |
+     |---|--------|----------------------|
+     | 1 | Single | *Incident First Response* 60 |
+     | 2 | Response + Resolution | *Incident First Response* 30, *Incident Resolution* 480 |
+     | 3 | Priority-tiered | Critical 15, High 60, Moderate 240, Low 1440 — one per active `Priority` value, all *Incident First Response* |
+     | 4 | Escalation ladder | *Incident First Response* 30, *Incident Manager Escalation* 120, *Incident Executive Escalation* 480 (concurrent timers) |
+     | 5 | Custom | Per milestone: its name, minutes, and condition |
+
+     Every milestone's criteria start from `Incident.Status` not equal to `Closed`, ANDed with its own
+     condition. For options 3 and 5, reconcile with the live `Priority` values both ways: rename a renamed
+     tier, drop an inactive one, and add a milestone for an extra active one (confirm its minutes).
+   - **Milestone actions, only if asked.** The default is a Field Update on Incident — `Urgency` to `High`
+     at the warning and `Impact` to `High` at the breach — never `Priority`, which the Priority Matrix
+     derives from Impact × Urgency. "Warn at X%" is an offset of round(target × (1 − X/100)) before the
+     target (120 min at 75% → 30); "escalate on breach" is a Violation at 0. Apply the checkpoints to every
+     milestone the user named, and give each action a unique name per milestone (suffix `_FR`, `_RES`, …).
+   - **Confirm the plan** before the first write: the policy name, the Business Hours by name (or 24×7),
+     the **full** milestone list (never "N milestones"), every action, the matrix-off note if it applies,
+     and that the policy engages per Incident through its Entitlement.
+7. **Custom — build** in `sla-management-setup`'s order, through its steps and the leaves they delegate to:
+   the milestone types, the policy, each milestone, the actions (each confirmed as the
+   `create-milestone-action` leaf describes, including its `verify-milestone-action` read-back), then
+   activation.
+   - Check Entitlement Management once, with `sla-management-setup`'s `check-entitlements-enabled`, and
+     follow that step if it reads `false` — never a leaf's own check (some turn it on unasked).
+   - **Halt on the first failed milestone** — nothing after it is created; say which one failed.
+   - **Org-wide auto-apply** (`create-entitlement-criteria`) runs only on an explicit request that every
+     Incident match, after a warning that it collides with any existing broad Incident policy. Otherwise
+     say the policy engages per Incident and no criterion was created.
+   - **Another active Incident policy** stays untouched — never offer to deactivate, reorder, broaden, or
+     rank it. Narrate: "your existing *<name>* policy stays active; this custom policy is applied per
+     Incident by setting the Incident's Entitlement to it."
+
+```text
+SLA & Milestones
+  SLA Management for IT Service ... On | Turned on now
+  SLA Versioning .................. On | Turned on now (permanent)
+  Policy .......................... Standard Support for Incidents (predefined — seeded now | already present)
+                                    | <name> (custom — created)
+  Business Hours .................. <name> | 24×7
+  Milestones ...................... <type name> — <minutes> min — <criteria>   (one line each)
+  Entitlement ..................... Provisioned on activation (no Account)
+  Actions ......................... <tier or type> — <Warning | Violation> — <offset>   (one line each)
+  Scope ........................... Incident SLA only
+```
+
+Report only what read-back confirmed, name every artifact (never a record Id, even masked), and omit the
+lines that don't apply. Case SLAs, Problem and Change Request policies, editing an existing policy,
+assignment and escalation rules, and SLA reporting are outside this feature.