@dzhechkov/harness-cli 0.3.258 → 0.3.260

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.258",
+  "version": "0.3.260",
   "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.147",
+    "@dzhechkov/harness-core": "^0.3.150",
     "@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": "a38e5ef6a741aec138af0de7bd3616d4356d613ba1616bd8b5417194c1ee5f03"
+          "content": "6b3bcc252253732b9703f1eb43ac1f0e9f0599979b09d0fea3208932fd0f33a8"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f954d1e2e3d9f5941481a2b2ccbf553bab892dfa9ba1e7aefb4bf7d1800e9203"
+          "content": "4c5fa8c51cc350874413efceb0a2e4dce2f0c71f39914ddd8be425336a37ae2d"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5fb105be335591fb20401a3b23bac9829777e7ba96c2a2480c29970f4ffa2774"
+          "content": "a75034dfe70f0b57811dfad831366bd5c7995583a57db0f218621b026ac8d854"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a4be3aac6dadec03c1fc85fc5354d9a286ac0a21b4983349c4e511cae49dec79"
+          "content": "dbe8fa418aedcb77dead3a374bba7cbf0fb5e305dd9a06002946a19604279684"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b502ba368d29e25413ce35e8853bc5650c06f686202e51f997f67db0fac03224"
+          "content": "72858a1f0199832c7ad781f892b7b117ec980af33ff9598587e1ed1544046a35"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a369561502f08d9dd4993a294adcb3a38349f543959fa8de31cd1580778062b0"
+          "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';
@@ -275,7 +275,17 @@ import {
   makeBacklogIO,
   harmonizeBacklog,
   BACKLOG_BACKENDS,
+  applyDomainBoost,
+  countDisplacedByCut,
+  renderDomainBoostNote,
+  renderDomainCutNote,
+  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';
@@ -314,6 +324,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)
@@ -326,7 +337,7 @@ Usage:
   dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
   dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]] [--prune-quarantine [--apply]]   (both prunes: DRY-RUN by default; --apply snapshots then deletes; prune-quarantine = expired unproven lessons ONLY, never coupled to noise)
-  dz recall "<query>" [--limit <N>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply] | dz recall --promote <dzId>[,<dzId>] [--apply]   (forget/promote: dry-run default; forget snapshots before removing; promote lifts lesson-quarantine)
+  dz recall "<query>" [--limit <N>] [--domain <name>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply] | dz recall --promote <dzId>[,<dzId>] [--apply]   (--domain <name> BOOSTS lessons of that domain without dropping foreign ones — a shared store keeps its cross-domain transfers; forget/promote: dry-run default; forget snapshots before removing; promote lifts lesson-quarantine)
   dz vector status [--project <dir>] [--json]                          (semantic tier: engine, mirrored vs lexical counts, pending queue)
   dz vector reindex [--project <dir>] [--json]                         (snapshot, re-embed learned-pattern vectors, stamp current model)
   dz vector export <path> [--project <dir>]                            (portable VECTOR form (.rvf, opt-in RVF engine); patterns ship via recall --all --json)
@@ -1626,6 +1637,7 @@ function cmdUsage(
         limits: typeof limitsPayload;
         weeklyByModel?: typeof u.weeklyByModel;
         estimated: true;
+        reqeDue?: number;
       } = {
         sessionPct: u.sessionPct,
         weeklyPct: u.weeklyPct,
@@ -1636,6 +1648,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),
       );
@@ -1645,6 +1664,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.
@@ -1660,6 +1683,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.
@@ -2216,13 +2245,31 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     : flags.has('no-semantic') || flags.has('lexical')
       ? ('lexical' as const)
       : ('hybrid' as const);
-  const result = await recallHybrid(projectRoot, query, { limit, mode });
+  const wantedDomain = options.get('domain');
+  // OVER-FETCH before boosting (Codex QE #5): the boost used to run on hits ALREADY
+  // truncated to `limit`, so an exact-domain lesson sitting at rank limit+1 could
+  // never receive its promised lift — the feature was weakest in exactly the case it
+  // exists for (foreign-domain dilution pushing a relevant lesson just past the cut).
+  // Fetch a bounded surplus, re-rank, then trim to the limit the caller asked for.
+  const fetchLimit = wantedDomain !== undefined ? Math.min(limit * 3, limit + 20) : limit;
+  const result = await recallHybrid(projectRoot, query, { limit: fetchLimit, mode });
+
   if (mode === 'semantic' && result.vectorEngine === 'none') {
     // --semantic is an explicit ask — degrading it silently would be dishonest (FR-3).
     write(`dz recall --semantic: ${result.vectorReason ?? 'no vector engine available — run: dz setup --memory agentdb'}`);
     return 1;
   }
-  const hits = result.hits;
+  // Domain-aware re-ranking (health-advisor slice H): `--domain <name>` lifts lessons
+  // tagged with that domain WITHOUT dropping foreign ones — a boost, not a filter, so a
+  // shared store keeps the cross-domain transfers that make it worth more than two stores.
+  const boost = wantedDomain !== undefined ? applyDomainBoost(result.hits, wantedDomain) : null;
+  const hits = (boost ? boost.hits : result.hits).slice(0, limit);
+  // The boost never drops a hit, but the CUT still can: promoting a match into the top
+  // `limit` pushes the last one out, so a lesson visible WITHOUT --domain can vanish
+  // WITH it. Cross-model review called this out as a lie by omission — the note said
+  // "foreign-domain lessons kept" about the pre-cut list while the printed list was
+  // missing one. Count it and say so; the reader can act on it (raise --limit).
+  const displaced = boost !== null ? countDisplacedByCut(result.hits, boost.hits, limit) : 0;
   if (asJson) {
     // Portable contract UNCHANGED (I-7/AC-6): a plain PatternRecord[] — round-trips through
     // `dz teach --from-json` regardless of which backend ranked each hit.
@@ -2233,6 +2280,10 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   if (hits.length === 0) {
     write(`dz recall "${query}"`);
     write(`  No matching patterns (teach some with \`dz teach\`, or consolidate sessions).`);
+    // The domain note must print here too (Codex QE #10): a --domain run with zero hits
+    // silently said nothing about the domain, so the reader could not tell whether the
+    // boost had been applied and found nothing, or had not run at all.
+    if (boost !== null && wantedDomain !== undefined) write(renderDomainBoostNote(boost, wantedDomain));
     return 0;
   }
   const vectorOn = result.vectorEngine !== 'none' && result.vectorError === undefined && mode !== 'lexical';
@@ -2244,12 +2295,25 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     const backendTag = vectorOn ? ` ⟨${h.backend}⟩` : '';
     const qTag = h.quarantined === true ? ' ⚠q' : '';
     if (h.quarantined === true) sawQuarantined = true;
-    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag}${qTag} ${h.pattern.pattern.slice(0, 80)}`);
+    // ONE line per hit, always. A lesson may contain newlines, and printing them raw
+    // let stored CONTENT forge lines that look like the tool's own output — including
+    // the domain-boost note that learning_bridge.py reads as a capability probe. Any
+    // consumer that parses this output line-wise has the same exposure, so the fix
+    // belongs at the point of rendering rather than in each reader.
+    const oneLine = h.pattern.pattern.replace(/[\r\n]+/g, ' ⏎ ').slice(0, 80);
+    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag}${qTag} ${oneLine}`);
   }
   if (sawQuarantined) {
     // The loop stays VISIBLE (ADR D2): a quarantined hit is shown, marked, and explained.
     write('  ⚠q = quarantined (unproven hypothesis, rank damped) — confirm with dz teach --reinforce, or dz recall --promote <dzId> --apply');
   }
+  if (boost !== null && wantedDomain !== undefined) {
+    // Say what the boost did — INCLUDING when it did nothing. A silent reorder would
+    // let the reader believe the ranking was domain-aware when it had no match to work with.
+    write(renderDomainBoostNote(boost, wantedDomain));
+    const cutNote = renderDomainCutNote(displaced, limit);
+    if (cutNote !== '') write(cutNote);
+  }
   if (result.vectorError !== undefined && mode !== 'lexical') {
     // Engine present but the semantic leg failed/timed out — one honest line, exit 0 (05 §2.3).
     write(`  ℹ vector search degraded: ${result.vectorError} — showing lexical ranking`);
@@ -6213,6 +6277,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')) {
@@ -6285,8 +6537,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;
 }
 
@@ -7815,6 +8080,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':