@salesforce/afv-skills 1.40.0 → 1.41.0

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

@@ -0,0 +1,265 @@
+# CLI invocation reference — service-itsm-agentic-setup-agentforce-studio-configure
+
+This skill uses the **Salesforce CLI (`sf`)** as its only transport. It is
+**write-capable**: it reads the *Agentforce for IT Service* Salesforce Go
+feature toggles via Connect API (`sf api request rest`), computes a
+dependency-ordered enable plan with a Node helper script, and — after explicit
+user confirmation — enables each disabled toggle via the same Connect API
+route. 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 -X POST -H "Authorization: Bearer $TOKEN" \
+  https://.../connect/setup/discovery/feature/sales-cloud-agent-studio/enable
+```
+
+Every call this skill makes — read and write — 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.
+
+## The feature toggles and dependency order
+
+| UI toggle | featureApiName | Depends on |
+|-----------|----------------|------------|
+| Einstein Generative AI | `sales-cloud-einstein-generative-ai` | none |
+| Turn on Agentforce Studio | `sales-cloud-agent-studio` | Einstein GenAI |
+| Agentforce for IT Service (parent umbrella) | `service-cloud-agentforce-for-itsm` | Studio, Einstein GenAI |
+| IT Service Fulfiller (template) | `service-cloud-it-fulfiller-agent` | parent umbrella |
+| IT Service Employee (template) | `service-cloud-requestor-agent` | parent umbrella |
+| Specialized Agent Templates for Employee | `service-cloud-it-service-employee-agent` | parent umbrella |
+
+Enable order: Einstein GenAI → Studio → parent umbrella → path-specific
+template(s). The read response echoes unmet dependencies in
+`dependencyStatuses[]`; the classifier encodes this same order in `ORDER` so
+the enable loop never attempts a child before its parent.
+
+## Target org, API version, and the `--json` rule
+
+- **Target org**: always `--target-org <alias>` (or `-o <alias>`).
+- **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
+
+```bash
+sf api request rest "/services/data/v67.0/connect/setup/discovery/features/status" \
+  --method POST \
+  --body '{"featureApiNames":["sales-cloud-einstein-generative-ai","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/enable-status-before.json 2>/tmp/enable-status-before.err
+echo $? > /tmp/enable-status-before.exit
+```
+
+Response shape (abridged):
+
+```json
+{
+  "items": [
+    { "apiName": "sales-cloud-einstein-generative-ai", "status": "ENABLED", "enableBlockedReasons": [], "dependencyStatuses": [] },
+    { "apiName": "sales-cloud-agent-studio", "status": "NOT_ENABLED", "enableBlockedReasons": [], "dependencyStatuses": [{ "apiName": "sales-cloud-einstein-generative-ai", "status": "ENABLED" }] }
+  ]
+}
+```
+
+- `status: "ENABLED"` ⇒ already on ⇒ skip the write (idempotent).
+- `status: "NOT_ENABLED"` with empty `enableBlockedReasons` ⇒ enable-able.
+- `status: "NOT_ENABLED"` with non-empty `enableBlockedReasons` ⇒ **do not
+  attempt to enable** — report the blocker.
+- 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.
+
+## Write — enable a feature
+
+```bash
+sf api request rest "/services/data/v67.0/connect/setup/discovery/feature/sales-cloud-agent-studio/enable" \
+  --method POST \
+  --body '{}' \
+  --target-org <alias>
+```
+
+Replace the path segment with the exact `featureApiName`. The endpoint itself
+takes **no meaningful body** — but `sf api request rest --method POST` with no
+`--body` flag at all fails with `Error (SfError): No 'mode' found in 'body'
+entry` (verified on CLI 2.140.6 and 2.145.6 — this is a CLI-parser quirk, not
+version-specific). Always pass `--body '{}'` explicitly. An optional
+`solutionApiName` query param can bind the feature to a specific SKU/license
+solution (omit for default — not used by this skill).
+
+Response shape:
+
+```json
+{ "success": true }
+```
+
+`{success:true}` = enabled (or was already enabled). If the response is an
+error (e.g. `enableBlockedReasons` still present, missing license, unmet
+dependency), record it verbatim and continue to the next toggle in the plan —
+do not let one failure block the rest.
+
+Capture every `/enable` response to a file and immediately hand it to
+`scripts/record-enable-result.mjs` (below) — do not eyeball the JSON body in
+prose to decide ENABLED vs FAILED.
+
+## Re-check before every toggle — never trust one snapshot for the whole loop
+
+A toggle whose dependency is still off at read time carries a non-empty
+`enableBlockedReasons` — but that dependency may be enabled by an *earlier*
+step in this same loop. If the loop trusts the Phase-1/Phase-2 snapshot for
+every toggle, a child that becomes enable-able mid-loop is permanently
+written off as blocked. **Re-read `features/status` and re-run
+`classify-enable-plan.mjs` immediately before each toggle attempt**, and
+branch on that toggle's *current* signal:
+
+- `PASS` → already enabled, skip.
+- `FAIL` with empty `enableBlockedReasons` → POST `/enable`, then record the
+  result.
+- `FAIL` with non-empty `enableBlockedReasons` → still genuinely blocked,
+  skip to the next toggle.
+- `CANNOT-CONFIRM`/`ERROR` on that specific re-read → stop the loop and
+  surface the failure; do not guess.
+
+One failed or blocked toggle does not stop the loop from attempting the
+remaining toggles in `order`.
+
+## Enablement is confirm-gated — never a silent write
+
+This skill mutates org state. Before any `/enable` POST, the exact `pending`
+list (from the classifier) must be presented to the user via
+`AskUserQuestion` and explicitly confirmed. Do not skip this checkpoint even
+when the skill was reached via a hand-off from the validate skill's
+NOT-READY report — that report names what is off, it does not constitute
+confirmation to write.
+
+## The classifier — `scripts/classify-enable-plan.mjs`
+
+The deterministic plan/verdict logic lives in the script, not in the workflow
+prose (authoring standard A9). Invoke it with the captured file, the agent
+type, and the captured exit status, using the skill's **absolute** directory:
+
+```bash
+node "<skill_dir>/scripts/classify-enable-plan.mjs" /tmp/enable-status-before.json <fulfiller|employee> "$(cat /tmp/enable-status-before.exit)"
+```
+
+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": [] } },
+  "order": ["<apiName>", "..."],
+  "alreadyEnabled": ["<apiName>", "..."],
+  "pending": ["<apiName>", "..."],
+  "blocked": ["<apiName>", "..."],
+  "unconfirmed": ["<apiName>", "..."],
+  "verdict": "ALL-ENABLED | NEEDS-ENABLE | CANNOT-CONFIRM | ERROR",
+  "reasons": ["..."],
+  "rawError": "null | <error snippet>"
+}
+```
+
+`unconfirmed` lists any required `apiName` that was missing from the response
+or carried a status the classifier doesn't recognize — neither confirmed
+`ENABLED` nor `NOT_ENABLED`. `verdict` is `NEEDS-ENABLE` whenever `pending` is
+non-empty; otherwise `CANNOT-CONFIRM` whenever `unconfirmed` is non-empty; only
+`ALL-ENABLED` when both are empty. An empty `pending` alone does **not** mean
+every toggle is enabled — always check `unconfirmed` too.
+
+Call the script at least **three times** across the flow: once on the Phase-2
+read (before any write) to compute the confirm checkpoint and seed
+`alreadyEnabled`; then **once per toggle, immediately before each attempt**,
+inside the Phase-4 loop (see re-check rule above); and once more on the
+Phase-5 re-read (after the enable loop) to feed `classify-final-report.mjs`.
+
+## Recording each enable attempt — `scripts/record-enable-result.mjs`
+
+Deterministic per-toggle response classifier/accumulator (authoring standard
+A9) — call it once per toggle, right after that toggle's `/enable` POST, from
+inside the Bash loop:
+
+```bash
+node "<skill_dir>/scripts/record-enable-result.mjs" /tmp/enable-<apiName>.json <apiName> /tmp/enable-results.json
+```
+
+- `<response.json>` — the raw stdout captured from that toggle's `/enable`
+  POST.
+- `<apiName>` — the featureApiName just attempted.
+- `<results.json>` — an accumulator file read (if present) and rewritten each
+  call, keyed by `apiName`.
+
+Emits/writes `{ "<apiName>": { "status": "ENABLED|FAILED", "reason": "null | <snippet>" } }` merged with any prior entries. `success:true` in the response body ⇒ `ENABLED`; any error body, empty body, or unexpected shape ⇒ `FAILED` with the reason captured verbatim. Never left unrecorded — even a malformed response becomes a `FAILED` entry, not a skipped one.
+
+## Final verdict — `scripts/classify-final-report.mjs`
+
+Deterministic final-report aggregator (authoring standard A9) — run once,
+after the Phase-5 re-read, combining the Phase-2 plan, the Phase-4 results
+accumulator, and the Phase-5 re-classification:
+
+```bash
+node "<skill_dir>/scripts/classify-final-report.mjs" /tmp/enable-plan-before.json /tmp/enable-results.json /tmp/enable-plan-after.json
+```
+
+Pass `-` for the results arg if Phase 4 never ran (Phase-2 verdict was already
+`ALL-ENABLED` or `CANNOT-CONFIRM`/`ERROR`). Output:
+
+```json
+{
+  "features": { "<apiName>": { "finalStatus": "ALREADY-ENABLED|ENABLED|FAILED|CANNOT-CONFIRM|ERROR", "reason": "..." } },
+  "order": ["<apiName>", "..."],
+  "overall": "SUCCESS | PARTIAL | FAILED | CANNOT-CONFIRM | ERROR",
+  "reasons": ["..."]
+}
+```
+
+Render `features` and `overall` directly into the Output Format — do not
+re-derive the per-feature or aggregate verdict in prose.
+
+## 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. The classifier maps a confirmed 404/NOT_FOUND
+  error body to CANNOT-CONFIRM.
+- **Empty body / unexpected shape** — the classifier maps these to ERROR (not
+  CANNOT-CONFIRM): surface `rawError` and stop.
+- **`enableBlockedReasons` non-empty** on a toggle — an unmet dependency or a
+  purchase/licensing gate; the classifier keeps the toggle out of the enable
+  loop (`blocked`) and reports the reason. Do not retry the POST — but do
+  re-check on the next loop iteration in case an earlier toggle's `/enable`
+  just unblocked it.
+- **A required `apiName` missing from the response, or an unrecognized
+  `status` string** — neither confirmed `ENABLED` nor `NOT_ENABLED`; the
+  classifier lists it in `unconfirmed` and the verdict is `CANNOT-CONFIRM`
+  even if `pending` is empty. Never report `ALL-ENABLED`/`SUCCESS` while
+  `unconfirmed` is non-empty.
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `sf api request rest --json` errors | Don't pass `--json` — the raw stdout body is already JSON |
+| `sf api request rest --method POST` with no `--body` flag errors `No 'mode' found in 'body' entry` | The `/enable` endpoint takes no meaningful body, but the CLI still requires the flag — always pass `--body '{}'` explicitly (verified on CLI 2.140.6 and 2.145.6) |
+| Bare `./scripts/classify-enable-plan.mjs` "not found" | Use the skill's absolute `<skill_dir>` in the `node` invocation |
+| Enabling a child before its dependency | Always enable in the classifier's `order` — Einstein GenAI → Studio → parent → child template(s) |
+| Attempting to enable a toggle whose *current* re-checked `enableBlockedReasons` is non-empty | Never — report the reasons instead of POSTing; the write would fail |
+| Trusting the Phase-2 `blocked`/`pending` snapshot for the whole Phase-4 loop | Re-read + reclassify immediately before each toggle — a child blocked only because an earlier dependency was off becomes enable-able the instant that dependency's `/enable` succeeds |
+| Reporting `ALL-ENABLED`/`SUCCESS` because `pending` is empty | Also check `unconfirmed` — a missing/unrecognized feature status is neither ENABLED nor NOT_ENABLED |
+| Re-deriving the per-toggle or final aggregate verdict in prose | Use `record-enable-result.mjs` (per toggle) and `classify-final-report.mjs` (final) — deterministic scripts, not model judgment (authoring standard A9) |
+| Skipping the confirm-to-write checkpoint on a hand-off from validate | Never — a NOT-READY report names what is off, it is not user confirmation to write |
+| `updateOrgPref` → 500 `Invalid prefName` for an agent pref | Wrong write path — IPCManagement `updateOrgPref` is for IPC Management (Incident/Problem/Change) prefs only. Use `feature/{apiName}/enable` |
+| Tempted to token+curl for "just a POST write" | Never — `sf api request rest` handles auth for `/services/data/...` paths |

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/scripts/classify-enable-plan.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// Deterministic enable-plan classifier for Agentforce for IT Service.
+//
+// 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), computes a dependency-ordered enable plan and (on a
+// second call, after the enable loop) the final per-feature verdict. This is
+// the deterministic decision table that MUST NOT be interpreted by the model
+// in prose (authoring standard A9) — same contract as the sibling
+// service-itsm-agentic-setup-agentforce-studio-validate skill's
+// classify-readiness.mjs, extended with enable ordering.
+//
+// Usage:
+//   node classify-enable-plan.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 or be empty on a non-zero exit.
+//
+// <exitStatus> is the OPTIONAL numeric exit code of the `sf` command ($? in
+// the shell) — distinguishes a confirmed 404 ("gate not wired" ->
+// CANNOT-CONFIRM) from an auth/permission/transport failure (-> ERROR).
+//
+// <agentType> is one of: fulfiller | employee. Selects which path-specific
+// template toggle is required in addition to the three shared toggles.
+//
+// Emits a single JSON object to stdout:
+//   { agentType, readState,
+//     features: { <apiName>: { status, signal, enableBlockedReasons } },
+//     order: [<apiName>...],        // dependency-first order for the REQUIRED set
+//     alreadyEnabled: [<apiName>...],
+//     pending: [<apiName>...],      // NOT_ENABLED, in dependency order — the enable plan
+//     blocked: [<apiName>...],      // NOT_ENABLED with non-empty enableBlockedReasons
+//     unconfirmed: [<apiName>...],  // missing from the response or an unexpected status
+//     verdict, reasons: [...], rawError }
+// where verdict is ALL-ENABLED | NEEDS-ENABLE | CANNOT-CONFIRM | ERROR.
+// Call this script BEFORE enabling (verdict=NEEDS-ENABLE -> drive the confirm
+// list + enable loop from `pending`, in `order`) and AGAIN AFTER the enable
+// loop on a fresh read (verdict=ALL-ENABLED -> success; anything left in
+// `blocked` -> report enableBlockedReasons verbatim as FAILED for that toggle;
+// anything in `unconfirmed` -> report CANNOT-CONFIRM for that toggle rather
+// than assuming success — a required feature can be missing from the
+// response or carry a status this classifier doesn't recognize, and an empty
+// `pending` in that case does NOT mean every required toggle is ENABLED).
+// Exit code is always 0 on a usable agentType; the verdict is in the payload.
+
+import { readFileSync } from 'node:fs';
+
+// Real Salesforce Go featureApiNames behind the "Agentforce for IT Service"
+// setup page toggles — same apiNames the sibling validate skill classifies.
+const EINSTEIN = 'sales-cloud-einstein-generative-ai';      // base layer (no deps)
+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"
+
+// Dependency-first order per path: Einstein GenAI -> Studio -> parent umbrella -> child template(s).
+const ORDER = {
+  fulfiller: [EINSTEIN, STUDIO, PARENT, FULFILLER],
+  employee: [EINSTEIN, STUDIO, PARENT, REQUESTOR, SPECIALIZED],
+};
+
+const LABEL = {
+  [EINSTEIN]: 'Einstein Generative AI',
+  [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 readJson(path) {
+  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) {
+  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) {
+  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);
+}
+
+function readFeatureStatus(res, exitStatus) {
+  if (!res.ok) {
+    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: [], reason: `${label} (${apiName}) — no status returned.` };
+  }
+  const { status, enableBlockedReasons } = statusMap.get(apiName);
+  if (status === 'ENABLED') {
+    return { status, signal: 'PASS', enableBlockedReasons: [], reason: `${label} (${apiName}) → ENABLED.` };
+  }
+  if (status === 'NOT_ENABLED') {
+    const blocked = enableBlockedReasons.length > 0;
+    return {
+      status, signal: 'FAIL', enableBlockedReasons,
+      reason: blocked
+        ? `${label} (${apiName}) → NOT_ENABLED, blocked: ${enableBlockedReasons.map((r) => (typeof r === 'string' ? r : (r?.message ?? JSON.stringify(r)))).join('; ')}.`
+        : `${label} (${apiName}) → NOT_ENABLED (ready to enable).`,
+    };
+  }
+  return { status, signal: 'CANNOT-CONFIRM', enableBlockedReasons: [], reason: `${label} (${apiName}) → unexpected status "${status}".` };
+}
+
+const [statusPath, rawAgentType, rawExit] = process.argv.slice(2);
+const agentType = String(rawAgentType ?? '').toLowerCase();
+if (!statusPath || !ORDER[agentType]) {
+  process.stderr.write('usage: node classify-enable-plan.mjs <features-status.json> <fulfiller|employee> [exitStatus]\n');
+  process.exit(2);
+}
+const exitStatus = rawExit === undefined ? NaN : Number(rawExit);
+const order = ORDER[agentType];
+
+const { readState, statusMap, rawError } = readFeatureStatus(readJson(statusPath), exitStatus);
+
+const features = {};
+const reasons = [];
+const alreadyEnabled = [];
+const pending = [];
+const blocked = [];
+
+if (readState === 'error') {
+  for (const apiName of order) {
+    features[apiName] = { status: 'UNKNOWN', signal: 'ERROR', enableBlockedReasons: [] };
+  }
+  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, order, alreadyEnabled, pending, blocked, unconfirmed: order.slice(), verdict: 'ERROR', reasons, rawError,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+if (readState === 'not-wired') {
+  for (const apiName of order) {
+    features[apiName] = { status: 'UNKNOWN', signal: 'CANNOT-CONFIRM', enableBlockedReasons: [] };
+  }
+  reasons.push('The feature-discovery surface returned a confirmed 404 — not wired on this org tier.');
+  process.stdout.write(JSON.stringify({
+    agentType, readState, features, order, alreadyEnabled, pending, blocked, unconfirmed: order.slice(), verdict: 'CANNOT-CONFIRM', reasons, rawError,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const unconfirmed = [];
+for (const apiName of order) {
+  const c = classifyFeature(apiName, statusMap);
+  features[apiName] = { status: c.status, signal: c.signal, enableBlockedReasons: c.enableBlockedReasons };
+  reasons.push(c.reason);
+  if (c.signal === 'PASS') alreadyEnabled.push(apiName);
+  if (c.signal === 'FAIL') {
+    pending.push(apiName);
+    if (c.enableBlockedReasons.length) blocked.push(apiName);
+  }
+  if (c.signal === 'CANNOT-CONFIRM') unconfirmed.push(apiName);
+}
+
+// A required feature missing from the response, or carrying an unexpected
+// status string, is neither confirmed ENABLED nor NOT_ENABLED — an empty
+// `pending` list in that case must NOT read as ALL-ENABLED.
+let verdict;
+if (pending.length > 0) verdict = 'NEEDS-ENABLE';
+else if (unconfirmed.length > 0) verdict = 'CANNOT-CONFIRM';
+else verdict = 'ALL-ENABLED';
+
+process.stdout.write(JSON.stringify({
+  agentType, readState, features, order, alreadyEnabled, pending, blocked, unconfirmed, verdict, reasons, rawError,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/scripts/classify-final-report.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Deterministic final-report aggregator for the enable flow (authoring
+// standard A9). Combines the Phase-2 (before-write) plan, the Phase-4
+// per-toggle enable results (from record-enable-result.mjs), and the Phase-5
+// (after-write) re-classification into one final per-feature verdict plus an
+// overall SUCCESS/PARTIAL/FAILED/CANNOT-CONFIRM/ERROR summary — a fixed
+// comparison/aggregation that must not be eyeballed by the model across a
+// variable-length feature list.
+//
+// Usage:
+//   node classify-final-report.mjs <before.json> <results.json|-> <after.json>
+//
+// <before.json>  — stdout of classify-enable-plan.mjs from Phase 2 (pre-write).
+// <results.json> — stdout of record-enable-result.mjs accumulated across
+//                  Phase 4 (one entry per toggle actually POSTed to /enable).
+//                  Pass "-" if Phase 4 never ran (Phase-2 verdict was already
+//                  ALL-ENABLED or CANNOT-CONFIRM/ERROR).
+// <after.json>   — stdout of classify-enable-plan.mjs from Phase 5 (post-write).
+//
+// Emits a single JSON object to stdout:
+//   { features: { <apiName>: { finalStatus, reason } }, order: [...], overall, reasons: [...] }
+// where finalStatus is ALREADY-ENABLED | ENABLED | FAILED | CANNOT-CONFIRM | ERROR
+// and overall is SUCCESS | PARTIAL | FAILED | CANNOT-CONFIRM | ERROR.
+// Exit code is always 0 on usable args.
+
+import { readFileSync } from 'node:fs';
+
+const [beforePath, resultsPath, afterPath] = process.argv.slice(2);
+if (!beforePath || !resultsPath || !afterPath) {
+  process.stderr.write('usage: node classify-final-report.mjs <before.json> <results.json|-> <after.json>\n');
+  process.exit(2);
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const before = readJson(beforePath);
+const after = readJson(afterPath);
+const results = resultsPath === '-' ? {} : (readJson(resultsPath) ?? {});
+
+if (!after || !Array.isArray(after.order)) {
+  process.stderr.write(`error: could not read/parse a usable "after" report from ${afterPath}\n`);
+  process.exit(3);
+}
+
+const alreadyEnabledBefore = new Set(Array.isArray(before?.alreadyEnabled) ? before.alreadyEnabled : []);
+const order = after.order;
+const features = {};
+const reasons = [];
+
+for (const apiName of order) {
+  const afterFeature = after.features?.[apiName];
+  const recorded = results?.[apiName];
+  const signal = afterFeature?.signal;
+
+  // The Phase-2 "already enabled" shortcut only applies if the Phase-5
+  // post-write read actually confirms it — a failed/unconfirmed re-read must
+  // never be silently overridden by the pre-write snapshot, or a broken
+  // verification read reports false SUCCESS for every already-enabled toggle.
+  if (alreadyEnabledBefore.has(apiName) && signal === 'PASS') {
+    features[apiName] = { finalStatus: 'ALREADY-ENABLED', reason: `${apiName} was already ENABLED before this run.` };
+    continue;
+  }
+
+  if (signal === 'PASS') {
+    features[apiName] = { finalStatus: 'ENABLED', reason: `${apiName} is ENABLED after this run.` };
+  } else if (signal === 'FAIL') {
+    const enableBlockedReasons = afterFeature?.enableBlockedReasons ?? [];
+    const recordedReason = recorded?.status === 'FAILED' ? recorded.reason : null;
+    features[apiName] = {
+      finalStatus: 'FAILED',
+      reason: recordedReason
+        ? `${apiName} — the /enable call failed: ${recordedReason}`
+        : enableBlockedReasons.length
+          ? `${apiName} — still blocked after the enable loop: ${JSON.stringify(enableBlockedReasons)}`
+          : `${apiName} — still NOT_ENABLED after the enable loop (not attempted or attempt did not persist).`,
+    };
+  } else if (signal === 'CANNOT-CONFIRM') {
+    features[apiName] = { finalStatus: 'CANNOT-CONFIRM', reason: `${apiName} — status could not be confirmed on the post-write read.` };
+  } else {
+    features[apiName] = { finalStatus: 'ERROR', reason: `${apiName} — the post-write read failed (${afterFeature?.reason ?? 'unknown error'}).` };
+  }
+  reasons.push(features[apiName].reason);
+}
+
+const statuses = Object.values(features).map((f) => f.finalStatus);
+const hasError = statuses.includes('ERROR');
+const hasFailed = statuses.includes('FAILED');
+const hasCannotConfirm = statuses.includes('CANNOT-CONFIRM');
+const hasEnabled = statuses.includes('ENABLED');
+
+let overall;
+if (hasError) overall = 'ERROR';
+else if (hasFailed || hasCannotConfirm) overall = hasEnabled ? 'PARTIAL' : (hasFailed ? 'FAILED' : 'CANNOT-CONFIRM');
+else overall = 'SUCCESS';
+
+process.stdout.write(JSON.stringify({ features, order, overall, reasons }, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/scripts/record-enable-result.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Deterministic per-toggle enable-result recorder (authoring standard A9).
+//
+// Classifying a single `/enable` POST response as ENABLED vs FAILED, and
+// accumulating that into a running results file across the enable loop, is a
+// fixed decision — it must not be left to the model to eyeball each response
+// in prose across a variable-length loop.
+//
+// Usage:
+//   node record-enable-result.mjs <response.json> <apiName> <results.json>
+//
+// <response.json> is a FILE PATH to the raw stdout captured from a single:
+//   sf api request rest ".../feature/<apiName>/enable" --method POST --body '{}' --target-org <alias>
+// <results.json> is a FILE PATH this script reads (if present) and rewrites —
+// an accumulator object keyed by apiName, so it can be called once per
+// toggle, immediately after each individual (still-visible) Bash enable call.
+//
+// Prints the updated accumulator object to stdout on success. Exit code is
+// always 0 on usable args — a failed enable is a recorded FAILED result, not
+// a script failure.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const [responsePath, apiName, resultsPath] = process.argv.slice(2);
+if (!responsePath || !apiName || !resultsPath) {
+  process.stderr.write('usage: node record-enable-result.mjs <response.json> <apiName> <results.json>\n');
+  process.exit(2);
+}
+
+function readJson(path) {
+  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) {
+  if (Array.isArray(data)) return data.filter((e) => e && (e.errorCode || e.message));
+  if (data && (data.errorCode || data.message)) return [data];
+  return [];
+}
+
+function errorSnippet(errs) {
+  return errs.map((e) => `${e.errorCode ?? 'ERROR'}: ${e.message ?? ''}`.trim()).join(' | ').slice(0, 500);
+}
+
+const res = readJson(responsePath);
+let entry;
+if (!res.ok) {
+  entry = { status: 'FAILED', reason: res.empty ? 'Enable call produced an empty body.' : 'Enable call produced a non-JSON body.' };
+} else {
+  const errs = asErrorArray(res.data);
+  if (errs.length) {
+    entry = { status: 'FAILED', reason: errorSnippet(errs) };
+  } else if (res.data?.success === true) {
+    entry = { status: 'ENABLED', reason: null };
+  } else {
+    entry = { status: 'FAILED', reason: `Unexpected response shape (no success:true, no error body): ${JSON.stringify(res.data).slice(0, 500)}` };
+  }
+}
+
+let results = {};
+if (existsSync(resultsPath)) {
+  const existing = readJson(resultsPath);
+  if (existing.ok && existing.data && typeof existing.data === 'object') results = existing.data;
+}
+results[apiName] = entry;
+
+writeFileSync(resultsPath, JSON.stringify(results, null, 2), 'utf8');
+process.stdout.write(JSON.stringify(results, null, 2) + '\n');