test(bpmn): port the live-tier and field-shape Maestro Flow evals to the BPMN suite

tests/tasks/uipath-maestro-bpmn/_porting/LIVE-ADDENDUM.md

@@ -0,0 +1,39 @@
+# Live-tier addendum — ports whose Flow grader runs `flow debug`
+
+Read `PORTING-BRIEF.md` (Grading contract is mandatory) and `BATCH1-ADDENDUM.md` first. This file adds the rules for ports whose Flow criteria execute the artifact. Everything here is a **T** translation of Flow's `flow_check.run_debug` + output assertions; it is not licence to add assertions Flow does not make.
+
+## The canonical live pattern (copy it)
+
+`_shared/check_jira_get_issue.py` is the canonical live BPMN grader. Its sequence, all via `_shared/bpmn_live.py`:
+
+1-2. `import_exact(bpmn_path, project_dir, LIVE_RUN_DIR / <Name>)`: ephemeral `uip solution init` under the sandbox CWD (so the standard post_run sweep finds the `.uipx`) + `uip solution projects import`, asserting the imported `.bpmn` bytes equal the submitted ones.
+3. `debug_data, instance_id = run_debug(imported_project_dir, inputs, log_file, timeout=…)` — `bpmn debug` returns an instance id, not inline variables. `--inputs` JSON is honoured (the escalation run seeded correlationId this way and found it in Jira).
+4. `fetch_variables(id)` (`debug-instance variables-all`) → `root_scope(variables_data)` for root variables; `element_output_records(variables_data, element_id)` for a node's `Outputs`; `connector_response_values(outputs, name)` for connector response fields.
+5. Side-effect ids go to a flat journal the moment they are visible, before any status check; post_run replays it (teardown) — mirror the Flow task's `_setup/teardown_*.py`.
+6. `fetch_incidents(id)` then `require_clean_run(debug_data, evidence)`; a completed run with incidents is a failure. `debug_evidence(id)` does 4 and 6 together for a grader with no side effects.
+
+Known runtime facts (grade around them, do not fight them):
+- Element-level `Outputs` (a script task's mapped output, a connector's `response`) are reliably readable in `variables-all`. Root **public output values** have been read back as `null` even when correctly mapped (see `debug/live_debug_e2e/check_live_debug.py` docstring). So when Flow asserted "some output equals X" (`assert_output_value` / `assert_outputs_contain` over `variables.globals` + element outputs), translate to: read the declared output first, and only when it reads back null search `output_leaves(variables, skip=input_echo_ids(process))`, narrowed with `elements=` to the nodes that produce the value when the task names them.
+- Variables are addressed by **id**, and the runtime may re-case ids — use `resolve_runtime_key`.
+- Debug instances are ephemeral; read variables-all immediately after the run.
+
+## Budgets (the test suite enforces this)
+
+`_shared/test_criterion_budgets.py` statically prices every `run_debug(...)` call in a grader and requires the calling criterion's `timeout:` ≥ `debug_budget(timeout, retries, backoff) + bpmn_live.CRITERION_MARGIN_SECONDS` (plus the other CLI steps you run — the escalation grader sums `STEP_TIMEOUTS` and its unit test pins the YAML timeout to that sum). Keep Flow's criterion `timeout:` if it fits; if the BPMN sequence (solution init + import + debug + variables-all + incidents) needs more, raise ONLY that criterion's `timeout` and say so in the description — this is the one sanctioned deviation from "criteria identical", because the budget is a property of the CLI surface, not of what is graded. `run_limits.task_timeout` must cover the agent's turn budget plus all grading, as the escalation YAML documents.
+
+## Fixtures, seeds, teardown, cleanup
+
+- Copy the Flow task's `_setup/` scripts (seed, teardown, `jira_is.py`-style helpers) into the BPMN task's own `_setup/` and mount them the same way; change only what is suite-specific (none of the `uip is` plumbing is). Keep tenant targets (connection names, folder `Shared/uipath-maestro-flow`, project keys, channel ids) verbatim — they are shared tenant fixtures, not Flow vocabulary.
+- post_run: `python3 _setup/cleanup_solutions.py` (mounted from `tests/tasks/uipath-maestro-bpmn/_setup/`) first, then the task's teardown, with Flow's timeouts or larger if the BPMN sweep has more to delete.
+- Prompts keep Flow's wording about running ("Validate the flow" stays validate; if Flow's prompt told the agent to debug/run, keep that instruction with the `bpmn debug` verb). Live ports do NOT get the structural "Do NOT upload/debug/run" closing line — the grader itself runs the process, and the Flow prompt's own scope stands.
+
+## Assertion map tags for live ports
+
+Add these T rows as needed and cite the Flow helper you translate:
+- `T flow_check.run_debug(inputs=…)` → ephemeral solution + `bpmn_live.run_debug(project, inputs, log)`
+- `T assert_output_value / assert_outputs_contain / assert_named_equals` → value-leaf search over `variables-all` root scope + element `Outputs` (declared inputs excluded, as Flow excluded them)
+- `T assert_node_type_executed / completed_node_ids_of_type` → the element's record in `variables-all` (or `debug_data.ElementExecutions[].Status == Completed`)
+- `T assert_slack_message_posted / assert_connector_send_identity` → `connector_response_values` on the connector element's outputs, then the same tenant re-read Flow did
+- `T assert_connector_error_handlers` → boundary error event / error path presence — only if Flow asserted it
+
+If a Flow assertion has no readable runtime evidence on the BPMN side (e.g. a root-output-only value that the runtime returns as null and no element output carries it), STOP and report "parked: <evidence>" rather than loosening the assertion.

tests/tasks/uipath-maestro-bpmn/_porting/LIVE-HANDOFF.md

@@ -0,0 +1,35 @@
+# Flow → BPMN eval porting: live tier
+
+Methodology is in `PORTING-BRIEF.md`, `BATCH1-ADDENDUM.md`, `NORMALIZATION.md` and `LIVE-ADDENDUM.md` beside this file; per-task history and run ids in `parity-ledger.md`. Ports that never went green live on `test/bpmn-port-parked`, each `skip: true` with its evidence.
+
+## Rules
+
+1. Every grader assertion is tagged F (Flow translation), I (plumbing) or T (listed tolerance) in its module docstring.
+2. Criteria keep Flow's type, order, weight and threshold. Sanctioned deviations: CLI verbs, grader implementation, live criterion timeouts sized to the BPMN CLI sequence, and `task_timeout` = turn_timeout + every criterion and pre_run timeout + 60.
+3. Dispatch: `gh workflow run run-coder-eval.yml --ref <branch> -f task_globs='…'`, codex driver, alpha tenant. Read results with `gh run download <id>` → `**/task.json`; agent artifacts under `**/00/artifacts/` feed grader regression replays.
+4. Fix only port defects; three graded iterations at most; a repeat runtime or skill failure parks the task with evidence. Never weaken a Flow assertion.
+
+## Live-grader recipe
+
+Canonical: `_shared/check_jira_get_issue.py`. From `_shared/bpmn_live.py`: `import_exact` (ephemeral `uip solution init` + `projects import`, sha256-pinned) → `run_debug(project, inputs, log, timeout)` in the grader itself, so `test_criterion_budgets.py` can price it → `debug_evidence` (`variables-all`, `incidents`) → `require_clean_run`. Read a declared output first; when it reads back null (root public outputs have), fall back to `output_leaves(variables, skip=input_echo_ids(process), elements=…)` over the nodes that produce it. An unskipped input reads as an output. A grader with side effects journals their ids before `require_clean_run`, so a faulted run still cleans up.
+
+post_run `_setup/cleanup_solutions.py` sweeps the ephemeral solution; a later criterion in the same task passes `resolve_project(exclude_under=[LIVE_RUN_DIR])` so that import is not read as a second project.
+
+Budget: the guard enforces criterion `timeout` ≥ `debug_budget(...)` + 60. Size it to cover the whole sequence: 90 (init) + 180 (import) + `debug_budget(...)` + 120 (variables-all) + 120 (incidents) + 60, e.g. 1050 for one default debug.
+
+## Runtime and grader facts
+
+- `uip maestro bpmn debug` polls at most 300 times; `run_debug` sizes `--poll-interval` to 80% of its budget and raises `CheckFailure` on timeout after writing the CLI output to its log file.
+- Incident 102010 "Parameter 'Folder' null" on a Slack node = missing `folderKey` binding; 102009 = missing activity parameter; 400008 on a multi-instance marker = input collection over a connector response.
+- Connector nodes come in two forms: curated `objectName` with path/query inputs, or generic entity-CRUD with the verb in `operation`/`method`. A request body is one JSON `target="body"` input; several do not merge at runtime, and `bpmn_check.body_object` raises `BodyShapeError` on them.
+- Managed HTTP is `Intsvc.HttpExecution` or `Intsvc.UnifiedHttpRequest`; connector-mode HTTP is `Intsvc.ActivityExecution`. Wait-for-event may be a `receiveTask` or an `intermediateCatchEvent`; classify by the `uipath:type` wrapper, never the BPMN tag.
+- `find_bpmn_file` treats byte-identical copies as one artifact and fails on any other ambiguity; `validate_bpmn.py` validates every `.bpmn` in the sandbox.
+- Actions.HITL needs a deployed Action App to pass `bpmn validate`; the curated Data Fabric query template has no sort-field parameter.
+
+## Skill findings to report upstream
+
+Slack channel-id resolution and pagination (three tasks); Slack `folderKey` binding omitted; connector trigger parameters (Data Fabric entity, Outlook `parentFolderId`) omitted and `uip is triggers` discovery not taught; managed-HTTP response shape unclear to downstream scripts; Data Service where-clause grammar from variables; multi-instance over connector output; fixed literal values parametrised into unbound variables; no "existing solutions → ask" greenfield rule; WooCommerce connector node not produced.
+
+## Not yet ported
+
+billing_dispute_analyst / _resolution / _writer need a published agent to stand in for Flow's inline agents; single_node/file_attachment needs a file-typed process variable. Undecided: generate_schema (opaque `jsonSchema` output contract) and dtl_load_by_default ×2 (design-time metadata, not wire XML).