@salesforce/afv-skills 1.55.0 → 1.56.0

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

@@ -1,127 +1,193 @@
 ---
 name: service-itsm-agentic-setup-incident-management
-description: "Orchestrator skill for setting up Incident Management features in Salesforce Service Cloud ITSM. Use when the user asks to set up incident management, configure ITSM incident features, wants a guided walkthrough of incident management configuration, or asks what incident features are available to configure. Presents the available Incident Management capabilities and delegates each selection to a specialized child skill — currently SLA & Milestones — while tracking progress across the setup. Triggers on: set up incident management, configure ITSM incident features, incident management walkthrough, incident management capabilities, what incident features can I configure. DO NOT TRIGGER when: the user asks about a specific feature directly (e.g., an SLA alone without mentioning incident management setup), asks to create, clone, or provision users, Case management setup, or general ITSM questions without setup intent."
+description: "Orchestrator for Incident Management setup in Salesforce Service Cloud ITSM: presents the available features, tracks progress, and configures each — SLA & Milestones, Priority Matrix, Incident preferences, Major Incident Management, Incident persona PSG assignment, and Service Management Privilege. Use for: set up or configure incident management, incident management walkthrough, what incident features can I configure; the incident preference toggles (default field validations, auto-close child incidents, auto-triage, assign with Einstein, restrict assigned group, rich text descriptions); Major Incident Management (approval group + MIM preferences); assigning the Incident Fulfiller or Incident Manager persona PSG to a user; Service Management Privilege / privilege escalation setup. DO NOT TRIGGER for: the master on/off switch (service-itsm-incident-mgmt-configure), the Priority Matrix or SLA alone, the Major Incident Manager PSG, creating/editing PSGs, or Problem/Change/Case Management."
 metadata:
-  version: "1.2"
+  version: "2.0"
   domains: ["Service"]
+  minApiVersion: "67.0"
   relatedSkills:
+    - "dx-org-permission-set-assign"
+    - "service-itsm-agentic-setup-cmdb-access-assign"
     - "service-itsm-agentic-setup-incident-sla-configure"
+    - "service-itsm-agentic-setup-itsm-agentforce-permset-assign"
     - "service-itsm-incident-mgmt-configure"
     - "service-itsm-incident-priority-configure"
-allowed-tools: Read AskUserQuestion
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "userPerm"
+      value: "CustomizeApplication"
+    - type: "orgPerm"
+      value: "IncidentMgmt.orgHasITSMOrgPermission"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
 ---
 
 # Incident Management Setup Orchestrator
 
-Guide the user through setting up Incident Management features in Salesforce Service Cloud ITSM by presenting the available capabilities, delegating to specialized child skills, and tracking progress.
+Guide the user through setting up Incident Management features in Salesforce Service Cloud ITSM by
+presenting the available capabilities, tracking progress, and — per feature — either **delegating** to a
+specialized child skill or **executing the feature inline over its system of record (SOR)**.
 
 ## Goal
 
-Act as the coordinator for Incident Management feature configuration. Present the user with a menu of configurable features, invoke the appropriate child skill for each selection, and after each feature completes, return to the menu with updated progress until the user is done.
+Act as the coordinator for Incident Management feature configuration. Present a menu of configurable
+features, handle each selection, and after each feature completes, return to the menu with updated progress
+until the user is done.
+
+## How each feature is handled
+
+| # | Feature | Handled by |
+|---|---------|-----------|
+| 1 | SLA & Milestones | **Delegate** → `service-itsm-agentic-setup-incident-sla-configure` |
+| 2 | Priority Matrix | **Delegate** → `service-itsm-incident-priority-configure` |
+| 3 | Incident Preferences | **Inline over SOR** → `references/incident-preferences.md` |
+| 4 | Major Incident Management | **Inline over SOR** → `references/major-incident-management.md` |
+| 5 | Incident Persona PSG | **Inline over SOR** → `references/incident-persona-psg.md` |
+| 6 | Service Management Privilege | **Inline over SOR** → `references/service-mgmt-privilege.md` |
+
+**Delegated** features invoke their child skill (this skill only coordinates). **Inline** features are run
+by this skill directly through the `headless-360` MCP server — **read the matching reference file before
+executing that feature** and follow it. Every inline operation is fetched at runtime: `discover` by intent,
+`describe` for the current route/schema/labels, then `dispatch_readonly` (reads) / `dispatch` (writes).
+**Hardcode nothing — `describe` wins.**
 
 ## Behavior
 
 ### 0. Reuse what the session already knows
 
-Before running any preflight below, check whether the same fact was already established
-earlier in this conversation. Cache-eligible facts for this orchestrator:
-
-- **Master switch state** — reuse **only when the master switch was confirmed
-  enabled** by an earlier read or flip in this conversation. A cached "off" value
-  MUST NOT let step 2 skip: the delegation exists precisely to flip an off switch
-  on with user confirmation before downstream feature setup runs.
-- **Already-completed features** — features the user (or a child skill) reported "Done"
-  in an earlier turn stay "Done" — do not re-run their child skill unless the user asks
-  to reconfigure.
-- **Target org** — if the target org was already confirmed earlier in the conversation,
-  reuse it; do not re-ask.
-
-**When in doubt, re-check.** Skip only when the earlier fact is unambiguously in context
-AND you have not switched orgs. If the user hints at a different org, or a child skill's
-write elsewhere in the session could have invalidated the cached state (e.g., the master
-switch was toggled off after being confirmed on), re-run the check. A wrong skip on a
-live org write is worse than a duplicated read.
+Before running any preflight below, check whether the same fact was already established earlier in this
+conversation. Cache-eligible: the **master switch state** (reuse **only when confirmed *enabled***; a
+cached "off" MUST NOT let step 2 skip), **already-completed features** (stay "Done"; don't re-run unless
+asked to reconfigure), and the **target org**. **When in doubt, re-check.** Skip only when the earlier fact
+is unambiguously in context AND you have not switched orgs — a wrong skip on a live write is worse than a
+duplicated read.
 
 ### 1. Extract context from conversation
 
-Before presenting options, scan chat history for:
-
-- Which features the user has already set up (skip or mark as done)
-- Any preferences or constraints mentioned (e.g., "we only need the SLA milestones")
-- The target org (if mentioned)
-- Business context that informs which features are relevant
+Scan chat history for which features are already done, any stated preferences/constraints, the target org,
+and business context that informs which features are relevant.
 
 ### 2. Ensure the Incident Management master switch is on (prerequisite)
 
-Every Incident Management feature below depends on the org-level `service-cloud-itsm-incident` master switch being enabled — SLA milestones and downstream features cannot function while the switch is off. Before showing the feature menu, delegate to `service-itsm-incident-mgmt-configure` to read current state; if the switch is already on, it is a no-op — otherwise it confirms with the user before flipping it. **Skip this delegation only when the master switch was already confirmed *enabled* in this session — see Behavior step 0**. A cached "off" or unknown state MUST fall through to the delegation; a wrong skip here would silently let downstream feature setup run against an org where the master is off.
-
-### 3. Present the Incident Management feature menu as a multi-select
+Every feature below depends on the org-level `service-cloud-itsm-incident` master switch being enabled.
+Before showing the menu, delegate to `service-itsm-incident-mgmt-configure` to read current state; if on,
+it is a no-op — otherwise it confirms with the user before flipping it. **Skip only when the master switch
+was already confirmed *enabled* in this session** (see step 0). A cached "off"/unknown state MUST fall
+through to the delegation.
 
-Show the user what's available and what's done. Only features with a working child skill appear in the menu. Emit the **Feature menu** template from `examples/output-templates.md` AND, in the same response, a single `AskUserQuestion` call with `multiSelect: true` whose options mirror the rendered rows — the table is the visual view; the tool call is how the selection is collected. Both MUST appear together, never one without the other. Selecting one feature is valid; selecting several enqueues them for sequential handling in step 4. Do NOT show placeholder features that cannot be executed. Additional Incident Management features (Major Incident Management, Custom Fields, incident permission assignment, user provisioning) will be added to this menu as their child skills become available.
+### 3. Present the feature menu as a multi-select
 
-### 4. Delegate to child skills for each selected feature in order
+Emit the **Feature menu** template from `examples/output-templates.md` AND, in the same response, a single
+`AskUserQuestion` (`multiSelect: true`) whose options mirror the rendered rows — the table is the visual
+view; the tool call collects the selection. Both MUST appear together. Selecting one feature is valid;
+several enqueue for sequential handling in step 4.
 
-Handle the user's selected features sequentially in dependency order (or the order given). For each selected feature, invoke the corresponding child skill:
+### 4. Handle each selected feature in order
 
-| # | Feature | Child Skill |
-|---|---------|-------------|
-| 1 | SLA & Milestones | `service-itsm-agentic-setup-incident-sla-configure` |
-| 2 | Priority Matrix | `service-itsm-incident-priority-configure` |
+Handle selected features sequentially in dependency order (or the order given). For each: if it is a
+**delegated** feature, invoke its child skill; if it is an **inline** feature, **read its reference file**
+and execute it there — always **read live state before writing, confirm before every write, and verify
+every write by read-back**. Honor the per-feature invariants below.
 
 ### 5. After each feature completes
 
-Once a child skill finishes:
-
-1. **Update the status** — mark the completed feature as "Done"
-2. **Suggest the next logical step** — if another feature is available, recommend it based on the dependency order
-3. **Re-present the menu** with updated status — use the **Post-feature progress** template in `examples/output-templates.md`
+Mark it "Done", suggest the next logical step, and re-present the menu with updated status using the
+**Post-feature progress** template in `examples/output-templates.md`.
 
 ### 6. Completion summary
 
-When the user says they're done (or all available features are configured), present a final summary using the **Completion summary** template in `examples/output-templates.md`.
+When the user says they're done (or all features are configured), present the **Completion summary**
+template in `examples/output-templates.md`.
+
+---
+
+## Critical inline-execution invariants (load-bearing — full detail in each reference)
+
+Apply these whenever an inline feature runs. They are irreversible or silently-wrong if missed.
+
+- **Resolve the right node (Preferences).** Target the ITSM Incident Management org-preferences node
+  (controller `IPCManagementSetupController`), **not** the Service-Foundation look-alike
+  (`IncidentMgmtSetupController`, broadcast channels + a master switch).
+- **Two preferences are one-way / enable-only (Preferences).** *Restrict Assigned Group to Regular Groups*
+  and *Enable Rich Text for Incident Descriptions* cannot be turned off once on. Never offer to disable
+  them; require an explicit "I understand this can't be undone" confirmation before enabling; never enable
+  to test. *Restrict Assigned Group…* also **freezes once the org has any Incident record** — an enable can
+  fail outright; do not retry.
+- **License, not assignment (Major Incident Management).** MIM is the approval group + two preferences on
+  top of **base** Incident Management. The Major Incident Manager grant is a **LICENSE**
+  (`PermissionSetLicenseAssign`), never a `PermissionSetAssignment`. **License before group membership;
+  validate group users before designating a group; remove before reassign.** Only two preference names are
+  valid: `AutoCreationOfProblem`, `AutoClosureChildIncidents`.
+- **PSL before PSG (Persona).** Assign the union of a persona PSG's member permission-set **licenses first,
+  then the PSG** (keyed on `PermissionSetGroupId`, never a permission-set Id) — otherwise the persona is
+  silently half-provisioned. Query the persona PSGs by `DeveloperName` with **no** `NamespacePrefix` filter.
+- **Destructive delete + unverifiable assignments (Service Management Privilege).** Deleting a Service
+  Management Privilege is irreversible — confirm explicitly, never delete to test. Bulk employee↔privilege
+  assignments have **no read-back** — report them as applied, not verified. The *Enable Privilege Assignment*
+  master toggle is the UI entry gate (reversible; the controller does not re-check it), so enable it first as
+  workflow ordering, not a hard precondition. No public API substitute exists — a `404` / discover-miss means
+  the surface isn't served on this org yet; surface it and stop.
+- **Everywhere:** read before write; treat "already in that state" / a duplicate as idempotent success;
+  verify by read-back (a write response alone is not proof); each license consumes a seat; on `401`/`403`/
+  `404` surface the raw error and stop; keep record Ids, HTTP codes, route paths, and tooling terms
+  (`dispatch`, `headless-360`, SOR/step ids) out of user-facing output.
 
 ---
 
 ## Feature Dependencies & Recommended Order
 
 ```text
-1. SLA & Milestones      (attaches time-based commitments to incidents)
-2. Priority Matrix       (derives Incident.Priority from Impact × Urgency)
+1. SLA & Milestones            (time-based commitments on incidents)      [delegated]
+2. Priority Matrix             (Impact × Urgency → Incident.Priority)      [delegated]
+3. Incident Preferences        (the six per-feature setup toggles)         [inline]
+4. Major Incident Management   (approval group + two MIM preferences)      [inline]
+5. Incident Persona PSG        (Fulfiller / Manager persona for a user)    [inline]
+6. Service Management Privilege (escalation level + privilege assignments) [inline]
 ```
 
-Additional Incident Management features (Major Incident Management, Custom Fields, incident permission assignment, user provisioning) will be added to this menu as their child skills merge.
-
 ---
 
 ## Rules
 
 - ALWAYS show "(via service-itsm-agentic-setup-incident-management)" in the setup header
-- ALWAYS run the Incident Management master-switch prerequisite (Behavior step 2) before showing the feature menu, unless the user has already confirmed the switch is on earlier in this conversation — every downstream feature depends on it
-- ALWAYS present the feature menu before configuring any selected feature — do not assume which feature the user wants (the master-switch prerequisite in Behavior step 2 is the only permitted action before the menu)
-- ALWAYS present the feature menu as a multi-select — accept a set of one or more features in a single interaction
-- ALWAYS pair the rendered feature-menu table with an `AskUserQuestion` (`multiSelect: true`) call in the same response — the table is the visual view; the tool call is the selection channel. Emitting the table alone breaks the selection channel; emitting the tool call alone hides the visual view
-- NEVER set up a feature without the user selecting it (explicit selection confirms intent and avoids partial configurations if the user cancels mid-flow; for "set up everything" requests, use the sequential-confirmation loop in the rule below rather than batching all features in one pass)
-- NEVER show features that do not have a working child skill
-- If the user says "set up everything" or "all", walk through each available feature sequentially in the recommended order, confirming between each step
+- ALWAYS run the master-switch prerequisite (Behavior step 2) before showing the menu, unless the user
+  already confirmed the switch is on earlier in this conversation
+- ALWAYS present the feature menu before configuring any selected feature (the master-switch prerequisite
+  is the only permitted action before the menu) — do not assume which feature the user wants, **except**
+  when the user named a specific feature, in which case go straight to it (single-select is fine)
+- ALWAYS pair the rendered feature-menu table with an `AskUserQuestion` (`multiSelect: true`) in the same
+  response — the table is the visual view; the tool call is the selection channel
+- For an **inline** feature, ALWAYS read its reference file first and follow the SOR at runtime — never
+  hardcode a route, body, or preference name
+- NEVER set up a feature the user did not select; for "set up everything", walk each feature sequentially
+  in recommended order, confirming between each step
 - Track progress across the conversation — do not re-present completed features as "Not done"
-- Do not show Salesforce record IDs in any output — use human-readable names only
-- If the user asks to create, clone, or provision users, or to assign incident permission sets, tell them those features are not yet available in this orchestrator and will be added as their child skills merge
+- Do not show Salesforce record IDs in any output — human-readable names only
 
 ---
 
 ## Verification checklist
 
-Before emitting any menu or summary in this skill, mentally confirm each of the following. If any box is unchecked, adjust the output before sending.
+Before emitting any menu or summary, confirm each; adjust the output before sending if any is unchecked.
 
 - [ ] The header line ends with `(via service-itsm-agentic-setup-incident-management)`
-- [ ] The Incident Management master switch has been confirmed on (via `service-itsm-incident-mgmt-configure`) before the feature menu is emitted, unless the user already confirmed it earlier in this conversation
-- [ ] Only features with a working child skill are shown; placeholder features are hidden
-- [ ] The feature menu is presented as a multi-select (single-select only if the user has already named a specific feature)
-- [ ] The feature menu emitted BOTH the ASCII table AND an `AskUserQuestion` (`multiSelect: true`) presenting the same options in the same response — never one without the other
-- [ ] Each feature row's `Status` column reflects the actual tracked state from the conversation (`Not done`, `In progress`, or `Done`) — not a hard-coded default
-- [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
-- [ ] A feature is being configured only because the user explicitly selected it (or is being walked through sequentially with confirmation under an "all" / "everything" request)
-- [ ] The next action delegates to a child skill, never configures a feature inline
+- [ ] The master switch was confirmed on (via `service-itsm-incident-mgmt-configure`) before the menu,
+      unless already confirmed earlier in this conversation
+- [ ] The feature menu emitted BOTH the ASCII table AND an `AskUserQuestion` (`multiSelect: true`) in the
+      same response (single-select only if the user already named a specific feature)
+- [ ] Each feature row's `Status` reflects the actual tracked state (`Not done`, `In progress`, `Done`)
+- [ ] A feature is being handled only because the user explicitly selected it (or is being walked through
+      sequentially with confirmation under an "all" / "everything" request)
+- [ ] For an inline feature: its reference file was read; live state was read before any write; each write
+      was confirmed and verified by read-back; one-way / license-ordering invariants were honored
+- [ ] For a delegated feature: the child skill was invoked, not configured inline
 - [ ] No Salesforce record IDs appear in the output — human-readable names only
 
 ---
@@ -130,4 +196,8 @@ Before emitting any menu or summary in this skill, mentally confirm each of the
 
 | File | When to read |
 |------|--------------|
-| `examples/output-templates.md` | Behavior steps 3, 5, and 6 — feature menu (multi-select), post-feature progress, and completion summary text blocks |
+| `examples/output-templates.md` | Behavior steps 3, 5, 6 — feature menu (multi-select), post-feature progress, completion summary |
+| `references/incident-preferences.md` | Before executing the **Incident Preferences** feature — the six preferences, the one-way rules, the SOR delegation map, invariants, and failure taxonomy |
+| `references/major-incident-management.md` | Before executing the **Major Incident Management** feature — the two surfaces (approval group + preferences), licensing preconditions, ordering, invariants |
+| `references/incident-persona-psg.md` | Before executing the **Incident Persona PSG** feature — the two persona PSGs, PSL-before-PSG ordering, resolution rules, invariants |
+| `references/service-mgmt-privilege.md` | Before executing the **Service Management Privilege** feature — the Enable Privilege Assignment toggle, escalation level, privilege CRUD (destructive delete), bulk assignments (no read-back), and the SOR step map |

package/skills/service-itsm-agentic-setup-incident-management/examples/output-templates.md

@@ -1,7 +1,8 @@
 # Output Templates — service-itsm-agentic-setup-incident-management
 
-Emit one of these text blocks at the corresponding step in the workflow. Only features with a
-working child skill appear — hide placeholder rows.
+Emit one of these text blocks at the corresponding step in the workflow. Show every feature the master
+switch enables; render each row's `Status` from the actual tracked state (`Not done`, `In progress`,
+`Done`) — never hard-code it.
 
 ## Feature menu (Behavior step 3)
 
@@ -17,36 +18,47 @@ Here are the features available for Incident Management. Select one or more to c
 │   │                               │ Entitlement so Incidents inherit SLA milestones  │          │
 │ 2 │ Priority Matrix               │ Enable and shape the Impact × Urgency grid that  │ Not done │
 │   │                               │ derives Priority on Incident records             │          │
+│ 3 │ Incident Preferences          │ The six per-feature setup toggles (validations,  │ Not done │
+│   │                               │ auto-close, triage, Einstein assign, rich text)  │          │
+│ 4 │ Major Incident Management     │ Approval group + the two MIM preferences         │ Not done │
+│   │                               │ (auto-create problem, auto-close child)          │          │
+│ 5 │ Incident Persona PSG          │ Assign the Incident Fulfiller / Incident Manager │ Not done │
+│   │                               │ persona to a user (bundle + backing licenses)    │          │
+│ 6 │ Service Management Privilege  │ Escalation level, privilege records + employee   │ Not done │
+│   │                               │ assignments, behind Enable Privilege Assignment  │          │
 └───┴───────────────────────────────┴──────────────────────────────────────────────────┴──────────┘
 
-Reply with the numbers of the features you want to set up (one or more, e.g. `1,2`).
+Reply with the numbers of the features you want to set up (one or more, e.g. `1,3`).
 ```
 
 ## Post-feature progress (Behavior step 5)
 
-Example after the SLA & Milestones child skill completes (Priority Matrix still `Not done`):
+Example after the Incident Preferences feature completes (others still `Not done`):
 
 ```text
-SLA & Milestones — configured successfully
-(via service-itsm-agentic-setup-incident-sla-configure)
+Incident Preferences — configured successfully
+(via service-itsm-agentic-setup-incident-management)
 
 ┌───┬───────────────────────────────┬──────────┐
 │ # │ Feature                       │ Status   │
 ├───┼───────────────────────────────┼──────────┤
-│ 1 │ SLA & Milestones              │ Done     │
+│ 1 │ SLA & Milestones              │ Not done │
 │ 2 │ Priority Matrix               │ Not done │
+│ 3 │ Incident Preferences          │ Done     │
+│ 4 │ Major Incident Management     │ Not done │
+│ 5 │ Incident Persona PSG          │ Not done │
+│ 6 │ Service Management Privilege  │ Not done │
 └───┴───────────────────────────────┴──────────┘
 
-The next logical step is Priority Matrix — say `2` to configure it now, or `done` to finish.
+Say a number to configure the next feature, or `done` to finish.
 ```
 
 ## Completion summary (Behavior step 6)
 
-The completion summary fires either (a) after every feature completes, or (b) when the user says
-they are finished — even if some features are still `Not done`. When rendering:
+The completion summary fires either (a) after every feature completes, or (b) when the user says they are
+finished — even if some features are still `Not done`. When rendering:
 
 - Substitute each feature's row with its actual tracked status: `Done`, `In progress`, or `Not done`.
-  Do NOT hard-code `Done`.
 - Choose the header line based on whether every feature is `Done`:
   - All features `Done` → `Incident Management Setup — Complete`
   - Any feature still `Not done` or `In progress` → `Incident Management Setup — Finished`
@@ -54,18 +66,22 @@ they are finished — even if some features are still `Not done`. When rendering
   - All `Done` → `Your Incident Management features are configured.`
   - Otherwise → `You have finished the features you selected. The remaining features can be resumed later by re-invoking this orchestrator.`
 
-Example — user finished the setup with both features configured:
+Example — user finished with three features configured, three left:
 
 ```text
-Incident Management Setup — Complete
+Incident Management Setup — Finished
 (via service-itsm-agentic-setup-incident-management)
 
 ┌───────────────────────────────┬──────────┐
 │ Feature                       │ Status   │
 ├───────────────────────────────┼──────────┤
 │ SLA & Milestones              │ Done     │
-│ Priority Matrix               │ Done     │
+│ Priority Matrix               │ Not done │
+│ Incident Preferences          │ Done     │
+│ Major Incident Management     │ Done     │
+│ Incident Persona PSG          │ Not done │
+│ Service Management Privilege  │ Not done │
 └───────────────────────────────┴──────────┘
 
-Your Incident Management features are configured.
+You have finished the features you selected. The remaining features can be resumed later by re-invoking this orchestrator.
 ```

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

@@ -0,0 +1,156 @@
+# Feature: Incident Persona PSG Assignment (inline execution)
+
+How the orchestrator executes the **Persona** feature — granting a **specific user** an ITSM Incident
+Management **persona** by assigning the persona's **permission set group (PSG)** (the **Incident Fulfiller**
+or **Incident Manager** bundle) together with the **backing permission-set licenses** its member permission
+sets require. 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 to the systems of record
+
+Every operation is delegated to a system of record (SOR) and its exact shape is fetched at runtime —
+`discover` by intent, `describe` the SOR step for its **current** route, method, and argument schema, then
+`dispatch_readonly` (reads) / `dispatch` (writes). **Hardcode no routes, SOQL, or request bodies; use what
+`describe` returns, and if it disagrees with anything here, `describe` wins.** Discover by intent, not by
+id; a `discover` miss is not proof an operation is unavailable.
+
+| SOR | Owns | Status |
+|-----|------|--------|
+| **`PermSetGroups`** (approved) | Assigning a PSG to a user; listing a user's PSG assignments | Served today |
+| **ITSM incident-persona assignment SOR** | Resolving the incident persona PSGs; resolving the target user; resolving a PSG's member permission sets + their backing licenses; assigning the backing permission-set licenses; the license-seat check; read-back verification | Being onboarded separately. Until served, resolve these via the standard Salesforce Data API **by intent** — the objects and invariants are named below; never via a route written here |
+
+Discover each by intent — e.g. `discover("assign a permission set group to a user")` for the assignment,
+`discover("assign the backing permission-set licenses of an incident persona PSG")` for the license recipe.
+
+> **Load-bearing trap the SOR does not encode.** Assigning the PSG *alone* sticks the assignment, but any
+> permission in a member set whose backing **permission-set license (PSL)** the user lacks **never
+> activates** — the persona is silently half-provisioned, and Salesforce does not auto-assign a PSG's
+> member PSLs. **Assign the union of the member sets' backing PSLs first, then the PSG.** The PSL set
+> differs per PSG and the Ids differ per org, so resolve it at runtime — never hardcode it.
+
+## The two Incident Management persona PSGs
+
+Both are Core-shipped in namespace `force` — query by `DeveloperName` with **no** `NamespacePrefix` filter
+(which would exclude them). Resolve each PSG's Id, its member permission sets, and their backing license Ids
+at **runtime**.
+
+| Persona | PSG (`DeveloperName`) | Grants |
+|---------|-----------------------|--------|
+| Incident Fulfiller | `IncidentFulfillerPSG` | Work incidents as a fulfiller (incident + problem/change/release associators, major-incident proposer) |
+| Incident Manager | `IncidentManagerPSG` | Manage the incident-management process and its records |
+
+The **Major Incident Manager** PSG (`MajorIncidentManagerPSG`) is **out of scope** here (its approver
+licensing is part of the orchestrator's **Major Incident Management** feature).
+
+## Scope
+
+- **In scope**: resolving which incident persona PSG(s) exist on the org; resolving the target user;
+  resolving each chosen PSG's member permission sets and their backing licenses at runtime; checking
+  existing assignments (idempotency); assigning the missing backing PSL(s) and then the PSG; verifying by
+  read-back.
+- **Out of scope**: the **Major Incident Manager** PSG; creating / editing / recalculating a PSG or its
+  membership; enabling ITSM / incident-management features (`service-itsm-incident-mgmt-configure`); the
+  `IncidentFulfiller` permission **set** for the Fulfiller **agent's** access
+  (`service-itsm-agentic-setup-itsm-agentforce-permset-assign`); CMDB access
+  (`service-itsm-agentic-setup-cmdb-access-assign`); generic, non-incident permission-set / PSG assignment
+  (`dx-org-permission-set-assign`).
+
+## Preconditions
+
+- **ITSM Incident Management must be provisioned** — the incident persona PSGs must exist on the org. If
+  neither is found, **stop and hand off** to `service-itsm-incident-mgmt-configure`; assign nothing.
+- **The acting user must be able to assign permission sets** (the SOR gates writes on it). A write that
+  fails with an access error that is not a duplicate → surface it plainly and stop; an admin must do it.
+- **Each backing license consumes a seat.** A seat-exhausted license blocks that persona; report it.
+
+## Operations (shapes come from `describe`)
+
+1. **Resolve which incident persona PSGs exist (read).** Look up the two PSGs by `DeveloperName`
+   (`IncidentFulfillerPSG`, `IncidentManagerPSG`) with **no `NamespacePrefix` filter**. None found → hand
+   off to `service-itsm-incident-mgmt-configure` and stop. Capture each PSG's Id and status.
+2. **Resolve the target user (read).** To exactly one active user. For "me" / "the current user", read the
+   API root's identity (the running user's `005…` Id) — **not** the `USER_ID()` SOQL function (Apex-only)
+   and **not** the Chatter current-user endpoint (fails when Chatter is off). Zero / multiple → disambiguate.
+3. **Resolve the chosen PSG's member licenses (read).** From the PSG's member permission sets, collect the
+   **distinct, non-null backing permission-set-license Ids** — the link is each member permission set's
+   `LicenseId`. Do **not** traverse the license's `Name`/`DeveloperName` from the member (that relationship
+   rejects); resolve the license label separately by Id. No members → the bundle is empty; surface and stop.
+4. **Check existing assignments (read — idempotency).** Whether the PSG is already assigned, and which
+   backing licenses the user already holds. Write only what is missing.
+5. **Assign the missing backing licenses, then the PSG (write — confirm first).** Assign each **missing
+   backing license first**, then the PSG (keyed on `PermissionSetGroupId`). A duplicate = already-assigned
+   (idempotent success). A seat/limit error on a license = exhausted; stop and report — do not retry.
+6. **Verify (read).** Re-read the PSG assignment and every backing license for the user, and re-read the
+   PSG's status. Provisioned only when all read back. If `Status` is still `Updating`, tell the user
+   effective permissions are settling and will be active shortly.
+
+If the user picks **both** personas, run steps 3–6 once **per PSG** (the bundles have different member
+licenses) and report each.
+
+## Invariants — the contract (these do NOT come from `describe`)
+
+- **Assign the backing licenses before the PSG — correctness ordering, not a platform gate.** The PSG
+  sticks on its own, but any member-set permission whose backing license the user lacks **never activates**.
+  Salesforce neither rejects the PSG assignment for a missing license nor auto-assigns the licenses.
+- **A PSG assignment keys on the permission-set-*group* Id, never a permission-set Id.**
+- **Query the persona PSGs by `DeveloperName` with no `NamespacePrefix` filter** (namespace `force`).
+- **Idempotent** — read before every write; a duplicate is already-assigned success, not a failure.
+- **The PSG recalculates asynchronously** after an assignment; effective permissions can be stale until its
+  status settles.
+- **Verify by read-back** — the write response alone is not proof (half-provisioning / recalculation).
+- **Resolve the backing-license set at runtime** — it differs per PSG and Ids differ per org; never hardcode.
+
+## Clarifying questions
+
+- **Which user?** A username / name / email resolving to exactly one active user; for "me", the running user.
+- **Which persona(s)?** For a generic request, do **not** auto-select — present an `AskUserQuestion` menu of
+  the incident PSGs that **exist on the org** (Fulfiller = work incidents; Manager = manage the process),
+  multi-select (one or both). Never offer the Major Incident Manager PSG.
+- **Which org?** Confirm it and state plainly the org will be **modified** (a PSG + licenses are writes;
+  each license consumes a seat). For production, get explicit confirmation.
+
+## Output expectations
+
+```text
+Incident Management Persona Assignment
+User:    <name> (<username>)
+Persona: <Incident Fulfiller | Incident Manager>
+
+  Persona bundle .................... Assigned | Already had it
+  Backing licenses (N) .............. Assigned N | M already held
+  Effective permissions ............. Active | Recalculating (settles shortly)
+```
+
+Repeat the `Persona:` block per PSG if both were chosen. Report only what read-back confirmed. If the
+personas are not on the org, say so and name `service-itsm-incident-mgmt-configure`.
+
+## Common failures (surface in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| No incident PSG on the org | ITSM Incident Management not provisioned | The incident personas aren't set up yet — that's a separate step (`service-itsm-incident-mgmt-configure`) |
+| Duplicate on assign | User already has that grant | Not an error — report as already assigned |
+| Seat / limit error on a license | An incident license has no free seats | A seat must free up (or more licenses added); the persona is incomplete without it |
+| PSG assigned but some actions missing | A backing license wasn't assigned, or the PSG is still recalculating | Confirm every backing license is assigned; if it's settling, retry in a moment |
+| Access error on the PSG write (not a duplicate) | Acting user can't assign permission sets | An admin must grant that or perform the assignment |
+| `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
+
+## Reading `dispatch` results
+
+Responses come back wrapped as `{ status_code, body }`; read what you need from `body`. A write success is a
+created record. A `400` carrying a duplicate code = already-assigned (treat as success). A seat/limit error
+on a license = no free seats (report used-vs-total; do not retry). An access error that is **not** a
+duplicate on the PSG write = the acting user can't assign permission sets (an admin must). A `404` = the
+operation isn't available on this org.
+
+## Dead ends — do NOT do these
+
+- Assign the PSG with a permission-set Id — a PSG assignment keys on the group Id.
+- Assign the PSG without its members' backing licenses — it silently half-provisions the persona.
+- Hardcode the backing-license list, or add a `NamespacePrefix` filter to the PSG lookup.
+- Create, edit, or recalculate the PSG or its membership — this feature only **assigns** the standard
+  incident PSGs.
+- Retry a write that failed with a seat/limit error — the shortage is real; surface it.
+- Write a route, SOQL string, or request body here — delegate to the SOR and let `describe` carry the shape.