feat(review): the review is a gate - verdict in the file, CC engine, project memory

Ordre 5 (wave 1, P11 + P5), review_version 1.1.

- K7: `verdict: ALLOW | WARN | BLOCK` is required in review.md (strict
  error, soft warning for 1.0 reviews). New CLI lib/review/verdict-gate.mjs:
  0 = ALLOW/WARN, 1 = BLOCK, 2 = could not decide (never green); a verdict
  greener than the file's own BLOCKERs or JSON block is exit 2. Realpath
  main guard (the old file:// guard exits 0 under a symlink - measured).
- No finding is struck for length: succinctness trims only MINOR/SUGGESTION
  text (catalogue tier), keeps BLOCKER/MAJOR whole, counts trims; the
  coordinator lists what it declined to judge.
- Claude Code's /code-review and /security-review run as the engine via the
  Skill tool (never --fix/--comment/--post/ultra); lib/review/engine-findings.mjs
  turns their findings into a reviewer payload; two catalogue keys
  (CODE_REVIEW_DEFECT, SECURITY_REVIEW_VULNERABILITY), catalogue 12 -> 14.
  An engine that did not run forbids ALLOW.
- Every BLOCKER is written as a numbered `### Step R<n>` with its source
  finding (strict error REVIEW_MISSING_REMEDIATION_STEP).
- P5: lib/review/recurrence.mjs - a finding class in two review.md files
  (current + git history, no new store) becomes one proposal, routed by the
  catalogue's memory_route; written only between Voyage markers in
  .claude/rules/voyage-review-lessons.md under a size budget, CLAUDE.md gets
  a pointer only; the operator approves every line (Phase 8.7).
- Workflow substrate: catalogue enum in step; a missing reviewer or engine
  forbids ALLOW there too (it returned ALLOW on zero findings before).
- Fixtures review-run-A/B said WARN over a BLOCKER; now BLOCK.

Borrowed and credited in code: Superpowers (declined-to-judge), ai-native-sdlc
(cap only nits; mistake/fix/check), Spec Kit (managed block; converge steps),
Pocock (retro routing), Kiro (verdict file + gate; evidence per lesson),
Cherny (engine -> brief control order; review -> memory; budget).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

lib/review/verdict-gate.mjs

@@ -0,0 +1,127 @@
+// lib/review/verdict-gate.mjs
+// K7 — the review verdict gate (ordre 5, P11).
+//
+// One command decides on the verdict written in review.md, so whatever stops a
+// merge or a release reads a file and an exit code, never a model's summary:
+//
+//   node lib/review/verdict-gate.mjs [--json] <review.md>
+//     0 = ALLOW or WARN
+//     1 = BLOCK
+//     2 = could not decide: missing/unreadable file, not a review, no verdict,
+//         an unknown verdict, or a file that contradicts its own verdict.
+//         Exit 2 is NEVER green.
+//
+// Fail-closed reading: a missing `verdict` is exit 2, never ALLOW. A verdict
+// that is GREENER than the file's own findings (ALLOW/WARN over a BLOCKER, or a
+// frontmatter verdict the trailing JSON block disagrees with) is exit 2 as well
+// — the file cannot be trusted for the direction that would let work through.
+// BLOCK always exits 1: a stricter-than-supported verdict is still a stop.
+//
+// Borrowed: the verdict goes to a file and a command check gates on it
+// (Kiro `feature-pipeline`, https://kiro.dev/docs/workflows/patterns); the
+// executor may read the verdict but never write it (Spec Kit
+// `templates/checklist-template.md:8-9`, MIT). The blocking itself is Voyage's
+// own design — neither source blocks on its own.
+
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { validateReviewContent, VERDICT_VALUES } from '../validators/review-validator.mjs';
+import { extractFindingsBlock } from './findings-schema.mjs';
+
+export const EXIT = Object.freeze({ PASS: 0, BLOCK: 1, UNDECIDED: 2 });
+
+function undecided(reason, verdict = null) {
+  return { exit: EXIT.UNDECIDED, verdict, reason };
+}
+
+/**
+ * Decide on review.md text. Pure: no I/O.
+ * @param {string} text
+ * @returns {{ exit: 0|1|2, verdict: string|null, reason: string }}
+ */
+export function decideVerdict(text) {
+  const r = validateReviewContent(text, { strict: false });
+  const fm = r.parsed?.frontmatter ?? {};
+  if (!r.valid) {
+    const codes = (r.errors ?? []).map((e) => e.code).join(', ');
+    return undecided(`not a readable review.md (${codes || 'parse failure'})`);
+  }
+  const verdict = fm.verdict;
+  if (verdict === undefined || verdict === null || verdict === '') {
+    return undecided('review.md carries no verdict (K7: required) — never read as ALLOW');
+  }
+  if (!VERDICT_VALUES.includes(verdict)) {
+    return undecided(`unknown verdict ${JSON.stringify(verdict)}`);
+  }
+  if (verdict === 'BLOCK') {
+    return { exit: EXIT.BLOCK, verdict, reason: 'verdict BLOCK' };
+  }
+
+  // ALLOW / WARN: the file must back the greener direction.
+  const block = extractFindingsBlock(r.parsed.body ?? '');
+  if (block === null) {
+    return undecided(`verdict ${verdict} has no trailing JSON block to back it`, verdict);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(block);
+  } catch (e) {
+    return undecided(`trailing JSON block does not parse: ${e.message}`, verdict);
+  }
+  if (payload?.verdict !== undefined && payload.verdict !== verdict) {
+    return undecided(`frontmatter verdict ${verdict} disagrees with the JSON block verdict ${payload.verdict}`, verdict);
+  }
+  const blockerFindings = Array.isArray(payload?.findings)
+    ? payload.findings.filter((f) => f?.severity === 'BLOCKER').length
+    : 0;
+  const blockerCount = Number(payload?.counts?.BLOCKER ?? 0);
+  if (blockerFindings > 0 || blockerCount > 0) {
+    return undecided(`verdict ${verdict} over ${Math.max(blockerFindings, blockerCount)} BLOCKER finding(s)`, verdict);
+  }
+  return { exit: EXIT.PASS, verdict, reason: `verdict ${verdict}` };
+}
+
+/**
+ * Decide on a review.md path.
+ * @param {string} filePath
+ */
+export function decideVerdictFile(filePath) {
+  if (!filePath || !existsSync(filePath)) return undecided(`file not found: ${filePath}`);
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    return undecided(`cannot read ${filePath}: ${e.message}`);
+  }
+  return decideVerdict(text);
+}
+
+function isMain() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const args = process.argv.slice(2);
+  const filePath = args.find((a) => !a.startsWith('--'));
+  if (!filePath) {
+    process.stderr.write('Usage: verdict-gate.mjs [--json] <review.md>\n');
+    process.exit(EXIT.UNDECIDED);
+  }
+  let result;
+  try {
+    result = decideVerdictFile(filePath);
+  } catch (e) {
+    result = undecided(`gate crashed: ${e.message}`);
+  }
+  if (args.includes('--json')) {
+    process.stdout.write(JSON.stringify({ path: filePath, ...result }) + '\n');
+  } else {
+    const label = result.exit === EXIT.UNDECIDED ? 'UNDECIDED (not green)' : result.verdict;
+    process.stdout.write(`verdict-gate: ${label} — ${result.reason} — ${filePath}\n`);
+  }
+  process.exit(result.exit);
+}