@webpieces/rules-config 0.4.534 → 0.4.536

package/src/review-json.js

@@ -13,181 +13,23 @@ const constants_1 = require("./constants");
 const state_dir_1 = require("./state-dir");
 const inform_ai_error_1 = require("./inform-ai-error");
 const to_error_1 = require("./to-error");
-// The three colors a reviewer subagent may report in `review-<id>.json`. A TRI-state, not a boolean,
-// because the boolean it replaced gave a reviewer no way to say "this passes, but a human should look at
-// X" — the only way to raise a concern was to FAIL the PR and then override your own failure, which reads
-// on the dashboard as a deliberately-accepted defect rather than as a note.
-exports.VERDICT_GREEN = 'green';
-exports.VERDICT_YELLOW = 'yellow';
-exports.VERDICT_RED = 'red';
-exports.VERDICT_STATUSES = [exports.VERDICT_GREEN, exports.VERDICT_YELLOW, exports.VERDICT_RED];
-// The verdict a reviewer SUBAGENT writes into `.webpieces/pr-review/<branch>/review-<id>.json`, one per
-// matched checklist. One file per checklist so N concurrent reviewer subagents never clobber a shared
-// file. It records the OUTCOME:
-//   status:'green'                  → PASS
-//   status:'yellow'                 → WARN (passes; the concern is published on the PR, nothing is blocked)
-//   status:'red' + override non-empty → OVERRIDDEN (pass; the free-text justification reaches the PR)
-//   status:'red' + no override      → FAIL (refuse; `output` is printed verbatim)
-// `override` is deliberately free text, not a boolean — it forces the ship-anyway decision to be stated
-// in words and surfaces it on the dashboard, where a human sees it. Data-only (per CLAUDE.md).
-class ChecklistResult {
-    id;
-    status; // one of VERDICT_STATUSES; anything else is reported via `problem`
-    output; // what the reviewer found; printed verbatim when the checklist fails
-    override; // '' = no override; non-empty = ship-anyway justification (renders 🟠 overridden)
-    // '' = a well-formed verdict. Non-empty = the file exists and parses but its verdict cannot be READ
-    // (most often: it still uses the removed `success` field). Carried as data rather than thrown so the
-    // complaint can be reported by BOTH wp-review-upsert-pr and wp-finish-upsert-pr in identical words, and so a
-    // legacy file is never silently mistaken for a missing one.
-    problem;
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(id, status, output, override, problem = '') {
-        this.id = id;
-        this.status = status;
-        this.output = output;
-        this.override = override;
-        this.problem = problem;
-    }
-}
-exports.ChecklistResult = ChecklistResult;
-// What the pr-gate command computed from the diff: a checklist this branch MATCHED (its patterns hit the
-// diff, so its reviewer subagent must run). Drives review-<id>.json enforcement, provenance, the schema
-// hint, and the dashboard. Data-only.
-class RequiredChecklist {
-    id; // = subagent name; keys review-<id>.json
-    subagent; // reviewer agent that must run (agentType the harness stamps)
-    doc; // REPO-RELATIVE guidance doc the reviewer reads ('' → it just reads the diff)
-    matchedFiles; // the changed files that matched it (for the dashboard + hint)
-    // Which of the checklist's OWN globs actually fired. Printed so a reviewer can judge how coarse the
-    // match was — a precise `db/migrations/**` hit means something different from a blanket `**` — and the
-    // template tells reviewers that matching IS deliberately coarse. [] = no patterns (matches every PR).
-    matchedPatterns;
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(id, subagent, doc, matchedFiles, matchedPatterns = []) {
-        this.id = id;
-        this.subagent = subagent;
-        this.doc = doc;
-        this.matchedFiles = matchedFiles;
-        this.matchedPatterns = matchedPatterns;
-    }
-}
-exports.RequiredChecklist = RequiredChecklist;
-/**
- * The per-PR facts every reviewer subagent needs GIVEN to it, alongside its own checklist: the exact base
- * sha the gate diffs against and the file holding the complete changed-file set. Both used to live only in
- * a doc the printed instruction told the AI to go read, one indirection away from the instruction to hand
- * them over — so the printed block could not stand on its own. Data-only; empty = omit those lines.
- */
-class ChecklistReviewContext {
-    baseSha; // the 3-point merge-base sha
-    prContextPath; // path of pr-context.json — the AUTHORITATIVE full changed-file set
-    /**
-     * The exact command that reproduces ONE file's diff, with a `-- <file>` tail — NOT assembled by the
-     * caller. This used to be hardcoded as `git diff <baseSha> HEAD -- <file>`, which returns NOTHING on a
-     * dirty tree because the changed-file set is computed base→working-tree. See DiffBasis, which derives
-     * this string from the same range the file set came from.
-     */
-    fileDiffCommand;
-    diffDir; // dir of the MATERIALIZED diff (diff/ALL.diff + diff/files/…); '' when not written
-    dirty; // true ⇒ the range includes uncommitted + untracked work, and must be said out loud
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(baseSha = '', prContextPath = '', fileDiffCommand = '', diffDir = '', dirty = false) {
-        this.baseSha = baseSha;
-        this.prContextPath = prContextPath;
-        this.fileDiffCommand = fileDiffCommand;
-        this.diffDir = diffDir;
-        this.dirty = dirty;
-    }
-}
-exports.ChecklistReviewContext = ChecklistReviewContext;
-// The AI-authored review for a PR. The AI writes review.json itself between `wp-start-upsert-pr` (which
-// prints the schema) and `wp-finish-upsert-pr` (which reads it); reviewer subagents write the per-checklist
-// review-<id>.json files. Data-only (per CLAUDE.md).
-class ReviewJson {
-    title; // human PR title describing the change; used as the `gh pr` title (empty → caller falls back)
-    riskScore; // 0–100, drives the risk bar
-    riskLevel; // 'green' | 'yellow' | 'red'
-    riskEmoji; // '🟢' | '🟡' | '🔴' — derived from riskLevel when omitted
-    summary; // rendered in the dashboard Summary section
-    violations; // pattern/architecture violations; length = the Pattern Violations count
-    risks;
-    filesToReview;
-    results; // resolved per-checklist verdicts (from review-<id>.json); [] when none
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(title, riskScore, riskLevel, riskEmoji, summary, violations, risks, filesToReview, results = []) {
-        this.title = title;
-        this.riskScore = riskScore;
-        this.riskLevel = riskLevel;
-        this.riskEmoji = riskEmoji;
-        this.summary = summary;
-        this.violations = violations;
-        this.risks = risks;
-        this.filesToReview = filesToReview;
-        this.results = results;
-    }
-}
-exports.ReviewJson = ReviewJson;
-// A checklist's resolved outcome, shared by review.json enforcement and the dashboard so both agree.
-// PASS, WARN and OVERRIDDEN all ship; FAIL, MISSING and BAD_FORMAT all refuse the PR.
-exports.CK_PASS = 'pass'; // review-<id>.json status:'green'
-exports.CK_WARN = 'warn'; // review-<id>.json status:'yellow' → 🟡 passes WITH concerns
-exports.CK_OVERRIDDEN = 'overridden'; // review-<id>.json status:'red' + non-empty override → 🟠
-exports.CK_FAIL = 'fail'; // review-<id>.json status:'red' + no override → refuse
-exports.CK_MISSING = 'missing'; // no review-<id>.json written → refuse
-exports.CK_BAD_FORMAT = 'bad-format'; // written, but its verdict is unreadable (e.g. legacy `success`)
-class ChecklistVerdict {
-    id;
-    status; // one of CK_PASS | CK_WARN | CK_OVERRIDDEN | CK_FAIL | CK_MISSING | CK_BAD_FORMAT
-    detail; // reviewer output / override justification / format complaint (dashboard + errors)
-    constructor(id, status, detail) {
-        this.id = id;
-        this.status = status;
-        this.detail = detail;
-    }
-}
-exports.ChecklistVerdict = ChecklistVerdict;
-// The PR's diff context, written by wp-start-upsert-pr into `.webpieces/pr-review/<branch>/pr-context.json`
-// so a reviewer subagent knows the exact 3-point base the gate used and the full changed-file set — then
-// reads any file's actual diff with `git diff <base> HEAD -- <file>`. This is what lets a checklist match
-// coarsely by path (in the config) while the subagent makes the fine, content-level judgment. Data-only.
-class PrContext {
-    base; // the 3-point merge-base sha the gate diffs against
-    /**
-     * The real HEAD sha. This was once the literal string 'HEAD', which is not a fact — it cannot be
-     * compared later to detect that the tree moved under a review, and it reads as a range that was never
-     * actually diffed. Its only reader (reviewContextFor) takes `base`, so recording the sha is free.
-     */
-    head;
-    changedFiles; // every file changed in the range (NOT tsOnly — includes .sql/.gql/Dockerfile/…)
-    dirty; // true ⇒ changedFiles includes uncommitted + untracked work
-    dirtyFiles; // exactly which paths are uncommitted/untracked — why `dirty` is true
-    diffCommand; // the command that reproduces the WHOLE diff (see DiffBasis; correct when dirty)
-    diffDir; // dir holding the materialized per-file diffs + ALL.diff; '' when not materialized
-    generatedAt; // ISO timestamp, so a stale context is detectable rather than silently trusted
-    /**
-     * Main's head as this clone last saw it — the THIRD hash point, matching the trio the 3-point merge
-     * records in `merge-info/<branch>/updatemain-hashes.json`. `base`/`head` above are points A and B
-     * under the review side's older names.
-     *
-     * The review side used to record only A and B, so nothing could answer "did main move while this was
-     * under review?" — the question you most want answered when a review looks stale. '' when origin/main
-     * is unresolvable. Purely informational; nothing gates on it.
-     */
-    hashMainHead;
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(base, head, changedFiles, dirty = false, dirtyFiles = [], diffCommand = '', diffDir = '', generatedAt = '', hashMainHead = '') {
-        this.hashMainHead = hashMainHead;
-        this.base = base;
-        this.head = head;
-        this.changedFiles = changedFiles;
-        this.dirty = dirty;
-        this.dirtyFiles = dirtyFiles;
-        this.diffCommand = diffCommand;
-        this.diffDir = diffDir;
-        this.generatedAt = generatedAt;
-    }
-}
-exports.PrContext = PrContext;
+const review_json_data_1 = require("./review-json-data");
+Object.defineProperty(exports, "VERDICT_GREEN", { enumerable: true, get: function () { return review_json_data_1.VERDICT_GREEN; } });
+Object.defineProperty(exports, "VERDICT_YELLOW", { enumerable: true, get: function () { return review_json_data_1.VERDICT_YELLOW; } });
+Object.defineProperty(exports, "VERDICT_RED", { enumerable: true, get: function () { return review_json_data_1.VERDICT_RED; } });
+Object.defineProperty(exports, "VERDICT_STATUSES", { enumerable: true, get: function () { return review_json_data_1.VERDICT_STATUSES; } });
+Object.defineProperty(exports, "ChecklistResult", { enumerable: true, get: function () { return review_json_data_1.ChecklistResult; } });
+Object.defineProperty(exports, "RequiredChecklist", { enumerable: true, get: function () { return review_json_data_1.RequiredChecklist; } });
+Object.defineProperty(exports, "ChecklistReviewContext", { enumerable: true, get: function () { return review_json_data_1.ChecklistReviewContext; } });
+Object.defineProperty(exports, "ReviewJson", { enumerable: true, get: function () { return review_json_data_1.ReviewJson; } });
+Object.defineProperty(exports, "CK_PASS", { enumerable: true, get: function () { return review_json_data_1.CK_PASS; } });
+Object.defineProperty(exports, "CK_WARN", { enumerable: true, get: function () { return review_json_data_1.CK_WARN; } });
+Object.defineProperty(exports, "CK_OVERRIDDEN", { enumerable: true, get: function () { return review_json_data_1.CK_OVERRIDDEN; } });
+Object.defineProperty(exports, "CK_FAIL", { enumerable: true, get: function () { return review_json_data_1.CK_FAIL; } });
+Object.defineProperty(exports, "CK_MISSING", { enumerable: true, get: function () { return review_json_data_1.CK_MISSING; } });
+Object.defineProperty(exports, "CK_BAD_FORMAT", { enumerable: true, get: function () { return review_json_data_1.CK_BAD_FORMAT; } });
+Object.defineProperty(exports, "ChecklistVerdict", { enumerable: true, get: function () { return review_json_data_1.ChecklistVerdict; } });
+Object.defineProperty(exports, "PrContext", { enumerable: true, get: function () { return review_json_data_1.PrContext; } });
 const RISK_LEVELS = ['green', 'yellow', 'red'];
 const EMOJI_FOR_LEVEL = { green: '🟢', yellow: '🟡', red: '🔴' };
 // Where `wp-finish-upsert-pr` retires the review.json it just consumed, and the note it stamps on the way.
@@ -200,6 +42,15 @@ const ARCHIVE_NOTE = 'ARCHIVE — this is the review from the PREVIOUS wp-finish
     'update, which has since moved. If you are reviewing again, write a FRESH review.json at the path ' +
     'pnpm wp-review-upsert-pr prints; do not copy this file\'s title, summary or risk level forward without ' +
     're-deciding each one. Overwritten by every finish, so only the most recent review is ever here.';
+// The same stamp, for a retired per-checklist verdict. Verdict files get their OWN wording because the two
+// archives answer different questions: old-review.json holds a description of the code, this holds a
+// REVIEWER'S DECISION. The one thing that must not happen is a reader treating an archived red as the live
+// verdict — the whole reason the file was moved rather than copied — so the note says that outright.
+const CHECKLIST_ARCHIVE_NOTE = 'ARCHIVE — this is a checklist verdict from a PREVIOUS reviewer run on this branch, kept for audit ' +
+    'purposes only. It is NOT a live verdict and must never be read back as one: it was RETIRED because it ' +
+    'refused the PR, and the gate moved it here so the only way forward is a FRESH review-<id>.json written ' +
+    'by a real reviewer run. Do not copy its status back onto the live path to get past the gate. ' +
+    'Overwritten by every retirement, so only the most recently retired verdict is ever here.';
 /** Locates + loads/validates the AI-authored review.json. `@injectable(bindingScopeValues.Singleton)` so it's drawn in the design. */
 let ReviewJsonService = class ReviewJsonService {
     dotDir;
@@ -243,24 +94,31 @@ let ReviewJsonService = class ReviewJsonService {
             return '';
         const archivePath = this.oldReviewJsonPath(reviewJsonFilePath);
         const raw = fs.readFileSync(reviewJsonFilePath, 'utf8');
-        fs.writeFileSync(archivePath, this.archivedBody(raw));
+        fs.writeFileSync(archivePath, this.archivedBody(raw, ARCHIVE_NOTE));
         fs.rmSync(reviewJsonFilePath);
         return archivePath;
     }
     /**
-     * The archived bytes: the original review with the AUDIT-ONLY note as its FIRST key, so anything that
-     * opens the file — human or AI — reads what it is before it reads any of its content.
+     * The archived bytes: the original JSON with an AUDIT-ONLY note as its FIRST key, so anything that opens
+     * the file — human or AI — reads what it is before it reads any of its content.
      *
-     * Falls back to the raw bytes when they do not parse. By here `loadReviewJson` has already accepted the
-     * file, so that is close to impossible; preserving the original beats losing it to a stamping failure.
+     * `note` is a parameter rather than a constant because two different files are archived here (review.json
+     * and review-<id>.json) and they need to say different things, while the stamping MECHANICS — parse,
+     * note first, original keys in order, fall back to raw — are identical. One implementation, two texts;
+     * a second copy of this method would be the thing that drifts.
+     *
+     * Falls back to the raw bytes when they do not parse. For review.json `loadReviewJson` has already
+     * accepted the file so that is close to impossible, but a verdict file is written by a subagent and may
+     * be half-written or not an object at all — and preserving the original always beats losing it to a
+     * stamping failure, since the archive exists precisely to be the record.
      */
-    archivedBody(raw) {
+    archivedBody(raw, note) {
         const parsed = this.tryParseObject(raw);
         if (parsed === null)
             return raw;
         // webpieces-disable no-any-unknown -- re-serializing opaque review fields verbatim; only the key ORDER is ours
         const stamped = {};
-        stamped[ARCHIVE_NOTE_KEY] = ARCHIVE_NOTE;
+        stamped[ARCHIVE_NOTE_KEY] = note;
         for (const key of Object.keys(parsed))
             stamped[key] = parsed[key];
         return JSON.stringify(stamped, null, 2) + '\n';
@@ -314,7 +172,7 @@ let ReviewJsonService = class ReviewJsonService {
     reviewContextFor(repoRoot, featureName) {
         const p = this.prContextPath(repoRoot, featureName);
         if (!fs.existsSync(p))
-            return new ChecklistReviewContext();
+            return new review_json_data_1.ChecklistReviewContext();
         // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable context file degrades to fewer printed lines, never a crash
         // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
         try {
@@ -327,12 +185,12 @@ let ReviewJsonService = class ReviewJsonService {
             const cmd = typeof raw['diffCommand'] === 'string' ? raw['diffCommand'] : '';
             const diffDir = typeof raw['diffDir'] === 'string' ? raw['diffDir'] : '';
             const dirty = raw['dirty'] === true;
-            return new ChecklistReviewContext(base, p, cmd === '' ? '' : `${cmd} -- <file>`, diffDir, dirty);
+            return new review_json_data_1.ChecklistReviewContext(base, p, cmd === '' ? '' : `${cmd} -- <file>`, diffDir, dirty);
         }
         catch (err) {
             const error = (0, to_error_1.toError)(err);
             void error;
-            return new ChecklistReviewContext('', p);
+            return new review_json_data_1.ChecklistReviewContext('', p);
         }
     }
     // Copy-paste schema both commands print. `required` is the set of checklists the diff MATCHED; empty
@@ -367,6 +225,43 @@ let ReviewJsonService = class ReviewJsonService {
     checklistResultPath(reviewJsonFilePath, checklistId) {
         return path.join(path.dirname(reviewJsonFilePath), `review-${checklistId}.json`);
     }
+    /**
+     * Where a RETIRED verdict for one checklist goes: `review-<id>.json.old`, beside the live path.
+     *
+     * Mirrors {@link oldReviewJsonPath} deliberately, including its single-slot rule: ALWAYS the same path,
+     * so it holds the last retired verdict and only the last one. A series (`.old.old`, `.old.1`) would read
+     * as though the number of retirements meant something, and nothing downstream can interpret that — the
+     * one fact worth keeping is "this checklist refused before, here is what it said".
+     */
+    oldChecklistResultPath(reviewJsonFilePath, checklistId) {
+        return `${this.checklistResultPath(reviewJsonFilePath, checklistId)}.old`;
+    }
+    /**
+     * Retire one checklist's verdict: MOVE review-<id>.json to review-<id>.json.old, stamped with a note
+     * saying what it is. Returns the archive path, or '' when there was nothing to archive.
+     *
+     * The point is the MOVE, exactly as in {@link archiveReviewJson}. A red verdict left on the live path is
+     * re-read by the next run and re-reported as the CURRENT state of the branch, so the branch keeps being
+     * refused for a finding that may already be fixed — and the fix, when it comes, silently overwrites the
+     * only record that the gate ever refused anything. Moving it makes the refusal durable and makes a fresh
+     * reviewer run the only way forward, which is the honest requirement: the old verdict judged code that
+     * has since changed.
+     *
+     * Safe by construction for RED verdicts specifically, which is why the caller only archives on CK_FAIL:
+     * a red verdict is never reusable — it always blocks — so nothing is lost by moving it. Green and yellow
+     * verdicts ARE deliberately reused across finish attempts, and retiring one would force a needless (and
+     * expensive) subagent re-run.
+     */
+    archiveChecklistResult(reviewJsonFilePath, checklistId) {
+        const livePath = this.checklistResultPath(reviewJsonFilePath, checklistId);
+        if (!fs.existsSync(livePath))
+            return '';
+        const archivePath = this.oldChecklistResultPath(reviewJsonFilePath, checklistId);
+        const raw = fs.readFileSync(livePath, 'utf8');
+        fs.writeFileSync(archivePath, this.archivedBody(raw, CHECKLIST_ARCHIVE_NOTE));
+        fs.rmSync(livePath);
+        return archivePath;
+    }
     /**
      * Load + validate the AI-authored review.json. Throws InformAiError (with the schema) when missing,
      * unparseable, or structurally wrong. `required` is the set of checklists the diff matched: every one
@@ -410,7 +305,7 @@ let ReviewJsonService = class ReviewJsonService {
             ? raw['riskEmoji']
             : (EMOJI_FOR_LEVEL[level] ?? '🟡');
         const summary = typeof raw['summary'] === 'string' ? raw['summary'] : '';
-        return new ReviewJson(title, riskScore, level, emoji, summary, this.asStringArray(raw['violations']), this.asStringArray(raw['risks']), this.asStringArray(raw['filesToReview']), results);
+        return new review_json_data_1.ReviewJson(title, riskScore, level, emoji, summary, this.asStringArray(raw['violations']), this.asStringArray(raw['risks']), this.asStringArray(raw['filesToReview']), results);
     }
     /**
      * The checklists that still OWE a verdict: no review-<id>.json at all, a malformed one, or one whose
@@ -424,12 +319,63 @@ let ReviewJsonService = class ReviewJsonService {
             // CK_WARN must be listed here beside PASS/OVERRIDDEN. A yellow verdict SHIPS — leaving it out
             // would mark the checklist owed forever, so `outstanding` never empties and the PR is refused
             // permanently no matter how many times the reviewer runs.
-            return status !== exports.CK_PASS && status !== exports.CK_WARN && status !== exports.CK_OVERRIDDEN;
+            return status !== review_json_data_1.CK_PASS && status !== review_json_data_1.CK_WARN && status !== review_json_data_1.CK_OVERRIDDEN;
         });
     }
+    /**
+     * The checklists that REFUSED: a reviewer ran, judged the change, and said no (CK_FAIL — status red with
+     * no override). A strict subset of {@link pendingChecklists}, split out because it demands a completely
+     * different action from the reader.
+     *
+     * Public so every command agrees on the set. When "refused" was computed ad hoc, a refusal and a
+     * never-ran reviewer landed in one bucket and produced one message — "you MUST run these N reviewer
+     * subagent(s)" — handed to an AI, which obediently re-spawned a reviewer that had already answered. It
+     * refused again for the same reason, and the loop cost a full subagent run per pass while the reviewer's
+     * actual finding was never shown to anyone. A refusal is a RESULT, not a missing step.
+     */
+    refusedChecklists(required, results) {
+        return required.filter((req) => this.resolveVerdict(req, results).status === review_json_data_1.CK_FAIL);
+    }
+    /**
+     * THE renderer for "this reviewer refused" — one wording, wherever the refusal surfaces. It exists as a
+     * method because the text was previously inlined in {@link requiredChecklistErrors}, reachable only
+     * through review.json validation, while the command layer refused earlier with its own generic message.
+     * Two messages for one event is how the useful one became unreachable; there is now exactly one.
+     *
+     * It always quotes the reviewer's own `output` verbatim: the finding is the whole point, and an error
+     * that names a checklist without saying what it objected to gives the reader nothing to fix.
+     *
+     * `archivedPath` non-empty ⇒ the verdict has just been RETIRED (moved) to that path, so the message must
+     * change in two ways. It says where the record went — otherwise the move reads as data loss — and,
+     * critically, it must NOT tell the reader to "set override in review-<id>.json", because that file no
+     * longer exists. The escape hatch is therefore worded as writing a FRESH verdict file (the body can be
+     * copied back out of the archive) with a human-authored override.
+     */
+    refusalError(req, verdict, archivedPath = '') {
+        const finding = `${verdict.detail.split('\n').join('\n      ')}\n`;
+        const head = `Checklist "${req.id}" FAILED review (status:"${review_json_data_1.VERDICT_RED}"). The reviewer (${req.subagent}) wrote:\n      ` + finding;
+        if (archivedPath === '') {
+            return head +
+                `      Fix it, then re-run; or set a non-empty "override" in ${this.checklistFileName(req.id)} to ship anyway with a stated justification.`;
+        }
+        // Re-spawning is the LAST thing said, and only after the finding, because an instruction to spawn a
+        // subagent is the one line an AI acts on first — see refusedChecklists for what that cost.
+        return head +
+            `      That verdict has been RETIRED to ${archivedPath} (audit only — it is not a live verdict).\n` +
+            `      A FRESH ${this.checklistFileName(req.id)} is now required. Fix the finding first, then have the ` +
+            `"${req.subagent}" subagent review again and write a new verdict.\n` +
+            `      To ship anyway, a HUMAN must decide it: write a fresh ${this.checklistFileName(req.id)} (you may copy the ` +
+            `body back from the archive) carrying a non-empty, human-authored "override" justification.`;
+    }
     // Read the per-checklist verdict files `review-<id>.json` beside review.json — one per matched checklist.
     // A missing file is simply absent from the result (→ counts as MISSING for that checklist); a malformed
     // one is skipped (a stale review-<id>.json never wedges the branch).
+    //
+    // It looks up the EXACT `review-<id>.json` name per required id — never a directory scan, never a prefix
+    // match. That is what guarantees an archived `review-<id>.json.old` can never resolve as a live verdict:
+    // the retired file sits right beside the live path, and a scan that swept the directory would hand a
+    // RETIRED refusal (or worse, a retired pass) back as the current state, undoing the whole point of the
+    // move in {@link archiveChecklistResult}.
     loadChecklistResults(reviewJsonFilePath, required) {
         const results = [];
         for (const req of required) {
@@ -448,16 +394,16 @@ let ReviewJsonService = class ReviewJsonService {
     resolveVerdict(req, results) {
         const result = results.find((r) => r.id === req.id);
         if (!result)
-            return new ChecklistVerdict(req.id, exports.CK_MISSING, '');
+            return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_MISSING, '');
         if (result.problem !== '')
-            return new ChecklistVerdict(req.id, exports.CK_BAD_FORMAT, result.problem);
-        if (result.status === exports.VERDICT_GREEN)
-            return new ChecklistVerdict(req.id, exports.CK_PASS, result.output);
-        if (result.status === exports.VERDICT_YELLOW)
-            return new ChecklistVerdict(req.id, exports.CK_WARN, result.output);
+            return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_BAD_FORMAT, result.problem);
+        if (result.status === review_json_data_1.VERDICT_GREEN)
+            return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_PASS, result.output);
+        if (result.status === review_json_data_1.VERDICT_YELLOW)
+            return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_WARN, result.output);
         if (result.override.trim() !== '')
-            return new ChecklistVerdict(req.id, exports.CK_OVERRIDDEN, result.override.trim());
-        return new ChecklistVerdict(req.id, exports.CK_FAIL, result.output);
+            return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_OVERRIDDEN, result.override.trim());
+        return new review_json_data_1.ChecklistVerdict(req.id, review_json_data_1.CK_FAIL, result.output);
     }
     /**
      * One loud complaint per checklist whose verdict file EXISTS but cannot be read as a verdict — almost
@@ -470,7 +416,7 @@ let ReviewJsonService = class ReviewJsonService {
         const errors = [];
         for (const req of required) {
             const verdict = this.resolveVerdict(req, results);
-            if (verdict.status === exports.CK_BAD_FORMAT)
+            if (verdict.status === review_json_data_1.CK_BAD_FORMAT)
                 errors.push(verdict.detail);
         }
         return errors;
@@ -484,16 +430,16 @@ let ReviewJsonService = class ReviewJsonService {
             const verdict = this.resolveVerdict(req, results);
             // CK_WARN ('yellow' — passed with concerns) is deliberately absent from this chain: it SHIPS.
             // The concern still reaches the PR, published in the checklist comment. Do not "fix" this.
-            if (verdict.status === exports.CK_FAIL) {
-                errors.push(`Checklist "${req.id}" FAILED review (status:"${exports.VERDICT_RED}"). The reviewer (${req.subagent}) wrote:\n      ` +
-                    `${verdict.detail.split('\n').join('\n      ')}\n` +
-                    `      Fix it, then re-run; or set a non-empty "override" in ${this.checklistFileName(req.id)} to ship anyway with a stated justification.`);
+            if (verdict.status === review_json_data_1.CK_FAIL) {
+                // Through the ONE renderer, so this path and the command layer's refusal say the same thing.
+                // No archive path here: this is validation, not the act of retiring the verdict.
+                errors.push(this.refusalError(req, verdict));
             }
-            else if (verdict.status === exports.CK_MISSING) {
+            else if (verdict.status === review_json_data_1.CK_MISSING) {
                 const doc = req.doc.trim() !== '' ? ` Read: ${req.doc}.` : '';
                 errors.push(`Checklist "${req.id}" MATCHED this diff but has no verdict. Spawn the "${req.subagent}" subagent to review it, ` +
                     `then write ${this.checklistFileName(req.id)} with ` +
-                    `{"id":"${req.id}","status":"${exports.VERDICT_GREEN}","output":"…","override":""}.${doc}`);
+                    `{"id":"${req.id}","status":"${review_json_data_1.VERDICT_GREEN}","output":"…","override":""}.${doc}`);
             }
         }
         return errors;
@@ -516,12 +462,12 @@ let ReviewJsonService = class ReviewJsonService {
      */
     verdictSchemaFor(id, verdictPath = '', indent = '      ') {
         const lines = [
-            `${indent}{ "id": "${id}", "status": "${exports.VERDICT_GREEN} | ${exports.VERDICT_YELLOW} | ${exports.VERDICT_RED}", ` +
+            `${indent}{ "id": "${id}", "status": "${review_json_data_1.VERDICT_GREEN} | ${review_json_data_1.VERDICT_YELLOW} | ${review_json_data_1.VERDICT_RED}", ` +
                 `"output": "what you checked / found", "override": "" }`,
-            `${indent}  ${exports.VERDICT_GREEN}  → passes, nothing to flag`,
-            `${indent}  ${exports.VERDICT_YELLOW} → passes WITH CONCERNS; nothing is blocked and the concern is published on the PR`,
-            `${indent}  ${exports.VERDICT_RED}    → REFUSES the PR (set a non-empty "override" to ship anyway with a stated justification)`,
-            `${indent}Prefer "${exports.VERDICT_YELLOW}" over red-plus-override when the change is acceptable but worth a human's`,
+            `${indent}  ${review_json_data_1.VERDICT_GREEN}  → passes, nothing to flag`,
+            `${indent}  ${review_json_data_1.VERDICT_YELLOW} → passes WITH CONCERNS; nothing is blocked and the concern is published on the PR`,
+            `${indent}  ${review_json_data_1.VERDICT_RED}    → REFUSES the PR (set a non-empty "override" to ship anyway with a stated justification)`,
+            `${indent}Prefer "${review_json_data_1.VERDICT_YELLOW}" over red-plus-override when the change is acceptable but worth a human's`,
             `${indent}attention — an override reads as a deliberately-accepted defect, a yellow reads as a note.`,
         ];
         if (verdictPath !== '')
@@ -549,7 +495,7 @@ let ReviewJsonService = class ReviewJsonService {
             const output = typeof raw['output'] === 'string' ? raw['output'] : '';
             const override = typeof raw['override'] === 'string' ? raw['override'] : '';
             const status = typeof raw['status'] === 'string' ? raw['status'].trim().toLowerCase() : '';
-            return new ChecklistResult(id, status, output, override, this.statusProblem(filePath, id, status, raw));
+            return new review_json_data_1.ChecklistResult(id, status, output, override, this.statusProblem(filePath, id, status, raw));
         }
         catch (err) {
             const error = (0, to_error_1.toError)(err);
@@ -566,7 +512,7 @@ let ReviewJsonService = class ReviewJsonService {
     // webpieces-disable no-any-unknown -- opaque parsed JSON; only tested for key presence here
     statusProblem(filePath, id, status, raw) {
         // webpieces-disable no-any-unknown -- comparing against the readonly literal tuple of valid colors
-        if (exports.VERDICT_STATUSES.includes(status))
+        if (review_json_data_1.VERDICT_STATUSES.includes(status))
             return '';
         // The ONE renderer — see verdictSchemaFor. A second copy here is what let the old `success` shape
         // survive in print after it was removed from the parser.
@@ -576,7 +522,7 @@ let ReviewJsonService = class ReviewJsonService {
                 `"status" — there is no compatibility mode. Rewrite the file as:\n${shape}`;
         }
         return `Checklist "${id}" wrote a verdict with no valid "status" (got ${JSON.stringify(status)}). ` +
-            `It must be exactly one of ${exports.VERDICT_STATUSES.join(', ')}:\n${shape}`;
+            `It must be exactly one of ${review_json_data_1.VERDICT_STATUSES.join(', ')}:\n${shape}`;
     }
     // webpieces-disable no-any-unknown -- opaque parsed JSON value, narrowed to string[] here
     asStringArray(value) {