bmad-method-test-architecture-enterprise 1.13.0 → 1.14.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,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.13.0",
+      "version": "1.14.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/.github/workflows/publish.yaml

@@ -0,0 +1,168 @@
+name: Publish
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/**"
+      - "package.json"
+      - "package-lock.json"
+  workflow_dispatch:
+    inputs:
+      channel:
+        description: "Publish channel"
+        required: true
+        default: "latest"
+        type: choice
+        options:
+          - latest
+          - next
+      bump:
+        description: "Version bump type (latest channel only)"
+        required: false
+        default: "patch"
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+concurrency:
+  group: publish-${{ github.event_name }}-${{ github.ref_name }}-${{ inputs.channel || 'push' }}
+  cancel-in-progress: ${{ github.event_name == 'push' }}
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  publish:
+    if: github.repository == 'bmad-code-org/bmad-method-test-architecture-enterprise' && (github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/main')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Ensure trusted publishing toolchain
+        run: |
+          # npm trusted publishing requires modern npm on the runner.
+          npm install --global npm@11.6.2
+
+      - name: Configure git user
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Derive next prerelease version
+        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'next')
+        run: |
+          NEXT_VER=$(npm view bmad-method-test-architecture-enterprise@next version 2>/dev/null || echo "")
+          LATEST_VER=$(npm view bmad-method-test-architecture-enterprise@latest version 2>/dev/null || echo "")
+
+          BASE=$(node -e "
+            const semver = require('semver');
+            const next = process.argv[1] || null;
+            const latest = process.argv[2] || null;
+            if (!next && !latest) process.exit(0);
+            if (!next) { console.log(latest); process.exit(0); }
+            if (!latest) { console.log(next); process.exit(0); }
+            const nextBase = next.replace(/-next\.\d+$/, '');
+            console.log(semver.gte(latest, nextBase) ? latest : next);
+          " "$NEXT_VER" "$LATEST_VER")
+
+          if [ -n "$BASE" ]; then
+            npm version "$BASE" --no-git-tag-version --allow-same-version
+          fi
+          npm version prerelease --preid=next --no-git-tag-version
+
+      - name: Bump stable version
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: npm version "${{ inputs.bump }}" --no-git-tag-version
+
+      - name: Sync marketplace version
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+
+          const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+          const marketplacePath = '.claude-plugin/marketplace.json';
+          const marketplace = JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));
+          const plugin = (marketplace.plugins || []).find((entry) => entry && entry.name === packageJson.name);
+
+          if (!plugin) {
+            throw new Error(`Marketplace entry not found for ${packageJson.name}`);
+          }
+
+          plugin.version = packageJson.version;
+          fs.writeFileSync(marketplacePath, `${JSON.stringify(marketplace, null, 2)}\n`);
+          NODE
+
+      - name: Validate release metadata
+        run: npm run test:release-metadata
+
+      - name: Publish prerelease to npm
+        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'next')
+        run: npm publish --tag next --provenance
+
+      - name: Commit version bump
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: |
+          VERSION=$(node -p 'require("./package.json").version')
+          git add package.json package-lock.json .claude-plugin/marketplace.json
+          git commit -m "release: bump to v${VERSION} [skip ci]"
+          git tag -a "v${VERSION}" -m "Release v${VERSION}"
+
+      - name: Push version commit and tag
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: git push origin main --follow-tags
+
+      - name: Publish stable release to npm
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: npm publish --tag latest --provenance
+
+      - name: Create GitHub Release
+        if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest'
+        run: |
+          TAG="v$(node -p 'require("./package.json").version')"
+          VERSION="${TAG#v}"
+          BODY=$(awk -v ver="$VERSION" '
+            /^## / {
+              if (found) exit
+              if ($0 ~ ("^##[[:space:]]*\\[?[[:space:]]*v?" ver "[[:space:]]*\\]?([[:space:]]*-[[:space:]].*)?$")) found=1
+              next
+            }
+            found { print }
+          ' CHANGELOG.md)
+          if [ -z "$BODY" ]; then
+            echo "::warning::No CHANGELOG.md entry for $TAG — falling back to auto-generated notes"
+            gh release create "$TAG" --generate-notes
+          else
+            gh release create "$TAG" --notes "$BODY"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -28,26 +28,28 @@ BMad is a small **agent + workflow engine**. There is no external orchestrator
 
 ### Building Blocks
 
-Each workflow directory contains these files, and each has a specific job:
-
-| File              | What it does                                                                                                        | When it loads                                                             |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `SKILL.md`        | Expert persona — identity, principles, critical actions, capabilities table                                         | First — always in context                                                 |
-| `workflow.yaml`   | Machine-readable metadata — config variables, required tools, tags                                                  | Second — resolves `{project-root}`, `{config_source}`, `{test_artifacts}` |
-| `workflow.md`     | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step                          | Second — presents mode choice                                             |
-| `instructions.md` | Workflow-specific rules and context (optional, supplements workflow.md)                                             | On demand                                                                 |
-| `steps-c/*.md`    | **Create** steps — primary execution, 5-9 sequential files                                                          | One at a time (just-in-time)                                              |
-| `steps-e/*.md`    | **Edit** steps — always 2 files: assess target, apply edit                                                          | One at a time                                                             |
-| `steps-v/*.md`    | **Validate** steps — always 1 file: evaluate against checklist                                                      | On demand                                                                 |
-| `checklist.md`    | Validation criteria — what "done" looks like for this workflow                                                      | Read by steps-v                                                           |
-| `*-template.md`   | Output skeleton with `{PLACEHOLDER}` vars — steps fill these in to produce the final artifact                       | Read by steps-c when generating output                                    |
-| `tea-index.csv`   | Knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path                              | Read by step-01 to decide which fragments to load                         |
-| `knowledge/*.md`  | 40 reusable fragments — standards, patterns, API references (e.g., `data-factories.md`, `pactjs-utils-overview.md`) | Selectively read into context based on tier + config flags                |
+TEA has two layers of files, and each has a specific job:
+
+| File / Scope                                       | What it does                                                                                         | When it loads                                           |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `src/agents/bmad-tea/SKILL.md`                     | Murat's persona — identity, principles, critical actions, capabilities table                         | First — activates the TEA agent                         |
+| `src/agents/bmad-tea/customize.toml`               | Agent customization surface — menu items, persistent facts, activation hooks                         | During agent activation                                 |
+| `src/workflows/testarch/<workflow>/SKILL.md`       | Workflow entrypoint — resolves workflow customization, picks mode, routes to the first step          | When a TEA workflow is invoked                          |
+| `src/workflows/testarch/<workflow>/customize.toml` | Workflow customization surface — activation hooks, persistent facts, optional `on_complete` behavior | During workflow activation                              |
+| `src/workflows/testarch/<workflow>/workflow.yaml`  | Machine-readable workflow metadata — descriptions, defaults, tool hints, output paths                | Used by installer/tooling and workflow metadata lookups |
+| `instructions.md`                                  | Workflow-specific summary and operator notes                                                         | On demand                                               |
+| `steps-c/*.md`                                     | **Create** steps — primary execution, 5-9 sequential files                                           | One at a time (just-in-time)                            |
+| `steps-e/*.md`                                     | **Edit** steps — always 2 files: assess target, apply edit                                           | One at a time                                           |
+| `steps-v/*.md`                                     | **Validate** steps — always 1 file: evaluate against checklist                                       | On demand                                               |
+| `checklist.md`                                     | Validation criteria — what "done" looks like for this workflow                                       | Read by steps-v                                         |
+| `*-template.md`                                    | Output skeleton with `{PLACEHOLDER}` vars — steps fill these in to produce the final artifact        | Read by steps-c when generating output                  |
+| `src/agents/bmad-tea/resources/tea-index.csv`      | Knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path               | Read to decide which shared TEA fragments to load       |
+| `resources/knowledge/*.md`                         | Reusable fragments — standards, patterns, API references                                             | Selectively read into context based on tier + config    |
 
 ```mermaid
 flowchart LR
   U[User] --> A[Agent Persona]
-  A --> W[Workflow Entry: workflow.md]
+  A --> W[Workflow Entry: workflow SKILL.md]
   W --> S[Step Files: steps-c / steps-e / steps-v]
   S --> K[Knowledge Fragments<br/>tea-index.csv → knowledge/*.md]
   S --> T[Templates & Checklists<br/>*-template.md, checklist.md]
@@ -59,8 +61,8 @@ flowchart LR
 
 1. **Trigger** — Direct commands are `/bmad:tea:automate` (Claude/Cursor/Windsurf) and `$bmad-tea-testarch-automate` (Codex). Load the conversational TEA menu with `$bmad-tea` in Codex. `TA` is an agent-menu trigger available only after TEA is activated; the capabilities table in `SKILL.md` maps `TA` to the `bmad-testarch-automate` skill.
 2. **Agent loads** — `SKILL.md` injects the persona (identity, principles, critical actions) into the context window.
-3. **Workflow loads** — `workflow.yaml` resolves config variables and `workflow.md` presents the mode menu (Create / Edit / Validate), then routes to the first step file.
-4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one (`nextStepFile: './step-02-...'`). The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
+3. **Workflow loads** — The workflow's `SKILL.md` becomes the entrypoint. It resolves the workflow block from `customize.toml`, loads persistent facts and config, decides the mode (Create / Edit / Validate), then routes to the first step file.
+4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one with a `{skill-root}`-anchored path. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
 5. **Knowledge injection** — Step-01 reads `tea-index.csv` and selectively loads fragments by **tier** (core = always, extended = on-demand, specialized = only when relevant) and **config flags** (e.g., `tea_use_pactjs_utils`). This is deliberate context engineering: a backend project loads ~1,800 lines of fragments; a fullstack project loads ~4,500 lines. Conditional loading cuts context usage by 40-50%.
 6. **Templates** — When a step produces output (e.g., a traceability matrix or test review report), it reads the `*-template.md` file and fills in the `{PLACEHOLDER}` values with computed results. The template provides consistent structure; the step provides the content.
 7. **Subagent isolation** — Heavy workflows (e.g., `automate`) spawn parallel subagents that each run in an isolated context. Subagents write structured JSON to temp files. An aggregation step reads the JSON outputs — only the results enter the main context, not the full subagent history.
@@ -84,12 +86,12 @@ BMad workflows and Claude Code Skills solve different problems at different scal
 
 The key insight is that there is **no external runtime engine** — the LLM _is_ the engine. BMad workflows are structured markdown that the LLM follows as instructions: "read this file, execute it completely, save your output, load the next file." Skills are a single tool in a toolbox; BMad workflows are a workshop with a process manual.
 
-**How workflows become commands.** When you run `npx bmad-method install`, the installer generates tool-specific artifacts for your runtime (for example, Claude Code uses `.claude/commands/`, while Codex uses `.agents/skills/`). In Claude Code, `bmad-tea-testarch-automate.md` tells the LLM: "load the core workflow engine (`workflow.xml`), pass it this workflow config (`automate/workflow.yaml`), follow the instructions exactly." That launcher artifact is the bridge — it triggers the workflow entry point; the multi-step engine takes over from there.
+**How workflows become commands.** When you run `npx bmad-method install`, the installer generates tool-specific artifacts for your runtime (for example, Claude Code uses `.claude/commands/`, while Codex uses `.agents/skills/`). Those launchers bridge into the installed TEA agent or workflow package. Once invoked, the workflow's `SKILL.md` is the conversational entrypoint, and the step-file process takes over from there.
 
 ```text
 .claude/commands/                         # Generated by installer
 ├── bmad-tea.md                           # /tea → loads agent persona + menu
-├── bmad-tea-testarch-automate.md         # /automate → loads workflow.xml + workflow.yaml
+├── bmad-tea-testarch-automate.md         # /automate → invokes the automate workflow package
 ├── bmad-tea-testarch-test-design.md      # /test-design → ...
 ├── bmad-bmm-create-prd.md               # /create-prd → BMM workflow
 └── ... (61 commands total across all installed modules)
@@ -174,7 +176,12 @@ Workflows load only the fragments required for the current task to stay focused
 src/
 ├── module.yaml
 ├── agents/
-│   └── bmad-tea/              # Native skill: SKILL.md + bmad-skill-manifest.yaml
+│   └── bmad-tea/
+│       ├── SKILL.md
+│       ├── customize.toml
+│       └── resources/
+│           ├── tea-index.csv
+│           └── knowledge/
 ├── workflows/
 │   └── testarch/
 │       ├── bmad-teach-me-testing/
@@ -186,11 +193,6 @@ src/
 │       ├── bmad-testarch-test-design/
 │       ├── bmad-testarch-test-review/
 │       └── bmad-testarch-trace/
-└── agents/
-    └── bmad-tea/
-        └── resources/
-            ├── tea-index.csv
-            └── knowledge/
 ```
 
 ## Extending TEA
@@ -214,17 +216,28 @@ See `CONTRIBUTING.md` for guidelines.
 
 ## Publishing TEA to NPM
 
-TEA uses an automated release workflow that handles versioning, metadata sync, tagging, NPM publishing, and GitHub releases.
+TEA uses an automated publish workflow modeled after the main `BMAD-METHOD` repo. It supports:
+
+- `next` prereleases published automatically from `main`
+- manual stable releases on the `latest` dist-tag
+- trusted npm publishing (no `NPM_TOKEN` secret)
+- metadata sync for `package.json`, `package-lock.json`, and `.claude-plugin/marketplace.json`
 
 ### Prerequisites (One-Time Setup)
 
-1. **NPM Token Configuration:**
-   - Generate NPM automation token: [npmjs.com/settings/tokens](https://www.npmjs.com/settings/your-username/tokens)
-   - Add to GitHub Secrets: `Settings` → `Secrets and variables` → `Actions` → `New repository secret`
-   - Name: `NPM_TOKEN`
-   - Value: [your token]
+1. **npm Trusted Publishing:**
+   - In npm package settings for `bmad-method-test-architecture-enterprise`, configure Trusted Publishers for this GitHub repository
+   - Allow publishes from the `bmad-code-org/bmad-method-test-architecture-enterprise` repo and the `.github/workflows/publish.yaml` workflow
+   - GitHub Actions must be able to request an OIDC token (`id-token: write`), which the workflow already does
+
+2. **GitHub App Secrets for Stable Releases:**
+   - Add `RELEASE_APP_ID`
+   - Add `RELEASE_APP_PRIVATE_KEY`
+   - Install the corresponding GitHub App on this repository with contents write access
+   - If `main` is protected, ensure the app is allowed to push the release commit and tag
+   - These are used only for manual stable releases so the workflow can push the version bump commit and tag back to `main`
 
-2. **Verify Package Configuration:**
+3. **Verify Package Configuration:**
    ```bash
    # Check package.json settings
    cat package.json | grep -A 3 "publishConfig"
@@ -240,71 +253,61 @@ TEA uses an automated release workflow that handles versioning, metadata sync, t
 
 #### Option 1: Using npm Scripts (Recommended)
 
-From your local terminal after merging to the release branch you want to publish, typically `main`:
+From your local terminal after merging to `main`:
 
 ```bash
-# Beta release (first release or testing)
-npm run release:beta
-
-# Alpha release (early testing)
-npm run release:alpha
+# Publish the next prerelease from current main
+npm run release:next
 
-# Patch release (bug fixes)
+# Publish a stable patch release
 npm run release:patch
 
-# Minor release (new features, backwards compatible)
+# Publish a stable minor release
 npm run release:minor
 
-# Major release (breaking changes)
+# Publish a stable major release
 npm run release:major
 ```
 
 #### Option 2: Manual Workflow Trigger
 
 1. Go to **Actions** tab in GitHub
-2. Click **"Manual Release"** workflow
+2. Click **"Publish"** workflow
 3. Click **"Run workflow"**
 4. Choose the branch to release, typically `main`
-5. Select version bump type (alpha, beta, patch, minor, major)
-6. Click **"Run workflow"**
+5. Select channel:
+   - `next` for a prerelease publish
+   - `latest` for a stable release
+6. If using `latest`, choose the bump type (`patch`, `minor`, `major`)
+7. Click **"Run workflow"**
 
 ### What Happens Automatically
 
 The workflow performs these steps:
 
 1. ✅ **Validation**: Runs the full `npm test` suite, including schema checks, install tests, knowledge checks, linting, markdown linting, formatting, and release metadata validation
-2. ✅ **Version Bump**: Updates `package.json`, `package-lock.json`, and `.claude-plugin/marketplace.json`
-   - `beta`: 1.12.3 → 1.12.4-beta.0
-   - `alpha`: 1.12.3 → 1.12.4-alpha.0
-   - `patch`: 1.12.3 → 1.12.4
-   - `minor`: 1.12.3 → 1.13.0
-   - `major`: 1.12.3 → 2.0.0
-3. ✅ **Commit**: Creates version bump commit
-4. ✅ **Tag**: Creates git tag (e.g., v1.12.4-beta.0)
-5. ✅ **Publish**: Publishes to NPM registry
-   - Alpha → dist-tag `alpha` (`npm install bmad-method-test-architecture-enterprise@alpha`)
-   - Beta → dist-tag `beta` (`npm install bmad-method-test-architecture-enterprise@beta`)
-   - Stable → dist-tag `latest` (`npm install bmad-method-test-architecture-enterprise`)
-6. ✅ **Push**: Pushes the version bump commit back to the selected branch when permitted, and always pushes the tag
-7. ✅ **GitHub Release**: Creates release with auto-generated notes
-8. ✅ **Summary**: Displays installation instructions and distribution links
-
-### Version Bump Strategy
-
-**For TEA Module:**
-
-- **Beta (`1.12.x-beta.x`)**: Release candidate testing on the next patch line
-- **Alpha (`1.12.x-alpha.x`)**: Early development and experimental validation
-- **Patch (`1.12.x`)**: Bug fixes, no breaking changes
-- **Minor (`1.x.0`)**: New features, backwards compatible
-- **Major (`x.0.0`)**: Breaking changes
+2. ✅ **Version Bump**:
+   - `next`: derives the next prerelease version and publishes it with dist-tag `next`
+   - `latest`: bumps the stable version (`patch`, `minor`, or `major`)
+3. ✅ **Metadata Sync**: Updates `.claude-plugin/marketplace.json` to match the package version before publishing
+4. ✅ **Publish**: Publishes to npm with provenance enabled
+   - `next` → `npm publish --tag next --provenance`
+   - `latest` → `npm publish --tag latest --provenance`
+5. ✅ **Stable Release Finalization**: For `latest`, creates a version bump commit, tags it, pushes it to `main`, and creates a GitHub Release
+
+### Channel Strategy
+
+- **`next`**: prerelease channel for the newest merged changes
+- **`latest`**: stable channel for intentional releases
+- **`patch`**: bug fixes, no breaking changes
+- **`minor`**: new features, backwards compatible
+- **`major`**: breaking changes
 
 **Recommended Release Path:**
 
-1. `1.12.3` → `1.12.4-beta.0` (first beta)
-2. Test beta with early adopters
-3. `1.12.4-beta.0` → `1.12.4-beta.1` (fixes)
-4. When stable: `1.12.4-beta.1` → `1.12.4`
+1. Merge releasable work to `main`
+2. Let `next` publish for early validation
+3. When ready, cut a stable `latest` release via `patch`, `minor`, or `major`
 
 ### Verify Publication
 
@@ -312,6 +315,7 @@ The workflow performs these steps:
 
 ```bash
 npm view bmad-method-test-architecture-enterprise
+npm view bmad-method-test-architecture-enterprise dist-tags
 ```
 
 **Install TEA:**
@@ -335,24 +339,31 @@ If you need to unpublish a version:
 
 ```bash
 # Unpublish specific version (within 72 hours)
-npm unpublish bmad-method-test-architecture-enterprise@1.12.4-beta.0
+npm unpublish bmad-method-test-architecture-enterprise@1.13.2-next.0
 
 # Deprecate version (preferred for older releases)
-npm deprecate bmad-method-test-architecture-enterprise@1.12.4-beta.0 "Use version X.Y.Z instead"
+npm deprecate bmad-method-test-architecture-enterprise@1.13.2-next.0 "Use version X.Y.Z instead"
 ```
 
 ### Troubleshooting
 
-**"NPM_TOKEN not found":**
+**Trusted publishing failed:**
 
-- Verify secret is set: GitHub repo → Settings → Secrets and variables → Actions
-- Secret name must be exactly: `NPM_TOKEN`
+- Verify npm Trusted Publishing is configured for this repository and workflow
+- Verify the workflow has `id-token: write`
+- Confirm the publish is running from the canonical repository, not a fork
 
 **"Package already exists":**
 
 - Check if package name is already taken on NPM
 - Update `name` in `package.json` if needed
 
+**"Version push failed":**
+
+- Verify `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` are configured
+- Verify the GitHub App is installed on this repository with contents write access
+- If branch protection is enabled on `main`, verify the app is allowed to push the release commit and tag
+
 **"Tests failed":**
 
 - Fix failing tests before release
@@ -360,9 +371,9 @@ npm deprecate bmad-method-test-architecture-enterprise@1.12.4-beta.0 "Use versio
 
 **"Git push failed (protected branch)":**
 
-- This is expected for a protected release branch
-- The tag and version bump are still created
-- You may need to manually merge the version bump commit
+- This is not expected once the release GitHub App is configured correctly
+- Verify branch protection allows the app to push the release commit and tag
+- If needed, create the GitHub Release manually after resolving the app permissions
 
 ### Release Checklist
 
@@ -373,7 +384,8 @@ Before releasing:
 - [ ] CHANGELOG.md updated
 - [ ] No uncommitted changes
 - [ ] On `main` branch
-- [ ] NPM token configured in GitHub Secrets
+- [ ] npm Trusted Publishing configured
+- [ ] `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` configured
 - [ ] Package name available on NPM
 
 After releasing:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -33,11 +33,10 @@
     "lint:fix": "eslint . --fix",
     "lint:md": "markdownlint-cli2 '**/*.md'",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "release:alpha": "gh workflow run manual-release.yaml -f version_bump=alpha",
-    "release:beta": "gh workflow run manual-release.yaml -f version_bump=beta",
-    "release:major": "gh workflow run manual-release.yaml -f version_bump=major",
-    "release:minor": "gh workflow run manual-release.yaml -f version_bump=minor",
-    "release:patch": "gh workflow run manual-release.yaml -f version_bump=patch",
+    "release:major": "gh workflow run publish.yaml -f channel=latest -f bump=major",
+    "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:schemas && npm run test:install && npm run test:knowledge && npm run test:release-metadata && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 npm test",
     "test:install": "node test/test-installation-components.js",

package/src/agents/bmad-tea/resources/knowledge/contract-testing.md

@@ -167,7 +167,8 @@ describe('User API Contract', () => {
 ```json
 {
   "scripts": {
-    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "test:pact:consumer": "./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts",
+    "test:pact:consumer:run": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
   }
 }
@@ -1024,7 +1025,7 @@ Before implementing contract testing, verify:
 ## Integration Points
 
 - Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
-- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md` (consumer vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true`), `pactjs-utils-consumer-helpers.md` (PactV4 one-interaction-per-`it()` rule), `pactjs-utils-provider-verifier.md` (provider vitest `pool: 'forks'` + `singleFork: true` — same rule as consumer), `pact-broker-webhooks.md` (PactFlow → GitHub webhook auth, PAT rotation, staleness monitoring)
 - Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
 
 ---
@@ -1033,18 +1034,34 @@ Before implementing contract testing, verify:
 
 When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
 
-| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
-| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
-| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
-| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
-| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
-| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
-| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
-| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
-| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
-
-See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                                                                    |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                                                     |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)`                                      |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                                                          |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                                                             |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                                                     |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                                                         |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                                                                 |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                                                            |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                                                               |
+| Hand-written matcher helper duplicating a Zod/TS type    | `zodToPactMatchers(ConsumerMovieSchema, example)`                                 | Single source of truth for response shape; consumer-curated scope keeps contracts lean and consumer-driven |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns (`pactjs-utils-zod-to-pact.md` covers the consumer-curated schema pattern).
+
+### PactV4 Determinism & FFI Safety (Mandatory)
+
+Four rules that together prevent both (a) non-deterministic pact generation failures that cause `Cannot change pact content for already published pact` errors at PactFlow publish, and (b) "request was expected but not received" flakes observed on Linux CI once a consumer+provider pair has more than one `.pacttest.ts` file:
+
+1. **Consumer Vitest `fileParallelism: false`** in `vitest.config.pact.ts` — prevents parallel workers from racing on the shared pact JSON. See `pact-consumer-framework-setup.md` Example 2.
+2. **Consumer Vitest `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.pact.ts` — same config as the provider side (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; serialization alone (via `fileParallelism: false`) is insufficient on the default threads pool in Vitest v1. Forks + `singleFork: true` runs every pact file in one subprocess with a coherent FFI handle and eliminated a reproducible Linux-CI flake on two repos (`pactjs-utils`, `seon-mcp-server`). Single-file consumer suites have not been observed to flake; this rule is still recommended as a future-proof. See `pact-consumer-framework-setup.md` Example 2.
+3. **One `addInteraction()` per `it()` block** — see `pactjs-utils-consumer-helpers.md` Example 6.
+4. **Determinism gate** runs the consumer suite N times and fails on byte-different pact JSON before publish — see `pact-consumer-framework-setup.md` Example 10 (`scripts/check-pact-determinism.sh`).
+
+Provider suites require the same `pool: 'forks'` + `singleFork: true` combination — see `pactjs-utils-provider-verifier.md` Example 7.
+
+### Webhook Auth & Staleness
+
+When `can-i-deploy` in a consumer repo times out with `There is no verified pact between <consumer> and the version of <provider> currently in <env>` — check the provider's PactFlow webhook. Silent failures from an expired/revoked GitHub PAT are the most common non-code cause of this symptom. See `pact-broker-webhooks.md` for the dedicated-machine-user pattern, classic-PAT-with-`repo`-scope rationale, rotation runbook, and staleness monitoring options.
 
 _Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_