@uipath/skills 1.195.0

package/skills/uipath-maestro-case/references/plugins/variables/global-vars/planning.md

@@ -0,0 +1,119 @@
+# Variables — Planning
+
+Case-level data lives in the variables block (v19: `root.data.uipath.variables`; v20: top-level `variables` — see Rule 18). Three categories:
+
+| Category | Arrays touched | When |
+|---|---|---|
+| **Variable** | `inputOutputs[]` (declaration) + `triggerNode.outputs[]` (when populated by trigger payload) | Case-internal state, including trigger-payload-sourced state |
+| **In** | `inputs[]` + companion `inputOutputs[]` + `triggerNode.outputs[]` bridge | Formal argument supplied by external caller. Manual / timer triggers only. |
+| **Out** | `outputs[]` + companion `inputOutputs[]` (ALWAYS — see [`impl-json.md` § Out argument](impl-json.md)) | Formal argument returned to caller at case end |
+
+> **Canonical definition:** [`impl-json.md` § Pattern shapes by category](impl-json.md) is the source of truth for emission shapes (which arrays get written, exact JSON shape, runtime resolution semantics). This table is the Phase 1 routing summary.
+
+## SDD-to-Category Mapping
+
+Read the `Category` column on each Case Variables row. No inference, no fallback chain.
+
+| SDD `Category` cell | Action |
+|---|---|
+| `In` | Process as In argument |
+| `Out` | Process as Out argument |
+| `Variable` | Process as plain Variable |
+| Empty / missing | **AskUserQuestion** — present row's Name + ask `In` / `Out` / `Variable`. Never silently default. |
+| Other value | AskUserQuestion (same) |
+
+The Category column is REQUIRED in the SDD template.
+
+**Pre-flight: when the Category column is entirely absent from the Case Variables table** (legacy SDD authored against the pre-α template), do NOT proceed with inference. Apply the migration prompt:
+
+1. Read the Case Variables table rows.
+2. For EACH row, present a single AskUserQuestion: `<rowName>`: `In` / `Out` / `Variable` / `Skip — not a variable`. Multi-select if the harness allows batching; otherwise one prompt per row.
+3. Record the user's answer in memory and emit the T-entries as if the Category column had been authored that way.
+4. Strongly recommend (via plain-text output before/after the prompts) that the user migrate their SDD to include the column for future regenerate-from-scratch runs.
+
+Never default missing categories to a guess. The pre-α "Listed in Trigger Initial Variable Mapping → In argument" inference rule is removed under α and MUST NOT be re-implemented as a fallback. See [`assets/templates/sdd-template.md`](../../../../../assets/templates/sdd-template.md) § Case Variables for the post-α table shape.
+
+## Phase 2 Structural Validation
+
+Validate at planning time (before tasks.md is finalized). All checks operate on SDD content alone — no spec data needed yet.
+
+| Check | Severity | Action |
+|---|---|---|
+| `Category=Out` row has `sourceTriggers` filled | ERROR | Reject — Out-args flow case→caller, not trigger→case. AskUserQuestion: recategorize or clear sourceTriggers. |
+| `Category=In` or `Out` row has missing `Type` | ERROR | Reject — type is required for formal arguments. |
+| Two rows share the same `Name` (regardless of which other columns differ) | ERROR | Reject — name collision. Variable names MUST be globally unique. AskUserQuestion to resolve (rename one, or merge into one row). |
+| `Category=Variable` row has `sourceTriggers` but no matching `sourceFields` entry per trigger | ERROR | Reject — multi-trigger requires per-trigger sourceField. |
+| `sourceTriggers` references a T-number that doesn't exist in tasks.md | ERROR | Reject — orphan reference. |
+
+Phase 3 (implementation) catches spec-dependent issues — see [`impl-json.md`](impl-json.md) § Phase 3 Validation.
+
+## tasks.md Entry Format
+
+One T-entry per Case Variables row. Place after the case file (T01) and all trigger T-entries (T02+), before stages. T-number for the first variable depends on trigger count.
+
+```markdown
+## T05: Declare In-argument "applicantName"
+- category: In
+- type: string
+- triggerRef: T02
+- default: ""
+- verify: inputs[] formal slot + inputOutputs[] companion (elementId=<triggerId>) + triggerNode.outputs[] bridge written.
+
+## T06: Declare Variable "subject"
+- category: Variable
+- type: string
+- sourceTrigger: T02
+- sourceField: response.subject
+- verify: inputOutputs[] entry (id=subject, elementId="root"); trigger T02's outputs[] carries Pattern C wire (source="=response.subject", var=id="subject"); no inputs[] entry.
+
+## T07: Declare Variable "caseStarter"
+- category: Variable
+- type: string
+- sourceTriggers: T02, T03
+- sourceFields:
+    T02: response.user
+    T03: response.initiator
+- verify: one inputOutputs[] companion (elementId="root") shared across triggers; each listed trigger's outputs[] has its own Pattern C wire targeting the companion.
+
+## T08: Declare Variable "caseStatus"
+- category: Variable
+- type: string
+- default: "Open"
+- verify: inputOutputs[] entry (id=caseStatus, elementId="root", default="Open"); no trigger output entries.
+
+## T09: Declare Out-argument "finalDecision"
+- category: Out
+- type: string
+- producedBy: T15.outputs.finalDecision   # informational reference to the producing task T-entry
+- verify: outputs[] formal entry (var=finalDecision); companion in inputOutputs[] ALWAYS emitted (with default="" when Default empty); io-binding validator confirms producer task output has id=finalDecision.
+```
+
+**Field semantics on the T-entry:**
+
+- `category` — required, one of `In`, `Out`, `Variable`
+- `type` — required, one of `string`, `integer`, `float`, `double`, `boolean`, `datetime`, `date`, `jsonSchema`, `file`
+- `triggerRef` — T-number of the trigger this In-arg is attached to (single-trigger). For In-args only.
+- `sourceTrigger` — T-number when the value comes from a single trigger's payload (Variable category)
+- `sourceTriggers` — CSV of T-numbers when multiple triggers populate this Variable
+- `sourceFields` — per-trigger payload paths. Single-trigger form is `<path>`; multi-trigger form is a YAML-style sub-block with one `T<N>: <path>` per line
+- `default` — initial value (string-encoded for non-string types). Drives the `default` field on the companion `inputOutputs[]` entry.
+- `producedBy` — informational only (for Out-args). The io-binding validator confirms the named task actually exists with a matching output.
+
+**`verify` text — use exact terms from [`impl-json.md` § Pattern shapes](impl-json.md):**
+
+- "Bridge" = In-arg formal-arg → companion forwarding (manual/timer only, 3-entry shape). NEVER use for Variable rows.
+- Variable-row trigger.outputs[] entries are "Pattern C wires" (direct payload extraction, 2-entry shape).
+- `sourceField`'s right side IS the connector's spec path (e.g., `response.subject` is the literal field path in `caseShape.outputs[]`), not an alias. SDD-name on the LEFT becomes `var`/`id`; spec path on the RIGHT becomes `source`.
+- Spec-vs-SDD drift validation runs in the variables plugin's Phase 3 dispatcher, not in io-binding.
+
+## Types
+
+`"string"` | `"integer"` | `"float"` | `"double"` | `"boolean"` | `"datetime"` | `"date"` | `"jsonSchema"` | `"file"`
+
+## Naming
+
+camelCase IDs (`=vars.claimId`). See [`impl-json.md`](impl-json.md) § Uniqueness rules and ID generation.
+
+## Completeness obligation
+
+Per [planning.md §4.0](../../../planning.md), every row in the Case Variables table emits exactly one T-entry. Skipping rows because their Category cannot be determined is forbidden — invoke AskUserQuestion instead. The pre-approval cross-check counts variable-table rows against emitted variable T-entries; mismatch is a defect.

package/skills/uipath-maestro-case/references/plugins/variables/io-binding/impl-json.md

@@ -0,0 +1,255 @@
+# I/O Binding — Implementation
+
+> **Phase split.** Phase 3 only (Step 9.8). Phase 2 writes task shape (schema with empty `value` fields) but does not bind values. See [`../../../phased-execution.md`](../../../phased-execution.md).
+
+Wire task inputs by editing `caseplan.json` directly. Runs after all tasks are created and enriched (Step 9) and after global variable + output wiring is complete.
+
+## Task Input Shape
+
+`task.data.inputs[]` — binding = setting `value`:
+
+```json
+{ "name": "in_CustomerId", "type": "string",
+  "id": "vA1b2C3d4", "var": "vA1b2C3d4",
+  "elementId": "Stage_verify-tKYC001",
+  "value": "=vars.customerId" }
+```
+
+Inputs are populated with empty `value` from the `tasks describe` schema when `data.context.taskTypeId` is set during the task plugin's impl-json write. Input IDs are random (`v` + 8 chars).
+
+## Task Output Shape
+
+`task.data.outputs[]` — read-only, set at enrichment:
+
+```json
+{ "name": "KycResult", "type": "string",
+  "id": "kycResult", "var": "kycResult", "value": "kycResult",
+  "source": "=KycResult", "target": "=kycResult",
+  "elementId": "Stage_verify-tKYC001" }
+```
+
+Output IDs are name-based camelCase per [uniqueness rule](../global-vars/impl-json.md#uniqueness-rule). `source` reads from the task response — never changes even when `var` is counter-suffixed.
+
+## Output Binding Shapes
+
+Each task plugin emits `data.outputs[]` entries by combining its Step 0 schema (from `tasks describe` for non-connector plugins, `case spec --input-details` `caseShape.outputs[]` for connector plugins) with the SDD's `outputs:` row operators (`->`, `=`, or bare name). Apply these rules during the plugin's task-write step.
+
+For each entry in the Step 0 schema, check whether the SDD's `outputs:` row in tasks.md references it (matched by schema field name on the left side of `->`, or as a bare name).
+
+- **`<sdd-field-path> -> <sdd-name>`** (extract) → reassign-shape: `{name: <Step 0 displayName>, type: <Step 0 schema entry's type>, id: <camelCase(leaf segment)>, var: "<sdd-name>", originalVar: <camelCase(leaf segment)>, value: "<sdd-name>", source: "=<sdd-field-path>", target: "=<id>", elementId: "<stage-task>"}`. **`source` is the SDD's left-side string with `=` prefix, verbatim.** The SDD writes the full runtime path (e.g., `response.status`, `Error`, `response.message.ts`, `Action`); skill never adds, removes, or infers envelope prefixes. Consult the Step 0 schema for `type` / `displayName` — top-level entries match by their `source` field (with `=` stripped); nested fields are found by navigating the parent entry's `body` schema. **`type` is required on every emitted output — FE rejects entries without it.** **`originalVar` is load-bearing** — tells FE's `mutateRootVariables` (`VariableMutationUtils.ts:135`) to skip root-mirroring, preserving the case-Variable companion across FE edits.
+- **Bare `<name>`** (no operator) → auto-mint shape: `{name, type: <Step 0 entry's type>, id: <camelCase(name)>, var: <id>, value: <id>, source: <Step 0 entry's source verbatim>, target: "=<id>", elementId}`. No `originalVar`. Used for top-level Step 0 entries the SDD doesn't alias.
+- **`<sdd-name> = <expression>`** (set / compute / copy) → Scenario E shape: `{name: "<sdd-name>", custom: true, var: "<sdd-name>", value: "<expression>", source: "<same as value>", target: "", body: "", type: <case var's type>, elementId: "root"}`. **No `id`**, no `originalVar`. NO root mirror — FE's `isUpdateExistingOutput` filter at `VariableMutationUtils.ts:49-64` skips it.
+- **Schema fields with no SDD reference** → fall back to auto-mint shape (`var` = camelCased schema name). Connector plugins additionally apply the [uniqueness rule](../global-vars/impl-json.md#uniqueness-rule) dedup-suffix on collision (e.g., `response` → `response2`).
+
+Cross-cutting rules:
+
+- Expression values for `=`: literal (`"InReview"`, `5`, `true`), computed (`=js:vars.x + 1`), or variable reference (`=vars.X.Y.Z`).
+- Dot-paths in `->` paths are supported (e.g., `response.message.ts`, `Error.code`). Array indexing not supported in v1.
+- Target case variable on both `->` and `=` MUST exist in Case Variables table (validated at planning time).
+- [Uniqueness rule](../global-vars/impl-json.md#uniqueness-rule) applies to `var`/`id` on collision; `source` is never suffixed.
+
+## Output Binding Shapes for Connector Condition Rules
+
+The Output Binding Shapes above are operator-driven, not task-specific. The SAME shapes (`->` reassign with `originalVar`, `=` Scenario E with `custom: true`, bare-name auto-mint) apply when the SDD declares `Outputs:` rows on a `wait-for-connector` **condition rule** (in any of the 4 scopes: stage-entry, stage-exit, case-exit, task-entry). The connector-rule dispatch mirrors the connector-task dispatch with three targeting overrides:
+
+| Aspect | Connector task | Connector condition rule |
+|---|---|---|
+| Target array | `task.data.outputs[]` | `rule.uipath.outputs[]` |
+| Step 0 schema source | `tasks describe` / `case spec --input-details` `caseShape.outputs[]` | `case spec --type trigger --input-details` `caseShape.outputs[]` (already minted on `rule.uipath.outputs[]` by the connector-rule recipe — see [connector-trigger-common.md § Target: connector-bound condition rule](../../../connector-trigger-common.md#target-connector-bound-condition-rule)) |
+| `elementId` on each entry | `<stageId>-<taskId>` | `<ownerNodeId>-<ruleId>` — `<stageId>-<ruleId>` for stage-entry / stage-exit / task-entry; `root-<ruleId>` for case-exit |
+| Companion in `root.inputOutputs[]` (for `->` extract) | Required — `elementId: "root"`, `custom: true` | Required — same shape (`elementId: "root"`, `custom: true`) |
+| `=` Scenario E (custom output) | Permitted | Permitted — case variable assigned from rule response (`caseVar = response.X`), a literal, or an expression. NO root mirror per `isUpdateExistingOutput` filter. |
+
+**Uniqueness.** The [global pool](../global-vars/impl-json.md#uniqueness-rule) now includes rule outputs across all condition scopes — apply dedup against the union of tasks ∪ triggers ∪ rules ∪ root before minting.
+
+**When invoked.** Each condition plugin's `impl-json.md` invokes this dispatch as the LAST step of its `wait-for-connector` recipe — after writing `rule.uipath` (Step 5 of [connector-trigger-common.md § Procedure](../../../connector-trigger-common.md#procedure-phase-3)) and BEFORE running root bindings (Step 6). Iterate the rule's SDD `Outputs:` rows against the already-minted `rule.uipath.outputs[]` entries; rewrite each matched entry per the operator (`->` / `=` / bare). See the 4 condition `impl-json.md` files for the invocation site.
+
+**Skip guard.** Rules with no `rule.uipath` (connector configuration unresolved — see [`connector-trigger-common.md § Placeholder fallback`](../../../connector-trigger-common.md#placeholder-fallback)) — log `SKIPPED` and move on, same pattern as placeholder tasks (`data:{}`). Nothing to bind against until the connector resolves.
+
+**Runtime order (KNOWN ISSUE).** The case-backend currently evaluates the gateway BEFORE the rule's output extract populates `vars.caseVar` — gate-first / extract-after, opposite of the intended design contract. Extract-then-gate on a SINGLE rule does NOT work for in-rule event-payload conditioning; the gate sees the pre-extract value of the case var. **Workaround** at the case-design level: place the case-state gate on the DOWNSTREAM stage-entry / task-entry condition that follows the connector rule — by then the extract has populated the case var. Backend disposition pending; treat the in-rule gate against extracted values as undefined behavior until verified.
+
+## Binding Procedure
+
+For each task input in `tasks.md`:
+
+**Literals/expressions** — write the value string directly to `input.value`. Values shown are POST-rewrite — impl translates `=metadata.X` from `tasks.md` to `=js:metadata.X` per the [canonical-form table](../../../bindings-and-expressions.md#canonical-form-per-sink) (plain `=metadata.X` is not resolved by the lookup-path evaluator):
+```
+"=vars.amount"  |  "=js:metadata.ExternalId"  |  "50"  |  "=js:new Date()"
+```
+
+**Cross-task references** (`input <- "Stage A"."Task X".outputName`) — resolve first:
+
+1. Find Stage A by `data.label`, Task X by `displayName`
+2. Find output by `name` in `task.data.outputs[]`, read its `var` field
+3. Write `=vars.<var>` to target input's `value`
+
+```text
+# pseudocode — not executed. Realize via Read → reason → Write/Edit.
+src_output = find_output_by_name(src_task, "outputName")
+target_input["value"] = f"=vars.{src_output['var']}"
+```
+
+After all bindings, run the end-of-Phase-3 validator. It performs three cross-reference checks:
+
+### Check 1 — `=vars.X` reference resolution
+
+Verify every bound input has a non-empty `value`, and every `=vars.X` reference resolves to an existing entry in one of:
+- Any task `data.outputs[].id` (the resolver match key; mirrors `var` under skill convention)
+- Variables `inputOutputs[].id`
+- Variables `inputs[].id`
+
+Variables array path is schema-dependent — `root.data.uipath.variables.{inputOutputs,inputs}[].id` in v19, top-level `variables.{inputOutputs,inputs}[].id` in v20 (Rule 18).
+
+> **Scan key:** match by `.id`, NOT `.var`. The runtime resolver matches on `Variable.id` (`VariablesService.findVariableByVariableId`). Under the skill convention `id === var` on self-declaring outputs, scanning by `.var` is harmless in practice, but `.id` is symmetric with the resolver.
+
+Also scan `=vars.X` references in:
+- Edge guard expressions (`edges[].data.conditionExpression`)
+- Entry / exit condition expressions (stage and task)
+- SLA expressions
+- `=js:` expressions anywhere they appear
+
+Same resolution rule applies — these are read-side consumers of the variable namespace.
+
+### Check 2 — Out-arg producer presence
+
+For every entry in `root.data.uipath.variables.outputs[]` (formal Out-arg entries), the entry's `var` field is a POINTER to the variable slot that should hold the value at case end. Per the always-emit-companion rule, the companion in `root.inputOutputs[]` is always present; its `default` field is empty when SDD didn't declare a Default.
+
+**The check:** can the Out-arg's slot be populated at runtime? Three populating mechanisms exist:
+
+1. **Companion default** — non-empty `default` field on the companion → always-populated fallback.
+2. **Extraction producer** — a task's `outputs: <field> -> <var>` row (extract response field into the Out-arg slot).
+3. **Assignment producer** — a task's `outputs: <var> = <expr>` row (`=` operator: set/compute/copy a literal or expression into the Out-arg slot).
+4. **Bare-name producer** — a task's `outputs: <var>` row where the bare name matches the Out-arg's var (camelCase of schema field name).
+
+If none of these exist → **pure orphan**, prompt the author.
+
+| Producer status | Validate time action |
+|---|---|
+| Companion has non-empty `default` | OK — Out-arg always has a value. |
+| At least one producer (extraction, assignment, or bare-name) exists in tasks.md AND its task is resolved (not Rule 17 placeholder) | OK — producer wires the slot when its task fires. |
+| Producer declared but its task is a Rule 17 placeholder (declared-but-unwirable) | **Silent WARN.** Log to `tasks/build-issues.md` under `## Open Items for User`. Rule 17 already prompted the author for this task. |
+| NO producer anywhere AND companion default empty | **AskUserQuestion** — pure orphan. 4 options below. |
+
+Pseudocode:
+
+```text
+for entry in root.outputs[]:
+  var = entry.var
+  case_var_row = tasks_md_row_for_out_arg(name=entry.name)
+  has_companion_default = (case_var_row.default not empty)
+
+  # Producer scan — three patterns. All operate on tasks.md `outputs:` lines:
+  has_extraction_producer  = exists in tasks.md any task's T-entry with an `outputs:` line containing `<field> -> <var>` (where var matches the Out-arg's var)
+  has_assignment_producer  = exists in tasks.md any task's T-entry with an `outputs:` line containing `<var> = <expression>` (where var matches the Out-arg's var)
+  has_bare_name_producer   = exists in tasks.md any task's T-entry with an `outputs:` line `- <name>` (bare, no operator) where camelCase(name) == var
+  has_any_producer         = has_extraction_producer || has_assignment_producer || has_bare_name_producer
+
+  producer_task_unresolved = the tasks.md-declared producer task is a Rule 17 placeholder (look up the task in caseplan.json by displayName; check `node.data.uipath` is empty `{}`)
+
+  if has_companion_default:
+      # Companion default guarantees a value; producer is optional bonus
+      OK
+  elif has_any_producer and producer_task_unresolved:
+      # Declared producer but task is unresolvable — Rule 17 already prompted; just log
+      LOG_OPEN_ITEM("Out-arg with declared but unresolvable producer — runtime returns empty until producer is wired")
+  elif not has_any_producer:
+      # Pure orphan — author never declared a producer AND no Default. Ask.
+      AskUserQuestion("pure orphan", options=(a, b, c, d))
+```
+
+**On AskUserQuestion ("pure orphan" branch):**
+
+```
+Out-argument "<name>" (id <random>, var <var>) has no value source:
+  SDD row Default: <"" (empty)>
+  Companion root.inputOutputs[].id="<var>": exists, default=""
+  Producing task in tasks.md (extraction or assignment): none found
+
+Pick one:
+  (a) Add producer task output — supply the producer task's **display name** as shown in tasks.md (e.g., `Send Slack Message`). If the named task doesn't exist, re-prompt. Skill appends `<field> -> <var>` to that task's Outputs.
+  (b) Add a Default value to the SDD Case Variables row — supply value inline (literal string).
+  (c) Recategorize as Variable (case-internal state) or remove the variable.
+  (d) Continue with best-effort emit (case builds; runtime returns empty string for this Out-arg; entry logged under "Open Items for User" in build-issues.md).
+```
+
+**Skill response per user pick:**
+
+- **(a)** Edit `tasks.md`: append `outputs: <field> -> <var-name>` to the named task's T-entry (use spec-derived field name if available, else `<UNKNOWN>` placeholder). Re-run Phase 1 dispatcher from the modified tasks.md, then retry Step 12.
+- **(b)** Edit `tasks.md`: set `default: "<value>"` on the Out-arg's T-entry. Re-run Phase 1 dispatcher, then retry Step 12.
+- **(c)** Prompt the user inline: `Recategorize as "Variable" or "Remove" the variable?` On `Variable`: edit `tasks.md` Case Variables row Category → Variable, re-run Phase 1 dispatcher, retry Step 12. On `Remove`: delete the row from `tasks.md`, re-run Phase 1 dispatcher, retry Step 12.
+- **(d)** Append the build-issues entry (template below) and continue to Phase 4. No re-run.
+
+Option (d) is the build-with-best escape for cases where the author intends to wire the producer later but wants to keep iterating now — equivalent to the silent-WARN treatment that declared-but-unresolvable producers (T20-style) get automatically.
+
+**Rationale for the split:** real-world authoring is iterative. When an author has already gone through a Rule 17 prompt for the producer task (T20-style), the skill should not pile a second prompt on top — that's the path the author already chose by picking "Skip". But when the author authored a *pure orphan* with no producer declared at all (T14-style — wait-for-timer with no aliasing wire AND no Default), there's no prior signal of intent; the AskUserQuestion is the right surface to ask "did you mean to forget this, or wire it now?" Option (d) preserves the build-with-best escape.
+
+**Build-issues entry template** (both branches log to this, only the AskUserQuestion branch ALSO prompts):
+
+```markdown
+## Open Items for User
+
+- **[Out-arg `<name>` has no value source]** — The Out-argument `<name>` is declared in `variables.outputs[]` but {no producer wired AND no Default}. Runtime will return empty string for this Out-argument unless one of:
+  - Add a `<field> -> <name>` row to a task's Outputs that produces this value (extraction)
+  - Add a `<name> = <expression>` row to a task's Outputs (assignment from literal / computed / variable reference)
+  - Add a Default value to the SDD Case Variables row
+  - Recategorize the variable as `Variable` or remove it
+```
+
+See [implementation.md § Step 12 — End-of-Phase-3 validator pass](../../../implementation.md) for invocation.
+
+### Check 3 — Type mismatch warnings
+
+Where a `=vars.X` reference resolves to a declaration with a different `type` than the consuming input expects, log WARNING. Proceed (string coercion is common and runtime-tolerant).
+
+## Connector Tasks
+
+Connector task input values are written during Step 9.7 (connector detail), not during this I/O binding step. Resolve cross-task `var` IDs before constructing the `input-values` body from `tasks.md`, then apply the canonical wrap per sink:
+
+```json
+{ "body": { "email": "=js:(vars.employeeEmail)", "caseRef": "=js:(metadata.ExternalId)" } }
+```
+
+**Connector body sinks require `=js:(...)` wrap for ALL references** — `=vars.X`, `=metadata.X`, `=bindings.X`, and operator expressions (e.g. `=js:(vars.amount > 5000)`). The runtime only evaluates `=js:` prefixed strings inside connector body fields; plain prefix forms arrive at the API as literal strings (silent runtime fault). Full per-sink rule: [bindings-and-expressions.md § Canonical form per sink](../../../bindings-and-expressions.md#canonical-form-per-sink).
+
+See [connector-activity/impl-json.md](../../../plugins/tasks/connector-activity/impl-json.md) for the connector body write path.
+
+## End-to-End: Task A Output → Task B Input
+
+"Validate Expense Data" produces `validationResult`, consumed by "Enrich Employee Details":
+
+```json
+// 1. Task A output (auto-enriched) — Stage "Submission", task.data.outputs[]
+{ "name": "ValidationResult", "var": "validationResult", "id": "validationResult",
+  "value": "validationResult", "source": "=ValidationResult", "target": "=validationResult",
+  "type": "string", "elementId": "Stage_submit-tValidate01" }
+
+// 2. Task B input after binding — value set to =vars.<output.var>
+{ "name": "in_ValidationResult", "value": "=vars.validationResult",
+  "type": "string", "id": "vXr9pQ2mK", "var": "vXr9pQ2mK",
+  "elementId": "Stage_submit-tEnrich02" }
+```
+
+Two things must exist: output on Task A with a `var` field, and bound input on Task B referencing `=vars.<var>`. Root `inputOutputs` companion entries for case Variables produced via `->` are also written for picker visibility — see [global-vars/impl-json.md § Task Output → variable resolution](../global-vars/impl-json.md#task-output--variable-resolution).
+
+## Error Handling
+
+All issues go to the shared issue list per [logging/impl-json.md](../../logging/impl-json.md). No fuzzy matching, no auto-creation, no retries.
+
+| Check | Severity | Action |
+|---|---|---|
+| Placeholder task (no `data.inputs[]`) | `SKIPPED` | Skip all bindings |
+| Placeholder connector rule (no `rule.uipath`) | `SKIPPED` | Skip rule output bindings (nothing minted) |
+| Input name not found (exact match) | `ERROR` | Skip binding — log available inputs |
+| Source output not found (exact match) | `ERROR` | Skip binding — log available outputs |
+| `=vars.X` not in any task `outputs[].id` or root `inputOutputs[].id` / `inputs[].id` | `ERROR` | Skip binding |
+| Out-arg formal entry has NO producer (no extraction, assignment, or bare-name match in any task outputs) AND companion has no `default` | `ERROR` | Log Out-arg pure-orphan issue (Check 2 above); AskUserQuestion |
+| Type mismatch (input vs variable) | `WARNING` | Proceed |
+
+Example log entry (pseudocode — record in-reasoning, not via subprocess):
+
+```text
+# pseudocode — not executed
+issues.append({"severity": "ERROR", "step": "9", "plugin": "io-binding",
+    "message": f'input "{name}" not found on task "{task}" — available: {available}',
+    "context": {"task": task, "stage": stage, "input": name, "available": available}})
+```

package/skills/uipath-maestro-case/references/plugins/variables/io-binding/planning.md

@@ -0,0 +1,80 @@
+# I/O Binding — Planning
+
+Trust the SDD. Emit inputs/outputs exactly as declared. There is no `caseplan.json` yet — all validation happens during [implementation](impl-json.md).
+
+## Discovering Input/Output Names
+
+1. **SDD per-task tables** — primary source. Each task lists input/output field names, types, and variable bindings.
+2. **`uip maestro case tasks describe --type <type> --id "<taskTypeId>" --output json`** — validates SDD names and discovers additional fields (e.g., standard `Error` output). The SDD per-task Outputs table uses TWO operators (per v1 contract — see [`assets/templates/sdd-template.md`](../../../../assets/templates/sdd-template.md) Section 2):
+
+   **`->` operator — extract a field into a case variable.** Left side is the **full runtime path** the value lives at relative to the task's root scope; right side is the target case variable name:
+   ```markdown
+   - outputs:
+     - response.status        -> sendStatus    # connector payload field → vars.sendStatus
+     - response.message.ts    -> messageTs     # nested connector field  → vars.messageTs
+     - Error                  -> error         # top-level error (connector or action) → vars.error
+     - Error.code             -> errorCode     # nested error sub-field   → vars.errorCode
+     - Action                 -> userDecision  # action task's top-level output → vars.userDecision
+   ```
+
+   `<sdd-field-path> -> <case variable>`. Left side is the full runtime path. Right side becomes `var` / `id` / `value` on `task.data.outputs[]` (the case-scope variable name). Extracted source is `"=<sdd-field-path>"` verbatim — the skill emits the SDD's left-side string with `=` prefix; never adds, removes, or infers envelope prefixes. Target case variable MUST exist in the Case Variables table.
+
+   **`=` operator — set / compute / copy a literal or expression into an existing case variable.** Left side is the target case variable (must already exist in Case Variables); right side is the expression. No `Field` column:
+   ```markdown
+   - outputs:
+     - caseStatus  = "InReview"                            # literal
+     - reviewCount = =js:vars.reviewCount + 1              # computed expression
+     - summary     = =vars.response.message.text           # copy from another variable's sub-field
+   ```
+
+   `<case variable> = <expression>`. Expression can be a plain literal string/number/bool, a `=js:` computation, or a `=vars.X.Y` variable reference. Target case variable MUST exist in the Case Variables table.
+
+   **Dot-path support** on the left side of `->`: full paths like `response.message.ts`, `response.data.user.email`, `Error.code` are emitted as-is. Array indexing (`items[0]`) is NOT supported in v1 — fall back to consuming the array variable and using `=js:` expressions downstream.
+
+   **Bare-name outputs** (no operator): emits an auto-mint entry that references a **top-level** Step 0 schema entry (e.g., `Error` or a pre-expanded shortcut like Slack's `ts`). `id = var = value = camelCase(entry name)`. Source is the entry's pre-populated value verbatim. For non-top-level fields, use the `->` operator with the full path instead.
+   ```markdown
+   - outputs:
+     - Error            # bare — references top-level Error entry; produces vars.error (source = entry's =Error)
+   ```
+
+3. **Unresolved taskTypeId** — `tasks describe` unavailable. Follow [placeholder-tasks](../../../placeholder-tasks.md) — omit `inputs:`/`outputs:`, capture wiring intent in a fenced code block.
+
+Do not fabricate names not in the SDD or `tasks describe`. Validation of variable existence happens at planning time (Phase 2) for `=` rows (target must exist in Case Variables); at implementation time (Phase 3) for `->` rows (deferred to io-binding validator).
+
+## Input/Output Notation
+
+For the full notation and expression prefixes, see [bindings-and-expressions.md](../../../bindings-and-expressions.md). Quick reference:
+
+| Source | Notation | Example |
+|---|---|---|
+| Cross-task output | `input <- "Stage"."Task".output` | `emails <- "Triage"."Fetch Inbox".emails` |
+| Global variable | `input = "=vars.<id>"` | `caseId = "=vars.caseId"` |
+| Metadata | `input = "=metadata.<field>"` | `caseRef = "=metadata.ExternalId"` |
+| Binding | `input = "=bindings.<id>"` | `connectionId = "=bindings.bA1B2C3D4"` |
+| Literal | `input = "<value>"` | `maxResults = "50"` |
+
+> **Note:** task INPUT bindings still use `<-` for cross-task references (`input <- "Stage"."Task".output`) — this is the planner-side notation for "this input value comes from another task's output." Task OUTPUT bindings use `->` for extract (`Field -> caseVar`) and `=` for set/compute/copy. Different directional conventions because inputs read from somewhere; outputs write to somewhere.
+
+Record discovered outputs on each task entry (`outputs: kycResult, riskScore, error`) so downstream cross-task references can be validated during implementation.
+
+> **Planner emits SDD-natural form; impl applies the per-sink canonical wrap.** Values in `tasks.md` use the natural prefix notation shown above — `=vars.X`, `=metadata.X`, `=bindings.X`, cross-task `<-`. The implementation step rewrites each value to its canonical sink form when constructing `caseplan.json` (e.g., `=js:(vars.X)` for connector body fields, `=js:metadata.X` for `=metadata` references in any sink that runs the JS evaluator). Full rule: [bindings-and-expressions.md § Canonical form per sink](../../../bindings-and-expressions.md#canonical-form-per-sink).
+
+## Outputs table validation rules
+
+Apply at planning time (Phase 2):
+
+| Rule | Severity | Detail |
+|---|---|---|
+| `->` row's target case variable not in Case Variables table | ERROR | Outputs declare bindings, not new variables. Target must pre-exist. |
+| `=` row's target case variable not in Case Variables table | ERROR | Same — `=` writes to existing variable's slot. |
+| `->` row missing left-side Field | ERROR | `->` requires a schema field name on the left. |
+| `=` row has a non-empty Field column | ERROR | `=` rows have `—` (no field), since the source is the right-side expression, not a schema field. |
+| Per task: same target case variable appears in multiple Outputs rows | ERROR | No double-binding; one row per target var per task. Last-writer-wins is a runtime footgun. |
+
+## Scoping
+
+| Task location | Can reference |
+|---|---|
+| Regular stage task | Earlier stages + same stage earlier tasks + root variables |
+| Exception stage task | ALL tasks across ALL stages |
+| Adhoc task | ALL tasks |

package/skills/uipath-maestro-case/references/registry-discovery.md

@@ -0,0 +1,170 @@
+# Registry Discovery Reference
+
+Resolve the correct task type and entity identifier for a case task by searching the local registry cache files directly.
+
+## When to Use
+
+During sdd.md → task.md interpretation, when you need to determine:
+- What **task type** to use for a task (e.g., `agent`, `process`, `execute-connector-activity`)
+- What **entity identifier** to reference in the task.md
+
+## Prerequisites
+
+Run `uip maestro case registry pull` before any lookups. This populates the local cache at `~/.uip/case-resources/`. All subsequent discovery is done by reading these cache files directly — **do not** rely on `uip maestro case registry search` as the primary discovery method. See the "CLI Search Gaps" section below for the reason.
+
+> **Missing file ≠ empty match.** Before searching any `<type>-index.json`, verify it exists on disk. If it does not, run `uip maestro case registry pull` (not `--force` — a normal pull is enough for first-time population). The Rule 17 / § MUST-Confirm-Before-Placeholder-Fallback gate only applies to **empty matches inside an existing cache**; a missing file is a precondition failure, not a 0-result lookup. If the file is still absent after a successful pull, the tenant has no resources of that type — proceed to placeholder.
+
+## CLI Search Gaps
+
+The `uip maestro case registry search` command has known gaps. In particular, it fails to return results for certain resource types even when the resource is present in the cache (most commonly affecting **action-apps** / HITL tasks). When search returns an empty or incomplete result for a resource you know exists:
+
+1. Do **not** retry the same search with different keywords.
+2. Fall back to reading the cache files directly using the procedure in this document.
+3. Record the gap in `registry-resolved.json` so the audit trail reflects the fallback.
+
+Direct cache-file inspection is the authoritative discovery method for this skill.
+
+## MUST Confirm Before Placeholder Fallback
+
+> **Hard gate.** If the planning-phase lookup batch returns ≥1 empty result (no match across all relevant cache files for any task / trigger / connector), STOP. Run AskUserQuestion before invoking any per-plugin Unresolved Fallback path or writing any placeholder T-entry.
+
+Required prompt shape:
+
+```
+Question: <N> registry lookup(s) returned 0 matches: <comma-list of <name> in <folder>>.
+          Run `uip maestro case registry pull --force` to bypass the cache and re-resolve?
+Header:   Force pull
+Options:
+  - Yes, force pull and re-resolve
+      → run `uip maestro case registry pull --force`, re-search caches, update registry-resolved.json with the second-pass results.
+        Any STILL-empty lookups go to placeholder ONLY after this round.
+  - Skip and use placeholders
+      → proceed to per-plugin Unresolved Fallback paths for the unmatched lookups.
+```
+
+**Apply once per planning batch, not per-task.** A single prompt covers every empty in that batch.
+
+**Do NOT pre-judge.** Resource-name heuristics ("looks vendor-specific, won't be in registry anyway", "this is an obvious custom connector") are the user's call to make, not the agent's. Always ask. SKILL.md Rule 17.
+
+## Cache File Index
+
+Each resource type has a `<type>-index.json` file at `~/.uip/case-resources/`:
+
+| File | Identifier field | Name field | Folder field |
+|------|-----------------|------------|--------------|
+| `agent-index.json` | `entityKey` | `name` | `folders[0].fullyQualifiedName` |
+| `process-index.json` | `entityKey` | `name` | `folders[0].fullyQualifiedName` |
+| `api-index.json` | `entityKey` | `name` | `folders[0].fullyQualifiedName` |
+| `processOrchestration-index.json` | `entityKey` | `name` | `folders[0].fullyQualifiedName` |
+| `caseManagement-index.json` | `entityKey` | `name` | `folders[0].fullyQualifiedName` |
+| `action-apps-index.json` | `id` | `deploymentTitle` | `deploymentFolder.fullyQualifiedName` |
+| `typecache-activities-index.json` | `uiPathActivityTypeId` | `displayName` | *(none)* |
+| `typecache-triggers-index.json` | `uiPathActivityTypeId` | `displayName` | *(none)* |
+
+Each file is a JSON array of resource entries.
+
+## Procedure
+
+### 1. Determine Which Cache Files to Search
+
+Use the component type from the sdd.md to identify the **primary** cache file, then always include related files as fallbacks. This is important because the sdd.md component type label may not match the actual registry resource type (e.g., an "RPA" task in the sdd.md may be registered as `process` in the registry).
+
+| sdd.md component type | Primary cache file |
+|---|---|
+| API_WORKFLOW | `api-index.json` |
+| AGENTIC_PROCESS | `processOrchestration-index.json` |
+| HITL | `action-apps-index.json` |
+| RPA | `process-index.json` |
+| AGENT | `agent-index.json` |
+| CASE_MANAGEMENT | `caseManagement-index.json` |
+| CONNECTOR_ACTIVITY | `typecache-activities-index.json` |
+| CONNECTOR_TRIGGER | `typecache-triggers-index.json` |
+| PROCESS | `process-index.json` |
+| EXTERNAL_AGENT | *(not in cache)* |
+| TIMER | *(not in cache)* |
+
+For types marked "not in cache" (`EXTERNAL_AGENT`, `TIMER`), skip the cache lookup — these have no registry representation. Use the JSON `type` value directly.
+
+**Cross-type fallback:** The sdd.md component type label is not always accurate — the actual registry resource may be stored under a different type. For example, an "RPA" process may appear in `process-index.json`, or an "AGENTIC_PROCESS" might be in `process-index.json` instead of `processOrchestration-index.json`. If the primary cache file yields no match, search **all** cache files listed above for the task name. When a match is found in a different cache file than expected, use that cache file's identifier field and type mapping for the `taskTypeId`, but keep the sdd.md's component type for the JSON `type` field.
+
+### 2. Search by Name and Folder Path
+
+For each task in the sdd.md, extract the **name** and **folder path** from the Process References table, then filter the cache file:
+
+```bash
+cat ~/.uip/case-resources/<type>-index.json | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for item in data:
+    name = item.get('name', '') or item.get('deploymentTitle', '')
+    if '<task_name>' in name:
+        folders = item.get('folders', [])
+        folder = folders[0].get('fullyQualifiedName', '') if folders else ''
+        if not folder:
+            df = item.get('deploymentFolder', {})
+            folder = df.get('fullyQualifiedName', '') if df else ''
+        ident = item.get('entityKey') or item.get('id') or item.get('uiPathActivityTypeId', '')
+        print(json.dumps({'identifier': ident, 'name': name, 'folder': folder}))
+"
+```
+
+**Match priority:**
+1. **Exact name + exact folder** — strongest match, use directly.
+2. **Exact name, multiple folders** — pick the one matching the sdd.md folder path.
+3. **Exact name, no folder specified in sdd.md** — pick the first exact-name match; note alternatives in `registry-resolved.json`.
+4. **No match in primary cache file** — search all other cache files (the resource may be registered under a different type than expected).
+
+### 3. Handle Empty Results
+
+> **Required precondition.** Before reaching this step, the [§ MUST: Confirm Before Placeholder Fallback](#must-confirm-before-placeholder-fallback) gate above MUST have been satisfied. If you have not yet run AskUserQuestion for the empty-result batch, do that first. Force pull and per-plugin Unresolved Fallback both flow through that gate.
+
+If no match is found across all relevant cache files:
+
+1. **Already gated above.** AskUserQuestion confirmation already ran. If the user picked `Yes, force pull and re-resolve`, the force pull has already executed; this step is reached for lookups that remained empty after the second-pass search.
+   ```bash
+   # already executed during the gate's "Yes" branch:
+   uip maestro case registry pull --force
+   ```
+2. If still no match (or user picked `Skip`), mark it in tasks.md: `[REGISTRY LOOKUP FAILED: <name> in <folder>]` and proceed to the per-plugin Unresolved Fallback path.
+
+### 4. Return All Matches
+
+Collect all matching results for the `registry-resolved.json` debug output. Record:
+- The cache file searched
+- All entries that matched the name
+- Which entry was selected and why (folder match, first-match, etc.)
+
+## Type Mapping
+
+After finding a match, map the **cache file type** (not the sdd.md component type) to the JSON `type` value written into the task node:
+
+| Cache file | Task `type` | Identifier field |
+|---|---|---|
+| `agent-index.json` | `agent` | `entityKey` |
+| `process-index.json` | `process` | `entityKey` |
+| `api-index.json` | `api-workflow` | `entityKey` |
+| `processOrchestration-index.json` | `process` | `entityKey` |
+| `caseManagement-index.json` | `case-management` | `entityKey` |
+| `action-apps-index.json` | `action` | `id` |
+| `typecache-activities-index.json` | `execute-connector-activity` | `uiPathActivityTypeId` |
+| `typecache-triggers-index.json` | `wait-for-connector` | `uiPathActivityTypeId` |
+
+Additional `type` values not discoverable through cache: `rpa`, `external-agent`, `wait-for-timer`.
+
+**Important:** The sdd.md component type determines the JSON `type` to write, but the **cache file** determines the `taskTypeId`. For example, if the sdd.md says "RPA" and the cache match is in `process-index.json`, write `type: "rpa"` (from sdd.md) and `data.context.taskTypeId: "<entityKey>"` (from cache).
+
+## Connector Tasks
+
+For entries in `typecache-activities-index.json` or `typecache-triggers-index.json`, the resolution pipeline (get-connection + `case spec`) lives in [connector-integration.md](connector-integration.md). Registry discovery provides only the `uiPathActivityTypeId`; everything else is handled there.
+
+After registry pull, `uip maestro case spec` is the unified metadata endpoint for connector tasks — it returns identity, connection details, inputs/outputs/filter contract, references with pre-built discoverCommand, and (in Phase 3) a populated `caseShape` ready to drop into `caseplan.json`. This replaces the legacy `case tasks describe` + `is resources describe` dance for connector activities and triggers. See [connector-integration.md § Step 3](connector-integration.md) for the call shape.
+
+- **Only use entries that have a `uiPathActivityTypeId` field.** Skip entries without it — these are non-connector activities and are not supported as case tasks at this time.
+
+## Output Contract
+
+The discovery result for each match should include the **entity identifier** (the value from the "Identifier field" column above) so `tasks.md` can reference it. The implementation agent writes this identifier into `data.context.taskTypeId` (or `data.typeId` for connectors) on the task node.
+
+### `registry-resolved.json` content discipline
+
+Structured log only — per Rule 9, each entry is `{search query, matches, selected, rationale}`. The file is re-ingested as a perf cache on subsequent runs (planning.md § Phase 0 carryover), so any free-form prose written here gets parroted back into `tasks.md`. `rationale` MUST explain the selection choice (e.g., `"exact name match in caseManagement folder"`); never use it for verify-text drafts, SDD-vs-spec field translations, or downstream-plugin-behavior claims.