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

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

package/cli/lib/build-prompt.js

@@ -136,11 +136,12 @@ function buildPrompt({
     '- **Recommendation** must be exactly one of: Approve | Approve with Comments | Request Changes | Block',
     '- A "## Decision" section is required, spelled exactly that, and its **Recommendation** must match the',
     "  Executive Summary's. Do not rename the heading after the sentence that describes it.",
-    '- **Quality Score**: N/100 is required and must be an integer from 0 to 100.',
+    '- **Quality Score**: N/100 is required and must be an integer from 0 to 100. The CLI treats this agent-written',
+    '  number as provisional and replaces it with the deterministic ledger result before gating.',
     '- The **Total Violations**: line is required, with Critical, High, Medium, and Low counts.',
-    '- The "## Quality Score Breakdown" section is required and its ledger must reproduce the score. The CLI',
-    '  recomputes 100 - (Critical×10 + High×5 + Medium×2 + Low×1) + Total Bonus and rejects any disagreement,',
-    '  so the deduction ledger is the only scoring model: never a weighted average and never a judgment adjustment.',
+    '- The "## Quality Score Breakdown" section is required. The CLI computes the authoritative score as',
+    '  100 - (Critical×10 + High×5 + Medium×2 + Low×1) + Total Bonus, then normalizes the report score and grade',
+    '  before gating. The deduction ledger is the only scoring model: never a weighted average or judgment adjustment.',
     '- Each of the six bonus categories is worth 0 or 5, so "Total Bonus" is a multiple of 5 from 0 to 30.',
     '- Grade is exactly one of A, B, C, D, F, with no modifier such as A+.',
     `- The Executive Summary must carry exactly one "**Context Basis**: ${contextBasis}" line, exactly that value.`,

package/cli/lib/parse-report.js

@@ -10,9 +10,9 @@
  *   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
- *   published score; the skill's deduction model is the only scoring model, so
- *   a score that contradicts its own breakdown is rejected rather than gated on.
+ * - A "## Quality Score Breakdown" ledger from which the CLI computes the
+ *   authoritative score; the skill's deduction model is the only scoring
+ *   model, so agent arithmetic never controls the gate.
  * - A "## Reviewed Files" section listing every reviewed file.
  * - Exactly one "**Context Basis**:" line inside the Executive Summary, plus a
  *   "## Review Context" manifest whenever that basis is not `none`.
@@ -46,7 +46,7 @@ const RECOMMENDATION_LINE = /^[ \t]*(?:\*\*Recommendation\*\*:|\*\*Recommendatio
 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]*$`;
-const SCORE_PATTERN = /\*\*Quality Score\*\*:\s*(\d+)\s*\/\s*100/;
+const SCORE_PATTERN = /\*\*Quality Score\*\*:\s*(\d+)\s*\/\s*100(?:[ \t]*\([ \t]*([A-F])(?=[ \t)-]))?/;
 const VIOLATIONS_LINE = /\*\*Total Violations:?\*\*:?[ \t]*([^\n]+)/;
 const VIOLATION_LEVELS = ['Critical', 'High', 'Medium', 'Low'];
 // The template always prints the bonus with a leading "+" (every fixture in
@@ -444,20 +444,19 @@ function verifyRunContract({ reviewedFiles, contextBasis, contextFiles }, runCon
 }
 
 /**
- * Recompute the template's deduction ledger and reject a report whose
- * arithmetic disagrees with the score it published.
+ * Compute the authoritative quality score from the template's deduction
+ * ledger. The agent's published score is presentation data only.
  *
- * Two live runs over an identical four-file set returned 83/100 and 92/100, and
- * the lower one printed a breakdown that summed to 92, so a published score
- * cannot be trusted on its face. The ledger in `test-review-template.md` is the
- * workflow's only scoring model, which makes it recomputable here from the
- * violation counts the report already declares.
+ * Live runs have repeatedly published arithmetic that contradicts their own
+ * ledgers. The ledger in `test-review-template.md` is the workflow's only
+ * scoring model, so the CLI derives the score from the violation counts and
+ * bonus instead of asking a probabilistic producer to perform gate arithmetic.
  *
  * The breakdown sits inside a fenced block, which the verdict scan strips, so
  * this reads the raw report instead and anchors on the section heading: only
  * the ledger under "## Quality Score Breakdown" is ever consulted.
  */
-function verifyScoreLedger(rawText, qualityScore, violations) {
+function deriveQualityScore(rawText, violations) {
   // extractSection's regex takes the first match; on raw (fence-intact) text
   // that is exploitable if the reviewed file's own quoted content contains a
   // second "## Quality Score Breakdown" heading earlier in the report than
@@ -488,13 +487,64 @@ function verifyScoreLedger(rawText, qualityScore, violations) {
     const key = level.toLowerCase();
     return sum + violations[key] * SEVERITY_DEDUCTIONS[key];
   }, 0);
-  const expected = Math.max(0, Math.min(100, 100 - deductions + bonus));
-  if (expected !== qualityScore) {
-    unparseable(
-      `Report Quality Score ${qualityScore} contradicts its own breakdown: ` +
-        `100 - ${deductions} deductions + ${bonus} bonus = ${expected}`,
-    );
-  }
+  return Math.max(0, Math.min(100, 100 - deductions + bonus));
+}
+
+function gradeForScore(score) {
+  if (score >= 90) return 'A';
+  if (score >= 80) return 'B';
+  if (score >= 70) return 'C';
+  if (score >= 60) return 'D';
+  return 'F';
+}
+
+/** Normalize the report's schema-owned score and grade fields to CLI arithmetic. */
+function normalizeReportScore(reportText, qualityScore) {
+  const grade = gradeForScore(qualityScore);
+  let inFence = false;
+  let section = null;
+  let summaryNormalized = false;
+  let finalScoreNormalized = false;
+  let finalGradeNormalized = false;
+
+  return reportText
+    .split('\n')
+    .map((originalLine) => {
+      let line = originalLine;
+      if (/^\s*```/.test(line)) {
+        inFence = !inFence;
+        return line;
+      }
+
+      if (!inFence) {
+        const heading = /^##[ \t]+([^\r\n]+?)[ \t]*\r?$/.exec(line);
+        if (heading) {
+          section = heading[1];
+        }
+        if (!summaryNormalized && /^[ \t]*\*\*Quality Score\*\*:/.test(line)) {
+          line = line
+            .replace(/^([ \t]*\*\*Quality Score\*\*:[ \t]*)\d+([ \t]*\/[ \t]*100)/, `$1${qualityScore}$2`)
+            .replace(/^([ \t]*\*\*Quality Score\*\*:[^\r\n]*\([ \t]*)[A-F](?=[ \t)-])/, `$1${grade}`);
+          summaryNormalized = true;
+        }
+      }
+
+      // The score ledger is itself a fenced block. Its fields remain active
+      // only inside the unique Quality Score Breakdown section validated by
+      // deriveQualityScore; unrelated fenced examples stay untouched.
+      if (section === 'Quality Score Breakdown') {
+        if (!finalScoreNormalized && /^[ \t]*Final Score[ \t]*:/.test(line)) {
+          line = line.replace(/^([ \t]*Final Score[ \t]*:[ \t]*)\d+([ \t]*\/[ \t]*100[ \t]*\r?)$/, `$1${qualityScore}$2`);
+          finalScoreNormalized = true;
+        }
+        if (!finalGradeNormalized && /^[ \t]*Grade[ \t]*:/.test(line)) {
+          line = line.replace(/^([ \t]*Grade[ \t]*:[ \t]*)[A-F]([ \t]*\r?)$/, `$1${grade}$2`);
+          finalGradeNormalized = true;
+        }
+      }
+      return line;
+    })
+    .join('\n');
 }
 
 /**
@@ -502,7 +552,7 @@ function verifyScoreLedger(rawText, qualityScore, violations) {
  *
  * @param {string} reportText - Full test-review.md contents.
  * @param {object} [runContract] - Exact reviewed/context evidence supplied by the runner.
- * @returns {{recommendation: string, qualityScore: number, violations: object,
+ * @returns {{recommendation: string, qualityScore: number, reportedQualityScore?: number, violations: object,
  *   reviewedFiles: string[], contextBasis: string, contextFiles: string[],
  *   contextWaiversApplied: number}}
  * @throws {Error} With code REPORT_UNPARSEABLE on any missing/invalid element.
@@ -522,9 +572,10 @@ function parseReport(reportText, runContract = {}) {
   if (!scoreMatch) {
     unparseable('Report is missing the "**Quality Score**: N/100" line');
   }
-  const qualityScore = Number.parseInt(scoreMatch[1], 10);
-  if (qualityScore < 0 || qualityScore > 100) {
-    unparseable(`Report Quality Score ${qualityScore} is outside the required 0-100 range`);
+  const reportedQualityScore = Number.parseInt(scoreMatch[1], 10);
+  const reportedQualityGrade = scoreMatch[2];
+  if (reportedQualityScore < 0 || reportedQualityScore > 100) {
+    unparseable(`Report Quality Score ${reportedQualityScore} is outside the required 0-100 range`);
   }
 
   const violations = parseViolations(text);
@@ -535,7 +586,7 @@ function parseReport(reportText, runContract = {}) {
     );
   }
 
-  verifyScoreLedger(reportText, qualityScore, violations);
+  const qualityScore = deriveQualityScore(reportText, violations);
 
   const reviewedFiles = parseReviewedFiles(text);
   const contextBasis = parseContextBasis(text);
@@ -560,7 +611,7 @@ function parseReport(reportText, runContract = {}) {
   const keyStrengths = extractBullets(extractSubsection(executiveSection, 'Key Strengths'), '✅');
   const keyWeaknesses = extractBullets(extractSubsection(executiveSection, 'Key Weaknesses'), '❌');
 
-  return {
+  const parsed = {
     recommendation: executive,
     qualityScore,
     violations,
@@ -571,6 +622,13 @@ function parseReport(reportText, runContract = {}) {
     keyStrengths,
     keyWeaknesses,
   };
+  if (
+    reportedQualityScore !== qualityScore ||
+    (reportedQualityGrade !== undefined && reportedQualityGrade !== gradeForScore(qualityScore))
+  ) {
+    parsed.reportedQualityScore = reportedQualityScore;
+  }
+  return parsed;
 }
 
 /**
@@ -599,4 +657,4 @@ function scoreFails(score, minScore) {
   return score < minScore;
 }
 
-module.exports = { parseReport, verdictFor, scoreFails, CONTEXT_BASIS_ENUM };
+module.exports = { parseReport, normalizeReportScore, verdictFor, scoreFails, CONTEXT_BASIS_ENUM };

package/cli/test-review.js

@@ -15,8 +15,9 @@
  *
  * Exit codes: 0 pass/skip (or a verdict failure waived with --waive), 1 review
  * verdict fail (or a skip with --fail-on-skip / a deletions-only diff),
- * 2 environment/config error, 3 agent or parse failure. A waiver never applies
- * to exit 2 or 3: environment, agent, and parse failures are never waivable.
+ * 2 environment/config error, 3 agent, parse, or report-artifact failure. A
+ * waiver never applies to exit 2 or 3: infrastructure failures are never
+ * waivable.
  *
  * Usage:
  *   tea-test-review --base origin/main --agent claude --json test-review.json
@@ -24,6 +25,7 @@
  */
 
 const fs = require('node:fs');
+const { randomUUID } = require('node:crypto');
 const os = require('node:os');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
@@ -41,7 +43,7 @@ const {
   registerExtraTestPattern,
 } = require('./lib/changed-tests');
 const { buildPrompt } = require('./lib/build-prompt');
-const { parseReport, verdictFor, scoreFails } = require('./lib/parse-report');
+const { parseReport, normalizeReportScore, verdictFor, scoreFails } = require('./lib/parse-report');
 const { runAgent } = require('./lib/run-agent');
 const { AGENT_ADAPTERS, resolveModel } = require('./lib/agent-adapters');
 const { withIsolation, selectBackend } = require('./lib/isolate');
@@ -151,6 +153,45 @@ function writeJsonFile(jsonPath, payload) {
   }
 }
 
+function reportArtifactFailure(action, artifactPath, cause) {
+  const error = new Error(`Failed to ${action} report artifact ${artifactPath}: ${cause.message}`);
+  error.code = 'REPORT_ARTIFACT';
+  return error;
+}
+
+function reportTemporaryPath(artifactPath) {
+  return path.join(path.dirname(artifactPath), `.${path.basename(artifactPath)}.${randomUUID()}.tmp`);
+}
+
+function replaceReportArtifact(artifactPath, temporaryPath, writeTemporary) {
+  let temporaryReady = false;
+  try {
+    fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+    writeTemporary(temporaryPath);
+    temporaryReady = true;
+    fs.renameSync(temporaryPath, artifactPath);
+  } catch (error) {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // Preserve the artifact error that caused the failure.
+    }
+    throw reportArtifactFailure(temporaryReady ? 'replace' : 'prepare', artifactPath, error);
+  }
+}
+
+function copyReportArtifact(sourcePath, artifactPath, temporaryPath) {
+  replaceReportArtifact(artifactPath, temporaryPath, (temporary) => {
+    fs.copyFileSync(sourcePath, temporary);
+  });
+}
+
+function writeReportArtifact(artifactPath, temporaryPath, content) {
+  replaceReportArtifact(artifactPath, temporaryPath, (temporary) => {
+    fs.writeFileSync(temporary, content, 'utf8');
+  });
+}
+
 function main() {
   const program = new Command();
 
@@ -554,7 +595,8 @@ function main() {
   }
   const runStart = Date.now();
 
-  const writablePaths = [outputPath, ...(jsonPath ? [jsonPath] : [])];
+  const copiedReportTemporaryPath = reportTemporaryPath(outputPath);
+  const normalizedReportTemporaryPath = reportTemporaryPath(outputPath);
   let redirectDir = null;
   let gateFailures = [];
 
@@ -581,28 +623,25 @@ function main() {
     return () => heartbeat.kill();
   };
 
-  const executeRun = ({ agentCwd, spawnPrefix }) => {
-    // Under isolation the agent writes into a fresh tmpdir; the CLI copies the
-    // artifacts back to the requested paths after a successful run.
-    let agentOutputPath = outputPath;
-    let agentJsonPath = jsonPath;
-    if (isolationActive) {
-      redirectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tea-test-review-'));
-      agentOutputPath = path.join(redirectDir, 'test-review.md');
-      agentJsonPath = jsonPath ? path.join(redirectDir, 'verdict.json') : null;
-    }
-
-    const prompt = buildPrompt({
-      skillRoot,
-      files: changedTestFiles,
-      outputPath: agentOutputPath,
-      scope: options.scope,
-      testDir: options.testDir,
-      teaConfig,
-      contextFiles,
-      contextBasis,
-    });
+  // Under isolation the agent writes into a fresh tmpdir. Artifact processing
+  // happens after withIsolation restores the project, so an atomic rename never
+  // needs a project directory to be writable while the agent is running.
+  if (isolationActive) {
+    redirectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tea-test-review-'));
+  }
+  const agentOutputPath = redirectDir ? path.join(redirectDir, 'test-review.md') : outputPath;
+  const prompt = buildPrompt({
+    skillRoot,
+    files: changedTestFiles,
+    outputPath: agentOutputPath,
+    scope: options.scope,
+    testDir: options.testDir,
+    teaConfig,
+    contextFiles,
+    contextBasis,
+  });
 
+  const executeAgent = ({ agentCwd, spawnPrefix }) => {
     const stopHeartbeat = startHeartbeat();
     let agentResult;
     try {
@@ -622,41 +661,45 @@ 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
-      // with the outer redirectDir cleanup below. Thrown errors propagate
-      // through both finally blocks before the outer catch calls fail().
       const error = new Error(
         `Agent finished but no fresh report was written to ${agentOutputPath}; refusing to parse a stale or missing report.`,
       );
       error.code = 'REPORT_MISSING';
       throw error;
     }
+  };
 
+  const processReport = () => {
     // The report is copied back even when the verdict fails or parsing fails;
     // on agent failure nothing was produced and nothing is copied.
     if (redirectDir) {
-      fs.copyFileSync(agentOutputPath, outputPath);
+      copyReportArtifact(agentOutputPath, outputPath, copiedReportTemporaryPath);
     }
 
+    const rawReport = fs.readFileSync(agentOutputPath, 'utf8');
     let parsed;
     try {
-      parsed = parseReport(fs.readFileSync(agentOutputPath, 'utf8'), {
+      parsed = parseReport(rawReport, {
         reviewedFiles: changedTestFiles,
         contextFiles,
         contextBasis,
       });
     } catch (error) {
       if (error.code === 'REPORT_UNPARSEABLE') {
-        // Same reasoning as the freshness check above: throw, don't exit, so
-        // isolation cleanup runs before the process actually terminates.
         const wrapped = new Error(`${error.message} (report: ${outputPath})`);
         wrapped.code = 'REPORT_UNPARSEABLE';
         throw wrapped;
       }
       throw error;
     }
+
+    if (parsed.reportedQualityScore !== undefined) {
+      const normalizedReport = normalizeReportScore(rawReport, parsed.qualityScore);
+      writeReportArtifact(outputPath, normalizedReportTemporaryPath, normalizedReport);
+      console.error(
+        `tea-test-review: normalized agent Quality Score ${parsed.reportedQualityScore} to deterministic ledger score ${parsed.qualityScore}.`,
+      );
+    }
     gateFailures = evaluateGates(parsed);
 
     // The verdict JSON files manifest is the report's own Reviewed Files
@@ -676,41 +719,58 @@ function main() {
     const finalPayload = applyWaiver(verdictPayload, gateFailures.length > 0);
     console.log(JSON.stringify(finalPayload, null, 2));
 
-    if (agentJsonPath) {
+    if (jsonPath) {
       // No freshness check here, unlike the report: the CLI is the only writer of
       // the verdict JSON and writeJsonFile already fails closed on a write error,
       // so a stale verdict is not reachable. The pre-run rm still applies, so a
       // failed run leaves no previous verdict behind.
-      writeJsonFile(agentJsonPath, finalPayload);
-      if (redirectDir) {
-        fs.copyFileSync(agentJsonPath, jsonPath);
+      writeJsonFile(jsonPath, finalPayload);
+    }
+  };
+
+  const cleanupRunArtifacts = () => {
+    for (const temporaryPath of [copiedReportTemporaryPath, normalizedReportTemporaryPath]) {
+      try {
+        fs.rmSync(temporaryPath, { force: true });
+      } catch (error) {
+        console.error(`tea-test-review WARNING: failed to remove temporary report ${temporaryPath}: ${error.message}`);
       }
     }
+    if (redirectDir) {
+      try {
+        fs.rmSync(redirectDir, { recursive: true, force: true });
+      } catch (error) {
+        console.error(`tea-test-review WARNING: failed to remove temporary directory ${redirectDir}: ${error.message}`);
+      }
+      redirectDir = null;
+    }
   };
 
   try {
     if (isolationActive) {
-      withIsolation(projectRoot, writablePaths, executeRun);
+      withIsolation(projectRoot, [], executeAgent);
     } else {
-      executeRun({ agentCwd: projectRoot, spawnPrefix: [] });
+      executeAgent({ agentCwd: projectRoot, spawnPrefix: [] });
     }
+    processReport();
   } catch (error) {
     if (
       error.code === 'AGENT_FAILED' ||
       error.code === 'AGENT_NOT_FOUND' ||
       error.code === 'REPORT_MISSING' ||
-      error.code === 'REPORT_UNPARSEABLE'
+      error.code === 'REPORT_UNPARSEABLE' ||
+      error.code === 'REPORT_ARTIFACT'
     ) {
+      cleanupRunArtifacts();
       fail(EXIT.AGENT_OR_PARSE_ERROR, error.message);
     }
     if (error.code === 'ISOLATION_ERROR') {
+      cleanupRunArtifacts();
       fail(EXIT.ENV_ERROR, error.message);
     }
     throw error;
   } finally {
-    if (redirectDir) {
-      fs.rmSync(redirectDir, { recursive: true, force: true });
-    }
+    cleanupRunArtifacts();
   }
 
   for (const failure of gateFailures) {

package/docs/explanation/test-review-cli-architecture.md

@@ -121,7 +121,7 @@ Same logic on the report: a parse failure is never a silent pass, stale artifact
 
 Prompt contract, parser, and report template are one contract in three files; they version together.
 
-Clearest example: the scoring model. The report template defines the deduction ledger, the prompt states its arithmetic, the parser recomputes the score and rejects anything that contradicts the ledger. Change one without the others and the gate rejects every valid report. Shipping CLI and skill in the same package, same version, prevents that.
+Clearest example: the scoring model. The report template defines the deduction ledger, the prompt states its arithmetic, and the parser computes the authoritative score from the declared violations and bonus. The CLI then normalizes the report before gating, so model arithmetic cannot break CI or control the verdict. Shipping CLI and skill in the same package, same version, keeps that contract synchronized.
 
 ---
 

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

@@ -228,7 +228,7 @@ The report itself is strictly validated:
 
 Fenced code blocks are stripped first, so a quoted example can't spoof a verdict. Markdown emphasis is stripped only where it wraps a whole value, so `tests/user_profile.spec.ts` survives the manifest intact.
 
-The score is recomputed rather than trusted: the CLI evaluates `100 - (Critical × 10 + High × 5 + Medium × 2 + Low × 1) + Total Bonus` against the report's own violation counts, and rejects a score that contradicts its breakdown, a bonus total outside the legal multiples of 5 from 0 to 30, or a missing breakdown section. The prompt states this same arithmetic.
+The score is computed rather than trusted: the CLI evaluates `100 - (Critical × 10 + High × 5 + Medium × 2 + Low × 1) + Total Bonus` from the report's violation counts and bonus. That result becomes the verdict score, and the CLI normalizes the report's score and grade fields before publishing it. The original model value is retained as `reportedQualityScore` metadata when corrected. An invalid bonus total or missing breakdown still fails closed. The prompt states this same arithmetic.
 
 A report declaring Critical violations alongside an approve-type recommendation is rejected as an inconsistent verdict (exit 3): Critical means Must Fix. Stale artifacts are never parsed, output files are deleted before the run and must be freshly written by it.
 

package/package.json

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

package/src/workflows/testarch/bmad-testarch-test-review/test-review-template.md

@@ -99,7 +99,7 @@ Grade:                   {grade}
      Every bonus line is 0 or 5, never a partial value, and the six categories above are the
      complete set. {grade} is exactly one of A, B, C, D, F, with no modifier such as A+ or B-.
      The lines above must sum to {final_score}, which must equal the **Quality Score** line;
-     headless runners recompute the ledger and reject a report whose arithmetic disagrees. -->
+     headless runners compute the authoritative result and normalize score and grade fields. -->
 
 ---
 

package/test/fixtures/test-review-cli/reports/score-mismatch.md

@@ -5,17 +5,21 @@ stepsCompleted:
   - step-04-generate-report
 ---
 
-# Test Quality Review: mismatch.spec.ts
+# Test Quality Review: alert-preferences-dogfood.spec.ts
 
-**Quality Score**: 95/100 (A)
-**Review Date**: 2026-07-30
+```markdown
+**Quality Score**: 42/100 (F - Example only)
+```
+
+**Quality Score**: 86/100 (B)
+**Review Date**: 2026-08-04
 **Review Scope**: single
 
 ## Executive Summary
 
-**Overall Assessment**: Excellent
+**Overall Assessment**: Needs Improvement
 
-**Recommendation**: Approve
+**Recommendation**: Approve with Comments
 
 **Context Basis**: none
 
@@ -23,11 +27,11 @@ stepsCompleted:
 
 ### Summary
 
-Two High violations deduct 10 with no bonus, so the ledger lands on 90 while the
-report publishes 95. This is the shape a live run produced: a breakdown that
-does not sum to the score printed above it.
+Two High and two Medium violations deduct 14. A five-point bonus makes the
+authoritative score 91, while this live Codex report published 86 because it
+forgot to add the bonus.
 
-**Total Violations**: 0 Critical, 2 High, 0 Medium, 0 Low
+**Total Violations**: 0 Critical, 2 High, 2 Medium, 0 Low
 
 ## Quality Score Breakdown
 
@@ -35,19 +39,19 @@ does not sum to the score printed above it.
 Starting Score:          100
 Critical Violations:     -0 × 10 = -0
 High Violations:         -2 × 5 = -10
-Medium Violations:       -0 × 2 = -0
+Medium Violations:       -2 × 2 = -4
 Low Violations:          -0 × 1 = -0
 
-Total Bonus:             +0
+Total Bonus:             +5
 
-Final Score:             95/100
-Grade:                   A
+Final Score:             86/100
+Grade:                   B
 ```
 
 ## Decision
 
-**Recommendation**: Approve
+Recommendation: Approve with Comments
 
 ## Reviewed Files
 
-tests/mismatch.spec.ts
+playwright/tests/api/alert-preferences-dogfood.spec.ts

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

@@ -10,7 +10,8 @@
  *
  *   STUB_MODE          approve (default) | approve-low | block | request-changes |
  *                      request-changes-critical | critical-approve | conflict |
- *                      partial | nothing | fail | forbidden-write | stale-copy
+ *                      score-mismatch | partial | nothing | fail |
+ *                      forbidden-write | stale-copy
  *   STUB_ASSERT_STDIN  when "1", fail if the prompt did not arrive on stdin or
  *                      if any of it leaked into argv
  *   STUB_ASSERT_MODEL  expected model value; fail unless argv carries a model
@@ -22,6 +23,8 @@
  *                      manifest. Adversarial tests use it to prove the CLI
  *                      binds report claims to the supplied context set.
  *   STUB_OLD_REPORT    stale-copy source: a report pre-placed with an old mtime
+ *   STUB_LOCK_OUTPUT   when "1", make the report and its parent read-only after
+ *                      writing so artifact replacement failure handling runs
  */
 
 const fs = require('node:fs');
@@ -35,6 +38,7 @@ const REPORTS = {
   'request-changes-critical': 'request-changes-critical.md',
   'critical-approve': 'critical-approve.md',
   conflict: 'conflicting.md',
+  'score-mismatch': 'score-mismatch.md',
   partial: 'malformed.md',
 };
 
@@ -160,6 +164,10 @@ function writeFixtureReport(fixtureName) {
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   const report = fs.readFileSync(path.join(__dirname, 'reports', fixtureName), 'utf8');
   fs.writeFileSync(outputPath, bindReportToPrompt(report));
+  if (process.env.STUB_LOCK_OUTPUT === '1') {
+    fs.chmodSync(outputPath, 0o444);
+    fs.chmodSync(path.dirname(outputPath), 0o555);
+  }
 }
 
 if (mode === 'forbidden-write') {

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

@@ -47,7 +47,7 @@ const { spawnSync } = require('node:child_process');
 const vm = require('node:vm');
 const yaml = require('js-yaml');
 
-const { parseReport, verdictFor, scoreFails, CONTEXT_BASIS_ENUM } = require('../cli/lib/parse-report');
+const { parseReport, normalizeReportScore, verdictFor, scoreFails, CONTEXT_BASIS_ENUM } = require('../cli/lib/parse-report');
 const {
   isTestFile,
   isContextNoise,
@@ -353,7 +353,6 @@ async function runTests() {
       ['missing-violations.md', 'no Total Violations line'],
       ['missing-frontmatter.md', 'no YAML frontmatter'],
       ['empty-steps-flow.md', 'wrapped stepsCompleted flow sequence with no entries'],
-      ['score-mismatch.md', 'published score contradicts its own deduction ledger'],
       ['bonus-not-multiple.md', 'bonus total is not a multiple of the 5-point category value'],
       ['missing-breakdown.md', 'no Quality Score Breakdown, so the score cannot be recomputed'],
       ['duplicate-breakdown-heading.md', 'two Quality Score Breakdown headings, so neither can be trusted as the real ledger'],
@@ -373,6 +372,45 @@ async function runTests() {
       }
     }
 
+    // Regression from couture-cast run 30897431283: Codex correctly declared
+    // its deductions and bonus, then published arithmetic that omitted the
+    // bonus. Derived
+    // arithmetic belongs to the CLI, while the model remains responsible for
+    // the findings, severity counts, and bonus declarations.
+    try {
+      const source = readFixture('reports', 'score-mismatch.md');
+      const corrected = parseReport(source);
+      assert(
+        corrected.qualityScore === 91 && corrected.reportedQualityScore === 86,
+        'score-mismatch fixture: CLI derives 91/A and preserves the agent-reported 86/B score as metadata',
+        JSON.stringify(corrected),
+      );
+      const normalized = normalizeReportScore(source, corrected.qualityScore);
+      assert(
+        normalized.includes('**Quality Score**: 42/100 (F - Example only)') &&
+          normalized.includes('**Quality Score**: 91/100 (A)') &&
+          normalized.includes('Final Score:             91/100') &&
+          normalized.includes('Grade:                   A'),
+        'score-mismatch fixture: every active score and grade field normalizes while an earlier fenced example stays untouched',
+        normalized,
+      );
+    } catch (error) {
+      assert(false, 'score-mismatch fixture is corrected deterministically', error.message);
+    }
+
+    try {
+      const source = readFixture('reports', 'approve.md').replace('93/100 (A)', '93/100 (F)');
+      const corrected = parseReport(source);
+      const normalized = normalizeReportScore(source, corrected.qualityScore);
+      assert(
+        corrected.qualityScore === 93 && corrected.reportedQualityScore === 93 && normalized.includes('**Quality Score**: 93/100 (A)'),
+        'grade-only mismatch triggers normalization even when the reported numeric score is correct',
+        JSON.stringify(corrected),
+      );
+    } catch (error) {
+      assert(false, 'grade-only score mismatch is corrected deterministically', error.message);
+    }
+
     try {
       parseReport(readFixture('reports', 'conflicting.md'));
       assert(false, 'conflicting fixture error message calls out the conflict');
@@ -1164,15 +1202,16 @@ async function runTests() {
       'prompt requires Quality Score 0-100',
     );
     assert(prompt.includes('**Total Violations**: line is required'), 'prompt requires the Total Violations line');
-    // The parser recomputes the ledger, so the prompt has to state the same
-    // model; a strict check the producer was never told about is a false FAIL.
+    // The parser computes the authoritative score, so the prompt has to state
+    // the same model and make clear that agent arithmetic is provisional.
     assert(
-      prompt.includes('"## Quality Score Breakdown" section is required and its ledger must reproduce the score'),
-      'prompt requires a breakdown that reproduces the score',
+      prompt.includes('"## Quality Score Breakdown" section is required') &&
+        prompt.includes('replaces it with the deterministic ledger result before gating'),
+      'prompt identifies the ledger as the CLI-owned score source',
     );
     assert(
       prompt.includes('100 - (Critical×10 + High×5 + Medium×2 + Low×1) + Total Bonus'),
-      'prompt states the deduction ledger the CLI recomputes',
+      'prompt states the deduction ledger the CLI computes',
     );
     assert(prompt.includes('multiple of 5 from 0 to 30'), 'prompt bounds the bonus total to legal category values');
     assert(prompt.includes('exactly one of A, B, C, D, F'), 'prompt bounds the grade scale');
@@ -1751,6 +1790,92 @@ async function runTests() {
       assert(false, 'verdict JSON parses', error.message);
     }
 
+    const normalizedScoreOut = path.join(tmpRoot, 'normalized-score-run', 'test-review.md');
+    const normalizedScoreJsonPath = path.join(tmpRoot, 'normalized-score-run', 'verdict.json');
+    const normalizedScoreRun = runCli(
+      [
+        '--files',
+        'playwright/tests/api/alert-preferences-dogfood.spec.ts',
+        '--project-root',
+        fixtureProject,
+        '--output',
+        normalizedScoreOut,
+        '--json',
+        normalizedScoreJsonPath,
+        '--agent-cmd',
+        stubAgent,
+        '--no-isolate',
+        ...stubPass('STUB_MODE'),
+      ],
+      { STUB_MODE: 'score-mismatch' },
+    );
+    assert(
+      normalizedScoreRun.status === 0 && normalizedScoreRun.stderr.includes('normalized agent Quality Score 86'),
+      'score arithmetic mismatch is normalized instead of failing the run',
+      `status=${normalizedScoreRun.status} stderr=${normalizedScoreRun.stderr}`,
+    );
+    try {
+      const normalizedPayload = JSON.parse(fs.readFileSync(normalizedScoreJsonPath, 'utf8'));
+      const normalizedReport = fs.readFileSync(normalizedScoreOut, 'utf8');
+      assert(
+        normalizedPayload.qualityScore === 91 && normalizedPayload.reportedQualityScore === 86,
+        'normalized verdict JSON uses the CLI score crossing into grade A and preserves the agent score',
+        JSON.stringify(normalizedPayload),
+      );
+      assert(
+        normalizedReport.includes('**Quality Score**: 42/100 (F - Example only)') &&
+          normalizedReport.includes('**Quality Score**: 91/100 (A)') &&
+          normalizedReport.includes('Final Score:             91/100') &&
+          normalizedReport.includes('Grade:                   A'),
+        'normalized report publishes the same derived score and grade as the verdict JSON while preserving fenced examples',
+        normalizedReport,
+      );
+    } catch (error) {
+      assert(false, 'normalized score artifacts are readable', error.message);
+    }
+
+    const artifactPermissionsTestable = process.platform !== 'win32' && !(typeof process.getuid === 'function' && process.getuid() === 0);
+    if (artifactPermissionsTestable) {
+      const lockedArtifactDir = path.join(tmpRoot, 'locked-normalized-score-run');
+      const lockedArtifactOut = path.join(lockedArtifactDir, 'test-review.md');
+      const lockedArtifactRun = runCli(
+        [
+          '--files',
+          'playwright/tests/api/alert-preferences-dogfood.spec.ts',
+          '--project-root',
+          fixtureProject,
+          '--output',
+          lockedArtifactOut,
+          '--agent-cmd',
+          stubAgent,
+          '--no-isolate',
+          ...stubPass('STUB_MODE', 'STUB_LOCK_OUTPUT'),
+        ],
+        { STUB_MODE: 'score-mismatch', STUB_LOCK_OUTPUT: '1' },
+      );
+      let preservedArtifact = '';
+      try {
+        preservedArtifact = fs.readFileSync(lockedArtifactOut, 'utf8');
+      } finally {
+        fs.chmodSync(lockedArtifactDir, 0o755);
+        if (fs.existsSync(lockedArtifactOut)) {
+          fs.chmodSync(lockedArtifactOut, 0o644);
+        }
+      }
+      assert(
+        lockedArtifactRun.status === 3 && lockedArtifactRun.stderr.includes('Failed to prepare report artifact'),
+        'normalized report write failures are classified as report-artifact failures',
+        `status=${lockedArtifactRun.status} stderr=${lockedArtifactRun.stderr}`,
+      );
+      assert(
+        preservedArtifact.includes('**Quality Score**: 86/100 (B)') && !preservedArtifact.includes('**Quality Score**: 91/100 (A)'),
+        'failed normalized report writes preserve the original agent artifact',
+        preservedArtifact,
+      );
+    } else {
+      skip('normalized report write failure preserves the original artifact', 'filesystem permissions cannot be enforced');
+    }
+
     // --agent selects the adapter (codex here, not just the claude default);
     // --agent-cmd still only overrides the executable on top of it.
     const codexAdapterOut = path.join(tmpRoot, 'codex-adapter-run', 'test-review.md');