@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-maestro-bpmn/validator/validate-bpmn.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// Offline semantic validator for UiPath Maestro BPMN XML.
+//
+// Pipeline:
+//   1. Parse the BPMN with bpmn-moddle using the UiPath extension descriptor
+//      (same getModdle() + fromXML() pattern as PO.Frontend).
+//   2. Reconstruct the PO.Frontend Node[]/Edge[]/CanvasState model (model.mjs).
+//   3. Run ALL 19 PO.Frontend validation rules (rules.mjs) per diagram, plus a
+//      whole-model variable-existence check.
+//   4. (Optional) Run the Maestro-original connection-liveness ping via uip CLI.
+//
+// Prints `VALID` and exits 0 when there are no ERROR-severity findings.
+// Otherwise lists every finding (rule code + message) and exits non-zero.
+// WARNING-severity findings are printed but do not gate.
+//
+// Usage: node validate-bpmn.mjs <bpmn-file> [resources]
+//   resources: comma-separated release names, or a numeric folder ID, for the
+//              optional solution-resource liveness ping (requires uip CLI auth).
+import BpmnModdle from "bpmn-moddle";
+import sax from "sax";
+import descriptor from "./uipath-moddle.v1.json" with { type: "json" };
+import { readFileSync, existsSync } from "fs";
+import { execFileSync } from "child_process";
+import { buildModel, collectKnownVariableIds, allNodes, allEdges } from "./model.mjs";
+import { validateDiagram, validateVariableExistence, validateVariableNotSet, SEVERITY } from "./rules.mjs";
+
+// Strict XML well-formedness check via sax's strict mode. Returns the first
+// error message (with a line number) or null when the document is well-formed.
+function strictXmlError(xml) {
+  const parser = sax.parser(true, {});
+  let error = null;
+  parser.onerror = (e) => {
+    if (!error) {
+      const line = (parser.line ?? 0) + 1;
+      error = `${e.message.split("\n")[0]} (near line ${line})`;
+    }
+  };
+  try {
+    parser.write(xml).close();
+  } catch (e) {
+    if (!error) error = String(e.message ?? e).split("\n")[0];
+  }
+  return error;
+}
+
+// --- uip CLI resolution (cached) — used only for the liveness-ping extra. ---
+let _uipBin;
+function resolveUipBin() {
+  if (_uipBin !== undefined) return _uipBin;
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const candidates = ["uip", `${home}/.bun/bin/uip`, `${home}/.local/bin/uip`, "/usr/local/bin/uip"];
+  for (const p of candidates) {
+    try {
+      if ((p.startsWith("/") || p.startsWith(home)) && !existsSync(p)) continue;
+      execFileSync(p, ["--version"], { encoding: "utf8", timeout: 5000, stdio: "pipe" });
+      _uipBin = p;
+      return p;
+    } catch {
+      /* keep trying */
+    }
+  }
+  _uipBin = null;
+  return null;
+}
+
+function pingConnections(resourceArg) {
+  // Maestro-original extra: liveness-check bound IS connections. Best-effort;
+  // a missing/unauthenticated CLI is reported as a NOTE, never a hard failure.
+  const bin = resolveUipBin();
+  if (!bin) return { note: "uip CLI not found; skipped connection liveness ping." };
+  try {
+    const args = ["is", "connections", "ping", "--output", "json"];
+    if (/^\d+$/.test(resourceArg)) args.push("--folder", resourceArg);
+    const out = execFileSync(bin, args, { encoding: "utf8", timeout: 30000, stdio: "pipe" });
+    return { ok: true, raw: out.trim() };
+  } catch (e) {
+    return { note: `connection liveness ping unavailable: ${String(e.message || e).split("\n")[0]}` };
+  }
+}
+
+const file = process.argv[2];
+const resourceArg = process.argv[3];
+if (!file) {
+  console.error("Usage: node validate-bpmn.mjs <bpmn-file> [resources]");
+  process.exit(1);
+}
+
+const xml = readFileSync(file, "utf8");
+
+// Strict XML well-formedness gate. bpmn-moddle's SAX parser (saxen) is lenient:
+// it accepts unescaped `&`/`<`, `--` inside comments, and other malformed input
+// that strict parsers — and the Studio Web canvas import — reject. A validator
+// that is more permissive than the real import gives false confidence, so parse
+// strictly first and refuse anything the import would refuse.
+{
+  const err = strictXmlError(xml);
+  if (err) {
+    console.error(`WELL-FORMEDNESS ERROR: ${err}`);
+    process.exit(2);
+  }
+}
+
+const moddle = new BpmnModdle({ uipath: descriptor });
+
+let definitions;
+try {
+  const result = await moddle.fromXML(xml);
+  definitions = result.rootElement;
+  if (result.warnings?.length) {
+    for (const w of result.warnings) console.error(`PARSE WARNING: ${w.message ?? w}`);
+  }
+} catch (e) {
+  console.error(`SCHEMA ERROR: failed to parse BPMN XML: ${e.message ?? e}`);
+  process.exit(2);
+}
+
+// Build the model and run all rules.
+const canvasState = buildModel(definitions);
+const knownIds = collectKnownVariableIds(canvasState);
+
+const findings = [];
+for (const diagram of Object.values(canvasState.diagramsById)) {
+  // Skip the trivial root-only "single blank start, no edges" diagram, mirroring
+  // ValidateBpmnFlowUtils.validateBpmnFlow.
+  const realNodes = diagram.nodes.filter((n) => n.type !== "bpmn:Participant");
+  if (
+    diagram.diagramId === canvasState.rootDiagramId &&
+    realNodes.length === 1 &&
+    realNodes[0].type === "bpmn:StartEvent" &&
+    diagram.edges.length === 0
+  ) {
+    continue;
+  }
+  findings.push(...validateDiagram(diagram, canvasState, { enableMissingRootVariableValidation: true }));
+}
+findings.push(...validateVariableExistence(allNodes(canvasState), allEdges(canvasState), knownIds));
+findings.push(...validateVariableNotSet(allNodes(canvasState), allEdges(canvasState), knownIds, canvasState));
+
+// Optional connection liveness ping (Maestro-original extra).
+if (resourceArg) {
+  const ping = pingConnections(resourceArg);
+  if (ping.note) console.error(`NOTE: ${ping.note}`);
+  else if (ping.ok) console.error(`connection liveness ping ok`);
+}
+
+const errors = findings.filter((f) => f.severity === SEVERITY.ERROR);
+const warnings = findings.filter((f) => f.severity === SEVERITY.WARNING);
+
+const fmt = (f) => `  [${f.severity}] ${f.code}: ${f.message}${f.elementId ? ` (element: ${f.elementId})` : ""}`;
+
+if (warnings.length) {
+  console.error("WARNINGS:");
+  for (const w of warnings) console.error(fmt(w));
+}
+
+if (errors.length === 0) {
+  console.log("VALID");
+  process.exit(0);
+}
+
+console.error("ERRORS:");
+for (const e of errors) console.error(fmt(e));
+console.error(`\n${errors.length} blocking error(s), ${warnings.length} warning(s).`);
+process.exit(1);

package/skills/uipath-maestro-case/SKILL.md

@@ -34,7 +34,7 @@ When `sdd.md` is absent, **Phase 0 interview** generates one interactively (list
 7. **HARD STOP after `tasks.md`.** AskUserQuestion: `Approve and proceed` / `Request changes`. Re-read `tasks.md` before executing.
 8. **Unresolved resource → placeholder, never fabricate IDs.** Keep `<UNRESOLVED: ...>` markers in `tasks.md`. Placeholder **task**: node with `type` + `displayName` + structural fields, `data: {}`; conditions still reference the TaskId. Placeholder **event trigger**: node with render fields + `data.uipath: { serviceType: "Intsvc.EventTrigger" }` only (no other `data.uipath` keys); `entry-points.json` entry appended. No trigger-edge is created (edges retired) — the first stage's `case-entered` entry condition starts the case. See [references/placeholder-tasks.md](references/placeholder-tasks.md) and [references/plugins/triggers/event/impl-json.md § Placeholder fallback](references/plugins/triggers/event/impl-json.md).
 9. **Persist every registry resolution to `registry-resolved.json`** — search query, all matches, selected result, rationale.
-10. **Cross-task refs:** `"Stage Name"."Task Name".output_name` in planning, resolve to `=vars.<outputId>` at execution by reading source's `id` field (the resolver match key; `var` mirrors `id` on self-declaring task outputs but `.id` is symmetric with the runtime resolver per io-binding validator). Discover output names via `uip maestro case spec` (connector tasks) or `uip maestro case tasks describe` (non-connector tasks) — never fabricate. See [references/bindings-and-expressions.md](references/bindings-and-expressions.md) and [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md).
+10. **Cross-task refs:** plan as `"Stage Name"."Task Name".output_name`. Resolve to `=vars.<outputId>` at execution by reading the source's `id` field (the resolver match key — `var` mirrors `id` on self-declaring task outputs, but `.id` is symmetric with the runtime resolver per the io-binding validator). Discover output names via `uip maestro case spec` (connector tasks) or `uip maestro case tasks describe` (non-connector tasks) — never fabricate. **Inside** a larger `=js:` expression (composite payload, condition, SLA), use the in-expression marker `vars.$xref('Stage','Task','output')` instead — resolved at Step 11.5. See [references/bindings-and-expressions.md](references/bindings-and-expressions.md) and [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md).
 11. **HARD STOP between Phase 2 (Prototyping) and Phase 3 (Implementation) — unconditional, every run.** Run `validate --skeleton` (structural checks only — skips tasks/SLAs/escalations/entry-exit rules), surface counts, present AskUserQuestion: `Publish for review` / `Skip publish and continue` / `Abort`. Do NOT halt on Phase 2 validate errors — advisory only; user inspects via `Abort`. Never skip prompt for auto mode, non-interactive mode, prior approval. If harness forbids prompts, halt with error. **On `Publish for review`: print `DesignerUrl` as plain-text output BEFORE invoking the second AskUserQuestion — never embed URL only inside question body.** Additional hard stops gate Phase 4 retry exhaustion (`Retry with fix` / `Pause for manual edit` / `Abort`), Phase 5 entry (`Run debug session` / `Skip to Publish`), and Phase 6 entry (`Publish to Studio Web` / `Done`). Full contract in [`references/phased-execution.md`](references/phased-execution.md).
 12. **Never run `uip maestro case debug` automatically.** Executes case for real — emails, messages, API calls. Explicit user consent only.
 13. **All skill artifacts: Read + Write/Edit only.** Applies to `caseplan.json`, `sdd.md`, `sdd.draft.md`, `tasks.md`, `tasks/registry-resolved.json`, `tasks/trigger-spec-cache.json`, `tasks/spec-cache.<elementId>.json`, `bindings_v2.json`, `id-map.json`, `entry-points.json`, `build-issues.md`. No `python`, `node`, `jq`, `sed`, `awk`, or scripts that open/parse/modify/save these files. **Specifically forbidden** (common slip): `node -e "...fs.writeFileSync..."`, `node -e "...fs.readFileSync..."`, `node -e "..." > <artifact>`, `jq '...' <artifact> > <artifact>`, `python -c "...open(...,'w')..."`, `sed -i`, `awk -i inplace`, or any shell redirection (`>`, `>>`, `| tee`) onto a skill artifact regardless of interpreter. **Writing a helper script under `/tmp` or anywhere else to assemble a skill artifact is also forbidden** — the build-assembler pattern (`/tmp/build-caseplan.js`, `/tmp/gen-tasks.py`, etc.) is the same Rule 13 violation as inline `node -e`, regardless of "mechanical copy" or "avoid Read+Write churn" framing. If `caseplan.json` exceeds ~30KB and a single Write feels too large, split into the Phase-2-skeleton-then-Phase-3-fill cadence (per [case-editing-operations.md § Per-section batch write contract](references/case-editing-operations.md#per-section-batch-write-contract--canonical)) — never via helper script. Bash subprocesses OK ONLY for UUID v4 generation (`node -e "console.log(crypto.randomUUID())"` for `operate.json.projectId` and `entry-points.json` `uniqueId` — subprocess MUST NOT `require('fs')` or use redirection), CLI metadata fetches, validate, debug, and solution scaffold/upload. **Prefixed IDs (`Stage_`, `t`, `Rule_`, etc.) are picked inline by the agent — no subprocess.** See [references/case-editing-operations.md § Tool usage](references/case-editing-operations.md#tool-usage--mandatory).
@@ -68,6 +68,8 @@ Read [references/planning.md](references/planning.md). Produces:
 - `tasks/tasks.md` — T-numbered entries (stages → tasks → conditions → SLA)
 - `tasks/registry-resolved.json` — audit trail
 
+> **`tasks/` is created at the working root, adjacent to `sdd.md` — NEVER inside the solution/project folder (`<Solution>/`).** This holds regardless of where the case file lives: `caseplan.json` sits at `<Solution>/<Project>/caseplan.json`, but the planning artifacts (`tasks.md`, `registry-resolved.json`) stay next to `sdd.md` at the root.
+
 HARD STOP: AskUserQuestion approval. Loop on `Request changes`.
 
 ### Phase 2 — Prototyping
@@ -90,6 +92,7 @@ Re-read `tasks.md` AND `caseplan.json` (Step 9.6). Then:
 2. I/O binding all task classes (Step 9.8) — per [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md)
 3. Conditions all 4 scopes (Step 10)
 4. SLA + escalation (Step 11)
+5. In-expression `vars.$xref` marker resolution (Step 11.5) — per [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md)
 
 No hard stop on Phase 3 exit — proceed directly to Phase 4.
 
@@ -186,6 +189,7 @@ Completion report + **HARD STOP** AskUserQuestion (Step 13): `Run debug session`
 - **One task per lane — except parallel members of a `runs-sequentially` group.** Default: each task own `lane` index in `stageNode.data.tasks[laneIndex][]`, lane is FE layout only. Exception: tasks sharing a `runs-sequentially` task-entry condition that are meant to run in parallel share the same lane (shared lane = parallel siblings inside the sequential group, carries execution semantics). Solo runs-sequentially tasks still get their own lane.
 - **Do NOT edit `content/*.bpmn`.** Auto-generated, will be overwritten. Edit `content/*.json` only.
 - **Do NOT fabricate expression syntax for conditional SLA rules.** Describe condition in natural language; execution phase determines exact form.
+- **Do NOT place `tasks/` inside the solution or project directory.** `tasks/` (and its `tasks.md`, `registry-resolved.json`) lives next to `sdd.md` at the working root — NOT inside `<Solution>/` or `<Solution>/<Project>/`. The case file path (`<Solution>/<Project>/caseplan.json`) does NOT root the planning artifacts; they track `sdd.md`, not `caseplan.json`.
 - **Do NOT invoke other skills automatically.** If case needs process/agent/action that doesn't exist, emit placeholder task (Rule 8) and list missing resources in completion report. On-demand resource creation is future milestone.
 
 > **Trouble?** Use `/uipath-feedback` to send report.

package/skills/uipath-maestro-case/assets/templates/sdd-template-examples.md

@@ -473,6 +473,16 @@ In v1, **every variable accessible via `=vars.X` must appear in the Case Variabl
 
 **Workaround:** if you want a "task-local" variable that doesn't pollute Case Variables, rely on the task's auto-emitted schema fields directly via their natural names. The skill auto-emits all of a task's response fields; you only need a Case Variables row when you want to RENAME the variable or expose it as case-level state with custom Default / Type / Description.
 
+**In an expression — `vars.$xref(...)`.** When the upstream output is one term *inside* a larger `=js:` expression (a composite payload, an `IF`, an SLA expression) rather than the whole input value, embed the in-expression marker `vars.$xref('Stage Name','Task Name','output_name')` (single quotes only). It resolves to the source output's `var` at build time (Step 11.5) — no Case Variables row, no "middle variable". Use whole-value `<- "Stage"."Task".out` when the output IS the entire input.
+
+**Worked example** — a composite input payload built from two upstream decisions, no Case Variables rows:
+
+```json
+"value": "=js:({ approvalDecision: vars.$xref('AP Review','AP lead approval','outcome'), urgentPaymentDecision: vars.$xref('AP Review','Urgent payment','outcome') })"
+```
+
+Full marker semantics: [bindings-and-expressions.md § In-expression references](../../references/bindings-and-expressions.md#in-expression-references-varsxref).
+
 ---
 
 ## Authoring checklist

package/skills/uipath-maestro-case/assets/templates/sdd-template.md

@@ -61,7 +61,7 @@ build the case in the Case Designer without guessing.
 
 6. **Entry/exit conditions use WHEN + IF format:**
    - **WHEN** = the rule type (event that triggers evaluation, e.g., `selected-stage-completed("Intake")`)
-   - **IF** = the optional `conditionExpression` (JavaScript expression evaluated against case variables, e.g., `applicationStatus == "Approved"`)
+   - **IF** = the optional `conditionExpression` (JavaScript expression evaluated against case variables, e.g., `applicationStatus == "Approved"`). To gate on an upstream task's output without a middle case variable, embed `vars.$xref('Stage','Task','output')` directly in the IF expression — see [bindings-and-expressions.md § In-expression references](../../references/bindings-and-expressions.md#in-expression-references-varsxref).
    - **Display Name** (optional) = human-readable label for the condition row. Leave blank (`—`) to let the skill default it: entry/task-entry conditions → `Entry Rule {N}`; stage-exit/case-exit conditions → `Complete Rule {N}` when Marks Complete is `Yes`, `Exit Rule {N}` when `No`. `N` is the 1-based index within the same label kind in the stage / task / case container. Set a value only to override the default.
    - **`wait-for-connector` WHEN** binds an Integration Service connector event. Name it inline in the WHEN cell (e.g. `wait-for-connector (Outlook "Email Received", Inbox)`) AND add a **Connector Rule Detail** block under the condition table. Applies to stage-entry, stage-exit, case-exit, and task-entry conditions. The IF cell is then an optional `=js:` gate on **case state** (`=js:vars.X`); the event payload is NOT directly accessible (no `event` namespace). **In-rule event-payload gating is NOT supported at runtime** — same-rule extract-then-gate (`response.X -> caseVar` on outputs + `=js:vars.caseVar` in IF) does not work; the case-backend evaluates the gate before the extract runs. To condition on the event payload, extract `response.field -> caseVar` on the connector rule and place the case-state gate on the DOWNSTREAM stage-entry / task-entry condition (where the extract has already populated the case var).
 
@@ -112,7 +112,8 @@ The generated SDD must start with:
 
 1. **Title** — `# SDD — {Case Name}`
 2. **Subtitle** — Case Definition Blueprint blurb
-3. **Table of Contents** — Numbered list with markdown anchor links. Use plain numbered list items with links, NOT headings (no `###`). Format:
+3. **(optional) Version / Change Log** — a single blockquote under the subtitle when the SDD is revised: `> **Version: vN** — <one-line what-changed-and-why>`. Use it to record material build-driven corrections (e.g. "rebound `caseId` to `=metadata.ExternalId` — the workflow does not return it") so a reader/coding-agent sees the rationale, not just the result. Omit on a first draft.
+4. **Table of Contents** — Numbered list with markdown anchor links. Use plain numbered list items with links, NOT headings (no `###`). Format:
    ```markdown
    ## Table of Contents
 
@@ -122,7 +123,7 @@ The generated SDD must start with:
       - [Stage 2: {Name}](#stage-2-{slug}) — {N} tasks
       ...
    3. [Personas & App Views](#section-3-personas--app-views) — {N} Personas, Process App Views
-   4. [Integrations](#section-4-integrations) — Integration Service Connectors, External Agents
+   4. [Integrations](#section-4-integrations) — IS Connectors, API Workflows, Agents, Processes & RPA, Child Cases, External Agents
    ```
    Anchor slugs must match the actual heading text: lowercase, spaces→hyphens, strip special chars (e.g., `### Stage 1: Request Intake & Triage` → `#stage-1-request-intake--triage`).
 
@@ -161,6 +162,9 @@ The generated SDD must start with:
 | Priority | Choiceset: {comma-separated values} — Default: {value} |
 | Case-Level SLA | {count} {unit: h/d/w/m} |
 | SLA Type | {time-based \| condition-based} |
+| Case App | {Enabled \| Disabled} — whether the in-product Case App UI is on (`caseAppEnabled`; default Disabled) |
+| Task-output passing | {Direct \| Shared} — `caseDirectlyPassTaskOutputs` (Direct = a task's outputs flow straight to downstream tasks; default Direct) |
+| Case Identifier source | {`=metadata.ExternalId` (platform-generated — the default) \| custom} — what every `caseId` task input binds to |
 
 ### Case-Level SLA Escalation Rules
 
@@ -215,9 +219,9 @@ DO NOT include in Configuration:
 
 ### Case Variables
 
-> Complete inventory of all case-level variables and arguments. Every row's `Category` column is REQUIRED — drives classification at build time. Inference from other columns is no longer supported.
+> This table holds **only**: `In` / `Out` arguments; trigger-payload `Variable`s (`sourceTriggers` + `sourceFields`); and case-level state read by a condition (`IF`) or consumed in **≥ 2 places**. An input that is simply one upstream task's output is **referenced directly** — whole-value `<- "Stage"."Task".out`, or in-expression `vars.$xref('Stage','Task','out')` — and is **NOT** a row here (the emitting task self-declares the output and is its own producer). 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. Every row's `Category` column is REQUIRED — drives classification at build time. Inference from other columns is no longer supported.
 >
-> For worked patterns by use case (single-trigger, multi-trigger, In / Out / Variable, Pattern C, etc.), see [`sdd-template-examples.md`](sdd-template-examples.md).
+> For worked patterns by use case (single-trigger, multi-trigger, In / Out / Variable, task-local-only via direct xref), see [`sdd-template-examples.md`](sdd-template-examples.md).
 
 | Name | Category | Type | sourceTriggers | sourceFields | Default | Description |
 |------|----------|------|----------------|--------------|---------|-------------|
@@ -267,6 +271,9 @@ If neither holds, the io-binding validator surfaces the misalignment.
 - **Outputs `Binding / Value` column** uses one of two operators:
   - **`-> caseVar`** (extract): the value at the runtime path in the `Field` column is extracted into the named case variable. `Field` is the **full runtime path relative to the task's root scope** — write `response.status` for a connector payload field, `Action` for an action task's top-level output, `Error.code` for a nested error sub-field, etc. The skill emits `source: "=<Field>"` verbatim; no envelope inference.
   - **`caseVar = <expression>`** (set / compute / copy): the case variable is assigned the result of the expression at task completion. The `Field` column is `—` for `=` rows. Expression can be a literal (`"InReview"`, `5`), a computed value (`=js:(vars.count + 1)`), a top-level case-var copy (`=vars.X`), or a sub-field copy via JS eval (`=js:vars.X.Y`).
+- **In-expression upstream reference (`vars.$xref(...)`)** — inside ANY `=js:` expression (a composite input payload, a computed `=` output, an IF `conditionExpression`, an SLA expression), reference another task's output directly with `vars.$xref('Stage Name','Task Name','output_name')` instead of routing it through a "middle" case variable. Single quotes only. The skill resolves it to the source output's variable at build time. Use this whenever a case variable would exist only to carry one task's output into a downstream expression. When the output IS the entire input value (not part of a larger expression), use the whole-value `<- "Stage"."Task".output` form instead. See [bindings-and-expressions.md § In-expression references](../../references/bindings-and-expressions.md#in-expression-references-varsxref).
+
+- **Case identity — bind `caseId` to `=metadata.ExternalId`.** The case external id is platform-generated (constant prefix or external expression) and exposed as `metadata.ExternalId`; it is NOT a task output. Every task input named `caseId` binds to `=metadata.ExternalId`. **Never** author a `-> caseId` extraction on a workflow whose result has no `caseId` key — it resolves to runtime null. (`Action` is the conventional top-level output field of an `action` task — its button result — captured via `Action -> <decisionVar>`.)
 
 **Authoring rules:**
 
@@ -317,7 +324,8 @@ The runtime engine resolves the binding when the task completes, writing the res
 #### Stage Exit Conditions
 
 > **WHEN ↔ Marks Stage Complete pairing is a schema constraint (see Key Rule 4):** `Yes` row MUST use `required-tasks-completed` (or `required-stages-completed`); `No` row MAY use `selected-tasks-completed(...)`. Mixing is invalid.
-> Completion (`Yes`) and routing (`No`) rows share this one table. **Stage-to-stage routing is expressed by the destination stages' Entry Conditions** (`selected-stage-completed("This Stage")` / `selected-stage-exited("This Stage")`) — one stage can fan out to N stages, each declaring it as their entry trigger. `return-to-origin` returns to the origin stage automatically.
+> Completion (`Yes`) and routing (`No`) rows share this one table. **Regular stage-to-stage routing is expressed by the destination stages' Entry Conditions** (`selected-stage-completed("This Stage")` / `selected-stage-exited("This Stage")`) — one stage can fan out to N stages, each declaring it as their entry trigger. `return-to-origin` returns to the origin stage automatically.
+> **Exception carve-out:** to route this stage INTO a decision/signal-routed exception lane, add a gated divert row here — `Marks Stage Complete: No`, `selected-tasks-completed("<decider>")`, `IF =js:(<signal> === <exception-value>)`, `exit-only`, with `exitToStageId` → the exception stage — AND gate this stage's `Yes` completion row with the inverse `IF`. The lane returns via `return-to-origin`. Omitting the divert row → dual-fire or deadlock. See sdd-generation-rules § Logical integrity step 5.
 
 | WHEN | IF | Exit Type | Marks Stage Complete | Display Name |
 |------|-----|-----------|---------------------|--------------|
@@ -360,13 +368,28 @@ The runtime engine resolves the binding when the task completes, writing the res
 
 > If `WHEN` is `wait-for-connector`, add a **Connector Rule Detail** block under this table (see Key Rule 6).
 
+**Task envelope** (every task — render after the Entry Condition table):
+
+| Required | Run Only Once | Skip Condition |
+|----------|---------------|----------------|
+| {Yes \| No} | {Yes \| No} | {`=js:` expression that skips the task when truthy, or `—`} |
+
+> `Required: Yes` means the task counts toward the stage's `required-tasks-completed` exit — **at least one task per stage MUST be `Required: Yes`**, or the stage can never complete. `Skip Condition` is the task-level `skipCondition` envelope field (sibling of `data`); use it for "run this task only when X" gating that is not expressible as a task-entry `IF`.
+
 ---
 
 ###### Action Task Detail (type: `action`)
 
 > Use this block for every task of type `action`. The action plugin authors action tasks ONLY from a deployed Action App registered in `action-apps-index.json`; inline JSON-Schema HITL forms are not authored by the skill (an unresolved app falls back to a Rule-8 placeholder).
 
-**HITL Implementation:** Action App: {app name from `action-apps-index.json` — must be deployed}
+**HITL Implementation:** Action App: {`deploymentTitle` from `action-apps-index.json` — must be deployed}
+**Action App ID:** {`actionAppId` — concrete deployment id, or `<UNRESOLVED>`}
+**Deployment Folder:** {`deploymentFolder.fullyQualifiedName`}
+**actionType:** {the dispatch code the app's code-behind switches on — e.g., `GRNConfirmation`, `ApLeadApproval`. **A recognised code is REQUIRED; passing a human display name instead fails result mapping at runtime.** `—` only when the app is not a code-switched app.}
+**Recipient:** {typed prefix only: `Role:<name>` \| `User:<uuid>` \| `UserGroup:<uuid>` \| `Email:<addr>` \| `Expression:=vars.<id>`}
+**Priority:** {Low \| Medium \| High \| Critical} · **Task Title:** {one-line Action Center prompt} · **Labels:** {csv or `—`}
+
+> `Action App ID` + `Deployment Folder` make the SDD replicable standalone (a reader can locate the exact deployed app). `actionType` is the human-decision app's behaviour selector — treat it as a closed enum sourced from the app, not a free-text label.
 
 **Input Schema:**
 
@@ -400,13 +423,16 @@ The runtime engine resolves the binding when the task completes, writing the res
 > - **Account/Endpoint is not stored** in the compact cache. Render `—` unless the user spec supplies it explicitly.
 > If a cache is unavailable or no enabled connection is found, render `—` rather than inventing values.
 
-**Connector:** {connector name from Integration Service, e.g., "Salesforce"}
-**Connection:** {connection instance `name` from `connections.json`, e.g., "Salesforce-Prod" — or "Tenant default (connection ID {id})" when `isDefault: true`}
+**Connector:** {connector name from Integration Service, e.g., "Salesforce"} · **Connector Key:** {`connectorKey`, e.g. `salesforce`}
+**Connection:** {connection instance `name` from `connections.json`, e.g., "Salesforce-Prod" — or "Tenant default" when `isDefault: true`} · **Connection ID:** {`connectionId` — concrete, or `<UNRESOLVED>`}
+**Activity Type ID:** {`activityTypeId` from the typecache} · **Service Type:** {`serviceType`, e.g. `Intsvc.WaitForEvent`}
 **Auth Method:** {`defaultAuthenticationType` from `connectors.json`, e.g., OAuth2 \| API Key \| Basic \| Service Account}
 **Account / Endpoint:** {explicit endpoint if supplied — or "—" (not stored in the CLI cache)}
 **Operation:** {`displayName` / `operation` from `activities.json`}
 **Trigger / Event:** {trigger display name for `wait-for-connector`, or "—" for `execute-connector-activity`}
 
+> `Connection ID` + `Activity Type ID` are the concrete identities Phase 1 binds — without them the connector cannot resolve at build time; surface them here so the SDD is replicable standalone (missing either → `<UNRESOLVED>` + a high review item).
+
 **Inputs:**
 
 | Field | Type | Binding |
@@ -458,6 +484,14 @@ The runtime engine resolves the binding when the task completes, writing the res
 
 > Use this block for `process`, `agent`, `rpa`, and `api-workflow` tasks. These tasks do NOT support SLA — SLA column in the task summary should be "—".
 
+**Resolved Resource:** {the deployed resource's `name` — e.g. `AgedInvoiceMockIntegrationApi` (api-workflow), `InvoiceTriageAgent` (agent), `AgedInvoice_StatementReconciliation` (rpa). This is the `name`-binding default — REQUIRED so the SDD names which resource the task invokes.}
+**Folder Path:** {resolved `folders[0].fullyQualifiedName` — the `folderPath`-binding default. MUST be the resource's exact folder (never a parent path, or the job faults at runtime).}
+**Resource Identity:** {resolved id (+version) — `apiWorkflowId` / `agentId` / `processOrchestrationId` — or `<UNRESOLVED>`. Recommended in the SDD body so it is replicable standalone; also carried in `tasks/registry-resolved.json`.}
+**Binding Sub-Type:** {`Api` (api-workflow) \| `Agent` (agent) \| `ProcessOrchestration` (process) \| `—` (rpa) — the `resourceSubType` on the name/folderPath bindings. Omitting it makes Studio Web report the resource as not found.}
+**Dispatch / Operation:** {when the resource is a shared façade dispatched by a parameter, name the selector and value — e.g. `requestSource = "RegisterCaseShell"`. Render `—` for single-purpose resources. The selector itself is also an Inputs row (a literal binding).}
+
+> The resource **name + folder** make this task replicable from the SDD alone; without them a reader knows the I/O contract but not which deployed resource to bind. When one façade resource (e.g. a generic mock-integration API, or a code-switched action app) backs many tasks, the **Dispatch / Operation** value is what distinguishes their behaviour — capture it explicitly, not just as an opaque input.
+
 **Inputs:**
 
 | Field | Type | Binding |
@@ -473,6 +507,8 @@ The runtime engine resolves the binding when the task completes, writing the res
 
 > Target case variable MUST exist in Case Variables table. See Section 2 I/O bindings explainer for `->` vs `=` operator semantics.
 
+> **I/O completeness (resolved resources).** Once this task binds a deployed resource, every **required** input the resource declares MUST appear as an Inputs row with a value (or `<UNRESOLVED>` + a high review item), and every `-> caseVar` output `Field` MUST be a field the resource actually emits. **An input fed by an upstream task's output is bound directly — `<- "Stage"."Task".out` (whole value) or `vars.$xref('Stage','Task','out')` (inside a `=js:` expression) — and is NOT declared as a Case Variable.** Declare a Case Variable only to rename, default, retype, or expose case-level state.
+
 ---
 
 ## Section 3: Personas & App Views
@@ -497,13 +533,15 @@ The runtime engine resolves the binding when the task completes, writing the res
 
 ## Section 4: Integrations
 
-**Purpose:** External systems and how they connect to the case. Covers Integration Service connectors with their operations and external agent configurations.
+**Purpose:** The complete inventory of every deployed resource and external system the case binds — **one subsection per resource family**, so the full integration/resource footprint is visible and replicable from the SDD alone. Render only the subsections whose task type appears in the case; for a family with no tasks, either omit the subsection or render the heading with `> None.`. Every resource row carries the **folder** and **resource id** so a reader can locate the exact deployed artifact (mirrors the per-task `Resolved Resource` / `Folder Path` cells in Section 2 — this section is the de-duplicated roll-up).
 
 ### Integration Service Connectors
 
-| Connector | System | Auth Method | Operations Used | Used By Tasks |
-|-----------|--------|-------------|-----------------|---------------|
-| {connector name} | {target system name} | {OAuth2 \| API Key \| Basic \| Service Account \| ...} | {comma-separated operation names} | {comma-separated task names} |
+> For `execute-connector-activity` and `wait-for-connector` tasks. `> None.` when the case has neither.
+
+| Connector | Connector Key | System | Connection (ID) | Auth Method | Operations Used | Used By Tasks |
+|-----------|---------------|--------|-----------------|-------------|-----------------|---------------|
+| {connector name} | {connectorKey} | {target system} | {connection name (connectionId)} | {OAuth2 \| API Key \| Basic \| Service Account \| ...} | {comma-separated operation names} | {comma-separated task names} |
 
 > For each connector, provide operation detail. If CLI registry data is available, include actual I/O fields from the registry.
 
@@ -511,13 +549,47 @@ The runtime engine resolves the binding when the task completes, writing the res
 
 **Operations:**
 
-| Operation | Method | Input Fields | Output Fields |
-|-----------|--------|-------------|---------------|
-| {operation name} | {GET \| POST \| PUT \| DELETE \| PATCH \| EVENT} | {field: type, field: type, ...} | {field: type, field: type, ...} |
+| Operation | Activity Type ID | Method | Input Fields | Output Fields |
+|-----------|------------------|--------|-------------|---------------|
+| {operation name} | {activityTypeId} | {GET \| POST \| PUT \| DELETE \| PATCH \| EVENT} | {field: type, ...} | {field: type, ...} |
+
+### API Workflows
+
+> For `api-workflow` tasks. One row per **distinct** workflow (de-duplicate across tasks).
+
+| Workflow | Folder | Resource ID (+version) | Inputs → Outputs | Used By Tasks |
+|----------|--------|------------------------|------------------|---------------|
+| {workflow name} | {folders[0].fullyQualifiedName} | {apiWorkflowId (+version)} | {in fields → out fields} | {comma-separated task names} |
+
+> **Shared-façade note:** when one workflow backs multiple tasks via a dispatch parameter, list the distinct selector values in the `Used By Tasks` cell, e.g. `Start case (requestSource=StartAgedInvoiceCase), Register shell (requestSource=RegisterCaseShell)`.
+
+### Agents
+
+> First-class UiPath `agent` tasks (NOT externally-hosted agents — those go under **External Agents** below). One row per distinct agent.
+
+| Agent | Folder | Resource ID (+version) | Inputs → Outputs (or shared contract) | Used By Tasks |
+|-------|--------|------------------------|----------------------------------------|---------------|
+| {agent name} | {folders[0].fullyQualifiedName} | {agentId (+version)} | {in fields → out fields, or "shared agent contract"} | {comma-separated task names} |
+
+### Processes & RPA
+
+> For `process` and `rpa` tasks. One row per distinct resource.
+
+| Resource | Type | Folder | Resource ID (+version) | Used By Tasks |
+|----------|------|--------|------------------------|---------------|
+| {resource name} | {process \| rpa} | {folders[0].fullyQualifiedName} | {processOrchestrationId (+version)} | {comma-separated task names} |
+
+### Child Cases
+
+> For `case-management` tasks. Render only if the case launches a child case.
+
+| Child Case | Identifier Prefix | Wait for Completion | Used By Tasks |
+|------------|-------------------|---------------------|---------------|
+| {child case name} | {2-4 char prefix} | {Yes \| No} | {comma-separated task names} |
 
 ### External Agents
 
-> Include this table only if the case uses external agent tasks.
+> Externally-hosted AI agents (CrewAI, Salesforce Einstein, Databricks, LangChain, …), modeled as `api-workflow` / `execute-connector-activity` tasks (the skill has no first-class `external-agent` type). Include this table only if the case uses such an agent.
 
 | Agent | Service Type | Endpoint | Used By Tasks |
 |-------|-------------|----------|---------------|

package/skills/uipath-maestro-case/references/bindings-and-expressions.md

@@ -36,6 +36,8 @@ When using the literal/expression mode, the `--value` string can start with one
 
 > The prefix tells you WHAT the value refers to. The **sink** tells you HOW to wrap it — see [§ Canonical form per sink](#canonical-form-per-sink) below.
 
+> **Variable / binding ids are always letter-leading.** Formal-arg slots use a `v` prefix, bindings use `b`, and companion ids inherit the (letter-leading) variable name — so `<id>` in `=vars.<id>` / `=bindings.<id>` is always a valid C# identifier. Dot notation is always safe; bracket notation (`vars["…"]`) is never needed. A digit-leading id would fail the case BPMN with `illegal ID` — see [global-vars § Formal-arg slot ID format](plugins/variables/global-vars/impl-json.md#formal-arg-slot-id-format).
+
 ## Canonical form per sink
 
 Every `=`-prefixed value in `caseplan.json` is dispatched to one of two runtime evaluators based on the sink it lands in. **The wrap form must match the sink** — wrong wrap is a silent runtime fault (the literal string arrives at the consumer instead of the resolved value).
@@ -127,6 +129,30 @@ target_input.value = f"=vars.{src_output['var']}"
 
 See [plugins/variables/io-binding/impl-json.md](plugins/variables/io-binding/impl-json.md) for the full procedure.
 
+### In-expression references (`vars.$xref(...)`)
+
+Whole-value `<-` (above) resolves only when it IS the entire input value. To reference an upstream task output from **inside** a `=js:` expression — a composite payload, a `conditionExpression`, an SLA `expression`, a computed `=` output — embed a `vars.$xref(...)` marker. This eliminates the "middle variable" that would otherwise exist solely to carry one task's output into a downstream expression.
+
+**Marker form** (quote-safe — single quotes are legal inside a JSON double-quoted value):
+
+```
+vars.$xref('Stage Name','Task Name','output_name')
+```
+
+- Three args = the same name-triple as whole-value `<-`: source stage `data.label`, source task `displayName`, source output `name`.
+- Single quotes ONLY — double quotes break the enclosing JSON string. Names containing a literal `'` are unsupported (re-author the name).
+- Drop it anywhere a bare `vars.X` is legal inside an `=js:` expression. It resolves to bare `vars.<var>` (NOT `=vars.` — it is already inside `=js:`).
+
+**Example** — composite input payload, no middle variables:
+
+```json
+"value": "=js:({ approvalDecision: vars.$xref('AP Review','AP lead approval','outcome'), urgentPaymentDecision: vars.$xref('AP Review','Urgent payment','outcome') })"
+```
+
+**Resolution** — a single post-pass near the end of Phase 3 (Step 11.5, after conditions and SLA are written) walks every string value in `caseplan.json`, resolves each marker to the source output's **post-dedup** `var`, and substitutes `vars.<var>` in place. Because it runs after all outputs are minted and deduped, it reads the real suffixed id (`outcome2`, `data6`) — strictly more stable than hand-authoring `=js:vars.outcome2`. An unresolved marker is a build-time ERROR surfaced via **AskUserQuestion** (Check 4), not a silent fail — and `vars.$xref` would throw at runtime too (a method call on `vars`). See [plugins/variables/io-binding/impl-json.md § In-Expression Marker Resolution](plugins/variables/io-binding/impl-json.md#in-expression-marker-resolution-step-115).
+
+> **Additive, not a replacement.** Whole-value `input <- "Stage"."Task".out` keeps resolving to `=vars.<var>` via the binding procedure. The `vars.$xref(...)` marker is only for the in-expression case. Use whole-value `<-` when the output IS the input; use the marker when the output is one term inside a larger `=js:` expression.
+
 ## Examples
 
 ### Literal and expression inputs

package/skills/uipath-maestro-case/references/case-editing-operations.md

@@ -90,6 +90,9 @@ All IDs follow the CLI's `prefixedId(prefix, count)` scheme: a fixed prefix + `c
 | Sticky note | `StickyNote_` | 6 | `StickyNote_aBcDeF` | |
 | SLA escalation | `esc_` | 6 | `esc_gH2jKl` | |
 | Binding | `b` | 8 | `b3KmNp7Q9` | |
+| Variable formal arg slot (`variables.inputs[]` / `variables.outputs[]` `id`) | `v` | 8 | `vK3mNp9Qx` | In/Out-arg formal slot. Surfaces in case BPMN as `<uipath:input id>` + dot-referenced via `=vars.<id>` — MUST be letter-leading. See [global-vars](plugins/variables/global-vars/impl-json.md#formal-arg-slot-id-format). |
+
+> **Leading-letter requirement.** Any id that surfaces as a BPMN element / input id, or is referenced via `=vars.<id>` / `=bindings.<id>` dot notation, MUST start with a letter or underscore (C# identifier + XML NCName rules). Every prefix above is letter-leading, which satisfies this — never mint a **prefix-less** random id for a variable / argument slot; a digit-leading id fails BPMN with `illegal ID`.
 
 ### Algorithm — inline, no subprocess
 

package/skills/uipath-maestro-case/references/implementation.md

@@ -172,9 +172,9 @@ On continue (either `Skip publish and continue` or `Continue to phase 3` after p
 
 ---
 
-# Phase 3 — Implementation (Steps 9.6 – 11)
+# Phase 3 — Implementation (Steps 9.6 – 11.5)
 
-Steps 9.6 onwards wire connector task schemas, input/output values, conditions, and SLA. Full contract in [phased-execution.md § Phase 3](phased-execution.md#phase-3--implementation).
+Steps 9.6 onwards wire connector task schemas, input/output values, conditions, SLA, and in-expression marker resolution. Full contract in [phased-execution.md § Phase 3](phased-execution.md#phase-3--implementation).
 
 ## Step 9.6 — Phase 3 re-entry
 
@@ -187,6 +187,7 @@ Before any Phase 3 mutation:
    2. Bind task I/O values (Step 9.8)
    3. Add conditions (Step 10)
    4. Configure SLA + escalation (Step 11)
+   5. Resolve in-expression `vars.$xref` markers (Step 11.5)
 
    Inside each section, also seed per-T-entry sub-items (one per T-entry that section will Edit). Mark each `in_progress` before composing the entry's mutation in reasoning, `completed` after the Edit returns success. Per-T-entry items are the audit trail under the per-section batched contract (per [case-editing-operations.md § Per-section batch write contract](case-editing-operations.md#per-section-batch-write-contract--canonical)).
 
@@ -247,11 +248,15 @@ Skip the re-Read between sibling Edits. One validate at section end. Per-scope c
 
 One Read of `caseplan.json` at Step 11 entry. Group `tasks.md §4.8` entries by target (root or stage). For each target, one Edit replacing that target's full `slaRules[]` array per [`plugins/sla/impl-json.md`](plugins/sla/impl-json.md). Skip the re-Read between sibling Edits. Supports per-conditional-rule escalations, ExceptionStage SLA, and multi-recipient single rules. One validate at section end.
 
+## Step 11.5 — Resolve in-expression `vars.$xref` markers (whole-file pass)
+
+Runs after bindings (9.8), conditions (10), and SLA (11) — when every task / trigger / rule output is minted and deduped (the dedup pool spans tasks ∪ triggers ∪ rules, so a marker's target `var` is not final until Step 10's rule outputs are minted). Resolve every `vars.$xref('Stage','Task','output')` marker in `caseplan.json` in ONE pass: one Read, then Edit each string value holding a marker — substitute the source output's post-dedup `var` as bare `vars.<var>` (no leading `=`; the marker already sits inside `=js:`). Sink-blind: covers composite input payloads, `conditionExpression`, SLA `expression`, computed `=` outputs, and connector body fields in one place. An unresolved name-triple is an ERROR (Check 4 below). Algorithm + pseudocode: [`plugins/variables/io-binding/impl-json.md § In-Expression Marker Resolution`](plugins/variables/io-binding/impl-json.md#in-expression-marker-resolution-step-115). One validate at section end.
+
 ## Step 12 — End-of-Phase-3 validator pass
 
 > **Algorithm reference:** the per-check pseudocode + AskUserQuestion prompt templates + skill-response-per-pick details all live in [`plugins/variables/io-binding/impl-json.md § Binding Procedure`](plugins/variables/io-binding/impl-json.md#binding-procedure). This step is the orchestration hook; that doc is the algorithm. When in doubt, follow the impl-json doc.
 
-After all value bindings (Step 9.8), conditions (Step 10), and SLA (Step 11) are written, invoke the end-of-Phase-3 validator — Checks 1, 2, 3.
+After all value bindings (Step 9.8), conditions (Step 10), SLA (Step 11), and marker resolution (Step 11.5) are written, invoke the end-of-Phase-3 validator — Checks 1, 2, 3, 4, 5.
 
 - **Check 1** — Resolve every `=vars.X` reference against `variables.{inputs, inputOutputs}[].id`. Scan all task input `value` fields, entry/exit condition expressions (stage and task), case-exit and trigger rule expressions, SLA expressions, and `=js:` expressions anywhere they appear. On unresolved → **AskUserQuestion** offering: (a) name the intended variable, (b) remove the reference, (c) continue with best-effort emit (entry logged under Open Items, runtime returns undefined).
 - **Check 2 — Out-arg producer presence** — For every formal Out-arg in `variables.outputs[]`, verify the producer/Default situation per [`io-binding/impl-json.md` § Check 2](plugins/variables/io-binding/impl-json.md):
@@ -259,8 +264,10 @@ After all value bindings (Step 9.8), conditions (Step 10), and SLA (Step 11) are
   - **No Default + producer declared in SDD on a Rule 17 placeholder task** (declared-but-unresolvable) → no prompt; silent log to `## Open Items for User` in `tasks/build-issues.md`. Rule 17 already prompted the author for this task.
   - **No Default + no producer declared anywhere (pure orphan)** → AskUserQuestion offering 4 options: (a) add producer task output, (b) add Default value, (c) recategorize as Variable / remove, (d) continue with best-effort emit (entry logged under Open Items).
 - **Check 3** — Type mismatch between `=vars.X` reference and consumer slot → log WARN inline (non-blocking; string coercion is runtime-tolerant).
+- **Check 4 — No surviving `$xref` markers** — Scan every string value in `caseplan.json` for the literal `$xref(`. Step 11.5 resolves all; any survivor means its name-triple failed (typo'd stage / task / output) — the same class of failure as a Check 1 unresolved `=vars.X`, so it gets the same interactive remediation. On unresolved → **AskUserQuestion** (present the outputs that DO exist on the named task as candidates): (a) name the intended source output — skill rewrites the triple, re-resolves, substitutes `vars.<var>`; (b) edit the SDD expression + re-run the Phase 1 dispatcher (when the output genuinely doesn't exist); (c) continue with best-effort emit (token left unsubstituted, entry logged under Open Items; `vars.$xref(...)` throws at runtime until fixed). Detail: [`io-binding/impl-json.md` § Check 4](plugins/variables/io-binding/impl-json.md).
+- **Check 5 — Resolved-resource I/O completeness** — For each task with a persisted contract in `tasks/registry-resolved.json`, verify every **required** declared input has a bound `value` and every extract output `Field` exists in the resolved output contract. An upstream-output-fed input (`=vars.<var>` / resolved `$xref`) counts as bound with NO §1.5 row. On unbound-required-input or phantom-output-field → **AskUserQuestion**: (a) bind / re-point, (b) `<UNRESOLVED>`+review-item / drop row, (c) continue with best-effort emit (entry logged under Open Items; runtime null until fixed). Tasks with no contract (placeholder / `<UNRESOLVED>`) are skipped. Detail: [`io-binding/impl-json.md` § Check 5](plugins/variables/io-binding/impl-json.md#check-5--resolved-resource-io-completeness).
 
-**Build-with-best policy:** for any user pick of "continue with best-effort emit" on a Check 1 or Check 2 AskUserQuestion, append a `## Open Items for User` entry to `tasks/build-issues.md` and proceed to Phase 4. AskUserQuestion is the surface; build-with-best is the escape. The skill conservatively emits what it has; Phase 4 validate stays green (structural validity is intact); runtime concerns are listed for pre-publish review.
+**Build-with-best policy:** for any user pick of "continue with best-effort emit" on a Check 1, Check 2, Check 4, or Check 5 AskUserQuestion, append a `## Open Items for User` entry to `tasks/build-issues.md` and proceed to Phase 4. AskUserQuestion is the surface; build-with-best is the escape. The skill conservatively emits what it has; Phase 4 validate stays green (structural validity is intact); runtime concerns are listed for pre-publish review.
 
 **Reporting:** at end of Phase 4, count entries in the `## Open Items for User` section of `tasks/build-issues.md` (read the file after writing). If count > 0, the completion report MUST include a literal line of the form:
 

package/skills/uipath-maestro-case/references/phase-0-interview.md

@@ -96,6 +96,7 @@ The agent privately fills out the SDD shape against [`sdd-template.md`](../asset
   > `Defaulting to single "Process Owner" persona (source: inferred-default:no roles mentioned).`
 - Required fields still missing → marked as gaps to Ask.
 - Optional fields still missing → marked `—` in the draft. No question.
+- **§1.5 declare-vs-xref (apply while sketching variables, every path).** Mint a §1.5 row ONLY for `In` / `Out` args, trigger-payload Variables, and case-level state read by a condition or in ≥ 2 places. An input that is just one upstream task's output is referenced directly (`<- "Stage"."Task".out` / `vars.$xref('Stage','Task','out')`), NEVER relayed through a new §1.5 variable. This holds on the **doc-derived path** (Listen reads a PDD/spec → Sketch) too, where the interactive Resolve back-solve does not run — so the steer must be applied here. See [sdd-generation-rules.md § 1.5 Case Variables](sdd-generation-rules.md) and § Variable lineage closure.
 
 **Required fields (block until answered):**
 
@@ -280,8 +281,8 @@ Before per-task prompts, run all task searches in parallel, then bucket results:
 
 | Bucket | Definition |
 |---|---|
-| **A — single high-confidence** | Exactly 1 match, AND the match's name shares ≥ 1 token (case-insensitive, ≥ 3 chars) with the task's `Task Name` |
-| **B — ambiguous** | Multiple matches, OR single match with no token overlap |
+| **A — single high-confidence** | Exactly 1 match **across all folders**, AND the match's name shares ≥ 1 token (case-insensitive, ≥ 3 chars) with the task's `Task Name` |
+| **B — ambiguous** | Multiple matches (**including the same resource name present in ≥2 folders** — a cross-folder name never auto-confirms), OR single match with no token overlap |
 | **C — empty** | 0 matches across cache files |
 
 Present a single upfront AskUserQuestion **only when bucket A is non-empty**:
@@ -295,12 +296,12 @@ For each bucket A auto-confirm, record `tenant-registry:<resource-name>` provena
 
 #### Per-task prompts (bucket B + bucket C remainder)
 
-Per-task AskUserQuestion (4 options max):
+Per-task AskUserQuestion (4 options max). **When candidate matches differ by folder, each option label MUST carry the match's folder `fullyQualifiedName`** — the user is choosing a folder, not just a name. Tasks resolve independently, so the resulting case may bind different tasks to resources in different folders/solutions (mixing is valid — there is no single-solution constraint):
 
 | Option | Effect |
 |---|---|
-| `<top match — name + version + type>` | Record selection. |
-| `<second match>` (if available) | Record selection. |
+| `<top match — name · folder · version · type>` | Record selection (incl. chosen folder). |
+| `<second match — name · folder · version · type>` (if available) | Record selection (incl. chosen folder). |
 | `Placeholder — resolve later` | Keep `<UNRESOLVED>` on `taskTypeId` / `typeId` / `connectionId`. Phase 1 emits placeholder task per Rule 8. |
 | `Something else` | Free-text re-search keyword, retry. |
 
@@ -323,7 +324,7 @@ For each task with required inputs the sketch has not mapped, one AskUserQuestio
 
 > `Send Slack message needs a channel and a message body — what feeds each?`
 
-Map each answer to a variable, a literal, or an upstream task's output (§Ask → Buildability musts). For an event trigger, surface required event params the same way (e.g., which mailbox folder) and fill each payload-extraction Variable's `sourceFields` path from the discovered output shape. A filter clause the connector can't support → narrate and Ask for a substitute. A required input the user skips → `<UNRESOLVED>` + a `high` review item (optional input skipped → `medium`).
+Map each answer to a variable, a literal, or an upstream task's output (§Ask → Buildability musts). **When the answer is an upstream task's output, reference it directly** — whole-value `<- "Stage"."Task".out` or, inside a larger `=js:` expression, `vars.$xref('Stage','Task','out')` — and do NOT mint a §1.5 Case Variable for it (the emitting task is its own producer; see [sdd-generation-rules.md § Resolved-resource I/O completeness](sdd-generation-rules.md#resolved-resource-io-completeness)). For an event trigger, surface required event params the same way (e.g., which mailbox folder) and fill each payload-extraction Variable's `sourceFields` path from the discovered output shape. A filter clause the connector can't support → narrate and Ask for a substitute. A required input the user skips → `<UNRESOLVED>` + a `high` review item (optional input skipped → `medium`). Coverage closes against the resource's **own required-input list**, not the user's recollection — every required input ends Resolve either bound or `<UNRESOLVED>`+review-item; the Approve gate re-checks this (§Finalization step 19).
 
 **Connection selection (connector tasks).** For each `execute-connector-activity`, `wait-for-connector`, and connector event trigger, resolve the IS **connection**, not just the activity `typeId`. When the cache holds **0 or > 1** connections for the connector, AskUserQuestion which connection — in business terms (the account / environment name, never the `connectionId`). Never auto-pick among multiple, never leave `connectionId` silently `<UNRESOLVED>`; a missing connection is a `high` review item per §Resource reality.
 
@@ -331,7 +332,7 @@ Map each answer to a variable, a literal, or an upstream task's output (§Ask
 
 **Cost.** One CLI call per resolved task, run in parallel and resolved-only. The trade is a longer Resolve for far fewer Phase 3 / 4 binding failures — wrong `Field` names and unmapped required inputs that otherwise surface only after Rule 2 locks the file.
 
-After all picks and schema discovery, write `tasks/registry-resolved.json` (Rule 9 shape — including each resolved task's fetched I/O contract). Update `sdd.draft.md` with concrete resource names and the real Inputs / Outputs `Field` names. Any unresolved task carries a paired `review_items[]` entry in the same JSON.
+After all picks and schema discovery, write `tasks/registry-resolved.json` (Rule 9 shape — including each resolved task's fetched I/O contract). The persisted contract MUST record, per resolved task, each declared **input name + `required` flag** and the full **declared output-field list** — Phase 3 io-binding Check 5 re-verifies required-input coverage and output-field fidelity against this without re-fetching ([io-binding/impl-json.md § Check 5](plugins/variables/io-binding/impl-json.md#check-5--resolved-resource-io-completeness)). Update `sdd.draft.md` with concrete resource names and the real Inputs / Outputs `Field` names. Any unresolved task carries a paired `review_items[]` entry in the same JSON.
 
 > **Phase 1 handoff.** Phase 1 reads `tasks/registry-resolved.json` and skips re-search for resolved entries. It still extends the file with any resolutions Phase 0 deferred. No artifact replay; sdd.md is the contract.