@uipath/skills 1.195.0

package/skills/uipath-maestro-case/references/phased-execution.md

@@ -0,0 +1,263 @@
+# Phased Execution: Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6
+
+Authoritative reference for the post-planning execution flow. Read before executing any T-entry from an approved `tasks.md`.
+
+> **Relationship to other docs.** This document defines phase boundaries and hard-stop contracts. Per-plugin execution detail lives in `plugins/<name>/impl-json.md`. Per-step ordering and file-system mutations live in [implementation.md](implementation.md).
+
+## v20 mode (Rule 18)
+
+When `Schema: v20` is set in `tasks.md`, the following phase modifications apply. v19 mode is unchanged.
+
+| Phase | v19 behavior | v20 behavior |
+|---|---|---|
+| 2 — Prototyping | Informational validate, no halt on errors | Identical (already informational) |
+| 4 — Validate | Authoritative validate, 3-retry cap, hard stop on 3rd failure | **Identical** — CLI now accepts the v20 top-level shape. Authoritative validate, retry-and-fix, same 3-retry cap and hard stop on 3rd failure. |
+| 5 — Debug | `Run debug session` runs `uip maestro case debug` | Same prompt + behavior, BUT print plain-text warning BEFORE AskUserQuestion: `> v20 mode: uip maestro case debug may reject. Failure does not invalidate caseplan.json.` On failure, note `caveat: CLI may reject v20 schema — failure may be schema-related not case-bug-related` in build-issues.md. |
+| 6 — Publish | `Publish to Studio Web` runs `uip solution upload` | Same prompt + behavior, BUT print plain-text warning BEFORE AskUserQuestion: `> v20 mode: uip solution upload may reject top-level shape until CLI catches up. Failure non-fatal — caseplan.json still valid v20.` On failure, dump response to `tasks/upload-response.json`, re-show Phase 6 prompt. |
+
+Skill stays emit-honest in v20 mode: JSON-shape correctness is the skill's job, downstream CLI accept-correctness is outside scope (Rule 18).
+
+## Why phased
+
+After `tasks.md` is approved, skill does **not** build full case in one pass. It builds **placeholder** first (Phase 2 Prototyping) — enough structure for user to review case graph visually in Studio Web — then hard-stops for approval before wiring detail (Phase 3 Implementation). Validate (Phase 4), Debug (Phase 5), and Publish (Phase 6) each follow as separate gated phases. Debug runs before Publish so the user only publishes a build they've verified end-to-end.
+
+Each hard stop gives user review checkpoint before agent commits to costly downstream work.
+
+## Phase summary
+
+| Phase | What gets built | Output | Hard stop on exit |
+|---|---|---|---|
+| **2 — Prototyping** | Solution + project, root case, global variables, stages, edges, triggers (full), tasks (name + type, no value binding), placeholder tasks for unresolved | `caseplan.json` emitted; placeholder-profile validate run (structural errors only) | `Publish for review` / `Skip publish and continue` / `Abort` |
+| **3 — Implementation** | Connector task schemas, task I/O value binding, conditions (all 4 scopes), SLA + escalation | `caseplan.json` ready for authoritative validation | None — proceeds to Phase 4 |
+| **4 — Validate** | Run authoritative `uip maestro case validate`, dump `build-issues.md` | `caseplan.json` passes full validation | On 3rd validate failure: `Retry with fix` / `Pause for manual edit` / `Abort` |
+| **5 — Debug** | Optional CLI debug run (real execution — emails, API calls, etc.) | Debug output streamed | `Run debug session` / `Skip to Publish` |
+| **6 — Publish** | Optional Studio Web upload | `DesignerUrl` printed | `Publish to Studio Web` / `Done` |
+
+## Phase 2 — Prototyping
+
+### Structural nodes (full detail)
+
+- Solution + project scaffolding (`uip solution init`, `uip solution project add`, plus JSON scaffolding from `plugins/case/impl-json.md`).
+- Root case — `caseplan.json` with `root` block populated (name, caseIdentifier, empty `nodes[]`, empty `edges[]`, empty `caseExitConditions[]`).
+- Global variables and arguments — variables block (`inputs`, `outputs`, `inputOutputs`) fully declared. Path is schema-dependent: `root.data.uipath.variables` in v19, top-level `variables` in v20 (Rule 18).
+- Stages — all StageIds generated and captured.
+- Edges — all edges written; sources and targets resolve.
+- Triggers — fully built. Trigger output mappings written (they reference global variables, which already exist).
+
+### Tasks (shape depends on resolution state + task class)
+
+| Task class | Resolved resources | Phase 2 shape |
+|---|---|---|
+| Non-connector (`process`, `agent`, `rpa`, `action`, `api-workflow`, `case-management`, `wait-for-timer`) | `task-type-id` resolved | Full `data.inputs[]` schema written (from `uip maestro case tasks describe`). Each input's `value` field is empty (`""`). Outputs and task-specific scalar fields (e.g. `action`'s `taskTitle`/`priority`/`recipient`/`labels`) populated per plugin — these are final at Step 2; only input `value`s defer to Phase 3. |
+| Connector (`connector-activity`, `connector-trigger`) | `type-id` + `connection-id` resolved | `data.typeId` + `data.connectionId` set. `data.inputs` omitted or empty. **No `case spec` call in Phase 2** — schema discovery is deferred to Phase 3. |
+| Any task | Unresolved (`<UNRESOLVED: …>` in `tasks.md`) | Placeholder task per Rule 8 of `SKILL.md` — empty `data: {}` (plus `data.taskTitle` / `data.priority` / `data.recipient` for `action`). Marker preserved. See [placeholder-tasks.md](placeholder-tasks.md). |
+
+### What does NOT get written in Phase 2
+
+- Task input `value` bindings (literals, expressions, cross-task references).
+- Connector task input/output schemas.
+- Conditions of any scope (stage-entry, stage-exit, task-entry, case-exit).
+- SLA rules (default, conditional) and escalation rules.
+
+### Phase 2 informational validate
+
+End of Phase 2 mutations, run placeholder-profile validate:
+
+```bash
+uip maestro case validate "<caseplan.json path>" --skeleton --output json
+```
+
+`--skeleton` runs structural checks only (nodes, edges, identity, types, topology). Skips tasks, SLAs, escalations, and entry/exit rules — all unbound at this gate, filled in Phase 3.
+
+**Informational — do NOT halt on errors or warnings.** Capture error and warning counts (and optionally first few messages); include in hard-stop summary. Errors that remain are structural (dangling edge, missing trigger, duplicate names) and meaningful — user inspects via the existing `Abort` option before continuing.
+
+### Phase 2 hard stop
+
+**Unconditional.** Present summary, then prompt via AskUserQuestion. Prompt is MANDATORY on every run — auto mode, non-interactive mode, prior blanket approval do NOT bypass. Only valid transition out of Phase 2 is user response. If harness refuses interactive prompts, halt with explicit error rather than proceeding silently.
+
+#### Summary content
+
+Print before prompt:
+
+1. Counts: stages / primary stages / exception stages / edges / triggers / tasks total / placeholder tasks / unresolved resources.
+2. Validate result (placeholder-profile): `<N> errors, <M> warnings` — remaining errors are structural (dangling edge, missing trigger, duplicate names) and actionable. Surfacing counts is enough; do not dump full error list unless user asks.
+3. Paths: `caseplan.json`, `tasks.md`, `registry-resolved.json`.
+
+Do not enumerate every task. Studio Web visualization fills that role after publish.
+
+#### Prompt
+
+Use **AskUserQuestion** with three options:
+
+- `Publish for review` — upload skeleton to Studio Web for visual review.
+- `Skip publish and continue` — proceed directly to Phase 3.
+- `Abort` — stop the skill; leave artifacts in place.
+
+#### On `Publish for review`
+
+1. Run `uip solution resource refresh --solution-folder "<SolutionDir>" --output json` then `uip solution upload "<SolutionDir>" --output json`. Capture full upload response.
+2. Parse `DesignerUrl` from response.
+3. **MUST emit DesignerUrl as plain-text output to user BEFORE invoking AskUserQuestion**, on its own line:
+   `Skeleton published. Review at: <DesignerUrl>`
+   Never bundle URL only into question body — some renderers display question before surrounding prose, leaving user without URL until after they answer.
+4. Only after URL line emitted, invoke **AskUserQuestion** (second prompt): `Continue to phase 3` / `Abort`.
+
+If `DesignerUrl` missing from response, dump full upload response to `tasks/upload-response.json`, print path, continue to prompt — user can recover URL from file.
+
+Do not warn user about Studio Web edits being overwritten. Phase 6's re-publish (when chosen) overwrites volatile review-time edits with final local state. User can compare Studio Web state before and after Phase 3 to spot edits they want to preserve.
+
+#### On `Skip publish and continue`
+
+Proceed directly to Phase 3.
+
+#### On `Abort`
+
+1. Dump in-memory issue list to `tasks/build-issues.md` per [`plugins/logging/impl-json.md`](plugins/logging/impl-json.md).
+2. Print paths of `caseplan.json`, `tasks.md`, `registry-resolved.json`, and solution directory.
+3. Exit skill.
+
+Do **not** delete artifacts. User may want to inspect them, or re-run skill later (regenerates `tasks.md` from scratch per Rule 6).
+
+## Phase 3 — Implementation
+
+### Re-entry protocol
+
+Phase 3 begins after user selects `Continue to phase 3` (or `Skip publish and continue`). Before executing any Phase 3 step:
+
+1. **Re-read `tasks.md`** — per Rule 7. Declarative plan is the handoff.
+2. **Re-read `caseplan.json`** — authoritative source of all IDs generated in Phase 2:
+   - Stage name → StageId (from `schema.nodes[]` where `type === "case-management:Stage"` or `"case-management:ExceptionStage"`, keyed on `data.label`).
+   - Trigger ID (from `schema.nodes[]` where `type === "case-management:Trigger"`).
+   - Task name → TaskId per stage (from `schema.nodes[<stage>].data.tasks[][]`).
+   - Variable name → `var` ID (path schema-dependent: v19 from `root.data.uipath.variables.{inputs,outputs,inputOutputs}`; v20 from top-level `variables.{inputs,outputs,inputOutputs}`).
+3. Optionally cross-check against `id-map.json` if JSON-strategy plugins wrote one. `caseplan.json` is source of truth; `id-map.json` is speed-up.
+
+Never trust in-memory maps from Phase 2 without re-reading `caseplan.json` — context may be compacted across hard stop.
+
+### Phase 3 — Execution order
+
+After re-entry:
+
+1. **Connector task detail** — for each connector task in `tasks.md`, run plugin's `impl-json.md` detail steps: `case spec --type {activity,trigger} --input-details`, then mint `data.context[]` / `data.inputs[]` / `data.outputs[]` from the populated `caseShape` (placeholder substitution + var/id minting).
+2. **Task I/O value binding (all task classes)** — per [`plugins/variables/io-binding/impl-json.md`](plugins/variables/io-binding/impl-json.md). Applies to both non-connector and connector tasks. For each task's inputs in `tasks.md` order, write literal, expression, or cross-task reference (resolved to `=vars.<var>`) into `task.data.inputs[i].value`. Connector tasks have `data.inputs[]` schema written in step 1; value binding happens here in step 2, same as non-connector tasks.
+3. **Conditions** — per-scope plugin `impl-json.md`:
+   - Stage entry conditions
+   - Stage exit conditions
+   - Task entry conditions (depends on TaskIds from Phase 2)
+   - Case exit conditions
+4. **SLA + escalation** — per [`plugins/sla/impl-json.md`](plugins/sla/impl-json.md). Group `tasks.md §4.8` by target (root or stage); write full `slaRules[]` in one mutation per target.
+5. **End-of-Phase-3 validator pass** — per [`implementation.md § Step 12`](implementation.md). Run Checks 1-3 (=vars.X resolution, Q10 II Out-arg producer presence, type mismatch). AskUserQuestion for unresolved references and pure orphan Out-args; option (d) "continue with best-effort emit" preserves forward progress. Never HALT.
+
+Phase 3 produces a `caseplan.json` that should pass authoritative validation. No hard stop on Phase 3 exit — agent proceeds directly to Phase 4.
+
+## Phase 4 — Validate
+
+End of detail mutations. Run full-mode validate (omit `--skeleton`; defaults to full):
+
+```bash
+uip maestro case validate "<caseplan.json path>" --output json
+```
+
+On success: `{ Result: "Success", Code: "CaseValidate", Data: { File, Status: "Valid" } }` — proceed to Phase 4 dump step.
+
+On failure: output lists `[error]` and `[warning]` entries with path and message. Fix reported issues (usually via targeted re-run of earlier step) and re-run `validate`.
+
+### Retry policy
+
+> **v20 mode.** When `tasks.md` carries `Schema: v20`, Phase 4 follows the same retry policy as v19 below — the CLI now accepts the v20 top-level shape, so validate authoritatively, retry-and-fix on failure, and hard-stop on the 3rd failure.
+
+**Retry policy (both schemas).** Up to **3 validation retries** per session. After 3rd failure, halt and ask user with **AskUserQuestion**: show remaining errors and options:
+
+- `Retry with fix` — agent attempts fix, re-runs validate (counter does not reset).
+- `Pause for manual edit` — exit skill mid-flight; user edits `caseplan.json` directly and re-runs skill.
+- `Abort` — exit; dump `build-issues.md`; leave artifacts in place.
+
+### Dump issue log
+
+After successful validate, write issue list to `tasks/build-issues.md` per [`plugins/logging/impl-json.md`](plugins/logging/impl-json.md), grouped by plugin with summary index. Source of truth for completion report. Write even if zero issues logged (confirms clean build).
+
+On Phase 4 success → proceed to Phase 5.
+
+## Phase 5 — Debug
+
+After Phase 4 success, report results then ask user via **AskUserQuestion**:
+
+- `Run debug session` — run `uip solution resource refresh --solution-folder "<SolutionDir>" --output json` then `uip maestro case debug "<directory>/<solutionName>/<projectName>" --log-level debug --output json`. Streams results.
+- `Skip to Publish` — proceed to Phase 6 without debugging.
+
+> **Debug executes case for real — sends emails, posts messages, calls APIs, writes to databases. Only run when user explicitly asks. Never auto-run** (Rule 12).
+
+Requires `uip login`. Uploads to Studio Web, runs in Orchestrator, streams results.
+
+After debug completes, return to Phase 5 prompt so user can re-run or move on. Proceed to Phase 6 only on `Skip to Publish`.
+
+> **v20 mode.** When `tasks.md` carries `Schema: v20`, print this plain-text warning line BEFORE the AskUserQuestion:
+> ```
+> > v20 mode: uip maestro case debug may reject top-level shape until CLI catches up. Failure does not invalidate caseplan.json.
+> ```
+> On debug failure in v20 mode, append `caveat: CLI may reject v20 schema — failure may be schema-related not case-bug-related` to the troubleshoot context in `build-issues.md` so the user does not chase a bogus root cause.
+
+### Report fields (printed before prompt)
+
+1. File path of `caseplan.json`.
+2. What was built — summary of stages, edges, tasks, conditions, SLA.
+3. Validation status — `validate` pass / remaining warnings.
+4. Placeholder tasks + unresolved resources — list every placeholder (TaskId, type, display-name, stage) + external resource user must register (task-type-id / connection-id) + wiring-notes from `tasks.md`. See [placeholder-tasks.md](placeholder-tasks.md).
+5. Missing connections — connector tasks needing IS connections that don't exist yet.
+
+### Debug notes
+
+- `uip solution resource refresh` MUST run before debug — syncs resources from `bindings_v2.json` so Studio Web can resolve connector dependencies (Rule 14).
+- Debug verifies the build actually runs end-to-end before the user commits to a publish. If debug surfaces a fixable issue, see [Step 13a — Troubleshoot failed case](implementation.md#step-13a--troubleshoot-failed-case) and re-run.
+
+## Phase 6 — Publish
+
+After Phase 5 (whether debugged or skipped), prompt via **AskUserQuestion**:
+
+- `Publish to Studio Web` — run `uip solution resource refresh --solution-folder "<SolutionDir>" --output json` then `uip solution upload "<SolutionDir>" --output json`. Print returned `DesignerUrl` on its own line. Exit skill.
+- `Done` — exit skill without publishing.
+
+> **v20 mode.** When `tasks.md` carries `Schema: v20`, print this plain-text warning line BEFORE the AskUserQuestion:
+> ```
+> > v20 mode: uip solution upload may reject top-level shape until CLI catches up. Failure non-fatal — caseplan.json still valid v20.
+> ```
+> If `Publish to Studio Web` is picked and upload fails, dump full response to `tasks/upload-response.json`, print the path, then re-show this Phase 6 AskUserQuestion. Do not auto-exit on upload failure — let user decide whether to retry or `Done`.
+
+### Publish notes
+
+- `uip solution upload` accepts solution directory (folder containing `.uipx`) directly — no intermediate bundling step.
+- `uip solution resource refresh` MUST run before upload — syncs resources from `bindings_v2.json` so Studio Web can resolve connector dependencies (Rule 14).
+- Do **NOT** run `uip maestro case pack` + `uip solution publish` unless user explicitly asks for Orchestrator deployment. That path puts case directly into Orchestrator, bypassing Studio Web. Default is always Studio Web.
+
+For further authoring changes (add task, tweak condition, etc.), user updates `sdd.md` and re-runs skill from Phase 1 — skill does not offer in-place incremental edits.
+
+## Placeholder tasks — unchanged semantics
+
+Placeholder tasks (empty `data: {}` for unresolved resources) behave the same in all phases. Phase 2 creates them; Phase 3 does **not** upgrade them to typed tasks — upgrading requires user to register missing resource externally. See [placeholder-tasks.md](placeholder-tasks.md).
+
+Phase 3 still wires placeholder TaskIds into:
+- Task-entry conditions that reference the placeholder.
+- Stage-exit `selected-tasks-completed` rules that include the placeholder.
+
+It does **not** write `data.inputs` / `data.outputs` for placeholders. Input binding deferred to user's post-build upgrade pass.
+
+## Abort semantics
+
+Abort can occur at any hard stop:
+
+- Phase 2 first prompt (`Publish for review` / `Skip` / `Abort`).
+- Phase 2 second prompt (`Continue to phase 3` / `Abort`) after publishing.
+- Phase 4 retry-cap prompt (`Retry with fix` / `Pause for manual edit` / `Abort`).
+
+All follow same cleanup:
+
+1. Dump `build-issues.md`.
+2. Print paths.
+3. Exit.
+
+No artifact deletion. No rollback. User owns partial state.
+
+## Out of scope
+
+- **Re-ingesting Studio Web edits.** If user edits published placeholder in Studio Web during review, edits are not round-tripped back into local `caseplan.json`. Phase 3 writes on top of local state; Phase 6 re-publish overwrites Studio Web with completed local build.
+- **Resuming aborted session.** Re-running skill regenerates `tasks.md` from scratch (Rule 6) and re-executes Phase 2 onwards.

package/skills/uipath-maestro-case/references/placeholder-tasks.md

@@ -0,0 +1,195 @@
+# Placeholder Tasks Reference
+
+How the skill handles unresolved task resources — what a placeholder task is, when one is created, what it preserves, what it leaves out, and how the user upgrades it to a fully wired task later.
+
+## Why Placeholders Exist
+
+Registry pulls are often incomplete during early authoring:
+
+- The target tenant has not yet published the processes / agents / RPA / action-apps.
+- Custom Integration Service connectors have not been registered.
+- IS connections for registered connectors are not yet provisioned.
+
+If the skill halted on every unresolved resource, the generated `caseplan.json` would be a small fragment — not reviewable, not validatable, not useful. Placeholders solve that: the full **workflow structure** (stages, edges, conditions, SLA, ordering, task names + types) lands in `caseplan.json`, and only the parts that strictly require a registry lookup (task-type-id, connection-id, input/output schemas) are deferred.
+
+The user reviews structure first, then attaches real resources once they exist.
+
+## What a Placeholder Is (vs a Mock)
+
+| Field | Full task | Placeholder task | Mock (forbidden) |
+|-------|-----------|---------------|------------------|
+| `type` | ✓ | ✓ | ✓ |
+| `displayName` | ✓ | ✓ | ✓ |
+| `isRequired`, `shouldRunOnlyOnce` | ✓ | ✓ | ✓ |
+| `data.context.taskTypeId` (non-connector) / `data.typeId` (connector) | real ID | **key omitted** | fake ID |
+| `data.connectionId` (connector) | real UUID | **key omitted** | fake UUID |
+| `data.inputs[]` value JSON (connector) | real values | **omitted** | `{}` |
+| Input / output variable bindings | real JSON edits via `io-binding` plugin | **skipped entirely** (no `data.inputs[]` to edit) | edits targeting nonexistent input names |
+| Task-entry conditions | ✓ | ✓ | ✓ |
+| Referenced by stage-exit `selected-tasks-completed` | ✓ | ✓ | ✓ |
+
+**Mocks are forbidden** because Case's typed cross-task outputs reject references to non-existent output schemas at validation time. A fabricated task-type-id causes `uip maestro case validate` to emit errors about unknown bindings. A placeholder sidesteps this by having no bindings at all — clean validation, clear `<UNRESOLVED>` markers in `tasks.md`, explicit upgrade path.
+
+## When a Placeholder Is Created
+
+During **execution** (Phase 2, Step 9), for any `tasks.md` entry whose `taskTypeId`, `typeId`, or `connectionId` is `<UNRESOLVED: …>`:
+
+1. Skip the schema fetch (`uip maestro case spec` / `uip maestro case tasks describe`).
+2. Write the task JSON node with structural fields only — no `taskTypeId` / `connectionId` / `inputs` / `outputs` keys (see JSON Shape below).
+3. Skip the `io-binding` plugin entirely for that task (see [`plugins/variables/io-binding/impl-json.md`](plugins/variables/io-binding/impl-json.md) — placeholder tasks log a `SKIPPED` severity entry and move on, because there is no `data.inputs[]` schema to write into).
+4. Generate and capture the `TaskId` normally — task-entry conditions and stage-exit rules still reference it.
+
+## JSON Shape
+
+Placeholders occupy a `laneIndex` in `stageNode.data.tasks[laneIndex][]`, the same way full tasks do — default one task per lane for FE readability, lane is layout-only. **Exception:** when a placeholder participates in a `runs-sequentially` group and is meant to run in parallel with sibling tasks in that group, it shares the same `laneIndex` as those siblings (shared lane = parallel siblings inside the sequential group, semantic).
+
+A placeholder task in `caseplan.json.nodes[<stage>].data.tasks[<lane>][]`:
+
+```json
+{
+  "id": "t8GQTYo8O",
+  "elementId": "Stage_aB3kL9-t8GQTYo8O",
+  "displayName": "Validate Submission Completeness",
+  "isRequired": true,
+  "type": "process",
+  "data": {},
+  "entryConditions": [
+    {
+      "id": "Condition_xC1XyX",
+      "displayName": "After Fetch Submission",
+      "rules": [
+        [{ "rule": "selected-tasks-completed", "id": "Rule_jdBFrJ", "selectedTasksIds": ["…"] }]
+      ]
+    }
+  ]
+}
+```
+
+Note the empty `data: {}` — no `taskTypeId`, no folder path, no input/output wiring. The shape is uniform across classes: connector placeholders use `type` `connector-activity` / `connector-trigger`; action placeholders too — no exception for `data.taskTitle` or other action-specific keys.
+
+### In-stage timer
+
+Timers are a built-in type — they are never placeholders because they have no registry dependency. Use [`plugins/tasks/wait-for-timer/impl-json.md`](plugins/tasks/wait-for-timer/impl-json.md).
+
+### Case-level event triggers
+
+Case-level event triggers (`type: "case-management:Trigger"` with `serviceType: "Intsvc.EventTrigger"`) follow the same pattern but use a different shape — trigger nodes need `data.label` / `description` / `parentElement` to render at all, so the placeholder keeps those plus `data.uipath: { serviceType: "Intsvc.EventTrigger" }`. Full spec in [`plugins/triggers/event/impl-json.md` § Placeholder fallback](plugins/triggers/event/impl-json.md). Manual and timer triggers are never placeholders (no registry dependency).
+
+### Connector condition rules
+
+When a `wait-for-connector` rule's connector hasn't resolved at write-time, the rule is emitted without `uipath` — the rule itself is not a placeholder; only its connector configuration is deferred (same pattern as task `data:{}`). Full recipe + skip behavior + upgrade path: [connector-trigger-common.md § Placeholder fallback](connector-trigger-common.md#placeholder-fallback).
+
+## `tasks.md` Planning-Entry Shape
+
+A placeholder-bound entry keeps every structural field and moves the lost wiring into a fenced code block the user will act on later:
+
+````markdown
+## T20: Add process task "Validate Submission Completeness" to "Submission Review"
+- taskTypeId: <UNRESOLVED: process-index.json empty in tenant>
+- folder-path: <UNRESOLVED>
+- runOnlyOnce: false
+- isRequired: true
+- order: after T19
+- verify: Confirm Result: Success, capture TaskId (placeholder — user to attach process + bindings)
+```text
+wiring notes (user must attach after publishing the process):
+  lob = =metadata.lob
+  sourceDocs <- "Submission Review"."Fetch Submission from U Submit".submissionData
+  outputs expected: submissionComplete, missingItems, tier
+```
+````
+
+Rules:
+- **Omit `inputs:` and `outputs:` lines** — no schema to wire against.
+- **Capture the intended wiring in a fenced ```` ```text ```` code block** so the user sees the mapping when they upgrade. **Do not start wiring lines with `#`** — they would render as markdown H1 headings; the fenced code block renders as preformatted text.
+- **Keep every other field** — order, verify, is-required, run-only-once, display-name.
+
+## What Validation Catches
+
+`uip maestro case validate` on a caseplan with placeholders emits warnings, not errors:
+
+- `Stage "<name>" has a task with no configuration` — one per placeholder.
+- `Stage "<name>" has no tasks` — if every task in a stage is absent (not even a placeholder).
+
+These are **expected** and do not block the build. Errors only appear when cross-task bindings reference non-existent outputs — which is exactly why the skill forbids mocks.
+
+## Upgrade Procedure — Placeholder → Full Task
+
+When the user has registered the real resource:
+
+### 1. Re-pull the registry
+
+**Confirm with the user via the `AskUserQuestion` tool before running** — force pull bypasses the cache, is network-heavy, and may be slow.
+
+```bash
+uip maestro case registry pull --force
+```
+
+### 2. Resolve the task-type-id
+
+Read the relevant cache file directly per [registry-discovery.md](registry-discovery.md) — e.g., `process-index.json` for processes, `action-apps-index.json` for action apps.
+
+### 3. Fetch the schema
+
+For non-connector tasks, run `uip maestro case tasks describe --type <type> --id <entityKey> --output json` to get the per-resource input/output schema. For connector tasks, run `uip maestro case registry get-connection` to obtain the `connectionId`, then `uip maestro case spec --type <activity|trigger> --activity-type-id <typeId> --connection-id <connId>` to get the unified spec output (identity, connection, inputs, outputs, filter, references, and a populated `caseShape` when `--input-details` is supplied).
+
+### 4. Edit the placeholder in place
+
+Read `caseplan.json`, locate the placeholder task by `id`, and mutate its `data` field in place. Keep the task's `id` and `elementId` unchanged — any conditions or `selected-tasks-completed` rules referencing the TaskId stay valid.
+
+| Task class | `data` mutation |
+|---|---|
+| `process`, `agent`, `rpa`, `api-workflow`, `case-management` | Set `data.name`, `data.folderPath`, `data.context.taskTypeId = <entityKey>`. Write `data.inputs[]` / `data.outputs[]` from the `tasks describe` schema (each input `value: ""` to start). |
+| `action` | Set `data.context.taskTypeId = <actionAppId>`, `data.taskTitle`, `data.priority`, `data.recipient` (if known). Write `data.inputs[]` / `data.outputs[]` from the schema. |
+| `connector-activity`, `connector-trigger` | Set `data.typeId`, `data.connectionId`. Write `data.inputs[]` / `data.outputs[]` from the `is describe` schema. |
+
+Per-class JSON shape lives in `plugins/tasks/<type>/impl-json.md` — match those exactly.
+
+> **Tip:** If the user has many placeholders to upgrade, a cleaner workflow is to update `sdd.md` with whatever context was missing (e.g., the now-registered process name) and re-invoke the skill from Phase 1. The regeneration path preserves the declarative intent.
+
+### 5. Bind inputs and outputs
+
+Wire each input per the `io-binding` plugin — see [`plugins/variables/io-binding/impl-json.md`](plugins/variables/io-binding/impl-json.md). In short:
+
+1. Read `caseplan.json`; locate the task's `data.inputs[]` by input `name`.
+2. For literals/expressions from the `wiring notes` code block (`foo = =metadata.x`) — write the RHS string to `input.value`.
+3. For cross-task references (`foo <- "Stage"."Task".output`) — resolve the source task's output `var` from `caseplan.json`, then write `=vars.<var>` to the target input's `value`.
+4. Write `caseplan.json` back.
+
+### 6. Re-validate
+
+```bash
+uip maestro case validate <file> --output json
+```
+
+The "task with no configuration" warning disappears once `data` is populated.
+
+## Completion-Report Shape
+
+When the build finishes with placeholders, the skill's completion report must list them explicitly:
+
+```
+### Placeholder tasks (N)
+
+| Stage | Task | Type | TaskId | Attach |
+|-------|------|------|--------|--------|
+| Submission Review | Validate Submission Completeness | process | t8GQTYo8O | process-index.json — "Validate Submission Completeness" |
+| Submission Review | Review Submission | action | ty5UcykfU | action-apps-index.json — "Review Submission" |
+| … | … | … | … | … |
+
+### External resources to register before upgrading placeholders
+
+- **Processes** (N): Validate Submission Completeness, Route Submission Decision, Finalize Case Closure
+- **Agents** (N): Classify Documents, Generate Carrier Emails, …
+- **Action Apps** (N): Review Submission, Schedule Huddle Meeting, …
+- **Custom IS connectors** (N): U Submit (GetSubmission), U Place (SubmitPlannedMarkets), …
+```
+
+The user uses this list to drive external resource creation, then runs the upgrade procedure.
+
+## Anti-Patterns
+
+- **Do NOT fabricate a task-type-id to silence the warning.** Validation will pass but runtime will fail with binding errors.
+- **Do NOT partially bind inputs on a placeholder.** A placeholder has no `data.inputs[]` to edit — the io-binding plugin logs a `SKIPPED` entry and moves on. Half-bound placeholders are harder to upgrade than bare ones.
+- **Do NOT skip task-entry conditions on placeholders.** Conditions are structural; they work on the TaskId and must be created so the workflow order is visible in review.
+- **Do NOT create placeholders for timer tasks.** Timers have no registry dependency — use the full `wait-for-timer` plugin.