@dzhechkov/harness-cli 0.3.257 → 0.3.259

package/dist/cli.js

@@ -3,19 +3,19 @@
  *
  * @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';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, 
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, 
 // guard-promotion (feature guard-promotion, scout idea #1)
 assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
-readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, BACKLOG_BACKENDS, } from '@dzhechkov/harness-core';
+readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, BACKLOG_BACKENDS, parseReqeDebt, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -48,6 +48,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)
@@ -79,6 +80,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>"
@@ -1129,6 +1131,57 @@ function cmdUsageCalibrate(options, optionLists, cwd, write) {
         return 0;
     }
 }
+/**
+ * `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, flags, write) {
+    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 = 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
@@ -1154,6 +1207,8 @@ function cmdUsage(options, optionLists, flags, cwd, write) {
     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);
         const modelLimits = lim.weeklyTokenLimitByModel;
@@ -1173,11 +1228,26 @@ function cmdUsage(options, optionLists, flags, cwd, write) {
             };
             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));
             return 0;
         }
         if (u.sessionPct === null && u.weeklyPct === null) {
             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.
@@ -1195,6 +1265,14 @@ function cmdUsage(options, optionLists, flags, cwd, write) {
         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 {
@@ -5872,6 +5950,213 @@ function nameFor(t, outcome) {
  * `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) {
+    const out = [];
+    let malformed = 0;
+    const featuresDir = join(root, 'features');
+    let slugs = [];
+    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, flags, cwd, write) {
+    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, flags, cwd, write) {
     const json = flags.has('json');
     if (flags.has('help')) {
@@ -5949,10 +6234,25 @@ function cmdScore(options, flags, cwd, write) {
     };
     walk(dir, '', 0);
     const card = scoreRun(slug, artifacts);
+    // 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 = 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, exitCode: 0 }, null, 2));
-    else
+        write(JSON.stringify({ ...card, reqeDebt: reqeNote, exitCode: 0 }, null, 2));
+    else {
         write(renderScorecard(card));
+        if (reqeNote)
+            write('note: ' + reqeNote);
+    }
     return 0;
 }
 /**
@@ -7549,6 +7849,8 @@ export async function runCli(argv, io = {}) {
                 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':