trxa-tool 0.0.0-stage → 0.2.0

package/.claude/skills/replay-trxa-testplan/SKILL.md

@@ -0,0 +1,627 @@
+---
+name: replay-trxa-testplan
+description: Replay a D365 Finance & Operations Task Recorder test script (testscript.json, produced by TRXA-TOOL from a .axtr file) against a live/sandbox environment via the d365-erp-mcp form tools. Resolves low-confidence step hints at runtime, saves edits, handles confirmation/async-processing dialogs, and reports pass/fail from what actually happened in the session rather than from the recording. Use when the user asks to "replay a task recording", "run this test script", "dry-run this axtr file", "run this test suite/plan", or "test this business process against D365".
+---
+
+# Replay an axtr Test Script against D365FO
+
+## Input
+
+A Test Script (`testscript.json`) produced by `trxa-tool`
+(`trxa parse <file.axtr> -o testscript.json`). If the user only has a raw `.axtr` file, run
+that first. Each entry in `steps[]` has: `sequence`, `description` (human text from the
+recording), `formName`, `nodeType`, the full recorded `node`, and a `hint` (`tool`, `confidence`,
+`params`, optional `note` and `followUp`) generated from the tool's own recording-to-MCP-call
+mapping logic.
+
+This skill folds in everything learned from live replays about the gaps between what a recording
+captures and what the MCP tools actually need, so it is self-contained. For the Test Case, Fixture,
+Suite and Plan file formats, `MANUAL.md` ships inside the installed package (with `README.md` and
+`STUDIO.md`): locate the install (`npm root -g` for a global install, `npm root` for a local
+one) and look under `trxa-tool/`.
+
+### A note on where this skill runs
+
+Every command below is written as `trxa <command> ...`, assuming a real install (`npm install
+-g trxa-tool` or equivalent) where that's the correct, always-available invocation. If instead
+you're working inside a clone of the tool's own source repo without having run `npm link`, use
+`node dist/index.js <command> ...` in its place (see that repo's own `DEVELOPING.md`). `src/`,
+`test/` and the design notes in `ARCHITECTURE.md` are source-checkout-only, never shipped in the
+installed package — don't go looking for them unless you know you're in a source checkout.
+
+## Before executing anything
+
+1. **Confirm the target environment and scope with the user.** A test script can contain
+   irreversible actions (posting, invoicing, deleting). Ask how far to run — e.g. "navigation
+   only" vs "full run including posting" — before starting, the same way you would for any
+   hard-to-reverse action. Never assume a connected `d365-erp-mcp` session points at a safe
+   sandbox; check the company/session info from the first tool response and say what you see.
+2. **Security preflight (optional but cheap).** If the Test Script's
+   `security.requiredPrivileges` is present, check it against the target user's access via
+   `get_security_coverage_for_object` / the `security-hierarchy-trace` skill, so a permissions
+   error doesn't get misreported as a business-logic failure.
+3. **`trxa-tool`'s own tooling is read-only while replaying — never edit it to work around an
+   error you hit mid-run**, whether that means source (`src/`, only present if you have the tool's
+   own repo checkout) or the installed package's own compiled `dist/`. A CLI command failing is one
+   of two things, and they call for opposite responses: (a) a mismatch between your shell and how
+   you quoted the command (see the PowerShell note under `record-result`, step 4 of "Running as
+   part of a Test Suite" below, for a documented example) — fix your own invocation, not the tool;
+   or (b) an actual bug in the tool. For (b), stop and report it to the user with what you saw
+   instead of patching it yourself — whether/how to fix the tool mid-test-run isn't a call to make
+   unilaterally while real D365FO data may be involved, and if you're running from an installed
+   package there's usually no source to fix anyway (see "Reporting" below for what to do with a
+   mapping-gap finding in that case). If you do have a source checkout, `mapping.ts` is the one
+   deliberate exception, and only as an explicit, separate follow-up once a run is done — not a
+   reflex during the run itself. Rebuilding (`npm run build`) to pick up a source change someone
+   else already made is fine; writing the change is not yours to do here.
+
+## Executing each step, in `sequence` order
+
+1. **`hint.tool === "skip"`**: don't call any MCP tool — `"skip"` isn't a real `d365-erp-mcp`
+   tool, it's `mapping.ts`'s way of saying this step's `SystemGenerated=true` in the recording
+   (an automatic side effect, like a form part lazy-loading — not something the user did). Move
+   to the next step; note it in the final report as "no action needed" rather than a pass/fail.
+2. **High confidence hints** (any other `tool`): call `hint.tool` with `hint.params` directly.
+   Date-typed `PropertyUserAction` values are already reformatted from the recording's ISO
+   (`yyyy-MM-dd`) into `M/d/yyyy` by `mapping.ts` -- confirmed live that some Date controls reject
+   ISO outright ("Dates must be in the format M/d/yyyy") even though the recording always captures
+   ISO, so this is handled for you; no extra reformatting needed on your end.
+3. **Medium/low confidence hints**: do not guess blindly.
+   - For grid row selection (`form_select_grid_row`/`form_filter_grid` hints with `confidence:
+     "low"`): the recording only captured a row *position*, which doesn't carry across
+     environments or data. Derive the real target from the step's `description` and neighboring
+     steps (e.g. a customer/item/order mentioned nearby), or ask the user which record to use —
+     exactly as was done in the reference dry run when a recording said "find and select the
+     desired record" with no captured business key. Then: `form_filter_grid` (if there's a
+     usable filter value) → read the returned grid rows → `form_select_grid_row` with the
+     resolved `rowNumber` and the `marking` value the grid's own response guidance asks for
+     (check `FormState...Grid.Guidance` — most grids require `"Marked"` or `"Unmarked"`
+     explicitly).
+   - For tree navigation (`form_click_control` hints on a `Tree`-typed control, `confidence:
+     "medium"`, e.g. a category picker): same non-portability problem as grid rows, but the
+     resolution mechanics are different. `hint.params` only has `controlName` — the actual click
+     needs an `actionId` you read off the *live* tree, not the recording. Call
+     `form_click_control` with just `controlName` (no `actionId`) or inspect the current
+     `FormState.Tree[name].Nodes` first; each node has `Actions.Select`/`Actions.Expand`
+     formatted `"Select:<n>"`/`"Expand:<n>"` where `<n>` is a live-session index. Walk the tree
+     matching each node's `Text` against the business value you need (expanding parent nodes with
+     their `Expand:<n>` action first if the target isn't visible yet), then click with that
+     node's own `Select:<n>`.
+   - For the filter/sort command family (`GetFilters`, `ApplyFilterForTaskRecorder`,
+     `ApplyFiltersForTaskRecorder`, `SetSortsForTaskRecorder`, `ApplyFilters`): `mapping.ts` now
+     computes `gridColumnName` (as `DataSourceName_FieldName`) and `sortDirection`/
+     `gridColumnValue` directly from the step's embedded JSON, at medium confidence. The one
+     piece still missing is `gridName` — it's never recorded on these steps and isn't always
+     `"Grid"` (standard lookup popups commonly expose one grid literally named `"Grid"`, but
+     list-page forms don't) — identify it from the current `FormState`'s `Grid` section before
+     calling `form_filter_grid`/`form_sort_grid_column`. `GetFilters` itself maps to `skip`
+     (confirmed read-only in every occurrence across the library).
+   - For any other low-confidence hint: call `form_find_controls`/`form_find_menu_item` with the
+     recorded `ControlName`/`MenuItemName` as the search term first, and act on what comes back.
+   - **Grid row selection immediately after creating a new record may already be selected.**
+     Confirmed live on a general journal entry: the recording captured `MarkActiveRow` right
+     after clicking New, but the newly created row was already active — a lookup opened on the
+     header's Name field worked immediately, with no `form_select_grid_row` call needed first.
+     Before spending a call resolving a `MarkActiveRow` hint, check whether the action you're
+     about to take even needs an explicit selection.
+   - **A lookup's `form_select_grid_row` call can submit and close the lookup by itself.**
+     Confirmed on the same journal's Name-field lookup: calling it with `marking: "Marked"`
+     closed the popup and applied the value directly — the recording's separate "click the link
+     in the selected row" step (a second `NavigationAction`) wasn't needed, even though the
+     lookup's own `Guidance` text says to click the first column afterward. Check `FormState`
+     after marking before assuming the extra click is required.
+   - **A lookup selection can cascade defaults into other fields.** Selecting `GenJrn` as the
+     journal Name auto-filled the header's Description field ("General Journal") — not every
+     `PropertyUserAction` the recording captured is still necessary; check `FormState` after each
+     lookup selection for fields it already populated before setting them again.
+   - **`SegmentedEntry` controls (ledger account/dimension combinations, e.g.
+     `LedgerJournalTrans_AccountNum`) are not lookups** — `form_open_lookup` fails with "Control
+     is not a lookup control". Use `form_set_control_values` directly; a bare main account number
+     is enough (D365FO fills in default financial dimension segments itself, confirmed live:
+     `"110110"` resolved to `"110110--"` and looked up the account name), so there's no need to
+     reproduce the recording's full dimension string. If the recorded literal account doesn't
+     exist in the target environment, query a valid one first (e.g. `data_find_entities` against
+     `MainAccountLegalEntities` filtered to the target `LegalEntityId` and
+     `DoNotAllowManualEntry eq 'No'`) rather than guessing.
+   - **`SegmentedEntry` values can cascade defaults too, not just lookup selections.** Confirmed
+     on a fixed asset acquisition journal: setting `LedgerJournalTrans_AccountNum` to a fixed
+     asset number auto-populated the account name, the depreciation book, and the offset account
+     from that asset's configured Fixed Asset Posting Profile — none of those needed a separate
+     `form_set_control_values` call the recording implied.
+   - **A recorded lookup step immediately followed by a close, with no row selection in between,
+     usually means the user typed the value manually instead of picking one.** If a
+     `RequestPopup` step is directly followed by `RequestClose` (no `NavigationAction`/grid
+     selection between them), skip both and go straight to the next `PropertyUserAction`'s
+     `form_set_control_values` call rather than opening the lookup at all.
+   - **Not every journal type's "Validate" click triggers the async `SysOperationSandboxForm`
+     pattern.** Confirmed on a fixed asset journal: `Validate` returned the updated `FormState`
+     synchronously with no polling needed, unlike the general journal scenario above where it did.
+     Don't assume polling is required after every validate/post-type click — check whether the
+     response is already a normal `FormState` or a `SysOperationSandboxForm` first.
+   - **Posting can insert lines you never entered.** Confirmed on the same fixed asset scenario:
+     posting a single acquisition line auto-generated a second, system-inserted "Depreciation
+     adjustment" voucher line (a catch-up entry for depreciation missed between the asset's
+     configured service date and the acquisition date) that wasn't part of the recording or
+     anything set during replay. After posting, re-read the grid rather than assuming it still
+     matches only what was entered — extra system-generated lines are a real outcome to report,
+     not a bug in the replay.
+   - **An Action Pane tab click the recording captured may be skippable if the button is already
+     reachable without it.** Confirmed on a purchase order confirmation: the recording clicked the
+     "Purchase" tab before "Confirmation", but `buttonUpdatePurchaseOrder` ("Confirmation") was
+     already clickable directly from the list page's top-level `Button` set with no tab switch —
+     check the current `FormState`'s `Button`/`MenuButton` sections for the target control before
+     replaying an `AppBarTab` click that precedes it.
+   - **Async job duration varies a lot by operation — don't assume a fixed number of polls, but do
+     cap it.** Journal posting resolved in 2-4 `__TimerForAsyncTaskPolling` calls; the same pattern
+     on a purchase order confirmation (which also generates a printed confirmation document) took
+     8. Keep polling until the form changes away from `SysOperationSandboxForm`, up to a hard cap of
+     **20 polls** for a single async operation. If still on `SysOperationSandboxForm` after 20,
+     stop — treat it as a genuine failure (record it as `failed`/`blocked` per the "Handling a
+     genuine failure mid-run" section below, with whatever `FormState`/`Messages` the last poll
+     returned as the `actual` evidence) rather than polling indefinitely.
+   - **When a recording's `ChangeSelectedIndexInCache`/`NavigationAction` grid-selection step gives
+     no usable filter value** (e.g. "find and select the desired record" with nothing else to go
+     on), query the underlying business data first (`data_find_entities` against the relevant
+     entity, filtered to the status/condition the scenario needs -- e.g. an unconfirmed purchase
+     order via `PurchaseOrderHeadersV2`'s `DocumentApprovalStatus`) to pick a real, valid target
+     before touching the UI grid at all, then select it directly by the row it appears at once the
+     list is open.
+   - **A menu item or button the recording expects may not exist in the target environment at
+     all.** Confirmed on a vendor invoice matching scenario: the recorded flow submitted the
+     invoice through a Workflow drop-dialog, but that environment's `VendEditInvoice` form had no
+     Workflow button in its `Button`/`MenuButton` set whatsoever -- completion was a direct
+     `OK`/"Post" click instead. Check what's actually available in the current `FormState` rather
+     than assuming every recorded control exists; a missing control isn't necessarily a mapping
+     failure, it can be a genuine environment/configuration difference.
+   - **Invoice/quantity/price matching status lives in `FormState` combobox and grid columns, not
+     just Messages.** Confirmed on the same scenario: clicking "Update match status"
+     (`UpdateMatchStatus`) flipped the header `MatchVariance` combobox from `"Not performed"` to
+     `"Passed"`, and each line already carried its own `QuantityMatch`/`PriceMatch` values
+     (`"Passed"`) from matching against the linked product receipt. For any matching-status
+     scenario, read these fields back to confirm the business outcome, the same way `Messages` is
+     read for other steps.
+   - **A product's dimension requirements (Site/Size/Color/...) can cascade defaults the same way
+     `SegmentedEntry` does, but through an ordinary combobox/lookup control, not a segmented one.**
+     Confirmed on an item requiring `Site` and `Size` as product dimensions: setting `Site` on a
+     line auto-populated the `Warehouse` and `Variant` defaults configured for that site, without a
+     separate `form_set_control_values` call for them. Check `FormState` after setting any
+     dimension-typed field for fields it already filled in, the same way you would after a
+     `SegmentedEntry` value or lookup selection.
+   - **A ribbon button that looks disabled/missing can have more than one cause — check the
+     specific one before treating it as a mapping gap.** `buttonUpdateInvoice`/`buttonJournalInvoice`
+     availability was inconsistent across replay sessions; in one case the real cause was an
+     intentional vendor-level "blocked for invoicing" setting (a genuine business-rule block, not a
+     recording/mapping issue) rather than a missing control or wrong `FormState` path. Before
+     concluding a button is unreachable due to a mapping problem, check the record's own
+     configuration (vendor/customer/item hold or block flags) as a possible cause, not just the
+     form's `Button`/`MenuButton` set.
+4. **Run any `hint.followUp` entries** after the main call — currently this only fires for
+   `form_set_control_values`, which requires a trailing `form_save_form` or the edit is lost.
+   `form_set_control_values`'s `setControlValues` also accepts multiple entries in one call
+   (confirmed live setting a line's Description and Credit amount together) — batch fields on the
+   same form together instead of one call per field when the recording has them as separate
+   consecutive `PropertyUserAction` steps.
+5. **Inspect the tool response, not the recording, for what actually happened.** Every
+   `d365-erp-mcp` form tool response includes `FormState` with a `Messages` array (`Info` /
+   `Warning` / `Error`) and sometimes a `Summary`/`Guidance`. This — not the recording's
+   `description` text — is the source of truth for whether a step succeeded. A recording never
+   carries an "expected outcome"; treat any `Error` message or an unexpected form appearing as a
+   failure worth surfacing in the report even if the click itself "succeeded".
+   - **`FormState.Company` can change as a side effect of any click, not just a recognized
+     "intercompany" jump button.** Confirmed live: clicking `ButtonInterCompanyPurchTable`/
+     `ButtonInterCompanySalesTable` returns the new company directly in `FormState.Company`, no
+     extra lookup needed — but treat this as a general rule, not special-cased to those two
+     buttons. Re-read `FormState.Company` after *any* click and trust it over assuming the company
+     stays fixed for the rest of a test case; `companyId` is only a parameter on the navigation
+     tools (`form_open_menu_item`/`form_find_menu_item`/`api_invoke_action`) — every other form
+     tool call has no `companyId` at all and simply inherits whatever company the currently open
+     form is in.
+6. **Handle forms the recording couldn't predict:**
+   - A `SysBoxForm` with `Summary: "A modal has appeared."` is a confirmation dialog — read its
+     `Label` text (it's real, runtime-only content) and click through if it matches the expected
+     flow.
+   - **A "Match found" duplicate-party dialog on a create-new-vendor/customer replay is expected
+     and by design, not a mapping problem or something needing fixture cleanup.** Suite authors
+     may deliberately reuse the same `Org_Name`/address fixture across runs (varying only the
+     account number, e.g. via an `autogenerated` binding) precisely because this pipeline's goal is
+     regression-testing the *process* — does creating a vendor still work end-to-end without error
+     — not generating unique, realistic data every time. Confirmed live: a fixture that always
+     supplies the same name surfaced a picker listing prior runs' own leftover records once the
+     environment already had some. Decline the match (don't select an existing party) to preserve
+     the test case's actual "create a new vendor" semantics — accepting it would silently turn a
+     create-scenario into an update against someone else's record — and continue normally. This
+     isn't a finding to flag or a fixture to "fix" on your own initiative; a suite that wanted
+     unique names every run would already bind `Org_Name` as `autogenerated` the same way it does
+     for the account number.
+   - A `SysOperationSandboxForm` with guidance to poll means an async job (commonly triggered by
+     posting actions) has started. Repeatedly call `form_click_control` on
+     `__TimerForAsyncTaskPolling` until the form changes away from
+     `SysOperationSandboxForm` — that response carries the final `Messages`, which is where a
+     genuine business failure (e.g. insufficient inventory) will show up. Confirmed on a general
+     journal post: the same pattern fires for **both** "Simulate posting" and the actual "Post"
+     click — a recording that captures a simulate step means the orchestrator polls twice, not
+     once. A clean post's `Messages` includes an explicit count, e.g. `"Number of vouchers posted
+     to the journal: 1"` — a good example of the kind of runtime-only success signal this skill's
+     "inspect the tool response" step above is about.
+   - **A tool call that times out client-side may still have succeeded server-side, silently
+     invalidating the whole session.** Confirmed live: a `form_click_control` call that opened a
+     vendor invoice edit dialog timed out; the next call failed with `"No form is available"`
+     (not just a stale-form error), and re-navigating from a menu item returned a brand-new
+     `SessionId`. Recovery is to re-navigate from a menu item rather than retrying the same call.
+     Separately, that first click *had* actually gone through server-side and left a genuinely
+     orphaned in-progress record: the next attempt to invoice the same purchase order surfaced a
+     "One or more invoices are in use" dialog listing it. Recover it (the dialog's own recovery
+     button) rather than abandoning it and creating a second orphan.
+   - **A Part-embedded button (e.g. `NewAddress` on a Vendor's Addresses tab) can fail immediately
+     after a fresh `New` + `form_save_form` on the parent record, even though the parent record now
+     genuinely exists.** Confirmed live on `VendTable`: clicking `NewAddress` right after creating
+     and saving a new vendor failed twice in a row with `"Must be called with Vendors table buffer
+     passed."` — not a real data problem, a stale/uninitialized table-buffer reference left over
+     from the New+Save sequence. Recovery is the same shape as the session-recovery case above but
+     a different root cause: re-navigate to the record via the list page (open the menu item,
+     filter/select the row, click the record link) rather than continuing to work off the
+     just-created form's own context — the button works normally once you're on a freshly-opened
+     record.
+
+## Reporting
+
+Produce a per-step table: `sequence`, `description`, tool actually called (may differ from the
+hint), params used, pass/fail, and any captured messages. Finish with a plain-language summary:
+what broke, and whether it was a mapping/tool logic problem (addressed below) or a genuine business
+process failure (report to the user as the actual test result — that's the point of this whole
+pipeline). If a hint's `params` shape turns out to be wrong against the live tool schema, **and you
+have access to the tool's own source repo** (`src/mapping.ts`, `test/normalize.test.ts` — a
+separate clone, not part of what an installed package ships), fix it there and add a regression
+test, the same way the `form_select_grid_row`/`form_filter_grid`/`form_set_control_values` param
+shapes were corrected after the first live run. **If you're running from an installed package with
+no source access**, you can't make that fix yourself — report the specific mapping gap (which
+tool, what params shape was expected vs. actually needed) to the user as part of your summary
+instead, so they can pass it upstream, rather than searching for a `src/` directory that isn't
+there and concluding the tool itself is broken.
+
+## Running as part of a Test Suite (tracked test cases, real data, sequencing)
+
+Everything above covers replaying one Test Script ad hoc. When a Test Case (`testcases/*.json`),
+Test Suite (`suites/*.json`), and Test Run exist, use this check-in loop instead — **and stay
+silent in chat while it runs.** Don't narrate per-step or per-test-case progress ("now running
+create-purchase-order…", "confirm-purchase-order passed…") — nobody is reading it mid-run, it burns
+chat tokens for no benefit, and it duplicates what's already being captured properly. The Test Run
+file (`outputs`, `assertionResults` with real `actual` evidence) is the durable, comprehensive
+record; chat only needs the one final summary in step 5 below (or, for a whole plan, the
+plan-level rollup). This holds through failures too — per "Handling a genuine failure mid-run"
+below, a failed/blocked entry gets recorded and the loop continues without pausing to tell the
+user about it; it isn't a reason to break silence either. It also holds for parallel-eligible
+batches ("Running parallel-eligible branches concurrently" below) — don't narrate spawning
+subagents or their individual progress either, just record each result as it comes back and
+keep going.
+
+1. `trxa resolve-next <suite.json> <testrun.json> --testcases-dir testcases --fixtures-dir testdata`
+   - `{"status":"blocked","blockedIds":[...]}` — a dependency failed, or (per the note below)
+     evaluated a downstream entry's `runIf` unreachable; `resolve-next` has already recorded each
+     of `blockedIds` as `"blocked"` itself (no `record-result` call needed from you) before
+     printing this. Just call `resolve-next` again — in a linear chain this surfaces one dependent
+     at a time, so repeat rather than stopping after the first one. Keep looping silently until
+     `resolve-next` itself reports `"complete"`, then move to the final summary (step 5).
+   - `{"status":"skipped","skippedIds":[...]}` — one or more pending, otherwise-runnable entries
+     declared a `runIf` (`suites/*.json`'s `TestSuiteEntry.runIf`) that evaluated false against an
+     upstream test case's captured output. Same handling as `blocked` above: `resolve-next` has
+     already recorded each id as `"skipped"` itself -- not a failure, just call `resolve-next`
+     again. A `dependsOn` on a skipped entry surfaces as `blocked` on the *next* call (a skipped
+     dependency can never satisfy "every dependency passed"), not as a further `skipped`.
+   - `{"status":"waiting"}` / `{"status":"complete"}` — nothing to do / suite finished. Skip to
+     step 5 for a final summary once complete.
+   - `{"status":"runnable","runnable":[{"testCaseId","testScriptPath","legalEntity","resolvedInputs","autogeneratedParams","outputs","expectations"}, ...]}`
+     — `runnable` is every entry that's currently pending, has every dependency passed, and (if it
+     has one) passes its `runIf`, not just one — a suite whose DAG has two or more entries that
+     share a satisfied dependency without depending on each other (e.g. two entries that both only
+     depend on a common upstream entry) surfaces all of them here at once. The command has already
+     marked every entry in `runnable` `"running"` before returning, atomically as a batch — either
+     all of them resolved cleanly and got marked, or (if resolving any one of them failed, e.g. a
+     missing `inputBindings` entry) none of them did, so a failed call is always safely retryable
+     without checking what partially landed.
+     - **`runnable.length === 1`** (by far the common case): proceed with steps 2-4 below directly,
+       exactly as if this were the only thing resolve-next could ever return.
+     - **`runnable.length > 1`**: see "Running parallel-eligible branches concurrently" below before
+       continuing — don't just work through the array one entry at a time with steps 2-4 in a
+       simple loop, that leaves real concurrency (and thus wall-clock time) on the table for exactly
+       the case this array shape exists to expose.
+   Each entry's `resolvedInputs` are already resolved concrete values (from a fixture or an
+   upstream test case's output) — **use them as-is, do not substitute your own guessed business
+   data.**
+   - `autogeneratedParams` (an array of `{name, description, example}`) is the one deliberate
+     exception to that rule: these are params whose suite binding is `{"kind": "autogenerated"}`
+     — no fixture or upstream output to pull from, by design. **Before replaying, invent a value
+     for each one yourself** using its `description`/`example` as guidance (this kind exists
+     specifically for values that just need to be unique per run, e.g. append a short
+     timestamp/random suffix to a recorded-example-shaped base value), then treat it exactly as if
+     it were part of `resolvedInputs` for every remaining step below — form input substitution
+     (step 2) and `{{paramName}}` expectation substitution (step 3) both need it, and the CLI has
+     no way to know what you generated, so you must carry it yourself.
+     - **A text field can silently truncate an over-length autogenerated value, with no error.**
+       Confirmed live on `PurchParmTable_Num` ("Product receipt"): a 22-char generated value was
+       silently cut to 21 chars on save, no `Messages` entry raised. Don't assume the value you
+       set is the value stored, especially for a generated value whose length you don't fully
+       control — after setting an autogenerated value, re-read the field back off `FormState`
+       (the same "inspect the tool response" discipline from the per-step procedure above) and
+       carry the *stored* value forward for any later step/expectation that references it, not
+       the one you originally generated.
+   - `legalEntity`, when present, is the company this entry's suite author intended the test case
+     to run in — pass it as `companyId` on the *first* navigation call of the replay in step 2
+     below (the `form_open_menu_item`/`form_find_menu_item`/`api_invoke_action` that opens the
+     test case's starting form) and omit it from every call after that. When `legalEntity` is
+     absent, don't pass `companyId` at all — the test case runs in whatever company the current
+     session/form is already in. This is a single fixed starting company, not a substitute for the
+     "Executing each step" section's `FormState.Company`-tracking rule above — a multi-company
+     round trip within one test case (e.g. an intercompany order pair) is still just one atomic
+     pass/fail unit, and any company change mid-flow is picked up live from `FormState.Company`
+     after the click that causes it, never declared up front.
+2. Replay `testScriptPath` using the existing per-step procedure above, but plug each step whose
+   `bindTo.controlName` matches a key in `resolvedInputs` (plus whatever you invented for
+   `autogeneratedParams`) with that resolved value instead of the recorded one. For any
+   `bindTo.kind: "grid-row-selector"` input, that resolved value **is** the business key to
+   filter/search the grid by (this is exactly the ambiguity flagged earlier in this skill — a
+   suite's `resolvedInputs` is what resolves it, so you should no longer need to guess from context
+   when a test case supplies one).
+3. After the step(s) each `expectations[]` entry references (`checkAfterStepSequence`), evaluate
+   it:
+   - `kind: "odata"` (preferred) — `filter`/`expectedValue` may contain `{{paramName}}`
+     placeholders referencing `resolvedInputs` from step 1 (or a value you invented for an
+     `autogeneratedParams` entry — same substitution, just from your own memory instead of the
+     CLI's JSON) (e.g. `SalesOrder eq '{{salesOrderId}}'`); substitute those first, then call
+     `data_find_entities` on
+     `entitySet` with the resolved `filter`, read `expectedField`, compare to `expectedValue`
+     with `comparator`.
+   - `kind: "uiMessage"` (fallback) — check `FormState.Messages` for an entry of `severity` whose
+     text contains `pattern` as a **plain substring, not a regex** (empty `pattern` means "any
+     message of this severity, regardless of text"). `shouldExist: true` means a matching message
+     must be present; `false` means it must be absent — e.g. `{severity: "Error", pattern: "",
+     shouldExist: false}` asserts no error occurred at all, `{severity: "Info", pattern: "created",
+     shouldExist: true}` asserts a creation-confirmation message appeared.
+   Also capture each `outputs[]` entry the same way:
+   - `kind: "odata"` — query as above.
+   - `kind: "uiField"` with `controlName` set — read that exact control's value off `FormState` at
+     `afterStepSequence`. No extra tool call needed: the value is already in the response of a
+     step you're replaying anyway, so this is free and exactly reproducible.
+   - `kind: "uiField"` with only `hint` set (no `controlName`) — the control name wasn't known at
+     authoring time. This happens for values Task Recorder never captured because nobody clicked
+     them (a commonly-seen example: an auto-assigned ID that only appears on screen after Save).
+     Read the full `FormState` at `afterStepSequence` and use the hint (plain English, e.g. "the
+     newly assigned purchase order number") to identify the right field yourself. **After a
+     successful resolution, edit the test case file to add the resolved `controlName`** (keep
+     `hint` too) so future replays read it directly instead of re-interpreting `FormState` every
+     time — confirmed live on a purchase order creation: `PurchTable_PurchId` appeared cleanly in
+     the "Create purchase order" dialog's own `FormState` right after clicking New, well before
+     Save, with a clean scalar value (`"00000178"`) distinct from the header's later combined
+     `HeaderTitle` string (`"00000178 : 1001 - Acme Office Supplies"`) — pick the cleanest matching
+     field, not just the first one that looks plausible.
+   These become available to *later* test cases in the suite via `resolvedInputs`.
+4. Record the outcome:
+   `trxa record-result <testrun.json> <testCaseId> --status passed|failed|blocked --outputs '{"name":"value"}' --assertions '[{"description":"...","passed":true,"actual":"..."}]'`
+   `sequence`/`startedAt`/`durationMs` are computed automatically by this command — nothing to
+   pass. If this entry was replayed by a subagent (see "Running parallel-eligible branches
+   concurrently" above), **you** — the parent — are the one who runs this command, using the
+   subagent's reported result as the source for every flag below; the subagent never calls
+   `record-result` itself, and multiple entries from the same chunk are still recorded one at a
+   time, never concurrently.
+   - **On Windows PowerShell, prefer the `--outputs-file`/`--assertions-file`/`--inputs-file`/
+     `--messages-file` flags over the inline `'{...}'` form.** PowerShell 5.1's argument-passing
+     layer to a native executable (`node.exe` isn't a cmdlet) can silently corrupt inline JSON
+     before Node ever sees it — confirmed live in two distinct, reproducible ways: quote-less-of-
+     spaces JSON gets its `"` characters stripped outright, and JSON containing a space (e.g. a
+     `description`/`actual` string) gets split across multiple `argv` entries mid-string, so
+     `flagValue` only reads the truncated first piece. Neither is a bug in the tool (see `MANUAL.md`'s "Windows
+     PowerShell" section). The `-file` flags exist specifically to avoid this: write the JSON to a
+     scratch file, pass its path, done — this works identically in every shell. Write the file
+     **without a byte-order mark** (your own file-writing tool, or `[IO.File]::WriteAllText`, not
+     PowerShell 5.1's `Set-Content -Encoding utf8`/`Out-File`, which add one and make the JSON fail
+     to parse). Two more flags:
+   - `--messages '["...", "..."]'` — **always pass this, pass or fail, whenever any step you
+     replayed for this test case had a non-empty `FormState.Messages`.** Collect one entry per
+     message across *every* step of this test case, not just the last one (e.g. an early "Info:
+     Purchase order 00000226 has been created." plus a later validation message both belong here) —
+     format each as `"<Severity>: <text>"`. This is the Studio Test Runs page's "Infolog" column;
+     it's only as complete as what you actually pass here, since the CLI has no independent way to
+     observe it. Only omit `--messages` entirely if every step's `FormState.Messages` was genuinely
+     empty for this test case.
+     - **A message's `Text` can itself contain tab characters (`\t`) encoding a hierarchy** —
+       confirmed live: posting a sales order blocked by credit management returned
+       `"Posting\tPosting\tSales order: 000963\tOrder is in credit management."` as one `Warning`
+       entry. This is the exact same content the D365 web client's "Message details" flyout renders
+       as an indented tree (`Posting` → `Posting` → `Sales order: 000963` → the actual detail) —
+       there's no separate tool call or hidden data source behind that flyout, it's this string,
+       client-side-indented. **Don't strip or collapse the tabs** — replace them with `" > "` when
+       building the `--messages` entry (e.g. `"Warning: Posting > Posting > Sales order: 000963 >
+       Order is in credit management."`) so the hierarchy survives into the Infolog column instead
+       of getting silently flattened into a run-on sentence or truncated at the first tab.
+   - `--tokens`/`--cost` — nothing to do here. `record-result` auto-measures `tokensUsed` itself
+     (reading Claude Code's own session transcript for the window between this test case's
+     `"running"` transition and now) whenever you don't pass `--tokens` explicitly, so just leave
+     both flags out. Be aware the auto-measured number is only a rough signal, not a trustworthy
+     one, whenever another Claude Code session might be active against this project at the same
+     time — live-tested inflation of 24%-98% from cross-session misattribution (more detail in
+     `src/report-schema.ts`'s `tokensUsed` comment, if you have a source checkout to read it from)
+     — but there's nothing different to do about it here; it's still the best available default.
+     Only pass `--tokens` yourself if you have a better
+     number from somewhere else; leave `--cost` unset entirely — there's no reliable per-model,
+     cache-aware pricing table this
+     skill should be maintaining, so don't compute one from `tokensUsed` with a guessed price.
+   - `--inputs '{"name":"value"}'` — only needed if you invented values for `autogeneratedParams`
+     (step 1) and want the full input set on record, since `resolve-next`'s own automatic capture
+     only knows the deterministic bindings.
+   Then go back to step 1 for the next test case.
+5. Once `resolve-next` reports `"complete"`, read the final Test Run file and summarize: per
+   test case pass/fail, which assertions failed and why (the captured `actual` value is the
+   evidence), and which — if any — got `"blocked"` by an upstream failure.
+
+### Running parallel-eligible branches concurrently
+
+When step 1's `resolve-next` returns `runnable.length > 1`, the suite's author has deliberately
+shaped the DAG so these entries share a satisfied dependency without depending on each other (e.g.
+two entries that both only depend on one common upstream entry, like `purchase-order-lifecycle.json`'s
+receive/confirm pair) — that's an explicit signal to run them at the same time, not an incidental
+list to work through sequentially.
+
+1. **Determine the concurrency cap.** Each subagent needs its own live D365FO session/connection —
+   two agents sharing one `d365-erp-mcp` connection will corrupt each other's `FormState` mid-flight,
+   since navigation and form state are per-connection. Count the distinct `d365-erp-mcp`-style MCP
+   servers actually available this session (check the tool list; this repo typically exposes two:
+   `d365-erp-mcp` and `d365-erp-mcp-2`) and treat that count as the hard cap on simultaneous
+   subagents — never spawn more than you have connections for, even if `runnable` has more entries
+   than that.
+2. **Chunk `runnable` into groups of that size.** Process one chunk fully (spawn, wait for all,
+   record all) before starting the next chunk — don't pipeline across chunks.
+3. **Spawn one subagent per entry in the chunk, all in a single message** containing multiple `Agent`
+   tool_use blocks (this is what actually parallelizes them — spawning one at a time in separate
+   messages serializes them instead). Assign each subagent a distinct MCP connection explicitly (e.g.
+   "use only `d365-erp-mcp-2` tools for every form/data/API call, never `d365-erp-mcp`") so the two
+   replays can't collide. Each subagent's prompt must be fully self-contained — it has no memory of
+   this conversation — and should include:
+   - The `replay-trxa-testplan` skill's per-step replay procedure (steps 2-3 above: substitute
+     `resolvedInputs`/`autogeneratedParams` into the script, evaluate `expectations[]`, capture
+     `outputs[]`), for exactly this one entry's `testScriptPath`/`legalEntity`/`resolvedInputs`/
+     `autogeneratedParams`/`outputs`/`expectations` bundle — paste the actual values, don't make the
+     subagent re-derive them.
+   - The two numeric hard caps restated directly, not just referenced — a subagent that only reads
+     "the skill has caps" tends to loop past them: **cap async-operation polling at 20 polls** (per
+     the `SysOperationSandboxForm` guidance above) and **cap alternate-path attempts on a rejected
+     action at 3** (per "Handling a genuine failure mid-run" below).
+   - An explicit instruction **not** to call `resolve-next` or `record-result` itself — those mutate
+     the shared Test Run file, and concurrent read-modify-write from multiple subagents will clobber
+     each other's writes. The subagent's job ends at reporting back.
+   - The exact structured result to report back: `status` (`passed`/`failed`/`blocked`), `outputs`
+     (`{name: value}`), `assertionResults` (`[{description, passed, actual}]`), `messages` (the full
+     `FormState.Messages` stack, formatted per step 4's rules below, including the tab-hierarchy
+     `" > "` substitution), and whatever values it invented for `autogeneratedParams` (so the parent
+     can pass `--inputs` if needed).
+4. **Wait for every subagent in the chunk to finish**, then call `record-result` yourself, once per
+   entry, **sequentially — never concurrently** — using each subagent's reported result exactly as
+   step 4 above describes. You (the parent orchestrating session) are the only writer to the Test Run
+   file in this whole flow; the subagents only replay and report.
+5. Go back to step 1 (`resolve-next`) for the next batch — no need to call it once per entry you just
+   recorded, one call after the whole chunk is committed is enough, and it'll either surface the next
+   chunk or report `blocked`/`skipped`/`complete` as usual.
+
+This procedure is a direct extension of steps 1-4 above, not a separate system: a subagent replaying
+its one entry follows exactly the same "Executing each step"/step 2/step 3 guidance as a
+sequential solo replay would, it just does so in an isolated subagent with a pinned connection so
+several branches can run at once. It has not yet been exercised end-to-end against a live
+environment as of this writing — treat the mechanics above as the documented design, and note here
+if a live run surfaces something the steps above don't cover (a new failure mode, a caps value that
+turns out wrong, etc.), the same way the rest of this skill accumulates confirmed-live notes.
+
+**Handling a genuine failure mid-run — do not get creative, and do not ask.** A resolved input can
+itself turn out to be invalid (a fixture's vendor/item/account rejected by D365FO), or a business
+rule can block the action outright (a stopped vendor, a vendor blocked for invoicing, etc.). This
+is a real test result, not a reason to pause: an automated suite run has no one to ask mid-flight,
+so never stop the check-in loop to request a replacement value or confirmation from the user.
+- Try at most **3** alternate paths the recording or the current `FormState` itself suggests (e.g.
+  a ribbon tab click before the button it reveals, or a list-level equivalent of a per-record
+  action) — a hard cap, not a target. If those are all consistently rejected or disabled, that's
+  confirmation enough — don't keep searching for workarounds. Once the cause is a business rule
+  rather than a mapping gap, more attempts won't change the outcome; they only burn tool calls.
+- Record the failure with `record-result ... --status failed`, using the real error/message text
+  as the `actual` evidence — never invent a plausible-sounding one, and never substitute a
+  different value than what `resolvedInputs` gave you just to make the step succeed. This is
+  exactly the case step 4's `--messages` flag matters most for — pass the full `FormState.Messages`
+  stack you observed, not just the one line you happened to quote in `actual`.
+- Go back to step 1. `resolve-next` reports the directly-dependent entry as `blocked` and has
+  already recorded it as such itself (no `record-result` call needed) — just call `resolve-next`
+  again; in a linear chain this surfaces one dependent at a time, so repeat until it reports
+  `"complete"`.
+- Confirmed live: an invalid fixture item number, a stopped vendor, and a vendor deliberately
+  blocked for invoicing all surfaced this way in the same session — each correctly recorded as
+  `failed`/`blocked` with no manual intervention, and the run still completed as a durable,
+  accurate record of what actually happened.
+
+**If a `d365-erp-mcp` connection appears unresponsive, don't keep retrying the same one
+indefinitely — and don't try to "restart" it, that's not something you can actually do.** MCP
+servers are processes the host application launches and manages; you have no tool for killing or
+relaunching one mid-session, and a tool call is synchronous from your side — you can't unilaterally
+abandon a call that hasn't returned yet, only decide what to do once one comes back as an error (or
+the user interrupts). Confirmed live: `d365-erp-mcp` node processes hung entirely partway through a
+run and had to be killed/restarted by the user, outside the replay session itself.
+- If a call to one connection errors out in a way that looks connection-level (not a business-logic
+  rejection — a timeout, "no response," or similar, distinct from the "times out client-side but
+  succeeded server-side" pattern above, which is about one slow call, not a dead connection) more
+  than **2** times in a row, stop retrying that same connection.
+- If another `d365-erp-mcp*` connection is available and healthy (this project commonly has more
+  than one configured — see "Running parallel-eligible branches concurrently" below for how suites
+  already use multiple connections), switch the remaining work to it rather than continuing to
+  target the dead one. This is genuinely something you can do, unlike restarting a server.
+- If no healthy connection is available, stop the replay loop entirely rather than hang
+  indefinitely — go to "Stopping before a test case reaches a real outcome" immediately below, and
+  tell the user directly (breaking silence is warranted here) that the `d365-erp-mcp` connection
+  appears unresponsive and needs to be restarted on their end; that part genuinely isn't something
+  you can fix from inside the conversation.
+
+**Stopping before a test case reaches a real outcome — never leave an entry stuck at `"running"`.**
+If you need to end the replay loop before a currently in-flight test case has reached a definitive
+`passed`/`failed`/`blocked` outcome — the user asks you to stop, you're running low on
+context/budget, or anything else cuts the session short while you're still able to make one more
+tool call — record its outcome as `failed` before you stop. Don't just end the conversation with it
+left at `"running"`.
+
+This isn't just tidiness. `resolve-next`'s own logic (`nextStep` in `suite-runner.ts`) treats
+`"running"` as a normal mid-flight state, not an error, and reports `"waiting"` for as long as
+anything is stuck there — a suite with an abandoned `"running"` entry can never reach `"complete"`
+again, and a future session calling `resolve-next` against the same Test Run gets stuck reporting
+`"waiting"` forever instead of surfacing the next real step (confirmed by reading `nextStep`'s
+actual return logic, not assumed). There's no separate "stopped"/"cancelled" status to reach for
+either — the schema has `pending`/`running`/`passed`/`failed`/`blocked`/`skipped`, nothing else --
+`failed` is the honest, conservative choice when you don't actually know the outcome: better to
+under-claim success than leave a false still-in-progress marker behind.
+
+- Call `record-result ... --status failed`, with an assertion or `--messages` entry whose `actual`
+  clearly states this was an interruption, not a genuine business-process failure — e.g.
+  `"actual": "Replay stopped by user request before this step's outcome could be determined"` — so
+  a human reading the Test Run later can tell the difference from a real D365FO rejection.
+- If you're mid-batch in the parallel-branch procedure above and the *orchestrating* session itself
+  is what's stopping (not one individual subagent finishing normally), every entry `resolve-next`
+  marked `"running"` for that batch needs this treatment, not just whichever one you happened to be
+  looking at — check the Test Run file for every `"running"` entry before ending, not only the most
+  recent one.
+- This only applies when you're still active enough to make one more tool call before stopping — a
+  genuine hard crash with no chance to run anything is outside what any skill instruction can fix.
+  For that case: if a *future* replay session opens a Test Run and finds an entry already marked
+  `"running"` that clearly isn't actually in progress (no other session is active against it),
+  recover it the same way — record it `failed` with a message explaining it was found abandoned —
+  before proceeding, rather than treating a stale `"running"` marker as a currently-active run.
+
+If you don't yet have a Test Run file for a suite, create one first:
+`trxa init-run <suite.json> -o testruns/<suiteId>-<runId>.json`.
+
+## Running a whole Test Plan (multiple related suites)
+
+A Test Plan (`plans/*.json`) groups several independent Test Suites for combined reporting — no
+dependency graph between suites, unlike within one suite. To run one:
+
+1. Call `trxa init-plan-run <plan.json> -o runs/` once, before running any suite.
+   This creates a PlanRun record and prints its generated `id` — use that exact id as the
+   `<runId>` for every suite below, instead of inventing one yourself; it's what lets
+   `plan-status` correlate them afterward, and the file it's written to (`runs/<id>.json`) is
+   what you pass to `plan-status` in step 3.
+2. For each suite listed in the plan (`suites[].suitePath`, resolved relative to the plan file),
+   repeat the full per-suite procedure from "Running as part of a Test Suite" above unchanged,
+   using `testruns/<suiteId>-<runId>.json` as that suite's Test Run path.
+3. Once every suite in the plan has reached `"complete"` (or you want an in-progress snapshot),
+   call `trxa plan-status <plan.json> runs/<runId>.json --testruns-dir testruns`
+   and report its rollup (`all-passed` / `has-failures` / `incomplete` / `missing-runs`, plus the
+   per-suite breakdown) to the user — this is the plan-level summary, on top of each suite's own
+   per-test-case report from step 5 above.
+
+This does not touch the per-scenario replay guidance above. `mapping.ts`'s coverage has since been
+broadened and live-validated against several of the ~100 real business scenarios in `recordings/`
+(legal entity addresses, free text invoices, purchase order lines, product categories), which is why this skill now
+documents `skip`, tree navigation, and the filter/sort family above instead of only the one
+packing-slip scenario. Four more scenarios — a general journal entry, a fixed asset acquisition
+journal, a purchase order confirmation, and a vendor invoice matched/posted against a purchase
+order, all run end-to-end (see the grid-selection, lookup-defaults, `SegmentedEntry`,
+double-async-poll, skip-redundant-lookup, system-inserted-lines, skippable-tab-click,
+variable-async-duration, missing-workflow-button, match-status, and session-recovery notes above,
+all new findings these runs surfaced) — have since been run start-to-finish through live sessions
+too. Three of the four needed no `mapping.ts` changes; the fourth (invoice matching) surfaced a
+real correctness gap now fixed in `mapping.ts` itself: Date-typed values are reformatted from the
+recording's ISO to `M/d/yyyy` before being set, since some Date controls reject ISO outright. This
+covers the four starting categories originally proposed for this pass (general journal posting,
+fixed asset acquisition, PO confirmation, invoice matching); broadening further across the rest of
+`recordings/` remains open but is no longer scoped to a specific starting set.