@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-maestro-case/references/sdd-generation-rules.md

@@ -13,8 +13,10 @@ Reason the case shape from the process the user describes — **do not reach for
 **Secondary stage** (a.k.a. exception stage — `case-management:ExceptionStage`) — work that is **not a fixed step on the line**: it can fire at many points and only under a condition. Errors, escalations, rejections, rework loops, cancellations. Three rules define it, all CLI-enforced:
 
 - **No edges** — reached and exited purely by conditions, never wired by an edge. (True of every stage now that edges are retired; the legacy `CASE_MGMT_SECONDARY_STAGE_EDGES` validator that flagged secondary-stage edges is moot.) It is detached from any flow graph.
-- **Entered by its own condition**, evaluated continuously against case state — often *interrupting* (pauses active stages when it fires). It is reached because a condition became true, not because the case traversed an edge.
-- **Exits via `return-to-origin`** — routes the case back to the stage it interrupted, through the exit rule, not a new edge.
+- **Entered by its own condition**, never by an edge — but the entry shape depends on the lane's trigger:
+  - **(a) Mid-stage interrupt** — user-launched (`user-selected-stage`, paired with a `wait-for-user` exit) or external (`wait-for-connector`). Fires *while the origin is still active* and genuinely interrupts it.
+  - **(b) Decision/signal divert** — the **origin** stage carries a **gated diverting exit** (`Marks Stage Complete: No`, `IF` on the decision/signal, `exitToStageId` → this lane), and this lane's `selected-stage-exited(origin) + IF` entry **matches** it. Fires when the origin *exits* — a divert-and-return, NOT a true mid-stage interrupt. A variable-driven mid-stage interrupt is not expressible without a connector, so a decision- or signal-gated lane MUST use shape (b). See [§ Logical integrity step 5](#logical-integrity--stage-graph).
+- **Exits via `return-to-origin`** — routes the case back to the origin stage, through the exit rule, not a new edge. Requires `Interrupting: Yes`.
 
 Ask: *does this work belong at one fixed point (regular stage), or could it happen at several points / only on a condition (secondary stage)?* "Handle rejected application", "escalate on SLA breach", "rework loop" → secondary. Pull these out of the main flow; do not string them inline as ordinary stages.
 
@@ -40,7 +42,7 @@ The case, each stage, and each task move through a lifecycle gated by **rules**
 How to reason with these:
 
 - **`required-*` vs `selected-*`.** `required-tasks-completed` / `required-stages-completed` = "all items flagged required are done" (the `isRequired` flow). `selected-tasks-completed` / `selected-stage-completed` / `selected-stage-exited` = "these *specific named* items." Pairing rule (Key Rule 4): `Marks Complete: Yes` pairs only with `required-*`; `selected-*` is for `No` (routing / early exit / alternate disposition). A `Yes` + `selected-*` pair is a schema error.
-- **Secondary (exception) stage** uses **stage-entry + stage-exit rules only, never edges** (true of every stage now — edges are retired). Its entry rule is typically *interrupting* (`isInterrupting: true`); its exit uses `return-to-origin` to rejoin the flow it left.
+- **Secondary (exception) stage** uses **stage-entry + stage-exit rules only, never edges** (true of every stage now — edges are retired). Its entry rule is typically *interrupting* (`isInterrupting: true`); its exit uses `return-to-origin` to rejoin the flow it left. **For a decision/signal-routed lane, the routing lives on the *origin* stage:** a gated diverting exit (`Marks Stage Complete: No`, `IF` on the decision/signal, `exitToStageId` → the lane), with the origin's completion exit gated by the inverse `IF` so the two paths are mutually exclusive — see [§ Logical integrity step 5](#logical-integrity--stage-graph).
 - **First task in a stage** must carry `current-stage-entered` (emit it explicitly). `wait-for-connector` makes a gate pause for an inbound connector callback — its `conditionExpression` gates on **case state** only (no `event` payload; in-rule extract-then-gate is unsupported at runtime — gate a downstream condition instead); `adhoc` lets a *task* fire manually from the case app (task-entry only — never a stage-entry rule); `runs-sequentially` chains tasks in a lane.
 - **`user-selected-stage`** (stage entry) starts a stage on demand by a user rather than by flow. The CLI validator requires it to pair with a `wait-for-user` stage exit elsewhere: a `wait-for-user` exit with no `user-selected-stage` entry — or a `user-selected-stage` entry with no `wait-for-user` exit — fails `validate`.
 
@@ -188,6 +190,8 @@ Defines what `sdd.md` Section 1 (Case Definition) must contain.
 | Priority | optional | `Low` / `Medium` / `High` / `Critical` | Default `Medium`; record in source ledger. |
 | Case SLA | conditional | Duration (e.g., `5 business days`) | `—` when case has no SLA; otherwise block Approve. |
 | SLA Type | conditional | `time-based` (single unconditional duration) / `condition-based` (one or more conditionExpression-keyed overrides + a default time-based row) | Default `time-based` when Case SLA set with no per-condition overrides. The FE persists `condition-based` whenever ≥ 1 `slaRules[]` entry carries a non-empty `conditionExpression` (see PO.Frontend `CaseManagementSlaProperties.tsx:27-30`). `condition-based` requires populating the §Variable SLA Rules table; `time-based` omits it. |
+| Case App | optional | `Enabled` / `Disabled` — whether the in-product Case App UI is on (`metadata.caseAppEnabled`). | Default `Disabled`; record in source ledger. |
+| Task-output passing | optional | `Direct` / `Shared` — `metadata.caseDirectlyPassTaskOutputs`. `Direct` passes a task's outputs straight to downstream tasks (default). | Default `Direct`. |
 
 ### 1.2 Case-level SLA escalation
 
@@ -275,7 +279,9 @@ Optional. `Marks Case Complete: No`. Used for ExceptionStage terminals (Withdraw
 
 ### 1.5 Case Variables
 
-Every variable used anywhere in the plan (task inputs / outputs, conditions, mappings, exit rules) appears in this table. Authoring is **declarative** — the row's `Category` + `sourceTriggers` + `sourceFields` columns drive build-time classification. Inference from prose or other columns is no longer supported.
+**What goes in §1.5 (the declare-vs-xref decision — apply per candidate value):** ONLY (a) `In` / `Out` arguments, (b) trigger-payload `Variable`s (`sourceTriggers` + `sourceFields`), and (c) case-level state read by a condition (`IF`) or consumed in **≥ 2 places**. **An input that is just one upstream task's output is NOT a §1.5 variable** — reference it directly (whole-value `<- "Stage"."Task".out`, or in-expression `vars.$xref('Stage','Task','out')`); the emitting task self-declares the output and is its own producer (see [§ Variable lineage closure → Task-output direct reference](#variable-lineage-closure) and [§ Resolved-resource I/O completeness → xref carve-out](#resolved-resource-io-completeness)). Minting a row to relay one task's output into one downstream consumer is the **case-var relay anti-pattern** — declare a row for an output only to rename it, set a custom `Default` / `Type` / `Description`, or expose it as case-level state read in multiple places.
+
+A variable used anywhere in the plan that meets the test above appears in this table. Authoring is **declarative** — the row's `Category` + `sourceTriggers` + `sourceFields` columns drive build-time classification. Inference from prose or other columns is no longer supported.
 
 | Column | Required? | Notes |
 |---|---|---|
@@ -293,6 +299,8 @@ Every variable used anywhere in the plan (task inputs / outputs, conditions, map
 - **`Out`** — case argument returned to caller. Value comes from a producer (a task's Outputs row that targets this Name via `-> {name}` or `{name} = {expr}`) OR from `Default` when no producer fires. `sourceTriggers` MUST be empty (direction mismatch: trigger → case is forbidden for `Out`).
 - **`Variable`** — case-internal state. Populated by one trigger's payload (`T<N>` + single path), multiple triggers sharing the same slot (CSV + keyed `T<N>: <path>` format), a task's Outputs row, or `Default` only.
 
+**Config-as-`In` pattern.** Business rules the case needs at runtime — priority bands, approval thresholds, exception taxonomy, payment controls — can be carried as a single `In` variable of `Type: string` whose `Default` is a JSON object, overridable at case start and consumed by agents (e.g. `businessRulesJson`). This gives business logic a first-class, replicable home in the SDD instead of scattering it across prose. Use `string` for the JSON-shaped value (never `json`). For a genuinely structured payload that the FE picker must navigate, use `Type: jsonSchema` and carry its schema in the variable's `body` — a `jsonSchema`/`file` variable without a `body` cannot have its sub-fields picked.
+
 **`sourceFields` notation:**
 
 - **Single-trigger:** bare path. `response.subject`, `response.user.id`, `Error.code`.
@@ -347,7 +355,9 @@ The trailing `` `{stage_id}` `` (e.g., `` `stage-intake` ``) MUST appear so read
 
 ### Stage Completion Conditions table (`Marks Stage Complete: Yes`)
 
-Completion (`Yes`) rows and the §Stage Exit Conditions (`No`) rows below render **together** as the single **Stage Exit Conditions** table in `sdd.md` (per [sdd-template.md](../assets/templates/sdd-template.md)). Shared columns, in order: `WHEN | IF | Exit Type | Marks Stage Complete | Display Name`. ≥ 1 completion row required. **Stage-to-stage routing is NOT carried here** — each destination stage declares the link via its own Entry Condition (`selected-stage-completed("This Stage")` / `selected-stage-exited("This Stage")`), so one stage can fan out to N stages.
+Completion (`Yes`) rows and the §Stage Exit Conditions (`No`) rows below render **together** as the single **Stage Exit Conditions** table in `sdd.md` (per [sdd-template.md](../assets/templates/sdd-template.md)). Shared columns, in order: `WHEN | IF | Exit Type | Marks Stage Complete | Display Name`. ≥ 1 completion row required. **Regular stage-to-stage routing is NOT carried here** — each destination stage declares the link via its own Entry Condition (`selected-stage-completed("This Stage")` / `selected-stage-exited("This Stage")`), so one stage can fan out to N stages.
+
+> **Carve-out — routing INTO a decision/signal-routed exception lane IS carried here.** This is the one case where the origin stage carries the route: add a **gated diverting exit row** (`Marks Stage Complete: No`, WHEN `selected-tasks-completed("<decider task>")`, `IF` on the decision/signal, `Exit Type: exit-only`, `exitToStageId` → the exception stage) AND gate this stage's completion row with the **inverse `IF`** so completion and divert are mutually exclusive. Without the diverting exit, the decision path either dual-fires (ungated completion → both the next stage and the lane enter) or deadlocks (gated completion with no alternative exit). See [§ Logical integrity step 5](#logical-integrity--stage-graph) and the worked example below.
 
 | WHEN | IF | Exit Type | Marks Stage Complete | Display Name |
 |---|---|---|---|---|
@@ -394,6 +404,20 @@ In plan order. ≥ 1 task per stage.
 
 Required-Tasks cells in completion / exit conditions use the bare task ids (`t10, t12, t13`) so readers grep across the document.
 
+### Deterministic stage completion (conditional-branch & re-entered stages)
+
+When a stage's real work is split across **mutually-exclusive conditional tasks** (e.g. one `action` per reason code, each entered via `current-stage-entered` + an `IF`), those tasks MUST be `Required: No` — only one runs per case, so none can be the stage's required completer (a `required-tasks-completed` exit over only-conditional tasks is the §Finalization step 17 footgun). Add a **single required convergence task** (typically an `api-workflow` that persists the resolution) whose entry condition is a DNF OR covering every path:
+
+| WHEN | IF | Display Name |
+|---|---|---|
+| `current-stage-entered` | `=js:(<none of the conditional guards hold>)` | No specialist branch |
+| `selected-tasks-completed("<Conditional Task A>")` | — | — |
+| `selected-tasks-completed("<Conditional Task B>")` | — | — |
+
+The convergence task is the stage's only `Required: Yes` task, so `required-tasks-completed` resolves deterministically whichever branch ran — including the no-branch case. (Worked example from a shipping SDD: an Exception-Resolution stage with per-reason-code action tasks + a `Persist exception resolution` api-workflow convergence task carrying exactly the three rows above.)
+
+**Re-entry safety (`return-to-origin` loops).** A task in a stage that an exception lane returns to via `return-to-origin` **re-runs on re-entry** unless flagged `Run Only Once: Yes`. Set `Run Only Once: Yes` on any such task whose re-execution would clobber a decision made during the exception (e.g. an AP-review task whose decision variable the escalation lane just overwrote) — the returning stage then re-evaluates its exit against the lane's decision without re-prompting the original actor. This is the one case where `Run Only Once` is load-bearing rather than cosmetic.
+
 ## Task content rules
 
 Defines per-task detail blocks. Every task opens with an **Entry Condition** block. Additional blocks depend on task type.
@@ -437,7 +461,7 @@ Multiple entry conditions render as multiple rows (DNF outer-OR). When `current-
 
 **HITL Implementation:** the action plugin requires a deployed Action App from `action-apps-index.json` (Action App ID + Deployment Folder). When no matching deployed app exists, the task falls back to a Rule-8 placeholder — the SDD should either use a deployed app, or use a different task type (`process` / `agent` / `api-workflow`) that doesn't require HITL.
 
-**Input/Output Schema fidelity.** The Input Schema and Output Schema `Field` cells MUST be a subset of the resolved app's actual schema (from `uip maestro case tasks describe --type action --id <actionAppId>`, fetched at Resolve and persisted in `tasks/registry-resolved.json`). Never author a field the deployed app does not expose — it cannot bind (the io-binding plugin has no `data.inputs[]` slot to write into). A field the user described but the app lacks → Ask (deploy a task-specific app / drop the field / placeholder), never silently author it. Reusing ONE app across ≥ 2 action tasks with divergent declared Input Schemas is the generic-substitute anti-pattern — see §Architect's lens `rev_substitute_app` and §Finalization step 16.
+**Input/Output Schema fidelity.** The Input Schema and Output Schema `Field` cells MUST be a subset of the resolved app's actual schema (from `uip maestro case tasks describe --type action --id <actionAppId>`, fetched at Resolve and persisted in `tasks/registry-resolved.json`). Never author a field the deployed app does not expose — it cannot bind (the io-binding plugin has no `data.inputs[]` slot to write into). A field the user described but the app lacks → Ask (deploy a task-specific app / drop the field / placeholder), never silently author it. **Code-switched app (sanctioned — do NOT flag):** reusing ONE deployed app across many `action` tasks is correct and expected when each task carries a **distinct `actionType`** dispatch value and its declared fields are a **subset of the app's schema**. This is the normalized human-decision-app pattern — a single app whose code-behind switches on `actionType` and renders the right form; a full case routes every human decision through it (the working aged-invoice case uses one app across all 7 of its action tasks). It is the generic-substitute anti-pattern ONLY when tasks reuse the app **without** a distinct `actionType`, or declare a field the app does not expose (won't bind) — see §Architect's lens `rev_substitute_app` and §Finalization step 16.
 
 **Recipient encoding** (typed prefix is the only allowed format):
 
@@ -505,14 +529,19 @@ Every `case-management` task triggers the §Soft redirect during Phase 0 thresho
 
 ### `process` / `agent` / `rpa` / `api-workflow` task — required cells
 
-These four runnable types share a single render block — the SDD surfaces only the binding contract, not the per-type runtime metadata.
+These four runnable types share a single render block. The SDD surfaces the binding contract **plus the resolved resource identity** — name + folder are REQUIRED so the document is replicable standalone (a reader must know *which* deployed resource the task invokes, not just its I/O contract).
 
-| Cell | Value |
-|---|---|
-| Inputs | Table: `Field | Type | Binding` — `Field` MUST match the runnable's declared In argument name verbatim; `Binding` per §Binding cell |
-| Outputs | Table: `Field | Binding / Value` — `Field` MUST match the runnable's declared Out argument name verbatim for `->` rows (or `—` for `=` rows); see §Outputs cell operators |
+| Cell | Required? | Value |
+|---|---|---|
+| Resolved Resource | yes | The deployed resource `name` (the `name`-binding default) — e.g. `AgedInvoiceMockIntegrationApi`, `InvoiceTriageAgent`. `<UNRESOLVED>` only when Resolve was skipped / returned 0 matches (pair with a `high` review item). |
+| Folder Path | yes | Resolved `folders[0].fullyQualifiedName` (the `folderPath`-binding default). Never a parent path — the exact resource folder, or the job faults at runtime. |
+| Resource Identity | recommended | Resolved id (+version): `apiWorkflowId` / `agentId` / `processOrchestrationId`. Carried here for standalone replicability AND in `tasks/registry-resolved.json`. `<UNRESOLVED>` when not resolved. |
+| Binding Sub-Type | yes | `resourceSubType` on the bindings: `Api` (api-workflow) / `Agent` (agent) / `ProcessOrchestration` (process) / `—` (rpa). Omitting it makes Studio Web report the resource as not found. |
+| Dispatch / Operation | conditional | When the resource is a shared façade dispatched by a parameter (e.g. one mock-integration api selected by `requestSource`, one code-switched action app), name the selector + value (`requestSource = "RegisterCaseShell"`). `—` for single-purpose resources. Also appears as an Inputs row (literal binding). |
+| Inputs | yes | Table: `Field | Type | Binding` — `Field` MUST match the runnable's declared In argument name verbatim; `Binding` per §Binding cell |
+| Outputs | yes | Table: `Field | Binding / Value` — `Field` MUST match the runnable's declared Out argument name verbatim for `->` rows (or `—` for `=` rows); see §Outputs cell operators |
 
-**Where per-type metadata lives.** The rendered SDD does NOT carry per-type runtime cells (agent prompt, RPA package version, api-workflow endpoint, process release tag). That metadata is resolved during §Resolve in [phase-0-interview.md](phase-0-interview.md#resolve) and persisted in `tasks/registry-resolved.json` under the task's resolution entry (per SKILL.md Rule 9 shape). Phase 1 reads it from there when emitting `caseplan.json`. Mapping:
+**Where the rest of the metadata lives.** Deep per-type runtime metadata that does NOT affect replication of the case plan (agent system prompt, RPA package version, api-workflow endpoint URL, process release tag) stays out of the SDD body — it is resolved during §Resolve in [phase-0-interview.md](phase-0-interview.md#resolve) and persisted in `tasks/registry-resolved.json` under the task's resolution entry (per SKILL.md Rule 9 shape). The SDD carries the resource **name + folder + id + sub-type** (above); Phase 1 reads the deeper metadata from `registry-resolved.json` when emitting `caseplan.json`. Mapping:
 
 | Task type | Registry source | Identity field in `registry-resolved.json` |
 |---|---|---|
@@ -538,6 +567,7 @@ Every Inputs `Binding` cell carries one of (case-sensitive):
 | `=vars.<id>.<subfield>` | Sub-field of a structured case variable (dot-path) |
 | `=bindings.<id>` | Registered resource (action app, process, connection) |
 | `=metadata.<key>` | Case metadata |
+| `=metadata.ExternalId` | **The platform-generated case identity** — the canonical binding for any task input named `caseId`. The case external id is minted by the platform (constant prefix or external expression) and exposed as `metadata.ExternalId`; it is **NOT** a task output. Bind `caseId` to `=metadata.ExternalId`; **never** add a `-> caseId` extraction on a workflow whose `data` payload has no `caseId` key — that extraction resolves to runtime null (a documented v4→v5 fix on a working case). Agents, the case mirror, and all write-backs key off `=metadata.ExternalId`. |
 | `=trigger.<field>` | Trigger payload field |
 | `=js:<expr>` | Inline JavaScript (REQUIRED when operators are involved) |
 | `=jsonString:<json>` | JSON literal as string (used for `essentialConfiguration` carry-through) |
@@ -576,6 +606,35 @@ Every Outputs `Binding / Value` cell carries one of two operators (case-sensitiv
 
 For worked patterns by Category and operator, see [`sdd-template-examples.md`](../assets/templates/sdd-template-examples.md).
 
+### Resolved-resource I/O completeness
+
+When a task resolves to a **live** resource (`process` / `agent` / `rpa` / `api-workflow` / `action` / `execute-connector-activity` / `wait-for-connector` / `case-management`), the SDD's binding contract MUST cover that resource's declared I/O — not merely match names verbatim where rows exist (§Binding cell, §Outputs cell). The declared contract is the one pulled at §Resolve in [phase-0-interview.md](phase-0-interview.md#resolve) (`tasks describe` for runnables, `spec` for connectors) and persisted — including each input's `required` flag and the full output-field list — in `tasks/registry-resolved.json`. Coverage is two-directional:
+
+**Inputs — required-coverage.** Every **required** declared input has an Inputs row whose `Binding` is non-empty (any allowed form in §Binding cell), OR is explicitly `<UNRESOLVED>` paired with a `high` review item (`rev_unbound_input_<task>_<field>`). A required input silently absent from the Inputs table is the defect this rule catches — it resolves to runtime null and faults the job. **Optional** declared inputs MAY be omitted; an optional input the user described but did not map → `medium` review item (existing §Resolve behavior). Never invent a `Default` to suppress an unmapped required input.
+
+**Outputs — field fidelity.** Every Outputs `-> caseVar` (extract) row's `Field` (its top-level leaf) MUST exist verbatim in the resolved output contract. A `Field` the resource does not emit → `high` review item (`rev_phantom_output_<task>_<field>`); it cannot bind. The case still binds outputs **selectively** — only the outputs it consumes need rows; this rule forbids referencing outputs the resource never produces, not under-consuming. (This generalizes the action-app-only fidelity rule, §Finalization step 16, to all runnable/connector types.)
+
+**xref carve-out — an upstream-output-fed input is *defined*, NOT a case variable.** When a required input is satisfied by an upstream task's output — whole-value `<- "Stage"."Task".out` (resolves to `=vars.<outputId>`) or in-expression `vars.$xref('Stage','Task','out')` — it counts as covered: do **NOT** raise a "missing variable" finding for it. The emitting task self-declares the output and is its own producer; declare a §1.5 row for it only per the [§ 1.5 declare-vs-xref test](#15-case-variables) (rename / custom `Default` / `Type` / `Description` / case-level state read in ≥ 2 places). See also [§ Variable lineage closure → Task-output direct reference](#variable-lineage-closure).
+
+Enforced at the Approve gate (§Variable lineage closure audit checklist + §Finalization step 19) and re-verified at build (Phase 3 io-binding Check 5, [`io-binding/impl-json.md`](plugins/variables/io-binding/impl-json.md#check-5--resolved-resource-io-completeness)). A task left `<UNRESOLVED>` (no resolved contract) is skipped by this rule — it has no declared I/O to check against.
+
+## Integrations content rules (Section 4)
+
+Section 4 is the **de-duplicated resource roll-up** — one subsection per resource family, so the case's full integration/resource footprint is replicable from the SDD alone (it mirrors the per-task `Resolved Resource` / `Folder Path` cells in Section 2). Render only the families whose task type appears; render `> None.` for an absent family when its absence is meaningful (e.g. "no IS connectors — all system calls go through an API workflow").
+
+| Subsection | Render when the case has… | Required columns |
+|---|---|---|
+| Integration Service Connectors | `execute-connector-activity` / `wait-for-connector` tasks | Connector, Connector Key, System, Connection (ID), Auth Method, Operations Used, Used By Tasks (+ per-connector Operations: Activity Type ID, Method, I/O fields) |
+| API Workflows | `api-workflow` tasks | Workflow, Folder, Resource ID (+version), Inputs → Outputs, Used By Tasks |
+| Agents | first-class `agent` tasks | Agent, Folder, Resource ID (+version), Inputs → Outputs (or "shared agent contract"), Used By Tasks |
+| Processes & RPA | `process` / `rpa` tasks | Resource, Type, Folder, Resource ID (+version), Used By Tasks |
+| Child Cases | `case-management` tasks | Child Case, Identifier Prefix, Wait for Completion, Used By Tasks |
+| External Agents | externally-hosted agents modeled as `api-workflow` / `execute-connector-activity` | Agent, Service Type, Endpoint, Used By Tasks |
+
+**De-dup rule.** One row per **distinct** resource, not per task. When a façade resource backs many tasks (one mock-integration API selected by `requestSource`, one code-switched action app by `actionType`), list the distinct selector values next to the task names in `Used By Tasks` (e.g. `Start case (requestSource=StartAgedInvoiceCase), Register shell (requestSource=RegisterCaseShell)`). Action apps render in their per-task Action blocks (Section 2), not as a Section 4 subsection — they are HITL surfaces, not system integrations — but the same de-dup + `actionType`-selector discipline applies there.
+
+**Resource identity is mandatory.** Every Section 4 row carries the resource's **folder + id** (`<UNRESOLVED>` + a `high` review item when Resolve could not bind it). A reader / coding-agent replicates from these, not from I/O contracts alone (§Finalization step 18).
+
 ## Variable lineage closure
 
 Every variable referenced in `sdd.md` must close — every consumer must have a producer that fires before it, OR the variable must carry a `Default` value that holds at case start.
@@ -638,6 +697,7 @@ Pattern X1 is preferred unless an actual connector emits the close event. When t
 6. **Stage-order closure.** For each consumer of `vars.<caseVar>`, identify producers (trigger-extraction, task Outputs row `->` or `=`). At least one producer's stage index ≤ consumer's stage index AND (same stage) task index < consumer's task index. If no producer exists, the §1.5 row MUST satisfy the `Category: In` or non-empty `Default` escape.
 7. **`->` row payload path present.** Every Outputs `-> {caseVar}` row has a non-empty `Field` cell (the runtime path). Every `=` row has `Field` exactly `—`.
 8. **Forbidden body vocabulary.** No occurrence in any narrative cell of: `Pattern C`, `bridge`, `companion`, `inputOutputs[]`, `=jsonString:` (outside connector `Operation Configuration` cells), `groupOperator`, `essentialConfiguration` (as prose), `savedFilterTrees`, `dispatcher`, `Phase 2 validator`, `Phase 3 dispatcher`, `Q10 II`, `Finding #N`, `io-binding`, `aliased into / from / back into`, `reassign`, `originalVar`, `auto-mint`. These are skill-internal terms — see [sdd-template.md § Output Rules](../assets/templates/sdd-template.md).
+9. **Resolved-resource I/O completeness** (§Resolved-resource I/O completeness). For each task resolved to a live resource (contract present in `tasks/registry-resolved.json`): every **required** declared input has a non-empty `Binding` row OR `<UNRESOLVED>` + a paired `high` review item; every Outputs `-> caseVar` row's `Field` exists verbatim in the resolved output contract. An upstream-output-fed input (whole-value `<-` or `vars.$xref(...)`) satisfies coverage with NO §1.5 row — do not flag it as a missing variable. Skip tasks left `<UNRESOLVED>` (no contract).
 
 Any failure → Phase 0 cannot Approve. Surface in edit-validation errors. AskUserQuestion `Re-edit` / `Restart` / `Abort`.
 
@@ -661,7 +721,7 @@ Severity:
 
 | Level | Definition | Examples |
 |---|---|---|
-| **high** | Blocks Phase 1 / `caseplan.json` build until resolved. | Missing `connectionId` for a resolved connector task; missing `actionAppId` for an `action` task; missing deployed `process` / `agent` / `api-workflow` for a runnable task; unresolved variable lineage; missing trigger config; compliance-override conflict the user has not reconciled. |
+| **high** | Blocks Phase 1 / `caseplan.json` build until resolved. | Missing `connectionId` for a resolved connector task; missing `actionAppId` for an `action` task; missing deployed `process` / `agent` / `api-workflow` for a runnable task; a resolved resource's **required** input left unbound (`rev_unbound_input_<task>_<field>`); an extract output naming a field the resource does not emit (`rev_phantom_output_<task>_<field>`); unresolved variable lineage; missing trigger config; compliance-override conflict the user has not reconciled. |
 | **medium** | Phase 1 can default with a prompt. | Missing SLA escalation recipient (default = owner group); missing variable default; ambiguous recipient (persona name without group resolution). |
 | **low** | Cosmetic. | Missing case-level description; missing exception-stage description; stylistic placeholder. |
 
@@ -697,9 +757,20 @@ Beyond schema-pairing checks (§Finalization step 1), the case must be a connect
 2. **Every stage exits.** Every primary stage must have either (a) a completion row (`Marks Stage Complete: Yes`) whose completion is consumed by a downstream stage's Entry Condition or a case-exit, OR (b) another primary stage whose Entry Condition references it (`selected-stage-completed`/`selected-stage-exited`), OR (c) feed an ExceptionStage. A stage no other stage (or case-exit) keys off → blocking error (terminal-loop stage).
 3. **Every case-exit row references a stage that exists.** No dangling `Required Stages` references.
 4. **Every `Required Stages` cell in §1.4 names ≥ 1 primary stage with `Required for case completion: Yes`.** Otherwise the case can never complete.
-5. **ExceptionStages must have ≥1 entry condition, each DISTINCT, chosen by trigger source.** Map the lane's *trigger* to the rule: a gate decision → `selected-stage-completed` / `selected-stage-exited` (+ `IF` on the decision var); a person launches it → `user-selected-stage`; an external event → `wait-for-connector`. `adhoc` is task-entry only — never a stage entry. Two ExceptionStages whose entry rules are identical (same rule type + `selectedStageId` + `conditionExpression`) fail `validate` (`CASE_MGMT_SECONDARY_STAGE_ENTRY_RULES_DUPLICATE`) — give each a distinct `selectedStageId` or `conditionExpression` guard. Set `Interrupting: Yes` for lanes that fire mid-stage (escalation, comms, withdrawal). Terminal lanes (Rejected / Withdrawn) exit `exit-only` and declare a §1.4a case-exit (`marks-case-complete: false`); return lanes (Escalation / Customer Comms) exit `return-to-origin`. **Decision-reachable lanes:** when any decision button's Behavior (or the user's stated intent) names an ExceptionStage as a destination ("route to / send to / escalate via the X lane"), that lane's entry conditions MUST include a `selected-stage-completed` / `selected-stage-exited` rule with an `IF` on the deciding variable's value. A lane described as decision-reachable but entered ONLY via `wait-for-connector` (no decision-keyed entry) is unreachable from its stated source → blocking error. A `wait-for-connector` entry may coexist as a separate trigger, but cannot be the lane's only entry when a decision is supposed to reach it.
+5. **ExceptionStages must have ≥1 entry condition, each DISTINCT, chosen by trigger source.** Map the lane's *trigger* to the rule: a gate decision → `selected-stage-completed` / `selected-stage-exited` (+ `IF` on the decision var); a person launches it → `user-selected-stage`; an external event → `wait-for-connector`. `adhoc` is task-entry only — never a stage entry. Two ExceptionStages whose entry rules are identical (same rule type + `selectedStageId` + `conditionExpression`) fail `validate` (`CASE_MGMT_SECONDARY_STAGE_ENTRY_RULES_DUPLICATE`) — give each a distinct `selectedStageId` or `conditionExpression` guard. Set `Interrupting: Yes` for lanes that fire mid-stage (escalation, comms, withdrawal). Terminal lanes (Rejected / Withdrawn) exit `exit-only` and declare a §1.4a case-exit (`marks-case-complete: false`); return lanes (Escalation / Customer Comms) exit `return-to-origin`. **Decision-reachable lanes:** when any decision button's Behavior (or the user's stated intent) names an ExceptionStage as a destination ("route to / send to / escalate via the X lane"), that lane's entry conditions MUST include a `selected-stage-completed` / `selected-stage-exited` rule with an `IF` on the deciding variable's value. A lane described as decision-reachable but entered ONLY via `wait-for-connector` (no decision-keyed entry) is unreachable from its stated source → blocking error. A `wait-for-connector` entry may coexist as a separate trigger, but cannot be the lane's only entry when a decision is supposed to reach it. **A `selected-stage-completed`/`selected-stage-exited` lane entry REQUIRES a matching origin diverting exit — the entry alone is not enough.** On the *origin* stage add a **gated diverting exit** (`Marks Stage Complete: No`, WHEN `selected-tasks-completed("<decider task>")`, `IF =js:(<signal> === <exception-value>)`, `exit-only`, `exitToStageId` → the lane) **and** gate the origin's completion exit with the inverse `IF` (`=js:(<signal> !== <exception-value>)`) so the two are mutually exclusive. Without the diverting exit the decision path either **dual-fires** (ungated completion → the next stage *and* the lane both enter) or **deadlocks** (gated completion with no alternative exit). `selected-stage-exited` fires *after* the origin exits, so this is a **divert-and-return, not a true mid-stage interrupt** — a genuine mid-stage interrupt needs `user-selected-stage` or `wait-for-connector` (mental-model shape (a)). Missing origin diverting exit, or a completion exit not mutually exclusive with it → blocking error.
 6. **Classify each secondary stage's `Interrupting` flag by whether it must halt active work.** `Interrupting: Yes` pauses the active stage(s) when the lane fires; `Interrupting: No` runs alongside them in parallel while the main flow continues. Choose the value from the lane's intent — does handling it require stopping the rest of the case, or can it proceed concurrently? Interrupting is independent of whether the lane is terminal or returning. The one hard rule: a `return-to-origin` exit **requires `Interrupting: Yes`** — the case can only return to a stage it interrupted, so a non-interrupting `return-to-origin` lane is incoherent → blocking error.
 
+**Worked example — decision/signal-routed return exception (AP Review → SLA Escalation).** The origin "AP Review" routes to the exception lane "SLA Escalation" on a `requiresEscalation` decision, then returns:
+
+| Stage | Condition | WHEN | IF | Exit Type | Marks Complete |
+|---|---|---|---|---|---|
+| AP Review | exit (complete) | `required-tasks-completed` | `=js:(vars.requiresEscalation !== true)` | `exit-only` | Yes |
+| AP Review | exit (divert) | `selected-tasks-completed("AP ownership review")` | `=js:(vars.requiresEscalation === true)` | `exit-only` (`exitToStageId` → SLA Escalation) | No |
+| SLA Escalation | entry | `selected-stage-exited("AP Review")` | `=js:(vars.requiresEscalation === true)` | — | — (`Interrupting: Yes`) |
+| SLA Escalation | exit | `required-tasks-completed` | — | `return-to-origin` | Yes |
+
+On escalate: the divert exit fires (completion's inverse `IF` is false), the case enters SLA Escalation, then `return-to-origin` re-activates AP Review for re-decision. On non-escalate: the completion exit fires and the next regular stage enters via its own `selected-stage-completed("AP Review")` entry. The decision (`requiresEscalation`) is read directly from the producing action's output — never relayed through a §1.5 variable.
+
 Failure on any step → blocking error in Finalization. AskUserQuestion `Re-edit` / `Restart` / `Abort`.
 
 ## Architect's lens
@@ -716,8 +787,9 @@ Phase 0's job is to surface execution-readiness gaps, not just schema validity.
 | **Missing happy-path exit on first stage** | The first primary stage has only routing exits (`Marks Stage Complete: No`) and no `required-tasks-completed` row | `rev_no_happy_path_<stage>`: "First stage has no happy-path completion — the case may not reach Stage 2 cleanly." |
 | **Decision-button outcome unread** | An `action` task with `is_decision: Yes` writes a case variable in its `Maps To` cell AND that variable is NOT consumed by any downstream condition / stage entry / task input / case exit | `rev_orphan_decision_<task>`: "Decision button writes `<var>` but no downstream rule reads it — branching has no effect on case path. Either consume the variable or downgrade `is_decision` to No." |
 | **Connector-task failure has no exception path** | `execute-connector-activity` / `wait-for-connector` task in a primary stage AND no ExceptionStage entered via `wait-for-connector` failure or task failure rule | `rev_no_failure_path_<task>` (`medium`; **`high`** when ≥ 2 connector tasks share a primary critical path with zero exception cover): "Connector activity in critical path with no exception-stage cover — runtime failure halts the case." |
-| **Generic action app reused as a substitute** | ONE resolved Action App ID bound to ≥ 2 `action` tasks with **divergent** declared Input Schemas | `rev_substitute_app_<app>` (`high`): "Generic action app reused across N tasks with different input schemas — declared fields will not bind. Deploy task-specific apps, or drop fields the app does not expose." |
+| **Generic action app reused as a substitute** | ONE resolved Action App ID bound to ≥ 2 `action` tasks **that do NOT each carry a distinct `actionType`**, OR where a declared field is absent from the app's schema (won't bind). **Exempt:** a code-switched app — distinct `actionType` per task **and** every declared field ⊆ the app schema — is the sanctioned normalized-action-app pattern, NOT flagged. | `rev_substitute_app_<app>` (`high`): "Action app reused across N tasks without a code-switching `actionType` (or with fields the app does not expose) — declared fields will not bind. Make it a code-switched app (distinct `actionType` per task, fields ⊆ the app schema) or deploy task-specific apps." |
 | **Multiple parallel single-recipient bottlenecks** | ≥ 2 stages have single-recipient bottleneck check fire AND they fan-in to the same downstream stage | `rev_multi_bottleneck_<stages>`: "Multiple single-recipient bottlenecks gate a downstream stage — fan-in stalls cascade." |
+| **Case-var relay (over-declaration)** | A §1.5 `Variable` row whose **only** producer is one task's Outputs `->` row AND whose **only** consumer is one downstream binding (one task Input `=vars.X`, OR one `=js:` expression / `IF`) — i.e., it carries a single output to a single consumer and is neither `In`/`Out` nor read in ≥ 2 places. **Exempt:** rows that rename, set a custom `Default` / `Type` / `Description`, or are read by ≥ 2 consumers / a condition. | `rev_relay_var_<name>`: "Variable `<name>` relays one task's output to a single consumer — reference the output directly (`<- \"Stage\".\"Task\".out` or `vars.$xref('Stage','Task','out')`) and drop the §1.5 row (see § 1.5 declare-vs-xref test)." |
 
 `medium` items DO NOT block Approve. They surface in the Approve summary's `Review items` count (not in the `sdd.md` body) — `medium` requires no acknowledgment but should not be silently buried. The **`high` variants above** (`rev_substitute_app`, and `rev_no_failure_path` at the ≥ 2-connector threshold) gate Approve like any other `high` item: the user can only `Approve despite N high-severity items`.
 
@@ -776,7 +848,10 @@ Before Approve atomic-renames `sdd.draft.md` → `sdd.md`, Phase 0 runs these ch
 13. **Domain-fidelity scan.** Run a single pass over every narrative cell (Description, persona name, stage name, task name, button label, app-view purpose). For each customer-named entity surfaced in §Source ledger as `verbatim:"..."`, confirm the rendered cell still uses the verbatim phrase (no synonym drift). Mismatch → list and offer `Re-edit` with the verbatim phrase pre-filled.
 14. **Architect's-lens advisory pass.** Run the §Architect's lens checks. Emit `medium` review items for each trigger (the `high` variants — `rev_substitute_app`, and `rev_no_failure_path` at the ≥ 2-connector threshold — emit `high` and gate via the opt-in). `medium` is non-blocking; Approve summary surfaces the count.
 15. **Decision-routing closure.** For every `action` task with `is_decision: Yes`, each button's `Maps To` variable+value MUST be consumed by ≥ 1 downstream rule (stage-entry `IF`, task-entry `IF`, stage-exit, or case-exit) OR the button's Behavior MUST declare it terminal (no routing claim). When a button's Behavior names a destination stage / lane ("route to / send to / via the X lane") and no entry condition keys off that variable+value, the branch is dead → **blocking error**. Pair with §Logical integrity step 5 (lane reachability). A fully-orphaned decision variable (produced by a button, read by nothing) on an `is_decision: Yes` task is blocking; the `medium` `rev_orphan_decision` variant in §Architect's lens applies only when the variable IS read but not for branching.
-16. **Action-app schema fidelity.** For every `action` task whose HITL Implementation resolves to a concrete deployed app, every declared Input Schema and Output Schema `Field` MUST exist in that app's schema (from `tasks describe`, persisted in `tasks/registry-resolved.json` at Resolve). A declared field absent from the app → `high` review item (`rev_action_schema_<task>`); it cannot bind. One app bound to ≥ 2 tasks with divergent declared schemas additionally trips `rev_substitute_app` (§Architect's lens).
+16. **Action-app schema fidelity.** For every `action` task whose HITL Implementation resolves to a concrete deployed app, every declared Input Schema and Output Schema `Field` MUST exist in that app's schema (from `tasks describe`, persisted in `tasks/registry-resolved.json` at Resolve). A declared field absent from the app → `high` review item (`rev_action_schema_<task>`); it cannot bind. One app bound to ≥ 2 tasks trips `rev_substitute_app` (§Architect's lens) **only** when the tasks lack distinct `actionType` dispatch values or declare fields outside the app schema; a code-switched app (distinct `actionType` per task, fields ⊆ app schema) is the sanctioned normalized-action-app pattern and does NOT trip it.
+17. **Required-task presence.** Every primary stage whose completion exit uses `required-tasks-completed` MUST contain ≥ 1 task with `Required: Yes`. A `required-tasks-completed` exit over a stage where no task is required is vacuous — the runtime resolves it without gating on real work (and the CLI flags it as `CASE_MGMT_..._NO_REQUIRED_TASK` at `validate`). Catch it at the Approve gate: zero `Required: Yes` tasks in such a stage → blocking error (offer `Re-edit` to mark the stage's terminal/primary task required). Tasks default to `Required: Yes` unless the SDD says otherwise, so this fires only when the author explicitly cleared every task's Required flag.
+18. **Resolved-resource presence (standalone replicability).** Every `process` / `agent` / `rpa` / `api-workflow` task has a concrete `Resolved Resource` + `Folder Path` (or `<UNRESOLVED>` + a paired `high` review item); every `action` task has `Action App ID` + `Deployment Folder`; every connector task has `Connection ID` + `Activity Type ID`. The SDD must name *which* deployed resource each task binds — a reader/coding-agent cannot replicate the case from I/O contracts alone. Missing identity with no review item → blocking error.
+19. **Resolved-resource I/O completeness** (§Resolved-resource I/O completeness; audit-checklist item 9). For every task resolved to a live resource (contract in `tasks/registry-resolved.json`): every **required** declared input is bound (any §Binding cell form, incl. an upstream-output ref — which needs NO §1.5 row) OR `<UNRESOLVED>` + a paired `high` review item (`rev_unbound_input_<task>_<field>`); every Outputs `-> caseVar` row's `Field` exists verbatim in the resolved output contract (a phantom field → `high` `rev_phantom_output_<task>_<field>`). Unbound required input with no review item → blocking error. Step 16 is the `action`-app instance of the output-fidelity direction; this step extends both directions to all runnable/connector types. Tasks left `<UNRESOLVED>` (no contract) are skipped.
 
 On pass: atomic rename `sdd.draft.md` → `sdd.md`, print Approve summary (with Inferred / defaulted block + Caller obligation block when applicable + review-items count), run Approve AskUserQuestion.
 
@@ -802,4 +877,6 @@ On fail: list the specific failing checks, return to AskUserQuestion `Re-edit` /
 - **Do NOT omit provenance on inferred values.** Silent inference reaches Phase 1 under Rule 2 trust — provenance is the audit trail.
 - **Do NOT alias a task output into an unrelated existing variable to satisfy lineage.** If a task produces a new datum, declare a §1.5 variable for it. Aliasing (`complianceStatus -> titleReviewStatus` with no `complianceStatus` row) closes lineage mechanically but corrupts meaning — see §Variable lineage closure output-naming rule.
 - **Do NOT emit a decision `action` button whose Behavior names a destination lane the case graph cannot reach.** Every routing button's variable+value must be keyed by a downstream entry / exit condition (§Finalization step 15, §Logical integrity step 5). A button that "routes to the X lane" while X is entered only by an external connector event is a dead branch.
-- **Do NOT author an `action` Input Schema field the resolved app does not expose.** Fields outside the app's `tasks describe` schema cannot bind (§Finalization step 16). Reusing one generic app across tasks that each need different fields is the substitute anti-pattern (`rev_substitute_app`).
+- **Do NOT author an `action` Input Schema field the resolved app does not expose.** Fields outside the app's `tasks describe` schema cannot bind (§Finalization step 16). Reusing one app across many tasks is correct **when it is code-switched** (distinct `actionType` per task, fields ⊆ the app schema — the normalized-action-app pattern a full case relies on); it is the substitute anti-pattern (`rev_substitute_app`) only without a distinct `actionType` or with non-bindable fields.
+- **Do NOT leave a resolved resource's required input unbound, and do NOT bind an output the resource never emits.** Once a task resolves to a live resource, every required declared input needs a `Binding` row (or `<UNRESOLVED>` + `high` review item) and every `-> caseVar` extract `Field` must exist in the resolved contract (§Resolved-resource I/O completeness, §Finalization step 19). A silently-missing required input faults the job at runtime.
+- **Do NOT declare a §1.5 Case Variable for an input that is just an upstream task's output.** Reference it directly — whole-value `<- "Stage"."Task".out` or in-expression `vars.$xref('Stage','Task','out')`. The emitting task is its own producer; a §1.5 row is only for renaming, custom `Default` / `Type`, or case-level state (§Variable lineage closure → Task-output direct reference).

package/skills/uipath-maestro-flow/references/author/CAPABILITY.md

@@ -28,7 +28,7 @@ Every node in a `.flow` file has exactly one author. The validator enforces this
 | Triggers | `core.trigger.manual`, `core.trigger.scheduled` |
 | Control flow | `core.logic.decision`, `core.logic.switch`, `core.logic.loop`, `core.logic.merge`, `core.control.end`, `core.logic.terminate`, `core.subflow` |
 | Logic | `core.action.script`, `core.action.transform`, `core.logic.delay`, `core.logic.mock` |
-| Human-in-the-loop | `uipath.human-in-the-loop` (inline + app-task forms) |
+| Human-in-the-loop | `uipath.human-in-the-loop.quick-form` (inline form), `uipath.human-in-the-loop.coded-action-app` (app-based) |
 | Patterns | `uipath.pattern.batch-transform`, `uipath.pattern.deep-rag` |
 | Agents | `uipath.agent.autonomous` (inline; after `uip agent init --inline-in-flow`) |
 | Resource nodes | `uipath.core.rpa-workflow.*`, `uipath.core.agent.*`, `uipath.core.flow.*`, `uipath.core.agentic-process.*`, `uipath.core.api-workflow.*`, `uipath.core.human-task.*` |

package/skills/uipath-maestro-flow/references/author/references/planning-arch.md

@@ -142,7 +142,7 @@ Each plugin has a `planning.md` with full selection heuristics, ports, key input
 | `core.logic.delay` | [delay](plugins/delay/planning.md) | Pause execution for a duration or until a specific date |
 | `core.action.queue.create` | [queue](plugins/queue/planning.md) | Distribute work to robots — fire-and-forget |
 | `core.action.queue.create-and-wait` | [queue](plugins/queue/planning.md) | Distribute work to robots — wait for result |
-| `uipath.human-in-the-loop` | [hitl](plugins/hitl/planning.md) | Pause flow for a human to review, approve, or fill in data — inline schema, no app required |
+| `uipath.human-in-the-loop.quick-form` | [hitl](plugins/hitl/planning.md) | Pause flow for a human to review, approve, or fill in data — inline schema, no app required |
 
 ### Control Flow
 
@@ -247,7 +247,7 @@ Use this when defining edges. Every edge requires a `sourcePort` and `targetPort
 | `uipath.connector.*` (activities) | `input` | `output`, `error` |
 | `core.action.queue.create` | `input` | `success` |
 | `core.action.queue.create-and-wait` | `input` | `success` |
-| `uipath.human-in-the-loop` | `input` | `completed` |
+| `uipath.human-in-the-loop.quick-form` | `input` | `completed` |
 | `uipath.core.human-task.{key}` | `input` | `output` |
 
 > **`error` is an implicit source port** on every action node (any node with `supportsErrorHandling: true`). Wire it whenever the flow needs to survive a failed HTTP call, script exception, transform error, agent fault, etc. — otherwise the flow faults as a whole. This is a **different mechanism** from content-based `inputs.branches` on HTTP. See [Implicit error port on action nodes](../../shared/file-format.md#implicit-error-port-on-action-nodes) for wiring, when it fires, and the decision matrix vs branches/decision/switch.

package/skills/uipath-maestro-flow/references/author/references/plugins/hitl/impl.md

@@ -4,7 +4,7 @@ Two node types implement human-in-the-loop checkpoints. Choose based on whether
 
 ---
 
-## Option 1 — `uipath.human-in-the-loop` (Inline Schema — OOTB)
+## Option 1 — `uipath.human-in-the-loop.quick-form` (Inline Schema — OOTB)
 
 This is the preferred option. No registry pull, no app publishing, no tenant dependency. Write the node directly into the `.flow` file as JSON.
 
@@ -24,17 +24,16 @@ For add, delete, and wiring procedures, see [editing-operations.md](../../editin
 ```json
 {
   "id": "hitlReview1",
-  "type": "uipath.human-in-the-loop",
+  "type": "uipath.human-in-the-loop.quick-form",
   "typeVersion": "1.0",
   "display": { "label": "Invoice Review" },
   "inputs": {
-    "type": "quick",
     "schema": {
       "schemaId": "<uuid>",
       "fields": [
         { "id": "invoiceid", "label": "Invoice ID", "type": "text",   "direction": "input", "binding": "vars.fetchInvoice.output.invoiceId" },
         { "id": "amount",    "label": "Amount",     "type": "number", "direction": "input", "binding": "vars.fetchInvoice.output.amount" },
-        { "id": "decision",  "label": "Decision",   "type": "text",   "direction": "output", "variable": "decision" }
+        { "id": "decision",  "label": "Decision",   "type": "text",   "direction": "output", "variable": "vars.decision" }
       ],
       "outcomes": [
         { "id": "approve", "name": "Approve", "type": "string", "isPrimary": true,  "action": "Continue" },
@@ -69,10 +68,10 @@ For add, delete, and wiring procedures, see [editing-operations.md](../../editin
 
 **Field format rules:**
 - **Input fields**: `binding: "vars.<nodeId>.output.<field>"` (raw path, no `=js:$` prefix). No `variable` property on input fields.
-- **Output fields**: `variable: "<globalName>"` (plain name, **no** `vars.` prefix). No `binding`.
+- **Output fields**: `variable: "vars.<globalName>"` (`vars.` prefix required). No `binding`.
 - **InOut fields**: both `binding` and `variable`, same formats as above.
 - `schemaId` (not `id`) at the schema level — generate a fresh UUID.
-- `typeVersion` — always `"1.0"` for `uipath.human-in-the-loop`. **Do not run `registry get` to derive this value; do not use `"1.1"` or any other version.** The OOTB HITL node version is stable at `1.0`.
+- `typeVersion` — always `"1.0"` for `uipath.human-in-the-loop.quick-form`. **Do not run `registry get` to derive this value; do not use `"1.1"` or any other version.** The OOTB HITL node version is stable at `1.0`.
 - No `model` block on node instances — only the definition carries it.
 
 **outputs block**: only `output` (with `properties` for output/inOut fields + `Action` outcome) and `status` (with `enum`/`default` from outcomes). No per-field `custom: true` entries.
@@ -83,13 +82,13 @@ For add, delete, and wiring procedures, see [editing-operations.md](../../editin
 - `$vars.{nodeId}.output` — object with all `output` / `inOut` field values, keyed by **field `id`**
 - `$vars.{nodeId}.output.{fieldId}` — individual field value (e.g. `$vars.hitlReview1.output.decision`)
 - `$vars.{nodeId}.status` — selected outcome name (e.g. `"Approve"`, `"Reject"`)
-- `$vars.{globalId}` — workflow-global variable for output/inOut fields; `globalId` is derived from `field.variable` (strip `vars.` prefix)
+- `$vars.{globalId}` — workflow-global alias; `globalId` is `field.variable` with `vars.` stripped. **Do not use this in scripts — always use `$vars.{nodeId}.output.{fieldId}` instead.**
 
 ---
 
-## Option 2 — App-Based HITL (`uipath.human-in-the-loop` with `inputs.type = "custom"`)
+## Option 2 — App-Based HITL (`uipath.human-in-the-loop.coded-action-app`)
 
-Use when there is an existing deployed Action Center app that should serve as the task form. Same node type as Option 1 — only `inputs.type`, `inputs.app`, and `inputs.appInputBindings` differ.
+Use when there is an existing deployed Action Center app that should serve as the task form.
 
 ### Discovery
 
@@ -120,11 +119,10 @@ Full step-by-step (app search → retrieve-configuration → resource files →
 ```json
 {
   "id": "invoiceReview1",
-  "type": "uipath.human-in-the-loop",
+  "type": "uipath.human-in-the-loop.coded-action-app",
   "typeVersion": "<DEFINITION_VERSION>",
   "display": { "label": "Invoice Review" },
   "inputs": {
-    "type": "custom",
     "recipient": { "channels": ["ActionCenter"], "connections": {}, "assignee": { "type": "group" } },
     "app": {
       "displayName": "Invoice Approval",
@@ -176,6 +174,8 @@ Full step-by-step (app search → retrieve-configuration → resource files →
 }
 ```
 
+**`typeVersion`** — fill in the version returned by `uip maestro flow registry get <appKey>` for the specific deployed app. Unlike QuickForm (always `"1.0"`), AppTask version varies per app definition.
+
 **`inputs.app`**: `inputSchema` and `outputSchema` are JSON Schema objects (`{ "type": "object", "properties": { ... } }`), **not arrays**.
 
 **`inputs.appInputBindings`** — maps app input parameter names to binding expressions. Format: `"=vars.<path>"` (with `=` prefix, no `js:`). Key = parameter name from `inputSchema.properties`. Without this, all input fields appear blank.

package/skills/uipath-maestro-flow/references/author/references/plugins/hitl/planning.md

@@ -8,16 +8,16 @@ The flow needs to pause for a human to review, approve, or fill in data. Two nod
 
 | Use case | Node type | Form source |
 | --- | --- | --- |
-| Inline form designed right now (fields + outcomes defined in the flow) | `uipath.human-in-the-loop` | Schema embedded in node inputs — no app needed |
-| Existing coded app or Action Center app | `uipath.core.human-task.{key}` | Deployed app from Orchestrator |
+| Inline form designed right now (fields + outcomes defined in the flow) | `uipath.human-in-the-loop.quick-form` | Schema embedded in node inputs — no app needed |
+| Existing coded app or Action Center app | `uipath.human-in-the-loop.coded-action-app` | Deployed app from Orchestrator |
 
-**Prefer `uipath.human-in-the-loop`** for new flows. It is an OOTB node — no registry discovery, no app publishing, no tenant dependency.
+**Prefer `uipath.human-in-the-loop.quick-form`** for new flows. It is an OOTB node — no registry discovery, no app publishing, no tenant dependency.
 
 ---
 
-## Option 1 — `uipath.human-in-the-loop` (Inline Schema — OOTB)
+## Option 1 — `uipath.human-in-the-loop.quick-form` (Inline Schema — OOTB)
 
-Node type: `uipath.human-in-the-loop`
+Node type: `uipath.human-in-the-loop.quick-form`
 Available: always — no `uip login` or registry pull required.
 
 ### When to Select
@@ -95,7 +95,7 @@ Trigger -> Process -> Decision (confidence ok?) ->
 
 In the node table:
 ```
-| hitlReview | Invoice Review | human-task | uipath.human-in-the-loop | inputs: [invoiceId, amount] outputs: [decision] outcomes: [Approve, Reject] | result, status |
+| hitlReview | Invoice Review | human-task | uipath.human-in-the-loop.quick-form | inputs: [invoiceId, amount] outputs: [decision] outcomes: [Approve, Reject] | output, status |
 ```
 
 ---

package/skills/uipath-maestro-flow/references/author/references/plugins/http/impl-connector.md

@@ -40,7 +40,10 @@ Record the chosen connection's `Id` and `FolderKey` — Step 3 needs both.
 
 ## Step 3 — Configure the node
 
-> **Find missing values first.** Before composing `url` / `query` / `body`, resolve any values the agent doesn't have (IDs from names, required body fields, response shape, …). See [/uipath:uipath-platform — http-request.md](../../../../../../uipath-platform/references/integration-service/http-request.md).
+> **STOP — open the platform skill before configuring.** Before composing `url` / `query` / `body`, read [/uipath:uipath-platform — http-request.md](../../../../../../uipath-platform/references/integration-service/http-request.md) and resolve every value you don't already have (IDs from names, required body fields, endpoint path, response shape).
+>
+> - **If the target connector is listed in that skill's `vendor-docs-registry.json`:** you MUST follow its **Step 0 (Ground Against the Vendor's API Docs)** — read the `docsUrl` + `notes` and confirm the exact endpoint with the `http-request` probe before running `node configure`. Pass the endpoint path verbatim: vendor method names can contain literal dots (Slack ``chat.postMessage`) — the dot is part of the path segment.
+> - **If the connector is NOT listed:** the registry-grounding step does not apply — resolve missing values via the `http-request` probe / vendor docs as usual.
 
 ```bash
 uip maestro flow node configure <ProjectName>.flow <nodeId> \