@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-command-center-analyze/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: service-omni-command-center-analyze
+description: "Use to analyze whether an org should use Command Center for Service V2 or classic Omni Supervisor and recommend the next action without making changes. Triggers: detect Command Center V2 versus classic, check supervisor readiness, choose a supervisor experience, diagnose Command Center availability, assess Omni Supervisor setup. Do not use to enable V2, assign permissions, or deploy configuration."
+allowed-tools: Bash Read Grep Glob
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-channel-setup-coordinate"
+    - "service-omni-supervisor-config-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-command-center-analyze
+
+Decide, **without changing anything**, which supervisor experience an org should use and what to do next. Command Center for Service V2 is gated on three independent dimensions — org **capability** (release gater), the **`CommandCenterForServiceV2` org preference** (whose ON-flip seeds the `CommandCenterForServiceV2_L` FlexiPage and registers the V2 tab), and the per-supervisor **`CommandCenterForServiceUser`** permission. A single boolean cannot express that, so this skill returns an explicit **state** plus the recommended follow-up skill (e.g. `service-omni-supervisor-config-deploy` for the classic path). It is the entry point of the Command Center flow — `service-omni-channel-setup-coordinate` runs it first — and is safe to run on any org, including production, because it only reads.
+
+## Inputs
+
+```bash
+bash scripts/analyze.sh <org-alias> [supervisor_username_or_id]
+```
+
+- `org-alias` (required).
+- `supervisor_username_or_id` (optional). A Username (`…@…`) or 15/18-char User Id (`005…`). When given, the per-user `CommandCenterForServiceUser` permission is evaluated; when omitted, the permission dimension is reported as not-checked and readiness is org-level only.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
+- **Read-only** — no `safe_to_write` guard is needed; the skill issues only SOQL/Tooling queries.
+
+## Run
+
+`analyze.sh` gathers observable signals and maps them to a state:
+
+| Signal | Source | Meaning |
+|---|---|---|
+| V2 capability | `SELECT Id FROM PermissionSet WHERE PermissionsCommandCenterForServiceUser = true` probe | If the user-permission column does not exist on the org schema, V2 is not available. |
+| Seeded FlexiPage | Tooling: `FlexiPage` where `DeveloperName='CommandCenterForServiceV2_L'` | Present ⇒ the org preference was enabled and the page was seeded. |
+| V2 tab | `TabDefinition` (best-effort) | Cross-checks the seed; a seed/tab mismatch indicates a partial provision. |
+| Supervisor permission | `PermissionSetAssignment` joined on `PermissionSet.PermissionsCommandCenterForServiceUser` | Whether the named supervisor can use V2. |
+| Legacy config | Tooling: `OmniSupervisorConfig` count | Informational for the classic path. |
+
+## Behavior
+
+**States and recommended next action:**
+
+| State | Meaning | Recommended skill |
+|---|---|---|
+| `v2_ready` | Capability + seed present (and supervisor has permission, if checked) | verify only (coordinator proceeds to V2 verification) |
+| `v2_permission_missing` | V2 enabled but the named supervisor lacks `CommandCenterForServiceUser` | Manual — assign `CommandCenterForServiceUser` (headless-capable via PermissionSet; packaging pending) |
+| `v2_seed_incomplete` | Capability present but the FlexiPage/tab provisioning is inconsistent | Manual — re-check in Setup → Omni-Channel → Supervisor Settings (no supported public write API) |
+| `v2_available_not_enabled` | Org supports V2 but the preference is off | Manual — enable in Setup → Omni-Channel → Supervisor Settings (no supported Metadata/Tooling write API) |
+| `legacy_selected` | V2 capability absent | `service-omni-supervisor-config-deploy` |
+| `ambiguous` | A required signal could not be read through a supported API | none — **blocks**, do not guess |
+
+`ambiguous` is the only state that exits non-zero: the review's rule is to block rather than infer when state cannot be proven read-only. All other states exit 0 with `status:"detected"`.
+
+## Output contract
+
+A single JSON object: `status` (`detected` | `blocked`), `state` (one of the six above), `recommended_action`, `recommended_skill`, `signals` (`v2_capability`, `seed_flexipage_present`, `v2_tab_present`, `supervisor{identifier,checked,has_command_center_permission}`, `legacy_omnisupervisorconfig_count`), `manual_actions`, `blocking_issue`.
+
+## Limitations
+
+- The `CommandCenterForServiceV2` org preference has no supported public read; its state is **inferred** from the seeded FlexiPage (the platform seeds on the ON-flip). This is called out in `signals` and is why a bare capability-without-seed reads as `v2_available_not_enabled`.
+- The release gater cannot be read directly; capability is inferred from the presence of the user-permission column on the org schema.
+- Tab detection is best-effort; when the tab query cannot run, `v2_tab_present` is `"unknown"` and state is derived from the remaining signals.
+- Read-only: it never enables V2, seeds pages, assigns permissions, or deploys config.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | The three-dimensional V2 gate, why each signal is a proxy, and the exact queries used |

package/skills/service-omni-command-center-analyze/references/api-notes.md

@@ -0,0 +1,54 @@
+# API notes — service-omni-command-center-analyze
+
+## The three-dimensional V2 gate
+
+Command Center for Service V2 renders only when **all** of the following hold, per the runtime
+access check on the seeded page (`OmniChannel.userCanUseCommandCenterForServiceV2`):
+
+```text
+orgHasCommandCenterForServiceV2Enabled
+    = release Gater
+      AND CommandCenterForServiceV2 org preference
+      AND NOT StandardOmniEOLExtension
+AND UserPermissions.CommandCenterForServiceUser   (per user)
+```
+
+A single boolean cannot capture this, so the detector reports an explicit **state** across the
+capability, preference/seed, and per-user permission dimensions.
+
+## Why the preference is read via a proxy
+
+The `CommandCenterForServiceV2` org preference is flipped only by an **internal** Setup
+`SettingMutator` (`OmniChannelSettings.OrgPreferences.commandCenterForServiceV2`) and is **not**
+exposed by the v66 Metadata API `OmniChannelSettings` (nor any other proven public write/read
+surface). Its ON-flip, however, has an observable side effect: the platform seeds the
+`CommandCenterForServiceV2_L` FlexiPage into a DB row and registers the V2 tab (idempotently). The
+detector therefore treats the **seeded FlexiPage** as the proxy for "preference is ON":
+
+- capability present + seed present ⇒ preference was enabled.
+- capability present + seed absent ⇒ preference is off (`v2_available_not_enabled`).
+
+This proxy is called out in the output; the detector does not claim to read the preference directly.
+
+## Signals and queries
+
+| Signal | Query | Notes |
+|---|---|---|
+| V2 capability | `SELECT Id FROM PermissionSet WHERE PermissionsCommandCenterForServiceUser = true LIMIT 1` | A `No such column`/`INVALID_FIELD` error ⇒ capability **absent** (org schema has no such user permission). Success ⇒ capability present. Any other error ⇒ `unknown` ⇒ `ambiguous`. |
+| Seeded FlexiPage | Tooling: `SELECT Id FROM FlexiPage WHERE DeveloperName='CommandCenterForServiceV2_L'` | Presence ⇒ preference enabled + page seeded. Query error ⇒ `unknown` ⇒ `ambiguous`. |
+| V2 tab | `SELECT Name FROM TabDefinition WHERE Name='standard-commandcenterforservicev2'` | Best-effort cross-check. Error ⇒ `"unknown"`; state falls back to capability + seed. |
+| Supervisor permission | `SELECT Id FROM PermissionSetAssignment WHERE AssigneeId='…' AND PermissionSet.PermissionsCommandCenterForServiceUser = true` | Catches both permission-set and profile-granted permission (profiles surface as owned permission sets). Only run when a supervisor is supplied. |
+| Legacy config | Tooling: `SELECT Id FROM OmniSupervisorConfig` | Informational count for the classic path. |
+
+## Seed/tab consistency
+
+The enable hook performs **two** side effects — tab registration and FlexiPage seed. A partial
+failure can leave exactly one present. When both signals are known and disagree, the detector
+returns `v2_seed_incomplete` (re-provision or apply the manual Setup step) rather than a misleading
+`v2_ready`.
+
+## Why `ambiguous` blocks
+
+The review's rule is explicit: when a required signal cannot be read through a supported API, **block
+and do not guess**. `ambiguous` is the only state that exits non-zero, so a coordinator will not
+proceed to enable or configure on unproven state.

package/skills/service-omni-command-center-analyze/scripts/analyze.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# analyze.sh - read-only analysis of the Omni supervisor experience (Command Center V2 vs classic) + recommended next action; SOQL/Tooling reads only, no writes. Args, states, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Usage: bash analyze.sh <org-alias> [supervisor_username_or_id]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+SUP="${2:-}"
+
+AUTH_CHECK=$(sf org display --target-org "$ORG" --json 2>/dev/null || true)
+if [ -z "$AUTH_CHECK" ]; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated. Run: sf org login web -a $ORG -r <my-domain-url>\"}" >&2
+  exit 1
+fi
+
+# Best-effort query helper: echoes the raw JSON; caller inspects .status and payload.
+soql() { sf data query --target-org "$ORG" --json --query "$1" 2>/dev/null || true; }
+soql_tooling() { sf data query --target-org "$ORG" --use-tooling-api --json --query "$1" 2>/dev/null || true; }
+
+json_status() { echo "$1" | jq -r '.status // 1' 2>/dev/null || echo 1; }
+json_total()  { echo "$1" | jq -r '.result.totalSize // (.result.records | length) // 0' 2>/dev/null || echo 0; }
+
+# Signal 1 - V2 capability (does the user-permission column exist on the org schema?)
+CAP_JSON=$(soql "SELECT Id FROM PermissionSet WHERE PermissionsCommandCenterForServiceUser = true LIMIT 1")
+if [ "$(json_status "$CAP_JSON")" = "0" ]; then
+  CAPABILITY=true
+elif echo "$CAP_JSON" | grep -qiE "No such column|INVALID_FIELD|PermissionsCommandCenterForServiceUser"; then
+  CAPABILITY=false
+else
+  CAPABILITY=unknown
+fi
+
+# Signal 2 - Seeded FlexiPage (proxy for the CommandCenterForServiceV2 preference being ON)
+SEED_PRESENT=unknown
+if [ "$CAPABILITY" = "true" ]; then
+  SEED_JSON=$(soql_tooling "SELECT Id FROM FlexiPage WHERE DeveloperName='CommandCenterForServiceV2_L'")
+  if [ "$(json_status "$SEED_JSON")" = "0" ]; then
+    if [ "$(json_total "$SEED_JSON")" -gt 0 ]; then SEED_PRESENT=true; else SEED_PRESENT=false; fi
+  else
+    SEED_PRESENT=unknown
+  fi
+fi
+
+# Signal 3 - V2 tab (best-effort cross-check)
+TAB_PRESENT=unknown
+if [ "$CAPABILITY" = "true" ]; then
+  TAB_JSON=$(soql "SELECT Name FROM TabDefinition WHERE Name='standard-commandcenterforservicev2' LIMIT 1")
+  if [ "$(json_status "$TAB_JSON")" = "0" ]; then
+    if [ "$(json_total "$TAB_JSON")" -gt 0 ]; then TAB_PRESENT=true; else TAB_PRESENT=false; fi
+  else
+    TAB_PRESENT=unknown
+  fi
+fi
+
+# Signal 4 - Legacy OmniSupervisorConfig count (informational)
+LEG_JSON=$(soql_tooling "SELECT Id FROM OmniSupervisorConfig")
+if [ "$(json_status "$LEG_JSON")" = "0" ]; then LEG_COUNT=$(json_total "$LEG_JSON"); else LEG_COUNT="null"; fi
+
+# Signal 5 - Supervisor permission (only when a supervisor is supplied)
+SUP_CHECKED=false
+SUP_HAS_PERM=unknown
+SUP_ID=""
+SUP_IDENT="null"
+SUP_CHECK_ERROR=""
+if [ -n "$SUP" ]; then
+  SUP_IDENT="$SUP"
+  if [[ "$SUP" =~ ^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ ]]; then
+    SUP_QUERY="SELECT Id FROM User WHERE Id='$SUP' LIMIT 1"
+  elif [[ "$SUP" =~ ^[^,\'\"[:space:]]+@[^,\'\"[:space:]]+$ ]]; then
+    SUP_QUERY="SELECT Id FROM User WHERE Username='$SUP' LIMIT 1"
+  else
+    echo "{\"error\":\"supervisor_username_or_id '$SUP' is neither a Username (...@...) nor a 15/18-char User Id (005...).\"}" >&2
+    exit 1
+  fi
+
+  if [ "$CAPABILITY" = "true" ]; then
+    UID_JSON=$(soql "$SUP_QUERY")
+    if [ "$(json_status "$UID_JSON")" != "0" ]; then
+      SUP_CHECK_ERROR="Supplied supervisor '$SUP_IDENT' could not be read through a supported API. Not guessing; verify User read access and retry."
+    elif [ "$(json_total "$UID_JSON")" -ne 1 ]; then
+      SUP_CHECK_ERROR="Supplied supervisor '$SUP_IDENT' was not found. Verify the username or User Id and retry."
+    else
+      SUP_ID=$(echo "$UID_JSON" | jq -r '.result.records[0].Id // ""' 2>/dev/null)
+      if [ -z "$SUP_ID" ]; then
+        SUP_CHECK_ERROR="Supplied supervisor '$SUP_IDENT' lookup returned no User Id. Not guessing; verify User read access and retry."
+      fi
+    fi
+
+    if [ -z "$SUP_CHECK_ERROR" ]; then
+      PERM_JSON=$(soql "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId='$SUP_ID' AND PermissionSet.PermissionsCommandCenterForServiceUser = true LIMIT 1")
+      if [ "$(json_status "$PERM_JSON")" = "0" ]; then
+        SUP_CHECKED=true
+        if [ "$(json_total "$PERM_JSON")" -gt 0 ]; then SUP_HAS_PERM=true; else SUP_HAS_PERM=false; fi
+      else
+        SUP_CHECK_ERROR="CommandCenterForServiceUser permission could not be read for supplied supervisor '$SUP_IDENT'. Not guessing; verify PermissionSetAssignment read access and retry."
+      fi
+    fi
+  fi
+fi
+
+# Derive state
+STATE=""; REC_ACTION=""; REC_SKILL="null"; STATUS="detected"; BLOCKING="null"
+
+if [ "$CAPABILITY" = "unknown" ]; then
+  STATE="ambiguous"; STATUS="blocked"
+  REC_ACTION="V2 capability could not be read through a supported API. Not guessing; re-run with an authenticated org that permits these read queries."
+  BLOCKING="\"$REC_ACTION\""
+elif [ "$CAPABILITY" = "false" ]; then
+  STATE="legacy_selected"
+  REC_ACTION="Command Center for Service V2 capability is not present on this org; configure the classic Omni Supervisor experience."
+  REC_SKILL="\"service-omni-supervisor-config-deploy\""
+elif [ -n "$SUP_CHECK_ERROR" ]; then
+  STATE="ambiguous"; STATUS="blocked"
+  REC_ACTION="$SUP_CHECK_ERROR"
+  BLOCKING="\"$REC_ACTION\""
+elif [ "$SEED_PRESENT" = "unknown" ]; then
+  STATE="ambiguous"; STATUS="blocked"
+  REC_ACTION="V2 capability is present but the seeded FlexiPage could not be read through a supported API. Not guessing; re-run with an org that permits the Tooling query."
+  BLOCKING="\"$REC_ACTION\""
+else
+  # capability true, seed known (true/false)
+  if [ "$SEED_PRESENT" = "true" ] && { [ "$TAB_PRESENT" = "true" ] || [ "$TAB_PRESENT" = "unknown" ]; }; then
+    if [ "$SUP_CHECKED" = "true" ] && [ "$SUP_HAS_PERM" = "false" ]; then
+      STATE="v2_permission_missing"
+      REC_ACTION="V2 is enabled and seeded, but supervisor '$SUP_IDENT' lacks the CommandCenterForServiceUser permission. Assign it via a PermissionSet (headless-capable; see manual_actions for packaging)."
+      REC_SKILL="null"
+    else
+      STATE="v2_ready"
+      if [ "$SUP_CHECKED" = "true" ]; then
+        REC_ACTION="V2 is enabled and seeded and supervisor '$SUP_IDENT' has the CommandCenterForServiceUser permission. Verify the seeded page and tab."
+      else
+        REC_ACTION="V2 is enabled and seeded at the org level. Supply a supervisor to verify per-user permission; otherwise verify the seeded page and tab."
+      fi
+    fi
+  elif { [ "$SEED_PRESENT" = "true" ] && [ "$TAB_PRESENT" = "false" ]; } || { [ "$SEED_PRESENT" = "false" ] && [ "$TAB_PRESENT" = "true" ]; }; then
+    STATE="v2_seed_incomplete"
+    REC_ACTION="V2 capability is present but page/tab provisioning is inconsistent (seed_flexipage_present=$SEED_PRESENT, v2_tab_present=$TAB_PRESENT). Re-check in Setup → Omni-Channel → Supervisor Settings; there is no supported public write API to re-provision headlessly."
+    REC_SKILL="null"
+  else
+    STATE="v2_available_not_enabled"
+    REC_ACTION="Org supports V2 but the CommandCenterForServiceV2 preference is off (no seeded page). Enable it manually in Setup → Omni-Channel → Supervisor Settings; there is no supported Metadata/Tooling write API for this preference."
+    REC_SKILL="null"
+  fi
+fi
+
+# manual_actions: for permission_missing and ambiguous surface a concrete pointer.
+MANUAL_ACTIONS='[]'
+case "$STATE" in
+  v2_permission_missing)
+    MANUAL_ACTIONS=$(jq -n '[{id:"ASSIGN_V2_PERM",title:"Assign the CommandCenterForServiceUser permission to the supervisor (headless-capable via PermissionSet; packaging pending)",target_skill:null}]') ;;
+  v2_available_not_enabled|v2_seed_incomplete)
+    MANUAL_ACTIONS=$(jq -n '[{id:"ENABLE_V2_PREF",title:"Enable Command Center for Service V2 in Setup → Omni-Channel → Supervisor Settings (no supported public write API; manual)",target_skill:null}]') ;;
+esac
+
+# Emit
+LEG_JQ="$LEG_COUNT"; [ "$LEG_COUNT" = "null" ] && LEG_JQ=null
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg state "$STATE" \
+  --arg rec_action "$REC_ACTION" \
+  --argjson rec_skill "$REC_SKILL" \
+  --arg cap "$CAPABILITY" \
+  --arg seed "$SEED_PRESENT" \
+  --arg tab "$TAB_PRESENT" \
+  --argjson sup_ident "$( [ "$SUP_IDENT" = "null" ] && echo null || jq -n --arg s "$SUP_IDENT" '$s' )" \
+  --argjson sup_checked "$SUP_CHECKED" \
+  --arg sup_perm "$SUP_HAS_PERM" \
+  --argjson leg "$LEG_JQ" \
+  --argjson manual "$MANUAL_ACTIONS" \
+  --argjson blocking "$BLOCKING" \
+  '{
+    skill: "service-omni-command-center-analyze",
+    status: $status,
+    state: $state,
+    recommended_action: $rec_action,
+    recommended_skill: $rec_skill,
+    signals: {
+      v2_capability: $cap,
+      seed_flexipage_present: $seed,
+      v2_tab_present: $tab,
+      supervisor: {
+        identifier: $sup_ident,
+        checked: $sup_checked,
+        has_command_center_permission: (if $sup_checked then ($sup_perm=="true") else $sup_perm end)
+      },
+      legacy_omnisupervisorconfig_count: $leg
+    },
+    manual_actions: $manual,
+    blocking_issue: $blocking
+  }'
+
+[ "$STATUS" = "blocked" ] && exit 1
+exit 0

package/skills/service-omni-command-center-analyze/scripts/tests/_bootstrap.py

@@ -0,0 +1,115 @@
+"""Shared paths + fake-`sf` harness for the command-center-analyze contract suite.
+
+Read-only skill: the fake serves SOQL/Tooling query responses only. Org-free and network-free.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SKILL_DIR = "service-omni-command-center-analyze"
+SCRIPT = f"{SKILL_DIR}/scripts/analyze.sh"
+
+# Tunables (env):
+#   FAKE_CAP   = true|false|unknown  (V2 capability probe on PermissionSet)
+#   FAKE_SEED  = true|false|unknown  (seeded FlexiPage, tooling)
+#   FAKE_TAB   = true|false|unknown  (V2 TabDefinition)
+#   FAKE_LEG   = integer             (OmniSupervisorConfig count; default 0)
+#   FAKE_SUP_LOOKUP = true|missing|unknown  (supervisor User lookup)
+#   FAKE_SUP_PERM = true|false|unknown      (supervisor permission query)
+_FAKE_SF = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+CAP="${FAKE_CAP:-true}"
+SEED="${FAKE_SEED:-false}"
+TAB="${FAKE_TAB:-false}"
+LEG="${FAKE_LEG:-0}"
+SUP_PERM="${FAKE_SUP_PERM:-false}"
+SUP_LOOKUP="${FAKE_SUP_LOOKUP:-true}"
+emit_ok() { echo "{\"status\":0,\"result\":{\"records\":$1,\"totalSize\":$2}}"; }
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q -- "--use-tooling-api"; then
+      if printf '%s' "$args" | grep -q "FROM FlexiPage"; then
+        case "$SEED" in
+          true)  emit_ok '[{"Id":"0M0xx0000000001AAA"}]' 1;;
+          false) emit_ok '[]' 0;;
+          *)     echo '{"status":1,"name":"UNEXPECTED","message":"tooling read failed"}';;
+        esac
+      elif printf '%s' "$args" | grep -q "FROM OmniSupervisorConfig"; then
+        if [ "$LEG" -gt 0 ] 2>/dev/null; then emit_ok '[{"Id":"0L0xx0000000001AAA"}]' "$LEG"; else emit_ok '[]' 0; fi
+      else
+        emit_ok '[]' 0
+      fi
+      exit 0
+    fi
+    # non-tooling SOQL
+    if printf '%s' "$args" | grep -q "FROM PermissionSetAssignment"; then
+      case "$SUP_PERM" in
+        true)    emit_ok '[{"Id":"0Paxx0000000001AAA"}]' 1;;
+        false)   emit_ok '[]' 0;;
+        *)       echo '{"status":1,"name":"UNEXPECTED","message":"permission read failed"}';;
+      esac
+    elif printf '%s' "$args" | grep -q "FROM PermissionSet"; then
+      case "$CAP" in
+        true)    emit_ok '[{"Id":"0PSxx0000000001AAA"}]' 1;;
+        false)   echo '{"status":1,"name":"INVALID_FIELD","message":"No such column '"'"'PermissionsCommandCenterForServiceUser'"'"' on entity PermissionSet"}';;
+        *)       echo '{"status":1,"name":"UNEXPECTED","message":"connection reset"}';;
+      esac
+    elif printf '%s' "$args" | grep -q "FROM TabDefinition"; then
+      case "$TAB" in
+        true)  emit_ok '[{"Name":"standard-commandcenterforservicev2"}]' 1;;
+        false) emit_ok '[]' 0;;
+        *)     echo '{"status":1,"name":"UNEXPECTED","message":"tab read failed"}';;
+      esac
+    elif printf '%s' "$args" | grep -q "FROM User"; then
+      case "$SUP_LOOKUP" in
+        true)    emit_ok '[{"Id":"0050000000000009AAA"}]' 1;;
+        missing) emit_ok '[]' 0;;
+        *)       echo '{"status":1,"name":"UNEXPECTED","message":"user read failed"}';;
+      esac
+    else
+      emit_ok '[]' 0
+    fi
+    exit 0;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+
+def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
+    env = dict(os.environ)
+    if scrub_sf:
+        kept = [d for d in env.get("PATH", "").split(os.pathsep)
+                if d and not os.path.exists(os.path.join(d, "sf"))]
+        env["PATH"] = os.pathsep.join(kept)
+    if path_prefix:
+        env["PATH"] = path_prefix + os.pathsep + env.get("PATH", "")
+    if extra_env:
+        env.update({k: str(v) for k, v in extra_env.items()})
+    proc = subprocess.run(
+        ["bash", str(SKILLS_ROOT / SCRIPT), *args],
+        capture_output=True, text=True, env=env, cwd=str(SKILLS_ROOT),
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+class FakeSf:
+    def __init__(self, body=_FAKE_SF):
+        self._body = body
+        self._tmp = None
+
+    def __enter__(self):
+        self._tmp = tempfile.mkdtemp(prefix="ccdetect-fake-sf-")
+        sf = Path(self._tmp) / "sf"
+        sf.write_text(self._body)
+        sf.chmod(0o755)
+        return self._tmp
+
+    def __exit__(self, *exc):
+        import shutil
+        if self._tmp:
+            shutil.rmtree(self._tmp, ignore_errors=True)

package/skills/service-omni-command-center-analyze/scripts/tests/test_command_center_analyze_contracts.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-command-center-analyze/scripts/analyze.sh (read-only state model)."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import FakeSf, _FAKE_SF, run  # noqa: E402
+
+
+def _last_json(out: str) -> dict:
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        if out[i] in "{[":
+            try:
+                cand, end = dec.raw_decode(out, i)
+                if isinstance(cand, dict):
+                    obj = cand
+                i = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        i += 1
+    assert obj is not None, f"no JSON object found in output:\n{out}"
+    return obj
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_args_rejected(self):
+        rc, out = run([], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_bad_supervisor_token_rejected(self):
+        with FakeSf(_FAKE_SF) as p:
+            rc, out = run(["org", "not-a-user-or-id"], path_prefix=p, extra_env={"FAKE_CAP": "true"})
+        self.assertEqual(rc, 1, out)
+        self.assertIn("neither a Username", out)
+
+
+class StateModelTests(unittest.TestCase):
+    def _detect(self, env, args=("org",)):
+        with FakeSf(_FAKE_SF) as p:
+            return run(list(args), path_prefix=p, extra_env=env)
+
+    def test_legacy_when_capability_absent(self):
+        rc, out = self._detect({"FAKE_CAP": "false"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "legacy_selected", out)
+        self.assertEqual(v["recommended_skill"], "service-omni-supervisor-config-deploy", out)
+        self.assertEqual(v["signals"]["v2_capability"], "false", out)
+
+    def test_ambiguous_when_capability_unknown_blocks(self):
+        rc, out = self._detect({"FAKE_CAP": "unknown"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "ambiguous", out)
+        self.assertEqual(v["status"], "blocked", out)
+
+    def test_ambiguous_when_seed_unreadable_blocks(self):
+        rc, out = self._detect({"FAKE_CAP": "true", "FAKE_SEED": "unknown"})
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "ambiguous", out)
+
+    def test_available_not_enabled_when_no_seed(self):
+        rc, out = self._detect({"FAKE_CAP": "true", "FAKE_SEED": "false", "FAKE_TAB": "false"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_available_not_enabled", out)
+        self.assertTrue(any(a["id"] == "ENABLE_V2_PREF" for a in v["manual_actions"]), out)
+
+    def test_ready_org_level_without_supervisor(self):
+        rc, out = self._detect({"FAKE_CAP": "true", "FAKE_SEED": "true", "FAKE_TAB": "true"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_ready", out)
+        self.assertFalse(v["signals"]["supervisor"]["checked"], out)
+
+    def test_ready_with_supervisor_having_permission(self):
+        rc, out = self._detect(
+            {"FAKE_CAP": "true", "FAKE_SEED": "true", "FAKE_TAB": "true", "FAKE_SUP_PERM": "true"},
+            args=("org", "sup@example.com"))
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_ready", out)
+        self.assertTrue(v["signals"]["supervisor"]["checked"], out)
+        self.assertTrue(v["signals"]["supervisor"]["has_command_center_permission"], out)
+
+    def test_permission_missing_when_supervisor_lacks_perm(self):
+        rc, out = self._detect(
+            {"FAKE_CAP": "true", "FAKE_SEED": "true", "FAKE_TAB": "true", "FAKE_SUP_PERM": "false"},
+            args=("org", "005000000000002AAA"))
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_permission_missing", out)
+        self.assertIsNone(v["recommended_skill"], out)
+        self.assertTrue(any(a["id"] == "ASSIGN_V2_PERM" for a in v["manual_actions"]), out)
+        self.assertFalse(v["signals"]["supervisor"]["has_command_center_permission"], out)
+
+    def test_missing_supplied_supervisor_blocks(self):
+        rc, out = self._detect(
+            {
+                "FAKE_CAP": "true",
+                "FAKE_SEED": "true",
+                "FAKE_TAB": "true",
+                "FAKE_SUP_LOOKUP": "missing",
+            },
+            args=("org", "sup@example.com"))
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "ambiguous", out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("was not found", v["blocking_issue"], out)
+        self.assertFalse(v["signals"]["supervisor"]["checked"], out)
+
+    def test_unreadable_supplied_supervisor_blocks(self):
+        rc, out = self._detect(
+            {
+                "FAKE_CAP": "true",
+                "FAKE_SEED": "true",
+                "FAKE_TAB": "true",
+                "FAKE_SUP_LOOKUP": "unknown",
+            },
+            args=("org", "005000000000002AAA"))
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "ambiguous", out)
+        self.assertIn("could not be read", v["blocking_issue"], out)
+
+    def test_unreadable_supervisor_permission_blocks(self):
+        rc, out = self._detect(
+            {
+                "FAKE_CAP": "true",
+                "FAKE_SEED": "true",
+                "FAKE_TAB": "true",
+                "FAKE_SUP_PERM": "unknown",
+            },
+            args=("org", "sup@example.com"))
+        self.assertEqual(rc, 1, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "ambiguous", out)
+        self.assertIn("permission could not be read", v["blocking_issue"], out)
+
+    def test_seed_incomplete_when_seed_without_tab(self):
+        rc, out = self._detect({"FAKE_CAP": "true", "FAKE_SEED": "true", "FAKE_TAB": "false"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_seed_incomplete", out)
+
+    def test_ready_when_tab_unknown(self):
+        rc, out = self._detect({"FAKE_CAP": "true", "FAKE_SEED": "true", "FAKE_TAB": "unknown"})
+        self.assertEqual(rc, 0, out)
+        v = _last_json(out)
+        self.assertEqual(v["state"], "v2_ready", out)
+        self.assertEqual(v["signals"]["v2_tab_present"], "unknown", out)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)