@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-agentforce-studio-validate/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: service-itsm-agentic-setup-agentforce-studio-validate
+description: "Validate the Agentforce for IT Service prerequisites for a Fulfiller or Employee agent, using the Salesforce CLI (sf). The READ-ONLY prerequisite check: it reads the Salesforce Go feature toggles behind the Agentforce for IT Service setup page (Agentforce Studio, the IT Service Fulfiller / IT Service Employee templates, Specialized Agent Templates for Employee) via one Connect API call, then a helper script classifies the chosen path into a READY / NOT-READY verdict. It never enables anything; when a toggle is off it hands off to the agentforce-studio-configure skill to turn it on. Use when asked to check Agentforce prerequisites, validate the org is ready for an ITSM agent, or verify Agentforce Studio is enabled. Triggers: check agentforce prerequisites, validate agentforce readiness, is my org ready for the fulfiller agent, verify agentforce studio enabled. DO NOT TRIGGER: enabling or turning on the toggles, creating the fulfiller agent (service-itsm-agentic-setup-fulfiller-agent-configure), or CMDB CRUD."
+metadata:
+  version: "2.1"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-agentic-setup-agentforce-studio-configure"
+    - "service-itsm-agentic-setup-employee-agent-configure"
+    - "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
+---
+
+# Validate Agentforce for IT Service Prerequisites
+
+Readiness check for **Agentforce for IT Service**, for either the **Fulfiller** or the **Employee** agent path. Before an ITSM agent can be created, the org must have the right **Salesforce Go feature toggles** turned on (the ones on the *Agentforce for IT Service* setup page). This skill reads those toggles through the **Salesforce CLI (`sf`)** — a single authenticated Connect API call via `sf api request rest` — and a helper script classifies the chosen agent path into a **READY / NOT-READY** verdict.
+
+This is the **read-only** step in a three-skill flow. It **never enables anything**; turning toggles on is a separate write-capable skill:
+
+| Step | Skill | What it does |
+|------|-------|--------------|
+| 1. Validate (this skill) | `service-itsm-agentic-setup-agentforce-studio-validate` | Read the toggles → READY / NOT-READY (no writes) |
+| 2. Configure | `service-itsm-agentic-setup-agentforce-studio-configure` | Turn the disabled toggles ON |
+| 3. Create agent | `service-itsm-agentic-setup-fulfiller-agent-configure` | Create + activate the Fulfiller agent |
+
+On NOT-READY this skill names each disabled toggle and **hands off** to `service-itsm-agentic-setup-agentforce-studio-configure` to enable them — it does not POST an enable itself.
+
+The feature toggles and their real `featureApiName`s:
+
+| Go-page toggle | featureApiName | Required for |
+|----------------|----------------|--------------|
+| Turn on Agentforce Studio | `sales-cloud-agent-studio` | both paths (shared) |
+| Agentforce for IT Service (parent umbrella) | `service-cloud-agentforce-for-itsm` | both paths (shared) |
+| IT Service Fulfiller | `service-cloud-it-fulfiller-agent` | **fulfiller** |
+| IT Service Employee | `service-cloud-requestor-agent` | **employee** |
+| Specialized Agent Templates for Employee | `service-cloud-it-service-employee-agent` | **employee** |
+
+All are **Connect API** features (`/connect/setup/discovery/...`) — the read goes through `sf api request rest`, no Headless360 dispatcher required. The classification is **deterministic** and lives in `scripts/classify-readiness.mjs` (invoked via `Bash`), not in prose.
+
+## Scope
+
+- **In scope**: Reading the Agentforce-for-IT-Service Go feature toggles via `connect/setup/discovery/features/status`; classifying the **fulfiller** or **employee** path into a per-feature + overall READY / NOT-READY verdict via a helper script; on NOT-READY, naming each disabled toggle and handing off to `service-itsm-agentic-setup-agentforce-studio-configure` to enable it.
+- **Out of scope**: **Enabling / turning on any toggle** — that write is owned by `service-itsm-agentic-setup-agentforce-studio-configure` (this skill is read-only and never POSTs an enable); creating, committing, or activating an agent (handled by `service-itsm-agentic-setup-fulfiller-agent-configure`); the org-wide multi-agent orchestration toggle (that is a Headless360-only pref, not an ITSM Connect feature, and is not one of the setup-page toggles); assigning permission sets; CMDB CRUD.
+
+---
+
+## Which path?
+
+Determine whether the user is setting up the **fulfiller** agent (the IT-fulfiller-facing agent) or an **employee** agent (the employee-facing / NGA agent). If it is not clear from the request, ask (`AskUserQuestion`). The path selects which toggles are required:
+
+- **fulfiller** → `sales-cloud-agent-studio` + `service-cloud-agentforce-for-itsm` + `service-cloud-it-fulfiller-agent`
+- **employee** → `sales-cloud-agent-studio` + `service-cloud-agentforce-for-itsm` + `service-cloud-requestor-agent` + `service-cloud-it-service-employee-agent`
+
+---
+
+## Preconditions
+
+Before the skill can read anything, the CLI and target org must be configured. If any of these are unmet, `sf` surfaces an auth error or a `401`/`403`/`404`; **do not fabricate state — surface the raw error and stop**.
+
+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+**: the `connect/setup/discovery` feature APIs are available at v67.0. The version is pinned in the URL path; do not hand-edit it below the minimum.
+3. **`node` ≥ 18** on PATH (runs the classifier script).
+
+If a precondition fails, `sf` returns one of:
+- Auth error / `401 Unauthorized` → session expired or wrong alias; re-run `sf org login web`.
+- `403 Forbidden` → the user/org lacks the required access (missing Agentforce license).
+- `404 Not Found` → the feature-discovery surface is not wired on this org tier — the classifier maps a missing/error body to CANNOT-CONFIRM, not a hard failure.
+
+---
+
+## Operations at a glance
+
+| Operation | Command | Returns |
+|-----------|---------|---------|
+| Read feature toggles | `sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" --method POST --body '{"featureApiNames":[...]}' --target-org <alias>` | `{items:[{apiName,status,enableBlockedReasons[],dependencyStatuses[]}]}` — `status` is `ENABLED` / `NOT_ENABLED` per toggle. |
+
+This skill makes **only** the read above — it is read-only. Enabling a toggle (`.../feature/{apiName}/enable`) is out of scope: hand off to `service-itsm-agentic-setup-agentforce-studio-configure`. `sf api request rest` prints the raw response body (JSON) to stdout — capture it to a file and hand it to the classifier. Full command shapes and the error taxonomy live in `references/cli-invocation.md`.
+
+> **Never extract the access token.** Use `sf api request rest` directly — it uses the CLI's stored session for the target org. Do **not** pull the `accessToken` out of `sf org display` and hand-build an HTTP request with it; that bypasses the CLI session and leaks a bearer token into shell context.
+
+---
+
+## Architecture — How the check works
+
+| Step | What happens | Tool used |
+|------|--------------|-----------|
+| Pick path | Determine fulfiller vs employee (ask if unclear) | `AskUserQuestion` |
+| Read toggles | POST the feature-status batch for all toggles the path needs, capture to a file | `Bash` (`sf api request rest`) |
+| Classify | Run `scripts/classify-readiness.mjs <file> <agentType> [exitStatus]` → per-feature + overall verdict | `Bash` (`node`) |
+| Report | Render the classifier's verdict into the Output Format | — |
+| Hand off | On NOT-READY, name each disabled toggle and hand off to `service-itsm-agentic-setup-agentforce-studio-configure` to enable it | — |
+
+The skill is read-only — it never enables a toggle.
+
+---
+
+## Workflow
+
+Substitute `<alias>` with the target org alias (ask the user, or use the default org from `sf config`). `<agentType>` is `fulfiller` or `employee`.
+
+### Phase 1 — Read the feature toggles
+
+1. POST the feature-status batch for every toggle the chosen path needs (safe to always request all five — the classifier only judges the ones the path requires), capturing stdout to a file. Do **not** add `--json`:
+
+   ```bash
+   sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" \
+     --method POST \
+     --body '{"featureApiNames":["sales-cloud-agent-studio","service-cloud-agentforce-for-itsm","service-cloud-it-fulfiller-agent","service-cloud-requestor-agent","service-cloud-it-service-employee-agent"]}' \
+     --target-org <alias> > /tmp/features-status.json 2>/tmp/features-status.err
+   echo $? > /tmp/features-status.exit
+   ```
+
+   Capture the command's exit status (`$?`) so the classifier can tell a confirmed 404 (gate not wired) apart from an auth/permission/transport failure. Do not swallow the exit with `|| true` — pass it to the classifier in Phase 2.
+
+### Phase 2 — Classify (helper script)
+
+2. Run the classifier over the captured file, the chosen agent type, **and the captured exit status**. **Use the skill's absolute directory** for the script path:
+
+   ```bash
+   node "<skill_dir>/scripts/classify-readiness.mjs" /tmp/features-status.json <agentType> "$(cat /tmp/features-status.exit)"
+   ```
+
+   It prints `{ agentType, readState, features, verdict, notEnabled, enableable, reasons, rawError }` where each feature is `PASS | FAIL | CANNOT-CONFIRM | ERROR` and `verdict` is `READY | NOT-READY | CANNOT-CONFIRM | ERROR`. This is the authoritative verdict — do not re-derive it from the raw response in prose. `notEnabled` lists every disabled required toggle; `enableable` is the subset with **no** `enableBlockedReasons` — the ones the configure skill can turn on straight away (the rest are blocked by an unmet dependency or a purchase/licensing gate).
+
+### Phase 3 — Report + hand off
+
+3. Render the classifier output into the Output Format below.
+   - **READY** → point the user at `service-itsm-agentic-setup-fulfiller-agent-configure` to create the agent (fulfiller path), or `service-itsm-agentic-setup-employee-agent-configure` (employee path).
+   - **NOT-READY** → name each disabled toggle (from `notEnabled`). For the `enableable` subset, hand off to `service-itsm-agentic-setup-agentforce-studio-configure` to turn them on (offer via `AskUserQuestion`: _"N prerequisite toggle(s) are off. Run service-itsm-agentic-setup-agentforce-studio-configure to enable them?"_ → on Yes, delegate; on No, stop and report). For any disabled-but-blocked toggle (in `notEnabled` but not `enableable`), report its `enableBlockedReasons` verbatim — it cannot be enabled until the blocker clears. **This skill does not POST an enable itself.**
+   - **CANNOT-CONFIRM** → state which toggle(s) had no status and that the feature-discovery surface may not be wired on this org tier.
+   - **ERROR** → the read failed (auth / permission / transport, or an unexpected body — see `rawError`). Surface the raw response and **stop**; do not treat it as a mere wiring gap.
+
+### Phase 4 — (After enable) re-validate
+
+4. If the user ran `service-itsm-agentic-setup-agentforce-studio-configure` to enable the toggles, re-run Phase 1 + Phase 2 here to confirm the verdict flips to READY, then report. This skill's own role remains read-only throughout.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| **This skill is read-only** — it never POSTs a feature enable | Turning toggles on is a separate write-capable skill (`service-itsm-agentic-setup-agentforce-studio-configure`); keeping the two apart keeps the `validate` verb honest and avoids two skills owning the same write |
+| On NOT-READY, **hand off** to `service-itsm-agentic-setup-agentforce-studio-configure` for enablement | That skill owns the `.../feature/{apiName}/enable` write path (idempotent, dependency-ordered); this skill only names what is off |
+| The read goes through `sf api request rest`; **never extract the access token** or hand-build a raw HTTP request | `sf api request rest` uses the CLI's stored session for `--target-org`; extracting the token leaks a bearer token into shell context |
+| Classification lives in `scripts/classify-readiness.mjs`, invoked via `Bash` — not in prose | The verdict is a deterministic decision table over fixed feature statuses; a script is reliable, prose interpretation is not (authoring standard A9) |
+| The required-toggle set depends on the agent path | Fulfiller and Employee agents gate on different template toggles; the classifier encodes both paths |
+| These are **Connect API** features — use SF CLI, not Headless360 | A Connect/Tooling equivalent exists, so SF CLI is preferred (avoids the Headless360HostedMcpServer org-perm gate) |
+| `enableBlockedReasons` non-empty ⇒ toggle is not in `enableable` — report the blocker | A blocked toggle can't be turned on even by the configure skill until the unmet dependency / purchase gate clears |
+| Do **not** pass `--json` to `sf api request rest` | It is unsupported on some Connect endpoints; the raw stdout body is already JSON |
+
+---
+
+## Verification Checklist
+
+- [ ] The agent path (fulfiller / employee) was determined (asked if unclear).
+- [ ] The feature-status POST was run via `sf api request rest` and its body captured to a file.
+- [ ] `scripts/classify-readiness.mjs` was invoked with the file, the agent type, **and the captured exit status**, and its `{verdict, notEnabled, enableable, rawError}` output recorded.
+- [ ] The verdict (READY / NOT-READY / CANNOT-CONFIRM / ERROR) was reported verbatim from the classifier; on NOT-READY each disabled toggle was named, with the enable route only for the `enableable` subset and `enableBlockedReasons` reported for the rest; on ERROR the raw response was surfaced and the skill stopped.
+- [ ] No feature was enabled by this skill (it is read-only); on NOT-READY the disabled toggles were named and the hand-off to `service-itsm-agentic-setup-agentforce-studio-configure` was offered, and the access token was never extracted.
+
+---
+
+## Output Format
+
+Present the readiness report as:
+
+```text
+Agentforce for IT Service — Prerequisite Check (via service-itsm-agentic-setup-agentforce-studio-validate)
+
+Org:          <org-alias> (API v67.0)
+Agent path:   fulfiller | employee
+
+  [PASS|FAIL] Agentforce Studio ......................... ENABLED | NOT_ENABLED (sales-cloud-agent-studio)
+  [PASS|FAIL] Agentforce for IT Service (parent) ........ ENABLED | NOT_ENABLED (service-cloud-agentforce-for-itsm)
+  [PASS|FAIL] <path-specific toggle(s)> ................. ENABLED | NOT_ENABLED (<featureApiName>)
+
+Verdict: READY  |  NOT-READY  |  CANNOT-CONFIRM  |  ERROR
+
+Next steps:
+  - <If READY: "Org satisfies the prerequisites for the <path> agent. Create it via service-itsm-agentic-setup-fulfiller-agent-configure (fulfiller) / the employee-agent skill.">
+  - <If NOT-READY: list each disabled toggle; for the enableable ones, hand off to service-itsm-agentic-setup-agentforce-studio-configure to turn them on; for blocked ones, report the enableBlockedReasons.>
+  - <If CANNOT-CONFIRM: state which toggle(s) returned no status and that the feature-discovery surface may not be wired on this org.>
+```
+
+This skill is **read-only** — no org state is written. The only file it produces is the temporary response capture handed to the classifier.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/cli-invocation.md` | Every phase — exact `sf api request rest` read call shape, the feature-status route, the read-only / hand-off rule, the never-extract-token rule, the classifier contract, and the error taxonomy |

package/skills/service-itsm-agentic-setup-agentforce-studio-validate/references/cli-invocation.md

@@ -0,0 +1,194 @@
+# CLI invocation reference — service-itsm-agentic-setup-agentforce-studio-validate
+
+This skill uses the **Salesforce CLI (`sf`)** as its only transport, and it is
+**read-only**: it reads the *Agentforce for IT Service* Salesforce Go feature
+toggles via one Connect API POST (`sf api request rest`), and a Node helper
+script classifies the chosen agent path into a verdict. It **never enables** a
+toggle — turning toggles on is owned by the separate write-capable skill
+`service-itsm-agentic-setup-agentforce-studio-configure`, which this skill hands
+off to on NOT-READY. It extracts no access tokens.
+
+## Why `sf api request rest`, never curl + token
+
+`sf api request rest` authenticates using the CLI's stored session for the
+`--target-org` alias — the CLI mints/refreshes the token internally and never
+exposes it. **Do not** do:
+
+<!-- skill-validate: ignore -->
+```bash
+# FORBIDDEN — leaks a bearer token into shell context, bypasses the CLI session
+TOKEN=$(sf org display --json -o <alias> | jq -r '.result.accessToken')
+curl -H "Authorization: Bearer $TOKEN" https://.../connect/setup/discovery/features/status
+```
+
+Every call this skill makes is a plain `/services/data/v67.0/connect/...` Connect
+API path, exactly what `sf api request rest` proxies. There is no reason to fall
+back to curl.
+
+## Why SF CLI (Connect API), not Headless360
+
+The *Agentforce for IT Service* Go toggles are backed by real Connect API
+features under `/connect/setup/discovery/`. Because a Connect equivalent exists,
+the transport decision prefers SF CLI to avoid the `Headless360HostedMcpServer`
+org-perm gate. (The only ITSM-adjacent pref that has *no* Connect equivalent —
+the org-wide multi-agent orchestrator toggle — is out of this skill's scope and
+would require Headless360 dispatch.)
+
+## The feature toggles
+
+The *Agentforce for IT Service* setup page (feature key
+`service-cloud-agentforce-for-itsm`) has these child toggles. The `featureApiName`
+column is what the API uses:
+
+| UI toggle | featureApiName | Required for |
+|-----------|----------------|--------------|
+| Turn on Agentforce Studio | `sales-cloud-agent-studio` | both paths |
+| Agentforce for IT Service (parent umbrella) | `service-cloud-agentforce-for-itsm` | both paths |
+| IT Service Fulfiller | `service-cloud-it-fulfiller-agent` | fulfiller |
+| IT Service Employee | `service-cloud-requestor-agent` | employee |
+| Specialized Agent Templates for Employee | `service-cloud-it-service-employee-agent` | employee |
+
+Dependency chain (enable order): `sales-cloud-einstein-generative-ai` →
+`sales-cloud-agent-studio` → `service-cloud-agentforce-for-itsm` (parent) → the
+child template toggles. The read response echoes this in `dependencyStatuses[]`.
+
+## Target org, API version, and the `--json` rule
+
+- **Target org**: always `--target-org <alias>` (or `-o <alias>`). Resolve from
+  the user or the default org (`sf config get target-org`).
+- **API version**: pinned in the URL path (`/services/data/v67.0/...`). Do not
+  hand-edit below `metadata.minApiVersion` (`67.0`).
+- **`--json`**: do **not** add `--json` to `sf api request rest` — it is
+  unsupported on some Connect endpoints and errors; the raw stdout body is
+  already JSON.
+
+## Read — feature status (the one read this skill makes)
+
+```bash
+sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" \
+  --method POST \
+  --body '{"featureApiNames":["sales-cloud-agent-studio","service-cloud-agentforce-for-itsm","service-cloud-it-fulfiller-agent","service-cloud-requestor-agent","service-cloud-it-service-employee-agent"]}' \
+  --target-org <alias> > /tmp/features-status.json 2>/tmp/features-status.err
+echo $? > /tmp/features-status.exit
+```
+
+Capture the exit status (`$?`) rather than swallowing it with `|| true` — the
+classifier uses it to separate a confirmed 404 (gate not wired → CANNOT-CONFIRM)
+from an empty-body auth/permission/transport failure (→ ERROR, surface and stop).
+It is safe to always request all five apiNames — the classifier only judges the
+subset the chosen path requires. Response shape (abridged):
+
+```json
+{
+  "items": [
+    {
+      "apiName": "service-cloud-it-fulfiller-agent",
+      "status": "ENABLED",
+      "enableBlockedReasons": [],
+      "dependencyStatuses": [
+        { "apiName": "sales-cloud-agent-studio", "status": "ENABLED", "enableBlockedReasons": [] }
+      ]
+    },
+    { "apiName": "service-cloud-it-service-employee-agent", "status": "NOT_ENABLED", "enableBlockedReasons": [] }
+  ]
+}
+```
+
+- `status: "ENABLED"` ⇒ toggle on ⇒ **PASS**.
+- `status: "NOT_ENABLED"` with empty `enableBlockedReasons` ⇒ toggle off ⇒ **FAIL**;
+  the classifier lists it under `enableable` and attaches the enable route (which the
+  hand-off skill uses — this skill only reports it, it does not call it).
+- `status: "NOT_ENABLED"` with non-empty `enableBlockedReasons` ⇒ **FAIL** but
+  **not** enableable — the classifier keeps it in `notEnabled`, omits it from
+  `enableable`, and carries the blockers so the hand-off never queues a doomed enable.
+- A missing item ⇒ **CANNOT-CONFIRM** for that toggle.
+- A confirmed `404`/NOT_FOUND error body ⇒ whole read is **CANNOT-CONFIRM** (gate not wired).
+- An empty body (CLI exited non-zero) or an auth/permission/unexpected error body ⇒
+  whole read is **ERROR** — surface `rawError` and stop.
+
+The single-feature GET `.../connect/setup/discovery/feature/{apiName}/summary`
+returns the same status for one feature; the batch POST above is preferred so one
+call covers the whole path.
+
+## Enablement is a hand-off — this skill never POSTs an enable
+
+This skill is read-only. When the verdict is NOT-READY, it names each disabled
+toggle (the `notEnabled` list; `enableable` is the subset with no blockers) and
+hands off to **`service-itsm-agentic-setup-agentforce-studio-configure`**, which
+owns the write path `POST /connect/setup/discovery/feature/{apiName}/enable`
+(idempotent, dependency-ordered — Einstein GenAI → Studio → the ITSM child
+toggles). After the user runs that skill, re-read `features/status` here and
+re-run the classifier to confirm the verdict flips to READY. Do **not** POST the
+enable route from this skill — that would duplicate the configure skill's
+responsibility and break the read-only contract the `validate` name promises.
+
+## The classifier — `scripts/classify-readiness.mjs`
+
+The deterministic verdict logic lives in the script, not in the workflow prose
+(authoring standard A9). Invoke it with the captured file **and** the agent type,
+using the skill's **absolute** directory (a bare `./scripts/...` won't resolve
+against the CWD):
+
+```bash
+node "<skill_dir>/scripts/classify-readiness.mjs" /tmp/features-status.json <fulfiller|employee> "$(cat /tmp/features-status.exit)"
+```
+
+The third arg (the captured `$?`) is optional but recommended — it lets the
+classifier distinguish an empty-body failure (ERROR) from a confirmed 404
+(CANNOT-CONFIRM). Output (to stdout):
+
+```json
+{
+  "agentType": "fulfiller | employee",
+  "readState": "ok | not-wired | error",
+  "features": { "<apiName>": { "status": "ENABLED|NOT_ENABLED|UNKNOWN", "signal": "PASS|FAIL|CANNOT-CONFIRM|ERROR", "enableBlockedReasons": [], "enableable": true, "enableRoute": "POST .../enable | null" } },
+  "verdict": "READY | NOT-READY | CANNOT-CONFIRM | ERROR",
+  "notEnabled": ["<apiName>", "..."],
+  "enableable": ["<apiName>", "..."],
+  "reasons": ["..."],
+  "rawError": "null | <error snippet>"
+}
+```
+
+Verdict rule (encoded in the script):
+- A read failure that is **not** a confirmed 404 (empty body / auth / permission /
+  unexpected shape) ⇒ `ERROR` — surface `rawError` and stop.
+- Otherwise: any required toggle `FAIL` ⇒ `NOT-READY`; all required `PASS` ⇒
+  `READY`; else (a `CANNOT-CONFIRM` with no `FAIL`) ⇒ `CANNOT-CONFIRM`.
+
+`notEnabled` lists every `NOT_ENABLED` required toggle; `enableable` is the subset
+with **no** `enableBlockedReasons` — the toggles the hand-off configure skill can
+turn on straight away (the rest are blocked). `enableRoute` is informational only.
+The script always exits `0` on a usable agent type; the verdict is in the payload.
+A confirmed `404`/NOT_FOUND maps every feature to CANNOT-CONFIRM (never a throw);
+an empty/auth/unexpected body maps to ERROR.
+
+## Error taxonomy
+
+- **Auth error / `401 Unauthorized`** — session expired or wrong alias. Re-run
+  `sf org login web`; there is no token to refresh by hand.
+- **`403 Forbidden`** — the user/org lacks the Agentforce license (`accessCheck`
+  gate). Surface verbatim.
+- **`404 Not Found`** on `features/status` — the feature-discovery surface is not
+  wired on the org tier (expected on some scratch orgs). The classifier maps a
+  confirmed 404/NOT_FOUND error body to CANNOT-CONFIRM.
+- **`401 Unauthorized` / `403 Forbidden` / empty body / unexpected shape** —
+  the classifier maps these to **ERROR** (not CANNOT-CONFIRM): surface `rawError`
+  and stop. An unreadable org must not masquerade as a mere wiring gap.
+- **`enableBlockedReasons` non-empty** on a toggle — an unmet dependency or a
+  purchase/licensing gate; the classifier keeps the toggle in `notEnabled`,
+  omits it from `enableable`, and reports the reason. Do not POST enable.
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `sf api request rest --json` errors | Don't pass `--json` — the raw stdout body is already JSON |
+| Bare `./scripts/classify-readiness.mjs` "not found" | Use the skill's absolute `<skill_dir>` in the `node` invocation |
+| Passing the file but no agent type | The classifier needs `<fulfiller\|employee>` as its 2nd arg — it exits 2 (usage) otherwise |
+| Treating a 404 as a hard fail | A confirmed 404 is CANNOT-CONFIRM — report which toggle had no status, not a hard NOT-READY |
+| Treating an auth/permission failure or empty body as CANNOT-CONFIRM | Pass `$?` as the 3rd classifier arg — an empty/auth/unexpected body is ERROR (surface `rawError`, stop); only a confirmed 404 is CANNOT-CONFIRM |
+| Handing off a blocked toggle for enable | Hand off only the `enableable` toggles; a `notEnabled` toggle with `enableBlockedReasons` is excluded — report the blocker instead |
+| POSTing the enable route from this skill | Never — this skill is read-only; enablement is owned by `service-itsm-agentic-setup-agentforce-studio-configure`. Hand off instead |
+| Tempted to token+curl for "just a POST read" | Never — `sf api request rest` handles auth for `/services/data/...` paths |
+| Checking `agentforce-studio/access/{product}` as the studio toggle | That endpoint is a product-entitlement check, not the feature toggle — use `sales-cloud-agent-studio` feature status instead |

package/skills/service-itsm-agentic-setup-agentforce-studio-validate/scripts/classify-readiness.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// Deterministic readiness classifier for the Agentforce for IT Service prerequisite check.
+//
+// Consumes the raw JSON body of a single `sf api request rest` read of the
+// Salesforce Go feature-status endpoint and, for a chosen agent path
+// (fulfiller | employee), decides whether every required feature toggle is ON.
+// This is the deterministic decision table that MUST NOT be interpreted by the
+// model in prose (authoring standard A9).
+//
+// Usage:
+//   node classify-readiness.mjs <features-status.json> <agentType> [exitStatus]
+//
+// <features-status.json> is a FILE PATH to the raw stdout captured from:
+//   sf api request rest "/services/data/vXX.0/connect/setup/discovery/features/status" \
+//     --method POST --body '{"featureApiNames":[...]}' --target-org <org> > file.json
+// The body shape is { items: [ { apiName, status, enableBlockedReasons[],
+// dependencyStatuses[] } ] } where status is "ENABLED" | "NOT_ENABLED".
+// The file may instead hold the CLI error payload (a JSON array like
+// [{"errorCode":"NOT_FOUND",...}]) or be empty when the CLI exited non-zero.
+//
+// <exitStatus> is the OPTIONAL numeric exit code of the `sf` command ($? in the
+// shell). Pass it so the classifier can tell a *confirmed* 404-style "gate not
+// wired" (→ CANNOT-CONFIRM) apart from an auth / permission / transport failure
+// (→ ERROR, surface the raw response and stop). An empty or unparseable body is
+// treated as ERROR, never CANNOT-CONFIRM.
+//
+// <agentType> is one of: fulfiller | employee. It selects which feature toggles
+// are required — fulfiller checks the fulfiller template pref, employee checks
+// the requestor + specialized-employee template prefs. Both paths also require
+// the shared Agentforce Studio pref and the ITSM parent umbrella.
+//
+// Emits a single JSON object to stdout:
+//   { agentType, readState,
+//     features: { <apiName>: { status, signal, enableBlockedReasons, enableable, enableRoute } },
+//     verdict, notEnabled: [<apiName>...], enableable: [<apiName>...], reasons: [...], rawError }
+// where each signal is PASS | FAIL | CANNOT-CONFIRM | ERROR and verdict is
+// READY | NOT-READY | CANNOT-CONFIRM | ERROR. Exit code is always 0 on a usable
+// agentType; the verdict is carried in the payload, not the exit status.
+
+import { readFileSync } from 'node:fs';
+
+// Required feature toggles per agent path. The apiNames are the real Salesforce
+// Go featureApiNames behind the "Agentforce for IT Service" page toggles.
+const STUDIO = 'sales-cloud-agent-studio';                 // "Turn on Agentforce Studio"
+const PARENT = 'service-cloud-agentforce-for-itsm';        // "Agentforce for IT Service" umbrella
+const FULFILLER = 'service-cloud-it-fulfiller-agent';      // "IT Service Fulfiller"
+const REQUESTOR = 'service-cloud-requestor-agent';         // "IT Service Employee"
+const SPECIALIZED = 'service-cloud-it-service-employee-agent'; // "Specialized Agent Templates for Employee"
+
+const REQUIRED = {
+  fulfiller: [STUDIO, PARENT, FULFILLER],
+  employee: [STUDIO, PARENT, REQUESTOR, SPECIALIZED],
+};
+
+const LABEL = {
+  [STUDIO]: 'Agentforce Studio',
+  [PARENT]: 'Agentforce for IT Service (parent)',
+  [FULFILLER]: 'IT Service Fulfiller template',
+  [REQUESTOR]: 'IT Service Employee template',
+  [SPECIALIZED]: 'Specialized Agent Templates for Employee',
+};
+
+function enableRoute(apiName) {
+  return `POST /connect/setup/discovery/feature/${apiName}/enable`;
+}
+
+function readJson(path) {
+  // { ok:true, data } on a parseable body; { ok:false, empty:true } when the file
+  // is missing/empty; { ok:false, empty:false } when it holds non-JSON garbage.
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, empty: true };
+    return { ok: true, data: JSON.parse(text) };
+  } catch {
+    return { ok: false, empty: false };
+  }
+}
+
+function asErrorArray(data) {
+  // sf api request rest surfaces Connect API errors as an array of
+  // {errorCode,message} (or a single such object). Returns [] if not an error body.
+  if (Array.isArray(data)) return data.filter((e) => e && (e.errorCode || e.message));
+  if (data && (data.errorCode || data.message)) return [data];
+  return [];
+}
+
+function isNotFoundError(errs) {
+  // A 404 / NOT_FOUND / gate-not-wired is the ONLY error shape that maps to
+  // "cannot confirm". Auth (401), permission (403), and everything else = ERROR.
+  return errs.some((e) => {
+    const code = String(e?.errorCode ?? '').toUpperCase();
+    const msg = String(e?.message ?? '').toUpperCase();
+    return code.includes('NOT_FOUND') || code.includes('NOT_EXIST') ||
+      msg.includes('NOT FOUND') || msg.includes('DOES NOT EXIST') ||
+      msg.includes('COULD NOT BE FOUND');
+  });
+}
+
+function errorSnippet(errs) {
+  return errs.map((e) => `${e.errorCode ?? 'ERROR'}: ${e.message ?? ''}`.trim()).join(' | ').slice(0, 500);
+}
+
+// Returns { readState, statusMap, rawError }:
+//   readState 'ok'        → statusMap has per-apiName { status, enableBlockedReasons }
+//   readState 'not-wired' → a confirmed 404 (feature-discovery surface not wired)
+//   readState 'error'     → empty / auth / permission / transport / unexpected body
+function readFeatureStatus(res, exitStatus) {
+  if (!res.ok) {
+    // Empty or non-JSON body. Never a confirmed 404 → ERROR (surface it, stop).
+    const why = res.empty
+      ? (Number.isFinite(exitStatus) && exitStatus !== 0
+          ? `The read command exited ${exitStatus} with an empty body (auth / permission / transport failure).`
+          : 'The read produced an empty body — the response could not be read.')
+      : 'The read produced a non-JSON body that could not be parsed.';
+    return { readState: 'error', statusMap: null, rawError: why };
+  }
+  const d = res.data;
+  const errs = asErrorArray(d);
+  if (errs.length) {
+    if (isNotFoundError(errs)) return { readState: 'not-wired', statusMap: null, rawError: null };
+    return { readState: 'error', statusMap: null, rawError: errorSnippet(errs) };
+  }
+  const items = Array.isArray(d?.items) ? d.items : null;
+  if (!items) {
+    return { readState: 'error', statusMap: null, rawError: 'The response had no "items" array (unexpected shape).' };
+  }
+  const map = new Map();
+  for (const it of items) {
+    if (it?.apiName) {
+      map.set(it.apiName, {
+        status: String(it.status ?? '').toUpperCase(),
+        enableBlockedReasons: Array.isArray(it.enableBlockedReasons) ? it.enableBlockedReasons : [],
+      });
+    }
+  }
+  return { readState: 'ok', statusMap: map, rawError: null };
+}
+
+function classifyFeature(apiName, statusMap) {
+  const label = LABEL[apiName] ?? apiName;
+  if (!statusMap || !statusMap.has(apiName)) {
+    return {
+      status: 'UNKNOWN', signal: 'CANNOT-CONFIRM', enableBlockedReasons: [], enableable: false, enableRoute: null,
+      reason: `${label} (${apiName}) — no status returned (endpoint not wired / not in response).`,
+    };
+  }
+  const { status, enableBlockedReasons } = statusMap.get(apiName);
+  if (status === 'ENABLED') {
+    return { status, signal: 'PASS', enableBlockedReasons: [], enableable: false, enableRoute: null, reason: `${label} (${apiName}) → ENABLED.` };
+  }
+  if (status === 'NOT_ENABLED') {
+    const blocked = enableBlockedReasons.length > 0;
+    return {
+      status, signal: 'FAIL', enableBlockedReasons,
+      enableable: !blocked,
+      enableRoute: blocked ? null : enableRoute(apiName),
+      reason: blocked
+        ? `${label} (${apiName}) → NOT_ENABLED, but blocked: ${enableBlockedReasons.map((r) => (typeof r === 'string' ? r : (r?.message ?? JSON.stringify(r)))).join('; ')}.`
+        : `${label} (${apiName}) → NOT_ENABLED (enableable).`,
+    };
+  }
+  return {
+    status, signal: 'CANNOT-CONFIRM', enableBlockedReasons: [], enableable: false, enableRoute: null,
+    reason: `${label} (${apiName}) → unexpected status "${status}".`,
+  };
+}
+
+const [statusPath, rawAgentType, rawExit] = process.argv.slice(2);
+const agentType = String(rawAgentType ?? '').toLowerCase();
+if (!statusPath || !REQUIRED[agentType]) {
+  process.stderr.write('usage: node classify-readiness.mjs <features-status.json> <fulfiller|employee> [exitStatus]\n');
+  process.exit(2);
+}
+const exitStatus = rawExit === undefined ? NaN : Number(rawExit);
+
+const { readState, statusMap, rawError } = readFeatureStatus(readJson(statusPath), exitStatus);
+
+const features = {};
+const reasons = [];
+const notEnabled = [];
+const enableable = [];
+
+if (readState === 'error') {
+  // Hard read failure (auth / permission / transport / unexpected). Do NOT
+  // pretend the gate is merely un-wired — surface it and stop.
+  for (const apiName of REQUIRED[agentType]) {
+    features[apiName] = { status: 'UNKNOWN', signal: 'ERROR', enableBlockedReasons: [], enableable: false, enableRoute: null };
+  }
+  reasons.push(`Feature status could not be read: ${rawError} Surface the raw response and stop — do not treat as a wiring gap.`);
+  process.stdout.write(JSON.stringify({
+    agentType, readState, features, verdict: 'ERROR', notEnabled, enableable, reasons, rawError,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const signals = [];
+for (const apiName of REQUIRED[agentType]) {
+  const c = classifyFeature(apiName, statusMap);
+  features[apiName] = {
+    status: c.status, signal: c.signal,
+    enableBlockedReasons: c.enableBlockedReasons, enableable: c.enableable, enableRoute: c.enableRoute,
+  };
+  reasons.push(c.reason);
+  signals.push(c.signal);
+  if (c.signal === 'FAIL') notEnabled.push(apiName);
+  if (c.enableable) enableable.push(apiName);
+}
+
+let verdict;
+if (signals.includes('FAIL')) verdict = 'NOT-READY';
+else if (signals.every((s) => s === 'PASS')) verdict = 'READY';
+else verdict = 'CANNOT-CONFIRM';
+
+process.stdout.write(JSON.stringify({
+  agentType,
+  readState,
+  features,
+  verdict,
+  notEnabled,
+  enableable,
+  reasons,
+  rawError,
+}, null, 2) + '\n');