feat(plan): the plan gate counts critic rounds 2+ by rule A and records rule B [skip-docs]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-10-16 00:33:31 +02:00
commit 7b46cdd788
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
3 changed files with 1018 additions and 20 deletions

View file

@ -21,12 +21,56 @@
// recurse between them; a gap with no unique line uses an LCS table, ties
// resolved toward matching the earliest old line.
//
// countRound({round, previous, base, baseNote, current, planPaths, findings, marks})
// -> { findings, resolved, diffBase, diffNote, lowered }
// Decides each finding's counted severity for one critic round (RULE_A,
// RULE_B below). `current` = {text, sha256, fullToOp, opToFull}, built by the
// caller from the plan gate's operativeLines and planHash; `base` = {sha256,
// text} is the operative text the previous round reviewed, or null.
// Rule A is on only from round 2, with a base whose sha256 is the previous
// verdict's plan_sha256 and differs from the plan now. Otherwise the round is
// counted as before (each finding at its reported severity, plus the rule-B
// record) and `diffNote` says why in one line. With rule A on, a current
// finding outside the diff is matched to a previous one (same id, its mapped
// line, or the same wording in the same file class); a previous finding stays
// counted until every reviewer that raised it marks it resolved, no reviewer
// says it is not, and nobody re-reports it.
// Carried findings come first (previous order), then new ones (dedup order).
//
// Trust limit: anything that can write the plan can rewrite the previous
// verdict's plan_sha256 and plant a matching base snapshot. That was already
// the stated limit of the verdict block; rule A raises what such a forgery
// buys. An unchanged base lowers nothing.
//
// Pure: no I/O, and it never reads the plan gate (one dependency direction).
//
// Credit: patience-style anchoring (unique-line anchors kept by their longest
// increasing subsequence), the idea behind Bram Cohen's patience diff; the code
// here is written fresh.
import { resolve } from 'node:path';
import {
normalizeSeverity, contentOverlap, contentTokens, DEFAULT_THRESHOLD, ANCHOR_MIN_CONTENT_WORDS,
} from './plan-review-dedup.mjs';
import { getRule } from './rule-catalogue.mjs';
export const RULE_A = 'Rule A: from round 2 on, a new major finding that cites a plan line outside the diff since the last reviewed text counts as minor; a blocker, a security finding and a finding with no plan line count at full severity, and a previous finding stays counted until it is marked resolved.';
export const RULE_B = 'Rule B: a major that a named test, `Regression:` command or gate in the plan will fail on during execution is minor — never a blocker, never a security finding.';
// The optional voyage.plan-verdict/1 fields of decision 43; absent means round-1 behaviour.
export const DIFF_FIELDS = Object.freeze([
// top level
'diff_base', 'diff_note', 'resolved',
// per finding
'op_line', 'op_line_end', 'line_end', 'rule_keys', 'original_severity', 'lowered_by', 'caught_by',
'lowering_refused', 'carried_from',
]);
/** A rule_key whose catalogue entry is in the security category (case and spaces ignored). */
export function isSecurityKey(key) {
return getRule(String(key).trim().toUpperCase())?.category === 'security';
}
const toLines = (text) => {
const t = String(text ?? '').replace(/\r\n?/g, '\n');
if (t === '') return [];
@ -167,3 +211,274 @@ export function lineDiff(oldText, newText) {
}
return { inside, oldToNew, hunks };
}
// ---- counting (rule A, rule B) ----------------------------------------------------
// Lower index = more severe; an unrated severity counts as blocker.
const SEV_ORDER = ['blocker', 'major', 'minor'];
const rankOf = s => SEV_ORDER.indexOf(s);
const countedOf = s => normalizeSeverity(s) ?? 'blocker';
const higher = (a, b) => (rankOf(a) <= rankOf(b) ? a : b);
const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
/** The rule keys of a finding: `rule_keys` when it is a list, else its one `rule_key`. */
function keysOf(f) {
const keys = Array.isArray(f.rule_keys) ? f.rule_keys : [f.rule_key];
return keys.filter(k => typeof k === 'string' && k !== '');
}
const isSecurity = f => keysOf(f).some(isSecurityKey);
function union(...lists) {
const out = [];
for (const list of lists) {
for (const x of Array.isArray(list) ? list : []) if (!out.includes(x)) out.push(x);
}
return out;
}
/**
* The rule-B record of one finding at its rated severity.
* A null or absent `lowered_from` is no record at all.
* @returns {{severity: string, record: object}}
*/
function ruleB(f, rated) {
if (f.lowered_from === undefined || f.lowered_from === null) return { severity: rated, record: {} };
const from = normalizeSeverity(f.lowered_from);
const caught = typeof f.caught_by === 'string' && f.caught_by.trim() !== '' ? f.caught_by : null;
const security = isSecurity(f);
if (from === 'major' && rated === 'minor' && caught && !security) {
return { severity: 'minor', record: { original_severity: 'major', lowered_by: `rule B: ${caught}`, caught_by: caught } };
}
let why;
if (from === null) why = 'rule B: lowered_from is not a severity; counted as blocker';
else if (from === 'blocker') why = 'rule B never lowers a blocker';
else if (from !== 'major') why = `rule B lowers only major to minor, not ${from}`;
else if (rated !== 'minor') why = `rule B lowers major to minor only; the finding is rated ${rated}`;
else if (security) why = 'rule B never lowers a security finding';
else why = 'rule B needs caught_by: the named test, Regression: command or gate that will fail on it';
const severity = higher(from ?? 'blocker', rated);
const record = { lowering_refused: why };
if (caught) record.caught_by = caught;
if (severity !== rated) record.original_severity = rated;
return { severity, record };
}
/** A current finding in today's verdict shape, plus the pass-through fields. */
function project(f) {
const rated = normalizeSeverity(f.severity);
const out = {
id: f.id ?? null,
severity: rated ?? 'blocker',
rule_key: f.rule_key ?? null,
file: f.file ?? null,
line: f.line ?? null,
text: typeof f.text === 'string' ? f.text : '',
raised_by: Array.isArray(f.raised_by) ? [...f.raised_by] : [],
};
if (rated === null) out.severity_defaulted = true;
if (Number.isInteger(f.line_end)) out.line_end = f.line_end;
if (Array.isArray(f.rule_keys)) out.rule_keys = [...f.rule_keys];
return out;
}
/**
* Where a current finding sits in the operative text, or null when it has no
* plan line (another file, no line, a line in the review log, past the end,
* or a `line_end` that does not map).
*/
function placeOf(f, fullToOp, planSet) {
if (typeof f.file !== 'string' || f.file === '' || !planSet.has(resolve(f.file))) return null;
const at = l => (Number.isInteger(l) && l >= 1 && l < fullToOp.length ? fullToOp[l] ?? null : null);
const start = at(f.line);
if (start === null) return null;
const hasEnd = f.line_end !== undefined && f.line_end !== null;
let end = start;
if (hasEnd) {
const e = Number.isInteger(f.line_end) && f.line_end >= f.line ? at(f.line_end) : null;
if (e === null) return null;
end = Math.max(start, e);
}
return { start, end, hasEnd };
}
const contentSize = t => new Set(contentTokens(typeof t === 'string' ? t : '')).size;
/** Does current finding `f` (placed at `pl`, outside the diff) re-report previous finding `p`? */
function sameFinding(f, pl, p, d) {
if (typeof f.id === 'string' && f.id === p.id) return true;
const pCites = hasOwn(p, 'op_line');
if (pl && pCites && Number.isInteger(p.op_line)) {
const n = d.oldToNew[p.op_line] ?? null;
if (n !== null && n >= pl.start && n <= pl.end) return true;
}
const sameClass = (pl !== null && pCites) ||
(typeof f.file === 'string' && f.file !== '' && f.file === p.file);
if (!sameClass) return false;
if (contentSize(f.text) < ANCHOR_MIN_CONTENT_WORDS || contentSize(p.text) < ANCHOR_MIN_CONTENT_WORDS) return false;
return contentOverlap(f.text, p.text) >= DEFAULT_THRESHOLD;
}
/** A previous finding leaves the count only on its raisers' true, nobody's false. */
function isResolved(p, marks) {
const ms = marks.filter(m => m && typeof m.id === 'string' && m.id === p.id);
if (!ms.some(m => m.resolved === true)) return false;
if (ms.some(m => m.resolved === false)) return false;
const raisers = Array.isArray(p.raised_by) ? p.raised_by : [];
return raisers.every(r => ms.some(m => m.agent === r && m.resolved === true));
}
/** A previous finding carried into this round, with its matches' severities and keys. */
function carry(p, matched, d, current, prevRound) {
const pSev = countedOf(p.severity);
const orig = normalizeSeverity(p.original_severity);
const wasLowered = orig !== null && rankOf(orig) < rankOf(pSev);
const keys = union(keysOf(p), ...matched.map(m => keysOf(m.f)));
let sev;
if (wasLowered) {
if (keys.some(isSecurityKey)) sev = matched.reduce((s, m) => higher(s, m.sev), orig);
else if (matched.some(m => m.sev === 'blocker')) sev = 'blocker';
else sev = pSev;
} else {
sev = matched.reduce((s, m) => higher(s, m.sev), pSev);
}
const out = {
id: p.id ?? null,
severity: sev,
rule_key: p.rule_key ?? null,
file: p.file ?? null,
line: p.line ?? null,
text: typeof p.text === 'string' ? p.text : '',
raised_by: union(p.raised_by, ...matched.map(m => m.f.raised_by)),
};
if (p.severity_defaulted === true) out.severity_defaulted = true;
if (Number.isInteger(p.line_end)) out.line_end = p.line_end;
if (keys.length > 0) out.rule_keys = keys;
if (hasOwn(p, 'op_line')) {
// A plan line: follow the diff. Its own line edited (or no op_line already):
// keep the old line, op_line null, never re-mapped from a stale position.
const n = Number.isInteger(p.op_line) ? (d.oldToNew[p.op_line] ?? null) : null;
out.op_line = n;
if (n !== null) {
out.line = current.opToFull[n] ?? out.line;
const e = Number.isInteger(p.op_line_end) ? (d.oldToNew[p.op_line_end] ?? null) : null;
const eFull = e !== null ? (current.opToFull[e] ?? null) : null;
if (e !== null && eFull !== null) {
out.line_end = eFull;
out.op_line_end = e;
} else {
delete out.line_end;
}
} else if (hasOwn(p, 'op_line_end')) {
out.op_line_end = null;
}
}
out.carried_from = Number.isInteger(p.carried_from) ? p.carried_from : prevRound;
if (wasLowered) {
if (rankOf(sev) > rankOf(orig)) {
out.original_severity = orig;
if (typeof p.lowered_by === 'string') out.lowered_by = p.lowered_by;
if (typeof p.caught_by === 'string') out.caught_by = p.caught_by;
}
} else {
if (orig !== null && orig !== sev) out.original_severity = orig;
if (typeof p.lowering_refused === 'string') out.lowering_refused = p.lowering_refused;
if (typeof p.caught_by === 'string') out.caught_by = p.caught_by;
}
return out;
}
/** One line: the reason a round is counted fully. */
const oneLine = s => String(s).replace(/\s*[\r\n]+\s*/g, ' ').trim();
/**
* Count one critic round by rule A (from round 2, against the diff since the
* text the previous round reviewed) and record rule B (every round).
* Pure and deterministic.
* @param {{round: number, previous: object|null, base: {sha256: string, text: string}|null,
* baseNote?: string|null, current: {text: string, sha256: string, fullToOp: Array<number|null>, opToFull: Array<number|null>},
* planPaths: string[], findings: object[], marks: Array<{agent: string, id: string, resolved: boolean}>}} input
* @returns {{findings: object[], resolved: string[]|null, diffBase: string|null, diffNote: string|null, lowered: number}}
*/
export function countRound({ round, previous, base, baseNote, current, planPaths, findings, marks }) {
const prevRound = previous && Number.isInteger(previous.round) ? previous.round : null;
let diffNote = null;
let d = null;
if (Number.isInteger(round) && round >= 2 && prevRound !== null) {
if (!base || typeof base !== 'object') {
diffNote = typeof baseNote === 'string' && baseNote.trim() !== ''
? oneLine(baseNote)
: `no base snapshot of round ${prevRound}'s reviewed text; full counting`;
} else if (typeof base.sha256 !== 'string' || base.sha256 !== previous.plan_sha256) {
diffNote = `the base snapshot is not the text round ${prevRound} reviewed; full counting`;
} else if (base.sha256 === current.sha256) {
diffNote = `the plan has not changed since round ${prevRound}; full counting`;
} else if (typeof base.text !== 'string') {
diffNote = `the base snapshot of round ${prevRound} has no text; full counting`;
} else {
d = lineDiff(base.text, current.text);
}
}
const ruleA = d !== null;
const planSet = new Set(Array.isArray(planPaths) ? planPaths : []);
const fullToOp = Array.isArray(current?.fullToOp) ? current.fullToOp : [];
const prevFindings = ruleA && Array.isArray(previous.findings)
? previous.findings.filter(p => p && typeof p === 'object')
: [];
const markList = Array.isArray(marks) ? marks : [];
const matchedTo = new Map(prevFindings.map(p => [p, []]));
const fresh = [];
for (const f of Array.isArray(findings) ? findings : []) {
const o = project(f);
const b = ruleB(f, o.severity);
o.severity = b.severity;
Object.assign(o, b.record);
const pl = placeOf(f, fullToOp, planSet);
let inside = false;
if (ruleA && pl) {
for (let n = pl.start; n <= pl.end && !inside; n++) inside = d.inside.has(n);
}
if (ruleA && !inside) {
const p = prevFindings.find(q => sameFinding(f, pl, q, d));
if (p) {
matchedTo.get(p).push({ f, sev: o.severity });
continue;
}
}
if (pl) {
o.op_line = pl.start;
if (pl.hasEnd) o.op_line_end = pl.end;
}
if (ruleA && o.severity === 'major' && pl && !inside && !isSecurity(f)) {
o.severity = 'minor';
o.original_severity = 'major';
o.lowered_by = `rule A: outside the diff since round ${prevRound}`;
}
fresh.push(o);
}
const carried = [];
const resolved = [];
for (const p of prevFindings) {
const matched = matchedTo.get(p);
if (matched.length === 0 && isResolved(p, markList)) {
resolved.push(p.id);
continue;
}
carried.push(carry(p, matched, d, current, prevRound));
}
const out = [...carried, ...fresh];
const lowered = out.filter((x) => {
const o = normalizeSeverity(x.original_severity);
return o !== null && rankOf(o) < rankOf(x.severity);
}).length;
return {
findings: out,
resolved: ruleA ? resolved : null,
diffBase: ruleA ? base.sha256 : null,
diffNote,
lowered,
};
}

View file

@ -53,12 +53,30 @@
// then stop and ask; never silently on. Unrated findings count as blockers.
// The verdict is a trace of a process, not a signature: anything that can
// write the plan can write the block.
//
// Rule A (decision 43): from critic round 2 on, `recordVerdict` counts a round
// against the diff between the operative text the previous round reviewed (the
// base, `opts.base`) and the plan now, through `countRound` in
// lib/review/critic-diff.mjs. A new MAJOR that cites a plan line outside that
// diff counts as minor; a blocker, a security finding and a finding with no
// plan line count at full severity; a previous finding stays counted (carried,
// with its id) until every reviewer that raised it marks it resolved and nobody
// re-reports it. Rule B (a major a named test, `Regression:` command or gate
// will fail on is minor) is recorded from round 1 and never lowers a blocker or
// a security finding. Without a usable base (none, not the previous round's
// text, or the plan unchanged since it) the round is counted as before, and
// `diff_note` says why in one line. Every new verdict field is optional
// (DIFF_FIELDS); its absence means round-1 behaviour, so an older block gives
// the same exits. Trust limit: anything that can write the plan can also
// rewrite the previous verdict's plan_sha256 and plant a matching base; rule A
// raises what such a forgery buys, and an unchanged base lowers nothing.
import { readFileSync, existsSync, writeFileSync, renameSync, rmSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { validatePlanContent } from './plan-validator.mjs';
import { splitSections, fenceTracker, extractPlanVersion, versionAtLeast } from '../parsers/plan-schema.mjs';
import { normalizeSeverity } from '../review/plan-review-dedup.mjs';
import { countRound } from '../review/critic-diff.mjs';
import { isMain } from '../util/is-main.mjs';
export const MAX_ROUNDS = 3;
@ -218,9 +236,15 @@ function missingReviewers(dedup) {
* @param {string} text - the plan
* @param {{findings: Array<object>, sources: Array<{agent: string, present: boolean}>}} dedup
* plan-review-dedup.mjs output
* @param {{reviewed?: string, extraRound?: boolean, maxRounds?: number, now?: string}} [opts]
* reviewed = planHash of the text the reviewers read (from --hash)
* @returns {{code: 0|1|2, text?: string, verdict?: object, message: string}}
* @param {{reviewed?: string, extraRound?: boolean, maxRounds?: number, now?: string,
* base?: {sha256: string, text: string}|null, baseNote?: string, planPaths?: string[]}} [opts]
* reviewed = planHash of the text the reviewers read (from --hash);
* base = the operative text the previous round reviewed, with its sha256;
* baseNote = why there is no base (one line, written as diff_note);
* planPaths = the absolute forms of the plan path (a finding whose
* resolve(file) is one of them cites the plan). Without base, baseNote and
* planPaths the round is recorded as before, plus the rule-B record.
* @returns {{code: 0|1|2, text?: string, verdict?: object, lowered?: number, message: string}}
*/
export function recordVerdict(text, dedup, opts = {}) {
if (!dedup || typeof dedup !== 'object' || !Array.isArray(dedup.findings)) {
@ -257,20 +281,19 @@ export function recordVerdict(text, dedup, opts = {}) {
};
}
const extra = prevExtra + (capped ? 1 : 0);
const findings = dedup.findings.map((f) => {
const sev = normalizeSeverity(f.severity);
const out = {
id: f.id ?? null,
severity: sev ?? 'blocker',
rule_key: f.rule_key ?? null,
file: f.file ?? null,
line: f.line ?? null,
text: typeof f.text === 'string' ? f.text : '',
raised_by: Array.isArray(f.raised_by) ? f.raised_by : [],
};
if (sev === null) out.severity_defaulted = true;
return out;
const diffMode = opts.base !== undefined || opts.baseNote !== undefined || opts.planPaths !== undefined;
const lines = operativeLines(text);
const c = countRound({
round,
previous: prev.verdict ?? null,
base: opts.base ?? null,
baseNote: opts.baseNote ?? null,
current: { text: lines.text, sha256: current, fullToOp: lines.fullToOp, opToFull: lines.opToFull },
planPaths: Array.isArray(opts.planPaths) ? opts.planPaths : [],
findings: dedup.findings,
marks: Array.isArray(dedup.marks) ? dedup.marks : [],
});
const findings = c.findings;
const counts = { blocker: 0, major: 0, minor: 0 };
for (const f of findings) counts[f.severity] += 1;
const verdict = {
@ -280,11 +303,17 @@ export function recordVerdict(text, dedup, opts = {}) {
extra_rounds: extra,
recorded_at: opts.now ?? new Date().toISOString(),
plan_sha256: current,
verdict: verdictFor(counts),
counts,
findings,
};
return { code: 0, text: placeSection(text, renderSection(verdict)), verdict, message: `round ${round} recorded: ${verdict.verdict}` };
if (c.diffBase !== null) verdict.diff_base = c.diffBase;
if (diffMode && c.diffNote !== null) verdict.diff_note = c.diffNote;
verdict.verdict = verdictFor(counts);
verdict.counts = counts;
verdict.findings = findings;
if (c.resolved !== null) verdict.resolved = c.resolved;
return {
code: 0, text: placeSection(text, renderSection(verdict)), verdict, lowered: c.lowered,
message: `round ${round} recorded: ${verdict.verdict}`,
};
}
const sevOf = f => normalizeSeverity(f.severity);