bmad-method-test-architecture-enterprise 1.21.0 → 1.21.2

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

package/cli/lib/agent-adapters.js

@@ -109,7 +109,7 @@ function modelFromArgs(flags, extra = []) {
 }
 
 /**
- * Model argv for an adapter, suppressed when the --claude-arg passthrough
+ * Model argv for an adapter, suppressed when the --agent-arg passthrough
  * already sets the model itself.
  *
  * The suppression is not politeness, it is required for codex: clap rejects a
@@ -171,7 +171,7 @@ const AGENT_ADAPTERS = {
     // on a one-word prompt, measured 2026-08-03), but it is codex-only, so
     // pinning it in this vendor-agnostic table would give the flag a meaning
     // no other adapter can honor. Set it per run with
-    // --claude-arg -c --claude-arg model_reasoning_effort=low.
+    // --agent-arg -c --agent-arg model_reasoning_effort=low.
     buildArgv: (extra = [], model) => [
       'exec',
       '--skip-git-repo-check',

package/cli/lib/parse-report.js

@@ -4,9 +4,10 @@
  * Strict, section-aware schema (every element is mandatory):
  * - YAML frontmatter declaring workflowType: testarch-test-review and a
  *   non-empty stepsCompleted list.
- * - A "**Recommendation**:" line in BOTH the "## Executive Summary" and the
- *   "## Decision" section; the two must agree (case-insensitively) and the
- *   value must be one of the legal enum, to which it is normalized.
+ * - A "Recommendation:" line, with or without Markdown bolding, in BOTH the
+ *   "## Executive Summary" and the "## Decision" section; the two must agree
+ *   (case-insensitively) and the value must be one of the legal enum, to which
+ *   it is normalized.
  * - "**Quality Score**: N/100" with N an integer in 0-100.
  * - A "**Total Violations**:" line with all four severity counts.
  * - A "## Quality Score Breakdown" ledger whose arithmetic reproduces the
@@ -41,7 +42,7 @@
 const path = require('node:path');
 
 const RECOMMENDATION_ENUM = ['Approve', 'Approve with Comments', 'Request Changes', 'Block'];
-const RECOMMENDATION_LINE = /\*\*Recommendation:?\*\*:?[ \t]*([^\n]+)/;
+const RECOMMENDATION_LINE = /^[ \t]*(?:\*\*Recommendation\*\*:|\*\*Recommendation:\*\*|Recommendation:)[ \t]*([^\r\n]+?)[ \t]*$/m;
 const CONTEXT_BASIS_ENUM = ['none', 'pr_diff', 'pr_diff_truncated'];
 const CONTEXT_BASIS_LINE_SOURCE = String.raw`^[ \t]*\*\*Context Basis:?\*\*:?[ \t]*([^\r\n]+)[ \t]*$`;
 const CONTEXT_WAIVERS_LINE_SOURCE = String.raw`^[ \t]*\*\*Context Waivers Applied:?\*\*:?[ \t]*([^\r\n]+)[ \t]*$`;
@@ -148,7 +149,7 @@ function recommendationFromSection(text, heading) {
   }
   const match = section.match(RECOMMENDATION_LINE);
   if (!match) {
-    unparseable(`Report is missing the "**Recommendation**:" line in the "## ${heading}" section`);
+    unparseable(`Report is missing the "Recommendation:" line in the "## ${heading}" section`);
   }
   return normalizeRecommendation(match[1], `"## ${heading}"`);
 }
@@ -514,7 +515,7 @@ function parseReport(reportText, runContract = {}) {
   const executive = recommendationFromSection(text, 'Executive Summary');
   const decision = recommendationFromSection(text, 'Decision');
   if (executive !== decision) {
-    unparseable(`Report has conflicting "**Recommendation**:" lines (${executive} in Executive Summary vs ${decision} in Decision)`);
+    unparseable(`Report has conflicting "Recommendation:" lines (${executive} in Executive Summary vs ${decision} in Decision)`);
   }
 
   const scoreMatch = text.match(SCORE_PATTERN);

package/cli/lib/run-agent.js

@@ -57,13 +57,13 @@ function buildMinimalEnv(envPass = [], sourceEnv = process.env, adapterEnvNames
  * @param {string} [options.agent] - Adapter key from agent-adapters.js (default claude).
  * @param {string} [options.agentCommand] - Executable override (--agent-cmd); replaces only the
  *   adapter's default command, not its argv/env.
- * @param {string[]} [options.agentArgs] - Extra args appended after the adapter's own argv (--claude-arg passthrough).
+ * @param {string[]} [options.agentArgs] - Extra args appended after the adapter's own argv (--agent-arg passthrough).
  * @param {string} [options.model] - Model to pin for this run; defaults to the adapter's defaultModel.
  * @param {number} [options.timeout] - Wall-clock timeout in ms (default 1800000); SIGTERM on expiry.
  * @param {string} [options.cwd] - Working directory for the agent.
  * @param {string[]} [options.envPass] - Extra env var names allowed through to the child.
  * @param {string[]} [options.spawnPrefix] - Isolation wrapper (e.g. sandbox-exec -f profile).
- * @returns {string} Agent stdout.
+ * @returns {{ stdout: string, stderr: string }} Captured output from a successful agent run.
  * @throws {Error} AGENT_NOT_FOUND when the executable is missing, AGENT_FAILED
  *   on spawn error, timeout, or non-zero exit.
  */
@@ -128,7 +128,7 @@ function runAgent(
     throw error;
   }
 
-  return result.stdout;
+  return { stdout: result.stdout || '', stderr: result.stderr || '' };
 }
 
 module.exports = { runAgent, buildMinimalEnv };

package/cli/test-review.js

@@ -59,6 +59,8 @@ const SCOPES = new Set(['single', 'directory', 'suite']);
 const FAIL_ON_LEVELS = new Set(['request-changes', 'block']);
 const DEFAULT_TIMEOUT_MS = 1_800_000; // 30 minutes
 const ENV_PASS_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const AGENT_OUTPUT_TAIL_LINES = 20;
+const AGENT_OUTPUT_TAIL_CHARS = 8000;
 
 function fail(exitCode, message) {
   console.error(`tea-test-review: ${message}`);
@@ -69,6 +71,52 @@ function collect(value, previous) {
   return [...previous, value];
 }
 
+/**
+ * Keep the pre-multi-vendor passthrough spelling working while exposing the
+ * generic name as the only documented interface. Normalizing argv before
+ * Commander parses it preserves the exact order when old and new spellings
+ * are mixed, which matters for paired vendor arguments such as `-c value`.
+ *
+ * @param {string[]} argv - Process argv.
+ * @returns {{ argv: string[], usedDeprecatedAlias: boolean }}
+ */
+function normalizeAgentArgAliases(argv) {
+  let usedDeprecatedAlias = false;
+  const normalized = argv.map((arg) => {
+    if (arg === '--claude-arg') {
+      usedDeprecatedAlias = true;
+      return '--agent-arg';
+    }
+    if (arg.startsWith('--claude-arg=')) {
+      usedDeprecatedAlias = true;
+      return `--agent-arg=${arg.slice('--claude-arg='.length)}`;
+    }
+    return arg;
+  });
+  return { argv: normalized, usedDeprecatedAlias };
+}
+
+function boundedAgentOutputTail(value) {
+  const byLines = String(value || '')
+    .trim()
+    .split(/\r?\n/)
+    .slice(-AGENT_OUTPUT_TAIL_LINES)
+    .join('\n');
+  return byLines.length > AGENT_OUTPUT_TAIL_CHARS ? byLines.slice(-AGENT_OUTPUT_TAIL_CHARS) : byLines;
+}
+
+function printMissingReportDiagnostics(agentResult) {
+  for (const [label, value] of [
+    ['stdout', agentResult && agentResult.stdout],
+    ['stderr', agentResult && agentResult.stderr],
+  ]) {
+    const tail = boundedAgentOutputTail(value);
+    if (tail) {
+      console.error(`Agent ${label} before missing report (bounded tail):\n${tail}`);
+    }
+  }
+}
+
 /**
  * Validate a --waive-until value: it must be a real calendar date in YYYY-MM-DD
  * form, strictly after the local today (day granularity, local timezone).
@@ -150,7 +198,7 @@ function main() {
         .join(', ')})`,
     )
     .option('--agent-cmd <path>', 'override the agent executable (advanced; used by tests with a stub agent)')
-    .option('--claude-arg <arg>', 'extra argument passed through to the claude CLI (repeatable)', collect, [])
+    .option('--agent-arg <arg>', 'extra argument appended to the selected agent CLI argv (repeatable)', collect, [])
     .option(
       '--env-pass <NAME>',
       'environment variable name allowed through to the agent beyond the minimal default set (repeatable)',
@@ -183,8 +231,12 @@ function main() {
     .option('--pact-mcp <mode>', `force tea_pact_mcp, overriding _bmad/tea/config.yaml (${PACT_MCP_VALUES.join('|')}; default: none)`);
 
   program.exitOverride();
+  const normalizedArgv = normalizeAgentArgAliases(process.argv);
+  if (normalizedArgv.usedDeprecatedAlias) {
+    console.error('tea-test-review: --claude-arg is deprecated; use --agent-arg.');
+  }
   try {
-    program.parse(process.argv);
+    program.parse(normalizedArgv.argv);
   } catch (error) {
     // --help/--version print their output and throw with exitCode 0.
     if (error.exitCode === 0) {
@@ -215,7 +267,7 @@ function main() {
   let resolvedModel = null;
   if (options.agent !== 'none') {
     try {
-      resolvedModel = resolveModel(options.agent, options.model, options.claudeArg);
+      resolvedModel = resolveModel(options.agent, options.model, options.agentArg);
     } catch (error) {
       if (error.code === 'MODEL_ARG_INVALID' || error.code === 'MODEL_ARG_CONFLICT') {
         fail(EXIT.ENV_ERROR, error.message);
@@ -552,11 +604,12 @@ function main() {
     });
 
     const stopHeartbeat = startHeartbeat();
+    let agentResult;
     try {
-      runAgent(prompt, {
+      agentResult = runAgent(prompt, {
         agent: options.agent,
         agentCommand: options.agentCmd,
-        agentArgs: options.claudeArg,
+        agentArgs: options.agentArg,
         model: options.model,
         timeout: timeoutMs,
         cwd: agentCwd,
@@ -568,6 +621,7 @@ function main() {
     }
 
     if (!fs.existsSync(agentOutputPath) || fs.statSync(agentOutputPath).mtimeMs <= runStart) {
+      printMissingReportDiagnostics(agentResult);
       // Throw rather than fail()/process.exit() here: this runs inside
       // withIsolation's callback, and exiting the process skips its finally
       // block (restoreModes(), the chmod-fallback permission restore) along

package/docs/reference/tea-test-review-cli.md

@@ -87,7 +87,7 @@ The job needs `contents: read` and `pull-requests: write`, and forks receive no
 | `--agent <agent>`                                      | `claude`                                   | `claude` or `codex` spawn the matching CLI via its adapter (`cli/lib/agent-adapters.js`); `none` prints the prompt only.          |
 | `--model <model>`                                      | `claude`: `sonnet`, `codex`: `gpt-5.6-sol` | Model the agent runs on. Overrides whatever the vendor CLI would pick from its own config. Rejected with `--agent none`.          |
 | `--agent-cmd <path>`                                   | the selected adapter's command             | Override the agent executable; the selected `--agent` adapter's argv/env still apply (advanced).                                  |
-| `--claude-arg <arg>`                                   | -                                          | Extra argument appended to the selected agent's argv (repeatable; name predates multi-vendor support).                            |
+| `--agent-arg <arg>`                                    | -                                          | Extra argument appended to the selected agent's argv (repeatable).                                                                |
 | `--env-pass <NAME>`                                    | -                                          | Env var allowed through beyond the default set (repeatable).                                                                      |
 | `--timeout-ms <n>`                                     | `1800000` (30 min)                         | Agent wall-clock timeout (SIGTERM on expiry).                                                                                     |
 | `--min-score <n>`                                      | -                                          | Fail when the quality score is below `n` (0-100).                                                                                 |
@@ -132,13 +132,15 @@ Left unstated, the model is whatever the vendor CLI resolves for itself: `~/.cod
 | `claude`  | `sonnet`       | `--model <model>` |
 | `codex`   | `gpt-5.6-sol`  | `--model <model>` |
 
-The resolved model travels in the verdict JSON as `model`, alongside `agent`, so a stored verdict says what produced it. A model supplied through `--claude-arg` becomes the resolved value too. Combining `--model` with a passthrough model, or declaring multiple passthrough models, is rejected before spawn. Two scores are only comparable when those two fields match.
+The resolved model travels in the verdict JSON as `model`, alongside `agent`, so a stored verdict says what produced it. A model supplied through `--agent-arg` becomes the resolved value too. Combining `--model` with a passthrough model, or declaring multiple passthrough models, is rejected before spawn. Two scores are only comparable when those two fields match.
+
+`--claude-arg` remains accepted as a deprecated alias for compatibility with workflows created before multi-vendor support. It emits a migration warning and preserves argument order. New workflows should use `--agent-arg`.
 
 The pinned values are aliases: they hold the tier steady, not the exact weights. Pass a fully-qualified slug to `--model` when a run has to be reproducible across model generations.
 
 `--model` is rejected with `--agent none`, which runs no agent. Honoring it there would be a lie, and quietly dropping it is the failure mode `--model` exists to remove.
 
-**Codex reasoning effort is a second unstated input, and it is not pinned here.** A local `model_reasoning_effort = "max"` costs about ten extra seconds even on a one-word prompt, and far more on a real review. It is codex-only, so it gets no vendor-agnostic flag; set it per run with `--claude-arg -c --claude-arg model_reasoning_effort=low`.
+**Codex reasoning effort is a second unstated input, and it is not pinned here.** A local `model_reasoning_effort = "max"` costs about ten extra seconds even on a one-word prompt, and far more on a real review. It is codex-only, so it gets no vendor-agnostic flag; set it per run with `--agent-arg -c --agent-arg model_reasoning_effort=low`.
 
 ## TEA config resolution
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.21.0",
+  "version": "1.21.2",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/test/fixtures/test-review-cli/stub-agent.js

@@ -94,6 +94,8 @@ if (mode === 'fail') {
 }
 
 if (mode === 'nothing') {
+  console.log('stub-agent: exited successfully without writing the requested report');
+  console.error('stub-agent: success-path stderr before missing report');
   process.exit(0);
 }
 

package/test/test-test-review-cli.js

@@ -592,6 +592,28 @@ async function runTests() {
       assert(false, 'colon-in-bold fixture parses', error.message);
     }
 
+    // Regression: a live Codex CI run produced the correct Decision value but
+    // omitted Markdown bolding from that one label. Styling cannot invalidate
+    // an otherwise complete verdict whose two Recommendation values agree.
+    try {
+      const source = readFixture('reports', 'request-changes.md');
+      const liveCodexShape = source.replace(
+        '## Decision\n\n**Recommendation**: Request Changes',
+        '## Decision\n\nRecommendation: Request Changes',
+      );
+      if (liveCodexShape === source) {
+        throw new Error('plain Recommendation regression setup did not modify the fixture');
+      }
+      const plainDecision = parseReport(liveCodexShape);
+      assert(
+        plainDecision.recommendation === 'Request Changes' && plainDecision.qualityScore === 63,
+        'plain Decision Recommendation from live Codex output parses',
+        JSON.stringify(plainDecision),
+      );
+    } catch (error) {
+      assert(false, 'plain Decision Recommendation from live Codex output parses', error.message);
+    }
+
     try {
       const lowercase = parseReport(readFixture('reports', 'lowercase.md'));
       assert(lowercase.recommendation === 'Approve', 'lowercase fixture: "approve" normalizes to Approve', JSON.stringify(lowercase));
@@ -1352,7 +1374,7 @@ async function runTests() {
       const argv = adapter.buildArgv(['--extra-marker']);
       assert(
         Array.isArray(argv) && argv.includes('--extra-marker') && argv.at(-1) === '--extra-marker',
-        `${name} adapter buildArgv appends extra args (--claude-arg passthrough) last`,
+        `${name} adapter buildArgv appends extra args (--agent-arg passthrough) last`,
         JSON.stringify(argv),
       );
       assert(typeof adapter.command === 'string' && adapter.command.length > 0, `${name} adapter declares a default command`);
@@ -1651,7 +1673,7 @@ async function runTests() {
       help.status === 0 &&
         [
           '--agent-cmd',
-          '--claude-arg',
+          '--agent-arg',
           '--timeout-ms',
           '--test-glob',
           '--env-pass',
@@ -1815,17 +1837,17 @@ async function runTests() {
       assert(false, 'verdict JSON records the pinned default when --model is absent', error.message);
     }
 
-    // The --claude-arg escape hatch predates --model and still has to work: a
-    // second --model would be a clap usage error on codex.
+    // The generic passthrough can name a model. A second --model would be a
+    // clap usage error on codex.
     const passthroughRun = modelRun(
       'model-passthrough',
-      ['--claude-arg', '-m', '--claude-arg', 'passthrough-model'],
+      ['--agent-arg', '-m', '--agent-arg', 'passthrough-model'],
       'passthrough-model',
       'codex',
     );
     assert(
       passthroughRun.status === 0 && passthroughRun.stderr.includes('model passthrough-model'),
-      'a --claude-arg model passthrough becomes the resolved model and suppresses the pinned default',
+      'an --agent-arg model passthrough becomes the resolved model and suppresses the pinned default',
       `status=${passthroughRun.status} stderr=${passthroughRun.stderr}`,
     );
     try {
@@ -1839,9 +1861,23 @@ async function runTests() {
       assert(false, 'verdict JSON records the passthrough model that actually produced the score', error.message);
     }
 
+    const legacyPassthroughRun = modelRun(
+      'model-passthrough-legacy-alias',
+      ['--claude-arg', '-m', '--claude-arg', 'legacy-passthrough-model'],
+      'legacy-passthrough-model',
+      'codex',
+    );
+    assert(
+      legacyPassthroughRun.status === 0 &&
+        legacyPassthroughRun.stderr.includes('--claude-arg is deprecated; use --agent-arg') &&
+        legacyPassthroughRun.stderr.includes('model legacy-passthrough-model'),
+      'the legacy --claude-arg alias preserves passthrough order and emits a migration warning',
+      `status=${legacyPassthroughRun.status} stderr=${legacyPassthroughRun.stderr}`,
+    );
+
     for (const [agent, passthroughArg, expected] of [
-      ['claude', '--claude-arg=--model=claude-equals', 'claude-equals'],
-      ['codex', '--claude-arg=-m=codex-equals', 'codex-equals'],
+      ['claude', '--agent-arg=--model=claude-equals', 'claude-equals'],
+      ['codex', '--agent-arg=-m=codex-equals', 'codex-equals'],
     ]) {
       const equalsRun = modelRun(`model-passthrough-equals-${agent}`, [passthroughArg], expected, agent);
       assert(
@@ -1860,7 +1896,7 @@ async function runTests() {
       fixtureProject,
       '--model',
       'explicit-model',
-      '--claude-arg=--model=passthrough-model',
+      '--agent-arg=--model=passthrough-model',
     ]);
     assert(
       modelConflict.status === 2 && modelConflict.stderr.includes('both --model'),
@@ -1875,8 +1911,8 @@ async function runTests() {
       'tests/checkout.spec.ts',
       '--project-root',
       fixtureProject,
-      '--claude-arg=-m=first-model',
-      '--claude-arg=--model=second-model',
+      '--agent-arg=-m=first-model',
+      '--agent-arg=--model=second-model',
     ]);
     assert(
       duplicatePassthroughModel.status === 2 && duplicatePassthroughModel.stderr.includes('declares the model 2 times'),
@@ -1891,7 +1927,7 @@ async function runTests() {
       'tests/checkout.spec.ts',
       '--project-root',
       fixtureProject,
-      '--claude-arg=--model',
+      '--agent-arg=--model',
     ]);
     assert(
       missingPassthroughModel.status === 2 && missingPassthroughModel.stderr.includes('passthrough value'),
@@ -2135,6 +2171,14 @@ async function runTests() {
       'stub writing nothing exits 3 despite a stale pre-placed report',
       `status=${staleRun.status} stderr=${staleRun.stderr}`,
     );
+    assert(
+      staleRun.stderr.includes('Agent stdout before missing report (bounded tail):') &&
+        staleRun.stderr.includes('exited successfully without writing the requested report') &&
+        staleRun.stderr.includes('Agent stderr before missing report (bounded tail):') &&
+        staleRun.stderr.includes('success-path stderr before missing report'),
+      'an exit-0 missing-report failure surfaces bounded stdout and stderr diagnostics',
+      staleRun.stderr,
+    );
     assert(!staleRun.stdout.includes('"recommendation": "Block"'), 'stale pre-placed report is never parsed', staleRun.stdout);
     assert(!fs.existsSync(staleOut), 'stale pre-placed report is deleted before the agent runs', staleOut);