bmad-method-test-architecture-enterprise 1.27.2-next.0 → 1.27.2-next.2

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test automation, CI/CD quality gates, and structured testing education. Part of the BMad Method ecosystem.",
-      "version": "1.27.2-next.0",
+      "version": "1.27.2-next.2",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/README.md

@@ -182,7 +182,7 @@ flowchart TB
 
 ### How It Works at Runtime
 
-**1. Activation.** `/bmad-tea` or `$bmad-tea` loads the agent skill. It resolves its customization block across base, team, and user layers, adopts the persona, loads persistent facts and `_bmad/tea/config.yaml`, greets you, and renders `{agent.menu}` as a numbered table. Naming an intent in your first message ("let's design tests for this epic") skips the menu and dispatches directly.
+**1. Activation.** `/bmad-tea` or `$bmad-tea` loads the agent skill. It resolves its customization block across base, team, and user layers, adopts the persona, loads persistent facts and `_bmad/tea/config.yaml`, greets you, and renders `{agent.menu}` as a numbered table. Naming one clear intent in your first message ("let's design tests for this epic") skips the menu and dispatches directly. A message that supports several menu choices triggers one focused question naming the relevant choices before any workflow starts.
 
 **2. Workflow entry.** Direct workflow commands use the installed skill name, such as `/bmad-testarch-automate` or `$bmad-testarch-automate`, depending on the host's invocation syntax. `TA` is the equivalent agent-menu code, available only once TEA is active. Either way, the workflow's `SKILL.md` resolves its own `[workflow]` customization block and asks which mode to run: Create, Resume, Validate, or Edit. Create and Resume both route into `steps-c/`; Validate into `steps-v/`; Edit into `steps-e/`. `test-review` alone supports `headless: true`, which skips the greeting and the menu and runs Create directly. That is how the CLI drives it in CI.
 
@@ -392,13 +392,15 @@ A passing fragment-selection eval means the workflow loaded the right knowledge.
 
 ### Deterministic Checks
 
-`npm test` chains seventy-one checks. That count covers the whole chain: every entry in it is deterministic and credential-free, so the chain and its credential-free subset are the same list. `npm run test:ci-coverage` derives the count from `package.json` and prints it. Eight of the seventy-one keep the rules, guidance, hook, eval data, eval contracts, diagnostics, and documentation aligned:
+`npm test` chains seventy-four checks. That count covers the whole chain: every entry in it is deterministic and credential-free, so the chain and its credential-free subset are the same list. `npm run test:ci-coverage` derives the count from `package.json` and prints it. Ten of the seventy-four keep the rules, guidance, hook, eval data, eval contracts, diagnostics, and documentation aligned:
 
 - `test:criteria-fragments` fails when a registry row is neither mapped to a knowledge fragment nor declared a known gap. A rule the reviewer scores but no fragment teaches is a rule TEA punishes without ever having explained it. All 36 rows are currently mapped across 50 anchors. Because the declared-gap list is empty, the validator feeds itself a synthetic unmapped row on every run to prove that path still works.
 - `test:doc-counts` runs `eval-quality-gates doc-counts`, which holds a hand-written count on a published page against the source that computes it: the roadmap's per-suite `eval:all` call counts, the knowledge-fragment tier breakdown, this section's own npm-test-chain length, and the fragment-selection case count. A pattern matching no sentence, or more than one, fails the same way a wrong number does, so the entry cannot go stale by drifting out from under its own pattern either.
 - `test:doc-claims` runs `eval-quality-gates doc-claims`, which holds a hand-written prose claim — a named symbol, a transcribed list, a worked JSON example, a named exit code, or a claim whose truth depends on when it was written — against the artifact it describes. A registered dated claim whose sentence was rewritten out from under it fails the same way a wrong symbol name does, so the entry cannot go stale by drifting out from under its own key either.
 - `test:enforce-hook` fails when a new Absolute registry row appears in neither the hook's enforced list nor its deferred list. This prevents a rule from being added without an explicit write-time enforcement decision.
+- `test:atdd-workflow-guidance` holds ATDD generation to one supplied criterion id per executable leaf, one primary scaffold per criterion, a criterion-defining first assertion, and a transition-bearing primary branch for state changes. It also checks every literal API and E2E example title against the same criterion-id format.
 - `test:eval-data` checks that all 24 fragment-selection cases are structurally usable: their workflow context files exist, every expected fragment exists and is indexed for that workflow, and the required and forbidden sets do not overlap. The expected sets come from the workflow step files. This check does not ask an agent to select anything.
+- `test:eval-routing-boundaries` mutates the facts, candidate codes, and missing deciding information in each source-bound routing ambiguity rule. It also rejects duplicate and orphan boundaries, plus any boundary that would turn a clear intent into a clarification.
 - `test:eval-schemas` checks this repository's own eval suite manifest against its schema, confirms that every threshold it declares is the threshold the harness actually applies, that the runner capabilities it declares are the ones the harness grants its runner, and that the preflight argv it declares fails on a missing runner and passes on a present one, and fails when a TEA skill has neither a behavioral suite nor a deferred declaration. A suite list that omits a skill reads as coverage, so the omission has to be an error rather than a silence.
 - `test:eval-diagnostics` checks that current result writers emit bounded case and repetition diagnostics, that quality and environment outcomes stay separate, that unstable signatures remain visible, and that the protected 1.3.0 baseline remains readable and byte-for-byte unchanged.
 - `test:contract-oracles` evaluates every oracle in every eval contract with `eval-quality`'s own evaluator, over the stored replay outputs and over constructed selections for all 24 fragment-selection cases, and fails when an oracle faults or disagrees with the harness scorer on the same evidence. The first run found that every regex oracle in the `test-review` contract was refused by the evaluator before it matched anything.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.27.2-next.0",
+  "version": "1.27.2-next.2",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -83,10 +83,11 @@
     "release:minor": "gh workflow run publish.yaml -f channel=latest -f bump=minor",
     "release:next": "gh workflow run publish.yaml -f channel=next",
     "release:patch": "gh workflow run publish.yaml -f channel=latest -f bump=patch",
-    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:atdd-workflow-guidance && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-routing-boundaries && npm run test:eval-routing-evidence && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:atdd-isolation": "node test/test-atdd-isolation.js",
     "test:atdd-net-guard": "node test/test-atdd-net-guard.js",
     "test:atdd-scoring": "node test/test-atdd-scoring.js",
+    "test:atdd-workflow-guidance": "node test/test-atdd-workflow-guidance.js",
     "test:automate-eval-fixture": "node test/test-automate-eval-fixture.js",
     "test:bmad-output-gated": "node test/test-bmad-output-gated.js",
     "test:boundary": "eval-quality-gates package-boundary",
@@ -121,7 +122,9 @@
     "test:eval-nfr-data": "node test/eval-nfr.js --validate-only",
     "test:eval-quality-corpus": "node test/test-eval-quality-corpus.js",
     "test:eval-replay": "node test/test-eval-replay.js",
+    "test:eval-routing-boundaries": "node test/test-routing-ambiguity-boundaries.js",
     "test:eval-routing-data": "node test/eval-bmad-tea-routing.js --validate-only",
+    "test:eval-routing-evidence": "node test/test-routing-evidence.js",
     "test:eval-schemas": "node tools/validate-eval-schemas.js",
     "test:eval-teach-me-testing-data": "node test/eval-teach-me-testing.js --validate-only",
     "test:eval-test-design-data": "node test/eval-test-design.js --validate-only",

package/src/agents/bmad-tea/SKILL.md

@@ -71,6 +71,43 @@ Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Act
 
 Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
 
+### Routing Ambiguity Boundaries
+
+Before dispatching, list the menu items directly supported by facts in the user's message. One supported item is a clear route. Two or more supported items require the missing deciding information when the user has supplied no priority, sequence, or requested deliverable that selects one.
+
+Ask one short question that names every supported choice in user-facing language and preserves any epic, story, feature, or file-set scope the user named. Keep the menu code and workflow unset until the user answers. Do not invoke any candidate while asking.
+
+In routing, `spec files` means written test files when the request asks which files are badly written and what to fix. That fact pattern is a clear Review Tests (`RV`) route. A request that identifies product requirements or design specifications falls outside this rule. Direct requests to judge existing tests, identify badly written tests, or recommend fixes for those tests also route to Review Tests. Fix recommendations remain part of the review. The Review Tests versus Trace Coverage boundary applies when the same request also asks which requirements or risks the tests cover, or whether that coverage supports shipping.
+
+<!-- routing-ambiguity-boundaries:start -->
+
+| Source case                       | Facts supplied by the user                                                         | Supported choices                                                 | Missing deciding information                                                                           |
+| :-------------------------------- | :--------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
+| `good-or-covering-what-matters`   | Existing tests raise both writing-quality and requirements-coverage concerns       | Review Tests (`RV`), Trace Coverage (`TR`)                        | Whether to assess how well the tests are written or map what they cover and evaluate ship readiness    |
+| `measured-some-nfrs-planned-none` | Measured NFR evidence exists for current work and future NFR coverage is unplanned | NFR Evidence Audit (`NR`), Test Design (`TD`)                     | Whether to audit the existing measurements or plan validation for the future scope first               |
+| `thin-coverage-on-payments`       | Coverage is described as thin with no requested activity                           | Test Design (`TD`), Test Automation (`TA`), Trace Coverage (`TR`) | Whether to plan coverage, generate tests, or measure current requirement coverage                      |
+| `story-half-done`                 | One scope contains an implemented part and an unbuilt part                         | ATDD (`AT`), Test Automation (`TA`)                               | Whether to create failing acceptance tests for the unbuilt part or automate the implemented part first |
+
+<!-- routing-ambiguity-boundaries:end -->
+
+### Unservable Request Boundaries
+
+When the facts support no menu item, keep the menu code and workflow unset. State the
+capability TEA's menu lacks and continue the conversation without activating a workflow.
+The closest-sounding menu item remains unavailable when its declared action cannot
+produce the requested result.
+
+<!-- routing-unservable-boundaries:start -->
+
+| Source case                | Requested result                      | Menu boundary                                                         | Missing capability                     |
+| :------------------------- | :------------------------------------ | :-------------------------------------------------------------------- | :------------------------------------- |
+| `run-and-fix-ci-failures`  | Execute the suite and repair failures | Continuous Integration scaffolds pipelines; Review Tests judges tests | Suite execution and failure repair     |
+| `write-production-code`    | Implement a production endpoint       | ATDD generates failing acceptance tests                               | Production implementation              |
+| `penetration-test-staging` | Perform a live penetration test       | NFR Evidence Audit assesses evidence already gathered                 | Security testing against a live target |
+| `hire-a-qa-lead`           | Produce hiring materials              | The menu serves testing and quality-engineering workflows             | Recruiting and interview design        |
+
+<!-- routing-unservable-boundaries:end -->
+
 ## Critical Actions
 
 - Consult `./resources/tea-index.csv` to select knowledge fragments under `resources/knowledge/` and load only the files needed for the current task.

package/src/workflows/testarch/bmad-testarch-atdd/atdd-checklist-template.md

@@ -34,11 +34,13 @@ inputDocuments: []
 
 ## Acceptance Criteria
 
-{List all testable acceptance criteria from the story}
+{List the persisted criterion registry. Preserve supplied ids. For unnamed criteria, assign the lowest unused `AC-<n>` id in source order.}
 
-1. {Acceptance criterion 1}
-2. {Acceptance criterion 2}
-3. {Acceptance criterion 3}
+| ID   | ID source          | Acceptance criterion     |
+| ---- | ------------------ | ------------------------ |
+| AC-1 | supplied/generated | {Acceptance criterion 1} |
+| AC-2 | supplied/generated | {Acceptance criterion 2} |
+| AC-3 | supplied/generated | {Acceptance criterion 3} |
 
 ---
 

package/src/workflows/testarch/bmad-testarch-atdd/checklist.md

@@ -20,6 +20,8 @@ Before starting this workflow, verify:
 
 - [ ] Story markdown file loaded and parsed successfully
 - [ ] All acceptance criteria identified and extracted
+- [ ] Supplied criterion ids preserved; unnamed criteria assigned the lowest unused `AC-<n>` ids in source order
+- [ ] Criterion registry persisted with `id`, `idSource`, and criterion text
 - [ ] Affected systems and components identified
 - [ ] Technical constraints documented
 - [ ] Framework configuration loaded (playwright.config.ts or cypress.config.ts)
@@ -95,6 +97,13 @@ Before starting this workflow, verify:
 
 - [ ] All tests use Given-When-Then structure with clear comments
 - [ ] All tests have descriptive names explaining what they test
+- [ ] Every executable leaf title carries exactly one declared `AC-<n>` id from the criterion registry
+- [ ] Every declared acceptance criterion has exactly one red-phase leaf scaffold
+- [ ] Secondary branches and journeys are recorded for green-phase automation
+- [ ] Criterion-defining assertion is the first assertion that can fail and directly isolates the exact newly promised status, scalar, or property
+- [ ] API setup responses from unimplemented endpoints remain opaque before the criterion assertion
+- [ ] E2E criterion-defining assertion is the first potentially failing operation and owns the browser journey
+- [ ] State-transition criteria exercise the transition-bearing branch first
 - [ ] No duplicate tests (same behavior tested multiple times)
 - [ ] No flaky patterns (race conditions, timing issues)
 - [ ] No test interdependencies (tests can run in any order)

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md

@@ -72,7 +72,11 @@ If any are missing: **HALT** and notify the user.
 ## 3. Load Story Context
 
 - Read story markdown from `{story_file}` (or ask user if not provided)
-- Extract acceptance criteria and constraints
+- Extract acceptance criteria and constraints into a criterion registry in source order
+- Preserve every supplied criterion id that matches `AC-<positive integer>` exactly
+- Reject duplicate supplied ids
+- Assign ids to unnamed criteria deterministically. Reserve all supplied ids first, then visit unnamed criteria in source order and assign the lowest unused `AC-<positive integer>` id
+- Persist each registry row as `{ id, idSource: supplied | generated, text }` and persist the exact ordered id set as `{criterion_ids}`. The same story content must always produce the same registry
 - Identify affected components and integrations
 - Derive and store `story_key` from the story filename when available (for BMM stories, this is the filename without `.md`, e.g. `1-2-user-authentication`)
 - Derive and store `story_id` from story metadata, the H1 heading, or the filename when available (for BMM stories, this is typically `{epic_num}.{story_num}`)
@@ -241,6 +245,7 @@ Summarize loaded inputs and confirm with the user. Then proceed.
 - Set `atddChecklistPath` to `{outputFile}`
 - Initialize `generatedTestFiles` to `[]`
 - Set `inputDocuments` to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files)
+- Set `acceptanceCriteria` to the persisted criterion registry, including generated ids and `idSource`
 
 Load next step: `{nextStepFile}`
 

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-03-test-strategy.md

@@ -38,7 +38,12 @@ Translate acceptance criteria into a prioritized, level-appropriate test plan.
 
 ## 1. Map Acceptance Criteria
 
-- Convert each acceptance criterion into test scenarios
+- Convert each acceptance criterion in the persisted registry into test scenarios
+- Record the exact declared acceptance criterion id on every scenario. Preserve supplied ids and use the preflight-generated id for an unnamed criterion
+- Plan exactly one primary red-phase scaffold for every declared criterion. Record secondary branches for green-phase automation without emitting extra red-phase leaves
+- Identify the one smallest criterion-defining assertion that must fail first. Assert the exact newly promised status, scalar, or property before broad object, schema, or secondary assertions
+- Establish prerequisite state through an existing fixture, provider state, or unasserted setup action. Keep an unimplemented setup response opaque before the criterion assertion: do not parse it, branch on it, throw from it, assert it, or derive cleanup data from it
+- For state-transition criteria, choose the transition-bearing branch as the primary red-phase scenario
 - Include negative and edge cases where risk is high
 
 ---
@@ -72,6 +77,8 @@ Assign P0–P3 priorities using risk and business impact.
 
 Ensure all tests are designed to **fail before implementation** (TDD red phase).
 
+For each declared criterion, confirm that its single red-phase scaffold reaches the criterion-defining assertion before any other assertion can fail. The first assertion must isolate the exact newly promised status, scalar, or property. Broad object, schema, and secondary assertions follow it within that leaf only when they cannot change its first failure. A criterion describing behavior after a state transition must exercise that transition. Record baseline branches and additional cases in the checklist for green-phase automation.
+
 ---
 
 ## 5. Save Progress

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-04a-subagent-api-failing.md

@@ -13,7 +13,7 @@ This is an **isolated subagent** running in parallel with E2E red-phase test gen
 
 **What you have from parent workflow:**
 
-- Story acceptance criteria from Step 1
+- Story acceptance criterion registry from Step 1, including preserved supplied ids and deterministic ids for unnamed criteria
 - Test strategy and scenarios from Step 3
 - Knowledge fragments loaded: playwright-utils-mandate, overview, api-request, recurse, log, auth-session, data-factories, api-testing-patterns
 - Config: test framework, `use_playwright_utils` (default `true`), Pact.js Utils enabled/disabled (`use_pactjs_utils`), Pact MCP mode (`pact_mcp`)
@@ -72,7 +72,7 @@ import { test, expect } from '../support/merged-fixtures';
 import { registrationPayload } from '../support/factories';
 
 test.describe('[Story Name] API Tests (ATDD)', () => {
-  test.skip('[P0] should register new user successfully', async ({ apiRequest }) => {
+  test.skip('[P0] AC-1 should register new user successfully', async ({ apiRequest }) => {
     // THIS TEST WILL FAIL - Endpoint not implemented yet
     const { status, body } = await apiRequest<RegisteredUser>({
       method: 'POST',
@@ -88,7 +88,7 @@ test.describe('[Story Name] API Tests (ATDD)', () => {
     });
   });
 
-  test.skip('[P1] should return 400 if email exists', async ({ apiRequest }) => {
+  test.skip('[P1] AC-2 should return 400 if email exists', async ({ apiRequest }) => {
     // THIS TEST WILL FAIL - Endpoint not implemented yet
     const { status, body } = await apiRequest({
       method: 'POST',
@@ -110,7 +110,7 @@ test.describe('[Story Name] API Tests (ATDD)', () => {
 import { test, expect } from '@playwright/test';
 
 test.describe('[Story Name] API Tests (ATDD)', () => {
-  test.skip('[P0] should register new user successfully', async ({ request }) => {
+  test.skip('[P0] AC-1 should register new user successfully', async ({ request }) => {
     const response = await request.post('/api/users/register', {
       data: { email: 'newuser@example.com', password: 'SecurePass123!' },
     });
@@ -139,6 +139,11 @@ If the merged-fixtures file does not exist yet, generate the import against `../
 **CRITICAL ATDD Requirements:**
 
 - ✅ Use `test.skip()` to mark tests as red-phase scaffolds
+- ✅ Every leaf `test.skip()` title MUST include exactly one declared acceptance criterion id from the Step 1 registry in the form `[P#] AC-<n> description`; an id on `test.describe()` does not map the leaf test
+- ✅ Generate exactly one red-phase leaf scaffold for every declared acceptance criterion. Record secondary branches and edge cases as green-phase checklist work; do not emit additional `test.skip()` leaves for the same criterion
+- ✅ The criterion-defining assertion MUST be the first assertion that can fail and MUST isolate the exact newly promised status, scalar, or property with a direct matcher. Put broad object, schema, and secondary assertions after it
+- ✅ Establish prerequisites through fixtures, provider state, or unasserted setup calls. Treat an unimplemented setup response as opaque before the criterion assertion: do not parse its body, branch on its result, throw from it, assert its status, or derive cleanup data from it. Use inputs known before the setup call and perform cleanup after the criterion assertion or in fixture teardown
+- ✅ For a state-transition criterion, choose the transition-bearing branch for the primary scaffold and assert the newly promised state directly
 - ✅ Write assertions for EXPECTED behavior (even though not implemented)
 - ✅ Use realistic test data (not placeholder data)
 - ✅ Test both happy path and error scenarios from acceptance criteria
@@ -185,7 +190,7 @@ When generating Pact consumer contract tests in the ATDD red phase, provider scr
  *   - Status: 201 for success, 400 for duplicate email, 422 for validation error
  *   - Response: { id: number, email: string, createdAt: string }
  */
-test.skip('[P0] should generate consumer contract for user registration', async () => {
+test.skip('[P0] AC-1 should generate consumer contract for user registration', async () => {
   await provider
     .given('no users exist')
     .uponReceiving('a request to register a new user')
@@ -238,6 +243,10 @@ Write JSON to temp file: `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
 {
   "success": true,
   "subagent": "atdd-api-tests",
+  "criterion_registry": [
+    { "id": "AC-1", "idSource": "supplied", "text": "A new user can register" },
+    { "id": "AC-2", "idSource": "generated", "text": "A duplicate email is rejected" }
+  ],
   "tests": [
     {
       "file": "tests/api/user-registration.spec.ts",

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-04b-subagent-e2e-failing.md

@@ -13,7 +13,7 @@ This is an **isolated subagent** running in parallel with API red-phase test gen
 
 **What you have from parent workflow:**
 
-- Story acceptance criteria from Step 1
+- Story acceptance criterion registry from Step 1, including preserved supplied ids and deterministic ids for unnamed criteria
 - Test strategy and user journey scenarios from Step 3
 - Knowledge fragments loaded: playwright-utils-mandate, overview, intercept-network-call, network-error-monitor, fixtures-composition, log, auth-session, fixture-architecture, network-first, selector-resilience
 - Config: test framework, `use_playwright_utils` (default `true`)
@@ -101,46 +101,46 @@ For each user journey, create test file in `tests/e2e/[feature].spec.ts`:
 import { test, expect } from '../support/merged-fixtures';
 
 test.describe('[Story Name] E2E User Journey (ATDD)', () => {
-  test.skip('[P0] should complete user registration successfully', async ({ page, interceptNetworkCall }) => {
-    // THIS TEST WILL FAIL - UI not implemented yet
-    // Declare the interception BEFORE navigating.
-    const registerCall = interceptNetworkCall({ url: '**/api/users/register', method: 'POST' });
-
-    await page.goto('/register');
-
-    // Expect registration form but will get 404 or missing elements
-    await page.getByLabel('Email').fill('newuser@example.com');
-    await page.getByLabel('Password').fill('SecurePass123!');
-    await page.getByRole('button', { name: 'Register' }).click();
-
-    const { status } = await registerCall;
-    expect(status).toBe(201);
-
-    await expect(page.getByText('Registration successful!')).toBeVisible();
-    await page.waitForURL('/dashboard');
+  test.skip('[P0] AC-1 should complete user registration successfully', async ({ page, interceptNetworkCall }) => {
+    // The outer assertion is the first potentially failing operation. It owns
+    // every navigation, interaction, network, and outcome failure in this AC.
+    await expect(
+      (async () => {
+        const registerCall = interceptNetworkCall({ url: '**/api/users/register', method: 'POST' });
+        await page.goto('/register');
+        await page.getByLabel('Email').fill('newuser@example.com');
+        await page.getByLabel('Password').fill('SecurePass123!');
+        await page.getByRole('button', { name: 'Register' }).click();
+
+        const { status } = await registerCall;
+        expect(status).toBe(201);
+        await expect(page.getByText('Registration successful!')).toBeVisible();
+        await page.waitForURL('/dashboard');
+      })(),
+    ).resolves.toBeUndefined();
   });
 
   // Stubs a 409 on purpose, so it opts out of network monitoring.
   test.skip(
-    '[P1] should show error if email exists',
+    '[P1] AC-2 should show error if email exists',
     { annotation: [{ type: 'skipNetworkMonitoring' }] },
     async ({ page, interceptNetworkCall }) => {
-      // THIS TEST WILL FAIL - UI not implemented yet
-      // Stub the conflict instead of depending on backend state.
-      const conflictCall = interceptNetworkCall({
-        url: '**/api/users/register',
-        method: 'POST',
-        fulfillResponse: { status: 409, body: { message: 'Email already exists' } },
-      });
-
-      await page.goto('/register');
-
-      await page.getByLabel('Email').fill('existing@example.com');
-      await page.getByLabel('Password').fill('SecurePass123!');
-      await page.getByRole('button', { name: 'Register' }).click();
-
-      await conflictCall;
-      await expect(page.getByText('Email already exists')).toBeVisible();
+      await expect(
+        (async () => {
+          const conflictCall = interceptNetworkCall({
+            url: '**/api/users/register',
+            method: 'POST',
+            fulfillResponse: { status: 409, body: { message: 'Email already exists' } },
+          });
+          await page.goto('/register');
+          await page.getByLabel('Email').fill('existing@example.com');
+          await page.getByLabel('Password').fill('SecurePass123!');
+          await page.getByRole('button', { name: 'Register' }).click();
+
+          await conflictCall;
+          await expect(page.getByText('Email already exists')).toBeVisible();
+        })(),
+      ).resolves.toBeUndefined();
     },
   );
 });
@@ -154,15 +154,17 @@ Note the selectors: `getByLabel` and `getByRole`, never `[name="email"]` or `but
 import { test, expect } from '@playwright/test';
 
 test.describe('[Story Name] E2E User Journey (ATDD)', () => {
-  test.skip('[P0] should complete user registration successfully', async ({ page }) => {
-    await page.route('**/api/users/register', (route) => route.continue());
-    await page.goto('/register');
-
-    await page.getByLabel('Email').fill('newuser@example.com');
-    await page.getByLabel('Password').fill('SecurePass123!');
-    await page.getByRole('button', { name: 'Register' }).click();
-
-    await expect(page.getByText('Registration successful!')).toBeVisible();
+  test.skip('[P0] AC-1 should complete user registration successfully', async ({ page }) => {
+    await expect(
+      (async () => {
+        await page.route('**/api/users/register', (route) => route.continue());
+        await page.goto('/register');
+        await page.getByLabel('Email').fill('newuser@example.com');
+        await page.getByLabel('Password').fill('SecurePass123!');
+        await page.getByRole('button', { name: 'Register' }).click();
+        await expect(page.getByText('Registration successful!')).toBeVisible();
+      })(),
+    ).resolves.toBeUndefined();
   });
 });
 ```
@@ -187,6 +189,10 @@ If the merged-fixtures file does not exist yet, generate the import against `../
 **CRITICAL ATDD Requirements:**
 
 - ✅ Use `test.skip()` to mark tests as red-phase scaffolds
+- ✅ Every leaf `test.skip()` title MUST include exactly one declared acceptance criterion id from the Step 1 registry in the form `[P#] AC-<n> description`; an id on `test.describe()` does not map the leaf test
+- ✅ Generate exactly one red-phase leaf scaffold for every declared acceptance criterion. Record secondary journeys as green-phase checklist work; do not emit additional `test.skip()` leaves for the same criterion
+- ✅ The criterion-defining assertion MUST be the first potentially failing operation. Wrap the complete browser journey in one `expect((async () => { ... })()).resolves.toBeUndefined()` assertion so navigation, locator, interaction, network, and outcome failures retain criterion provenance without retrying stateful steps
+- ✅ For a state-transition criterion, choose the transition-bearing branch for the primary scaffold and assert the newly promised state directly
 - ✅ Write assertions for EXPECTED UI behavior (even though not implemented)
 - ✅ Use resilient selectors: getByRole, getByText, getByLabel (from selector-resilience). Never `[name="..."]`, `button:has-text(...)`, CSS classes, or XPath
 - ✅ Network-first: interception declared before navigation when API calls are involved (from network-first; mechanism per the mandate when enabled)
@@ -222,6 +228,10 @@ Write JSON to temp file: `/tmp/tea-atdd-e2e-tests-{{timestamp}}.json`
 {
   "success": true,
   "subagent": "atdd-e2e-tests",
+  "criterion_registry": [
+    { "id": "AC-1", "idSource": "supplied", "text": "A new user can register" },
+    { "id": "AC-2", "idSource": "generated", "text": "A duplicate email is rejected" }
+  ],
   "tests": [
     {
       "file": "tests/e2e/user-registration.spec.ts",

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-04c-aggregate.md

@@ -66,6 +66,7 @@ const e2eTestsOutput = JSON.parse(fs.readFileSync(e2eTestsPath, 'utf8'));
 - Check `apiTestsOutput.success === true`
 - Check `e2eTestsOutput.success === true`
 - If either failed, report error and stop (don't proceed)
+- Require both workers' `criterion_registry` to match the persisted Step 1 registry exactly, including order, ids, `idSource`, and text
 
 ---
 
@@ -73,6 +74,20 @@ const e2eTestsOutput = JSON.parse(fs.readFileSync(e2eTestsPath, 'utf8'));
 
 **CRITICAL TDD Validation:**
 
+Load the exact criterion registry persisted by Step 1. For every leaf `test.skip()` title from both worker outputs, extract all tokens matching `\bAC-\d+\b`. Require exactly one token, then require that token to be a member of the registry. Reject titles with zero ids, multiple ids, repeated copies of one id, or an undeclared id. Count mapped leaf titles per criterion across both worker outputs. Require exactly one red-phase leaf for every declared criterion. An id present only on a containing `test.describe()` does not count. Record secondary branches and journeys in the implementation checklist for green-phase automation.
+
+For each criterion's primary scaffold, verify that the criterion-defining assertion is the first assertion that can fail and directly isolates the exact newly promised status, scalar, or property. Broad object, schema, and secondary assertions must follow it. An API setup call to an unimplemented endpoint must remain opaque before this assertion: no body parsing, result branching, explicit throw, status assertion, or cleanup-data derivation. In E2E scaffolds the criterion assertion must also be the first potentially failing operation and must own the complete browser journey. For a state-transition criterion, verify that the primary scaffold exercises the transition-bearing branch and directly asserts the newly promised state.
+
+Use this title guard as written:
+
+```javascript
+const declaredIds = new Set(criterionRegistry.map(({ id }) => id));
+const ids = title.match(/\bAC-\d+\b/g) ?? [];
+if (ids.length !== 1 || !declaredIds.has(ids[0])) {
+  throw new Error(`ATDD ERROR: leaf title must carry exactly one declared criterion id: ${title}`);
+}
+```
+
 **Check API tests:**
 
 ```javascript
@@ -118,6 +133,9 @@ e2eTestsOutput.tests.forEach((test) => {
 ```text
 ✅ TDD Red Phase Validation: PASS
 - All tests use test.skip()
+- Every leaf test maps to exactly one declared acceptance criterion
+- Every declared acceptance criterion has exactly one red-phase leaf scaffold
+- Each primary scaffold reaches a direct, exact criterion-defining assertion first
 - All tests assert expected behavior (not placeholders)
 - All tests marked as expected_to_fail
 ```

package/src/workflows/testarch/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md

@@ -43,6 +43,14 @@ Use `checklist.md` to validate:
 - Test files created correctly
 - Checklist matches acceptance criteria
 - Tests are generated as red-phase scaffolds and marked with `test.skip()`
+- Preflight preserved supplied criterion ids and assigned stable, collision-free ids to unnamed criteria
+- Every executable leaf title carries exactly one id from the persisted criterion registry
+- Every declared acceptance criterion has exactly one red-phase leaf scaffold
+- Secondary branches and journeys are checklist work for green-phase automation
+- The criterion-defining assertion is the first assertion that can fail and directly isolates the exact newly promised status, scalar, or property
+- API setup responses from unimplemented endpoints remain opaque before the criterion assertion
+- Each E2E primary scaffold begins with the criterion-defining assertion as its first potentially failing operation
+- State-transition criteria exercise the transition-bearing branch in their primary scaffold
 - Story metadata and handoff paths are captured for downstream workflows
 - [ ] CLI sessions cleaned up (no orphaned browsers)
 - [ ] Temp artifacts stored in `{test_artifacts}/` not random locations

package/src/workflows/testarch/bmad-testarch-atdd/steps-v/step-01-validate.md

@@ -59,6 +59,8 @@ Read `{validationChecklist}` and list all criteria.
 
 Evaluate outputs against each checklist item.
 
+For ATDD test artifacts, reconstruct the criterion registry from the selected checklist. Confirm supplied ids were preserved and generated ids follow the lowest-unused `AC-<n>` rule in source order. Extract all `\bAC-\d+\b` tokens from every executable leaf title. Require exactly one token and require it to exist in the registry. Require exactly one red-phase leaf per declared criterion. For every scaffold, confirm the first assertion directly isolates the exact newly promised status, scalar, or property. Confirm API setup responses from unimplemented endpoints remain opaque before that assertion. For each E2E scaffold, confirm the criterion-defining assertion is the first potentially failing operation and owns the complete browser journey.
+
 ### 4. Write Report
 
 Replace the `IN_PROGRESS` body in this run's reserved `{outputFile}` with the final validation report. Include PASS/WARN/FAIL per section plus the original `validation_scope`, `run_timestamp`, and `validated_artifacts` metadata. Record every selected artifact using its exact project-relative path.