@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/service-agentforce-channel-configure/SKILL.md

@@ -8,6 +8,7 @@ metadata:
   minApiVersion: "67.0"
   relatedSkills:
     - "agentforce-generate"
+    - "service-agentforce-human-escalation-configure"
     - "service-digital-engagement-channel-configure"
     - "service-digital-engagement-deployment-configure"
     - "service-email-to-case-configure"
@@ -17,6 +18,9 @@ metadata:
       semver: ">=3.8"
     - tool: ["sf"]
       semver: ">=2.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
 ---
 
 # service-agentforce-channel-configure: Wire an Agentforce agent to a channel
@@ -32,14 +36,13 @@ This skill is generic — it works for any Agentforce agent, not just the Help A
 - Branch A (Enhanced Chat / Enhanced Messaging): deploying `sessionHandlerType=AgentforceServiceAgent` + `sessionHandlerQueue` on an existing MessagingChannel, then binding `SessionHandlerId` via Data API PATCH
 - Branch B (Voice): assumes the phone number and `PstnVoice` MessagingChannel already exist (provisioned by the caller, e.g. `service-helpagent-coordinate`), then creating an inbound RoutingFlow (`routingType: Copilot`) that routes to the agent with the queue as fallback
 - Branch C (Email-to-Case): inbound routing via direct case-owner assignment or an Omni-Channel RoutingFlow, plus deploying a `BotEmailDefinition` (Email Configuration) that links the agent to Service Email and binding it to the routing address
-- Optional outbound escalation: adding the appropriate `connection {type}:` block to the agent and republishing
+- Optional outbound escalation: delegating the verified agent-to-human handoff contract to `service-agentforce-human-escalation-configure`
 
 **Out of scope:**
 - Creating the agent — use `agentforce-generate` or `service-helpagent-coordinate`
 - Creating the MessagingChannel — use `service-digital-engagement-channel-configure`
 - Creating the Embedded Service Deployment — use `service-digital-engagement-deployment-configure`
 - Creating the Voice or Email-to-Case channel infrastructure
-- Outbound escalation RoutingFlow creation — surface the gap if one is needed and doesn't exist
 
 ---
 
@@ -56,6 +59,21 @@ This skill is generic — it works for any Agentforce agent, not just the Help A
 
 Steps are sequential. Read `references/channel-types.md` first to confirm the routing branch before proceeding.
 
+### Phase 0 — Production write-guard (mandatory, before any write)
+
+This skill performs **metadata/data writes** (MessagingChannel edits, RoutingFlow deploys, agent republish). Before any write, classify the target org and refuse real production:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1"
+```
+
+- `safe_to_write` is **true** only when `IsSandbox=true`, OR `TrialExpirationDate` is non-null (trial/CDO), OR `OrganizationType` is `Developer Edition` / `Base Edition`.
+- If `safe_to_write` is false, **stop** — state plainly that this is a real production customer org and escalation/channel wiring will not be applied. Do not proceed to any write phase.
+- If `safe_to_write` is true, show the write plan (which MessagingChannel/RoutingFlow/agent will change) and get explicit user confirmation of the target org before continuing.
+
+Never bypass this gate — a mistaken production write here reroutes live customer traffic.
+
 ### Phase 1 — Verify agent and resolve queue
 
 1. **Confirm the agent exists and has an active version:**
@@ -70,6 +88,8 @@ Steps are sequential. Read `references/channel-types.md` first to confirm the ro
    ```
    Stop with a clear message if the definition is not found or no version has `Status = Active`.
 
+   > **Branch A caveat — an Active BotVersion is necessary but NOT sufficient to bind as `sessionHandlerAsa`.** The platform only accepts an agent that is provisioned/connected as a *deployable Agentforce Service Agent* (typically an `ExternalCopilot`). Binding an agent that is merely Active fails the Phase 2 deploy with `Only active Agentforce Service Agents are supported for a Messaging Channel`. Confirm bindability read-only before writing: if any MessagingChannel on the org already uses `sessionHandlerType=AgentforceServiceAgent`, retrieve it (`sf project retrieve start --metadata "MessagingChannel:{EXISTING}" --target-org $ORG`) and read its `<sessionHandlerAsa>` — that set is the org's provably-bindable ASAs. If the chosen agent is not a provisioned ASA and no bindable ASA exists, stop and report `BLOCKED`: *provide an agent that is provisioned as an Agentforce Service Agent.*
+
 2. **Resolve the fallback queue and routing configuration** — follow `references/queue-resolution.md`:
    - Determine SobjectType from the channel type (see `references/channel-types.md`)
    - Query existing compatible queues; present via `AskUserQuestion` or create new
@@ -94,7 +114,7 @@ Full detection queries, exact `AskUserQuestion` block, deferred-flow rules per b
 
 No RoutingFlow required. Deploy the MessagingChannel with `sessionHandlerType` + `sessionHandlerQueue` only, then bind the bot via a Data API PATCH. `sessionHandlerAsa` is not accepted by the Metadata API at v67 — the deploy silently drops it and `SessionHandlerId` stays null unless you run the PATCH. The bot must be Active before the PATCH ("Only active Agentforce Service Agents are supported" otherwise).
 
-All five steps below are mandatory and must run in order — do **not** skip the retrieve/edit/deploy and jump straight to the PATCH. Run the retrieve and edit in the **current working directory** (a real SFDX project), so the edited `.messagingChannel-meta.xml` is saved into the project's `force-app` tree — not a throwaway temp dir. Steps 1–3 record the routing change in source; steps 4–5 apply the binding the Metadata API can't.
+Run all five steps in order. Perform retrieve and edit in the **current SFDX project**, so the deploy reads the edited `.messagingChannel-meta.xml` from `force-app`; do not use a temporary directory.
 
 1. **Retrieve the current MessagingChannel metadata** into the working-directory project:
    ```bash
@@ -116,6 +136,7 @@ All five steps below are mandatory and must run in order — do **not** skip the
      --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
      --target-org $ORG
    ```
+   If the deploy fails with `Only active Agentforce Service Agents are supported for a Messaging Channel`, the agent is not a bindable ASA on this org (see the Phase 1 caveat). Do **not** retry with the same agent — the channel is left unchanged (the failed deploy is atomic). Report `BLOCKED` with the remediation: bind an agent already provisioned as an Agentforce Service Agent, or provision this one, then re-run.
 
 4. **Bind the bot via Data API PATCH:**
    ```bash
@@ -148,11 +169,11 @@ No agent file changes — no republish needed. Proceed to Phase 3 (optional).
 
 #### Branch B — Voice
 
-Wires a `PstnVoice` MessagingChannel to the agent via an inbound `Copilot`-type RoutingFlow with the queue as fallback. Distinct from Branch A: no `sessionHandlerAsa`; the channel is bound to the flow (`sessionHandlerType=Flow`), and the agent needs a `modality voice:` block appended before republish.
+Wire the `PstnVoice` MessagingChannel through an inbound `Copilot` RoutingFlow, with the queue as fallback, and add the required `modality voice:` block before republishing the agent.
 
 Follow `references/channel-branch-voice.md` end to end. Highlights:
 
-- Step 0 — reuse an existing `PstnVoice` MessagingChannel or have `service-helpagent-coordinate` provision one first (its `references/channel-voice.md`); abort if the org uses a partner telephony provider (see `references/channel-types.md`).
+- Step 0 — reuse an existing `PstnVoice` MessagingChannel or have `service-helpagent-coordinate` provision one first using that skill's Voice channel reference; abort if the org uses a partner telephony provider (see `references/channel-types.md`).
 - Steps 1–3 — write and deploy the inbound RoutingFlow using the template in `references/routing-flow.md`, verifying `ActiveVersionId` is non-null.
 - Step 4 — deploy a `MessagingChannel` metadata file for `{CHANNEL_DEVELOPER_NAME}` with `sessionHandlerType=Flow`, `sessionHandlerFlow={FLOW_DEVELOPER_NAME}`, `sessionHandlerQueue={QUEUE_DEVELOPER_NAME}`. Without this the flow is never executed and calls hang up. Verify `SessionHandlerId` starts with `300`.
 - Step 5 — append the platform-default `modality voice:` block (voice_id `UgBBYS2sOqTuMpoF3BR0`, "Mark", en_US) to the `.agent` file if missing; do not ask the user. Republish per `references/agent-wiring.md`.
@@ -163,7 +184,7 @@ Proceed to Phase 3 (optional).
 
 #### Branch C — Email-to-Case
 
-Inbound routing to the agent via direct case-owner assignment or an Omni-Channel `Copilot` RoutingFlow — user chooses in Step 2. Additionally requires the `connection service_email:` **surface** block and a mandatory BotEmailDefinition step (Email Configuration). It gates on API v68.0+ up front (see `references/channel-branch-email.md`).
+Let the user choose direct case-owner assignment or an Omni-Channel `Copilot` RoutingFlow. This branch requires API v68.0+, a `connection service_email:` surface, and a BotEmailDefinition.
 
 Follow `references/channel-branch-email.md` end to end. Load-bearing gotchas (full walkthrough in that file):
 
@@ -178,29 +199,15 @@ Branch C is complete once the routing-address binding is verified. Proceed to Ph
 
 ### Phase 3 — Outbound escalation (optional)
 
+> **Authoritative owner:** full agent-to-human escalation is owned by **`service-agentforce-human-escalation-configure`**. This includes the escalation topic, planner coupling, staffed human queue, outbound flow, failure-threshold directives, republish, and deterministic verification.
+
 After inbound routing is confirmed, ask the user:
 
 > *"Inbound routing is now set up — the channel will route to [agent name]. Do you also want to configure outbound escalation so the agent can hand off to a human when requested?"*
 
-If yes:
-
-1. **Resolve the escalation queue** — follow the escalation queue resolution steps in `references/queue-resolution.md` (Step 6). The user may want a different queue for escalation than the inbound fallback. Capture `ESCALATION_QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID`.
-
-2. **Determine the outbound flow name** from the channel type (see naming table in `references/routing-flow.md` Part 2).
-
-3. **Check if an active outbound flow already exists:**
-   ```bash
-   sf data query --target-org $ORG --json \
-     --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{OUTBOUND_FLOW_DEVELOPER_NAME}' AND ProcessType='RoutingFlow'"
-   ```
-   - Row exists with non-null `ActiveVersionId` → reuse it; skip to step 4.
-   - Row missing or `ActiveVersionId` null → create the flow using the QueueBased template in `references/routing-flow.md` Part 2, substituting `ESCALATION_QUEUE_DEVELOPER_NAME` for `QUEUE_DEVELOPER_NAME`. Deploy and verify `ActiveVersionId` is non-null before continuing.
-
-4. **Add the connection block** to the agent's `.agent` file and republish — follow `references/agent-wiring.md`. The connection key depends on channel type:
-   - **Enhanced Chat (EmbeddedMessaging)** → `connection customer_web_client:`
-   - **Enhanced Messaging (3rd-party)** → `connection messaging:`
-   - **Voice** → `connection telephony:`
-   - **Email-to-Case** → `connection service_email:`
+If yes, delegate to `service-agentforce-human-escalation-configure`. Pass the resolved agent,
+channel type, context object, and fallback queue as known inputs. Do not duplicate that skill's
+write or verification steps here.
 
 ---
 
@@ -255,9 +262,7 @@ If yes:
 - [ ] Inbound routing set on the same routing address: `caseOwner`+`caseOwnerType` or `routingFlow`+`fallbackQueue`, with `casePriority` present
 
 ### Optional Phase 3 — Outbound escalation
-- [ ] Correct connection block used: `customer_web_client:` for EmbeddedMessaging, `messaging:` for 3rd-party, `telephony:` for Voice, `service_email:` for Email-to-Case
-- [ ] `outboundRouteName` and `outboundRouteType` present in the correct `<plannerSurfaces>` entry of the deployed bundle
-- [ ] Agent status is Active after republish
+- [ ] `service-agentforce-human-escalation-configure` returned `CONFIGURED` or `ALREADY-CONFIGURED`
 
 ---
 

package/skills/service-agentforce-human-escalation-configure/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: service-agentforce-human-escalation-configure
+description: "Use to configure and verify Agentforce agent-to-human escalation, including human handoff, a staffed fallback queue, and failure-threshold directives. Triggers: configure agent escalation, escalate to a human agent, agent handoff to a queue, configure a human escalation queue, set an Agentforce fallback handoff. Do not use to create an agent or configure inbound channel routing; use service-agentforce-channel-configure for inbound routing."
+metadata:
+  version: "1.0"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "agentforce-generate"
+    - "service-agentforce-channel-configure"
+    - "service-digital-engagement-channel-configure"
+    - "service-itsm-agentic-setup-agentforce-coordinate"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
+allowed-tools: Bash Read Write AskUserQuestion
+---
+
+# Configure Agentforce Agent → Human Escalation
+
+Wire an Agentforce agent so it can hand a conversation off to a human agent through an Omni-Channel queue. This skill configures and verifies the escalation surfaces, then reports a single machine-readable JSON verdict. It is **idempotent** per developer name and **refuses to write to production orgs**. It runs standalone or as a stage in a larger setup flow (after the agent is created and active).
+
+The agent, queue, outbound flow name, routed context object, service channel, and failure thresholds are all inputs, so the same skill serves any scenario (IT employee support, customer messaging, etc.) — the caller supplies the scenario-specific identifiers.
+
+This skill is the **authoritative owner of agent-to-human (outbound) escalation**. `service-agentforce-channel-configure` may wire a basic outbound flow + `connection` block in the same pass as inbound channel setup, but it delegates full escalation configuration and verification here.
+
+## The honest boundary — what is deterministic vs. directive vs. runtime
+
+Escalation in Agentforce is assembled from surfaces with different verifiability:
+
+- **Deterministic** (this skill writes and/or round-trip verifies via the Metadata/Data API): `canEscalate=true` on the escalation topic (`GenAiPlugin`); `outboundRouteConfigs` on the agent's Messaging planner surface (`GenAiPlannerBundle`), where the SAME block couples `outboundRouteName` to `outboundRouteType=OmniChannelFlow` on a Messaging-class surface; a QueueBased outbound `RoutingFlow` with a non-null `ActiveVersionId`; a human queue with a `QueueSobject` for the context object, its `QueueRoutingConfig` bound to the queue, and **at least one active human member** (a queue with zero members can never route an escalation to a human, so it never reaches `CONFIGURED`); and the agent Active after republish.
+- **Directive / native policy** (authored as Agent Script instructions, **not** a metadata counter): the default **two consecutive failures** threshold plus per-topic overrides (e.g. **password reset = one failure**). There is no metadata field that counts failed turns — the threshold is instruction text, verified by an ADK eval rubric, not a runtime read. See [references/failure-policy.md](references/failure-policy.md).
+- **Runtime / manual only**: the actual conversational trigger, `AgentWork` creation, and same-session context preservation. These cannot be driven headlessly — they are a documented manual test + eval rubric. See [references/runtime-verification.md](references/runtime-verification.md).
+
+## Authoring models — classic vs next-gen (NGA)
+
+Salesforce exposes two Agentforce authoring models, and Phase 1b auto-detects which the org supports from its metadata types. The routing infrastructure (queue, `QueueSobject`, members, `QueueRoutingConfig`, outbound `RoutingFlow`) is **identical in both**; only the agent-side escalation surface differs.
+
+- **classic** — org exposes `GenAiPlugin` + `GenAiPlannerBundle`. The agent surface is `canEscalate` (topic) + `outboundRouteConfigs` (planner Messaging surface). This surface is authored in Phase 4 (hand-edited, or via the optional `AUTHOR_SURFACES=1` pass) and round-trip verified in Phase 7.
+- **nga** — org exposes `AiAuthoringBundle` (Agent Script) and **no** `GenAiPlannerBundle`. There is no `outboundRouteConfigs` metadata; the agent surface is a reachable `@utils.escalate` action (Service agents) or a create-record action (Employee agents, which cannot use `@utils.escalate`), and the queue routing is carried entirely by the deterministic routing half. This skill **verifies** that surface from the retrieved bundle and delegates its **authoring** to `agentforce-generate`.
+- **none** — neither surface is exposed → the skill fails closed before any write.
+
+Detection can be pinned with `AUTHORING_MODEL_OVERRIDE=classic|nga` when both coexist. Full rules, the Service-vs-Employee split, and the NGA verdict set live in [references/nga-escalation.md](references/nga-escalation.md).
+
+## Scope
+
+- **In scope**: enabling the escalation topic (`canEscalate`); wiring `outboundRouteConfigs` on the `GenAiPlannerBundle` Messaging surface; deploying the bundled QueueBased outbound `RoutingFlow`; create-or-adopt of the human queue (`QueueSobject` for the context object) and its `QueueRoutingConfig`; authoring the failure-threshold directives; republish + reactivate; and a deterministic config round-trip verdict. Idempotent re-run.
+- **Out of scope**: creating/activating the agent; inbound channel transport (`sessionHandlerAsa` on the `MessagingChannel`) and the agent's outbound `connection` block (owned by `service-agentforce-channel-configure`); provisioning the messaging channel itself (`service-digital-engagement-channel-configure`); broader Omni-Channel routing infrastructure; standalone queue provisioning outside an escalation context; and any production-org write.
+
+---
+
+## Inputs
+
+| Input | Positional | Env | Default |
+|---|---|---|---|
+| Org alias | 1 (required) | — | — |
+| Agent developer name | 2 | `AGENT_DEVELOPER_NAME` | `Support_Agent` |
+| Queue developer name | 3 | `QUEUE_DEVELOPER_NAME` | `Human_Support_Queue` |
+| Escalation topic API name | 4 | `ESCALATION_TOPIC_API_NAME` | (unset — surface unverified) |
+| Planner bundle API name | 5 | `PLANNER_BUNDLE_API_NAME` | (unset — surface unverified) |
+| Outbound flow developer name | — | `FLOW_DEVELOPER_NAME` | `Human_Escalation_Outbound_Flow` |
+| Outbound flow label | — | `FLOW_LABEL` | flow name with `_` → space |
+| Context object (routed sObject) | — | `CONTEXT_OBJECT` | `MessagingSession` |
+| Service channel dev name / label | — | `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL` | `sfdc_livemessage` / `Messaging` |
+| Human members to add if empty | — | `QUEUE_MEMBER_USERNAMES` | (unset) |
+| Failure threshold (consecutive failed attempts before hand-off) | — | `DEFAULT_FAILURE_THRESHOLD` | `2` |
+| Threshold directive authored (out-of-band flag) | — | `THRESHOLD_AUTHORED` | `0` |
+
+For a non-`MessagingSession` context object (e.g. `Case`, `VoiceCall`), pass the matching `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL`.
+
+## Preconditions
+
+1. **`sf` CLI installed and authenticated** to the target org (`sf org display -o <alias>` shows Connected). All calls use `--target-org <alias>`.
+2. **`node` ≥ 18** and **`jq`** on PATH (the deterministic classifiers and JSON assembly).
+3. **The agent exists and its latest `BotVersion` is Active.** This skill fails closed if not.
+4. **For `MessagingSession` handoff, an active `MessagingChannel` exists.** This skill fails closed if none is found. Other context objects use a different transport and are not gated on `MessagingChannel`.
+5. **Sandbox / trial CDO / Developer Edition org.** The skill refuses to configure escalation on a real production customer org.
+
+If a precondition fails, `sf` surfaces the raw error — do not fabricate state; surface it and stop.
+
+---
+
+## Workflow
+
+### Phase 0 — Production write-guard (mandatory, first write-gate)
+
+Before any write, the orchestrator queries `Organization` (`IsSandbox`, `TrialExpirationDate`, `OrganizationType`) and computes `safe_to_write`. If the org is a real production customer org, the skill emits `status: "BLOCKED"` and stops. This is enforced in `scripts/verify-and-configure.sh` — never bypass it.
+
+### Phase 1 — Preconditions (read-only, fail closed)
+
+1. **Agent Active** — SOQL `BotDefinition` (+ latest `BotVersion`), classified deterministically by [scripts/classify-agent-active.mjs](scripts/classify-agent-active.mjs). Not found or inactive → block with the activation click-path.
+2. **Transport channel present** — for `MessagingSession`, SOQL `MessagingChannel WHERE IsActive=true`; zero rows → block with a pointer to `service-digital-engagement-channel-configure`.
+
+### Phase 2 — Human queue (create-or-adopt) + members
+
+Resolve the queue by DeveloperName. If missing, deploy a `Queue` (canonical Metadata API element order: `doesSendEmailToMembers`, `name`, `queueSobject`) with a `QueueSobject` for `CONTEXT_OBJECT`. For an adopted queue missing the binding, add the context object additively via the Data API. Create the `QueueRoutingConfig` if absent and bind it to the queue (`Group.QueueRoutingConfigId`), re-querying to confirm the bind persisted.
+
+**Members (human routability):** the queue must have at least one active human member — otherwise the escalation routes to an empty queue. The skill counts `GroupMember` rows that resolve to an active `User`. If there are none and you pass `QUEUE_MEMBER_USERNAMES` (comma-separated usernames), it validates each against the username grammar up front, resolves the active `User`, and POSTs the `GroupMember`; it then re-counts. If the queue still has zero active human members the verdict is `INCOMPLETE` with `queueHasActiveDirectUserMember` in `missing` (an active direct user is necessary — not sufficient — for human routability; full Omni permission-set + presence-status eligibility is proven only at runtime). When there is no eligible member, the skill also skips QueueRoutingConfig binding and outbound-flow activation, so it never wires an empty queue. Use an approved Omni provisioning workflow when richer member reconciliation is required.
+
+### Phase 3 — Outbound QueueBased RoutingFlow
+
+Deploy the bundled outbound flow template [assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml](assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml), substituting the flow name/label, queue DeveloperName, and service-channel tokens. The flow looks the queue up by DeveloperName at runtime (portable, no hardcoded Id). After deploy, `FlowDefinitionView.ActiveVersionId` must be non-null.
+
+### Phase 4 — Escalation topic + planner outbound route (doc-driven edits)
+
+These two edits require per-org topic/bundle discovery, so they are authored explicitly (retrieve → edit → deploy), then verified by the orchestrator when you pass the topic/bundle API names. Follow [references/escalation-mechanism.md](references/escalation-mechanism.md):
+
+1. Retrieve the escalation topic (`GenAiPlugin`), set `<canEscalate>true</canEscalate>`, deploy.
+2. Retrieve the agent's `GenAiPlannerBundle`, add `outboundRouteConfigs` (`escalationMessage`, `outboundRouteName=<FLOW_DEVELOPER_NAME>`, `outboundRouteType=OmniChannelFlow`) on the Messaging planner surface, deploy. The verifier couples name + type inside the SAME block on a Messaging-class surface (via [scripts/extract-outbound-route.mjs](scripts/extract-outbound-route.mjs)) — a bundle with the right name and an `OmniChannelFlow` type in unrelated blocks will not pass.
+
+### Phase 5 — Failure-threshold directives (native policy)
+
+The failure threshold and any per-topic overrides are **directives, not enforced counters** — there is no metadata field that counts failed turns (see [references/failure-policy.md](references/failure-policy.md)). The orchestrator does **not** write these into the agent; it only renders `DEFAULT_FAILURE_THRESHOLD` (default `2`) into the local directive template [assets/escalation-thresholds.instructions.md](assets/escalation-thresholds.instructions.md) — pass e.g. `DEFAULT_FAILURE_THRESHOLD=3` for a three-attempt scenario — and reports that value under `threshold.default_failures` (with `threshold.directive_rendered`) as verdict evidence. Authoring the rendered directive into the agent's Agent Script is a manual/out-of-band step; set `THRESHOLD_AUTHORED=1` on the verifier run to record `threshold.authored=true`. The directive is eval-verified, never a headless runtime read, so it never blocks the deterministic verdict.
+
+### Phase 6 — Republish + reactivate
+
+After the Phase 4/5 edits, republish and reactivate the agent so they take effect. These are **manual operator commands** for the hand-edited path; the orchestrator itself only publishes/deactivates/reactivates the agent inside the optional `AUTHOR_SURFACES=1` pass (see "Running it"):
+
+```bash
+sf agent validate authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
+sf agent publish  authoring-bundle --api-name "$AGENT_DN" --target-org "$ORG" --json
+sf agent activate --api-name "$AGENT_DN" --target-org "$ORG"
+```
+
+### Phase 7 — Deterministic verification (single JSON verdict)
+
+The orchestrator round-trips every deterministic surface, assembles an evidence object, and classifies it with [scripts/verify-escalation-config.mjs](scripts/verify-escalation-config.mjs) into one of three states so a missing escalation policy can never masquerade as fully configured:
+
+- `CONFIGURED` — all deterministic surfaces satisfied **and** the failure-threshold directive is authored.
+- `ROUTING_CONFIGURED_POLICY_PENDING` — routing and the agent escalation surface are verified, but the failure-threshold directive (`thresholdAuthored`) is not yet confirmed. Author it (`AUTHOR_SURFACES=1` / `THRESHOLD_AUTHORED=1`) and re-run to reach `CONFIGURED`.
+- `INCOMPLETE` — one or more deterministic surfaces are missing (see `missing[]`).
+
+Note the NGA escalation-surface detection ([scripts/classify-nga-escalation.mjs](scripts/classify-nga-escalation.mjs)) is an **advisory preflight** — it matches for a reachable `@utils.escalate` / create-record action in the authoring bundle but does not prove runtime reachability from the topic. Treat a passing NGA surface check as a strong signal, not end-to-end runtime proof; confirm the live handoff with the Phase 8 runtime step.
+
+### Phase 8 — Runtime / manual proof (out of headless scope)
+
+Confirm the conversational trigger, `AgentWork` creation, and same-session context preservation with a live conversation — see [references/runtime-verification.md](references/runtime-verification.md).
+
+---
+
+## Running it
+
+```bash
+bash scripts/verify-and-configure.sh <org-alias> \
+  [<agent-developer-name>] [<queue-developer-name>] \
+  [<escalation-topic-api-name>] [<planner-bundle-api-name>]
+```
+
+- Positionals 2–5 also read from env (see the Inputs table). Further scenario inputs are env-only: `FLOW_DEVELOPER_NAME`, `FLOW_LABEL`, `CONTEXT_OBJECT`, `SERVICE_CHANNEL_DEV_NAME`, `SERVICE_CHANNEL_LABEL`, `QUEUE_MEMBER_USERNAMES`.
+- `PLAN_ONLY=1` previews (read-only) and stops before any write.
+- `THRESHOLD_AUTHORED=1` marks the directive policy as authored for the verdict.
+- `AUTHOR_SURFACES=1` (optional, run mode) — deterministically author the two doc-driven surfaces instead of hand-editing XML, following the Agentforce lifecycle in `agentforce-generate/references/known-issues.md` (Issue 18): **publish** (regenerate the compiled bundle) → **retrieve** the `GenAiPlugin` topic + `GenAiPlannerBundle` in **metadata format** (`--target-metadata-dir … --unzip`) → **deactivate** the agent (deploys fail while it is active) → apply a schema-aware, XSD-ordered, loss-less, idempotent patch (`scripts/patch-escalation-surfaces.mjs`) that sets `canEscalate=true` (after `aiPluginUtterances`, before `description`) and inserts `outboundRouteConfigs` (`outboundRouteType=OmniChannelFlow`, **before `<surface>`** on a Messaging-class planner surface, targeting the outbound flow) → **deploy** with `--metadata-dir` → **activate** (fail-closed; the agent is never left inactive silently) → **re-read the latest `BotVersion`** so the verdict reflects the freshly-authored version. It requires the topic and/or bundle API names, runs only after the membership gate (never wires an empty queue), and **refuses** (blocks) rather than guess if it cannot find a safe, XSD-ordered patch point. Omit it to keep the skill verify-only.
+- The `canEscalate` and `outboundRouteConfigs` surfaces are verified only when you pass `<escalation-topic-api-name>` / `<planner-bundle-api-name>` (they are authored via the doc-driven edits in Phase 4).
+
+**Typical two-pass flow**: run once to stand up the queue + outbound flow and preconditions; perform the Phase 4/5/6 doc-driven edits; then re-run with the topic + bundle API names and `THRESHOLD_AUTHORED=1` to reach `CONFIGURED`.
+
+## Output contract
+
+A single JSON object to stdout:
+
+```json
+{
+  "skill": "service-agentforce-human-escalation-configure",
+  "status": "CONFIGURED",
+  "agent": { "developer_name": "Support_Agent", "active": true },
+  "queue": { "developer_name": "Human_Support_Queue", "id": "00G...", "active_direct_user_member_count": 1 },
+  "outbound_flow": { "api_name": "Human_Escalation_Outbound_Flow", "active_version_id": "301..." },
+  "escalation_topic": "Escalate_To_Human",
+  "planner_bundle": "Support_Agent",
+  "config_verification": {
+    "verdict": "CONFIGURED",
+    "deterministicPass": true,
+    "directivePass": true,
+    "checks": [],
+    "missing": []
+  },
+  "next_steps": [],
+  "manual_actions": [],
+  "blocking_issue": null
+}
+```
+
+- `status`: `CONFIGURED` (all deterministic surfaces satisfied), `INCOMPLETE` (some `config_verification.missing`), or `BLOCKED` (bad input / auth / production / precondition; exit 1).
+- Re-running an already-configured org is a no-op that returns `CONFIGURED` (idempotent).
+
+## Idempotency
+
+Existing queue, `QueueSobject`, `QueueRoutingConfig`, queue members, and an already-active outbound flow are reused, not recreated (members are only added when the queue has zero active members and `QUEUE_MEMBER_USERNAMES` is supplied; already-present members are left untouched). The doc-driven edits (`canEscalate`, `outboundRouteConfigs`) are set-if-absent. A second run against a fully configured org performs no writes and returns `CONFIGURED`.
+
+## Verification
+
+Run the bundled escalation contract tests after changing this skill or its scripts:
+
+```bash
+python3 scripts/tests/test_escalation_contracts.py
+```

package/skills/service-agentforce-human-escalation-configure/assets/escalation-thresholds.instructions.md

@@ -0,0 +1,37 @@
+<!--
+Agent Script failure-threshold directive snippet (NGA / Agent Script authoring model).
+
+This is a TEMPLATE of directive text, NOT an enforced runtime counter. It is injected
+into the agent's topic/system instructions so the planner escalates consistently.
+Salesforce Agentforce does not expose a metadata field that counts failed turns; the
+threshold is expressed as instruction text and verified by an ADK eval rubric plus a
+documented manual conversation test — never by a deterministic metadata read.
+
+Substitute the tokens below when authoring:
+  __DEFAULT_FAILURES__   default consecutive-failure threshold (recommended: 2)
+  __OVERRIDE_TOPIC_LABEL__ label of a topic that needs a tighter threshold (e.g. "Password Reset")
+  __ESCALATION_MESSAGE__ customer-facing handoff line
+-->
+
+# Escalation policy (agent directives)
+
+Add the following to the agent's global/system instructions:
+
+- When you cannot resolve the user's request after __DEFAULT_FAILURES__ consecutive
+  failed attempts on the same request, escalate to a human agent instead of continuing
+  to retry.
+- Treat "failed attempt" as: you asked a clarifying question and still could not act, a
+  tool/action returned an error, or the user states your answer did not resolve the
+  issue.
+- On escalation, tell the user: "__ESCALATION_MESSAGE__" and then invoke the human
+  handoff (the escalation topic is enabled to transfer to the human queue).
+- Do not disclose internal error details, stack traces, or system identifiers when
+  escalating.
+
+# Per-topic override
+
+Add the following to the __OVERRIDE_TOPIC_LABEL__ topic instructions (tighter threshold):
+
+- For __OVERRIDE_TOPIC_LABEL__ requests, escalate to a human after a SINGLE failed attempt.
+  Time-sensitive requests (for example password/credential problems) should not be
+  retried repeatedly.

package/skills/service-agentforce-human-escalation-configure/assets/force-app/main/default/flows/Human_Escalation_Outbound_Flow.flow-meta.xml

@@ -0,0 +1,173 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <actionCalls>
+        <name>Check_Availability</name>
+        <label>Check Availability for Routing</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <actionName>checkAvailabilityForRouting</actionName>
+        <actionType>checkAvailabilityForRouting</actionType>
+        <connector>
+            <targetReference>Are_Reps_Available</targetReference>
+        </connector>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>__SERVICE_CHANNEL_DEV_NAME__</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>__SERVICE_CHANNEL_LABEL__</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>__SERVICE_CHANNEL_DEV_NAME__</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>QueueBased</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><elementReference>Lookup_Queue_by_Name.Id</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>true</booleanValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>selectedOutputs</name>
+            <value><stringValue>GET_AVAILABILITY</stringValue></value>
+        </inputParameters>
+        <nameSegment>checkAvailabilityForRouting</nameSegment>
+        <outputParameters>
+            <assignToReference>onlineAgentsCount</assignToReference>
+            <name>onlineAgentsCount</name>
+        </outputParameters>
+        <versionString>2.0.0</versionString>
+    </actionCalls>
+    <actionCalls>
+        <name>Route_to_Queue</name>
+        <label>Route to Queue</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <actionName>routeWork</actionName>
+        <actionType>routeWork</actionType>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>recordId</name>
+            <value><elementReference>recordId</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>__SERVICE_CHANNEL_LABEL__</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>__SERVICE_CHANNEL_DEV_NAME__</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>QueueBased</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>__SERVICE_CHANNEL_DEV_NAME__</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><elementReference>Lookup_Queue_by_Name.Id</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>true</booleanValue></value>
+        </inputParameters>
+        <nameSegment>routeWork</nameSegment>
+        <versionString>2.0.0</versionString>
+    </actionCalls>
+    <apiVersion>67.0</apiVersion>
+    <areMetricsLoggedToDataCloud>false</areMetricsLoggedToDataCloud>
+    <decisions>
+        <name>Are_Reps_Available</name>
+        <label>Are Reps Available?</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <defaultConnectorLabel>No</defaultConnectorLabel>
+        <rules>
+            <name>Reps_Available</name>
+            <conditionLogic>and</conditionLogic>
+            <conditions>
+                <leftValueReference>onlineAgentsCount</leftValueReference>
+                <operator>GreaterThan</operator>
+                <rightValue><numberValue>0.0</numberValue></rightValue>
+            </conditions>
+            <connector><targetReference>Route_to_Queue</targetReference></connector>
+            <label>Yes</label>
+        </rules>
+    </decisions>
+    <environments>Default</environments>
+    <interviewLabel>__FLOW_DEVELOPER_NAME__ {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>__FLOW_LABEL__</label>
+    <processMetadataValues>
+        <name>BuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>CanvasMode</name>
+        <value><stringValue>AUTO_LAYOUT_CANVAS</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>OriginBuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processType>RoutingFlow</processType>
+    <recordLookups>
+        <name>Lookup_Queue_by_Name</name>
+        <label>Lookup Queue by Name</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <assignNullValuesIfNoRecordsFound>false</assignNullValuesIfNoRecordsFound>
+        <connector><targetReference>Check_Availability</targetReference></connector>
+        <filterLogic>and</filterLogic>
+        <filters>
+            <field>DeveloperName</field>
+            <operator>EqualTo</operator>
+            <value><stringValue>__QUEUE_DEVELOPER_NAME__</stringValue></value>
+        </filters>
+        <filters>
+            <field>Type</field>
+            <operator>EqualTo</operator>
+            <value><stringValue>Queue</stringValue></value>
+        </filters>
+        <getFirstRecordOnly>true</getFirstRecordOnly>
+        <object>Group</object>
+        <storeOutputAutomatically>true</storeOutputAutomatically>
+    </recordLookups>
+    <start>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <connector><targetReference>Lookup_Queue_by_Name</targetReference></connector>
+    </start>
+    <status>Active</status>
+    <variables>
+        <name>onlineAgentsCount</name>
+        <dataType>Number</dataType>
+        <isCollection>false</isCollection>
+        <isInput>false</isInput>
+        <isOutput>false</isOutput>
+        <scale>0</scale>
+    </variables>
+    <variables>
+        <name>recordId</name>
+        <dataType>String</dataType>
+        <isCollection>false</isCollection>
+        <isInput>true</isInput>
+        <isOutput>false</isOutput>
+    </variables>
+</Flow>

package/skills/service-agentforce-human-escalation-configure/assets/package.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Human_Escalation_Outbound_Flow</members>
+        <name>Flow</name>
+    </types>
+    <version>67.0</version>
+</Package>

package/skills/service-agentforce-human-escalation-configure/assets/sfdx-project.json

@@ -0,0 +1,5 @@
+{
+  "packageDirectories": [{ "path": "force-app", "default": true }],
+  "namespace": "",
+  "sourceApiVersion": "67.0"
+}