@dzhechkov/harness-core 0.3.147 → 0.3.149

package/src/feature-adr-checkpoints.ts

@@ -0,0 +1,221 @@
+/**
+ * feature-adr durable checkpoints — the PURE half (backlog 49e4a95b).
+ *
+ * Problem: .claude/workflows/feature-adr.js restarts an L/XL run from scratch when its session dies
+ * (the exact failure that forced usage-adaptive routing — one run cost 623k subagent tokens), and the
+ * STANDARD L/XL two-phase flow (stop-after-plan → re-invoke) re-runs router+design+plan wholesale.
+ * The Workflow harness's own resumeFromRunId is same-session only, so it cannot cover either case.
+ *
+ * Design: the heavyweight state is ALREADY durable — the 00–09 artifacts in features/<slug>/. The
+ * checkpoint layer is deliberately THIN: after each expensive stage the workflow appends one JSONL
+ * line { stage, inputHash, result } to features/<slug>/.fa-state/checkpoints.jsonl (via a cheap
+ * effort-low agent — the workflow sandbox has no fs). On the next run with the same slug, a stage is
+ * SKIPPED only when its recorded inputHash matches the freshly computed one AND its expected artifact
+ * is still on disk. Granularity is per-STAGE, not per-agent-call: a death mid-Step-7 re-runs Step 7,
+ * never Steps 0–6.
+ *
+ * Provenance: concept (checkpoint keyed by input hash + call cache) from ADR-157
+ * darwin-checkpoints-durable-execution (status PROPOSED) in agent-harness-generator. Its "~39% resume
+ * saving" figure is from a SYNTHETIC deterministic simulation — deliberately NOT quoted as expected
+ * field saving anywhere in this feature.
+ *
+ * Everything here is pure and deterministic (no Date/random — the workflow sandbox forbids them);
+ * the workflow script mirrors these functions inline (it is self-contained and cannot import), and
+ * the wiring test asserts the mirror stays present.
+ */
+
+/** Stages the workflow checkpoints, in pipeline order. Cheap side-channel agents (usage probes,
+ * fa-record, auto-cost selects) are never checkpointed; the opt-in Delivery gate re-runs by design
+ * (advisory verdicts should reflect the CURRENT tree). */
+export const CHECKPOINT_STAGES = ['router', 'design', 'plan', 'code', 'qe', 'fleet'] as const;
+export type CheckpointStage = (typeof CHECKPOINT_STAGES)[number];
+
+/** The artifact(s) (relative to features/<slug>/) whose PRESENCE a resume additionally requires in
+ * 'auto' mode — EVERY listed path must exist. null = result-only stage (hash match suffices).
+ * Tier-dependent stages (design) take extra artifacts at the call site via `extraArtifacts` —
+ * an M+ design must probe its ADR/ideation/architecture files too, not just requirements
+ * (Codex QE #2: a one-file probe accepted a materially incomplete design). */
+export const STAGE_ARTIFACTS: Record<CheckpointStage, string | null> = {
+  router: null,
+  design: '01_requirements.md',
+  plan: '06_implementation_plan.md',
+  code: '07_code_changes/change_manifest.md',
+  qe: '08_qe_report.md',
+  fleet: '09_fleet_qe_assessment.md',
+};
+
+/** A checkpoint line as persisted (one JSON object per line). */
+export interface CheckpointEntry {
+  stage: string;
+  inputHash: string;
+  result: unknown;
+}
+
+/** Oversize guard: a result JSON above this is NOT checkpointed (the stage simply re-runs on resume).
+ * Keeps the read-back prompt bounded; artifacts on disk carry the heavy state anyway. */
+export const CHECKPOINT_MAX_RESULT_CHARS = 12_000;
+
+/** Checkpoint format/logic version — SALTED into every input hash. Bump it whenever the workflow's
+ * stage semantics, prompts, or composite result shapes change: every pre-existing checkpoint then
+ * hashes stale and re-runs, instead of an old-format entry resuming into new logic (Codex QE #5). */
+export const CKPT_SCHEMA_VERSION = 'fa-ckpt-2';
+
+/** FNV-1a 32-bit over UTF-16 code units, hex-encoded (one pass; building block for the 64-bit form). */
+export function fnv1a(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** 64 bits from two independent FNV-1a passes (plain + salted). A single 32-bit hash admits
+ * findable collisions (Codex QE #9 produced a real pair at `11a08b58`); two passes make the
+ * single-pair collision odds ~2^-64 — adequate for one slug's checkpoint file. */
+export function fnv1a64(str: string): string {
+  return fnv1a(str) + fnv1a('
fa-ckpt-salt
' + str);
+}
+
+/** The stage's input fingerprint: a JSON-tuple (delimiter-ambiguity class — never a separator join)
+ * of the schema version + stage name + every input that would change the stage's output, hashed.
+ * Upstream stage RESULTS are included as their serialized form, so a stale upstream auto-invalidates
+ * downstream. HONEST SCOPE: the hash proves the run INPUTS are unchanged — it does NOT fingerprint
+ * the working tree (a crash-resume legitimately sees the dead run's uncommitted writes, so a tree
+ * hash would invalidate every real resume). Tree-level staleness is out of the checkpoint contract:
+ * use resume:'never' (or delete .fa-state/) after manual edits, and re-QE independently — the ADR
+ * names this as the accepted limitation (Codex QE #1). */
+export function checkpointInputHash(stage: string, parts: readonly unknown[]): string {
+  return fnv1a64(JSON.stringify([CKPT_SCHEMA_VERSION, stage, ...parts.map((p) => (p === undefined ? null : p))]));
+}
+
+export type ResumeMode = 'auto' | 'never' | 'force';
+
+/** Normalize args.resume: anything but the two explicit strings means the default 'auto'. */
+export function resumeMode(raw: unknown): ResumeMode {
+  return raw === 'never' ? 'never' : raw === 'force' ? 'force' : 'auto';
+}
+
+export interface ResumeDecision {
+  resume: boolean;
+  reason:
+    | 'resumed'
+    | 'resumed-force'
+    | 'mode-never'
+    | 'no-checkpoint'
+    | 'stale-input'
+    | 'artifact-missing';
+}
+
+/** The pure resume decision. 'auto' resumes only on (hash match AND every required artifact
+ * present); 'force' trusts the hash alone; 'never' always runs live. A STALE-INPUT hash NEVER
+ * resumes in any mode — force skips only the artifact probe, never the input check (a checkpoint
+ * for different inputs is a different feature). A malformed/null recorded result is treated as
+ * no-checkpoint (Codex QE #8 — a null result must not resume as a real one). */
+export function decideCheckpointResume(opts: {
+  mode: ResumeMode;
+  entry: CheckpointEntry | undefined;
+  inputHash: string;
+  artifactRel: string | readonly string[] | null;
+  listing: ReadonlySet<string>;
+}): ResumeDecision {
+  if (opts.mode === 'never') return { resume: false, reason: 'mode-never' };
+  if (!opts.entry || opts.entry.result === null || opts.entry.result === undefined) {
+    return { resume: false, reason: 'no-checkpoint' };
+  }
+  if (opts.entry.inputHash !== opts.inputHash) return { resume: false, reason: 'stale-input' };
+  if (opts.mode === 'force') return { resume: true, reason: 'resumed-force' };
+  const required = opts.artifactRel === null ? [] : (typeof opts.artifactRel === 'string' ? [opts.artifactRel] : opts.artifactRel);
+  for (const rel of required) {
+    if (!opts.listing.has(rel)) return { resume: false, reason: 'artifact-missing' };
+  }
+  return { resume: true, reason: 'resumed' };
+}
+
+/** Serialize one checkpoint line, or null when the result is null/oversize/unserializable —
+ * the caller logs the skip loudly; a missing checkpoint only costs a re-run, never corrupts.
+ * A null result is never persisted (Codex QE #8: it would later parse as a resumable entry). */
+export function serializeCheckpoint(stage: string, inputHash: string, result: unknown): string | null {
+  if (result === null || result === undefined) return null;
+  let line: string;
+  try {
+    line = JSON.stringify({ stage, inputHash, result });
+  } catch {
+    return null;
+  }
+  if (typeof line !== 'string' || line.length > CHECKPOINT_MAX_RESULT_CHARS) return null;
+  return line;
+}
+
+export interface ParsedCheckpointRead {
+  entries: Record<string, CheckpointEntry>;
+  listing: Set<string>;
+  malformedLines: number;
+}
+
+/** Sentinel separating the checkpoint file body from the artifact listing in the single read-back
+ * command's stdout. */
+export const CHECKPOINT_LS_SENTINEL = '---FA-CKPT-LS---';
+
+/** Parse the read-back agent's stdout: JSONL entries (LAST occurrence of a stage wins — a re-run
+ * overwrites by append), then the sentinel ON ITS OWN LINE, then one artifact path per line
+ * (relative to the feature dir). The sentinel match is LINE-ANCHORED: JSON.stringify never emits
+ * literal newlines, so a sentinel string INSIDE a recorded result shares its line with JSON syntax
+ * and can never split the stream (Codex QE #10). Malformed JSONL lines are COUNTED, never silently
+ * ignored (corruption is named); entries with a null result are malformed, not resumable. */
+export function parseCheckpointRead(text: string): ParsedCheckpointRead {
+  const out: ParsedCheckpointRead = { entries: {}, listing: new Set(), malformedLines: 0 };
+  const raw = String(text ?? '');
+  const lines = raw.split('\n');
+  const sentinelAt = lines.findIndex((l) => l.trim() === CHECKPOINT_LS_SENTINEL);
+  const body = sentinelAt === -1 ? lines : lines.slice(0, sentinelAt);
+  const ls = sentinelAt === -1 ? [] : lines.slice(sentinelAt + 1);
+  for (const line of body) {
+    const t = line.trim();
+    if (t === '') continue;
+    try {
+      const e = JSON.parse(t) as CheckpointEntry;
+      if (e && typeof e === 'object' && typeof e.stage === 'string' && typeof e.inputHash === 'string' && 'result' in e && e.result !== null && e.result !== undefined) {
+        out.entries[e.stage] = e;
+      } else {
+        // last-wins holds for BAD records too: a stage-identifiable null/invalid record ERASES the
+        // older entry for that stage instead of silently reactivating it (Codex QE r2 #6).
+        if (e && typeof e === 'object' && typeof (e as CheckpointEntry).stage === 'string') delete out.entries[(e as CheckpointEntry).stage];
+        out.malformedLines++;
+      }
+    } catch {
+      out.malformedLines++;
+    }
+  }
+  for (const line of ls) {
+    const t = line.trim();
+    if (t !== '') out.listing.add(t);
+  }
+  return out;
+}
+
+/** Single-quote shell escaping (the workflow's shq twin). */
+export function shellQuote(s: string): string {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/** The one Bash command the read-back agent runs: checkpoint file body (absent file = empty),
+ * the sentinel, then the artifact listing as feature-dir-relative paths (find prints them with a
+ * leading ./ that sed strips). Never fails: every leg is || true. */
+export function checkpointReadCmd(fdirAbs: string): string {
+  const q = shellQuote(fdirAbs);
+  return (
+    'cat ' + q + '/.fa-state/checkpoints.jsonl 2>/dev/null || true; ' +
+    "echo '" + CHECKPOINT_LS_SENTINEL + "'; " +
+    'cd ' + q + ' 2>/dev/null && find . -maxdepth 2 -type f 2>/dev/null | sed "s|^\\./||" || true'
+  );
+}
+
+/** The one Bash command the write agent runs: mkdir the state dir, then append ONE line. The line
+ * is single-quote-escaped as a whole — JSON.stringify output never contains literal newlines, so
+ * printf '%s\n' emits exactly one record. */
+export function checkpointAppendCmd(fdirAbs: string, line: string): string {
+  const dir = shellQuote(fdirAbs + '/.fa-state');
+  const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');
+  return 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
+}

package/src/index.ts

@@ -138,6 +138,36 @@ export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-chec
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
 export type { Step8ClaimCounts, Step8ClaimGate } from './feature-adr-claim-gate.js';
+export {
+  CHECKPOINT_STAGES,
+  STAGE_ARTIFACTS,
+  CHECKPOINT_MAX_RESULT_CHARS,
+  CHECKPOINT_LS_SENTINEL,
+  CKPT_SCHEMA_VERSION,
+  fnv1a,
+  fnv1a64,
+  checkpointInputHash,
+  resumeMode,
+  decideCheckpointResume,
+  serializeCheckpoint,
+  parseCheckpointRead,
+  checkpointReadCmd,
+  checkpointAppendCmd,
+} from './feature-adr-checkpoints.js';
+export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead } from './feature-adr-checkpoints.js';
+export {
+  REQE_SCHEMA,
+  REQE_SCOPE,
+  modelFamily,
+  shouldEmitReqeDebt,
+  buildReqeDebt,
+  parseReqeDebt,
+  buildReqeBrief,
+  extractReportGrade,
+  settleReqeDebt,
+  renderReqeList,
+} from './reqe.js';
+export type { ModelFamily, ReqeEmitDecision, ReqeDebt, ReqeBrief, ReqeSettlement } from './reqe.js';
 export {
   detectQueryLang,
   relevanceFloorFor,

package/src/reqe.ts

@@ -0,0 +1,243 @@
+/**
+ * re-QE debt — the pure half of `dz reqe` (backlog 6b40e667, goal honest-quality).
+ *
+ * The cross-model-QE guard ("the model that writes code must not self-review") is an ADR-named
+ * safety property of the feature-adr pipeline. The usage-adaptive override consciously SUSPENDS it
+ * (FR-2.9): at >= threshold usage every remaining stage — including Step-8 QE — switches to Codex,
+ * so coder and reviewer become the SAME family. The rule doc said "run an independent re-QE after
+ * limits reset" — a human instruction on the weakest detection layer. This module turns it into a
+ * 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);
+ *   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
+ *            the coder);
+ *   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.
+ *
+ * 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.
+ */
+
+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.';
+
+export type ModelFamily = 'claude' | 'openai';
+
+/** Family classification shared with the workflow's acFamOf (codex/gpt/openai markers ⇒ openai).
+ * DELIBERATELY binary over the workflow's own CONTROLLED vocabulary (coderUsed ∈ claude | codex |
+ * codex-fallback; qeReviewerUsed ∈ claude | codex) — this is never fed arbitrary model ids, so the
+ * claude default is the correct reading of "not a codex marker", not a fail-open (Codex QE #11,
+ * accepted with this documentation). */
+export function modelFamily(spec: string | null | undefined): ModelFamily {
+  return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'openai' : 'claude';
+}
+
+export interface ReqeEmitDecision {
+  emit: boolean;
+  reason: string;
+}
+
+/** 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 ?? ''));
+  const coderFam = modelFamily(input.coderUsed);
+  const qeFam = modelFamily(input.qeReviewerUsed);
+  if (switched && coderFam === qeFam) {
+    return {
+      emit: true,
+      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' };
+}
+
+export interface ReqeDebt {
+  schema: typeof REQE_SCHEMA;
+  slug: string;
+  coderFamily: ModelFamily;
+  qeFamily: ModelFamily;
+  qeGrade: string | null;
+  reason: string;
+  emittedAt: string | null;
+  /** The emitting run's identity (the workflow's qe inputHash). Lets a LATER run on the same slug
+   * emit a fresh debt even though an older settlement exists, while the SAME run's resume never
+   * re-opens a debt its settlement already covered (Codex QE round-2 #2). Optional: debts from
+   * before this field settle normally. */
+  runStamp?: string | null;
+}
+
+/** Build the debt record (the workflow serializes this; emittedAt is stamped by the writer agent's
+ * shell `date`, so the sandbox needs no Date). */
+export function buildReqeDebt(input: {
+  slug: string;
+  coderUsed: string | null | undefined;
+  qeReviewerUsed: string | null | undefined;
+  qeGrade: string | null | undefined;
+  reason: string;
+  emittedAt?: string | null;
+}): ReqeDebt {
+  return {
+    schema: REQE_SCHEMA,
+    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,
+  };
+}
+
+/** Parse + validate a debt file's text. null = not a valid debt (the caller reports it as
+ * malformed — a corrupt debt file is NAMED, never silently dropped). */
+export function parseReqeDebt(text: string): ReqeDebt | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(String(text ?? ''));
+  } catch {
+    return null;
+  }
+  const d = raw as Partial<ReqeDebt>;
+  if (!d || typeof d !== 'object') return null;
+  if (d.schema !== REQE_SCHEMA) return null;
+  if (typeof d.slug !== 'string' || d.slug.trim() === '') return 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,
+    slug: d.slug,
+    coderFamily: d.coderFamily,
+    qeFamily: d.qeFamily,
+    qeGrade: typeof d.qeGrade === 'string' && d.qeGrade.trim() !== '' ? d.qeGrade.trim() : null,
+    reason: d.reason,
+    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 {
+  reviewFamily: ModelFamily;
+  header: string;
+  instructions: readonly string[];
+  codexCmdTemplate: string | null;
+}
+
+/** The ready-to-run cross-family review brief. Review family = the OTHER family than the CODER
+ * (reviewing with the other-than-reviewer family would let a codex-coded, codex-reviewed run be
+ * "re-reviewed" by codex again). */
+export function buildReqeBrief(debt: ReqeDebt, artifactsDir: string): ReqeBrief {
+  const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
+  const files = [
+    artifactsDir + '/07_code_changes/change_manifest.md',
+    artifactsDir + '/08_qe_report.md',
+    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 : '') + '.',
+    '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.',
+    'Then settle the debt: dz reqe --slug ' + debt.slug + ' --done --report ' + artifactsDir + '/08b_reqe_report.md',
+  ];
+  const codexCmdTemplate = reviewFamily === 'openai'
+    ? 'codex exec -m <probed-id> -c model_reasoning_effort="high" --sandbox read-only "<the brief above>" < /dev/null   # probe the id first: ids are account-specific'
+    : null;
+  return {
+    reviewFamily,
+    header: 're-QE brief for ' + debt.slug + ' (' + (debt.emittedAt ?? 'emitted: unknown') + ')',
+    instructions,
+    codexCmdTemplate,
+  };
+}
+
+export interface ReqeSettlement {
+  ok: boolean;
+  error: string | null;
+  grade: string | null;
+  epilogue: string | null;
+}
+
+/** Extract the verdict grade from a report, or null. LINE-ANCHORED and range-proof (Codex QE #7):
+ * the boilerplate phrase `GRADE A-F` must not read as grade A, so a letter followed by a dash and
+ * another grade letter is rejected; and the grade must head its line (a quoted "do not assign
+ * GRADE A" mid-paragraph is not a verdict). Conflicting distinct grades ⇒ null (ambiguous). */
+export function extractReportGrade(text: string): string | null {
+  // the lookahead rejects RANGES in punctuation form (A-F, A/F) AND word form (A through F,
+  // A to F) — Codex QE round-2 #6: 'GRADE A through F' must not read as grade A
+  const matches = [...String(text ?? '').matchAll(/^\s*(?:\*{0,2}#{0,4}\s*)?GRADE\s*[:=—–-]?\s*([A-F])\b(?!\s*(?:[-–—/]|through|to|thru)\s*[A-F]\b)/gim)];
+  const distinct = new Set(matches.map((m) => (m[1] ?? '').toUpperCase()).filter((g) => g !== ''));
+  if (distinct.size !== 1) return null;
+  return [...distinct][0] ?? null;
+}
+
+/** FAIL-CLOSED settlement validation: the report must be non-trivial (>= 200 chars of substance)
+ * and must NAME exactly one line-anchored grade. A settlement that cannot cite its evidence is
+ * refused — clearing a debt against an empty file would re-open the exact hole this feature closes.
+ * HONEST LIMIT (documented, not hidden): the validator proves the settlement is PROCEDURALLY sound
+ * (a distinct, graded report exists); it cannot prove which model authored the text — attribution
+ * stays with the human running the brief. */
+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 };
+  }
+  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 };
+  }
+  const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
+  const epilogue = [
+    '',
+    '---',
+    '',
+    '## re-QE settlement (cross-model debt cleared)',
+    '',
+    'The original Step-8 review ran on the coder’s own family (' + debt.coderFamily + ') under the',
+    'usage override (' + debt.reason + '). An independent ' + reviewFamily.toUpperCase() + '-family re-QE was performed:',
+    '',
+    '- report: `' + reportPath + '`',
+    '- re-QE grade: **' + grade + '**' + (debt.qeGrade ? ' (same-family grade on record: ' + debt.qeGrade + ')' : ''),
+    '- settled via `dz reqe --done` (fail-closed: an existing graded report is required).',
+    '',
+  ].join('\n');
+  return { ok: true, error: null, grade, epilogue };
+}
+
+/** 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).');
+  } 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);
+    }
+  }
+  if (malformed > 0) lines.push('  ' + malformed + ' malformed debt file(s) skipped (named, never silent).');
+  lines.push(REQE_SCOPE);
+  return lines;
+}