@salesforce/afv-skills 1.65.0 → 1.65.1

package/skills/automation-flow-coordinate/references/recipes/testing/shared-stages/intent-analyzer.md

@@ -1,180 +0,0 @@
----
-id: flow.recipes.testing.shared-stages.intent-analyzer
-description: "Phase 1 of author-test and debug workflows — classify the user request, run the eligibility probe, detect silo mode, and extract the flow shape."
----
-
-# Intent analyzer (shared stage)
-
-<!-- Consumers: workflows/author-test.md (Phase 1), workflows/debug.md (Phase 1), workflows/save-debug.md (Phase 1) -->
-
-The first phase in the author-test and debug workflows. Reads the user
-request and the parent flow, classifies what the user is asking for,
-confirms the flow is eligible, and emits a structured assessment that
-later phases consume.
-
-This stage is **read-only**: no `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}`,
-a `run_*` call, or any other write call happens here. Output is a
-plain assessment object handed to the next phase.
-
-## Step 1 — Input classification
-
-The Route-by-intent table in [[flow.recipes.testing]] is the **single
-source of truth for the trigger phrases** — this stage does not re-list
-them. The router already picked a workflow from that table; this stage's
-job is to **confirm that routing was right** for the flow at hand and
-emit the matching intent (one of `author-test`, `debug`, `promote`,
-`save-debug`, `run-saved`, `coverage`) in the Step 5 assessment.
-
-Confirm against the router's table rather than re-deriving from scratch:
-the consuming workflow tells you which intent it expects (author-test
-expects `author-test`, debug expects `debug`, and so on). **If the flow
-or request doesn't match that expected intent, hand control back to the
-router** — do not silently proceed down the wrong workflow.
-
-If the intent is `run-saved` or `coverage`, hand control back to the
-router — those paths skip this stage and go directly to the run-tool
-decision table or the coverage interpretation-only path. No coverage
-operation is onboarded to MCP.
-
-## Step 2 — Eligibility check (mandatory, no shortcuts)
-
-Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow/{id}")` for the target flow. Read:
-
-- `processType` (top-level)
-- `metadata.start.triggerType` (treat absent as `"None"`)
-
-Check against the confirmed-supported combos:
-
-| `processType` | `triggerType` | Status |
-|---|---|---|
-| `AutoLaunchedFlow` | `RecordBeforeSave` | Supported |
-| `AutoLaunchedFlow` | `RecordAfterSave` | Supported |
-| `AutoLaunchedFlow` | `None` (or absent) | Supported |
-| `AutoLaunchedFlow` | `Scheduled` | **Not supported** |
-| `Flow` | `None` (screen flow) | **Not supported** |
-| anything else | anything else | **Probe** |
-
-If the combo is unknown, call
-`GET /services/data/vXX.0/flowbuilder/schema/flow-capabilities` (read `.flowFeatures`) with that exact
-`(processType, triggerType)` pair. Look for the literal string
-`"FlowTesting"` in the returned `Array<string>`. **Do not key off
-`"TestModeExperience"`** — that flag is also present on screen flows
-and is misleading.
-
-Full table and decision flow: [[flow.recipes.testing.eligibility]].
-
-## Step 3 — Silo detection
-
-Scan the user message for any of these signals:
-
-- Literal `@testSetup`
-- The words "silo", "isolated", "fixture", "test data", "seeded data"
-- A specific Apex class name the user named as the seed source
-
-If any signal is present, set `siloMode: true`. When silo mode is on,
-the eligibility check also requires `"FlowTestingWithDataSilo"` in the
-features array — surface that as a second probe before proceeding.
-
-### Silo sub-type selection
-
-When silo mode is active, choose the `dataSourceType`:
-
-- **`AiGenerated` (default)** — when the user has NOT named a specific
-  Apex class or said `@testSetup`. The AI becomes the fixture generator.
-- **`ApexClass` (opt-in)** — when the user explicitly names an Apex
-  class or says `@testSetup`.
-
-The default flip is behavioral: "silo" no longer implies "Apex" —
-AiGenerated is the new default, and Apex is an opt-in.
-
-## Step 4 — Flow shape extraction
-
-From the `GET /services/data/vXX.0/flowbuilder/flow/{id}` response, extract:
-
-- `elementCount` — total number of canvas elements
-- `triggerType` — record-triggered (`RecordBeforeSave` /
-  `RecordAfterSave`), non-triggered (`None`), or other
-- `inputVariables[]` — only relevant for non-triggered flows; each
-  entry is `{ name, dataType, isInput, isOutput }`. Pulled from the
-  flow's `variables[]` filtered by `isInput: true`.
-- `startConfig` — `{ object, recordTriggerType, scheduledPaths }` —
-  needed by the payload-builder to pick `InputTriggeringRecordInitial`
-  vs. `InputVariable` parameter types.
-- `hasWaits` — `true` when `metadata.waits[]` is non-empty. Detection
-  only: a Wait never makes a flow ineligible, and each workflow decides
-  what to do with it.
-
-This is the structural difference that drives payload shape: a
-record-triggered flow takes `sobjectValue`-bound `$Record`; a
-non-triggered flow takes one `InputVariable` parameter per declared
-input variable.
-
-### SObject-reference scan (for AiGenerated silo)
-
-When `siloMode: true` and the silo sub-type is `AiGenerated`, identify
-the target SObject that the generator should fabricate a fixture record
-for:
-
-- **Record-triggered flows** (`RecordBeforeSave` / `RecordAfterSave`)
-  — the trigger object is `start.object`.
-- **Autolaunched flows** (`triggerType: None`) — scan the flow elements
-  for the first `recordLookup`, `recordCreate`, `recordUpdate`, or
-  `recordDelete` element and extract its `object` field. Alternatively,
-  scan `variables[]` for an SObject-typed variable.
-
-This story supports **single-object scope only**: if the flow touches
-multiple SObject types, pick the one the user's scenario names and note
-the others as out-of-scope. This scan supports AC-5 (detect and offer).
-
-## Step 5 — Output contract
-
-Emit a single assessment object:
-
-```jsonc
-{
-  "intent": "author-test" | "debug" | "promote" | "save-debug" | "run-saved" | "coverage",
-  "eligible": true,
-  "flowShape": {
-    "flowApiName": "<api name>",
-    "processType": "AutoLaunchedFlow",
-    "triggerType": "RecordAfterSave",
-    "elementCount": 7,
-    "inputVariables": [],
-    "startConfig": { "object": "Account", "recordTriggerType": "Update" },
-    "hasWaits": false
-  },
-  "siloMode": false,
-  "targetSObject": null,
-  "features": ["FlowTesting", "FlowTestCoverage", "FlowTestingWithDataSilo"]
-}
-```
-
-`targetSObject` is the single object type the AiGenerated generator will
-fabricate a fixture for — set from the SObject-reference scan above.
-For record-triggered flows it equals `startConfig.object`; for
-autolaunched flows it is the object resolved from the first
-`recordLookup` / `recordCreate` / `recordUpdate` / `recordDelete`
-element (or an SObject-typed variable). Leave `null` when
-`siloMode: false` or the sub-type is `ApexClass` (the Apex path sources
-its own records). The payload-builder Step 6 and
-[[flow.recipes.testing.workflows.author-test]] Phase 3 both read this
-field to drive the generator.
-
-## Step 6 — Error path
-
-If `eligible: false`:
-
-1. Tell the user FlowTest is not supported for this `(processType,
-   triggerType)` combo, naming both values.
-2. Offer the debug workflow as the ad-hoc-validation alternative — point
-   them at [[flow.recipes.testing.workflows.debug]], which probes the
-   flow's supported features and picks the right run endpoint.
-3. Stop. Do not attempt `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` against an
-   ineligible flow — the wrapper will forward the payload, Aura will
-   reject with `state: "ERROR"`, and the wrapper re-throws. There is
-   no implicit fallback.
-
-If `eligible: true` but `siloMode: true` and
-`"FlowTestingWithDataSilo"` is absent: tell the user silo mode isn't
-supported here, ask whether to proceed without silo (live-org binding
-via `sobjectValue`) or stop.

package/skills/automation-flow-coordinate/references/recipes/testing/workflows/debug.md

@@ -1,175 +0,0 @@
----
-id: flow.recipes.testing.workflows.debug
-description: "Pure debug workflow — interactive run-trace-refine loop on an existing flow with no test artifact produced. Three phases: Setup → Iterate → Decide. Endpoint chosen by probing `TestModeExperience` support; offers promotion to a saved FlowTest at end."
----
-
-<!-- Consumers: testing router -->
-
-# Debug a flow (no test artifact produced)
-
-Use when the user is investigating "did my flow do X?" or "why did the flow do Y?" with no upfront intent to save a test. The workflow is driven by the two debug-run endpoints covered in `## Tool routing`, plus a small set of supporting tools as the run demands: `POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-resume` (continue a run paused at a Wait element), `GET /services/data/vXX.0/flowbuilder/flow-test/record-run-data` (drill into one record of a multi-record run), `GET /services/data/vXX.0/flowbuilder/flow-test/interview-history` (inspect prior runs of this flow version), and `GET /services/data/vXX.0/flowbuilder/flow-test/debug-run-as-validation` (pre-flight guard for debug-as-another-user). At the end of the iterate loop the user is offered a promotion path to `[[flow.recipes.testing.workflows.promote]]` — that is the **only** way to produce a persistent FlowTest from this workflow.
-
-This skill is only intended to be used with Supported Flow Process Types listed below, even though debugging is available for a broader list of process types via the Flow Builder.
-
----
-
-## Supported flow process types
-
-Match `(processType, metadata.start.triggerType)` from `GET /services/data/vXX.0/flowbuilder/flow/{id}` against this allow-list before any run work. Treat an absent `triggerType` as `None`.
-
-| `processType` | `triggerType` | Shorthand | Debug workflow |
-|---|---|---|---|
-| `AutoLaunchedFlow` | `RecordBeforeSave` | Record-triggered (RT) | Supported |
-| `AutoLaunchedFlow` | `RecordAfterSave` | Record-triggered (RT) | Supported |
-| `AutoLaunchedFlow` | `None` (or absent) | Autolaunched (ALF) | Supported |
-| `AutoLaunchedFlow` | `Scheduled` | Scheduled | Supported |
-| `AutoLaunchedFlow` | `Segment` | Segment-triggered | Supported |
-| `AutoLaunchedFlow` | `AutomationEvent` | Automation-event-triggered | Supported |
-| `AutoLaunchedFlow` | `IndivRelatedRecord` | Individual-related-record-triggered | Supported |
-| `AutoLaunchedFlow` | `List` | List-triggered | Supported |
-| `AutoLaunchedFlow` | `FormSubmissionEvent` | Form-submission-event-triggered | Supported |
-| `AutoLaunchedFlow` | `CampaignMember` | Campaign-member-triggered | Supported |
-| `Flow` | `None` | Screen flow | **Not supported** — hand back to the testing router |
-| `AutoLaunchedFlow` | `PlatformEvent` | Platform-event-triggered | **Not supported** — hand back to the testing router |
-| Any other combo | | — | **Not supported** — hand back to the testing router |
-
-If unsupported, STOP before the routing probe and surface: "This workflow currently supports the above listed process types. `<processType>` × `<triggerType>` is out of scope." Do not proceed to the routing probe or Phase 2.
-
----
-
-## Tool routing
-
-Two endpoints exist for running debug iterations. Neither is a default — the workflow probes the flow's `(processType, triggerType)` combo and picks based on whether the org / flow-type supports test mode:
-
-- **`POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-test-mode`** — payload-driven behavior. Takes the FlowTest as `flowTestJson` (a JSON-**encoded string** of the same definition `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` consumes, unsaved). Rolls back unless the test's `doesCommitChanges` is `true`.
-- **`POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview`** — argument-driven DML behavior. Required `flowVersionId`; optional `flowDevName`, `arguments` (input vars as a JSON string). Commits when `enableRollbackMode` is `false` (default).
-
-### Routing probe
-
-**Mandatory before the first debug run.** The probe is the ONLY sanctioned way to pick between the two endpoints — do NOT infer the choice from the user's prompt phrasing (mentions of "test mode", "rollback", etc.), the tool-list order, or prior conversation.
-
-Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/schema/flow-capabilities")` (read `.flowFeatures`) for the flow's `(processType, triggerType)` and inspect the returned feature-name list for **`TestModeExperience`**:
-
-- **`TestModeExperience` present** → use `POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-test-mode`
-- **`TestModeExperience` absent** → use `POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview`.
-
-Cache the probe result for the session — the feature list does not change within one Aura session. For both endpoints, default to rollback debug option (no DML commits) unless explicitly approved by user.
-
-### Resume endpoint
-
-A run that stops at a Wait element is continued with a third call, whichever run endpoint started it:
-
-- **`POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-resume`** — required `flowVersionId` plus four values fed back **verbatim** from the paused result: `serializedInterview`, `resolvedContext`, `serializedCumulativeDebugInfo`, `waitEvent`. `waitEvent` is the **`name`** of one entry in the result's `waitEvents[]`, never its `value`; a blank `waitEvent` makes the resume fail. Returns a single `{runInterviewResult, canvasDecorator}`, not a `results[]` array.
-
-The server does **not** check that a resume's settings match the original run, so the workflow does (see `### Paused runs` in Phase 2).
-
----
-
-## Phase 1 — Setup
-
-Load `[[flow.recipes.testing.shared-stages.intent-analyzer]]`.
-
-The Intent Analyzer in this workflow is responsible for:
-
-1. **Confirming debug intent.** This is run-trace-refine, not test authoring and not promotion. If the user wants to author a test from scratch, hand back to the testing router; it should route to `[[flow.recipes.testing.workflows.author-test]]`.
-2. **Identifying the flow.** Read the parent flow via `GET /services/data/vXX.0/flowbuilder/flow/{id}`. Capture `processType`, `metadata.start.triggerType`, the flow's input variables (for non-triggered flows), and the active version ID.
-3. **Eligibility check.** Match `(processType, triggerType)` against the allow-list in `## Supported flow process types`. If the combo isn't on the allow-list, STOP: surface the ineligibility per that section and hand back to the testing router. **Do not** check for `"FlowTesting"` here — debug runs work for shapes (like scheduled) that cannot be saved as tests.
-4. **Route the run endpoint.** Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/schema/flow-capabilities")` (read `.flowFeatures`) for the flow's `(processType, triggerType)` and inspect for `TestModeExperience` per `## Tool routing`. Cache the result on the session. If test mode is absent, surface the constraint to the user now (before any input work) and gate on host-quoted confirmation; do not proceed to input-gathering until confirmed.
-5. **Assemble the run inputs for the routed endpoint.** The test-mode endpoint takes a full `FlowTest` definition (same shape as `POST /services/data/vXX.0/flowbuilder/flow-test`/`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}`, unsaved), JSON-encoded into its `flowTestJson` **string** field — hand off to `[[flow.recipes.testing.shared-stages.payload-builder]]` to build it in memory, then serialize it. The non-test-mode endpoint takes flat ad-hoc arguments (required `flowVersionId`; optional `flowDevName`, JSON-encoded `arguments`).
-
-6. **Offer pausing at Wait elements.** If the Intent Analyzer's `flowShape.hasWaits` is `true`, tell the user the flow has Wait elements and propose debugging with pausing enabled, so the run stops at a Wait instead of running past it. Enable it per the routed endpoint:
-   - **`debug-interview`** — set `debugWaits: true` on the request.
-   - **`debug-interview-test-mode`** — set `doesTestWaitElement: true` inside the `flowTestJson` definition. Core only allows this for autolaunched flows with no trigger, and a Wait that the test mocks never pauses. If pausing isn't available for this flow shape, say so plainly rather than offering it.
-
-   Pausing is opt-in: if the user declines, leave it off and run as before.
-
-Phase 1 emits: `{flow, processType, triggerType, runEndpoint, runInputs, activeVersion, debugWaits}`. No write-side tool calls other than the read-only routing probe.
-
----
-
-## Phase 2 — Iterate
-
-The run → trace → refine loop. The user stays in this phase as long as they want.
-
-### Loop body
-
-1. **Run.** Call the endpoint selected by the Phase 1 routing probe (per `## Tool routing`). If the probe hasn't run yet in this session, STOP and run it now — do NOT guess between the two endpoints from prompt phrasing, tool-list order, or prior conversation. Both run endpoints return a `results[]` array — **one entry per debugged record** (`{runInterviewResult, canvasDecorator}`), so a high-scale record-triggered flow can produce several. Iterate `results[]`; for a single-record flow it has one entry. **Capture each entry's run identifier** — this same value is the `interviewGUID` for `GET /services/data/vXX.0/flowbuilder/flow-test/interview-history`, the `flowRunId` for `GET /services/data/vXX.0/flowbuilder/flow-test/record-run-data`, and the `interviewId` handed to `[[flow.recipes.testing.workflows.promote]]` (for a multi-record run, pick the record you want to promote). To drill into one record's run after a multi-record debug, call `GET /services/data/vXX.0/flowbuilder/flow-test/record-run-data` with that record's `flowRunId` + `flowVersionId`. If a result's `interviewStatus` is `WAITING` or `ASYNC_WAITING`, the run is paused at a Wait element — follow `### Paused runs` below instead of treating it as finished.
-2. **Render the trace in two layers.** Emit the **Headline** layer using the verbatim skeleton and worked example in `examples/debug-output-template.md` — same headers, same order, every section present even if a section is `None`. Do not paraphrase headers, merge sections, or reorder. The **Details** layer is on-demand only (do not emit unless the user asks).
-
-   - **Details (raw, on demand).** Only when the user asks ("show raw trace", "deep dive", "why did element X…"), surface the `executionLog`, element-level inputs/outputs, and any fault paths taken. Scope to what they asked about — do not dump the full raw trace by default.
-3. **Ask the user what's next:**
-   > Deep dive into execution details? Refine inputs? Try a different scenario? Or save this run as a test?
-4. **Three valid responses:**
-   - **Refine** → mutate the payload (new record ID on the `$Record` test-point, different `parameters[]` values, switch scheduled path), loop back to step 1. **Discard any paused-run state** (see `### Paused runs`) — a paused interview belongs to the inputs that produced it and must never be resumed on top of changed ones.
-   - **New scenario** → discard the current payload, re-gather from the user, rebuild via the payload-builder, loop back to step 1. Treat as a fresh iteration; old `interviewId` and any paused-run state are not reused.
-   - **Save / promote** → exit Phase 2, go to Phase 3.
-
-### Paused runs
-
-A run is **paused** when a result's `interviewStatus` is `WAITING` (stopped at a Wait element) or `ASYNC_WAITING`. Do not test for `PAUSED` — that is a different engine status, even though the endpoint's schema example mentions it.
-
-1. **Say it's paused.** Render the headline with the `### Paused` block from `examples/debug-output-template.md` (see that file for the exact shape), not a "finished" summary.
-2. **Enumerate the resumable events.** `waitEvents[]` is a list of `{name, value}`: `name` is the wait event's API name, `value` is its resume time (empty for a platform-event wait). Show both and ask which event to resume. If there is only one, still confirm before resuming.
-3. **Resume** with `POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-resume`, passing the chosen event's **`name`** as `waitEvent` and the paused result's `serializedInterview`, `resolvedContext` and `serializedCumulativeDebugInfo` verbatim.
-4. **Keep the debug settings identical.** Send the same `enableRollbackMode`, `debugAsUserId`, `enableTrace` and `showGovernorLimit` as the original run, and do not change `arguments`. The server does not compare them, so a mismatch silently changes rollback or run-as behavior partway through one run. `useLatestSubflow` is ignored on resume; do not rely on it.
-5. **Append, don't restart.** Add the resumed leg's results to the existing trace and render one cumulative headline (Summary covers the run so far). A resumed run can pause again: repeat from step 1 until the status is no longer waiting.
-6. **Warn about rollback once.** Each leg is committed or rolled back on its own, so with rollback on, DML from earlier legs is already undone when the resume runs. Values carried over from an earlier leg (for example a new record's Id) may point at records that no longer exist. Say this before the first resume.
-7. **Record that the run paused.** If any leg paused, the final scenario is `paused` for Phase 3 and `[[flow.recipes.testing.workflows.promote]]`.
-
-Paused-run state is `{serializedInterview, resolvedContext, serializedCumulativeDebugInfo, waitEvents}`. Hold it only until the next run; **refine** and **new scenario** discard it (see the loop's step 4).
-
-**When the user requests a past-run trace** ("what did this flow do recently?"), call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow-test/interview-history")` with the run's `interviewGUID` + `flowVersionId` (both **required**; the query param is `interviewGUID`, NOT `interviewId`). History is returned only when its captured version matches the supplied `flowVersionId` — **per-flow-version**. Historic forensic queries across unrelated flow versions are out of scope.
-
-### Stop conditions inside the loop
-
-- User signals satisfaction with the run ("looks good", "that's it") → offer promotion in Phase 3.
-- User abandons ("never mind", "stop") → exit gracefully, no Phase 3.
-- 3 consecutive iterations with the same input pattern producing the same failure → STOP and surface the failure to the user. Don't spiral; ask for direction.
-- Aura session error (`aura:invalidSession` / `Aura HTTP 401`) → STOP, run `agentic-flow-poc-setup`, do not retry the failing call automatically.
-
----
-
-## Phase 3 — Decide
-
-The promotion offer. Brief and explicit.
-
-> Would you like to save this debug run as a persistent test?
-> 
-> Reply **"yes"** to convert this scenario into a FlowTest record (320xxx) for regression. Reply **"no"** or **"end"** to wrap up.
-
-Three valid responses:
-
-- **Yes / save** → hand off to `[[flow.recipes.testing.workflows.promote]]` with the debug context: `{interviewId, serializedInterview?, inputs, trace, flowVersionId, paused}`. Capture the `serializedInterview` blob if it's available (Route B needs it, not the id); if it isn't, promote falls back to Route A. Set `paused: true` if the run paused at any point. Promote will check the narrower save-as-test eligibility, build the payload, validate, save, and verify.
-  - **Paused or resumed runs can only be saved as a `WithoutAssertion` test.** Say so before the hand-off: "This run paused at a Wait, so it can be saved only as a test without assertions." Do not offer to derive assertions from a paused or resumed trace.
-- **No / end** → wrap up. Show one-line summary of what was iterated. Do not save anything.
-- **Not sure / what does that do?** → explain in one paragraph what a saved FlowTest gives them (regression coverage, re-runnable, tied to a flow version, contributes to coverage decorators), then re-ask.
-
-If the flow is debug-eligible but not save-eligible (scheduled `AutoLaunchedFlow`), pre-empt the promotion offer: tell the user the run was useful but cannot be saved as a `FlowTest` for this flow shape. Skip Phase 3's question.
-
----
-
-## Error recovery
-
-**Session expired mid-iterate.** STOP, run `agentic-flow-poc-setup`. The `interviewId` from previous iterations is bound to the old session and may not be retrievable in interview-history. The user can re-run the same inputs after re-auth.
-
-**Record not found.** The user supplied a record ID that doesn't exist in the target org. Surface the failure verbatim, ask for a different ID. Don't auto-retry with a guessed ID.
-
-**Flow version mismatch.** The active version changed mid-session (someone activated a new version). The next run will execute the new active version. Surface this once: "Flow version changed — runs will now execute v<N>." Subsequent runs continue normally.
-
-**User asked for real DML without quoting the org host.** Don't proceed. Re-ask per `## Tool routing`: "Real DML against `<orgHost>`? Quote the host explicitly to confirm."
-
-**Resume fails.** Most often `waitEvent` was blank or was the event's `value` instead of its `name`, or the run was not actually paused. Surface the error verbatim, re-list `waitEvents[]` from the paused result, and ask again. Do not guess an event or retry the same call.
-
-**Session expired while paused.** The paused state is bound to the old session and cannot be recovered. Tell the user the paused run is lost and offer to re-run from the start with the same inputs.
-
-**Run returns a fault.** A flow element hit an error and took a `faultConnector` (or unhandled, in which case the flow halts). Show the fault in the headline ("the flow failed at element `<X>` because `<reason>`") and offer the raw stack in the details. Then ask whether to refine inputs to avoid the fault or treat the fault as the scenario to lock in (which routes to Phase 3 for promotion).
-
----
-
-## Notes for callers
-
-- Tool routing is discussed in `## Tool routing` — the default and the two ways to opt into committing DML are covered there.
-- The final iteration's context is the handoff to `[[flow.recipes.testing.workflows.promote]]`. Route A (clean re-state) needs the `inputs`; Route B (shortcut via `POST /services/data/vXX.0/flowbuilder/flow-test/actions/generate-from-debug-run`) needs the `serializedInterview` blob from the run — **not** the `interviewId`. Capture the serialized interview if Route B is a possibility; if only the id is available, Route B is off and promote uses Route A.
-- Tool budget: 1 `GET /services/data/vXX.0/flowbuilder/flow/{id}` + 1 `GET /services/data/vXX.0/flowbuilder/schema/flow-capabilities` (read `.flowFeatures`) at start, then N iterations of the routed run endpoint. Optional, as the run demands: 1×`POST /services/data/vXX.0/flowbuilder/flow-test/debug-interview-resume` per pause, 1×`GET /services/data/vXX.0/flowbuilder/flow-test/record-run-data` per record drill-in, 1×`GET /services/data/vXX.0/flowbuilder/flow-test/interview-history` per history lookup, and a one-time `GET /services/data/vXX.0/flowbuilder/flow-test/debug-run-as-validation` pre-flight when debugging as another user. Each call is one Aura call. Cap run iterations at 10 before pausing to summarize and ask for direction.
-- **Debug as another user.** To run the interview as a different user (`debugAsUserId` on `dispatch(method: "POST", url: "/services/data/vXX.0/flowbuilder/flow-test/debug-interview")`), call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow-test/debug-run-as-validation")` FIRST as a pre-flight guard — pass `flowVersionId` or `flowDevName`; it returns `{showIsDebugAsUserAllowed, showIsDebugAsUserAllowedInNonPrd}` (NOT `{canDebug}`), validating the debug-**as-another-user** permission (prod + non-prod). Only pass `debugAsUserId` when allowed.
-- This workflow is **per-session**: state (`interviewId`, last inputs, last trace) does not persist across Aura sessions. If the user wants persistence, that's exactly what the promotion offer in Phase 3 is for.

package/skills/automation-flow-coordinate/references/recipes/testing/workflows/promote.md

@@ -1,255 +0,0 @@
----
-id: flow.recipes.testing.workflows.promote
-description: "Debug-to-test promotion bridge — converts a satisfactory debug run into a persistent FlowTest record. Skips Phases 1–2 of author-test (intent and plan are already established by debug iteration); enters at Phase 3 (Build) with debug context."
----
-
-<!-- Consumers: debug.md (Phase 3 hand-off), testing router (direct entry when user says "promote my last debug run") -->
-
-# Promote a debug run to a saved FlowTest
-
-A transition workflow, not a workflow in the same sense as author-test or debug. The user has already done the iteration in `[[flow.recipes.testing.workflows.debug]]` and decided the run is worth keeping. Promote does the narrow save-as-test eligibility check, builds the payload (two routes available), validates, saves, and verifies.
-
-## Why promotion skips Phases 1–2 of author-test
-
-The author-test pipeline's first two phases are about **establishing intent and a test plan**. Promotion arrives with both already established:
-
-- **Intent** — the user iterated until the run was right. The trace observed in debug *is* the intent.
-- **Plan** — the inputs used in the final debug iteration *are* the plan. The user already approved them implicitly by saying "save this".
-
-Re-running Phases 1 and 2 here would be redundant ceremony. Promotion lands directly at the **Build** equivalent (Phase 3 of author-test) with the debug context as the seed payload. The Reviewer (Phase 4) and Save & Run (Phase 5) phases of author-test still execute, because the payload still has to pass the server's save-time validation and the run still has to confirm the assertions — regardless of how the payload was constructed.
-
----
-
-## Inputs from caller
-
-From `[[flow.recipes.testing.workflows.debug]]` Phase 3 hand-off, OR direct from the testing router:
-
-- `interviewId` — the debug run to promote (most recent if router-direct).
-- `serializedInterview` (Route B only) — the serialized debug-run interview blob captured from the run. `POST /services/data/vXX.0/flowbuilder/flow-test/actions/generate-from-debug-run` requires this blob, **not** the `interviewId`. If it wasn't captured, Route B is unavailable — use Route A.
-- `inputs` — the input set used in the final debug iteration (record ID, input variables, scheduled path, etc.).
-- `trace` (optional) — what was observed; used to suggest assertions.
-- `flowVersionId` — pin the test to the version that produced the satisfactory run.
-- `paused` — `true` when the debug run paused at a Wait element at any point (including runs that were later resumed). Defaults to `false`.
-
----
-
-## Step 1 — Eligibility check (narrow)
-
-Promotion eligibility is **narrower** than debug eligibility. Debug works for many flow shapes that cannot host a saved `FlowTest` record. Re-run the eligibility probe from `[[flow.recipes.testing.workflows.author-test]]` Phase 1:
-
-- Confirm `processType` is `AutoLaunchedFlow`.
-- Confirm `triggerType` is in `{RecordBeforeSave, RecordAfterSave, None}` (or absent for non-triggered).
-- If not in the confirmed-supported set, call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/schema/flow-capabilities", queryParams: { processType, triggerType })` (read `.flowFeatures`) and check for the literal `"FlowTesting"` capability.
-
-If the flow is **not** save-eligible (e.g., screen flow, scheduled autolaunched), STOP. Surface to the user: "This flow can be debugged interactively but cannot be saved as a `FlowTest` in this org. The debug run scenario is not lost — you can re-iterate via debug, but there's no persistent test artifact available for `<processType>` × `<triggerType>` flows." Hand back to the testing router.
-
-If the user is in silo mode (rare for promotion — most debug runs use real records), additionally probe `"FlowTestingWithDataSilo"`.
-
----
-
-## Step 2 — Choose the build route
-
-Two routes produce the same `FlowTest` record. Route choice affects how the payload is built, not what it contains.
-
-**If `paused` is `true`, use Route A and skip the choice below.** The server's conversion (Route B) returns nothing for a paused interview and only ever builds a test with assertions, and assertions derived from a run that crossed a Wait aren't reliable. Build the payload with `assertions: []` and `testType: "WithoutAssertion"`. Set `doesTestWaitElement: true` so the saved test pauses at the Wait when replayed, as the debug run did. Then tell the user in one sentence: "This run paused at a Wait, so it can only be saved as a test without assertions." Do not offer to add assertions from the trace.
-
-### Route A — Clean (default, recommended)
-
-Re-state the inputs through the payload-builder — same construction as authoring from scratch, just seeded with debug inputs instead of user-stated intent.
-
-Use Route A when:
-- Debug inputs are simple (single record ID, a few scalar input variables, no scheduled path picks).
-- The user wants to add or refine assertions beyond what the run produced.
-- You want full control over `fullName`, `label`, and `doesCommitChanges`.
-
-### Route B — Shortcut
-
-`POST /services/data/vXX.0/flowbuilder/flow-test/actions/generate-from-debug-run` with the `serializedInterview` (the serialized debug-run interview). Continue only when the response has `isSuccess === true` and a string `flowTestJson`; parse that JSON-encoded string before reviewing or editing the generated definition.
-
-Use Route B when:
-- Debug inputs are **complex enough that retyping is error-prone** — large or relational `sobjectValue` payloads, multiple scheduled-path attempts, autolaunched flows with many input variables.
-- You want the returned draft as a starting point; inspect the parsed payload and retain assertions only when they are actually present and match the user's intent.
-
-Treat the shortcut's return as a draft, not a finished payload. Always pass it through Reviewer (Step 4) before save.
-
-Ask the user once if route is ambiguous. Default to Route A when input complexity is low.
-
----
-
-## Step 3 — Build the payload
-
-Load `[[flow.recipes.testing.shared-stages.payload-builder]]`.
-
-### Route A construction
-
-Same as `[[flow.recipes.testing.workflows.author-test]]` Phase 3:
-
-1. Top-level metadata. Pin a **real** record ID (not the throwaway `sobjectValue: "{}"` that interactive debug allows). For non-triggered flows, copy the input variables verbatim from the debug iteration.
-2. `testPoints[]` with the Start element parameters mapped from debug inputs:
-
-| Debug input | `testPoints[]` parameter |
-|---|---|
-| Trigger record's "before" snapshot | `{ leftValueReference: "$Record", type: "InputTriggeringRecordInitial", value: { sobjectValue: "<JSON>" } }` |
-| Trigger record's "after" snapshot (update flows) | `{ leftValueReference: "$Record", type: "InputTriggeringRecordUpdated", value: { sobjectValue: "<JSON>" } }` |
-| Scheduled path used | `{ leftValueReference: "ScheduledPathApiName", type: "ScheduledPath", value: { stringValue: "<path API name or ''>" } }` |
-| Input variable used (non-triggered flows) | `{ leftValueReference: "<varName>", type: "InputVariable", value: { ... } }` |
-
-3. Assertions — derive from observed trace if the user wants regression coverage. If the user only wants to lock in "this scenario passes", `assertions: []` is acceptable (`WithoutAssertion` semantics).
-
-Lazy-load flowtest-element files as needed: `[[flow.recipes.testing.flowtest-elements.parameters]]`, `[[flow.recipes.testing.flowtest-elements.assertions]]`, `[[flow.recipes.testing.flowtest-elements.silo-config]]`.
-
-### Route B construction
-
-1. Call `dispatch(method: "POST", url: "/services/data/vXX.0/flowbuilder/flow-test/actions/generate-from-debug-run")` with `serializedInterview`.
-2. Require `isSuccess === true` and a string `flowTestJson`, then parse it. If either field is missing/malformed or JSON parsing fails, surface the raw response and use Route A instead.
-   Inspect its test points, parameters, and any pre-populated assertions.
-3. Review any generated assertions against the user's requirements. Show the user the assertion list and ask which to keep.
-4. Set `fullName`, `label`, `doesCommitChanges` (the shortcut may return defaults; override per naming conventions below).
-5. Serialize the edited complete definition again: `flowTestJson = JSON.stringify(flowTest)`.
-
----
-
-## Step 4 — Validate
-
-Load `[[flow.recipes.testing.shared-stages.reviewer]]`.
-
-Reviewer applies the same two jobs as in author-test Phase 4 — cheap local auto-fixes, and the intent check the server can't make. Two intent-class concerns are specific to promotion (both are cases where the payload would *save and resolve* but isn't the durable test the user meant — exactly what the server can't catch):
-
-- **Throwaway record IDs.** If the debug run used `sobjectValue: "{}"` and the user didn't pin a real record in Step 3, `BLOCK` and ask for a real ID. A `{}` binding is a debug-only placeholder, not a persistent test scenario.
-- **Silo `Id`s in the payload.** If silo mode and the debug run captured silo record `Id`s into `sobjectValue`, `BLOCK` — silo IDs resolve at save but aren't stable across silo rebuilds. Re-bind via the `jsonValue` envelope with the external-key fields per `[[flow.recipes.testing.flowtest-elements.silo-config]]`.
-
-Anything structurally malformed in a Route B payload (bad `type` enums, stale references after a version change) is caught by the server on save — don't pre-check it here; the Step 5 save-and-react loop owns it.
-
----
-
-## Step 5 — Save
-
-`POST /services/data/vXX.0/flowbuilder/flow-test` with body `flowTestJson`, which must be the JSON-encoded
-string produced after the final edits. Continue only when
-`isSuccess === true` and `flowTestId` is a non-empty string; capture that
-`320xxx` ID.
-
-On `isSuccess === false`, surface each available error's `message` and
-`statusCode`; target a field only if the message identifies one. If status
-or a usable ID is missing, surface the raw response and stop because the
-create outcome is unproven. A confirmed success means the payload resolved,
-but the runtime probe in Step 6 is what proves the assertions hold.
-
----
-
-## Step 6 — Verify (round-trip)
-
-**Invariant — no broken test lingers in the org without the user's
-say-so.** Same rule as author-test Phase 5: every terminal failure of
-this step pauses for a user decision, and keeping a broken `320xxx`
-is only acceptable when the user explicitly asks for it. Terminal
-failure covers both **execution failed** (persistent missing/empty `results` or a server error after
-retry — the promoted payload can't be made to run) and any returned
-descriptor whose `testStatus` is missing or is not exactly `Pass`; both
-route through the **Terminal
-failure — user chooses cleanup** section at the end of this step.
-Because promotion always starts with a `POST /services/data/vXX.0/flowbuilder/flow-test` (first-time save) and has no
-prior passing state, the cleanup choice is **delete-or-keep** —
-rollback doesn't apply here. The debug `interviewId` is preserved
-either way for a follow-up promotion (usually Route A after a Route
-B failure).
-
-The single carve-out is when the user framed the failing scenario as
-the artifact they want — a regression pin locking in a known fault,
-not a bug in the promoted test. Confirm intent once before honoring
-the carve-out ("you want to keep this failing promoted test as-is as
-a regression pin, right?"); on confirmation, skip the cleanup prompt.
-
-1. **Run immediately, then self-correct (cap at ONE silent retry).** `POST /services/data/vXX.0/flowbuilder/flow-test/actions/run` with `flowVersionId` (the pinned version — **required**), `testIds: ["320..."]`, and `showTrace: true`. Read per `[[flow.recipes.testing.run-results]]`. Same loop as author-test Phase 5:
-   - Missing/empty `results` or a server error → surface the raw response. Round-trip via `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow-test/{id}")`, parse `flowTestJson`, and compare it with what was sent. Apply one fix only if the comparison proves a discrepancy, then call `dispatch(method: "PATCH", url: "/services/data/vXX.0/flowbuilder/flow-test/{id}")` with `{id, flowTestJson: JSON.stringify(completeDefinition)}`. Re-run only when the update returns `isSuccess === true`; otherwise surface its errors or raw response and hand off to terminal failure. **If the second run still fails**, hand off to the Terminal failure section below.
-   - `testStatus: "Pass"` → success for the documented run-result contract.
-   - Any descriptor whose `testStatus` is missing or is not exactly `Pass` → report `lastRunFailedAssertions`, `lastRunError`, and `interviewErrors` when present. Do not auto-retry; hand off to Terminal failure.
-2. **Round-trip.** Call `dispatch_readonly(method: "GET", url: "/services/data/vXX.0/flowbuilder/flow-test/{id}")` and parse its `flowTestJson` string to see the server-canonical definition — important when Route B was used and you want to compare what the server stored with the shortcut output.
-3. **Audit registration (best effort).** Scope `GET /services/data/vXX.0/flowbuilder/flow-test` with `flowVersionId`, an explicit `limit`, and `offset: 0`. Continue only when `flowTests` is an array. If the ID is absent and the page length equals `limit`, advance `offset` by the number of returned rows until the ID appears or a short/empty page ends the list. An absent or malformed `flowTests` makes the listing outcome unproven. Do not infer a per-test version field from the summary, and do not let a listing miss override a confirmed successful create.
-4. **Coverage limitation.** No coverage operation is onboarded to MCP.
-   Do not attempt a coverage call; state the limitation if the user asks.
-
-### Terminal failure — user chooses cleanup
-
-Reached from Step 1's failing branches once the one-shot self-correct
-budget is exhausted (persistent missing/empty `results` or a server error — the test can't be made
-to run), or immediately for any descriptor whose `testStatus` is missing
-or is not exactly `Pass`. Skipped only after the user confirms the
-fault-path carve-out from the top of this step.
-
-1. **Surface the failure.** Report to the user:
-   - (a) the verbatim run signal — `testStatus`, `lastRunFailedAssertions`,
-     `lastRunError`, `interviewErrors`, the retrieved-vs-sent diff, or the
-     raw absent/empty `results` response;
-   - (b) the specific field(s) implicated only when the response identifies
-     them;
-   - (c) the current org state — the `320xxx` id.
-
-2. **Ask the user how to handle the artifact:**
-
-   > This promoted test is broken as saved. How do you want to handle it?
-   > - **delete** — remove the `320xxx` from the org.
-   > - **keep** — leave it in place for hand-editing; I'll report the
-   >   `320xxx` and the failure trace.
-
-   Silence is not consent — wait for a reply. For Route B failures,
-   also mention that Route A (clean re-state from the same debug
-   `interviewId`) is a robust redo path once cleanup is done — but do
-   not conflate that recommendation with the delete/keep choice.
-
-3. **Execute the choice:**
-   - **delete** → `DELETE /services/data/vXX.0/flowbuilder/flow-test/{id}` with the CURRENT
-     promotion's `320xxx` as the path `id` (single id per call —
-     there is no bulk delete). Promotion is one-shot per `interviewId`
-     (see Notes for callers), so there is never more than one id in
-     scope here. Report deletion only when `isSuccess === true`. On
-     `false`, surface `errorMessage` when present; when status is missing,
-     report the delete outcome as unproven. The parent flow is untouched.
-   - **keep** → leave the artifact in place; report the `320xxx`, the
-     failure trace, and the pointer to `DELETE /services/data/vXX.0/flowbuilder/flow-test/{id}`
-     for later cleanup if the user changes their mind.
-
-4. **Offer a redesign.** After cleanup, ask whether to retry the
-   promotion with adjusted inputs, switch build route (A ↔ B), or
-   stop. Registration is skipped under the delete branch. Coverage
-   retrieval is unavailable through MCP in every branch.
-
----
-
-## Naming conventions for promoted tests
-
-- **`fullName`.** Server-validated. Convention: `<FlowApiName>_<scenario_slug>`. For promoted runs, suffix with `_from_debug` or the date if the user wants provenance: `Update_Account_Name_To_BAC_TEMP_20260521_save_as_test_try1` — note the `_TEMP_` from the parent flow flows through automatically via `flowApiName`.
-- **`label`.** Human-facing, shown in the Test runner UI. Short imperative phrases beat reused dev-name slugs. The debug iteration's intent is good source material — "Account name updates to BAC for active customers" beats "save as test try1".
-- **`doesCommitChanges`.** Default `false` (rollback) on this endpoint. Promote inherits the debug session's DML mode preference: if the user iterated with rollback pinned explicitly (`enableRollbackMode:true` on the argument-driven endpoint, or `doesCommitChanges:false` on the payload-driven endpoint), the promoted test should also roll back. Only `true` when downstream effects can't be observed without persisted state — confirm explicitly with user.
-- **`flowApiName`.** Inherited from the parent flow. The `_TEMP_<YYYYMMDD>` suffix flows through automatically; no manual handling needed.
-
----
-
-## Error recovery
-
-**Ineligible flow (debug works, save doesn't).** Surface in plain language. Do not call `POST /services/data/vXX.0/flowbuilder/flow-test` / `PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` — it will fail server-side with a `FlowTesting` capability error and consume Aura quota. Hand back to the testing router; user keeps the debug context but no test is produced.
-
-**Shortcut returns malformed payload.** Generation or save can surface it through `isSuccess: false` and optional error messages. Target a field only when a returned message identifies one. Two options:
-- Switch to Route A (clean re-state) using the same debug inputs — robust fallback.
-- When the response identifies a field, hand-edit it and re-save; otherwise surface the raw response instead of guessing.
-
-**Save succeeds, but the run has missing/empty `results` or a server error.** The OAS does not define the cause. Surface the raw response, round-trip via `GET /services/data/vXX.0/flowbuilder/flow-test/{id}`, parse `flowTestJson`, and compare it with what was sent. Re-save via `PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` only when that comparison proves a concrete fix. Exhausting the one-shot retry hands off to Step 6's **Terminal failure — user chooses cleanup** section; the user picks delete or keep, and the workflow waits for their answer.
-
-**Save succeeds, run returns `testStatus: "Fail"` with populated `lastRunFailedAssertions`.** No auto-retry. Hand off immediately to Step 6's Terminal failure section: surface the returned summary, offer delete-or-keep, then act on the user's answer. When you present the choice, note that Route A is an available clean re-state path on the next attempt.
-
-**`fullName` collision.** A test with this name already exists. Ask the user whether to:
-- Update the existing test (`PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}`) — destructive if the existing test was someone else's.
-- Pick a different `fullName`.
-
-**`flowVersionId` doesn't match the active version.** The flow was activated on a new version between debug and promote. Tests are version-pinned. Either save against the version the debug ran on (good for snapshotting historical behavior), or warn the user and re-run debug on the new active version (good for forward regression). Default: pin to the version the debug ran on, surface the version drift to the user.
-
-**Aura session expired.** STOP, run `agentic-flow-poc-setup`. The debug `interviewId` may not be retrievable across the session boundary, which kills Route B. Route A still works because it only needs the inputs (which the caller passed in).
-
----
-
-## Notes for callers
-
-- Promotion is one-shot per call. If the user wants to promote multiple debug runs, call this workflow once per `interviewId`.
-- `DELETE /services/data/vXX.0/flowbuilder/flow-test/{id}` removes a promoted test (pass the 320-prefixed id as the path `id` — one id per call), but it never removes the parent flow — that still requires Setup → Process Automation → Flows. Warn the user if the flow is throwaway (`_TEMP_<YYYYMMDD>` suffix) — the flow cleanup is manual.
-- Route B (`POST /services/data/vXX.0/flowbuilder/flow-test/actions/generate-from-debug-run`) is **server-side conversion** and counts as one Aura call. Route A is zero MCP calls until Step 5 (save) — usually cheaper and easier to debug.
-- Worked example with literal payloads (the `Update_Account_Name_To_BAC` case): see `examples/debugPromote.json` and notes referenced in `[[flow.recipes.testing]]`.