@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: service-itsm-agentic-setup-itsm-agentforce-permset-assign
+description: "Resolve missing ITSM Intelligence invocable actions so a Fulfiller NGA agent can activate. Reads which of the four Core Fulfiller persona permsets (IncidentFulfiller, ProblemFulfillerPermSet, ChangeRequestFulfillerPermSet, ReleaseManagerPermSet) are provisioned, then assigns the running user the selected persona (plus backing PSL when license-gated) so svc_itsm_intelligence__* actions surface; hands off to service-itsm-agentic-setup-agentforce-studio-validate if none are provisioned. Use when the Fulfiller agent-configure skill reports missing actions on activate, when 'Invocable action svc_itsm_intelligence__X does not exist' surfaces, or when a user asks to grant themselves Fulfiller prompt-template access. DO NOT TRIGGER for Employee-agent access, Agentforce for IT Service toggles, agent creation, CMDB access, or generic permset assignment."
+metadata:
+  version: "1.0"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "dx-org-permission-set-assign"
+    - "service-itsm-agentic-setup-agentforce-studio-validate"
+    - "service-itsm-agentic-setup-cmdb-access-assign"
+    - "service-itsm-agentic-setup-fulfiller-agent-configure"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
+allowed-tools: |
+  Bash
+  Read
+  AskUserQuestion
+---
+
+# Assign an ITSM Fulfiller Persona Permission Set (Prompt-Template Access)
+
+Grants the **running user** one of the Core-shipped **Fulfiller persona permission sets** that expose the `svc_itsm_intelligence__*` prompt-template **invocable actions** on the target org — the actions the Fulfiller NGA agent scripts reference via `source:` / `target: generatePromptResponse://...`. When those invocables are not surfaced by `/services/data/v67.0/actions/custom/generatePromptResponse` for the running user, the Fulfiller agent-configure skill's Phase 6 `activate` call returns **HTTP 200** with a silent `{success:false, messages:[{... "does not exist"}]}` body and the agent never becomes usable. This skill fixes that gap by assigning the correct Fulfiller persona permset (and its backing license when one exists) — **or**, when no Fulfiller persona permset is provisioned on the org at all, hands off to the Agentforce Studio configure/validate skill so the ITSM AddOn(s) can be enabled first.
+
+The four Fulfiller persona permsets, their AddOns, PSLs, and the userPerms they grant are documented in `references/permset-topology.md`. All are Core-shipped in namespace `force` — there is no managed-package namespaced permset for this feature.
+
+**Employee agent is out of scope.** The Employee NGA agent's access model is separate (org-preferences + a different persona layer) and does not map onto these four persona permsets.
+
+Every call runs through the **Salesforce CLI (`sf`)**:
+- `sf api request rest` — authenticated Connect API GET (identity, verify read).
+- `sf data query` — SOQL on `PermissionSet` (persona presence), `PermissionSetAssignment` / `PermissionSetLicenseAssign` (idempotency).
+- `sf org assign permset` — assigning the permission set for the running user.
+- No token is ever extracted; no MCP is used.
+
+## Scope
+
+- **In scope**: detecting which of the four Fulfiller persona permsets (`IncidentFulfiller`, `ProblemFulfillerPermSet`, `ChangeRequestFulfillerPermSet`, `ReleaseManagerPermSet`) are provisioned on the org, letting the user pick which persona to assign, checking existing assignments, assigning the permission-set license (when the persona is license-gated) and permission set to the running user (or a named user), verifying the target `svc_itsm_intelligence__*` invocable actions surface via a follow-up `/actions/custom/generatePromptResponse` read.
+- **Out of scope**: Employee-agent access (different access model, different skill), installing/enabling the ITSM AddOn(s) or content bundle (hand off to `service-itsm-agentic-setup-agentforce-studio-validate`), enabling org-level Agentforce feature toggles, creating a permission set, creating or activating the Fulfiller agent (that's `service-itsm-agentic-setup-fulfiller-agent-configure`), CMDB access (`service-itsm-agentic-setup-cmdb-access-assign`), generic non-ITSM permission-set assignment (`dx-org-permission-set-assign`).
+
+## Mechanism
+
+Two branches, decided by a read-only detection step first:
+
+- **Branch A — one or more Fulfiller persona permsets exist on the org.** Ask the user which persona to assign (do not auto-select — a Fulfiller commonly needs only one). Idempotent assign: PSL first when the persona is license-gated, then permission set, verified by read-back and by a follow-up `/actions/custom/generatePromptResponse` read.
+- **Branch B — none of the four Fulfiller persona permsets exist on the org.** The ITSM AddOn(s) are not provisioned; permset-assign is a no-op. STOP and hand off to `service-itsm-agentic-setup-agentforce-studio-validate` so the AddOn(s) can be enabled first.
+
+The two-branch shape is deliberate — the failure signature ("`svc_itsm_intelligence__X` does not exist" on activate) looks identical whether a persona is present-and-unassigned or the AddOn is absent entirely, and there is no way to tell from the activate response alone. The pre-check on the four persona `PermissionSet` names is what disambiguates them.
+
+## Four helper scripts (all invoked via `Bash`) hold every deterministic decision (A9). Full I/O contracts in `references/helper-contracts.md`; workflow-level usage summarized below:
+
+- `scripts/classify-permset-availability.mjs` — Branch A vs B and the per-persona `needsPsl` flag. Returns the full `candidates[]` (personas actually on the org) for the caller to prompt on.
+- `scripts/resolve-target-user.mjs` — extracts `005…` running-user Id from the API-root `identity` URL. Fails closed on any malformed shape.
+- `scripts/classify-assignment-state.mjs` — idempotency; pass the sentinel `NO-PSL` in place of the PSLA path when the selected persona's `needsPsl:false`.
+- `scripts/classify-action-surface.mjs` — Phase 4 verify verdict from the `/actions/custom/generatePromptResponse` capture (with optional expected-actions CSV).
+
+---
+
+## Preconditions
+
+1. **`sf` CLI installed and authenticated to the target org** (`sf org display -o <alias>` shows Connected). All calls use `--target-org <alias>`; never extract or pass the access token by hand.
+2. **API v67.0+**.
+3. **`node` ≥ 18** on PATH.
+
+If a precondition fails, `sf` surfaces an auth or `401`/`403`/`404`; report the raw response verbatim and stop.
+
+---
+
+## Clarifying questions
+
+Ask only what cannot be inferred from conversation:
+
+- **Target org** — the `sf` alias. Default to `sf config get target-org` if unset.
+- **Target user** — default to the **running user** (resolved via `scripts/resolve-target-user.mjs`). If the user asks to assign on behalf of a named user, resolve them by `Username` first.
+- **Which Fulfiller persona?** Incident / Problem / Change / Release. Only ask about personas that are actually provisioned on the org (from `candidates[]`). Do not auto-select — a Fulfiller commonly needs only one persona (e.g. Incident) even when others are provisioned.
+- **Confirm the write** — assigning a permission-set license consumes a seat and takes effect for a live user session. Present the target user + org + persona permset name, and require an explicit "yes" via `AskUserQuestion` before writing.
+
+---
+
+## Workflow
+
+All calls go through `sf`; substitute `<alias>` with the target org.
+
+### Phase 1 — Read: which Fulfiller persona permsets are provisioned on this org?
+
+1. Query `PermissionSet` for the four known Fulfiller persona DeveloperNames:
+
+   ```bash
+   sf data query \
+     -q "SELECT Id, Name, Label, LicenseId FROM PermissionSet WHERE Name IN ('IncidentFulfiller','ProblemFulfillerPermSet','ChangeRequestFulfillerPermSet','ReleaseManagerPermSet')" \
+     --target-org <alias> --json > /tmp/itsm-personas.json 2>/tmp/itsm-personas.err || true
+   ```
+
+   (The `PermissionSet` namespace on all four is `force` — do NOT filter by `NamespacePrefix`.)
+
+2. Classify:
+
+   ```bash
+   node "<skill_dir>/scripts/classify-permset-availability.mjs" /tmp/itsm-personas.json
+   ```
+
+   The classifier prints `{ personasFound, personasMissing, candidates, verdict, reasons }`, where each `candidates[]` row is `{Id, Name, Label, LicenseId, needsPsl}`:
+   - `verdict:"ASSIGN"` (≥1 persona present) ⇒ continue to Phase 2. Present the `personasFound` list to the user via `AskUserQuestion` and get the selected persona; record its `Id`, `LicenseId`, and `needsPsl` — they drive whether Phase 2b/2d touch the PSL at all.
+   - `verdict:"HAND-OFF"` (none of the four personas present) ⇒ Phase 2 is impossible on this org; go to Phase 3 (Branch B hand-off).
+   - `verdict:"CANNOT-CONFIRM"` (query failed) ⇒ surface the raw CLI error verbatim; stop.
+
+### Phase 2 — Assign path (Branch A)
+
+2a. **Resolve the target user.** Read the identity URL, then extract the user Id via the resolver (do NOT parse the URL by hand; do NOT use `USER_ID()` — Apex-only, rejected by REST; do NOT rely on `/chatter/users/me` — `403` when Chatter is off):
+
+   ```bash
+   sf api request rest "/services/data/v67.0/" --method GET --target-org <alias> > /tmp/api-root.json 2>/tmp/api-root.err || true
+   node "<skill_dir>/scripts/resolve-target-user.mjs" /tmp/api-root.json
+   ```
+
+   The resolver prints `{ userId, identity, verdict, reasons }`. On `verdict:"RESOLVED"` use `userId` as the running user; on `verdict:"CANNOT-CONFIRM"` surface the reasons verbatim and stop — do NOT guess.
+
+   If the user asks to assign on behalf of a **named** user instead, resolve by `Username`:
+
+   ```bash
+   sf data query \
+     -q "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" \
+     --target-org <alias> --json > /tmp/user-lookup.json 2>/tmp/user-lookup.err || true
+   ```
+
+2b. **Idempotency read.** Query the `PermissionSetAssignment` for the target user + selected persona's `Id` (SOQL shape in `references/cli-invocation.md`), and then branch on the selected persona's `needsPsl`:
+
+   - **`needsPsl:true`** — query the `PermissionSetLicenseAssign` for the target user + the persona's `LicenseId`, then classify:
+
+     ```bash
+     node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa-existing.json /tmp/psla-existing.json
+     ```
+
+   - **`needsPsl:false`** — skip the PSLA query entirely; pass the sentinel:
+
+     ```bash
+     node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa-existing.json NO-PSL
+     ```
+
+   The classifier prints `{ permsetAssigned, licenseAssigned, needsWrite, verdict, reasons }`. If `needsWrite:false` ⇒ Phase 4 (verify only). Else continue to Phase 2c.
+
+2c. **Confirm-to-write checkpoint (REQUIRED).** Present the target user + org + persona permset name and require an explicit "yes" via `AskUserQuestion`. On "no", stop and report the current state without any writes.
+
+2d. **Assign** — order depends on the selected persona's `needsPsl`:
+
+   - **`needsPsl:true`** — POST the PSL to `/sobjects/PermissionSetLicenseAssign` FIRST, then run `sf org assign permset --name <permsetName> --on-behalf-of <userId>`. Assigning the permission set without the PSL sticks the assignment but the license backing it never activates. Exact call shapes: `references/cli-invocation.md`.
+   - **`needsPsl:false`** — SKIP the PSL POST entirely; run `sf org assign permset` only. (This is normal for `ReleaseManagerPermSet` — its Fulfiller gating is on the org-preference layer, not on a PSL. Assigning the permset is still the correct write.)
+
+   Response handling:
+   - `201` on POST / `success:true` on `sf org assign permset` ⇒ assigned.
+   - `400 DUPLICATE_VALUE` on the PSL POST ⇒ user already had it; treat as success, not error.
+   - `400 INSUFFICIENT_ACCESS` / seat-exhaustion on the PSL POST ⇒ STOP for this write; tell the user the PSL has no seats available.
+
+### Phase 3 — Hand-off path (Branch B: no Fulfiller persona provisioned)
+
+3. When Phase 1 returns `verdict:"HAND-OFF"`, none of the four Fulfiller persona permsets exist on this org — the ITSM AddOn(s) are not provisioned. Permset-assign is a no-op in this state. Present the discovery via `AskUserQuestion`:
+
+   _"None of the Fulfiller persona permission sets (Incident, Problem, Change, Release) is provisioned on this org — no permset can grant access to actions that don't exist yet. Run `service-itsm-agentic-setup-agentforce-studio-validate` to diagnose which AddOn needs enabling?"_ (options: **Yes, run the readiness check** / **No, stop here**).
+
+   - On **Yes**: delegate to `service-itsm-agentic-setup-agentforce-studio-validate` and let it recommend the configure/bundle-deploy skill.
+   - On **No**: stop and report the current state (no persona provisioned, cannot assign) — no writes.
+
+### Phase 4 — Verify
+
+4. Regardless of write vs skip, re-read `/actions/custom/generatePromptResponse` and classify via the helper (never by prose grep — A9). CSV shape and both invocation forms live in `references/helper-contracts.md` / `references/cli-invocation.md`:
+
+   ```bash
+   sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" \
+     --method GET --target-org <alias> > /tmp/generate-prompt-response.json 2>/tmp/generate-prompt-response.err || true
+   node "<skill_dir>/scripts/classify-action-surface.mjs" /tmp/generate-prompt-response.json [expectedActions-csv]
+   ```
+
+   The helper prints `{ present, missing, totalItsmActionsSeen, verdict, reasons }`. On `SURFACED` proceed to Phase 5; on `PARTIAL` / `MISSING` after a successful assign, tell the user the write succeeded but the actions are not surfaced — session refresh or wrong persona. Do not falsely report success. On `CANNOT-CONFIRM` surface the reasons verbatim.
+
+### Phase 5 — Aggregate verdict
+
+5. Report one of:
+   - **ASSIGNED** — Branch A wrote, verify saw the target actions surface.
+   - **ALREADY-ASSIGNED** — Branch A found `needsWrite:false`; verify saw the target actions surface. (Assignment is already in place; no writes needed.)
+   - **HAND-OFF** — Branch B; no Fulfiller persona is provisioned. Named the follow-up skill.
+   - **VERIFY-INCONCLUSIVE** — write completed but the verify read didn't surface the expected action set. Surface the observed state verbatim; do not report success.
+   - **FAILED** — any Phase 2d write returned an error other than `DUPLICATE_VALUE`. Report the raw error.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Detect Fulfiller persona presence via the four fixed `PermissionSet.Name` values BEFORE any permset write | The failure signature ("action does not exist" on activate) is identical for AddOn-absent and permset-not-assigned; only the pre-check disambiguates them. The four personas are Core-shipped in namespace `force` — a `NamespacePrefix` filter never returns them |
+| Ask the user which persona to assign — never auto-select | A Fulfiller commonly needs only one persona (e.g. Incident). Auto-assigning the first row returned would over-grant |
+| All decisions are made by helper scripts, never by prose | Assignment/idempotency logic is deterministic; prose interpretation is not (A9) |
+| Assign the PSL before the permission set — ONLY when the selected persona's `needsPsl:true` | The permission set is license-backed; the license seat must be held before the assignment sticks. When the selected persona has no `LicenseId`, `needsPsl:false` and the PSL POST is skipped entirely |
+| Read `needsPsl` from the SELECTED persona's `LicenseId`, per-row — never from a namespace-wide PSL query | Different personas can have different license shapes on the same org; falling back to a namespace-wide PSL would POST a wrong `PermissionSetLicenseAssign` |
+| Resolve the running-user Id via `scripts/resolve-target-user.mjs` — never by prose parsing the `identity` URL | The identity URL's segment shape (`005…`, 15 or 18 chars) is a hard rule; the classifier validates and fails closed |
+| Classify the Phase 4 action surface via `scripts/classify-action-surface.mjs` — never by prose grep of the response | Verify is the gate for reporting SUCCESS vs VERIFY-INCONCLUSIVE; the decision must be deterministic |
+| Treat `400 DUPLICATE_VALUE` on PSL POST as success | It means the user already has that assignment — idempotent, not an error |
+| Never create or edit a permission set | This skill only assigns the standard Fulfiller persona permission set(s); authoring perm sets is out of scope |
+| Never install the AddOn / never toggle org-level Agentforce features | That is the `service-itsm-agentic-setup-agentforce-studio-validate` / `-configure` scope; this skill hands off, it does not enable |
+| Verify after write via `/actions/custom/generatePromptResponse` — never trust POST return code alone | The assignment can succeed while the target action surface still doesn't include what the Fulfiller template needs (wrong persona, cache) |
+| Confirm-to-write checkpoint before Phase 2d | A permset assign consumes a license seat and takes effect for a live user session |
+| Never extract the access token | Use `sf api request rest` / `sf data query` / `sf org assign permset` — they use the CLI's stored session |
+| Report exact error text from the CLI response | Enables support to diagnose failures |
+
+---
+
+## Verification Checklist
+
+- [ ] Persona availability classified by `scripts/classify-permset-availability.mjs` against the four fixed persona Names — never by prose scanning the query output.
+- [ ] User was asked to pick a persona from `personasFound[]` — no auto-selection.
+- [ ] Target user Id resolved by `scripts/resolve-target-user.mjs` — never by prose splitting the identity URL.
+- [ ] The SELECTED persona's `needsPsl` drove Phase 2b/2d: PSL SOQL + POST were performed when `true` and skipped when `false`.
+- [ ] `permsetLicenseId` used for the PSL POST came from the SELECTED persona's own `LicenseId` — never a fallback from a namespace-wide query.
+- [ ] On Branch A: existing assignments read via `sf data query` before any write, classified by `scripts/classify-assignment-state.mjs` (with `NO-PSL` sentinel when `needsPsl:false`).
+- [ ] On Branch A: user confirmed the write at the Phase 2c checkpoint.
+- [ ] On Branch A + `needsPsl:true`: PSL was POSTed before the permission set was assigned.
+- [ ] `DUPLICATE_VALUE` on the PSL POST was treated as success, not failure.
+- [ ] On Branch B: no write was attempted; the hand-off to `service-itsm-agentic-setup-agentforce-studio-validate` was offered.
+- [ ] Phase 4 verify classified via `scripts/classify-action-surface.mjs` — no false ASSIGNED without the helper returning `verdict:"SURFACED"`.
+- [ ] Aggregate verdict reported (ASSIGNED / ALREADY-ASSIGNED / HAND-OFF / VERIFY-INCONCLUSIVE / FAILED).
+
+---
+
+## Output Format
+
+```text
+ITSM Fulfiller Persona Permset Assignment (via service-itsm-agentic-setup-itsm-agentforce-permset-assign)
+
+Org:            <org-alias> (API v67.0)
+Target user:    <username> (<userId>)
+Persona:        <Incident | Problem | Change | Release>
+PermSet:        <DeveloperName>
+
+  Personas provisioned on org ...... <comma-separated list | none>
+  Existing PSL assignment .......... <yes | no | n/a>
+  Existing permset assignment ...... <yes | no>
+  Write PSL ........................ <succeeded | already-had | skipped | FAILED>
+  Write permset .................... <succeeded | already-had | skipped | FAILED>
+  Verify actions surface ........... <yes | partial | no>
+
+Verdict: ASSIGNED | ALREADY-ASSIGNED | HAND-OFF | VERIFY-INCONCLUSIVE | FAILED
+Reason:  <plain-language explanation, or empty on success>
+
+Next steps:
+  - <If ASSIGNED / ALREADY-ASSIGNED: "Re-run service-itsm-agentic-setup-fulfiller-agent-configure — the invocable actions should now surface, and the activate call will succeed.">
+  - <If HAND-OFF: "No Fulfiller persona is provisioned on this org. Run service-itsm-agentic-setup-agentforce-studio-validate to identify which AddOn needs enabling.">
+  - <If VERIFY-INCONCLUSIVE: list the observed state verbatim; a session refresh or a different persona may be required>
+  - <If FAILED: list the observed error verbatim + remediation>
+```
+
+Keep internal jargon (record Ids, HTTP status codes, `FUNCTIONALITY_NOT_ENABLED`, `DUPLICATE_VALUE`, object/developer names, `sf api request rest`) out of user-facing output.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/permset-topology.md` | Any change to the persona list — the four Core-shipped Fulfiller permsets, their AddOns/PSLs/userPerms, and the fixed-lookup discovery query |
+| `references/cli-invocation.md` | Every phase — exact `sf api request rest` / `sf data query` / `sf org assign permset` call shapes, the never-extract-token rule, response envelopes |
+| `references/helper-contracts.md` | The input/output shapes of all four helper scripts (`classify-permset-availability.mjs`, `resolve-target-user.mjs`, `classify-assignment-state.mjs`, `classify-action-surface.mjs`) and how to interpret each verdict |

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/references/cli-invocation.md

@@ -0,0 +1,106 @@
+# CLI Invocation — service-itsm-agentic-setup-itsm-agentforce-permset-assign
+
+Every read and write in this skill uses the **Salesforce CLI (`sf`)** against the CLI's stored session for `--target-org <alias>`. **Never extract the access token** from `sf org display` — hand-building a raw HTTP request bypasses the CLI session and leaks a bearer token into shell context.
+
+## `--json` rule
+
+- `sf data query` **takes** `--json`. Results come back in a `{status, result: {records: [...]}}` envelope — that's what the classifier scripts expect.
+- `sf api request rest` does **not** — its raw stdout body is already JSON. Passing `--json` here errors on some Connect endpoints.
+- `sf org assign permset` **takes** `--json`. Its `result` field carries `{ successes: [...], failures: [...] }`.
+
+## Discovery read (Phase 1)
+
+Fixed-lookup query over the four Core-shipped Fulfiller persona `PermissionSet.Name` values (see `permset-topology.md`). The namespace on all four is `force` — do NOT filter by `NamespacePrefix`.
+
+```bash
+sf data query \
+  -q "SELECT Id, Name, Label, LicenseId \
+      FROM PermissionSet \
+      WHERE Name IN ( \
+        'IncidentFulfiller', \
+        'ProblemFulfillerPermSet', \
+        'ChangeRequestFulfillerPermSet', \
+        'ReleaseManagerPermSet' \
+      )" \
+  --target-org <alias> --json
+```
+
+Interpret the result:
+
+- **≥1 row** ⇒ Branch A (assign). Ask the user which persona to assign — do NOT auto-select.
+- **Zero rows** ⇒ Branch B (hand-off). The ITSM AddOn(s) are not provisioned; route to `service-itsm-agentic-setup-agentforce-studio-validate`.
+
+There is no separate `InstalledSubscriberPackage` or namespace-wide `PermissionSetLicense` query in Phase 1 — the persona lookup above is sufficient because Core AddOn provisioning materializes the persona `PermissionSet` rows directly.
+
+## Identity read (Phase 2a)
+
+```bash
+sf api request rest "/services/data/v67.0/" --method GET --target-org <alias>
+```
+
+Response `identity` is a URL ending in `/<orgId>/<userId>`. Take the last path segment starting with `005` as the running user Id via `scripts/resolve-target-user.mjs`. Do **not** call `USER_ID()` (Apex-only), `/chatter/users/me`, or `/connect/user-profiles/me` — those either fail against REST or 403 when Chatter/Communities is off.
+
+For a named user, resolve by `Username`:
+
+```bash
+sf data query -q "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" \
+  --target-org <alias> --json
+```
+
+## Idempotency reads (Phase 2b)
+
+Substitute `<permsetId>` with the SELECTED persona's `Id` and `<pslId>` with the SELECTED persona's `LicenseId` (both from Phase 1's `candidates[]`).
+
+```bash
+sf data query -q "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<permsetId>'" \
+  --target-org <alias> --json > /tmp/psa-existing.json
+
+# Only when needsPsl:true on the selected persona:
+sf data query -q "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" \
+  --target-org <alias> --json > /tmp/psla-existing.json
+```
+
+When the selected persona's `needsPsl:false` (e.g. `ReleaseManagerPermSet`), SKIP the PSLA query — pass the sentinel `NO-PSL` to `classify-assignment-state.mjs`.
+
+## Writes (Phase 2d)
+
+Assign the PSL first, then the permission set — the license backs the permset, and the assignment is not fully effective until the seat is held. When `needsPsl:false`, skip the PSL POST entirely and only run `sf org assign permset`.
+
+```bash
+# PSL first — POST to the sObject endpoint (no bulk API dependency). needsPsl:true only.
+sf api request rest "/services/data/v67.0/sobjects/PermissionSetLicenseAssign" \
+  --method POST \
+  --body '{"AssigneeId":"<userId>","PermissionSetLicenseId":"<pslId>"}' \
+  --target-org <alias>
+```
+
+Response envelope: `{"id":"0Pk...","success":true,"errors":[]}` on assignment; `[{"errorCode":"DUPLICATE_VALUE",...}]` when the user already holds it (treat as success).
+
+```bash
+# Permset — sf CLI subcommand, supports --on-behalf-of for a named user.
+# <permsetName> is the selected persona's DeveloperName (from candidates[].Name).
+sf org assign permset --name "<permsetName>" \
+  --on-behalf-of <userId> \
+  --target-org <alias> --json
+```
+
+Response envelope: `result.successes[]` and `result.failures[]`. A `failure.message` matching `Duplicate id` / `already has` is idempotent success.
+
+## Verify read (Phase 4)
+
+```bash
+sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" \
+  --method GET --target-org <alias>
+```
+
+Response can be either `{actions: [ {name, ...}, ... ]}` (legacy) or `{actions: {<name>: {...}, ...}}` (newer). The Fulfiller agent-configure skill's Phase 1b provides the specific `svc_itsm_intelligence__*` names to look for; passed as the second arg to `classify-action-surface.mjs`.
+
+## Common error responses (surface verbatim)
+
+| Status / errorCode | Meaning | Handling |
+|---|---|---|
+| `400 DUPLICATE_VALUE` on PSL POST | User already holds this PSL | Idempotent success; not a failure |
+| `400 INSUFFICIENT_ACCESS` on PSL POST | PSL seat exhausted | STOP the write; tell the user how many seats are in use vs licensed |
+| `401 Unauthorized` on any call | CLI session expired for the target alias | `sf org login web --alias <alias>` and retry |
+| `403 FUNCTIONALITY_NOT_ENABLED` on the verify GET | The `generatePromptResponse` custom-action endpoint is gated on this user | Same signal as Branch A but for the discovery route — surface it and check whether the assigned persona permset actually gates the target actions |
+| `404 Not Found` on `sf org assign permset` | Permset name does not exist on this org | Re-run Phase 1 discovery; the org state may have changed |

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/references/helper-contracts.md

@@ -0,0 +1,142 @@
+# Helper Script Contracts — service-itsm-agentic-setup-itsm-agentforce-permset-assign
+
+All four scripts are deterministic, side-effect-free JSON classifiers (A9). They read one or more `sf data query --json` / `sf api request rest` captures and emit a single JSON object to stdout. Exit is `0` on any parseable body; the verdict is carried in the payload. Exit `2` is a usage error (missing args); the scripts do **not** exit non-zero on a workflow-blocking condition — that is the caller's job based on the emitted `verdict`.
+
+## `scripts/classify-permset-availability.mjs`
+
+Decides Branch A vs Branch B (assign vs hand-off) AND emits per-persona `needsPsl` flags. Fulfiller-only — the four persona names are hard-coded.
+
+### Input
+
+One file path (positional):
+
+1. `permsets.json` — `sf data query --json` capture of `PermissionSet` filtered to the four Fulfiller persona `Name` values (see `permset-topology.md`). Unrelated rows are filtered out by the classifier.
+
+Must be the raw stdout capture (the `{status, result: {records: [...]}}` envelope). An unparseable / non-envelope body produces `verdict:"CANNOT-CONFIRM"` with the raw error in `reasons[]`.
+
+### Output
+
+```json
+{
+  "personasFound": ["IncidentFulfiller"],
+  "personasMissing": ["ProblemFulfillerPermSet","ChangeRequestFulfillerPermSet","ReleaseManagerPermSet"],
+  "candidates": [
+    { "Id": "0PS...", "Name": "IncidentFulfiller", "Label": "Incident Fulfiller", "LicenseId": "0PL...", "needsPsl": true }
+  ],
+  "verdict": "ASSIGN",
+  "reasons": ["..."]
+}
+```
+
+- `candidates[]` lists ONLY rows whose `Name` matches one of the four known Fulfiller personas. Unrelated rows in the query result are dropped.
+- `needsPsl` is derived per-row from `LicenseId !== null` — read it from the SELECTED persona in the workflow.
+- `personasFound` preserves the canonical order (Incident, Problem, Change, Release) so the AskUserQuestion menu is stable across runs.
+
+Verdict values:
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `ASSIGN` | ≥1 Fulfiller persona present on the org | Continue to Phase 2. AskUserQuestion which persona to assign; read `needsPsl` off that persona to gate PSL SOQL + POST |
+| `HAND-OFF` | None of the four personas present | Skip Phase 2 entirely; go to Phase 3 (delegate to `service-itsm-agentic-setup-agentforce-studio-validate`) |
+| `CANNOT-CONFIRM` | The query envelope was unparseable | Surface `reasons[]` verbatim and stop |
+
+**Never auto-select** from `candidates[]` — a Fulfiller commonly needs only one persona (e.g. Incident) even when several are provisioned. Present the list and let the user pick.
+
+## `scripts/resolve-target-user.mjs`
+
+Extracts the running user's Id from the API-root `identity` URL. Replaces any prose "take the last path segment starting with `005` ..." step (A9).
+
+### Input
+
+One file path (positional):
+
+1. `api-root.json` — capture of `sf api request rest "/services/data/v67.0/" --method GET` for the target org.
+
+### Output
+
+```json
+{
+  "userId": "005...",
+  "identity": "https://<mydomain>.my.salesforce.com/id/00D.../005...",
+  "verdict": "RESOLVED",
+  "reasons": ["..."]
+}
+```
+
+Validation: the trailing path segment of `identity` must match `^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$` (15 or 18 chars, `005` prefix). Any other shape produces `CANNOT-CONFIRM` with the raw identity URL in `reasons[]`.
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `RESOLVED` | `userId` is safe to use as the running-user Id | Use `userId` for Phase 2b/2d assignments |
+| `CANNOT-CONFIRM` | No identity URL, or trailing segment does not match `005…` | Surface `reasons[]` verbatim and stop; do NOT fall back to prose parsing |
+
+## `scripts/classify-assignment-state.mjs`
+
+Decides whether the Phase 2d write is needed (idempotency). Handles both the license-backed persona flow and the standalone-persona flow.
+
+### Input
+
+Two positional arguments:
+
+1. `psa-existing.json` — `sf data query --json` capture of `PermissionSetAssignment` for the target user + selected persona's `Id`.
+2. `psla-existing.json` **OR** the literal sentinel `NO-PSL`:
+   - If the selected persona's `needsPsl:true`, pass the PSLA capture path.
+   - If the selected persona's `needsPsl:false`, pass the string `NO-PSL` — the classifier skips the PSLA envelope read and reports `licenseAssigned:null`.
+
+### Output
+
+```json
+{
+  "permsetAssigned": false,
+  "licenseAssigned": true,
+  "needsWrite": true,
+  "verdict": "NEEDS-WRITE",
+  "reasons": ["...", "..."]
+}
+```
+
+`licenseAssigned` is `null` (not `false`) in the `NO-PSL` branch to make it distinguishable from a real "no PSL row found" case.
+
+Verdict values:
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `NEEDS-WRITE` | `permsetAssigned` is `false` (or, when `needsPsl:true`, `licenseAssigned` is also `false`) | Confirm-to-write (Phase 2c), then Phase 2d (PSL first + permset if `needsPsl:true`; permset only if `needsPsl:false`) |
+| `ALREADY-ASSIGNED` | All applicable rows present | Skip Phase 2d entirely; go to Phase 4 verify |
+| `CANNOT-CONFIRM` | One of the query envelopes was unparseable | Surface `reasons[]` verbatim and stop |
+
+## `scripts/classify-action-surface.mjs`
+
+Decides whether the target `svc_itsm_intelligence__*` invocable actions are surfaced for the running user after the assign. Replaces prose "grep the response for ..." in Phase 4 (A9). Fulfiller-only — Employee actions (`svc_emp_intelligence__*`) are not tracked by this skill.
+
+### Input
+
+Positional arguments:
+
+1. `generate-prompt-response.json` — capture of `sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" --method GET`.
+2. `expectedActions-csv` (optional) — comma-separated list of specific action names to check by exact match (e.g. `svc_itsm_intelligence__DraftMobileTaskSummary,svc_itsm_intelligence__FindContextualKA`). Callers upstream (Fulfiller agent-configure Phase 1b) hold this list; when invoked standalone, omit the CSV.
+
+### Output
+
+```json
+{
+  "present": ["svc_itsm_intelligence__ActionA"],
+  "missing": ["svc_itsm_intelligence__ActionB"],
+  "totalItsmActionsSeen": 7,
+  "verdict": "PARTIAL",
+  "reasons": ["..."]
+}
+```
+
+Verdict values:
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `SURFACED` | With CSV: every expected action found. Without CSV: at least one `svc_itsm_intelligence__` action is present in the response | Proceed to Phase 5 → report `ASSIGNED` / `ALREADY-ASSIGNED` |
+| `PARTIAL` | With CSV only: some expected actions found, others missing | Report `VERIFY-INCONCLUSIVE` — session refresh may resolve, or the wrong persona permset was assigned |
+| `MISSING` | With CSV: none of the expected actions found. Without CSV: no `svc_itsm_intelligence__` actions in the response | Report `VERIFY-INCONCLUSIVE` — do not falsely report `ASSIGNED` |
+| `CANNOT-CONFIRM` | Envelope missing/failed or `actions[]` array not found | Surface `reasons[]` verbatim and stop |
+
+## Why deterministic classifiers?
+
+All four classifiers replace prose interpretation of query / response bodies with fixed rules that always produce the same output for the same input. This is the A9 rule the sibling agent-configure skills follow: any decision that gates a write (or a success report) on the state of a JSON body lives in a script, never in prose. Model interpretation of `records[].length === 0` is a well-documented source of false-positive skips ("classifier said empty, so no permset exists — proceed") when the real cause was an auth-failure that returned an empty envelope.

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/references/permset-topology.md

@@ -0,0 +1,82 @@
+# ITSM Fulfiller Persona Permset Topology (Core-shipped)
+
+This skill assigns Core-shipped **StandardPermissionSet** persona permsets — NOT a
+managed-package namespaced permset. On a real org there is no
+`svc_itsm_intelligence` namespaced `PermissionSet`; the Fulfiller agent's
+`svc_itsm_intelligence__*` prompt-template invocable actions surface only once
+the running user holds the correct **Fulfiller persona permset** shipped in
+Core (namespace `force`).
+
+**Employee agent is out of scope for this skill.** The Employee agent's access
+model is separate (org-preferences + a different persona layer) and does not
+map onto these four permsets.
+
+## Fulfiller persona ↔ AddOn ↔ PSL ↔ PermSet
+
+| Persona | AddOn (`.add.xml`) | PSL (`.psl.xml`) | **PermSet DeveloperName** (assign this) | Grants userPerm |
+|---|---|---|---|---|
+| Incident Fulfiller | `IncidentManagementAddOn-1` | `IncidentFulfillerPsl-1` | **`IncidentFulfiller`** | `IncidentFulfillerUser` |
+| Problem Fulfiller | `ProblemManagementAddOn-1` | `ProblemFulfillerPsl-1` | **`ProblemFulfillerPermSet`** | `ProblemFulfillerUser` |
+| Change Fulfiller | `ChangeManagementAddOn-1` | `ChangeRequestFulfillerPsl-1` | **`ChangeRequestFulfillerPermSet`** | `ChangeFulfillerPerm` |
+| Release Manager | `ReleaseManagementAddOn-1` | `ReleaseManagerPsl-1` | **`ReleaseManagerPermSet`** | (org-perm-gated only) |
+
+### Key facts
+
+- **Namespace is `force` on every permset** — the namespace-prefix filter used
+  in the previous version of this skill (`svc_itsm_intelligence`) never
+  returns any of these rows.
+- **Naming inconsistency**: `IncidentFulfiller` has NO `PermSet` suffix; the
+  other three DO. The classifier's fixed-name list reflects this exactly —
+  do not "normalize" the Incident name to `IncidentFulfillerPermSet`, it does
+  not exist on the org.
+- **`ReleaseManagerPermSet`** ships as a permset but its Fulfiller user permission
+  lives on the OrgPreference layer (org-perm-gated). Assigning the permset
+  still works and is the correct write; the runtime effect activates once the
+  org toggle is on. Downstream, `service-itsm-agentic-setup-agentforce-studio-validate`
+  is the skill that toggles the org preference.
+- **CMDB access is a separate concern** — the CMDB read/write permsets are
+  handled by `service-itsm-agentic-setup-cmdb-access-assign` and are not
+  gated by any `svc_itsm_intelligence__*` prompt-template invocable, so they
+  are intentionally excluded from this skill's fixed-lookup set.
+
+## Fixed-lookup discovery query (Phase 1)
+
+```sql
+SELECT Id, Name, Label, LicenseId
+FROM PermissionSet
+WHERE Name IN (
+  'IncidentFulfiller',
+  'ProblemFulfillerPermSet',
+  'ChangeRequestFulfillerPermSet',
+  'ReleaseManagerPermSet'
+)
+```
+
+**Interpreting the result set:**
+
+- **≥1 row present** ⇒ Branch A (assign). Ask the user which persona to
+  assign — do NOT auto-select, since a Fulfiller commonly needs only one
+  persona (e.g. Incident) even when others are provisioned.
+- **Zero rows** ⇒ Branch B (hand-off). The ITSM AddOn(s) are not provisioned
+  on this org. Route to `service-itsm-agentic-setup-agentforce-studio-validate`
+  so the AddOn(s) can be enabled first.
+
+## `needsPsl` per persona
+
+Whether the PSL POST step in Phase 2 runs is a **per-permset** decision, read
+from each row's `LicenseId`:
+
+- `LicenseId != null` ⇒ `needsPsl:true` (license-gated permset — POST the PSL
+  before the permset assign).
+- `LicenseId == null` ⇒ `needsPsl:false` (standalone permset — skip the PSL
+  POST entirely; assign the permset only).
+
+The classifier emits `needsPsl` per candidate row, so the caller reads the
+switch from the selected persona and does not need to re-derive it.
+
+## Codesearch sources
+
+Every row above was verified against the Core repo. When the AddOn / PSL /
+PermSet metadata drifts on a future release, re-run codesearch on the AddOn
+file (`*.add.xml`) — the AddOn's `<permissionSet>` reference is the source of
+truth for the DeveloperName this skill must assign.