@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/design_sync.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env tsx
+/**
+ * `/design-system:sync plan|reconcile|verify` (road-to-a-canvas-the-code-owns
+ * Phase 4).
+ *
+ * The repository is the only store of the design system; the host's canvas
+ * holds a projection of it, which the host's own `/design-sync` produces and
+ * which only the user starts. This script never starts it, never writes to the
+ * canvas and never touches the network. It reads files and writes exactly one:
+ * `<scope>/.claude/design-system/sync-ledger.json`.
+ *
+ * CLI:
+ *
+ *   design_sync plan      --code <design-system.json> [--remote <snapshot-dir>]
+ *                         [--base-commit <sha>] [--scope-root <dir>]
+ *   design_sync reconcile [--set <key>=<disposition>]... [--maturity <m>]
+ *                         [--intent preserve|extend|redesign] [--owner fe-design|directives/ui]
+ *                         [--scope-root <dir>]
+ *   design_sync verify    [--render-check <file>] [--baseline <path>]...
+ *                         [--accept-render <field>=<reason>]... [--state <state>]
+ *                         [--scope-root <dir>]
+ *
+ * Exit codes: 0 — done, nothing open · 1 — rows await a disposition, a check
+ * failed, or the ledger is invalid · 2 — argument error · 3 — internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { detect_component_taxonomy } from '../agent-src/templates/scripts/work_engine/taxonomy/detect.js';
+import { importClaudeDesignSnapshot } from './_lib/design_system_claude_design.js';
+import type { DesignSystem } from './_lib/design_system_import.js';
+import {
+    DISPOSITIONS,
+    type Disposition,
+    LEDGER_RELATIVE,
+    type Ledger,
+    PROJECTION_STATES,
+    type ProjectionState,
+    serializeLedger,
+    validateLedger,
+} from './_lib/design_sync_ledger.js';
+import { planCounts, planLedger, readBaseAtCommit } from './_lib/design_sync_plan.js';
+import { matrixRows, reconcileLedger } from './_lib/design_sync_reconcile.js';
+import { stampBaselines, verifyLedger } from './_lib/design_sync_verify.js';
+import type { ChangeIntent, ReferenceMaturity } from './_lib/ui_authority.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const USAGE = 'usage: design_sync {plan|reconcile|verify} [options] — see the file header';
+const CONFIG_RELATIVE = '.design-sync/config.json';
+
+class ArgError extends Error {}
+
+interface Parsed {
+    verb: 'plan' | 'reconcile' | 'verify';
+    single: Map<string, string>;
+    multi: Map<string, string[]>;
+}
+
+const MULTI = new Set(['--set', '--baseline', '--accept-render']);
+const SINGLE = new Set(['--scope-root', '--code', '--remote', '--base-commit', '--maturity', '--intent', '--owner', '--render-check', '--state']);
+
+export function parseArgs(argv: readonly string[]): Parsed {
+    const [verb, ...rest] = argv;
+    if (verb !== 'plan' && verb !== 'reconcile' && verb !== 'verify') throw new ArgError('the first argument must be plan, reconcile or verify');
+    const single = new Map<string, string>();
+    const multi = new Map<string, string[]>();
+    for (let i = 0; i < rest.length; i++) {
+        const flag = rest[i] as string;
+        const value = rest[i + 1];
+        if (!SINGLE.has(flag) && !MULTI.has(flag)) throw new ArgError(`unrecognized argument: ${flag}`);
+        if (value === undefined) throw new ArgError(`argument ${flag}: expected one argument`);
+        i += 1;
+        if (MULTI.has(flag)) multi.set(flag, [...(multi.get(flag) ?? []), value]);
+        else single.set(flag, value);
+    }
+    return { verb, single, multi };
+}
+
+function pairs(values: readonly string[] | undefined, flag: string): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const v of values ?? []) {
+        const eq = v.indexOf('=');
+        if (eq <= 0) throw new ArgError(`argument ${flag}: expected <key>=<value>, got "${v}"`);
+        out[v.slice(0, eq)] = v.slice(eq + 1);
+    }
+    return out;
+}
+
+function readJson(file: string): unknown {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8')) as unknown;
+    } catch {
+        return null;
+    }
+}
+
+function writeIfChanged(file: string, text: string): void {
+    try {
+        if (fs.readFileSync(file, 'utf-8') === text) return;
+    } catch {
+        /* first write */
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, 'utf-8');
+}
+
+function loadLedger(scope: string): Ledger | null {
+    const raw = readJson(path.join(scope, LEDGER_RELATIVE));
+    if (raw === null) return null;
+    const errors = validateLedger(raw);
+    if (errors.length > 0) throw new ArgError(`the existing ledger is invalid: ${errors.join('; ')}`);
+    return raw as Ledger;
+}
+
+function gitRoot(dir: string): string | null {
+    let d = path.resolve(dir);
+    for (;;) {
+        if (fs.existsSync(path.join(d, '.git'))) return d;
+        const up = path.dirname(d);
+        if (up === d) return null;
+        d = up;
+    }
+}
+
+function runPlan(p: Parsed, scope: string, out: string[]): number {
+    const codeFile = p.single.get('--code');
+    if (codeFile === undefined) throw new ArgError('plan requires --code <design-system.json> — the code-side inventory from /design-system:capture');
+    const code = readJson(codeFile) as DesignSystem | null;
+    if (code === null) throw new ArgError(`--code ${codeFile} is not readable JSON`);
+    const config = readJson(path.join(scope, CONFIG_RELATIVE)) as Record<string, unknown> | null;
+    const projectId = config !== null && typeof config['projectId'] === 'string' ? config['projectId'] : null;
+    const previous = loadLedger(scope);
+    const commit = p.single.get('--base-commit') ?? previous?.projection.commit ?? null;
+
+    let base: DesignSystem | null = null;
+    if (commit !== null) {
+        const root = gitRoot(scope);
+        if (root !== null) base = readBaseAtCommit(root, commit, path.relative(root, path.resolve(codeFile)).split(path.sep).join('/'));
+        if (base === null) out.push(`note: ${codeFile} is not readable at ${commit} — the comparison is two-way`);
+    }
+    const remoteDir = p.single.get('--remote');
+    let remote: DesignSystem | null = null;
+    if (remoteDir !== undefined) {
+        const r = importClaudeDesignSnapshot(remoteDir);
+        if (r.ok) remote = r.design_system;
+        else out.push(`note: remote unreachable — ${r.reason}`);
+    }
+    const ledger = planLedger({
+        scopeRoot: path.relative(gitRoot(scope) ?? scope, path.resolve(scope)) || '.',
+        config: CONFIG_RELATIVE,
+        code,
+        remote,
+        base,
+        projection: { projectId, commit, ...(previous?.projection.anchor_hash ? { anchor_hash: previous.projection.anchor_hash } : {}) },
+        previous,
+    });
+    writeIfChanged(path.join(scope, LEDGER_RELATIVE), serializeLedger(ledger));
+    const c = planCounts(ledger);
+    out.push(`overwrite: ${c.overwrite}  (remote-only:collides + conflict — what /design-sync would overwrite)`);
+    out.push(`twin: ${c.twin}  (remote-only:twin — left on the canvas as a second system unless dispositioned)`);
+    if (c.unknown > 0) out.push(`unknown: ${c.unknown}  (could not be classified — not empty, not in sync)`);
+    out.push(`pending: ${c.pending}`);
+    out.push(`handover: ${ledger.handover.recommended === null ? 'no recommendation' : ledger.handover.recommended ? 'ready' : 'not ready'} — ${ledger.handover.reason}`);
+    return c.pending > 0 || ledger.handover.recommended !== true ? 1 : 0;
+}
+
+function locksFrom(designMd: string): { palette: boolean; type_family: boolean } {
+    return { palette: /^\s*-\s*Colou?r Lock:/m.test(designMd), type_family: /^\s*-\s*(Type|Font) Lock:/m.test(designMd) };
+}
+
+function runReconcile(p: Parsed, scope: string, out: string[]): number {
+    const ledger = loadLedger(scope);
+    if (ledger === null) throw new ArgError(`no ledger at ${LEDGER_RELATIVE} — run plan first`);
+    const sets = pairs(p.multi.get('--set'), '--set');
+    for (const v of Object.values(sets)) {
+        if (!DISPOSITIONS.includes(v as Disposition)) throw new ArgError(`--set: "${v}" is not one of ${DISPOSITIONS.join(', ')}`);
+    }
+    let designMd = '';
+    try {
+        designMd = fs.readFileSync(path.join(scope, 'DESIGN.md'), 'utf-8');
+    } catch {
+        designMd = '';
+    }
+    const codeColours = ledger.rows.filter((r) => r.key.startsWith('colors.') && r.code !== null).map((r) => r.code as string);
+    const intent = p.single.get('--intent') as ChangeIntent | undefined;
+    const owner = p.single.get('--owner') ?? 'fe-design';
+    if (owner !== 'fe-design' && owner !== 'directives/ui') throw new ArgError('--owner must be fe-design or directives/ui');
+    const { ledger: next, errors } = reconcileLedger(ledger, {
+        referenceMaturity: (p.single.get('--maturity') ?? 'finished-comp') as Exclude<ReferenceMaturity, null>,
+        incumbent: { coherent: ledger.rows.some((r) => r.code !== null), palette: codeColours },
+        locks: locksFrom(designMd),
+        ...(intent !== undefined ? { userIntent: { change_intent: intent } } : {}),
+        dispositions: sets as Record<string, Disposition>,
+        tiers: detect_component_taxonomy(scope).tiers,
+        owner,
+    });
+    writeIfChanged(path.join(scope, LEDGER_RELATIVE), serializeLedger(next));
+    for (const b of next.briefs ?? []) out.push(`brief → ${String(b['owner'])}: ${String(b['component'])}`);
+    for (const m of matrixRows(next)) out.push(`matrix | ${m.chapter} | ${m.claim} | ${m.evidence} | ${m.status}`);
+    for (const e of errors) out.push(`open: ${e}`);
+    return errors.length > 0 ? 1 : 0;
+}
+
+function runVerify(p: Parsed, scope: string, out: string[]): number {
+    let ledger = loadLedger(scope);
+    if (ledger === null) throw new ArgError(`no ledger at ${LEDGER_RELATIVE} — run plan first`);
+    const state = p.single.get('--state');
+    if (state !== undefined) {
+        if (!PROJECTION_STATES.includes(state as ProjectionState)) throw new ArgError(`--state must be one of ${PROJECTION_STATES.join(', ')}`);
+        if (state === 'picker-confirmed') throw new ArgError('picker-confirmed is recorded by the maintainer after the host picker, never by this command');
+        ledger = { ...ledger, projection: { ...ledger.projection, state: state as ProjectionState } };
+    }
+    const baselines = p.multi.get('--baseline');
+    if (baselines !== undefined) ledger = stampBaselines(ledger, baselines);
+    const accepted = pairs(p.multi.get('--accept-render'), '--accept-render');
+    if (Object.keys(accepted).length > 0) ledger = { ...ledger, render_dispositions: { ...(ledger.render_dispositions ?? {}), ...accepted } };
+    writeIfChanged(path.join(scope, LEDGER_RELATIVE), serializeLedger(ledger));
+    const renderFile = p.single.get('--render-check') ?? path.join(scope, '.design-sync', '.render-check.json');
+    const result = verifyLedger(ledger, { renderCheck: readJson(renderFile), renderDispositions: ledger.render_dispositions ?? {} });
+    out.push(`verification: ${result.verification}`);
+    for (const r of result.reasons) out.push(`reason: ${r}`);
+    for (const s of result.stale_baselines) out.push(`stale: ${s}`);
+    for (const f of result.failures) out.push(`fail: ${f}`);
+    return result.failures.length > 0 ? 1 : 0;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let parsed: Parsed;
+    try {
+        parsed = parseArgs(argv);
+        const scope = parsed.single.get('--scope-root') ?? '.';
+        const out: string[] = [];
+        const code = parsed.verb === 'plan' ? runPlan(parsed, scope, out) : parsed.verb === 'reconcile' ? runReconcile(parsed, scope, out) : runVerify(parsed, scope, out);
+        process.stdout.write(`${out.join('\n')}\n`);
+        return code;
+    } catch (exc) {
+        if (exc instanceof ArgError) {
+            process.stderr.write(`${USAGE}\ndesign_sync: error: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        process.stderr.write(`design_sync: internal error: ${exc instanceof Error ? exc.message : String(exc)}\n`);
+        process.exit(3);
+    }
+}

package/src/scripts/design_system_import.ts

@@ -22,7 +22,10 @@
  *
  *   ./scripts-run src/scripts/design_system_import <file> [options]
  *
- *   --lane {native,dtcg,dembrandt}  Force a lane instead of detecting it.
+ *   --lane {native,dtcg,dembrandt,claude-design}
+ *                                   Force a lane instead of detecting it. A
+ *                                   directory argument is a canvas snapshot and
+ *                                   always takes the `claude-design` lane.
  *   --source-kind {url,repo,dir}    Provenance for formats that carry none.
  *   --source-ref REF                Provenance ref (the URL / repo / path).
  *   --captured-at ISO               Capture time; omitted records "unknown".
@@ -46,15 +49,16 @@ import {
     type ProvenanceOverride,
     importDesignSystem,
 } from './_lib/design_system_import.js';
+import { importClaudeDesignSnapshot } from './_lib/design_system_claude_design.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
-const LANES = new Set(['native', 'dtcg', 'dembrandt']);
+const LANES = new Set(['native', 'dtcg', 'dembrandt', 'claude-design']);
 const SOURCE_KINDS = new Set(['url', 'repo', 'dir']);
 const FORMATS = new Set(['json', 'summary']);
 
 const USAGE =
-    'usage: design_system_import <file> [--lane {native,dtcg,dembrandt}] ' +
+    'usage: design_system_import <file|snapshot-dir> [--lane {native,dtcg,dembrandt,claude-design}] ' +
     '[--source-kind {url,repo,dir}] [--source-ref REF] [--captured-at ISO] ' +
     '[--format {json,summary}]';
 
@@ -102,7 +106,7 @@ export function parse_args(argv: readonly string[]): Args {
             case '--lane': {
                 const v = take();
                 if (!LANES.has(v)) {
-                    argError(`argument --lane: invalid choice: '${v}' (choose from 'native', 'dtcg', 'dembrandt')`);
+                    argError(`argument --lane: invalid choice: '${v}' (choose from 'native', 'dtcg', 'dembrandt', 'claude-design')`);
                 }
                 args.lane = v as Lane;
                 break;
@@ -185,6 +189,25 @@ export function render_summary(outcome: ImportOutcome): string {
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const args = parse_args(argv);
 
+    const provenance: ProvenanceOverride | undefined =
+        args.sourceKind !== null && args.sourceRef !== null
+            ? {
+                  kind: args.sourceKind,
+                  ref: args.sourceRef,
+                  ...(args.capturedAt !== null ? { captured_at: args.capturedAt } : {}),
+              }
+            : undefined;
+
+    let isDir = false;
+    try {
+        isDir = fs.statSync(args.file).isDirectory();
+    } catch {
+        isDir = false;
+    }
+    if (isDir || args.lane === 'claude-design') {
+        return emit(args, importClaudeDesignSnapshot(args.file, provenance), provenance);
+    }
+
     let raw: string;
     try {
         raw = fs.readFileSync(args.file, 'utf-8');
@@ -203,16 +226,10 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         return 1;
     }
 
-    const provenance: ProvenanceOverride | undefined =
-        args.sourceKind !== null && args.sourceRef !== null
-            ? {
-                  kind: args.sourceKind,
-                  ref: args.sourceRef,
-                  ...(args.capturedAt !== null ? { captured_at: args.capturedAt } : {}),
-              }
-            : undefined;
+    return emit(args, importDesignSystem(parsed, provenance, args.lane ?? undefined), provenance);
+}
 
-    const outcome = importDesignSystem(parsed, provenance, args.lane ?? undefined);
+function emit(args: Args, outcome: ImportOutcome, provenance: ProvenanceOverride | undefined): number {
 
     // The input's own provenance wins over a caller override — defensible, and
     // previously invisible: a user who typed --source-ref was never told the

package/src/scripts/dispatch_economy_report.ts

@@ -48,6 +48,7 @@ import {
     weightedInputUnits,
     type TranscriptRecord,
 } from './_lib/cc_transcript.js';
+import { UNPAID_BILLING_CLASSES } from './ai_council/seat_policy.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/dispatch_economy_report.ts → parents[1] is the repo root (same
@@ -87,6 +88,14 @@ export interface RoleFloor {
     median_ratio_finite: number | null;
 }
 
+export interface BillingBucket {
+    ask_lines: number;
+    adopted: number;
+    escalated: number;
+    dispatch_tokens: number;
+    verify_tokens: number;
+}
+
 export interface RulesEfficiency {
     envelopes_with_pair: number;
     median_quota: number | null;
@@ -107,6 +116,14 @@ export interface Report {
         ask_lines: number;
         adopted: number;
         escalated: number;
+        /** Per `route_billing` class of the line; a line without one counts as `undeclared`. */
+        by_billing: Record<string, BillingBucket>;
+        /** Paid tokens an unpaid route served instead; null when no unpaid route served an ask. */
+        paid_tokens_avoided: number | null;
+        /** The paid head's tokens spent verifying those returns. */
+        head_verify_tokens: number | null;
+        /** The figure claim `free-hands-limit-relief` reads: avoided minus verification. */
+        net_paid_tokens_avoided: number | null;
         threshold_escalation_kill: number;
         /** null until asks exist; the registered verdict is a review-window call. */
         escalation_kill_signal: boolean | null;
@@ -177,6 +194,9 @@ interface AuditOrchestration {
     escalated?: unknown;
     return_channel_chars?: unknown;
     origin?: unknown;
+    route_billing?: unknown;
+    dispatch_tokens?: unknown;
+    verify_tokens?: unknown;
 }
 
 function isFiniteNonNegInt(v: unknown): v is number {
@@ -277,11 +297,24 @@ export function buildReport(opts: {
     let askLines = 0;
     let askAdopted = 0;
     let askEscalated = 0;
+    const byBilling: Record<string, BillingBucket> = {};
+    const bucket = (o: AuditOrchestration): BillingBucket => {
+        const k = typeof o.route_billing === 'string' && o.route_billing !== '' ? o.route_billing : 'undeclared';
+        byBilling[k] ??= { ask_lines: 0, adopted: 0, escalated: 0, dispatch_tokens: 0, verify_tokens: 0 };
+        return byBilling[k];
+    };
     const returnChars: number[] = [];
     for (const o of orchestrations) {
         if (o.route_taken === 'ask') {
             askLines += 1;
-            if (o.outcome === 'DONE') askAdopted += 1;
+            const b = bucket(o);
+            b.ask_lines += 1;
+            if (o.outcome === 'DONE') {
+                askAdopted += 1;
+                b.adopted += 1;
+            }
+            if (isFiniteNonNegInt(o.dispatch_tokens)) b.dispatch_tokens += o.dispatch_tokens;
+            if (isFiniteNonNegInt(o.verify_tokens)) b.verify_tokens += o.verify_tokens;
         }
         // Ask->spawn escalation is recorded on the CALLER's follow-up SPAWN
         // line (route_taken=subagent, escalated=true, origin-tagged) — the
@@ -290,6 +323,7 @@ export function buildReport(opts: {
         // unmeasurable by construction (review finding, 2026-08-10).
         if (o.route_taken === 'subagent' && o.escalated === true && o.origin === 'dispatch-economy-2026') {
             askEscalated += 1;
+            bucket(o).escalated += 1;
         }
         if (isFiniteNonNegInt(o.return_channel_chars)) {
             returnChars.push(o.return_channel_chars);
@@ -323,6 +357,10 @@ export function buildReport(opts: {
         median_ratio_finite: median(reviewerRatios),
     };
 
+    const unpaid = UNPAID_BILLING_CLASSES.map((c) => byBilling[c]).filter((b): b is BillingBucket => b !== undefined && b.ask_lines > 0);
+    const avoided = unpaid.length === 0 ? null : unpaid.reduce((a, b) => a + b.dispatch_tokens, 0);
+    const verifyTokens = unpaid.length === 0 ? null : unpaid.reduce((a, b) => a + b.verify_tokens, 0);
+
     const t = registration.metrics.dispatch_floor.thresholds;
     const lowQuota = registration.metrics.rules_efficiency.thresholds.low_quota_signal;
     const medianQuota = median(quotas);
@@ -353,6 +391,10 @@ export function buildReport(opts: {
             ask_lines: askLines,
             adopted: askAdopted,
             escalated: askEscalated,
+            by_billing: byBilling,
+            paid_tokens_avoided: avoided,
+            head_verify_tokens: verifyTokens,
+            net_paid_tokens_avoided: avoided === null || verifyTokens === null ? null : avoided - verifyTokens,
             threshold_escalation_kill: registration.metrics.ask_economy.thresholds.escalation_kill,
             escalation_kill_signal:
                 askLines === 0
@@ -408,6 +450,9 @@ export function renderText(r: Report): string {
     lines.push(
         `  ask lines=${r.ask_economy.ask_lines} · adopted=${r.ask_economy.adopted} · escalated=${r.ask_economy.escalated} · escalation-kill signal (> ${r.ask_economy.threshold_escalation_kill}): ${r.ask_economy.escalation_kill_signal === null ? 'no data' : String(r.ask_economy.escalation_kill_signal)}`,
     );
+    lines.push(
+        `  by billing: ${Object.entries(r.ask_economy.by_billing).map(([k, b]) => `${k}=${b.ask_lines}`).join(' · ') || 'no data'} · paid tokens avoided net of verification: ${fmtTokens(r.ask_economy.net_paid_tokens_avoided)}`,
+    );
     lines.push('');
     for (const n of r.notes) lines.push(`note: ${n}`);
     return lines.join('\n') + '\n';

package/src/scripts/dispatch_r2_reviewer.ts

@@ -56,7 +56,7 @@ import { isAcceptanceCriteriaHeading } from './_lib/ac_heading.js';
 import { gitEnv } from './_lib/git_env.js';
 import { loadDenyPatterns, redactSourceShape, redactSourceTokens, writeRedacted } from './_lib/source_redact.js';
 import { completionReviewDisabled } from './_lib/planning_settings.js';
-import { artifactRelevance } from './check_completion_review.js';
+import { REVIEW_ROUND_CAP, artifactRelevance, recordedReviewPasses } from './check_completion_review.js';
 
 export interface ManifestInputs {
     diffSha: string; // provenance only — never compared
@@ -389,8 +389,8 @@ export function leftoverArtefactRefusal(
         `    It binds scope ${staleScopeHash.slice(0, 12)}; this dispatch binds ${currentScopeHash.slice(0, 12)},\n` +
         '    so the reviewed content moved under it. That is the normal re-bind case, and\n' +
         '    contract §2.7 gives it two paths — neither of which is a fresh skeleton:\n' +
-        '      1. RE-BIND IN PLACE (the usual one): edit this artefact — new `scope:`, rows\n' +
-        '         flipped to terminal — and re-commit it. §2.5 expects exactly that.\n' +
+        '      1. RE-BIND IN PLACE (the usual one): edit this artefact — new `scope:`, same `round:`,\n' +
+        '         rows flipped to terminal — and re-commit it. §2.5 expects exactly that.\n' +
         '      2. ARCHIVE the closed round: rename it to `<slug>.round<N>-review.md` ONCE every\n' +
         '         finding is terminal, which `check_review_dispositions` enforces. Then dispatch.\n' +
         '    --force writes a fresh skeleton OVER this file and destroys the record.\n'
@@ -804,6 +804,22 @@ function reviewerPrompt(args: {
         '- inefficiencies',
         '- bug-producing patterns',
         '',
+        '## Severity',
+        '',
+        'Severity binds to correctness and to the requirements the change states',
+        '(the roadmap step, its acceptance criteria):',
+        '',
+        '- `critical` / `high` — wrong behaviour, a broken or missing check, a data',
+        '  or security exposure, or a stated requirement not met.',
+        '- `medium` — a defect that misleads a reader or fails under a condition the',
+        '  change itself names.',
+        '- `low` — style, naming, formatting or wording that changes no behaviour,',
+        '  including in record prose (roadmaps, evidence, decision records, comments).',
+        '',
+        'A false statement in record prose — a wrong figure, path or status — is not',
+        'style: it keeps the severity of what it breaks, which is high when a gate,',
+        'a command or the next step acts on it and medium when nothing does.',
+        '',
         '## Rules',
         '',
         '- Review only — write no code, fix nothing.',
@@ -893,10 +909,11 @@ function findingsSkeleton(args: {
     reviewedDate: string;
     manifest: string;
     promptHash: string;
+    round: number;
 }): string {
     return [
         `# Findings: ${args.slug}`,
-        `<!-- completion-review: v1 | reviewed: ${args.reviewedDate} | scope: ${args.scopeHash} | diff: ${args.headSha} | reviewer: r2-fresh-subagent-${args.slug} | prompt_hash: ${args.promptHash} -->`,
+        `<!-- completion-review: v1 | reviewed: ${args.reviewedDate} | scope: ${args.scopeHash} | diff: ${args.headSha} | reviewer: r2-fresh-subagent-${args.slug} | prompt_hash: ${args.promptHash} | round: ${String(args.round)} -->`,
         // SECOND PRODUCER of the independence record — step 2.2 of
         // road-to-review-independence. Until this line, `self_review_gate.ts` was the
         // only producer, which is why `check_review_schema` reported `scanned: 1`: a
@@ -1298,13 +1315,32 @@ function runDispatch(args: Args): number {
     const promptRedacted = redactSourceShape(promptTokens.text);
     redactions += promptTokens.count + promptRedacted.count;
 
+    const promptHash = sha256(promptRedacted.text);
+    // The round is the count of review passes this path records, this one
+    // included. An archived round still counts, so a fresh skeleton after the
+    // archive rename continues instead of restarting at 1.
+    const reviewRel = path.relative(args.repo, findingsAbs).split(path.sep).join('/');
+    const { passes } = recordedReviewPasses(args.repo, reviewRel);
+    passes.add(promptHash);
+    const round = passes.size;
+    if (round > REVIEW_ROUND_CAP) {
+        process.stderr.write(
+            `dispatch_r2_reviewer: refused — this would be review pass ${String(round)}, past the cap of ` +
+                `${String(REVIEW_ROUND_CAP)} (ADR-294). The review closed at round ${String(REVIEW_ROUND_CAP)}: re-bind ` +
+                `that round in place, defer open high/critical rows to ${reviewRel.replace(/\.findings\.md$/, '.owner-report.md')} ` +
+                'and medium/low rows to a ledger ref (contract §2.8).\n',
+        );
+        return 1;
+    }
+
     const skeleton = findingsSkeleton({
         slug,
         headSha,
         scopeHash: hashes.scope_hash,
         reviewedDate,
         manifest,
-        promptHash: sha256(promptRedacted.text),
+        promptHash,
+        round,
     });
 
     fs.mkdirSync(inputDirAbs, { recursive: true });