@dzhechkov/harness-core 0.8.40 → 0.8.41

package/src/reqe-verdict.ts

@@ -0,0 +1,174 @@
+export type ReqeSeverity = 'BLOCKER' | 'HIGH' | 'MEDIUM' | 'LOW' | 'unknown';
+export interface ReqeSeverityCounts {
+  readonly blocker: number; readonly high: number; readonly medium: number;
+  readonly low: number;     readonly unknown: number;
+}
+/** `where` is null when the location cell is an em dash — the title alone is echoed (ADR AM-5). */
+export interface ReqeBlockingRow {
+  readonly severity: 'BLOCKER' | 'HIGH'; readonly title: string; readonly where: string | null;
+}
+/** THREE states, never two (03.5 C5b): `absent` = no Findings section; `rejected` = section present,
+ *  table not canonical, reason NAMED; `accepted` = parsed. */
+export type ReqeFindingsClass =
+  | { readonly kind: 'accepted'; readonly counts: ReqeSeverityCounts; readonly rows: number;
+      readonly declared: number | null; readonly blocking: readonly ReqeBlockingRow[] }
+  | { readonly kind: 'rejected'; readonly reason: string }
+  | { readonly kind: 'absent' };
+export type ReqePriorVerdict =
+  | { readonly kind: 'closed'; readonly closed: number; readonly total: number }
+  | { readonly kind: 'open'; readonly open: readonly number[]; readonly total: number }
+  | { readonly kind: 'unassessed' };
+export interface ReqeVerdict {
+  readonly new: 'ready' | 'blocked' | 'unassessed';
+  readonly prior: ReqePriorVerdict;
+  readonly findings: ReqeFindingsClass;
+  readonly counts: ReqeSeverityCounts;           // all zeros unless findings.kind === 'accepted'
+  readonly rows: number;                         // 0 unless accepted
+  readonly blocking: readonly ReqeBlockingRow[]; // [] unless accepted
+  readonly source: 'reviewer-declared';          // FR-6: the declarer is named in the data too
+}
+
+const emptyCounts = (): ReqeSeverityCounts => ({ blocker: 0, high: 0, medium: 0, low: 0, unknown: 0 });
+const heading = /^#{1,6}[ \t]+/;
+const findingsHeading = /^#{1,6}[ \t]*Findings(?:[ \t]+\((\d+)\))?[ \t]*$/;
+const expectedTable = 'expected severity plus finding/title and location/where columns';
+
+/** qe-findings.ts does not export maskMarkdown. This local fallback blanks fences and
+ * HTML comments without moving source lines, as permitted by the TASK-1 contract. */
+function maskMarkdown(text: string): string {
+  let fence: string | null = null;
+  let inComment = false;
+  return text.split('\n').map((line) => {
+    if (fence !== null) {
+      const close = /^ {0,3}(`{3,}|~{3,})[ \t]*\r?$/.exec(line)?.[1];
+      if (close && close[0] === fence[0] && close.length >= fence.length) fence = null;
+      return ' '.repeat(line.length);
+    }
+    let visible = '';
+    for (let i = 0; i < line.length;) {
+      if (inComment) {
+        const end = line.indexOf('-->', i);
+        if (end === -1) { visible += ' '.repeat(line.length - i); break; }
+        visible += ' '.repeat(end + 3 - i);
+        i = end + 3;
+        inComment = false;
+      } else {
+        const start = line.indexOf('<!--', i);
+        if (start === -1) { visible += line.slice(i); break; }
+        visible += line.slice(i, start) + '    ';
+        i = start + 4;
+        inComment = true;
+      }
+    }
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(visible)?.[1];
+    if (open) { fence = open; return ' '.repeat(line.length); }
+    return visible;
+  }).join('\n');
+}
+
+function cells(line: string): string[] {
+  const parts = line.trim().split(/(?<!\\)\|/);
+  if (parts[0] === '') parts.shift();
+  if (parts[parts.length - 1] === '') parts.pop();
+  return parts.map((cell) => cell.replace(/\\\|/g, '|').trim());
+}
+
+function severityOf(cell: string): ReqeSeverity {
+  switch (cell.trim().toLowerCase()) {
+    case 'blocker': case 'critical': return 'BLOCKER';
+    case 'high': case 'major': return 'HIGH';
+    case 'medium': case 'med': return 'MEDIUM';
+    case 'low': case 'minor': return 'LOW';
+    default: return 'unknown';
+  }
+}
+
+/** Read only the single Findings section; malformed attempts carry an explicit reason. */
+export function classifyReqeFindings(text: string): ReqeFindingsClass {
+  const lines = maskMarkdown(text).split(/\r?\n/);
+  const sections = lines.flatMap((line, index) => {
+    const match = findingsHeading.exec(line);
+    return match ? [{ index, declared: match[1] === undefined ? null : Number(match[1]) }] : [];
+  });
+  if (sections.length === 0) return { kind: 'absent' };
+  if (sections.length !== 1) return { kind: 'rejected', reason: `ambiguous: ${sections.length} Findings headings` };
+  const section = sections[0]!;
+  let end = section.index + 1;
+  while (end < lines.length && !heading.test(lines[end]!)) end++;
+  let start = section.index + 1;
+  while (start < end && !/(?<!\\)\|/.test(lines[start]!)) start++;
+  if (start === end) {
+    if (section.declared === 0) {
+      return { kind: 'accepted', counts: emptyCounts(), rows: 0, declared: 0, blocking: [] };
+    }
+    return { kind: 'rejected', reason: `no canonical table; ${expectedTable}` };
+  }
+  const headers = cells(lines[start]!).map((cell) => cell.toLowerCase());
+  const severityIndex = headers.indexOf('severity');
+  if (severityIndex === -1) return { kind: 'rejected', reason: `no severity column; ${expectedTable}; parsed columns: ${headers.join(', ')}` };
+  if (headers.lastIndexOf('severity') !== severityIndex) return { kind: 'rejected', reason: 'ambiguous: multiple severity columns' };
+  const titleIndex = headers.findIndex((cell) => cell === 'finding' || cell === 'title');
+  const whereIndex = headers.findIndex((cell) => cell === 'location' || cell === 'where');
+  if (titleIndex === -1 || whereIndex === -1) return { kind: 'rejected', reason: `missing finding/title or location/where column; ${expectedTable}` };
+  const delimiter = start + 1 < end ? cells(lines[start + 1]!) : [];
+  if (delimiter.length !== headers.length || !delimiter.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+    return { kind: 'rejected', reason: `row ${start + 2}: invalid delimiter; expected ${headers.length} delimiter cells for columns: ${headers.join(', ')}` };
+  }
+  const counts = { ...emptyCounts() };
+  const blocking: ReqeBlockingRow[] = [];
+  let rows = 0;
+  let finished = false;
+  for (let index = start + 2; index < end; index++) {
+    const line = lines[index]!;
+    if (!/(?<!\\)\|/.test(line)) { finished = true; continue; }
+    if (finished) return { kind: 'rejected', reason: `row ${index + 1}: ambiguous table continuation` };
+    const row = cells(line);
+    if (row.length !== headers.length) {
+      return { kind: 'rejected', reason: `row ${index + 1}: ${row.length} cells for ${headers.length} columns (unescaped pipe?); parsed columns: ${headers.join(', ')}` };
+    }
+    if (row.every((cell) => /^:?-{3,}:?$/.test(cell))) return { kind: 'rejected', reason: `row ${index + 1}: ambiguous additional table delimiter` };
+    const severity = severityOf(row[severityIndex]!);
+    const key = severity.toLowerCase() as keyof ReqeSeverityCounts;
+    counts[key]++;
+    rows++;
+    if (severity === 'BLOCKER' || severity === 'HIGH') {
+      const where = row[whereIndex]!;
+      blocking.push({ severity, title: row[titleIndex]!, where: where === '—' || where === '' ? null : where });
+    }
+  }
+  return { kind: 'accepted', counts, rows, declared: section.declared, blocking };
+}
+
+/** Independent pass: no classification or new-findings state participates in prior status. */
+export function parsePriorFindings(text: string): ReqePriorVerdict {
+  const lines = maskMarkdown(text).split(/\r?\n/);
+  const sections = lines.flatMap((line, index) => /^#{1,6}[ \t]*Prior findings[ \t]*$/.test(line) ? [index] : []);
+  if (sections.length !== 1) return { kind: 'unassessed' };
+  let total = 0;
+  const open: number[] = [];
+  for (let index = sections[0]! + 1; index < lines.length; index++) {
+    const line = lines[index]!;
+    if (heading.test(line)) break;
+    const match = /^[ \t]*(\d+):[ \t]+(closed|open)[ \t]+—[ \t]+\S.*$/.exec(line);
+    if (!match) continue;
+    total++;
+    if (match[2] === 'open') open.push(Number(match[1]));
+  }
+  if (total === 0) return { kind: 'unassessed' };
+  return open.length > 0 ? { kind: 'open', open, total } : { kind: 'closed', closed: total, total };
+}
+
+/** The only blocking rule; prior status is reported independently. */
+export function buildReqeVerdict(text: string): ReqeVerdict {
+  const findings = classifyReqeFindings(text);
+  const prior = parsePriorFindings(text);
+  const accepted = findings.kind === 'accepted';
+  const counts = accepted ? findings.counts : emptyCounts();
+  return {
+    new: accepted ? (counts.blocker >= 1 || counts.high >= 1 ? 'blocked' : 'ready') : 'unassessed',
+    prior, findings, counts,
+    rows: accepted ? findings.rows : 0,
+    blocking: accepted ? findings.blocking : [],
+    source: 'reviewer-declared',
+  };
+}

package/src/reqe.ts

@@ -9,8 +9,8 @@
  * DEBT with a lifecycle:
  *
  *   emit   — the workflow records features/<slug>/.fa-state/reqe-due.json when Step-8 actually ran
- *            same-family under the override (not on every switch — a switch before Step 8 that
- *            still got cross-family QE creates no debt);
+ *            same-family after a usage switch, failed probe, fallback or explicit QE pin;
+ *            a review that stayed cross-family creates no debt;
  *   list   — `dz reqe` scans the debts; `dz usage` surfaces the count so the moment limits free up
  *            is the moment the debt is visible;
  *   brief  — `dz reqe --slug <s>` prints a ready cross-family review brief (the OTHER family than
@@ -18,19 +18,37 @@
  *   settle — `dz reqe --slug <s> --done --report <file>` clears the debt FAIL-CLOSED: only against
  *            an existing, non-trivial report that names a grade; the settlement is appended to
  *            08_qe_report.md so the artifact trail closes.
+ * The two-part verdict reports new and prior findings separately; blocked new findings signal CLI exit 3.
  *
  * HONEST SCOPE: nothing here re-runs QE automatically (no background spend — the human decides);
- * the same-family CLAUDE belt fallback (codex unavailable) is out of scope by design — it is
- * already logged loudly at run time and is not a limit-pressure artifact; runs from before this
- * feature carry no marker and are UNDETERMINABLE, not debt-free.
+ * routing-off runs are excluded by configuration. Old checkpoints without bridge facts or a usage
+ * marker are UNDETERMINABLE and explicitly degraded.
  */
 
+import { buildReqeVerdict, type ReqeVerdict } from './reqe-verdict.js';
+
 export const REQE_SCHEMA = 'reqe-due-1';
 
 export const REQE_SCOPE =
-  'scope: debt is emitted only when Step-8 QE actually ran on the coder’s own family under the ' +
-  'usage override; settling requires a graded cross-family report (fail-closed); nothing re-runs QE ' +
-  'automatically.';
+  'scope: same-family Step-8 QE records cause=usage-switched, probe-failed, same-family-fallback ' +
+  'or same-family-pinned; routing OFF is excluded by configuration; settling requires a graded ' +
+  'cross-family report (fail-closed); nothing re-runs QE automatically.';
+
+export type ReqeCause = 'usage-switched' | 'probe-failed' | 'same-family-fallback' | 'same-family-pinned';
+export type ReqeRungState = 'pending' | 'dispatched' | 'probe-failed' | 'refused-before-dispatch';
+export interface ReqeBridgeFacts {
+  happened: boolean | null;
+  rungState: ReqeRungState | null;
+  rungReason: string | null;
+  decline: string | null;
+}
+export interface ReqeEmitInput {
+  coderUsed: string | null | undefined;
+  qeReviewerUsed: string | null | undefined;
+  qeModelLabel: string | null | undefined;
+  routingRequested: boolean | null | undefined;
+  bridge?: ReqeBridgeFacts | null;
+}
 
 export type ModelFamily = 'claude' | 'openai';
 
@@ -46,35 +64,57 @@ export function modelFamily(spec: string | null | undefined): ModelFamily {
 export interface ReqeEmitDecision {
   emit: boolean;
   reason: string;
+  cause: ReqeCause | null;
+  degraded: boolean;
 }
 
-/** Emit iff the QE stage label carries the workflow's ' (usage-switched)' marker AND the reviewer
- * family equals the coder family. Marker-only (cross-family survived the switch) or same-family
- * WITHOUT the marker (the codex-unavailable Claude belt — degraded loudly at run time, not a
- * limit-pressure artifact) both create NO debt. */
-export function shouldEmitReqeDebt(input: {
-  coderUsed: string | null | undefined;
-  qeReviewerUsed: string | null | undefined;
-  qeModelLabel: string | null | undefined;
-}): ReqeEmitDecision {
-  const switched = /\(usage-switched\)/.test(String(input.qeModelLabel ?? ''));
+/** Families are authoritative; routing OFF is an explicit exclusion. For same-family reviews,
+ * classify usage overrides before probe failures, fallbacks and explicit pins. Missing checkpoint
+ * facts and unknown rung states stay visibly degraded rather than inventing a cause. */
+export function shouldEmitReqeDebt(input: ReqeEmitInput): ReqeEmitDecision {
   const coderFam = modelFamily(input.coderUsed);
   const qeFam = modelFamily(input.qeReviewerUsed);
-  if (switched && coderFam === qeFam) {
+  if (coderFam !== qeFam) {
+    return { emit: false, cause: null, degraded: false, reason: 'cross-family QE ran' };
+  }
+  if (input.routingRequested === false) {
+    return { emit: false, cause: null, degraded: false,
+      reason: 'same-family by configuration (cross-family never requested)' };
+  }
+  if (/\(usage-switched\)/.test(String(input.qeModelLabel ?? ''))) {
     return {
-      emit: true,
+      emit: true, cause: 'usage-switched', degraded: false,
       reason:
         'usage-switched self-review: Step-8 QE ran on the coder’s own family (' + coderFam +
         ') under the limit override — the cross-model guard was suspended (FR-2.9)',
     };
   }
-  if (switched) return { emit: false, reason: 'usage-switched but QE stayed cross-family (' + qeFam + ' vs coder ' + coderFam + ')' };
-  if (coderFam === qeFam) return { emit: false, reason: 'same-family without the usage override (belt degrade — logged loudly at run time; out of re-QE-debt scope)' };
-  return { emit: false, reason: 'cross-family QE ran' };
+  if (input.bridge?.rungState === 'probe-failed') {
+    return { emit: true, cause: 'probe-failed', degraded: false,
+      reason: 'codex probe found no usable id; review ran on the coder’s own family (' + coderFam + ')' };
+  }
+  if (input.bridge?.rungState === 'dispatched' || input.bridge?.rungState === 'refused-before-dispatch' ||
+      input.qeReviewerUsed === 'codex-fallback') {
+    return { emit: true, cause: 'same-family-fallback', degraded: false,
+      reason: 'same-family fallback: ' + (input.bridge?.decline ?? input.bridge?.rungReason ?? 'cross-family reviewer unavailable') +
+        '; review ran on the coder’s own family (' + coderFam + ')' };
+  }
+  if (input.bridge == null) {
+    return { emit: false, cause: null, degraded: true,
+      reason: "cause undeterminable (pre-change checkpoint) — re-run with resume:'never' to classify" };
+  }
+  if (input.routingRequested === true && input.bridge.rungState === 'pending') {
+    return { emit: true, cause: 'same-family-pinned', degraded: false,
+      reason: 'same-family by explicit qe pin (args.models.qe) while cross-family routing was requested' };
+  }
+  return { emit: false, cause: null, degraded: true,
+    reason: 'cause undeterminable (unknown rung state or routing request)' };
 }
 
 export interface ReqeDebt {
   schema: typeof REQE_SCHEMA;
+  cause: ReqeCause;
+  bridge?: ReqeBridgeFacts | null;
   slug: string;
   coderFamily: ModelFamily;
   qeFamily: ModelFamily;
@@ -97,15 +137,21 @@ export function buildReqeDebt(input: {
   qeGrade: string | null | undefined;
   reason: string;
   emittedAt?: string | null;
+  cause: ReqeCause;
+  bridge?: ReqeBridgeFacts | null;
+  runStamp?: string | null;
 }): ReqeDebt {
   return {
     schema: REQE_SCHEMA,
+    cause: input.cause,
+    ...(input.bridge === undefined ? {} : { bridge: input.bridge }),
     slug: input.slug,
     coderFamily: modelFamily(input.coderUsed),
     qeFamily: modelFamily(input.qeReviewerUsed),
     qeGrade: input.qeGrade == null || String(input.qeGrade).trim() === '' ? null : String(input.qeGrade).trim(),
     reason: input.reason,
     emittedAt: input.emittedAt ?? null,
+    runStamp: input.runStamp ?? null,
   };
 }
 
@@ -125,16 +171,21 @@ export function parseReqeDebt(text: string): ReqeDebt | null {
   if (d.coderFamily !== 'claude' && d.coderFamily !== 'openai') return null;
   if (d.qeFamily !== 'claude' && d.qeFamily !== 'openai') return null;
   if (typeof d.reason !== 'string' || d.reason.trim() === '') return null;
-  return {
-    schema: REQE_SCHEMA,
+  if (d.cause !== undefined && d.cause !== 'usage-switched' && d.cause !== 'probe-failed' &&
+      d.cause !== 'same-family-fallback' && d.cause !== 'same-family-pinned') return null;
+  return buildReqeDebt({
     slug: d.slug,
-    coderFamily: d.coderFamily,
-    qeFamily: d.qeFamily,
-    qeGrade: typeof d.qeGrade === 'string' && d.qeGrade.trim() !== '' ? d.qeGrade.trim() : null,
+    coderUsed: d.coderFamily,
+    qeReviewerUsed: d.qeFamily,
+    qeGrade: typeof d.qeGrade === 'string' ? d.qeGrade : null,
     reason: d.reason,
+    cause: d.cause ?? 'usage-switched',
+    ...(d.bridge === undefined ? {} : {
+      bridge: d.bridge && typeof d.bridge === 'object' && !Array.isArray(d.bridge) ? d.bridge : null,
+    }),
     emittedAt: typeof d.emittedAt === 'string' && d.emittedAt.trim() !== '' ? d.emittedAt : null,
     runStamp: typeof d.runStamp === 'string' && d.runStamp.trim() !== '' ? d.runStamp : null,
-  };
+  });
 }
 
 export interface ReqeBrief {
@@ -155,11 +206,12 @@ export function buildReqeBrief(debt: ReqeDebt, artifactsDir: string): ReqeBrief
     artifactsDir + '/03_adr/',
   ];
   const instructions = [
-    'Independent re-QE for "' + debt.slug + '": the recorded Step-8 review ran on the coder’s own family (' + debt.coderFamily + ') under the usage override' + (debt.qeGrade ? ' and graded ' + debt.qeGrade : '') + '.',
+    'Independent re-QE for "' + debt.slug + '": the recorded Step-8 review ran on the coder’s own family (' + debt.coderFamily + '); cause=' + debt.cause + (debt.qeGrade ? ' and graded ' + debt.qeGrade : '') + '.',
     'Review with the ' + reviewFamily.toUpperCase() + ' family (the OTHER family than the coder — the suspended guard, restored).',
     'Read: ' + files.join(' , ') + ' plus every file the change manifest lists.',
     'Adversarially verify: correctness, edge cases, the ADR-named load-bearing property HAS a test, and whether the same-family review missed anything.',
     'Output: GRADE A-F + numbered findings with file:line and severity; write the report to ' + artifactsDir + '/08b_reqe_report.md.',
+    'Also list every finding of the same-family 08_qe_report.md by number under a "## Prior findings" heading, one line each: <n>: closed|open — <reason>.',
     'Then settle the debt: dz reqe --slug ' + debt.slug + ' --done --report ' + artifactsDir + '/08b_reqe_report.md',
   ];
   const codexCmdTemplate = reviewFamily === 'openai'
@@ -178,6 +230,7 @@ export interface ReqeSettlement {
   error: string | null;
   grade: string | null;
   epilogue: string | null;
+  verdict: ReqeVerdict | null;
 }
 
 /** Extract the verdict grade from a report, or null. LINE-ANCHORED and range-proof (Codex QE #7):
@@ -212,12 +265,18 @@ export function extractReportGrade(text: string): string | null {
 export function settleReqeDebt(debt: ReqeDebt, reportText: string, reportPath: string): ReqeSettlement {
   const text = String(reportText ?? '');
   if (text.trim().length < 200) {
-    return { ok: false, error: 'report too small to be a review (< 200 chars of substance) — refusing to settle', grade: null, epilogue: null };
+    return { ok: false, error: 'report too small to be a review (< 200 chars of substance) — refusing to settle', grade: null, epilogue: null, verdict: null };
   }
   const grade = extractReportGrade(text);
   if (grade === null) {
-    return { ok: false, error: 'report names no unambiguous line-anchored GRADE (A-F) — text without exactly one verdict grade is not a verdict; refusing to settle', grade: null, epilogue: null };
+    return { ok: false, error: 'report names no unambiguous line-anchored GRADE (A-F) — text without exactly one verdict grade is not a verdict; refusing to settle', grade: null, epilogue: null, verdict: null };
   }
+  const verdict = buildReqeVerdict(text);
+  const { counts, findings, prior } = verdict;
+  const priorSummary = prior.kind === 'closed' ? `closed (${prior.closed}/${prior.total})`
+    : prior.kind === 'open' ? `open(${prior.open.length}) of ${prior.total}` : 'unassessed';
+  const mismatch = findings.kind === 'accepted' && findings.declared !== null && findings.declared !== findings.rows
+    ? ` (declared ${findings.declared}, parsed ${findings.rows})` : '';
   const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
   const epilogue = [
     '',
@@ -230,24 +289,41 @@ export function settleReqeDebt(debt: ReqeDebt, reportText: string, reportPath: s
     '',
     '- report: `' + reportPath + '`',
     '- re-QE grade: **' + grade + '**' + (debt.qeGrade ? ' (same-family grade on record: ' + debt.qeGrade + ')' : ''),
+    `- new findings: ${verdict.new} — BLOCKER ${counts.blocker}, HIGH ${counts.high}, MEDIUM ${counts.medium}, LOW ${counts.low}, unknown ${counts.unknown} (rows ${verdict.rows})${mismatch}`,
+    `- prior findings: ${priorSummary}`,
+    ...(findings.kind === 'accepted' ? [] : [
+      `- findings: unclassified (${findings.kind === 'absent' ? 'absent' : `rejected: ${findings.reason}`})`,
+    ]),
+    ...verdict.blocking.map((row) => `- ${row.severity} — ${row.title}${row.where === null ? '' : ` (${row.where})`}`),
+    '- severities and prior-finding status as declared by the reviewer; dz reqe counts them, it does not judge them.',
     '- settled via `dz reqe --done` (fail-closed: an existing graded report is required).',
     '',
   ].join('\n');
-  return { ok: true, error: null, grade, epilogue };
+  return { ok: true, error: null, grade, epilogue, verdict };
 }
 
 /** Render the debt list for `dz reqe` / the `dz usage` surfacing line. */
 export function renderReqeList(debts: readonly ReqeDebt[], malformed: number): string[] {
   const lines: string[] = [];
   if (debts.length === 0 && malformed === 0) {
-    lines.push('dz reqe: no re-QE debts — every recorded run kept cross-model QE (or none used the usage override).');
+    lines.push('dz reqe: no re-QE debts — no unsettled machine debts recorded.');
   } else {
     lines.push('dz reqe — ' + debts.length + ' unsettled re-QE debt(s):');
     for (const d of debts) {
-      lines.push('  ' + d.slug + '  coder=' + d.coderFamily + ' qe=' + d.qeFamily + (d.qeGrade ? ' grade=' + d.qeGrade : '') + (d.emittedAt ? '  ' + d.emittedAt : '') + '  → dz reqe --slug ' + d.slug);
+      lines.push('  ' + d.slug + '  coder=' + d.coderFamily + ' qe=' + d.qeFamily + (d.qeGrade ? ' grade=' + d.qeGrade : '') + (d.emittedAt ? '  ' + d.emittedAt : '') + ' cause=' + d.cause + '  → dz reqe --slug ' + d.slug);
     }
   }
   if (malformed > 0) lines.push('  ' + malformed + ' malformed debt file(s) skipped (named, never silent).');
   lines.push(REQE_SCOPE);
   return lines;
 }
+
+
+/** Stable keys, including zero counts, for the dz usage JSON output. */
+export function countReqeByCause(debts: readonly ReqeDebt[]): Record<ReqeCause, number> {
+  const counts: Record<ReqeCause, number> = {
+    'usage-switched': 0, 'probe-failed': 0, 'same-family-fallback': 0, 'same-family-pinned': 0,
+  };
+  for (const debt of debts) counts[debt.cause] += 1;
+  return counts;
+}

package/src/round.ts

@@ -78,6 +78,16 @@ export interface RoundLedgerRow {
   readonly reason: string | null;
   readonly round: number;
   readonly lessons: readonly string[];
+  /** Recall coverage for the "доведённая работа" metric: measured on 2026-09-21, 0 of 462
+   * ledger rows carried `recalled`, losing the shown-to-used link across 124 round rows.
+   * Preserve the lessons shown at open as exact IDs, deduplicated by Set and sorted; omit when empty. */
+  readonly recalled?: readonly string[];
+  /** Used lessons drawn from the shown set: `recalled` intersected with `lessons`, sorted and
+   * omitted when empty. Lessons obtained elsewhere do not count toward recall coverage. */
+  readonly recalledUsed?: readonly string[];
+  /** Shown lessons not used: `recalled` minus `lessons`, sorted and omitted when empty. Together
+   * with `recalledUsed`, preserves the denominator for the "доведённая работа" metric. */
+  readonly recalledUnused?: readonly string[];
   readonly noNewKnowledge: string | null;
   readonly note: string;
   readonly date: null;
@@ -568,6 +578,11 @@ export function closeRound(input: {
     ? (nonEmpty(input.shipTreeDirtyReason) ? input.shipTreeDirtyReason.trim() : 'not provided')
     : undefined;
 
+  const recalled = [...new Set(input.state.recalled)].sort();
+  const usedLessons = new Set(lessons);
+  const recalledUsed = recalled.filter((id) => usedLessons.has(id));
+  const recalledUnused = recalled.filter((id) => !usedLessons.has(id));
+
   const row: RoundLedgerRow = {
     slug: input.state.slug,
     stage: 'round',
@@ -584,6 +599,9 @@ export function closeRound(input: {
     reason: nonEmpty(input.reason) ? input.reason.trim() : null,
     round: input.state.round,
     lessons,
+    ...(recalled.length > 0 ? { recalled } : {}),
+    ...(recalledUsed.length > 0 ? { recalledUsed } : {}),
+    ...(recalledUnused.length > 0 ? { recalledUnused } : {}),
     noNewKnowledge: noNewKnowledge === '' ? null : noNewKnowledge,
     note: note === '' ? marker : `${marker} | ${note}`,
     date: null,

package/src/session-retro.ts

@@ -18,7 +18,7 @@ import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, cl
 import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 
-import { withNamedLockSync, NamedLockTimeoutError } from './named-lock.js';
+import { withProjectLockSync, NamedLockTimeoutError } from './named-lock.js';
 
 export interface SessionEvent {
   readonly kind: 'user' | 'assistant' | 'tool';
@@ -696,7 +696,7 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
  * a partial trailing line is left for the next scan) → fold the debt → persist state + sentinel.
  * NEVER throws (it runs inside a Stop hook; a broken scan must never surface as a turn failure).
  *
- * The WHOLE read→fold→write runs under `withNamedLockSync` (cross-family QE P1-3): two overlapping
+ * The WHOLE read→fold→write runs under `withProjectLockSync` (cross-family QE P1-3): two overlapping
  * Stop scans that both read the same offset/sentinel and then rename/unlink independently lose one
  * side's update — atomic per-file renames do not prevent that, only mutual exclusion does. The
  * critical section is short and synchronous (bounded ≤8 MB read, no subprocess, 65 ms measured on
@@ -707,7 +707,7 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
 export function runRetroTailScan(dzDir: string, transcriptPath: string | null, nowIso?: string): TailScanOutcome {
   if (transcriptPath === null || transcriptPath === '') return { status: 'no-transcript', scannedBytes: 0, offset: 0 };
   try {
-    return withNamedLockSync(
+    return withProjectLockSync(
       dirname(dzDir),
       RETRO_SCAN_LOCK_NAME,
       () => scanTailUnderLock(dzDir, transcriptPath, nowIso),