bmad-method-test-architecture-enterprise 1.19.2-next.0 → 1.20.0

package/.claude-plugin/marketplace.json

@@ -6,21 +6,13 @@
   "license": "MIT",
   "homepage": "https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise",
   "repository": "https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise",
-  "keywords": [
-    "bmad",
-    "test-architect",
-    "testing",
-    "quality",
-    "automation",
-    "playwright",
-    "test-engineering"
-  ],
+  "keywords": ["bmad", "test-architect", "testing", "quality", "automation", "playwright", "test-engineering"],
   "plugins": [
     {
       "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.19.2-next.0",
+      "version": "1.20.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/.github/workflows/publish.yaml

@@ -76,7 +76,7 @@ jobs:
         run: npm ci
 
       - name: Run tests
-        run: npm test
+        run: npm test && npm run test:cli
 
       - name: Derive next prerelease version
         if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'next')

package/.github/workflows/quality.yaml

@@ -115,3 +115,6 @@ jobs:
 
       - name: Test agent compilation components
         run: npm run test:install
+
+      - name: Test TEA test-review CLI
+        run: npm run test:cli

package/.github/workflows/tea-test-review.yaml

@@ -0,0 +1,228 @@
+# Dogfoods tea-test-review on this repo's own test suite (test/*.js). Unlike
+# cli/examples/pr-test-review.yml, this repo IS the skill source, so it points
+# --skill-root at src/workflows/testarch/bmad-testarch-test-review directly
+# instead of installing a pinned npm tarball.
+#
+# NOT YET ENABLED: no ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repository
+# secret exists yet, so the agent-running steps below are commented out and
+# the trigger is workflow_dispatch only, not pull_request. A run without
+# either secret would just fail and post a confusing "infrastructure failure"
+# comment on every real PR.
+#
+# To enable: add one of the two secrets, uncomment the "Install the pinned
+# agent CLI" and "Run headless test review" steps, and switch `on:` back to
+# `pull_request: { types: [opened, synchronize, reopened] }`.
+#   - ANTHROPIC_API_KEY: pay-per-token via the Anthropic Console.
+#   - CLAUDE_CODE_OAUTH_TOKEN: a long-lived token from an existing Claude
+#     subscription, generated locally with `claude setup-token`. No separate
+#     API billing. Already supported by cli/lib/run-agent.js's env allowlist.
+#
+# Honest limitation: forks receive no secrets, so the review skips for fork
+# PRs (the fork guard below) rather than failing. A skipped required check
+# still satisfies branch protection, so this cannot be the sole gate against
+# untrusted external contributions; see cli/examples/pr-test-review.yml's
+# header comment for the same caveat.
+name: TEA Test Review
+
+on:
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  review:
+    name: Headless test review
+    runs-on: ubuntu-latest
+    # Self-adapting fork guard: on workflow_dispatch there's no pull_request
+    # context to check, so this is trivially true; on pull_request it skips
+    # forks (no secrets there). No change needed when switching triggers back.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+    outputs:
+      verdict: ${{ steps.verdict.outputs.verdict }}
+    steps:
+      - name: Checkout (full history for the PR diff)
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      # - name: Install the pinned agent CLI
+      #   env:
+      #     CLAUDE_CODE_VERSION: 2.1.220
+      #   run: npm install --global "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+
+      # - name: Run headless test review
+      #   id: run-review
+      #   env:
+      #     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      #     # or: CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      #     BASE_REF: origin/${{ github.base_ref }}
+      #   run: node cli/test-review.js --base "$BASE_REF" --agent claude --skill-root src/workflows/testarch/bmad-testarch-test-review --test-dir test --output test-review.md --json test-review.json
+
+      - name: Upload review artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tea-test-review
+          path: |
+            test-review.md
+            test-review.json
+
+      - name: Export the verdict as a job output
+        id: verdict
+        if: always()
+        env:
+          REVIEW_OUTCOME: ${{ steps.run-review.outcome }}
+        run: |
+          verdict="failed"
+          if [ "$REVIEW_OUTCOME" = "success" ]; then
+            verdict="passed"
+          fi
+          echo "verdict=$verdict" >> "$GITHUB_OUTPUT"
+
+  comment:
+    name: Comment the outcome
+    needs: review
+    # Only meaningful with a PR to comment on; skips cleanly on workflow_dispatch.
+    if: always() && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Download review artifacts
+        id: download
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+        with:
+          name: tea-test-review
+
+      - name: Find-and-update the review comment
+        uses: actions/github-script@v7
+        env:
+          DOWNLOAD_OUTCOME: ${{ steps.download.outcome }}
+          REVIEW_RESULT: ${{ needs.review.result }}
+          REVIEW_VERDICT: ${{ needs.review.outputs.verdict }}
+        with:
+          # Kept in sync by hand with cli/examples/pr-test-review.yml's
+          # "Find-and-update the review comment" step: same comment-building
+          # logic, duplicated because that file is a standalone copy-paste
+          # template for other repos and cannot depend on this one.
+          script: |
+            const fs = require("fs");
+            const marker = "<!-- tea-test-review -->";
+            const artifactsUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}#artifacts`;
+            // GitHub caps a comment body at 65536 chars; this leaves headroom
+            // for the digest and wrapper around the inlined report.
+            const MAX_INLINE_REPORT_CHARS = 40000;
+
+            let body = null;
+            const artifactAvailable = process.env.DOWNLOAD_OUTCOME === "success" && fs.existsSync("test-review.json");
+            if (artifactAvailable) {
+              try {
+                const verdict = JSON.parse(fs.readFileSync("test-review.json", "utf8"));
+                if (verdict.skipped) {
+                  body = [
+                    marker,
+                    "## TEA Test Review: skipped",
+                    "",
+                    `${verdict.reason ?? "No changed test files in this PR"}.`,
+                    "",
+                    `[Review job artifacts](${artifactsUrl})`,
+                  ].join("\n");
+                } else {
+                  const counts = verdict.violations ?? {};
+                  const violations = `${counts.critical ?? 0} Critical / ${counts.high ?? 0} High / ${counts.medium ?? 0} Medium / ${counts.low ?? 0} Low`;
+                  const weaknesses = (verdict.keyWeaknesses ?? []).slice(0, 3);
+
+                  const lines = [
+                    marker,
+                    `## TEA Test Review: ${verdict.recommendation}`,
+                    "",
+                    `- **Quality score**: ${verdict.qualityScore ?? "n/a"}/100`,
+                    `- **Recommendation**: ${verdict.recommendation}`,
+                    `- **Violations**: ${violations}`,
+                    `- **Reviewed files**: ${(verdict.reviewedFiles ?? []).length}`,
+                  ];
+                  if (weaknesses.length > 0) {
+                    lines.push("", "**Key weaknesses**:", ...weaknesses.map((w) => `- ${w}`));
+                  }
+                  lines.push("");
+
+                  // Inline the full report (not just the digest above) so a
+                  // reviewer can paste it straight into an AI coding agent to
+                  // apply the fixes, no artifact download required. Falls back
+                  // to the artifact link alone if the report is too large or
+                  // missing from the download.
+                  const reportText = fs.existsSync("test-review.md") ? fs.readFileSync("test-review.md", "utf8") : null;
+                  if (reportText && reportText.length <= MAX_INLINE_REPORT_CHARS) {
+                    // A reviewed file's own content can contain a literal
+                    // </details>; inserting a zero-width space breaks that as
+                    // an HTML closing tag while leaving the visible text
+                    // effectively unchanged, so it cannot end this block early
+                    // and spill raw markdown into the rest of the comment.
+                    const safeReportText = reportText.replace(/<\/details>/gi, "<\u200B/details>");
+                    lines.push(
+                      "<details>",
+                      "<summary>Full report (paste into your AI coding agent to apply the fixes)</summary>",
+                      "",
+                      safeReportText,
+                      "",
+                      "</details>",
+                      "",
+                      `[Verdict JSON](${artifactsUrl})`,
+                    );
+                  } else {
+                    lines.push(`[Full report and verdict JSON](${artifactsUrl})`);
+                  }
+                  body = lines.join("\n");
+                }
+              } catch {
+                body = null;
+              }
+            }
+            if (body === null) {
+              body = [
+                marker,
+                "## TEA Test Review: infrastructure failure",
+                "",
+                "The review job did not produce a readable verdict artifact.",
+                "This is **not** a review verdict; treat the gate as broken, not as approved tests.",
+                "",
+                `Review job result: ${process.env.REVIEW_RESULT} (verdict output: ${process.env.REVIEW_VERDICT || "n/a"}).`,
+                `[Review job artifacts](${artifactsUrl})`,
+              ].join("\n");
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

package/CHANGELOG.md

@@ -7,8 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New `tea-test-review` CLI (`bin` entry) — headless runner for the `bmad-testarch-test-review` skill: changed-test scoping from the PR diff (`--base`, or an explicit `--files` list), prompt-only mode (`--agent none`), JSON verdict (`--json`), and CI exit codes (`--fail-on request-changes|block`). Hardened for required-gate use: stdin-delivered prompt, filesystem isolation (`--isolate`, on by default in CI, `--no-isolate` to opt out), extra test-file matchers (`--test-glob`), a quality-score floor (`--min-score`), non-pass on skips (`--fail-on-skip`) and deletions-only diffs, and strict report validation (dual-section Recommendation, bounded score, violations line, frontmatter, and a `## Reviewed Files` manifest). Ships with `cli/examples/pr-test-review.yml`, a two-job (review + comment) starting template for a required test-review gate, plus `cli/examples/README.md` covering two real adaptations: a central reusable-workflows repo, and a repo already running a third-party review bot.
+- `tea-test-review` is no longer Claude-only: `--agent` resolves against a per-vendor adapter table (`cli/lib/agent-adapters.js`) instead of hardcoding `claude -p`'s argv at every call site `--agent-cmd` could override. `--agent codex` spawns `codex exec --sandbox workspace-write`, live-verified with a real review against a real Playwright spec (`codex-cli` 0.146.0) whose report `parseReport()` accepted; that run wrote Key Strengths/Weaknesses as plain bullets instead of the `✅`/`❌`-prefixed form claude reliably produces, which the existing best-effort extraction already tolerates by design (`plain-bullets-key-strengths.md` fixture). A drafted `--agent gemini` adapter was not shipped: this account's `gemini` CLI OAuth login is on a deprecated Code Assist tier with no fallback API key configured, so it was never verified end-to-end.
+- Deterministic TEA config in headless runs: `tea-test-review` now resolves `tea_use_playwright_utils`, `tea_use_pactjs_utils`, and `tea_pact_mcp` through an explicit precedence chain (new `--use-playwright-utils` / `--no-use-playwright-utils`, `--use-pactjs-utils` / `--no-use-pactjs-utils`, and `--pact-mcp <mcp|none>` flags, then the project's `_bmad/tea/config.yaml`, then the `src/module.yaml` default) and states all of them in the prompt. `steps-c/step-01-load-context.md` branches on these keys to pick its knowledge fragments, and CI installs the skill from a tarball without running the installer, so `config.yaml` is typically absent: previously the three keys were unstated and the agent settled them per run, meaning two runs over identical files could review against different knowledge, and a contract-testing repository could load `contract-testing.md` instead of the six `pactjs-utils-*` and `pact-*` fragments. Unusable config content is an environment error (exit 2); a missing file is not. The CLI's copy of the module defaults is asserted equal to `src/module.yaml` in the test suite so the two cannot drift.
+- Gate semantics for the CLI: `--waive <reason>` with mandatory `--waive-until <YYYY-MM-DD>` expiry (verdict-fails waivable, environment/agent/parse failures never), `--min-files <n>` minimum-evidence floor, `--max-critical <n>` violation cap, inconsistent-verdict rejection (Critical violations with an Approve recommendation fail parsing), and `--skill-root <path>` for an explicit trusted skill source outside the PR checkout.
+- First-class headless contract in the `test-review` workflow: new `headless`, `review_files`, `output_file_override`, and `generate_inline_comments` inputs (`workflow.yaml`, `customize.toml`), a Headless mode section in `SKILL.md`, and `review_files` as an authoritative file-set source in the discovery step, so headless runs no longer depend on prompt prose overriding the interactive flow.
+- Docs: new `tea-test-review` CLI reference page (`docs/reference/tea-test-review-cli.md`) covering flags, exit codes, the JSON verdict schema, the skill prerequisite, and the security model. `test/README.md` now covers every suite and the `fixtures/test-review-cli/` layout, and drops a stale reference to a `test-cli-integration.sh` that no longer exists.
+- Docs: new explanation page `docs/explanation/test-review-cli-architecture.md` on how an interactive skill is wrapped into a headless CI gate — the five modules and the pipeline order, how a workflow is made headless without discarding its customization chain, why the prompt contract and the report parser must be edited together (a strict check absent from the prompt is a false failure, not a gate), why exit 1 is separated from exits 2 and 3, why the CLI must version with the skill, and what the fixture suite can and cannot prove.
+- Docs: the CLI reference now states that the reviewed repository never has to commit BMAD files, add a dependency, or install the TEA module. The skill only has to be present in the workspace when the CLI runs, which CI does as a build step from a pinned tarball. The previous "Installed in the consuming project" wording read as a repository prerequisite.
+
 ### Changed
 
+- Removed `test:cli` from the default `npm test` script (and Husky pre-commit hook) to keep local git hooks fast, running `test:cli` as part of CI validation in `quality.yaml` and `publish.yaml`.
+- `test-review` now has a single scoring model. The deduction ledger printed in `test-review-template.md` (Critical -10, High -5, Medium -2, Low -1, plus six bonus categories worth 0 or 5 each) is authoritative, and `steps-c/step-03f-aggregate-scores.md` no longer computes a competing weighted average of the four quality dimensions. Grades are limited to A/B/C/D/F. Two live runs over an identical file set had returned 83 and 92 under the old ambiguity, one of them printing a breakdown that did not sum to its own total.
+- `tea-test-review` recomputes the ledger from the report's own violation counts and rejects a report whose published score contradicts its breakdown, whose bonus total is not a multiple of 5 within 0-30, or that omits the `## Quality Score Breakdown` section. The prompt states the same arithmetic, so the strict check never demands a shape the reviewer was not told to produce.
+- `tea-test-review` no longer forbids the scratch files the skill itself requires: the prompt permits the `/tmp/tea-test-review-*.json` outputs that `steps-c/step-03*` write and that `step-03` aborts without, while still forbidding every other write, including the test files under review.
+- `output_file_override` is now honored where reports are actually written. Each step that resolves `{outputFile}` states that a non-empty override replaces the frontmatter default, so the input works for native skill runs and not only through the CLI prompt.
 - NFR workflow boundary clarified: `test-design` now owns NFR planning (thresholds, planned evidence, NFR-derived risks) and `nfr-assess` is reframed as NFR Evidence Audit — evaluating implementation evidence against planned thresholds after code exists.
 - `nfr-assess` step-02 now checks for an existing `test-design` NFR plan first and uses it as the primary threshold source, falling back to raw documents only for missing or UNKNOWN thresholds.
 - TEA agent menu gains a `GATE` routing intent that guides users through the release gate sequence (optional test-review → optional nfr-assess → trace Phase 2 gate) without merging those workflows.
@@ -23,6 +39,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Publish releases now use `[Unreleased]` changelog notes before falling back to generated GitHub release notes when an exact version section is missing.
 - Documented workflow-local knowledge resources as intentional self-contained skill packaging and added validation for workflow-local knowledge indexes.
 
+### Fixed
+
+- Normalized the `test-review` checklist's Recommendation vocabulary to the canonical four-value enum (`checklist.md`).
+- `test-review` score aggregation now emits a CRITICAL severity tier (`step-03f`), mapped to the report's `Critical Issues (Must Fix)` section, matching the template's four-tier violations line; `generate_inline_comments` is now a defined workflow input (default `false`) instead of an unresolved reference in the checklist.
+- `test-review` reports now carry a machine-readable `## Reviewed Files` manifest section in `test-review-template.md`, and every step's first-save frontmatter snippet declares `workflowType: 'testarch-test-review'`. A report produced from the template alone now satisfies the headless verdict schema, so a clean review can no longer be reported as a parse failure when the agent follows the template rather than prompt prose.
+- `tea-test-review` isolation and agent environment corrections: artifacts written directly to the project root are copied back under the chmod isolation fallback (previously `EACCES`, surfacing a clean review as exit 3), the macOS sandbox profile permits the `/tmp` subagent output files the workflow's own step contract requires, and the minimal agent environment keeps `USER`, `LOGNAME`, and `CLAUDE_CODE_OAUTH_TOKEN` so a subscription or token login stays authenticated.
+- `tea-test-review` chmod isolation now restores the project tree's exact permission bits from a snapshot taken before the lock. The previous `chmod -R u+w` restore is not an inverse of `chmod -R a-w`: it stripped group and other write bits and left deliberately read-only files writable.
+- `tea-test-review` reviewed-files manifest ignores prose lines and strips inline markup, so a sentence inside the report's `## Reviewed Files` section can no longer inflate the `--min-files` evidence floor; a section with no file paths is a parse failure rather than a pass.
+- `tea-test-review` no longer false-fails a valid report whose `stepsCompleted` frontmatter is a YAML flow sequence wrapped across several lines, which is the shape a formatter produces once the list outgrows one line. A live run produced an otherwise complete 742-line report and the CLI rejected it with exit 3.
+
 ---
 
 ## [1.16.0] - 2026-05-08

package/cli/examples/README.md

@@ -0,0 +1,53 @@
+# CLI examples
+
+`pr-test-review.yml` is the full annotated template, start there. These two cover real adaptations.
+
+## A central reusable-workflows repo
+
+Some orgs centralize CI logic: one repo owns `workflow_call` workflows, consuming repos call them. If that repo already has a comment-triggered `@claude` reviewer (opt-in, advisory, fired from `issue_comment`), don't graft TEA onto it. TEA needs to run on every PR automatically and gate merges, a different job than an on-demand advisory review. Add it as its own pair, same shape as whatever pattern you already use:
+
+- **Reusable workflow** (central repo, e.g. `rwf-tea-test-review.yml`): copy the `review` and `comment` jobs from `pr-test-review.yml` into a `workflow_call` workflow. Promote `--min-score`, `--max-critical`, `--min-files`, and the pinned `TEA_VERSION` to `inputs:`, and the Anthropic key to a required secret.
+- **Caller** (each consuming repo, or the central repo itself for dogfooding): a thin `pull_request`-triggered workflow that does `uses: <org>/<central-repo>/.github/workflows/rwf-tea-test-review.yml@<ref>`.
+
+Keep the trigger on `pull_request`. That's what makes it a required check: it runs automatically, no one has to remember to summon it.
+
+```yaml
+# rwf-tea-test-review.yml (central repo): only what differs from pr-test-review.yml
+on:
+  workflow_call:
+    inputs:
+      min_score: { type: number, required: false, default: 80 }
+    secrets:
+      anthropic_api_key:
+        required: true
+jobs:
+  review:
+    # ...same steps as pr-test-review.yml's `review` job...
+    run: tea-test-review --base "$BASE_REF" --min-score ${{ inputs.min_score }} --agent claude --skill-root "$GITHUB_WORKSPACE/_bmad/tea/workflows/testarch/bmad-testarch-test-review" --output test-review.md --json test-review.json
+```
+
+```yaml
+# .github/workflows/tea-test-review.yml (caller, per consuming repo)
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  tea-test-review:
+    uses: <org>/<central-repo>/.github/workflows/rwf-tea-test-review.yml@v1
+    with:
+      min_score: 80
+    secrets:
+      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## A repo already using a third-party review bot (CodeRabbit, etc.)
+
+Third-party review bots are configured entirely through their own SaaS-side file, there's no hook in there for invoking an external CLI. Leave that file alone. Add a new, independent `pull_request`-triggered workflow (same shape as `pr-test-review.yml`) next to it.
+
+The two don't compete. Check whether the bot's config sets a required commit status or a request-changes gate. If it doesn't (most default/free configs are advisory-only, commenting on the diff without blocking merges), TEA test-review can be the actual required check that config deliberately leaves open, scoped specifically to test quality rather than the whole diff.
+
+Adjust flags to your layout, for example a monorepo with tests outside the default directory:
+
+```yaml
+run: tea-test-review --base "$BASE_REF" --test-dir playwright --min-score 80 --agent claude --skill-root "$GITHUB_WORKSPACE/_bmad/tea/workflows/testarch/bmad-testarch-test-review" --output test-review.md --json test-review.json
+```

package/cli/examples/pr-test-review.yml

@@ -0,0 +1,279 @@
+# tea-test-review — a starting template for a required test-review gate.
+#
+# Two jobs: `review` runs the headless TEA test review against the PR's
+# changed test files and uploads the report artifacts; `comment` publishes the
+# outcome as a single upserted PR comment. Make the `review` job a required
+# status check to gate merges on the review verdict.
+#
+# Prerequisites:
+#   - An ANTHROPIC_API_KEY repository secret (this template's review step uses
+#     --agent claude, executed by the claude CLI installed below). --agent
+#     codex is also supported (OPENAI_API_KEY instead) — see the --agent flag
+#     in docs/reference/tea-test-review-cli.md and swap the installed package
+#     and secret accordingly.
+#   - A vetted version of the bmad-method-test-architecture-enterprise npm
+#     package, pinned exactly (see TEA_VERSION below).
+#
+# Honest limitations — read before requiring this check:
+#   - This workflow cannot be the sole required check for repositories that
+#     accept fork pull requests: forks receive no secrets by design, so the
+#     fork guard below skips the review for them and the gate never runs.
+#     Fork coverage needs a separate privileged design (for example a
+#     pull_request_target workflow with strict controls), which is out of
+#     scope for this template.
+#   - The review skill is installed from the pinned npm package below, not
+#     from the PR checkout, and the run step pins it explicitly with
+#     --skill-root — the CLI never probes the PR checkout for the reviewer,
+#     closing the vendored-checkout trust gap for this shipped path. The
+#     residual trust assumption: you are trusting the pinned version as
+#     published on the npm registry — vet that version once, pin it exactly,
+#     and bump the pin deliberately.
+#
+# Gate-policy flags (all optional; tune to your gate policy):
+#   --min-score <n>            fail below a quality-score floor (0-100); tune to your gate policy
+#   --max-critical <n>         fail above a Critical-violation cap (default: no cap); tune to your gate policy
+#   --min-files <n>            fail when fewer than n files were reviewed (default 1); tune to your gate policy
+#   --waive/--waive-until      record a time-boxed waiver: any verdict failure exits 0 with a WAIVED
+#                              banner and waived fields in the JSON (exit 2/3 are never waivable);
+#                              tune to your gate policy
+name: TEA Test Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+# Default deny; each job grants exactly the permissions it needs.
+permissions: {}
+
+jobs:
+  review:
+    name: Headless test review
+    runs-on: ubuntu-latest
+    # Forks receive no secrets, so the review cannot run for them; skip
+    # honestly instead of failing (see the header comment).
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+    outputs:
+      verdict: ${{ steps.verdict.outputs.verdict }}
+    env:
+      # Single source of truth for both install steps below, so bumping the
+      # pin can't update one and silently leave the other on the old version.
+      TEA_VERSION: 1.19.1
+    steps:
+      - name: Checkout (full history for the PR diff)
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          # The review only reads the tree; never hand the PR checkout a
+          # credentials-bearing git config.
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Install the review skill from the pinned package
+        # Deterministic, non-interactive install: the skill content the CLI
+        # discovers under _bmad/ comes from the vetted package tarball, never
+        # from the PR checkout.
+        run: |
+          npm pack "bmad-method-test-architecture-enterprise@${TEA_VERSION}"
+          tar -xzf "bmad-method-test-architecture-enterprise-${TEA_VERSION}.tgz"
+          mkdir -p _bmad/tea/workflows/testarch
+          cp -R package/src/workflows/testarch/bmad-testarch-test-review _bmad/tea/workflows/testarch/bmad-testarch-test-review
+
+      - name: Install the pinned CLI and agent
+        env:
+          # Both pinned: the reviewer's control plane must be the exact code
+          # you vetted, not whatever `latest` resolves to when a PR lands.
+          CLAUDE_CODE_VERSION: 2.1.220
+        run: npm install --global "bmad-method-test-architecture-enterprise@${TEA_VERSION}" "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+
+      - name: Run headless test review
+        id: run-review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          BASE_REF: origin/${{ github.base_ref }}
+        # No ${{ }} expansion inside run text: the base ref arrives via the
+        # environment so a crafted branch name cannot inject shell.
+        # --skill-root pins the reviewer to the pinned npm copy installed
+        # above: the CLI skips probing the PR checkout for the skill, so a PR
+        # that edits its own vendored _bmad/ copy cannot rewrite the reviewer.
+        #
+        # TEA config: this job installs the skill from a tarball rather than
+        # running the interactive installer, so _bmad/tea/config.yaml does not
+        # exist and the module defaults apply (Playwright Utils on, Pact off,
+        # no Pact MCP). Those defaults are stated in the prompt, so the run is
+        # deterministic either way. If this repository uses contract testing,
+        # say so or the review loads the generic contract-testing fragment
+        # instead of the pactjs-utils set:
+        #   --use-pactjs-utils [--pact-mcp mcp]
+        # Committing _bmad/tea/config.yaml works too; the flags win over it.
+        run: tea-test-review --base "$BASE_REF" --agent claude --skill-root "$GITHUB_WORKSPACE/_bmad/tea/workflows/testarch/bmad-testarch-test-review" --output test-review.md --json test-review.json
+
+      - name: Upload review artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tea-test-review
+          path: |
+            test-review.md
+            test-review.json
+
+      - name: Export the verdict as a job output
+        id: verdict
+        if: always()
+        env:
+          # The CLI exit code is the verdict (it already folds in --fail-on,
+          # --min-score and deletions-only handling), so the step outcome is
+          # the faithful pass/fail signal; the JSON carries the detail.
+          REVIEW_OUTCOME: ${{ steps.run-review.outcome }}
+        run: |
+          verdict="failed"
+          if [ "$REVIEW_OUTCOME" = "success" ]; then
+            verdict="passed"
+          fi
+          echo "verdict=$verdict" >> "$GITHUB_OUTPUT"
+
+  comment:
+    name: Comment the outcome
+    needs: review
+    # Always run after the review (success or failure) so a failed review is
+    # still reported; never run for forks (nothing was reviewed there).
+    if: always() && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      # No PR checkout and no ANTHROPIC_API_KEY in this job: it only reads
+      # the uploaded artifacts and writes a PR comment.
+      - name: Download review artifacts
+        id: download
+        uses: actions/download-artifact@v4
+        # A missing artifact is reported below as an infrastructure failure,
+        # not raised as a step failure.
+        continue-on-error: true
+        with:
+          name: tea-test-review
+
+      - name: Find-and-update the review comment
+        uses: actions/github-script@v7
+        env:
+          DOWNLOAD_OUTCOME: ${{ steps.download.outcome }}
+          REVIEW_RESULT: ${{ needs.review.result }}
+          REVIEW_VERDICT: ${{ needs.review.outputs.verdict }}
+        with:
+          # Kept in sync by hand with .github/workflows/tea-test-review.yaml's
+          # "Find-and-update the review comment" step: same comment-building
+          # logic, duplicated because this file is a standalone copy-paste
+          # template for other repos and cannot depend on that one.
+          script: |
+            const fs = require("fs");
+            const marker = "<!-- tea-test-review -->";
+            const artifactsUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}#artifacts`;
+            // GitHub caps a comment body at 65536 chars; this leaves headroom
+            // for the digest and wrapper around the inlined report.
+            const MAX_INLINE_REPORT_CHARS = 40000;
+
+            let body = null;
+            const artifactAvailable = process.env.DOWNLOAD_OUTCOME === "success" && fs.existsSync("test-review.json");
+            if (artifactAvailable) {
+              try {
+                const verdict = JSON.parse(fs.readFileSync("test-review.json", "utf8"));
+                if (verdict.skipped) {
+                  body = [
+                    marker,
+                    "## TEA Test Review: skipped",
+                    "",
+                    `${verdict.reason ?? "No changed test files in this PR"}.`,
+                    "",
+                    `[Review job artifacts](${artifactsUrl})`,
+                  ].join("\n");
+                } else {
+                  const counts = verdict.violations ?? {};
+                  const violations = `${counts.critical ?? 0} Critical / ${counts.high ?? 0} High / ${counts.medium ?? 0} Medium / ${counts.low ?? 0} Low`;
+                  const weaknesses = (verdict.keyWeaknesses ?? []).slice(0, 3);
+
+                  const lines = [
+                    marker,
+                    `## TEA Test Review: ${verdict.recommendation}`,
+                    "",
+                    `- **Quality score**: ${verdict.qualityScore ?? "n/a"}/100`,
+                    `- **Recommendation**: ${verdict.recommendation}`,
+                    `- **Violations**: ${violations}`,
+                    `- **Reviewed files**: ${(verdict.reviewedFiles ?? []).length}`,
+                  ];
+                  if (weaknesses.length > 0) {
+                    lines.push("", "**Key weaknesses**:", ...weaknesses.map((w) => `- ${w}`));
+                  }
+                  lines.push("");
+
+                  // Inline the full report (not just the digest above) so a
+                  // reviewer can paste it straight into an AI coding agent to
+                  // apply the fixes, no artifact download required. Falls back
+                  // to the artifact link alone if the report is too large or
+                  // missing from the download.
+                  const reportText = fs.existsSync("test-review.md") ? fs.readFileSync("test-review.md", "utf8") : null;
+                  if (reportText && reportText.length <= MAX_INLINE_REPORT_CHARS) {
+                    // A reviewed file's own content can contain a literal
+                    // </details>; inserting a zero-width space breaks that as
+                    // an HTML closing tag while leaving the visible text
+                    // effectively unchanged, so it cannot end this block early
+                    // and spill raw markdown into the rest of the comment.
+                    const safeReportText = reportText.replace(/<\/details>/gi, "<\u200B/details>");
+                    lines.push(
+                      "<details>",
+                      "<summary>Full report (paste into your AI coding agent to apply the fixes)</summary>",
+                      "",
+                      safeReportText,
+                      "",
+                      "</details>",
+                      "",
+                      `[Verdict JSON](${artifactsUrl})`,
+                    );
+                  } else {
+                    lines.push(`[Full report and verdict JSON](${artifactsUrl})`);
+                  }
+                  body = lines.join("\n");
+                }
+              } catch {
+                body = null;
+              }
+            }
+            if (body === null) {
+              body = [
+                marker,
+                "## TEA Test Review: infrastructure failure",
+                "",
+                "The review job did not produce a readable verdict artifact.",
+                "This is **not** a review verdict — treat the gate as broken, not as approved tests.",
+                "",
+                `Review job result: ${process.env.REVIEW_RESULT} (verdict output: ${process.env.REVIEW_VERDICT || "n/a"}).`,
+                `[Review job artifacts](${artifactsUrl})`,
+              ].join("\n");
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }