@dzhechkov/harness-cli 0.3.257 → 0.3.259

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.257",
+  "version": "0.3.259",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
-    "@dzhechkov/harness-core": "^0.3.146",
+    "@dzhechkov/harness-core": "^0.3.149",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7333dd44bcbeb6536e8ee0f0490a57fefca211e706535da7f44cea7012388213"
+          "content": "6b3bcc252253732b9703f1eb43ac1f0e9f0599979b09d0fea3208932fd0f33a8"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "818293a250cdf1bd10b5d69267b714d9a8ab90017c1fa18de29fc24e28ad8a55"
+          "content": "4c5fa8c51cc350874413efceb0a2e4dce2f0c71f39914ddd8be425336a37ae2d"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9c37499ed55b571232b5718c863b83b31f7a79faab46a9dcbe3283b993b1862a"
+          "content": "a75034dfe70f0b57811dfad831366bd5c7995583a57db0f218621b026ac8d854"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6cf537925ccb4b1ffff84c8fd255b487438b78b56a46f9d91d33b25500ae520d"
+          "content": "dbe8fa418aedcb77dead3a374bba7cbf0fb5e305dd9a06002946a19604279684"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7abb07cdda09bea2b8e948cecdbaed4579371e8d0e8cee4436e7fcb20f430cdd"
+          "content": "72858a1f0199832c7ad781f892b7b117ec980af33ff9598587e1ed1544046a35"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d64af623372238bb5f2ead34e733130d7b013c49058a26f4795f09586b2b5dda"
+          "content": "1481238a2fc3a60051f678dcf6b415f8052ce954a9e55ee7577d8c3b2261e062"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "555aed692218a73f23a343df2f2b38ce028e694dd9d4aff37e727096f88eb50e"
+          "content": "24f2feb4c5c4fa939beb79cd658b03fbc7ce4bd87f15da563240abcb252c472c"
         }
       ]
     },

package/src/cli.ts

@@ -4,7 +4,7 @@
  * @packageDocumentation
  */
 
-import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, execSync, spawn } from 'node:child_process';
@@ -80,6 +80,11 @@ import {
   statuslineData,
   writeFeatureAdrState,
   computeUsage,
+  deriveCostLedger,
+  renderCostLedger,
+  verifyCostLedgerReport,
+  writeCostLedgerJsonl,
+  COST_LEDGER_SCOPE,
   deriveUsageCalibration,
   normalizeClaudeUsageModelKey,
   readUsageLimits,
@@ -270,7 +275,13 @@ import {
   makeBacklogIO,
   harmonizeBacklog,
   BACKLOG_BACKENDS,
+  parseReqeDebt,
+  buildReqeBrief,
+  settleReqeDebt,
+  renderReqeList,
+  REQE_SCOPE,
 } from '@dzhechkov/harness-core';
+import type { ReqeDebt } from '@dzhechkov/harness-core';
 import type { IdeaRecord, IdeaStatus } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
@@ -309,6 +320,7 @@ Usage:
   dz epoch-replay --judge <filled-work-order.json> [--out <file>]   (blind judge prompts from the filled plans)
   dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
+  dz reqe [--slug <feature> [--done --report <f>]] [--json]   (the re-QE debt ledger: a usage-switched run whose Step-8 QE ran on the coder's OWN family records a debt; list debts, print the cross-family review brief, settle FAIL-CLOSED against a graded report — the settlement lands in 08_qe_report.md)
   dz backlog add "<idea>" [--effort 1-5] [--proposal <text>] [--dry-run] [--project <dir>] [--json]   (capture an idea: semantic dedup against existing ideas via the Brain vector engine (DUPLICATE>=0.92 merges, RELATED links, NEW creates) + GoalMap alignment; --dry-run classifies without writing)
   dz backlog list [--status <s>] [--goal <id>] [--project <dir>] [--json]   (list captured ideas, filterable by status/goal)
   dz backlog show <id> [--project <dir>] [--json]                          (full record for one idea)
@@ -340,6 +352,7 @@ Usage:
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
   dz usage [--json] [--project <dir>] | dz usage --calibrate --session <pct> --weekly <pct> [--model fable=<pct>] [--project <dir>]  (ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS; pct=null when limits unconfigured)
+  dz usage --by-stage [--run <runId> | --slug <slug>] [--epsilon <0..1>] [--write <file.jsonl>] [--json]   (per-stage cost ledger for ONE feature-adr run + the reconciliation invariant: accounted + unaccounted = run total; verdict BALANCED | DEFECT | INSUFFICIENT_DATA; local transcript ESTIMATES — catches ATTRIBUTION errors, not pricing errors)
   dz claim-check [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]  (enforce the Integrity Rule: flag untagged/overstated accuracy claims; default scan = root README.md + every discovered package's README.md + features/*/08_qe_report.md + docs/**/*.md (historical feature artifacts are NOT scanned — pass paths explicitly); exit 1 only at/above --fail-on, default high)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
@@ -1509,6 +1522,64 @@ function cmdUsageCalibrate(
   }
 }
 
+/**
+ * `dz usage --by-stage` — the per-stage cost ledger for one feature-adr run (feature `cost-ledger`).
+ *
+ * A run reports ONE number; this turns it into an itemized receipt keyed by the workflow's OWN
+ * `stageLabel()` strings, plus the reconciliation line that guards the bookkeeping itself. Derived
+ * post-hoc from the transcripts already on disk — no workflow edit, killed runs included.
+ *
+ * Exit code is 0 ALWAYS, matching the rest of `dz usage`; the VERDICT (`BALANCED` / `DEFECT` /
+ * `INSUFFICIENT_DATA`) is the signal, and `INSUFFICIENT_DATA` is not success.
+ */
+function cmdUsageByStage(
+  options: Map<string, string>,
+  flags: Set<string>,
+  write: Write,
+): number {
+  const runId = options.get('run');
+  const slug = options.get('slug');
+  const epsilonRaw = options.get('epsilon');
+  const epsilon = epsilonRaw === undefined ? undefined : Number(epsilonRaw);
+  const report = deriveCostLedger({
+    ...(runId !== undefined ? { runId } : {}),
+    ...(slug !== undefined ? { slug } : {}),
+    ...(epsilon !== undefined && Number.isFinite(epsilon) ? { epsilon } : {}),
+  });
+
+  if (report === null) {
+    // An ABSENT run is never a balanced empty report (ADR-003).
+    const detail = runId !== undefined ? `run ${runId}` : slug !== undefined ? `slug ${slug}` : 'any workflow run';
+    if (flags.has('json')) {
+      write(JSON.stringify({ verdict: 'INSUFFICIENT_DATA', reason: `no workflow run record found for ${detail}`, rows: [], estimated: true, scope: COST_LEDGER_SCOPE }));
+    } else {
+      write(`usage --by-stage: INSUFFICIENT_DATA — no workflow run record found for ${detail}`);
+      write(`usage --by-stage: scope: ${COST_LEDGER_SCOPE}`);
+    }
+    return 0;
+  }
+
+  // The verifier re-derives the identities from the EMITTED report — a builder bug must surface as
+  // a finding, not as a plausible table.
+  const verifyDefects = verifyCostLedgerReport(report);
+
+  const outPath = options.get('write');
+  let wrote: boolean | null = null;
+  if (outPath !== undefined && outPath.length > 0) wrote = writeCostLedgerJsonl(resolve(outPath), report);
+
+  if (flags.has('json')) {
+    write(JSON.stringify({ ...report, verifyDefects, ...(wrote === null ? {} : { wrote, writePath: resolve(outPath ?? '') }) }));
+    return 0;
+  }
+
+  write(renderCostLedger(report));
+  for (const d of verifyDefects) write(`  verifier: ${d.kind}: ${d.detail}`);
+  if (wrote !== null) {
+    write(`  ${wrote ? 'wrote' : 'FAILED to write'} ${resolve(outPath ?? '')} (derived report — regenerable, never read back)`);
+  }
+  return 0;
+}
+
 /**
  * `dz usage` — print an ESTIMATE of Claude session + weekly usage from fixed reset windows,
  * aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json` emits
@@ -1540,6 +1611,7 @@ function cmdUsage(
     });
   try {
     if (flags.has('calibrate')) return cmdUsageCalibrate(options, optionLists, cwd, write);
+    if (flags.has('by-stage')) return cmdUsageByStage(options, flags, write);
 
     const u = computeUsage(projectRoot);
     const lim = readUsageLimits(projectRoot);
@@ -1561,6 +1633,7 @@ function cmdUsage(
         limits: typeof limitsPayload;
         weeklyByModel?: typeof u.weeklyByModel;
         estimated: true;
+        reqeDue?: number;
       } = {
         sessionPct: u.sessionPct,
         weeklyPct: u.weeklyPct,
@@ -1571,6 +1644,13 @@ function cmdUsage(
         estimated: true,
       };
       if (hasModelLimits && u.weeklyByModel !== undefined) payload.weeklyByModel = u.weeklyByModel;
+      // re-QE debt surfacing (backlog 6b40e667 — QE #9: the json contract must carry the debt too,
+      // a probe is exactly the consumer that needs it). The field appears ONLY when a debt exists,
+      // so the zero-debt contract stays byte-identical to the pinned legacy shape. Best-effort.
+      try {
+        const reqeCount = scanReqeDebts(resolve(cwd, options.get('project') ?? '.')).debts.length;
+        if (reqeCount > 0) payload.reqeDue = reqeCount;
+      } catch { /* advisory only */ }
       write(
         JSON.stringify(payload),
       );
@@ -1580,6 +1660,10 @@ function cmdUsage(
       write(
         'usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json (percentages are ESTIMATES calibrated from observed exhaustion)',
       );
+      try {
+        const reqe = scanReqeDebts(resolve(cwd, options.get('project') ?? '.'));
+        if (reqe.debts.length > 0) write('re-QE due: ' + reqe.debts.length + ' usage-switched run(s) kept same-family QE — run `dz reqe` for the cross-family pass');
+      } catch { /* advisory only */ }
       return 0;
     }
     // Compact human line — a short HH:MM / weekday hint on the resets, best-effort.
@@ -1595,6 +1679,12 @@ function cmdUsage(
     const binding = hasModelLimits && u.weeklyBindingModel !== undefined ? ' ' + u.weeklyBindingModel + '-bound' : '';
     const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%' + binding;
     write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
+    // re-QE debt surfacing (backlog 6b40e667): the moment someone checks usage is the moment a
+    // usage-switched self-review debt should be visible. Best-effort — never breaks the contract.
+    try {
+      const reqe = scanReqeDebts(resolve(cwd, options.get('project') ?? '.'));
+      if (reqe.debts.length > 0) write('re-QE due: ' + reqe.debts.length + ' usage-switched run(s) kept same-family QE — run `dz reqe` for the cross-family pass');
+    } catch { /* advisory only */ }
     return 0;
   } catch {
     // never let a probe see a non-zero exit — print the all-null contract and exit 0.
@@ -6148,6 +6238,194 @@ function nameFor(t: { file: string; name?: string }, outcome: 'pass' | 'fail' |
  * `dz score --slug <feature>` — score a feature-adr RUN's process discipline from its artifacts
  * (feature dz-score, Reading C). Descriptive-only: exit 0 on any score; non-zero only on usage errors.
  */
+/** Scan features/<slug>/.fa-state/reqe-due.json under a project root. Symlinked ANCESTOR dirs are
+ * skipped too, not just the leaf (Codex QE #5 — a symlinked feature dir could smuggle an outside
+ * debt); an oversized or non-regular due-file counts as MALFORMED, never a silent skip (QE #8);
+ * a debt whose embedded slug differs from its directory is MALFORMED — identity is the directory,
+ * the JSON only confirms it (QE #4: an embedded foreign slug must not redirect settlement). */
+function scanReqeDebts(root: string): { debts: Array<{ debt: ReqeDebt; duePath: string; dir: string }>; malformed: number } {
+  const out: Array<{ debt: ReqeDebt; duePath: string; dir: string }> = [];
+  let malformed = 0;
+  const featuresDir = join(root, 'features');
+  let slugs: string[] = [];
+  try {
+    if (lstatSync(featuresDir).isSymbolicLink()) return { debts: [], malformed: 0 }; // r2 #4: features/ itself
+    slugs = readdirSync(featuresDir);
+  } catch {
+    return { debts: [], malformed: 0 };
+  }
+  for (const slug of slugs.sort()) {
+    const dir = join(featuresDir, slug);
+    const stateDir = join(dir, '.fa-state');
+    const duePath = join(stateDir, 'reqe-due.json');
+    try {
+      if (lstatSync(dir).isSymbolicLink() || lstatSync(stateDir).isSymbolicLink()) continue;
+    } catch {
+      continue; // no feature dir / no state dir — nothing to scan
+    }
+    let st;
+    try {
+      st = lstatSync(duePath);
+    } catch {
+      continue; // no due-file — the common, silent case
+    }
+    if (!st.isFile() || st.size > 64 * 1024) {
+      malformed++; // exists but is not a plain small file — named, never silently dropped
+      continue;
+    }
+    try {
+      const debt = parseReqeDebt(readFileSync(duePath, 'utf-8'));
+      if (debt && debt.slug === slug) out.push({ debt, duePath, dir });
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { debts: out, malformed };
+}
+
+/**
+ * `dz reqe` — the re-QE debt ledger (backlog 6b40e667): list usage-switched same-family QE debts,
+ * print the cross-family review brief, settle FAIL-CLOSED against a graded report.
+ */
+function cmdReqe(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  if (flags.has('help')) {
+    const usage = 'dz reqe [--slug <feature> [--done --report <file>]] [--project <dir>] [--json]';
+    if (json) write(JSON.stringify({ help: usage, exitCode: 0 }));
+    else {
+      write(usage + ' — the re-QE debt ledger');
+      write('  (no args)              list unsettled debts (runs whose Step-8 QE ran on the coder’s own family under the usage override)');
+      write('  --slug <s>             print the ready cross-family review brief for one debt');
+      write('  --slug <s> --done --report <file>   settle the debt — FAIL-CLOSED: requires an existing, non-trivial, GRADED report; appends the settlement to 08_qe_report.md');
+      write('  ' + REQE_SCOPE);
+    }
+    return 0;
+  }
+  for (const flag of flags) {
+    if (!new Set(['json', 'help', 'done']).has(flag)) {
+      write(json ? JSON.stringify({ error: `unknown option --${flag}`, exitCode: 1 }) : `dz reqe: unknown option --${flag}\n  allowed: --slug <feature>, --done, --report <file>, --project <dir>, --json`);
+      return 1;
+    }
+  }
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_') || !new Set(['slug', 'report', 'project']).has(key)) {
+      const what = key.startsWith('_positional_') ? `unexpected argument "${options.get(key)}"` : `unknown option --${key}`;
+      write(json ? JSON.stringify({ error: what, exitCode: 1 }) : `dz reqe: ${what}`);
+      return 1;
+    }
+  }
+  const root = resolve(cwd, options.get('project') ?? '.');
+  const slug = options.get('slug') ?? '';
+  if (slug !== '' && (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug) || slug.includes('..'))) {
+    write(json ? JSON.stringify({ error: 'a plain --slug <feature> is required (no path separators)', exitCode: 1 }) : 'dz reqe: a plain --slug <feature> is required (no path separators)');
+    return 1;
+  }
+
+  const { debts, malformed } = scanReqeDebts(root);
+
+  if (slug === '') {
+    if (flags.has('done')) {
+      write(json ? JSON.stringify({ error: '--done requires --slug', exitCode: 1 }) : 'dz reqe: --done requires --slug <feature>');
+      return 1;
+    }
+    if (json) write(JSON.stringify({ debts: debts.map((d) => d.debt), malformed, scope: REQE_SCOPE, exitCode: 0 }));
+    else for (const line of renderReqeList(debts.map((d) => d.debt), malformed)) write(line);
+    return 0;
+  }
+
+  const hit = debts.find((d) => d.debt.slug === slug) ?? null;
+  if (!hit) {
+    // distinguish "no debt file" from "malformed debt file" — a corrupt debt must be named
+    const duePath = join(root, 'features', slug, '.fa-state', 'reqe-due.json');
+    const exists = existsSync(duePath);
+    const msg = exists
+      ? `debt file at features/${slug}/.fa-state/reqe-due.json is MALFORMED — inspect it manually (a corrupt debt is named, never auto-cleared)`
+      : `no re-QE debt recorded for "${slug}"`;
+    write(json ? JSON.stringify({ error: msg, exitCode: 1 }) : `dz reqe: ${msg}`);
+    return 1;
+  }
+
+  if (!flags.has('done')) {
+    const brief = buildReqeBrief(hit.debt, join('features', slug));
+    if (json) write(JSON.stringify({ debt: hit.debt, brief, exitCode: 0 }));
+    else {
+      write(brief.header);
+      for (const line of brief.instructions) write('  ' + line);
+      if (brief.codexCmdTemplate) write('  codex template: ' + brief.codexCmdTemplate);
+      write('  ' + REQE_SCOPE);
+    }
+    return 0;
+  }
+
+  // --done: FAIL-CLOSED settlement
+  const reportOpt = options.get('report') ?? '';
+  if (reportOpt === '') {
+    write(json ? JSON.stringify({ error: '--done requires --report <file> (the cross-family re-QE report)', exitCode: 1 }) : 'dz reqe: --done requires --report <file>');
+    return 1;
+  }
+  const reportPath = resolve(root, reportOpt);
+  const qeReportPath = join(hit.dir, '08_qe_report.md');
+  // QE #1: the run's OWN same-family Step-8 report must never settle its own debt — the exact
+  // laundering this ledger exists to prevent. Compared by REAL path so a symlink cannot alias it.
+  try {
+    const sameReal = realpathSync(reportPath) === realpathSync(qeReportPath);
+    // r2 #1: a HARD LINK to the same report has a different path but the same inode — compare
+    // dev+ino, not just resolved paths
+    const rSt = statSync(reportPath);
+    const qSt = statSync(qeReportPath);
+    const sameInode = rSt.dev === qSt.dev && rSt.ino === qSt.ino;
+    if (sameReal || sameInode) {
+      write(json ? JSON.stringify({ error: 'the report IS this run’s own 08_qe_report.md (same file/inode) — the same-family review cannot settle its own debt; provide the independent cross-family report', exitCode: 1 }) : 'dz reqe: the report IS this run’s own 08_qe_report.md (same file/inode) — the same-family review cannot settle its own debt (fail-closed)');
+      return 1;
+    }
+  } catch { /* one of the two does not resolve — the reads below decide */ }
+  let reportText = '';
+  try {
+    const st = lstatSync(reportPath);
+    if (!st.isFile()) throw new Error('not a regular file'); // symlinked report refused (QE #5)
+    reportText = readFileSync(reportPath, 'utf-8');
+  } catch {
+    write(json ? JSON.stringify({ error: `report not readable at ${reportOpt} (must be a regular file, not a symlink) — refusing to settle`, exitCode: 1 }) : `dz reqe: report not readable at ${reportOpt} (must be a regular file, not a symlink) — refusing to settle (fail-closed)`);
+    return 1;
+  }
+  const settlement = settleReqeDebt(hit.debt, reportText, reportOpt);
+  if (!settlement.ok || settlement.epilogue === null) {
+    write(json ? JSON.stringify({ error: settlement.error, exitCode: 1 }) : `dz reqe: ${settlement.error}`);
+    return 1;
+  }
+  // QE #6 ordering: rotate the debt FIRST, append the human-readable epilogue LAST — a crash may
+  // leave a settled debt without its epilogue (recoverable from reqe-settled.json), never an
+  // epilogue claiming clearance while the debt is still live.
+  const settledBase = join(hit.dir, '.fa-state', 'reqe-settled');
+  let settledPath = settledBase + '.json';
+  for (let n = 2; existsSync(settledPath); n++) settledPath = settledBase + '-' + n + '.json'; // never overwrite prior evidence
+  try {
+    const settled = { ...hit.debt, settledGrade: settlement.grade, settledReport: reportOpt };
+    writeFileSync(settledPath, JSON.stringify(settled) + '\n', { flag: 'wx' }); // wx: never through a planted symlink
+    try {
+      unlinkSync(hit.duePath);
+    } catch (e) {
+      // r2 #5: a failed unlink must not leave a settled marker beside a live debt — roll back
+      try { unlinkSync(settledPath); } catch { /* best-effort rollback */ }
+      throw e;
+    }
+  } catch {
+    write(json ? JSON.stringify({ error: 'could not rotate the debt file — debt NOT cleared, nothing was appended', exitCode: 1 }) : 'dz reqe: could not rotate the debt file — debt NOT cleared, nothing was appended (fail-closed)');
+    return 1;
+  }
+  try {
+    if (lstatSync(qeReportPath).isSymbolicLink()) throw new Error('symlinked 08_qe_report.md');
+    appendFileSync(qeReportPath, settlement.epilogue);
+  } catch {
+    write(json ? JSON.stringify({ settled: true, grade: settlement.grade, warning: 'debt cleared (see .fa-state/reqe-settled*.json) but the epilogue could NOT be appended to 08_qe_report.md — append it manually', exitCode: 0 }) : 'dz reqe: debt cleared (evidence in .fa-state/) but the epilogue could NOT be appended to 08_qe_report.md — append it manually');
+    return 0;
+  }
+  const okMsg = `debt settled: re-QE grade ${settlement.grade} (report ${reportOpt}) — settlement appended to features/${slug}/08_qe_report.md`;
+  write(json ? JSON.stringify({ settled: true, grade: settlement.grade, exitCode: 0 }) : `dz reqe: ${okMsg}`);
+  return 0;
+}
+
 function cmdScore(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   if (flags.has('help')) {
@@ -6220,8 +6498,21 @@ function cmdScore(options: Map<string, string>, flags: Set<string>, cwd: string,
   walk(dir, '', 0);
 
   const card = scoreRun(slug, artifacts);
-  if (json) write(JSON.stringify({ ...card, exitCode: 0 }, null, 2));
-  else write(renderScorecard(card));
+  // re-QE debt note (backlog 6b40e667): a scorecard that praised cross-model QE while an unsettled
+  // same-family debt sits on disk would be half the truth. PARSED, not existence-guessed (QE #9);
+  // a malformed debt file is named. Advisory in both modes — never moves the score or exit code.
+  let reqeNote: string | null = null;
+  {
+    const scan = scanReqeDebts(root);
+    const mine = scan.debts.find((d) => d.debt.slug === slug);
+    if (mine) reqeNote = 'UNSETTLED re-QE debt — Step-8 ran same-family under the usage override; run `dz reqe --slug ' + slug + '`';
+    else if (existsSync(join(dir, '.fa-state', 'reqe-due.json'))) reqeNote = 'a reqe-due.json exists but is MALFORMED/mismatched — inspect features/' + slug + '/.fa-state/ manually';
+  }
+  if (json) write(JSON.stringify({ ...card, reqeDebt: reqeNote, exitCode: 0 }, null, 2));
+  else {
+    write(renderScorecard(card));
+    if (reqeNote) write('note: ' + reqeNote);
+  }
   return 0;
 }
 
@@ -7750,6 +8041,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdEpochReplay(options, flags, cwd, write);
       case 'score':
         return cmdScore(options, flags, cwd, write);
+      case 'reqe':
+        return cmdReqe(options, flags, cwd, write);
       case 'backlog':
         return await cmdBacklog(options, flags, cwd, write);
       case 'routing':