Develop

.github/workflows/DeployManual.yml

@@ -24,6 +24,13 @@ jobs:
           registry-url: 'https://registry.npmjs.org'
           scope: '@provartesting'
       - name: Install dependencies and build
+        env:
+          # Required by scripts/fetch-nitrox-packages.cjs to pull the latest
+          # NitroX schemas and component catalog from ProvarTesting/factPackages
+          # at release time. Without this, prepack falls back to the bundled
+          # snapshots and ships them as-is. The auto-provided GITHUB_TOKEN has
+          # read access to factPackages.
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           npm install -g @salesforce/cli
           yarn
@@ -75,23 +82,27 @@ jobs:
         if: success()
         env:
           RELEASE_BODY: ${{ github.event.release.body }}
+          GH_TOKEN: ${{ github.token }}
         run: |
           VERSION=$(node -p "require('./package.json').version")
           TAG="${{ github.event.inputs.tag || 'latest' }}"
 
           # --- Determine change notes source ---
           if [ -n "$RELEASE_BODY" ]; then
-            # GitHub Release body provided — use it verbatim
+            # GitHub Release body provided via release event — use it verbatim
             NOTES="$RELEASE_BODY"
           else
-            # Auto-extract from git log since the previous tag
+            # workflow_dispatch: fetch release notes from the GitHub release for this version
+            NOTES=$(gh api "repos/${{ github.repository }}/releases/tags/v${VERSION}" --jq '.body' 2>/dev/null || echo "")
+          fi
+
+          if [ -z "$NOTES" ]; then
+            # Final fallback: auto-extract from git log since the previous tag
             if [ "${{ github.event_name }}" = "release" ]; then
-              # Release event: HEAD is the new tag — find the nearest ancestor tag before it
               PREV=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || git tag --sort=-version:refname | head -1)
             else
-              # Manual dispatch: find the nearest ancestor tag from HEAD
-              # (git describe respects branch ancestry; avoids pulling in commits from sibling branches)
-              PREV=$(git describe --tags --abbrev=0 HEAD 2>/dev/null || true)
+              # HEAD^ avoids returning the current tag itself when HEAD is exactly at a tag
+              PREV=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || true)
             fi
 
             RANGE="${PREV:+${PREV}..}HEAD"

CLAUDE.md

@@ -104,3 +104,16 @@ The project uses ESLint with `@typescript-eslint` strict rules. Common gotchas:
 - `camelcase` — `nitroX` is valid camelCase (capital X starts the next word)
 
 CI runs lint as part of `sf-prepack` — do not skip with `--no-verify` on the final merge commit.
+
+---
+
+## Script naming convention
+
+Files anywhere under `scripts/` (including nested subdirectories) must be named for what they **do**, not for the ticket that prompted them. Ticket-prefixed names (e.g. `pdx-482-validate.cjs`) leak internal Jira plumbing into the file tree, age poorly once the ticket closes, and surface in customer-visible artifacts (CI logs, PR diffs, repo browsing).
+
+- **Allowed:** `authoring-flow-trace.cjs`, `construction-contract-validate.cjs`, `mcp-smoke.cjs`, `fetch-nitrox-packages.cjs`
+- **Rejected:** `pdx-482-validate.cjs`, `PDX_481_trace.cjs`, `scripts/tmp/pdx-999.cjs`, anything whose basename matches `^pdx[-_]?\d+` (case-insensitive)
+
+Enforced by `scripts/lint-script-names.cjs`, which walks `scripts/` recursively and runs as a dependency of `yarn lint` (wireit `lint:script-names`). The check fails the lint step if any ticket-prefixed filename appears at any depth.
+
+Ticket IDs and rationale belong in commit messages and PR descriptions, not in filenames or in user-facing docs (`docs/mcp.md`, `docs/mcp-pilot-guide.md`).

docs/PROVAR_TOOL_GUIDE.md

@@ -77,15 +77,27 @@ provar_properties_set  { file_path: "<output_path>", key: "connectionName", valu
 
 ## "I want to write a new test"
 
+A Provar test case is a tree (scenarios → UI screens → asserts), not a flat list of steps. The agent that calls `provar_testcase_generate` is responsible for constructing the full tree in **one** call. Splitting authoring across many tool calls causes scenario numbering drift, flat asserts, and inconsistent step types — `provar_testcase_step_edit` is for **amending** an existing test case, not for **constructing** one.
+
+Recommended sequence:
+
 ```
-1. provar_project_inspect    { project_path }           ← find coverage gaps first
-2. provar_testcase_generate  { project_path, name, ... }
-3. provar_testcase_step_edit { test_case_path, ... }    ← repeat per step
-4. provar_testcase_validate  { file_path }              ← must pass before adding to plan
-5. provar_testplan_add-instance  { project_path, plan_name, test_case_path }
-6. provar_testplan_validate      { project_path, plan_name }
+1. provar_project_inspect              { project_path }                        ← find coverage gaps first
+2. provar_qualityhub_examples_retrieve { object_or_scenario }                  ← ground in corpus examples for the step types you need
+3. provar_testcase_generate            { test_case_name, steps: [<ALL steps>] } ← single call, full step tree in one payload
+4. provar_testcase_validate            { file_path }                            ← must pass before adding to plan
+5. provar_testplan_add-instance        { project_path, plan_name, test_case_path }
+6. provar_testplan_validate            { project_path, plan_name }
 ```
 
+Use `provar_testcase_step_edit` only when:
+
+- Adding a single step to an existing, already-validated test case
+- Fixing a step's attributes after a validation finding
+- Targeted edits during debugging
+
+Do **not** use `provar_testcase_step_edit` to construct a test case step-by-step from an empty skeleton — the LLM loses scenario context between calls and the resulting structure is unreliable.
+
 ---
 
 ## "I want to work with Salesforce metadata"

docs/mcp-pilot-guide.md

@@ -439,6 +439,50 @@ NitroX is Provar's Hybrid Model for locators — it maps Salesforce component-ba
 
 ---
 
+### Scenario 12: Construct a Multi-Scenario Test Case in a Single Call
+
+**Goal:** Confirm the AI authors a multi-scenario test case by passing the full step tree to `provar_testcase_generate` in **one** call — not by generating an empty skeleton and looping `provar_testcase_step_edit` per step.
+
+**Background:** A previously observed regression traced to authoring guidance that steered LLMs toward a per-step construction pattern. Multi-call construction drops scenario numbers (e.g. Scenario 1 → Scenario 3, no Scenario 2), flattens asserts that should be nested inside `UiWithScreen` clauses, and produces inconsistent assert API IDs across the case. This scenario exists so the regression class is exercised in pilot evaluation and cannot recur silently.
+
+**Defense in depth.** Three layers protect against the multi-call construction pattern:
+
+1. **Prompt and resource guidance** — authoring prompts and the MCP step-reference resource describe single-call construction as the contract.
+2. **Tool-description contract** — `provar_testcase_generate` and `provar_testcase_step_edit` descriptions explicitly mark generate as constructor-only and step_edit as amendment-only, so the LLM reads the contract at every call site (including compact schema mode).
+3. **Runtime guard** — `provar_testcase_generate` rejects the exact shape that would produce a skeleton-only file: `steps:[]` + `dry_run:false` + `output_path`. The rejection returns `STEPS_REQUIRED` with `details.suggestion` telling the LLM to pass the full step tree in one call. Empty-steps shapes that don't write a file (dry-run preview, no `output_path`) remain allowed.
+
+If a pilot LLM falls into the multi-call pattern despite the description contract, the runtime guard converts the failure into an actionable error rather than a silently broken file on disk.
+
+**Title-level contract:** the chip-level `title` fields for the two tools — `Generate Test Case (full steps in one call)` and `Amend Existing Test Case Step` — carry the construct-vs-amend split at the tool-picker surface. MCP clients that render only the title (Claude Desktop tool-picker chips, Cursor audit pane, inline tool-call references in chat threads) still expose the contract to the agent before any description is read.
+
+**Prompt:**
+
+> "Create a Provar test case `AccountFlow.testcase` that covers three scenarios:
+>
+> 1. **Create Account** — navigate to the Account home, click New, set Name = `{AccountName}` and Phone = `{AccountPhone}`, click Save
+> 2. **Verify Account on List** — navigate back to the Account list view, assert the Name and Phone values
+> 3. **Open Account Detail** — open the just-created Account, assert all saved field values
+>
+> Use UI On Screen wrappers, AssertValues for value assertions, and reference SetValues variables with `{Name}`. Write to `<project-path>/tests/AccountFlow.testcase`."
+
+**What to look for (PASS):**
+
+- Exactly **one** call to `provar_testcase_generate` with a populated `steps[]` array — not a call with `steps: []` followed by N `step_edit` calls
+- The generated XML lists three scenarios numbered consecutively (1, 2, 3 — no skipped numbers)
+- Each scenario's UI actions and asserts are nested inside the appropriate `UiWithScreen` clause (or its equivalent grouping element) — not flat siblings under `<steps>`
+- Assert step types are consistent across the case (e.g. all `AssertValues`, not mixed `AssertValues` + `UiAssert` for the same purpose)
+- `provar_testcase_validate` on the result returns `is_valid: true`
+
+**What to look for (FAIL — regression indicator):**
+
+- Two or more calls to `provar_testcase_generate` for the same file
+- A call to `provar_testcase_generate` with `steps: []` followed by `provar_testcase_step_edit` calls
+- The generated case skips a scenario number, mixes assert API IDs for similar assertions, or emits asserts as flat siblings rather than nested inside the screen wrapper
+
+If any FAIL indicator appears, report it to the Provar team with the prompt and the generated XML attached.
+
+---
+
 ## Security Model
 
 ### What the server does