bmad-method-test-architecture-enterprise 2.0.2 → 2.0.3-next.0

package/.claude-plugin/marketplace.json

@@ -31,16 +31,14 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test generation in red and expand modes with automatic run-and-heal, combined framework and CI setup, CI/CD quality gates, and structured testing education. The CI and ATDD commands remain available with existing customizations. Part of the BMad Method ecosystem.",
-      "version": "2.0.2",
+      "version": "2.0.3-next.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },
       "skills": [
         "./skills/bmod-tea",
         "./skills/bmad-tea",
-        "./skills/bmad-testarch-atdd",
         "./skills/bmad-testarch-automate",
-        "./skills/bmad-testarch-ci",
         "./skills/bmad-testarch-evaluate",
         "./skills/bmad-testarch-framework",
         "./skills/bmad-testarch-nfr",

package/README.md

@@ -50,7 +50,7 @@ npx skills add https://github.com/bmad-code-org/bmad-method-test-architecture-en
 
 ## Start with one skill
 
-Ten commands start the eight skills: Framework includes CI setup; Automate includes red and expand modes.
+Eight commands start the eight workflows: Framework includes CI setup; Automate includes red and expand modes.
 
 In Claude Code, Cursor, and Windsurf, type `/bmad-testarch-test-design` in chat.
 In Codex, type `$bmad-testarch-test-design`.
@@ -73,10 +73,10 @@ Evaluate:
 
 Framework and CI setup share one skill, `bmad-testarch-framework`.
 Ask for framework only, CI only, or both; TEA infers the scope from your prompt and asks "Do you want CI too?" once when CI scope is unclear in an interactive session. An unattended request with unclear scope runs framework setup only and states that CI was excluded.
-`/bmad-testarch-ci` and the `CI` menu code still work and start the same skill's CI setup, with your existing CI customizations.
+Request CI setup through `/bmad-testarch-framework` or the agent's `CI` menu code. Existing CI customizations remain usable.
 Create, Resume, Validate, and Edit remain available for the selected setup scope.
 
-Automation uses `red` mode before implementation and `expand` mode for existing code. Your prompt selects the mode. `/bmad-testarch-atdd` and `AT` default to red; `/bmad-testarch-automate` and `TA` default to expand. Existing commands and customization files keep working. Create runs execute the generated tests and repair test issues for up to three rounds. Red confirms the intended missing behavior; expand aims for passing coverage and reports product defects.
+Automation uses `red` mode before implementation and `expand` mode for existing code. Request red mode through `/bmad-testarch-automate` or the agent's `AT` menu code; the direct command defaults to expand. Existing customization files and saved progress remain usable. Create runs execute the generated tests and repair test issues for up to three rounds. Red confirms the intended missing behavior; expand aims for passing coverage and reports product defects.
 
 For Codex, replace the leading `/` in the table with `$`.
 The agent menu also accepts `GATE` to route you through test review, NFR evidence audit, and trace Phase 2.

package/cli/evaluate.js

@@ -29,6 +29,8 @@
  *                                             compare a scored run's evidence with baseline/ through eval-quality's
  *                                             compareDominance (compared, first-run or refused, every one exit 0), or
  *                                             with --accept replace baseline/ with a byte-identical snapshot of the run
+ *   tea-evaluate status --evaluation <path> [--run <invocationId>] [--follow]
+ *                                             show the latest run's progress, or follow it until it ends
  *   tea-evaluate ci --evaluation <path> --tier <pr|merge|scheduled|release>
  *                                             run exactly the checks ci/evaluation-ci-plan.json places on the tier, in
  *                                             plan order, each one's exit, stdout and stderr kept under
@@ -130,6 +132,7 @@ const { runRunCommand } = require('./lib/evaluate/run');
 const { runCompareCommand } = require('./lib/evaluate/compare');
 const { runScoreCommand } = require('./lib/evaluate/score');
 const { runCiCommand } = require('./lib/evaluate/ci');
+const { runStatusCommand } = require('./lib/evaluate/status');
 const { TIERS } = require('./lib/evaluate/ci-plan');
 const { escapeUnprintable, findingLine } = require('./lib/evaluate/finding-lines');
 const { calibrationInputsOf } = require('./lib/evaluate/records-calibration');
@@ -265,6 +268,17 @@ function compareCommand(options) {
   return runDriven('compare', runCompareCommand, options, { run: options.run, accept: options.accept === true });
 }
 
+async function statusCommand(options) {
+  const folder = folderFrom(options);
+  const result = await runStatusCommand(folder, {
+    run: options.run,
+    follow: options.follow === true,
+    emit: (line) => process.stdout.write(`${NAME} status: ${escapeUnprintable(line)}\n`),
+  });
+  if (result.exitCode !== 0) process.stderr.write(`${NAME} status: ${escapeUnprintable(result.message)}\n`);
+  return result.exitCode;
+}
+
 async function ciCommand(options) {
   if (!TIERS.includes(options.tier)) {
     throw new UsageError(
@@ -278,7 +292,7 @@ function buildProgram(run) {
   const program = new Command();
   program
     .name(NAME)
-    .description('Validate, digest, preflight, run, score, compare and run the CI tiers of an Evaluate evaluation folder.')
+    .description('Validate, digest, preflight, run, score, compare, report status and run the CI tiers of an Evaluate evaluation folder.')
     .showHelpAfterError()
     .exitOverride()
     .configureOutput({ writeErr: (text) => process.stderr.write(text) });
@@ -338,6 +352,13 @@ function buildProgram(run) {
     .option('--run <invocationId>', 'the run to compare or accept; the most recent run when omitted')
     .option('--accept', 'replace baseline/ with a byte-identical snapshot of the run; refused for a dirty run')
     .action((options) => run(compareCommand, options));
+  program
+    .command('status')
+    .description("Show the newest run's progress, or follow it until completion; --run selects a specific invocation.")
+    .option('--evaluation <path>', 'the evaluation folder, or its evaluation.json')
+    .option('--run <invocationId>', 'the run to inspect; the most recent run when omitted')
+    .option('--follow', 'print progress changes and periodic heartbeats until the run ends')
+    .action((options) => run(statusCommand, options));
   program
     .command('ci')
     .description(
@@ -377,7 +398,9 @@ async function main(argv) {
     return await pending;
   } catch (error) {
     if (error instanceof UsageError) {
-      process.stderr.write(`${NAME}: ${error.message}\nUsage: ${NAME} <check|digest|preflight|run|score|compare|ci> --evaluation <path>\n`);
+      process.stderr.write(
+        `${NAME}: ${error.message}\nUsage: ${NAME} <check|digest|preflight|run|score|compare|status|ci> --evaluation <path>\n`,
+      );
       return EXIT_CODES.usage;
     }
     if (error instanceof CorpusIndexError) {

package/cli/lib/evaluate/preflight.js

@@ -513,6 +513,8 @@ function runPreflightCommand(folder, { partition, requirePartition = false, ...o
  * @param {Set<string>|null} [options.selectedProbeIds] the probes the partition selects; every probe when null
  * @param {NodeJS.ProcessEnv} [options.env]
  * @param {(line: string) => void} [options.log]
+ * @param {number} [options.progressIntervalMs] heartbeat interval, for tests and long-running runs
+ * @param {number} [options.progressStartedAt] invocation start time, before setup
  * @param {(context: object) => PreflightOutcome|null|Promise<PreflightOutcome|null>} [options.prepare]
  * @param {(context: object) => Promise<PreflightOutcome>} [options.afterVerdict]
  * @returns {Promise<PreflightOutcome>}
@@ -520,10 +522,11 @@ function runPreflightCommand(folder, { partition, requirePartition = false, ...o
 async function runPipeline(folder, options) {
   // The invocation's run directory and run.json, held in memory, so its end is
   // recorded from what the runtime knows, never from a file read back.
-  const state = { writer: null, run: null, sealed: false, retractUnlessSealed: [] };
+  const state = { writer: null, run: null, sealed: false, retractUnlessSealed: [], progressTimer: null, finishProgress: null };
   try {
     return await recordEnd(await pipeline(folder, options, state), state);
   } finally {
+    if (state.progressTimer !== null) clearInterval(state.progressTimer);
     // The directories the run made stay held open until here, so none of
     // their inode numbers can pass to a directory the target makes.
     state.writer?.close();
@@ -543,6 +546,7 @@ function recordEnd(outcome, state) {
     const failed = [];
     for (const [what, step] of [
       ...state.retractUnlessSealed.map((file) => [`remove ${file}`, () => state.writer.remove(file)]),
+      ['record final progress', () => state.finishProgress?.('stopped')],
       ['record this end in run.json', () => state.writer.replaceJson('run.json', state.run)],
     ]) {
       try {
@@ -574,6 +578,8 @@ async function pipeline(
     selectedProbeIds = null,
     partition,
     seed,
+    progressIntervalMs = 30_000,
+    progressStartedAt,
   },
   state,
 ) {
@@ -658,6 +664,7 @@ async function pipeline(
     }
   };
   const onSignal = (name) => {
+    if (state.progressTimer !== null) clearInterval(state.progressTimer);
     removeScratch();
     if (journal) {
       try {
@@ -671,6 +678,7 @@ async function pipeline(
       for (const file of [...retractOnSignal, ...state.retractUnlessSealed]) state.writer.remove(file);
       state.run.outcome = { stage: 'signal', exitCode: null, signal: name, message: `stopped by ${name} before it finished` };
       if (state.run.command === 'run') state.run.completed = false;
+      state.finishProgress?.('stopped');
       state.writer.replaceJson('run.json', state.run);
     } catch {
       // The signal still ends the process; run.json keeps its last state.
@@ -735,6 +743,11 @@ async function pipeline(
     log(
       `pristine workspace, ${pristine.kind === 'git-worktree' ? `a detached worktree at ${pristine.commit}` : `a temp copy${pristine.dirty ? ' of the working tree' : ''}`}: ${pristine.root}`,
     );
+    if (pristine.kind === 'git-worktree' && sharedState) {
+      log(
+        'Git worktrees share repository refs, config and hooks. Keep Git writes in every worktree of this repository paused until this command ends, or use a dedicated clone for concurrent work.',
+      );
+    }
     // The evaluation folder is read from the working tree (the workspaces
     // leave it out), so uncommitted work in it reaches the run, which is then
     // dirty: no committed state names what it measured.
@@ -766,6 +779,8 @@ async function pipeline(
       runsDirectory,
       invocationId,
       seed: runSeed,
+      progressStartedAt,
+      progressIntervalMs,
       retractOnSignal,
       scratch,
       state,
@@ -826,6 +841,8 @@ async function runInWorkspaces({
   runsDirectory,
   invocationId,
   seed,
+  progressStartedAt,
+  progressIntervalMs,
   retractOnSignal,
   scratch,
   state,
@@ -877,9 +894,65 @@ async function runInWorkspaces({
     adopterTree: { repository: before.repository === null ? null : REPOSITORY, unchanged: null },
     refused: [],
   };
+  const progressStarted = progressStartedAt ?? Date.now();
+  const progressCreatedAt = Date.now();
+  const progressCreatedTick = globalThis.performance.now();
+  const setupBeforeRecordMs = Math.max(0, progressCreatedAt - progressStarted);
+  let phaseStartedTick = progressCreatedTick;
+  if (command === 'run') {
+    run.progress = {
+      phase: 'setup',
+      detail: 'Preparing the run',
+      startedAt: new Date(progressStarted).toISOString(),
+      updatedAt: new Date(progressCreatedAt).toISOString(),
+      phaseStartedAt: new Date(progressStarted).toISOString(),
+      phaseElapsedMs: setupBeforeRecordMs,
+      elapsedMs: setupBeforeRecordMs,
+      phaseDurationsMs: {},
+      completedTrials: 0,
+      totalTrials: null,
+      usage: null,
+    };
+  }
   state.run = run;
   const writeRun = () => writer.replaceJson('run.json', run);
   writeRun();
+  const progress = (phase, fields = {}) => {
+    if (command !== 'run' || state.sealed) return;
+    const now = Date.now();
+    const tick = globalThis.performance.now();
+    const sinceCreated = Math.max(0, tick - progressCreatedTick);
+    if (phase !== run.progress.phase) {
+      const prior = run.progress.phase;
+      const priorDuration = Math.max(0, tick - phaseStartedTick) + (prior === 'setup' ? setupBeforeRecordMs : 0);
+      run.progress.phaseDurationsMs[prior] = (run.progress.phaseDurationsMs[prior] ?? 0) + priorDuration;
+      phaseStartedTick = tick;
+      run.progress.phase = phase;
+      run.progress.phaseStartedAt = new Date(now).toISOString();
+    }
+    Object.assign(run.progress, fields, {
+      updatedAt: new Date(now).toISOString(),
+      elapsedMs: setupBeforeRecordMs + sinceCreated,
+      phaseElapsedMs: Math.max(0, tick - phaseStartedTick) + (phase === 'setup' ? setupBeforeRecordMs : 0),
+    });
+    writeRun();
+  };
+  state.finishProgress = (phase) => progress(phase, { detail: phase === 'complete' ? 'Run sealed' : 'Run stopped' });
+  if (command === 'run') {
+    state.progressTimer = setInterval(() => {
+      try {
+        progress(run.progress.phase);
+        log(
+          `progress: ${run.progress.phase}; ${run.progress.completedTrials ?? '?'}/${run.progress.totalTrials ?? '?'} trials; ${Math.floor(run.progress.elapsedMs / 1000)}s elapsed`,
+        );
+      } catch (error) {
+        // A progress write is guarded like every other run-directory write. The main
+        // pipeline will detect the same changed directory at its next verification.
+        log(`progress could not be recorded: ${error.message}`);
+      }
+    }, progressIntervalMs);
+    state.progressTimer.unref?.();
+  }
 
   // The run keeps its own copy of the contract this partition runs, so every stage below reads the
   // same bytes and the verdict can be reproduced from the run directory alone.
@@ -951,6 +1024,7 @@ async function runInWorkspaces({
     }
   };
 
+  progress('qualification', { detail: 'Qualifying probes and clean controls' });
   const qualified = [];
   const policyPath = path.join(folder, POLICY_PATH);
   const policy = fs.existsSync(policyPath) ? readJson(policyPath) : null;
@@ -1192,6 +1266,7 @@ async function runInWorkspaces({
     // Every leg has a port, and so a home, of its own.
     resetHome() {},
   };
+  progress('preflight', { detail: 'Running preflight legs and verdict' });
   try {
     const recorder = recordingPort({
       pristine: { label: 'pristine', cwd: workspaceDirectory(pristine), port: auditedLegs },
@@ -1325,6 +1400,7 @@ async function runInWorkspaces({
       writer,
       run,
       writeRun,
+      progress,
       treeUnchanged,
       retractUnlessSealed: state.retractUnlessSealed,
       markSealed: () => {

package/cli/lib/evaluate/run.js

@@ -236,11 +236,12 @@ function refusal({ folder, selectedProbeIds = null }) {
  *   (`before-state.js`) may fail its baseline, and the run is marked so it is never accepted as a baseline
  * @param {NodeJS.ProcessEnv} [options.env]
  * @param {(line: string) => void} [options.log]
+ * @param {number} [options.progressIntervalMs] heartbeat interval used by integration tests
  * @returns {Promise<PreflightOutcome>}
  */
 function runRunCommand(
   folder,
-  { fromWorkingTree = false, partition, trials, seed, beforeState = false, env = process.env, log = () => {} } = {},
+  { fromWorkingTree = false, partition, trials, seed, beforeState = false, env = process.env, log = () => {}, progressIntervalMs } = {},
 ) {
   if (trials !== undefined && !(Number.isInteger(trials) && trials >= 1))
     return Promise.resolve(
@@ -260,7 +261,7 @@ function runRunCommand(
   } catch {
     // The pipeline's check reports malformed source files with authoring findings; it keeps the partition, so a development
     // run still does not open the held-out plan.
-    return runPipeline(folder, { command: 'run', partition, fromWorkingTree, seed, env, log });
+    return runPipeline(folder, { command: 'run', partition, fromWorkingTree, seed, env, log, progressIntervalMs });
   }
   if (selection.refusal !== undefined) return Promise.resolve(new PreflightOutcome({ stage: 'check', ...selection.refusal }));
   const { selectedProbeIds } = selection;
@@ -276,6 +277,8 @@ function runRunCommand(
     seed,
     env,
     log,
+    progressIntervalMs,
+    progressStartedAt: started,
     prepare: async (context) => {
       const refused = refusal({ ...context, selectedProbeIds });
       if (refused !== null) return refused;
@@ -1148,6 +1151,8 @@ async function runTrialSets(given) {
     sealed,
   } = context;
   const { treeUnchanged, stop, log, snapshot } = context;
+  const progress = context.progress ?? (() => {});
+  progress('clean-control-qualification', { detail: 'Qualifying clean controls' });
 
   const cleanControls = await qualifyCleanControls({ ...context, seed: run.seed });
   // The gameability probes the shared pipeline qualified before the verdict.
@@ -1214,8 +1219,19 @@ async function runTrialSets(given) {
   const { kind } = snapshot.layer.evaluator;
   if (kind === 'records') {
     if (sealed === null) throw noStages();
+    // Imported sets can share arm work, and the importer does not attest to
+    // complete usage reports. Leave both the trial count and cost unknown.
+    progress('records-import', {
+      detail: 'Importing existing evaluator records',
+      completedTrials: null,
+      totalTrials: null,
+      usage: null,
+    });
     return concludeImportedRecords({ ...context, arms, refusedIds });
   }
+  const trialCount = snapshot.trials ?? evaluation.trials;
+  const totalTrials = arms.length * trialCount;
+  progress('trial-preparation', { detail: 'Preparing scored trials', totalTrials });
   if (convertsRows(kind)) {
     // A command evaluator and a sealed-brief agent read the brief the run sealed, as its bytes were written.
     if (sealed === null) throw noStages();
@@ -1242,6 +1258,7 @@ async function runTrialSets(given) {
 
   let calibrationDigest = null;
   if ((contract.rubrics ?? []).length > 0) {
+    progress('calibration', { detail: 'Calibrating rubric judge' });
     const { layer } = snapshot;
     const judgeItem = async ({ rubric, criterion, response, responseKind }) => {
       const stepId = /^\/interactions\/([^/]+)/.exec(criterion.evidence)?.[1];
@@ -1357,7 +1374,6 @@ async function runTrialSets(given) {
     }
   }
 
-  const trialCount = snapshot.trials ?? evaluation.trials;
   if (sealed === null) throw noStages();
   const { contractDigest, sealedBriefDigest } = sealed;
   const { conditions, layer } = snapshot;
@@ -1439,7 +1455,15 @@ async function runTrialSets(given) {
   };
 
   // A sealed-brief agent chooses its own calls, so its verdicts count only once it agrees with itself on the arms it will judge.
-  if (kind === 'sealed-brief-agent') await qualifyEvaluator({ ...context, arms, sealing });
+  if (kind === 'sealed-brief-agent') {
+    progress('evaluator-qualification', { detail: 'Qualifying evaluator agreement' });
+    await qualifyEvaluator({ ...context, arms, sealing });
+  }
+
+  let completedTrials = 0;
+  let reportedUse = ZERO;
+  let missingReports = 0;
+  progress('trials', { detail: 'Running scored trials', totalTrials, completedTrials });
 
   for (const arm of arms) {
     arm.trials = [];
@@ -1452,6 +1476,19 @@ async function runTrialSets(given) {
         throw stop({ stage: 'trial', exitCode: 12, message: `the installed agent version could not be held after a trial: ${agentMoved}` });
       trial.elapsedMs += Date.now() - versionReadBegan;
       arm.trials.push(trial);
+      reportedUse = addUsage(reportedUse, trial.resourceUse);
+      missingReports += trial.unreportedSteps.length;
+      completedTrials += 1;
+      progress('trials', {
+        detail: `${arm.conditionArm}: trial ${trialIndex} of ${trialCount}`,
+        completedTrials,
+        usage: {
+          trialCostUsd: missingReports === 0 && completedTrials === totalTrials ? reportedUse.costUsd : null,
+          reportedTrialCostUsd: reportedUse.costUsd,
+          missingReports,
+          scope: 'trials-only',
+        },
+      });
       // Read after every trial, so a target that writes into the project stops the run at once.
       treeUnchanged('trials');
     }
@@ -1493,6 +1530,7 @@ async function runTrialSets(given) {
   // wrote, and the run directory nothing else, before any trial set is written.
   writer.verify('after the trials');
 
+  progress('sealing', { detail: 'Sealing trial sets and evidence' });
   const trialSets = [];
   const recordDigests = {};
   const manifestDigests = {};
@@ -2103,6 +2141,7 @@ async function completeRun(
   // runtime wrote, before run.json says completed; that write is the run's last.
   treeUnchanged('sealing', { record: false });
   writer.verify('after the trial sets were sealed');
+  context.progress?.('complete', { detail: 'Run sealed' });
   Object.assign(run, {
     artifacts,
     contractDigest: sealed.contractDigest,

package/cli/lib/evaluate/status.js

@@ -0,0 +1,184 @@
+/** Read-only progress view for a running or finished Evaluate invocation. */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readFolderFile } = require('./folder');
+
+const STALE_AFTER_MS = 90_000;
+const POLL_MS = 2000;
+const REPORT_EVERY_MS = 30_000;
+
+/** Only the runtime's flat invocation identifiers may name a run. */
+function validRunId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]+$/.test(value) && value !== '.' && value !== '..';
+}
+
+function readRecord(folder, runId) {
+  const relative = `runs/${runId}/run.json`;
+  // An atomic progress replacement can land between the guarded path walk and
+  // open. Retry that one race, while retaining every link and file-type refusal.
+  let read;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    read = readFolderFile(folder, relative);
+    if (read.ok || read.reason !== 'changed while it was read; run the command again') break;
+  }
+  if (!read.ok) return { error: `${relative} ${read.reason}` };
+  let record;
+  try {
+    record = JSON.parse(read.bytes.toString('utf8'));
+  } catch {
+    return { error: `${relative} is not valid JSON` };
+  }
+  if (record === null || typeof record !== 'object' || Array.isArray(record) || record.command !== 'run' || record.invocationId !== runId) {
+    return { error: `${relative} does not identify a tea-evaluate run` };
+  }
+  return { record };
+}
+
+/** Resolve the requested run, or the newest run whose guarded record identifies it. */
+function locateRun(folder, requested) {
+  if (requested !== undefined) {
+    if (!validRunId(requested)) return { error: `--run ${JSON.stringify(requested)} is not a run identifier` };
+    const read = readRecord(folder, requested);
+    return read.error === undefined ? { runId: requested, record: read.record } : read;
+  }
+  const runs = path.join(folder, 'runs');
+  let names;
+  try {
+    if (!fs.lstatSync(runs).isDirectory()) return { error: `${runs} is not a runs directory` };
+    names = fs.readdirSync(runs, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return { error: `${runs} holds no tea-evaluate run` };
+    return { error: `${runs} cannot be read (${error.code ?? error.message})` };
+  }
+  for (const entry of names
+    .map((item) => item.name)
+    .filter(validRunId)
+    .sort()
+    .toReversed()) {
+    const read = readRecord(folder, entry);
+    if (read.error === undefined) return { runId: entry, record: read.record };
+  }
+  return { error: `${runs} holds no tea-evaluate run` };
+}
+
+function elapsedText(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const seconds = Math.floor(ms / 1000);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  return `${hours}h ${minutes}m ${seconds % 60}s`;
+}
+
+function shortDuration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return elapsedText(ms);
+}
+
+function safeText(value) {
+  return typeof value === 'string' ? value.replaceAll(/[\r\n\t]+/g, ' ').trim() : '';
+}
+
+function costAmount(value) {
+  return typeof value === 'string' && /^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value) ? value : null;
+}
+
+function costText(usage) {
+  if (usage === null || typeof usage !== 'object' || usage.scope !== 'trials-only') return 'trial cost unknown (trials only)';
+  const missing = Number.isInteger(usage.missingReports) && usage.missingReports >= 0 ? usage.missingReports : null;
+  const reported = costAmount(usage.reportedTrialCostUsd);
+  const complete = costAmount(usage.trialCostUsd);
+  if (complete !== null && missing === 0) return `trial cost $${complete} (trials only)`;
+  const parts = ['trial cost unknown'];
+  if (reported !== null) parts.push(`reported $${reported}`);
+  if (missing !== null) parts.push(`${missing} missing report${missing === 1 ? '' : 's'}`);
+  return `${parts[0]} (${[...parts.slice(1), 'trials only'].join('; ')})`;
+}
+
+function statusOf(runId, record, now = Date.now()) {
+  const progress = record.progress && typeof record.progress === 'object' && !Array.isArray(record.progress) ? record.progress : {};
+  const outcome = record.outcome && typeof record.outcome === 'object' ? record.outcome : null;
+  const updatedAt = Date.parse(progress.updatedAt);
+  const startedAt = Date.parse(progress.startedAt ?? record.startedAt);
+  const terminal = record.completed === true || outcome !== null;
+  const stale = !terminal && (!Number.isFinite(updatedAt) || now - updatedAt >= STALE_AFTER_MS);
+  const state = terminal ? (record.completed === true ? 'complete' : 'stopped') : stale ? 'stale' : 'live';
+  const completedTrials = Number.isInteger(progress.completedTrials) && progress.completedTrials >= 0 ? progress.completedTrials : null;
+  const totalTrials = Number.isInteger(progress.totalTrials) && progress.totalTrials >= 0 ? progress.totalTrials : null;
+  const lastElapsed = Number.isFinite(progress.elapsedMs) && progress.elapsedMs >= 0 ? progress.elapsedMs : null;
+  const elapsed =
+    lastElapsed === null
+      ? terminal && Number.isFinite(record.durationMs)
+        ? record.durationMs
+        : stale
+          ? Number.NaN
+          : now - startedAt
+      : lastElapsed;
+  const parts = [`run ${runId}: ${state}`];
+  if (safeText(progress.phase)) parts.push(safeText(progress.phase));
+  if (safeText(progress.detail)) parts.push(safeText(progress.detail));
+  if (Number.isFinite(progress.phaseElapsedMs) && progress.phaseElapsedMs >= 0) {
+    parts.push(`phase elapsed ${elapsedText(progress.phaseElapsedMs)}`);
+  }
+  if (completedTrials !== null && totalTrials !== null) parts.push(`trials ${completedTrials}/${totalTrials}`);
+  parts.push(`elapsed ${elapsedText(elapsed)}`);
+  const phaseDurations = progress.phaseDurationsMs;
+  if (phaseDurations !== null && typeof phaseDurations === 'object' && !Array.isArray(phaseDurations)) {
+    const finishedPhases = Object.entries(phaseDurations)
+      .filter(([phase, ms]) => safeText(phase) !== '' && Number.isFinite(ms) && ms >= 0)
+      .map(([phase, ms]) => `${safeText(phase)} ${shortDuration(ms)}`);
+    if (finishedPhases.length > 0) parts.push(`phase times ${finishedPhases.join(', ')}`);
+  }
+  parts.push(
+    costText(progress.usage),
+    Number.isFinite(updatedAt)
+      ? `last update ${new Date(updatedAt).toISOString()} (${elapsedText(Math.max(0, now - updatedAt))} ago)`
+      : 'last update unknown',
+  );
+  if (outcome !== null) {
+    if (Number.isInteger(outcome.exitCode)) parts.push(`exit ${outcome.exitCode}`);
+    if (safeText(outcome.signal)) parts.push(`signal ${safeText(outcome.signal)}`);
+  }
+  return { runId, state, terminal, stale, line: parts.join(' | '), progress, outcome };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Emit one snapshot, then material changes and periodic heartbeats until the run ends. */
+async function runStatusCommand(folder, { run, follow = false, emit, pollMs = POLL_MS, reportEveryMs = REPORT_EVERY_MS } = {}) {
+  const located = locateRun(folder, run);
+  if (located.error !== undefined) return { exitCode: 64, message: located.error };
+  const { runId } = located;
+  let lastIdentity = null;
+  let lastReportAt = 0;
+  for (;;) {
+    const read = readRecord(folder, runId);
+    if (read.error !== undefined) return { exitCode: 12, message: read.error };
+    const now = Date.now();
+    const status = statusOf(runId, read.record, now);
+    const identity = JSON.stringify({
+      state: status.state,
+      phase: status.progress.phase,
+      detail: status.progress.detail,
+      completedTrials: status.progress.completedTrials,
+      totalTrials: status.progress.totalTrials,
+      outcome: status.outcome,
+    });
+    if (lastIdentity !== identity || now - lastReportAt >= reportEveryMs) {
+      emit?.(status.line);
+      lastIdentity = identity;
+      lastReportAt = now;
+    }
+    if (!follow || status.terminal) return { exitCode: 0, message: status.line, status };
+    await sleep(pollMs);
+  }
+}
+
+module.exports = { STALE_AFTER_MS, locateRun, runStatusCommand, statusOf, validRunId };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "2.0.2",
+  "version": "2.0.3-next.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -89,7 +89,7 @@
     "release:minor": "gh workflow run publish.yaml -f channel=latest -f bump=minor",
     "release:next": "gh workflow run publish.yaml -f channel=next",
     "release:patch": "gh workflow run publish.yaml -f channel=latest -f bump=patch",
-    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:evaluate-guidance && npm run test:evaluate-authoring && npm run test:evaluate-gap-loop && npm run test:evaluate-dogfood && npm run test:evaluate-check && npm run test:evaluate-compare && npm run test:evaluate-before-state && npm run test:evaluate-ci-gates && npm run test:evaluate-ci-tiers && npm run test:evaluate-ci-repositories:tagged-release-pr && npm run test:evaluate-ci-repositories:tagged-release-merge && npm run test:evaluate-ci-repositories:tagged-release-release && npm run test:evaluate-ci-repositories:nightly-deploy-pr && npm run test:evaluate-ci-repositories:nightly-deploy-merge && npm run test:evaluate-ci-repositories:nightly-deploy-scheduled && npm run test:evaluate-ci-repositories:nightly-deploy-release && npm run test:evaluate-ci-render && npm run test:evaluate-pr-mcp && npm run test:evaluate-pr-api && npm run test:evaluate-pr-suite && npm run test:evaluate-pr-workflow && npm run test:evaluate-pr-tool-use && npm run test:evaluate-pr-promptfoo && npm run test:evaluate-pr-ai-feature && npm run test:evaluate-pr-test-review && npm run test:evaluate-pr-gap-loop && npm run test:evaluate-pr-learn && npm run test:evaluate-pr-tutorial && npm run test:evaluate-partitions && npm run test:evaluate-partition-plans-views-and-check && npm run test:evaluate-partition-plans-preflight-and-run && npm run test:evaluate-partition-plans-score && npm run test:evaluate-partition-plans-attempts-seal-and-mappings && npm run test:evaluate-partition-plans-attempts-records && npm run test:evaluate-partition-plans-attempts-gameability && npm run test:evaluate-interpret && npm run test:evaluate-calibration && npm run test:evaluate-boundaries && npm run test:evaluate-preflight && npm run test:evaluate-isolation-conformance && npm run test:evaluate-mutation:qualification-basics && npm run test:evaluate-mutation:qualification-guards && npm run test:evaluate-mutation:recovery && npm run test:evaluate-mutation:journals && npm run test:evaluate-run && npm run test:evaluate-aggregate && npm run test:evaluate-confinement && npm run test:evaluate-confinement-audit && npm run test:evaluate-confinement-history && npm run test:evaluate-confinement-git-state && npm run test:evaluate-confinement-network && npm run test:evaluate-held-inputs && npm run test:evaluate-arms-historical && npm run test:evaluate-arms-deployments && npm run test:evaluate-evaluators && npm run test:evaluate-evaluators-agent-version && npm run test:evaluate-agents && npm run test:evaluate-agents-importers && npm run test:evaluate-agents-sealed-brief && npm run test:evaluate-held-attempts && npm run test:evaluate-private && npm run test:evaluate-records && npm run test:evaluate-mcp && npm run test:evaluate-api && npm run test:evaluate-workflow && npm run test:evaluate-tool-use && npm run test:evaluate-promptfoo && npm run test:evaluate-learned-framework && npm run test:docs-tutorial && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:planning-doc-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:doc-link-anchors && npm run test:docs-build-names && npm run test:docs-evaluate-sidebar && npm run test:docs-gap-reader && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:isolation-primitives && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:atdd-workflow-guidance && npm run test:generation-healing && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:nfr-evidence-guidance && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-routing-boundaries && npm run test:eval-routing-evidence && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:test-design-qualification && npm run test:test-review-qualification && npm run test:trace-qualification && npm run test:nfr-qualification && npm run test:ci-qualification && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:trial-set-scoring && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:install-actionlint && npm run test:workflows-lint && npm run test:install-linux-sandbox && npm run test:shards && npm run test:groups && npm run test:cli && npm run test:test-review-pr-scope && npm run test:test-review-report && npm run test:test-review-rubric && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:release-notes && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run test:docs-mermaid && npm run test:llms-headroom && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:conflict-markers && npm run test:schemas && npm run test:install && npm run test:evaluate-guidance && npm run test:evaluate-authoring && npm run test:evaluate-gap-loop && npm run test:evaluate-dogfood && npm run test:evaluate-check && npm run test:evaluate-compare && npm run test:evaluate-before-state && npm run test:evaluate-ci-gates && npm run test:evaluate-ci-tiers && npm run test:evaluate-ci-repositories:tagged-release-pr && npm run test:evaluate-ci-repositories:tagged-release-merge && npm run test:evaluate-ci-repositories:tagged-release-release && npm run test:evaluate-ci-repositories:nightly-deploy-pr && npm run test:evaluate-ci-repositories:nightly-deploy-merge && npm run test:evaluate-ci-repositories:nightly-deploy-scheduled && npm run test:evaluate-ci-repositories:nightly-deploy-release && npm run test:evaluate-ci-render && npm run test:evaluate-pr-mcp && npm run test:evaluate-pr-api && npm run test:evaluate-pr-suite && npm run test:evaluate-pr-workflow && npm run test:evaluate-pr-tool-use && npm run test:evaluate-pr-promptfoo && npm run test:evaluate-pr-ai-feature && npm run test:evaluate-pr-test-review && npm run test:evaluate-pr-gap-loop && npm run test:evaluate-pr-learn && npm run test:evaluate-pr-tutorial && npm run test:evaluate-partitions && npm run test:evaluate-partition-plans-views-and-check && npm run test:evaluate-partition-plans-preflight-and-run && npm run test:evaluate-partition-plans-score && npm run test:evaluate-partition-plans-attempts-seal-and-mappings && npm run test:evaluate-partition-plans-attempts-records && npm run test:evaluate-partition-plans-attempts-gameability && npm run test:evaluate-interpret && npm run test:evaluate-calibration && npm run test:evaluate-boundaries && npm run test:evaluate-preflight && npm run test:evaluate-isolation-conformance && npm run test:evaluate-mutation:qualification-basics && npm run test:evaluate-mutation:qualification-guards && npm run test:evaluate-mutation:recovery && npm run test:evaluate-mutation:journals && npm run test:evaluate-run && npm run test:evaluate-progress && npm run test:evaluate-aggregate && npm run test:evaluate-confinement && npm run test:evaluate-confinement-audit && npm run test:evaluate-confinement-history && npm run test:evaluate-confinement-git-state && npm run test:evaluate-confinement-network && npm run test:evaluate-held-inputs && npm run test:evaluate-arms-historical && npm run test:evaluate-arms-deployments && npm run test:evaluate-evaluators && npm run test:evaluate-evaluators-agent-version && npm run test:evaluate-agents && npm run test:evaluate-agents-importers && npm run test:evaluate-agents-sealed-brief && npm run test:evaluate-held-attempts && npm run test:evaluate-private && npm run test:evaluate-records && npm run test:evaluate-mcp && npm run test:evaluate-api && npm run test:evaluate-workflow && npm run test:evaluate-tool-use && npm run test:evaluate-promptfoo && npm run test:evaluate-learned-framework && npm run test:docs-tutorial && npm run test:knowledge && npm run test:criteria-fragments && npm run test:doc-count-sources && npm run test:planning-doc-sources && npm run test:doc-counts && npm run test:doc-claim-sources && npm run test:doc-claims && npm run test:doc-invocation-entry && npm run test:doc-invocations && npm run test:doc-link-anchors && npm run test:docs-build-names && npm run test:docs-evaluate-sidebar && npm run test:docs-gap-reader && npm run test:enforce-hook && npm run test:framework-scaffold && npm run test:isolation-primitives && npm run test:atdd-isolation && npm run test:atdd-net-guard && npm run test:atdd-scoring && npm run test:atdd-workflow-guidance && npm run test:generation-healing && npm run test:framework-scaffold-install-isolation && npm run test:transcript-harness && npm run test:suite-manifest && npm run test:teach-me-testing-scoring && npm run test:eval-data && npm run test:eval-atdd-data && npm run test:eval-ci-data && npm run test:eval-framework-scaffold-data && npm run test:eval-nfr-data && npm run test:nfr-validate-corpus && npm run test:nfr-evidence-guidance && npm run test:eval-test-design-data && npm run test:eval-trace-data && npm run test:eval-routing-data && npm run test:eval-routing-boundaries && npm run test:eval-routing-evidence && npm run test:eval-transcript-data && npm run test:eval-teach-me-testing-data && npm run test:eval-schemas && npm run test:eval-diagnostics && npm run test:eval-replay && npm run test:eval-quality-corpus && npm run test:schema-versions && npm run test:contract-sources && npm run test:contracts && npm run test:contract-oracles && npm run test:probe-sources && npm run test:test-design-qualification && npm run test:test-review-qualification && npm run test:trace-qualification && npm run test:nfr-qualification && npm run test:ci-qualification && npm run test:probe-corpus && npm run test:compare-dominance && npm run test:compare-eval-runs && npm run test:trial-set-scoring && npm run test:automate-eval-fixture && npm run test:eval-automate-data && npm run test:clock-port && npm run test:probe-conformance && npm run test:corpus-conformance && npm run test:file-system-conformance && npm run test:file-system-port && npm run test:probe-targets && npm run test:port-totality && npm run test:ci-coverage && npm run test:ci-coverage-filters && npm run test:install-actionlint && npm run test:workflows-lint && npm run test:install-linux-sandbox && npm run test:shards && npm run test:groups && npm run test:cli && npm run test:test-review-pr-scope && npm run test:test-review-report && npm run test:test-review-rubric && npm run test:bmad-output-gated && npm run test:release-metadata && npm run test:release-notes && npm run test:lockfile-age && npm run test:lockfile-age-cache && npm run test:licences && npm run test:supply-chain && npm run test:boundary && npm run test:direction && npm run test:lineage && npm run test:guard-publish && npm run test:layering-boundary-lineage && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run test:docs-mermaid && npm run test:llms-headroom && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:atdd-isolation": "node test/test-atdd-isolation.js",
     "test:atdd-net-guard": "node test/test-atdd-net-guard.js",
     "test:atdd-scoring": "node test/test-atdd-scoring.js",
@@ -209,6 +209,7 @@
     "test:evaluate-pr-workflow": "node test/test-evaluate-pr-tier.js workflow",
     "test:evaluate-preflight": "node test/test-evaluate-preflight.js",
     "test:evaluate-private": "node test/test-evaluate-evaluators.js --group=private",
+    "test:evaluate-progress": "node test/test-evaluate-progress.js",
     "test:evaluate-promptfoo": "node test/test-evaluate-promptfoo.js",
     "test:evaluate-records": "node test/test-evaluate-evaluators.js --group=records",
     "test:evaluate-run": "node test/test-evaluate-run.js --group=run",