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>
This commit is contained in:
parent
2c89a6b580
commit
d88245c06e
SSH key fingerprint:
SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
28 changed files with 2052 additions and 110 deletions
|
|
@ -18,7 +18,8 @@
|
|||
//
|
||||
// What IS implemented, purely: Pass 1 (triplet dedup → highest-severity-wins
|
||||
// survivor + conformance tiebreak + detail concat + raised_by provenance),
|
||||
// Pass 2 succinctness + actionability-presence, Pass 3 reasonableness
|
||||
// Pass 2 succinctness (trims MINOR/SUGGESTION text, never removes) +
|
||||
// actionability-presence, Pass 3 reasonableness
|
||||
// (citation / unknown-rule_key suppression, severity-mismatch correction),
|
||||
// Pass 4 verdict thresholds — fail-closed: a suppression that did not REFUTE
|
||||
// the finding, and a reviewer that never reported, forbid ALLOW (see
|
||||
|
|
@ -33,6 +34,8 @@
|
|||
import { SEVERITY_VALUES, RULE_KEYS, getRule } from './rule-catalogue.mjs';
|
||||
import { computeFindingId } from '../parsers/finding-id.mjs';
|
||||
import { validateFindings } from './findings-schema.mjs';
|
||||
import { realpathSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
export const JUDGE_TITLE_MAX = 100;
|
||||
export const JUDGE_DETAIL_MAX = 800;
|
||||
|
|
@ -64,14 +67,15 @@ export const REFUTING_REASONS = Object.freeze(new Set([
|
|||
]));
|
||||
|
||||
/**
|
||||
* The reason vocabulary on the unverified side. `file-existence:indeterminate`
|
||||
* The reason vocabulary on the unverified side. Length is not in it: since
|
||||
* ordre 5 (P11) succinctness trims MINOR/SUGGESTION text and never removes a
|
||||
* finding, so `succinctness:*` is no longer emitted (a stray one still fails
|
||||
* closed through `classifySuppression`). `file-existence:indeterminate`
|
||||
* is emitted by the LLM coordinator's Pass 3 (which runs the fs Glob this
|
||||
* module deliberately excludes); the vocabulary is owned here so prose and lib
|
||||
* cannot drift.
|
||||
*/
|
||||
export const UNVERIFIED_REASONS = Object.freeze([
|
||||
'succinctness:title',
|
||||
'succinctness:detail',
|
||||
'actionability:empty',
|
||||
'unknown-rule_key',
|
||||
'file-existence:indeterminate',
|
||||
|
|
@ -185,36 +189,76 @@ export function dedupByTriplet(findings) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Pass 2 — HubSpot Judge (deterministic subset): drop on succinctness
|
||||
* (title > 100 or detail > 800 chars) and actionability (recommended_action,
|
||||
* when present, must be a non-empty string). The imperative-verb test is
|
||||
* excluded (LLM judgement).
|
||||
* The tiers whose over-long text may be trimmed. Length is packaging, never a
|
||||
* claim: a BLOCKER or MAJOR keeps every character, and nothing is ever removed
|
||||
* for length. Borrowed: "cap only the nits, and count what was cut"
|
||||
* (ai-native-sdlc `assets/REVIEW.md:7-23`, MIT).
|
||||
*/
|
||||
export const TRIMMABLE_SEVERITIES = Object.freeze(['MINOR', 'SUGGESTION']);
|
||||
|
||||
export const TRIM_MARKER = ' […trimmed]';
|
||||
|
||||
/**
|
||||
* The tier a finding will be judged at: the catalogue tier when the rule_key is
|
||||
* known (Pass 3 resets to it anyway), else the reviewer-asserted severity. The
|
||||
* trim decision reads this, so a reviewer cannot get a MAJOR trimmed by
|
||||
* mislabelling it MINOR.
|
||||
* @param {object} f
|
||||
* @returns {string}
|
||||
*/
|
||||
function effectiveSeverity(f) {
|
||||
return getRule(f.rule_key)?.severity ?? f.severity;
|
||||
}
|
||||
|
||||
function trimText(text, max) {
|
||||
return text.slice(0, max - TRIM_MARKER.length) + TRIM_MARKER;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pass 2 — HubSpot Judge (deterministic subset): succinctness and
|
||||
* actionability (recommended_action, when present, must be a non-empty
|
||||
* string). The imperative-verb test is excluded (LLM judgement).
|
||||
*
|
||||
* Both tests read a `.length`; neither examines the claim, so neither can
|
||||
* establish the finding is unreal. Both therefore route to `unverified`.
|
||||
* `dropped` stays in the signature for the refuting Pass-2 filter this subset
|
||||
* excludes (Accuracy: a path-traversal escape IS a refutation).
|
||||
* Succinctness never removes a finding (ordre 5, P11 — S118's most serious
|
||||
* finding was struck for a long `detail`). A MINOR/SUGGESTION whose title is
|
||||
* over 100 or detail over 800 characters is TRIMMED, kept, and returned in
|
||||
* `trimmed` so the count is visible; a BLOCKER/MAJOR keeps its full text.
|
||||
*
|
||||
* Actionability reads a `.length`, never the claim, so it cannot establish the
|
||||
* finding is unreal: it routes to `unverified`. `dropped` stays in the
|
||||
* signature for the refuting Pass-2 filter this subset excludes (Accuracy: a
|
||||
* path-traversal escape IS a refutation).
|
||||
* @param {object[]} findings
|
||||
* @returns {{ kept: object[], dropped: object[], unverified: object[] }}
|
||||
* @returns {{ kept: object[], dropped: object[], unverified: object[], trimmed: object[] }}
|
||||
*/
|
||||
export function judgeFilter(findings) {
|
||||
const kept = [];
|
||||
const dropped = [];
|
||||
const unverified = [];
|
||||
const trimmed = [];
|
||||
for (const f of findings) {
|
||||
const titleLen = (f.title ?? '').length;
|
||||
const detailLen = (f.detail ?? '').length;
|
||||
let reason = null;
|
||||
if (titleLen > JUDGE_TITLE_MAX) reason = 'succinctness:title';
|
||||
else if (detailLen > JUDGE_DETAIL_MAX) reason = 'succinctness:detail';
|
||||
else if ('recommended_action' in f &&
|
||||
if ('recommended_action' in f &&
|
||||
(typeof f.recommended_action !== 'string' || f.recommended_action.trim().length === 0)) {
|
||||
reason = 'actionability:empty';
|
||||
suppress(f, 'actionability:empty', dropped, unverified);
|
||||
continue;
|
||||
}
|
||||
const title = f.title ?? '';
|
||||
const detail = f.detail ?? '';
|
||||
const longTitle = title.length > JUDGE_TITLE_MAX;
|
||||
const longDetail = detail.length > JUDGE_DETAIL_MAX;
|
||||
if ((longTitle || longDetail) && TRIMMABLE_SEVERITIES.includes(effectiveSeverity(f))) {
|
||||
const out = { ...f };
|
||||
const fields = [];
|
||||
if (longTitle) { out.title = trimText(title, JUDGE_TITLE_MAX); fields.push('title'); }
|
||||
if (longDetail) { out.detail = trimText(detail, JUDGE_DETAIL_MAX); fields.push('detail'); }
|
||||
out.trimmed_fields = fields;
|
||||
kept.push(out);
|
||||
trimmed.push(out);
|
||||
} else {
|
||||
kept.push(f);
|
||||
}
|
||||
if (reason) suppress(f, reason, dropped, unverified);
|
||||
else kept.push(f);
|
||||
}
|
||||
return { kept, dropped, unverified };
|
||||
return { kept, dropped, unverified, trimmed };
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
@ -314,7 +358,11 @@ export function computeVerdict(findings, options = {}) {
|
|||
*
|
||||
* @param {Array<{reviewer?: string, findings: object[]}>} reviewerPayloads
|
||||
* @param {{ expectedReviewers?: string[] }} [options]
|
||||
* @returns {{ verdict: string, counts: Record<string, number>, findings: object[], suppressed: object[], unverified: object[], skipped: object[], missing_reviewers: string[], unattributable_payloads: number, allow_blocked_by: string[] }}
|
||||
* `declined_to_judge` lists every unverified finding with its reason, and
|
||||
* `trimmed_count` counts the MINOR/SUGGESTION findings whose text was trimmed
|
||||
* (kept, judged, and counted — never removed for length).
|
||||
*
|
||||
* @returns {{ verdict: string, counts: Record<string, number>, findings: object[], suppressed: object[], unverified: object[], skipped: object[], missing_reviewers: string[], unattributable_payloads: number, allow_blocked_by: string[], declined_to_judge: object[], trimmed_count: number }}
|
||||
*/
|
||||
export function runContract(reviewerPayloads, options = {}) {
|
||||
const { findings: ingested, skipped } = ingest(reviewerPayloads);
|
||||
|
|
@ -322,6 +370,21 @@ export function runContract(reviewerPayloads, options = {}) {
|
|||
const judged = judgeFilter(deduped);
|
||||
const reasoned = reasonablenessFilter(judged.kept);
|
||||
const unverified = [...judged.unverified, ...reasoned.unverified];
|
||||
// What the coordinator set aside without ruling on it, one line each, so a
|
||||
// reader sees every finding that did not reach a verdict tier. Borrowed:
|
||||
// "Declined to judge … nothing you set aside is dropped silently"
|
||||
// (Superpowers `skills/requesting-code-review/code-reviewer.md:43-48`, MIT).
|
||||
const declined_to_judge = unverified.map((f) => ({
|
||||
file: f.file ?? null,
|
||||
line: f.line ?? null,
|
||||
rule_key: f.rule_key ?? null,
|
||||
severity: f.severity ?? null,
|
||||
title: f.title ?? null,
|
||||
reason: f.suppressed_reason,
|
||||
}));
|
||||
// A trimmed finding that Pass 3 later removed is accounted for there, not here.
|
||||
const keptSet = new Set(reasoned.kept.map((f) => tripletKey(f)));
|
||||
const trimmed_count = judged.trimmed.filter((f) => keptSet.has(tripletKey(f))).length;
|
||||
|
||||
// A reviewer counts as REPORTED only when a payload carrying its name
|
||||
// validated. `validateFindings` merely warns on a missing `reviewer`, so a
|
||||
|
|
@ -360,12 +423,22 @@ export function runContract(reviewerPayloads, options = {}) {
|
|||
missing_reviewers,
|
||||
unattributable_payloads,
|
||||
allow_blocked_by,
|
||||
declined_to_judge,
|
||||
trimmed_count,
|
||||
};
|
||||
}
|
||||
|
||||
// ---- CLI shim ----------------------------------------------------------------
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
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) {
|
||||
|
|
|
|||
133
lib/review/engine-findings.mjs
Normal file
133
lib/review/engine-findings.mjs
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
// lib/review/engine-findings.mjs
|
||||
// Claude Code's review as the engine (ordre 5, P11 — wrap, not a new engine).
|
||||
//
|
||||
// /trekreview Phase 4.7 starts Claude Code's own `/code-review` and
|
||||
// `/security-review` through the Skill tool (never with `--fix`, never anything
|
||||
// that edits code). Their findings come back as text: per finding a file
|
||||
// location, a one-sentence summary, a failure scenario and an optional category
|
||||
// slug (code.claude.com/docs/en/tools-reference.md, `ReportFindings`). The
|
||||
// orchestrator transcribes them into a small JSON list; THIS module turns that
|
||||
// list into a reviewer payload the coordinator already understands, so the
|
||||
// engine's findings meet Voyage's brief control in the same dedup + verdict.
|
||||
//
|
||||
// Input (one engine per call):
|
||||
// { "engine": "code-review" | "security-review",
|
||||
// "findings": [ { "file": "...", "line": 12, "summary": "...",
|
||||
// "failure_scenario": "...", "category": "correctness",
|
||||
// "rule_key": "<optional narrower catalogue key>" } ] }
|
||||
//
|
||||
// Output: { reviewer, findings: [...catalogue-conformant...], out_of_scope: [...] }
|
||||
// - rule_key: the given one when it is in the catalogue, else
|
||||
// CODE_REVIEW_DEFECT (MAJOR) / SECURITY_REVIEW_VULNERABILITY (BLOCKER).
|
||||
// - A finding on a file outside the review scope is NOT dropped silently: it
|
||||
// lands in `out_of_scope` for the Coverage section (`/security-review`
|
||||
// diffs against origin's default branch, which can be wider than the
|
||||
// review's SHA range).
|
||||
//
|
||||
// CLI: node lib/review/engine-findings.mjs [--scope <file-list.txt>] <engine-findings.json>
|
||||
// exit 0 = payload on stdout; 1 = input invalid (errors on stderr); 2 = could not run.
|
||||
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { computeFindingId } from '../parsers/finding-id.mjs';
|
||||
import { RULE_KEYS, getRule } from './rule-catalogue.mjs';
|
||||
import { validateFindings } from './findings-schema.mjs';
|
||||
|
||||
export const ENGINES = Object.freeze({
|
||||
'code-review': Object.freeze({
|
||||
reviewer: 'claude-code-review',
|
||||
rule_key: 'CODE_REVIEW_DEFECT',
|
||||
brief_ref: 'NFR — code correctness (Claude Code /code-review)',
|
||||
}),
|
||||
'security-review': Object.freeze({
|
||||
reviewer: 'claude-security-review',
|
||||
rule_key: 'SECURITY_REVIEW_VULNERABILITY',
|
||||
brief_ref: 'NFR — security (Claude Code /security-review)',
|
||||
}),
|
||||
});
|
||||
|
||||
function normPath(p) {
|
||||
return String(p ?? '').replace(/^\.\//, '').trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert one engine's transcribed findings into a coordinator payload.
|
||||
* @param {{ engine: string, findings: object[] }} input
|
||||
* @param {{ scopeFiles?: string[] }} [opts]
|
||||
* @returns {{ ok: boolean, errors: string[], payload?: { reviewer: string, findings: object[] }, out_of_scope?: object[] }}
|
||||
*/
|
||||
export function toReviewerPayload(input, opts = {}) {
|
||||
const errors = [];
|
||||
const spec = ENGINES[input?.engine];
|
||||
if (!spec) return { ok: false, errors: [`engine must be one of ${Object.keys(ENGINES).join('|')}, got ${JSON.stringify(input?.engine)}`] };
|
||||
if (!Array.isArray(input.findings)) return { ok: false, errors: ['findings must be an array'] };
|
||||
const scope = opts.scopeFiles ? new Set(opts.scopeFiles.map(normPath)) : null;
|
||||
|
||||
const findings = [];
|
||||
const out_of_scope = [];
|
||||
input.findings.forEach((f, i) => {
|
||||
const file = normPath(f?.file);
|
||||
const summary = String(f?.summary ?? '').trim();
|
||||
if (!file) errors.push(`findings[${i}].file is empty`);
|
||||
if (!summary) errors.push(`findings[${i}].summary is empty`);
|
||||
if (!file || !summary) return;
|
||||
const line = Number.isInteger(f.line) && f.line >= 0 ? f.line : 0;
|
||||
const rule_key = typeof f.rule_key === 'string' && RULE_KEYS.has(f.rule_key) ? f.rule_key : spec.rule_key;
|
||||
const out = {
|
||||
id: computeFindingId(file, line, rule_key),
|
||||
severity: getRule(rule_key).severity,
|
||||
rule_key,
|
||||
file,
|
||||
line,
|
||||
brief_ref: spec.brief_ref,
|
||||
title: summary,
|
||||
detail: [String(f.failure_scenario ?? '').trim(), f.category ? `(engine category: ${f.category})` : '']
|
||||
.filter(Boolean).join(' ') || summary,
|
||||
recommended_action: `Resolve: ${summary}`,
|
||||
engine: input.engine,
|
||||
};
|
||||
if (scope && !scope.has(file)) out_of_scope.push(out);
|
||||
else findings.push(out);
|
||||
});
|
||||
if (errors.length > 0) return { ok: false, errors };
|
||||
|
||||
const payload = { reviewer: spec.reviewer, findings };
|
||||
const v = validateFindings(payload);
|
||||
if (!v.valid) return { ok: false, errors: v.errors.map((e) => `${e.code}: ${e.message}`) };
|
||||
return { ok: true, errors: [], payload, out_of_scope };
|
||||
}
|
||||
|
||||
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 scopeIdx = args.indexOf('--scope');
|
||||
const scopePath = scopeIdx === -1 ? null : args[scopeIdx + 1];
|
||||
const filePath = args.find((a, i) => !a.startsWith('--') && (scopeIdx === -1 || i !== scopeIdx + 1));
|
||||
if (!filePath || !existsSync(filePath) || (scopePath && !existsSync(scopePath))) {
|
||||
process.stderr.write('Usage: engine-findings.mjs [--scope <file-list.txt>] <engine-findings.json>\n');
|
||||
process.exit(2);
|
||||
}
|
||||
let input;
|
||||
let scopeFiles;
|
||||
try {
|
||||
input = JSON.parse(readFileSync(filePath, 'utf-8'));
|
||||
if (scopePath) scopeFiles = readFileSync(scopePath, 'utf-8').split('\n').map((l) => l.trim()).filter(Boolean);
|
||||
} catch (e) {
|
||||
process.stderr.write(`engine-findings: could not read input: ${e.message}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
const r = toReviewerPayload(input, { scopeFiles });
|
||||
if (!r.ok) {
|
||||
for (const e of r.errors) process.stderr.write(` ERROR ${e}\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(JSON.stringify({ ...r.payload, out_of_scope: r.out_of_scope }, null, 2) + '\n');
|
||||
process.exit(0);
|
||||
}
|
||||
|
|
@ -21,7 +21,8 @@
|
|||
//
|
||||
// 3-layer pattern (Content → Raw-text → CLI shim) mirroring the other validators.
|
||||
|
||||
import { readFileSync, existsSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { issue, fail } from '../util/result.mjs';
|
||||
import { RULE_KEYS, SEVERITY_VALUES } from './rule-catalogue.mjs';
|
||||
|
||||
|
|
@ -152,7 +153,15 @@ export function validateReviewerOutput(rawText) {
|
|||
|
||||
// ---- CLI shim ----------------------------------------------------------------
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
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) {
|
||||
|
|
|
|||
356
lib/review/recurrence.mjs
Normal file
356
lib/review/recurrence.mjs
Normal file
|
|
@ -0,0 +1,356 @@
|
|||
// lib/review/recurrence.mjs
|
||||
// P5 — the project's memory, fed by review (ordre 5).
|
||||
//
|
||||
// A finding class (the same catalogue `rule_key`) that shows up in TWO review.md
|
||||
// files in the target repo becomes ONE proposal; one sighting is no proposal.
|
||||
// The history is the review.md files the repo already has — the current
|
||||
// `.claude/projects/*/review.md` plus, where git tracks them, their earlier
|
||||
// committed versions. No new store is created.
|
||||
//
|
||||
// Routing (the catalogue's `memory_route`): mechanical → the lesson names a
|
||||
// deterministic check; judgement → a line in the target repo's `.claude/rules/`
|
||||
// file; CLAUDE.md gets only a pointer. Review-hygiene classes (route null) are
|
||||
// never proposed. Format of every line: mistake · fix · how to check.
|
||||
//
|
||||
// Writes: only between Voyage's own markers, under a size budget; past the
|
||||
// budget the write is refused and the lesson belongs in a skill (operator's
|
||||
// call). Every line is approved by the operator first (/trekreview Phase 9.5,
|
||||
// AskUserQuestion) — this module never decides that on its own.
|
||||
//
|
||||
// Borrowed (credited, MIT where it applies):
|
||||
// - routing check / standard / pointer: Pocock `skills/in-progress/retro/SKILL.md:19,41`
|
||||
// - the three-part line "mistake · fix · how to check": ai-native-sdlc `assets/CLAUDE.md:27-29`
|
||||
// - the managed block between START/END markers: Spec Kit `extensions/agent-context/README.md:5`
|
||||
// - evidence (two finding IDs) per proposal, schema-check before writing:
|
||||
// Kiro https://kiro.dev/blog/trust-agent-triage/ (docs only, closed product)
|
||||
// - review → memory, and the size budget ("or make a skill"): Boris Cherny's
|
||||
// public talks/posts (sources A, B; see docs/praksisanalyse)
|
||||
//
|
||||
// CLI:
|
||||
// node lib/review/recurrence.mjs propose --repo <dir>
|
||||
// → {"proposals":[…], "reviews_read": N, "skipped": [...]} on stdout, exit 0; exit 2 = could not run
|
||||
// node lib/review/recurrence.mjs apply --repo <dir> --rule-key <KEY> [--line "<edited line>"]
|
||||
// → {"written":true|false, "reason":…} on stdout; exit 0 written, 1 refused, 2 could not run
|
||||
|
||||
import {
|
||||
readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, readdirSync, statSync, realpathSync,
|
||||
} from 'node:fs';
|
||||
import { join, relative, dirname } from 'node:path';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { validateReviewContent } from '../validators/review-validator.mjs';
|
||||
import { extractFindingsBlock } from './findings-schema.mjs';
|
||||
import { getRule } from './rule-catalogue.mjs';
|
||||
|
||||
export const LESSONS_DIR = join('.claude', 'rules');
|
||||
export const LESSONS_FILE_NAME = 'voyage-review-lessons.md';
|
||||
export const MARK_START = '<!-- voyage:review-lessons:start -->';
|
||||
export const MARK_END = '<!-- voyage:review-lessons:end -->';
|
||||
export const POINTER_START = '<!-- voyage:review-lessons-pointer:start -->';
|
||||
export const POINTER_END = '<!-- voyage:review-lessons-pointer:end -->';
|
||||
export const POINTER_LINE =
|
||||
`Recurring review lessons (operator-approved, managed by Voyage /trekreview): \`${LESSONS_DIR}/${LESSONS_FILE_NAME}\`.`;
|
||||
|
||||
/** Size budget for the managed block. Past it, a lesson belongs in a skill. */
|
||||
export const DEFAULT_BUDGET_ENTRIES = 20;
|
||||
export const DEFAULT_BUDGET_CHARS = 6000;
|
||||
export const LINE_MAX = 700;
|
||||
export const RECURRENCE_THRESHOLD = 2;
|
||||
|
||||
const BLOCK_HEADER = 'Each line: a finding class /trekreview saw in two reviews, approved by the operator. Format: mistake · fix · how to check.';
|
||||
|
||||
/** How to check a mechanical class. Judgement classes get the review itself. */
|
||||
const CHECK_HINTS = Object.freeze({
|
||||
MISSING_TEST: 'a coverage check on the changed files with the repo\'s own test tool — red when a changed source file has no test that exercises it.',
|
||||
PLACEHOLDER_IN_CODE: '`git grep -nE "TODO|FIXME|XXX|debugger" -- <changed files>` returns nothing.',
|
||||
UNDECLARED_DEPENDENCY: 'every import in the changed files resolves to a declared dependency (the repo\'s own dependency checker).',
|
||||
BROKEN_SUCCESS_CRITERION: 'run each Success Criterion\'s verification command before the step is called done; only exit 0 counts.',
|
||||
});
|
||||
|
||||
// ---- reading the history ----------------------------------------------------
|
||||
|
||||
/**
|
||||
* Pull the kept findings out of one review.md text.
|
||||
* @param {string} text
|
||||
* @returns {{ ok: boolean, identity?: string, findings?: object[], reason?: string }}
|
||||
*/
|
||||
export function parseReview(text) {
|
||||
const r = validateReviewContent(text, { strict: false });
|
||||
if (!r.valid) return { ok: false, reason: (r.errors ?? []).map((e) => e.code).join(',') || 'invalid' };
|
||||
const fm = r.parsed.frontmatter ?? {};
|
||||
const block = extractFindingsBlock(r.parsed.body ?? '');
|
||||
if (block === null) return { ok: false, reason: 'no-json-block' };
|
||||
let payload;
|
||||
try { payload = JSON.parse(block); } catch { return { ok: false, reason: 'json-parse-error' }; }
|
||||
const findings = (Array.isArray(payload?.findings) ? payload.findings : [])
|
||||
.map((f) => ({ ...f, rule_key: f?.rule_key ?? f?.rule }))
|
||||
.filter((f) => typeof f.rule_key === 'string');
|
||||
const identity = `${fm.project_dir ?? fm.slug ?? '?'}@${fm.scope_sha_end ?? '?'}`;
|
||||
return { ok: true, identity, findings };
|
||||
}
|
||||
|
||||
function git(repo, args) {
|
||||
return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
|
||||
}
|
||||
|
||||
/**
|
||||
* Every review.md the repo already holds: current files under
|
||||
* `.claude/projects/<dir>/review.md`, plus earlier committed versions of those
|
||||
* files when git tracks them. Deduplicated by review identity
|
||||
* (project_dir @ scope_sha_end).
|
||||
* @param {string} repo
|
||||
* @returns {{ reviews: Array<{ identity: string, source: string, findings: object[] }>, skipped: Array<{ source: string, reason: string }> }}
|
||||
*/
|
||||
export function collectReviews(repo) {
|
||||
const sources = [];
|
||||
const projects = join(repo, '.claude', 'projects');
|
||||
if (existsSync(projects)) {
|
||||
for (const name of readdirSync(projects).sort()) {
|
||||
const p = join(projects, name, 'review.md');
|
||||
if (existsSync(p) && statSync(p).isFile()) {
|
||||
sources.push({ source: relative(repo, p), text: readFileSync(p, 'utf-8') });
|
||||
}
|
||||
}
|
||||
}
|
||||
// Earlier versions (review.md is overwritten per iteration; git keeps the rest).
|
||||
for (const { source } of [...sources]) {
|
||||
let shas = [];
|
||||
try { shas = git(repo, ['log', '--format=%H', '--', source]).split('\n').filter(Boolean); } catch { shas = []; }
|
||||
for (const sha of shas) {
|
||||
try {
|
||||
// `./` makes the path relative to --repo, not to the enclosing git root.
|
||||
sources.push({ source: `${source}@${sha.slice(0, 12)}`, text: git(repo, ['show', `${sha}:./${source}`]) });
|
||||
} catch { /* not in that commit's tree */ }
|
||||
}
|
||||
}
|
||||
const seen = new Set();
|
||||
const reviews = [];
|
||||
const skipped = [];
|
||||
for (const s of sources) {
|
||||
const parsed = parseReview(s.text);
|
||||
if (!parsed.ok) { skipped.push({ source: s.source, reason: parsed.reason }); continue; }
|
||||
if (seen.has(parsed.identity)) continue;
|
||||
seen.add(parsed.identity);
|
||||
reviews.push({ identity: parsed.identity, source: s.source, findings: parsed.findings });
|
||||
}
|
||||
return { reviews, skipped };
|
||||
}
|
||||
|
||||
// ---- the managed block ------------------------------------------------------
|
||||
|
||||
function lessonsPath(repo) {
|
||||
return join(repo, LESSONS_DIR, LESSONS_FILE_NAME);
|
||||
}
|
||||
|
||||
function readBlock(text) {
|
||||
const start = text.indexOf(MARK_START);
|
||||
const end = text.indexOf(MARK_END);
|
||||
if (start === -1 || end === -1 || end < start) return null;
|
||||
return { start, end, inner: text.slice(start + MARK_START.length, end) };
|
||||
}
|
||||
|
||||
function blockEntries(inner) {
|
||||
return inner.split('\n').filter((l) => l.startsWith('- ['));
|
||||
}
|
||||
|
||||
/** The rule_keys already written as lessons. */
|
||||
export function writtenClasses(repo) {
|
||||
const p = lessonsPath(repo);
|
||||
if (!existsSync(p)) return new Set();
|
||||
const block = readBlock(readFileSync(p, 'utf-8'));
|
||||
if (!block) return new Set();
|
||||
const keys = new Set();
|
||||
for (const line of blockEntries(block.inner)) {
|
||||
const m = line.match(/^- \[([A-Z_]+)\]/);
|
||||
if (m) keys.add(m[1]);
|
||||
}
|
||||
return keys;
|
||||
}
|
||||
|
||||
// ---- proposals --------------------------------------------------------------
|
||||
|
||||
function clip(s, n) {
|
||||
const t = String(s ?? '').replace(/\s+/g, ' ').trim();
|
||||
return t.length > n ? `${t.slice(0, n - 1)}…` : t;
|
||||
}
|
||||
|
||||
function composeLine(rule, evidence) {
|
||||
const seen = evidence.map((e) => `"${clip(e.title ?? e.rule_key, 80)}" (${clip(e.file, 60)})`).join(', ');
|
||||
const fix = clip(evidence[evidence.length - 1].recommended_action
|
||||
?? evidence.find((e) => e.recommended_action)?.recommended_action
|
||||
?? 'Address the class before the step is called done.', 160);
|
||||
const how = rule.memory_route === 'check'
|
||||
? CHECK_HINTS[rule.rule_key] ?? `a deterministic check for ${rule.rule_key}.`
|
||||
: `/trekreview flags it as ${rule.rule_key}; read the diff for it before the step is called done.`;
|
||||
const ids = evidence.map((e) => String(e.id ?? '').slice(0, 8)).join(', ');
|
||||
const body = `Mistake: ${clip(rule.description, 160)} Seen: ${seen}. · Fix: ${fix} · How to check: ${how} (evidence: ${ids})`;
|
||||
return `- [${rule.rule_key}] (${rule.memory_route}) ${body}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate a lesson line (generated or operator-edited). Schema-check before
|
||||
* any write (Kiro's lesson-capture fix).
|
||||
* @param {string} line
|
||||
* @returns {{ valid: boolean, reason?: string }}
|
||||
*/
|
||||
export function validateLessonLine(line) {
|
||||
if (typeof line !== 'string' || line.trim().length === 0) return { valid: false, reason: 'empty' };
|
||||
if (line.includes('\n')) return { valid: false, reason: 'multi-line' };
|
||||
if (line.length > LINE_MAX) return { valid: false, reason: `longer than ${LINE_MAX}` };
|
||||
if (line.includes('<!--') || line.includes('-->')) return { valid: false, reason: 'marker text' };
|
||||
const a = line.indexOf('Mistake:');
|
||||
const b = line.indexOf('Fix:');
|
||||
const c = line.indexOf('How to check:');
|
||||
if (a === -1 || b === -1 || c === -1 || !(a < b && b < c)) {
|
||||
return { valid: false, reason: 'needs "Mistake:", "Fix:", "How to check:" in that order' };
|
||||
}
|
||||
return { valid: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Find recurring finding classes in the repo's review history.
|
||||
* @param {string} repo
|
||||
* @returns {{ proposals: object[], reviews_read: number, skipped: object[] }}
|
||||
*/
|
||||
export function proposeLessons(repo) {
|
||||
const { reviews, skipped } = collectReviews(repo);
|
||||
const already = writtenClasses(repo);
|
||||
const byKey = new Map();
|
||||
for (const review of reviews) {
|
||||
const firstPerKey = new Map();
|
||||
for (const f of review.findings) {
|
||||
if (!firstPerKey.has(f.rule_key)) firstPerKey.set(f.rule_key, f);
|
||||
}
|
||||
for (const [key, f] of firstPerKey) {
|
||||
if (!byKey.has(key)) byKey.set(key, []);
|
||||
byKey.get(key).push({ ...f, review: review.identity, source: review.source });
|
||||
}
|
||||
}
|
||||
const proposals = [];
|
||||
for (const [key, evidence] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
|
||||
if (evidence.length < RECURRENCE_THRESHOLD) continue;
|
||||
const rule = getRule(key);
|
||||
if (!rule || rule.memory_route === null || rule.memory_route === undefined) continue;
|
||||
if (already.has(key)) continue;
|
||||
const ev = evidence.slice(0, RECURRENCE_THRESHOLD);
|
||||
proposals.push({
|
||||
rule_key: key,
|
||||
route: rule.memory_route,
|
||||
target: `${LESSONS_DIR}/${LESSONS_FILE_NAME}`,
|
||||
line: composeLine(rule, ev),
|
||||
evidence: evidence.map((e) => ({ id: e.id ?? null, review: e.review, source: e.source, file: e.file ?? null, title: e.title ?? null })),
|
||||
});
|
||||
}
|
||||
return { proposals, reviews_read: reviews.length, skipped };
|
||||
}
|
||||
|
||||
// ---- writing an approved lesson ---------------------------------------------
|
||||
|
||||
function atomicWriteText(path, text) {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
const tmp = `${path}.tmp-${process.pid}`;
|
||||
writeFileSync(tmp, text);
|
||||
renameSync(tmp, path);
|
||||
}
|
||||
|
||||
function withPointer(claudeText) {
|
||||
if (claudeText.includes(POINTER_START)) return null;
|
||||
const sep = claudeText.endsWith('\n') ? '\n' : '\n\n';
|
||||
return `${claudeText}${sep}${POINTER_START}\n${POINTER_LINE}\n${POINTER_END}\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Write ONE operator-approved lesson. Call only after the operator said yes to
|
||||
* this exact line.
|
||||
* @param {string} repo
|
||||
* @param {string} ruleKey
|
||||
* @param {{ line?: string, budgetEntries?: number, budgetChars?: number }} [opts]
|
||||
* @returns {{ written: boolean, reason: string, path?: string, pointer?: string }}
|
||||
*/
|
||||
export function applyLesson(repo, ruleKey, opts = {}) {
|
||||
const budgetEntries = opts.budgetEntries ?? DEFAULT_BUDGET_ENTRIES;
|
||||
const budgetChars = opts.budgetChars ?? DEFAULT_BUDGET_CHARS;
|
||||
if (writtenClasses(repo).has(ruleKey)) return { written: false, reason: 'already-present' };
|
||||
const proposal = proposeLessons(repo).proposals.find((p) => p.rule_key === ruleKey);
|
||||
if (!proposal) return { written: false, reason: 'no-recurrence' };
|
||||
|
||||
let line = proposal.line;
|
||||
if (opts.line !== undefined) {
|
||||
const body = String(opts.line).replace(/^- \[[A-Z_]+\]\s*(\((check|rule)\)\s*)?/, '');
|
||||
line = `- [${ruleKey}] (${proposal.route}) ${body.trim()}`;
|
||||
}
|
||||
const check = validateLessonLine(line);
|
||||
if (!check.valid) return { written: false, reason: 'invalid-line', detail: check.reason };
|
||||
|
||||
const path = lessonsPath(repo);
|
||||
const current = existsSync(path) ? readFileSync(path, 'utf-8') : '';
|
||||
let block = readBlock(current);
|
||||
let base = current;
|
||||
if (!block) {
|
||||
const sep = current.length === 0 || current.endsWith('\n') ? '' : '\n';
|
||||
base = `${current}${sep}${MARK_START}\n${BLOCK_HEADER}\n${MARK_END}\n`;
|
||||
block = readBlock(base);
|
||||
}
|
||||
const entries = blockEntries(block.inner);
|
||||
const innerAfter = `${block.inner.replace(/\n*$/, '')}\n${line}\n`;
|
||||
if (entries.length + 1 > budgetEntries || innerAfter.length > budgetChars) {
|
||||
return { written: false, reason: 'over-budget', detail: 'the managed block is full — the lessons belong in a skill now (operator decision)' };
|
||||
}
|
||||
const next = base.slice(0, block.start + MARK_START.length) + innerAfter + base.slice(block.end);
|
||||
atomicWriteText(path, next);
|
||||
|
||||
let pointer = 'no-claude-md';
|
||||
const claudePath = join(repo, 'CLAUDE.md');
|
||||
if (existsSync(claudePath)) {
|
||||
const updated = withPointer(readFileSync(claudePath, 'utf-8'));
|
||||
if (updated === null) pointer = 'present';
|
||||
else { atomicWriteText(claudePath, updated); pointer = 'written'; }
|
||||
}
|
||||
return { written: true, reason: 'written', path: relative(repo, path), pointer };
|
||||
}
|
||||
|
||||
// ---- CLI --------------------------------------------------------------------
|
||||
|
||||
function isMain() {
|
||||
try {
|
||||
return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function flag(args, name) {
|
||||
const i = args.indexOf(name);
|
||||
return i === -1 ? undefined : args[i + 1];
|
||||
}
|
||||
|
||||
if (isMain()) {
|
||||
const [cmd, ...args] = process.argv.slice(2);
|
||||
const repo = flag(args, '--repo');
|
||||
const out = (o) => process.stdout.write(JSON.stringify(o, null, 2) + '\n');
|
||||
if (!['propose', 'apply'].includes(cmd) || !repo) {
|
||||
process.stderr.write('Usage: recurrence.mjs propose --repo <dir> | apply --repo <dir> --rule-key <KEY> [--line "<text>"]\n');
|
||||
process.exit(2);
|
||||
}
|
||||
if (!existsSync(repo) || !statSync(repo).isDirectory()) {
|
||||
process.stderr.write(`recurrence: repo not found: ${repo}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
try {
|
||||
if (cmd === 'propose') {
|
||||
out(proposeLessons(repo));
|
||||
process.exit(0);
|
||||
}
|
||||
const key = flag(args, '--rule-key');
|
||||
if (!key) {
|
||||
process.stderr.write('recurrence apply: --rule-key is required\n');
|
||||
process.exit(2);
|
||||
}
|
||||
const r = applyLesson(repo, key, { line: flag(args, '--line') });
|
||||
out(r);
|
||||
process.exit(r.written ? 0 : 1);
|
||||
} catch (e) {
|
||||
process.stderr.write(`recurrence: could not run: ${e.message}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
}
|
||||
|
|
@ -1,8 +1,20 @@
|
|||
// lib/review/rule-catalogue.mjs
|
||||
// Canonical rule catalogue for /trekreview v1.0.
|
||||
// Canonical rule catalogue for /trekreview.
|
||||
//
|
||||
// 12 rule keys, 4-tier severity (matches brief contract).
|
||||
// 14 rule keys, 4-tier severity (matches brief contract).
|
||||
// llm-security 5-tier alignment is a v1.1 candidate.
|
||||
//
|
||||
// Ordre 5 (review_version 1.1) added the two engine keys: findings from Claude
|
||||
// Code's own `/code-review` and `/security-review` enter the coordinator under
|
||||
// them when no narrower key fits (wrap, not a new engine).
|
||||
//
|
||||
// `memory_route` decides where a finding class that recurs across two
|
||||
// review.md files is proposed as project memory (P5, lib/review/recurrence.mjs):
|
||||
// 'check' - mechanical: a deterministic check can catch it;
|
||||
// 'rule' - judgement: a line in the target repo's `.claude/rules/` file;
|
||||
// null - review hygiene (about the review itself, not the target code):
|
||||
// never proposed.
|
||||
// Routing borrowed from Pocock `skills/in-progress/retro/SKILL.md:19` (MIT).
|
||||
|
||||
export const SEVERITY_VALUES = Object.freeze(['BLOCKER', 'MAJOR', 'MINOR', 'SUGGESTION']);
|
||||
|
||||
|
|
@ -21,75 +33,103 @@ export const RULE_CATALOGUE = Object.freeze([
|
|||
severity: 'MAJOR',
|
||||
category: 'conformance',
|
||||
description: 'Finding lacks brief_ref pointing to the brief section it traces back to.',
|
||||
memory_route: null,
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'UNIMPLEMENTED_CRITERION',
|
||||
severity: 'BLOCKER',
|
||||
category: 'conformance',
|
||||
description: 'A brief Success Criterion has no corresponding implementation in the delivered code.',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'SCOPE_CREEP_BUILT',
|
||||
severity: 'MAJOR',
|
||||
category: 'scope',
|
||||
description: 'Code implements features beyond what the brief requested.',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'NON_GOAL_VIOLATED',
|
||||
severity: 'BLOCKER',
|
||||
category: 'scope',
|
||||
description: 'Code implements something the brief explicitly listed as a Non-Goal.',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'MISSING_TEST',
|
||||
severity: 'MAJOR',
|
||||
category: 'tests',
|
||||
description: 'Delivered behavior has no automated test coverage.',
|
||||
memory_route: 'check',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'SECURITY_INJECTION',
|
||||
severity: 'BLOCKER',
|
||||
category: 'security',
|
||||
description: 'Code path constructs commands, queries, or templates from untrusted input without sanitization.',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'PLACEHOLDER_IN_CODE',
|
||||
severity: 'MAJOR',
|
||||
category: 'maintenance',
|
||||
description: 'Committed code contains TBD/TODO/FIXME/XXX/console.log/debugger placeholders.',
|
||||
memory_route: 'check',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'MISSING_ERROR_HANDLING',
|
||||
severity: 'MINOR',
|
||||
category: 'correctness',
|
||||
description: 'Code path can fail silently (uncaught promise, unchecked return, missing try/catch on I/O).',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'UNDECLARED_DEPENDENCY',
|
||||
severity: 'MAJOR',
|
||||
category: 'maintenance',
|
||||
description: 'Code imports or invokes something not declared in package.json / not bundled / not present in PATH.',
|
||||
memory_route: 'check',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'PLAN_EXECUTE_DRIFT',
|
||||
severity: 'MAJOR',
|
||||
category: 'conformance',
|
||||
description: 'Delivered code diverges from what the plan said would be built (different file, different approach, different API).',
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'BROKEN_SUCCESS_CRITERION',
|
||||
severity: 'BLOCKER',
|
||||
category: 'conformance',
|
||||
description: 'A brief Success Criterion is implemented but the verification command/test fails or is structurally incorrect.',
|
||||
memory_route: 'check',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'COVERAGE_SILENT_SKIP',
|
||||
severity: 'MAJOR',
|
||||
category: 'tests',
|
||||
description: 'Triage gate skipped a file without recording it in the Coverage section of review.md (hidden truncation).',
|
||||
memory_route: null,
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'CODE_REVIEW_DEFECT',
|
||||
severity: 'MAJOR',
|
||||
category: 'correctness',
|
||||
description: "A defect reported by Claude Code's /code-review that no narrower rule_key covers.",
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
Object.freeze({
|
||||
rule_key: 'SECURITY_REVIEW_VULNERABILITY',
|
||||
severity: 'BLOCKER',
|
||||
category: 'security',
|
||||
description: "A vulnerability reported by Claude Code's /security-review that no narrower rule_key covers.",
|
||||
memory_route: 'rule',
|
||||
}),
|
||||
]);
|
||||
|
||||
export const MEMORY_ROUTES = Object.freeze(['check', 'rule']);
|
||||
|
||||
export const RULE_KEYS = Object.freeze(new Set(RULE_CATALOGUE.map((r) => r.rule_key)));
|
||||
|
||||
/**
|
||||
|
|
|
|||
127
lib/review/verdict-gate.mjs
Normal file
127
lib/review/verdict-gate.mjs
Normal file
|
|
@ -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);
|
||||
}
|
||||
|
|
@ -6,8 +6,15 @@
|
|||
// tolerated silently. Strict-key checks are intentionally avoided so new
|
||||
// optional fields (jf. the source_findings precedent) can be added without
|
||||
// a review_version bump.
|
||||
//
|
||||
// K7 (ordre 5, review_version 1.1): `verdict: ALLOW | WARN | BLOCK` is REQUIRED.
|
||||
// Strict (write-time) mode rejects a review without it; soft (read-time) mode
|
||||
// warns, so a 1.0 review can still seed a plan (N-1 window, Handover 6). The
|
||||
// gate that decides on the verdict is lib/review/verdict-gate.mjs, which never
|
||||
// reads a missing verdict as ALLOW.
|
||||
|
||||
import { readFileSync, existsSync } from 'node:fs';
|
||||
import { readFileSync, existsSync, realpathSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { parseDocument } from '../util/frontmatter.mjs';
|
||||
import { issue, ok, fail } from '../util/result.mjs';
|
||||
|
||||
|
|
@ -23,8 +30,42 @@ export const REVIEW_REQUIRED_FRONTMATTER = [
|
|||
'findings',
|
||||
];
|
||||
export const REVIEW_BODY_SECTIONS = ['Executive Summary', 'Coverage', 'Remediation Summary'];
|
||||
export const VERDICT_VALUES = Object.freeze(['ALLOW', 'WARN', 'BLOCK']);
|
||||
|
||||
const HEX_ID_RE = /^[0-9a-f]{40}$/;
|
||||
const JSON_FENCE_GLOBAL = /```json[ \t]*\r?\n([\s\S]*?)```/gi;
|
||||
|
||||
/** IDs of BLOCKER findings in the trailing JSON block ([] when absent/unparseable). */
|
||||
function blockerIdsFromBody(body) {
|
||||
let last = null;
|
||||
let m;
|
||||
JSON_FENCE_GLOBAL.lastIndex = 0;
|
||||
while ((m = JSON_FENCE_GLOBAL.exec(body)) !== null) last = m[1];
|
||||
if (last === null) return [];
|
||||
try {
|
||||
const payload = JSON.parse(last);
|
||||
return (Array.isArray(payload?.findings) ? payload.findings : [])
|
||||
.filter((f) => f?.severity === 'BLOCKER' && typeof f.id === 'string')
|
||||
.map((f) => f.id);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/** Finding IDs named by `Source finding:` lines under `## Remediation Steps` step headings. */
|
||||
function remediationStepSources(body) {
|
||||
const start = body.search(/^##\s+Remediation Steps\b/m);
|
||||
if (start === -1) return new Set();
|
||||
const rest = body.slice(start).replace(/^##\s+Remediation Steps[^\n]*\n/, '');
|
||||
const next = rest.search(/^##\s+/m);
|
||||
const section = next === -1 ? rest : rest.slice(0, next);
|
||||
const ids = new Set();
|
||||
for (const step of section.split(/^###\s+Step\s+R\d+\b/m).slice(1)) {
|
||||
const m = step.match(/Source finding:\**\s*`?([0-9a-f]{40})`?/);
|
||||
if (m) ids.add(m[1]);
|
||||
}
|
||||
return ids;
|
||||
}
|
||||
|
||||
export function validateReviewContent(text, opts = {}) {
|
||||
const strict = opts.strict !== false;
|
||||
|
|
@ -66,6 +107,41 @@ export function validateReviewContent(text, opts = {}) {
|
|||
}
|
||||
}
|
||||
|
||||
if (!('verdict' in fm) || fm.verdict === null || fm.verdict === '') {
|
||||
const issueObj = issue(
|
||||
'REVIEW_MISSING_VERDICT',
|
||||
'Required frontmatter field missing: verdict (ALLOW | WARN | BLOCK)',
|
||||
'Copy the coordinator verdict from the trailing JSON block into the frontmatter.',
|
||||
);
|
||||
if (strict) errors.push(issueObj);
|
||||
else warnings.push(issueObj);
|
||||
} else if (!VERDICT_VALUES.includes(fm.verdict)) {
|
||||
errors.push(issue(
|
||||
'REVIEW_BAD_VERDICT',
|
||||
`frontmatter.verdict must be one of ${VERDICT_VALUES.join('|')}, got ${JSON.stringify(fm.verdict)}`,
|
||||
));
|
||||
}
|
||||
|
||||
// Every BLOCKER is written as a numbered remediation step that Handover 6 can
|
||||
// append to a plan unchanged: `### Step R<n>: …` with `Source finding: <id>`.
|
||||
// Borrowed: review gaps become appended, numbered tasks with a source-ref,
|
||||
// never rewriting earlier ones (Spec Kit `templates/commands/converge.md:156-163`, MIT).
|
||||
const blockerIds = blockerIdsFromBody(body);
|
||||
if (blockerIds.length > 0) {
|
||||
const steps = remediationStepSources(body);
|
||||
for (const id of blockerIds) {
|
||||
if (!steps.has(id)) {
|
||||
const issueObj = issue(
|
||||
'REVIEW_MISSING_REMEDIATION_STEP',
|
||||
`BLOCKER ${id} has no "### Step R<n>" with "Source finding: ${id}" under ## Remediation Steps`,
|
||||
'Write one numbered remediation step per BLOCKER (Handover 6).',
|
||||
);
|
||||
if (strict) errors.push(issueObj);
|
||||
else warnings.push(issueObj);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const section of REVIEW_BODY_SECTIONS) {
|
||||
const re = new RegExp(`^##\\s+${section}\\b`, 'm');
|
||||
if (!re.test(body)) {
|
||||
|
|
@ -94,7 +170,15 @@ export function validateReview(filePath, opts = {}) {
|
|||
return { ...r, parsed: { ...r.parsed, filePath } };
|
||||
}
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
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 strict = !args.includes('--soft');
|
||||
const filePath = args.find(a => !a.startsWith('--'));
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue