@dzhechkov/harness-cli 0.3.257 → 0.3.258

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "7333dd44bcbeb6536e8ee0f0490a57fefca211e706535da7f44cea7012388213"
+        "sha256": "a38e5ef6a741aec138af0de7bd3616d4356d613ba1616bd8b5417194c1ee5f03"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -41,15 +41,15 @@
       },
       {
         "path": "dist/cli.d.ts.map",
-        "sha256": "818293a250cdf1bd10b5d69267b714d9a8ab90017c1fa18de29fc24e28ad8a55"
+        "sha256": "f954d1e2e3d9f5941481a2b2ccbf553bab892dfa9ba1e7aefb4bf7d1800e9203"
       },
       {
         "path": "dist/cli.js",
-        "sha256": "9c37499ed55b571232b5718c863b83b31f7a79faab46a9dcbe3283b993b1862a"
+        "sha256": "5fb105be335591fb20401a3b23bac9829777e7ba96c2a2480c29970f4ffa2774"
       },
       {
         "path": "dist/cli.js.map",
-        "sha256": "6cf537925ccb4b1ffff84c8fd255b487438b78b56a46f9d91d33b25500ae520d"
+        "sha256": "a4be3aac6dadec03c1fc85fc5354d9a286ac0a21b4983349c4e511cae49dec79"
       },
       {
         "path": "dist/index.d.ts",
@@ -73,7 +73,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "7abb07cdda09bea2b8e948cecdbaed4579371e8d0e8cee4436e7fcb20f430cdd"
+        "sha256": "b502ba368d29e25413ce35e8853bc5650c06f686202e51f997f67db0fac03224"
       },
       {
         "path": "src/bin.ts",
@@ -81,7 +81,7 @@
       },
       {
         "path": "src/cli.ts",
-        "sha256": "d64af623372238bb5f2ead34e733130d7b013c49058a26f4795f09586b2b5dda"
+        "sha256": "a369561502f08d9dd4993a294adcb3a38349f543959fa8de31cd1580778062b0"
       },
       {
         "path": "src/index.ts",
@@ -109,5 +109,5 @@
       }
     ]
   },
-  "signature": "SGosjJne1+J5lgK/bAptsnGAciI95Bi4z2zHjB1QC8yWic0SGvKE3rj2mZqvjBfwmwzxvpmYBv/laFmWIQEtAw=="
+  "signature": "CXaYCYQIKEVpAB29MZ5rG0/VUWtihZaeJh86r6x8uFpzKrgzHnrzmg/MmTUW3R/rqeA5w12hcfyfr4kl85ZxBA=="
 }

package/README.md

@@ -632,6 +632,93 @@ a guess dressed as a number. The authoritative calibration is `--calibrate` with
 shown on claude.ai/settings/usage; absent that, limits set from your own observed peak mean "unusually
 heavy **for you**", which is exactly what a pre-emptive routing switch needs.
 
+### Where did the run's budget actually go? — `dz usage --by-stage`
+
+**The itemized receipt.** A `/feature-adr` run reports ONE number. The recorded run
+`wf_0576bd7d-797` spent `623290` tokens (MEASURED — reproducer:
+`dz usage --by-stage --run wf_0576bd7d-797`, `totalTokens` field of the run record) — a restaurant
+bill with no line items. `dz usage --by-stage` turns it into a receipt keyed by the workflow's own
+stage labels, so *"where the budget burns"* stops being a feeling and becomes a number you can sort.
+
+Why it matters, in four points:
+
+1. **Visibility → control.** Per-stage rows (`code` · `qe:brutal` · `fleet:cov` · `delivery:*`),
+   each with its model, its weighted tokens, its call count and a USD estimate — sorted by spend, so
+   the expensive stage is the first line you read.
+2. **Real numbers for auto-cost routing.** `args.models.<stage> = 'auto-cost'` picks models from a
+   STATIC assumptions table. The ledger exposes MEASURED per-stage aggregates
+   (`{stage, model, avgTokens, runs}`) — the missing sense organ for a system meant to optimize its
+   own cost. *Wiring into routing is deliberately out of scope for now: the reader exists, nothing
+   consumes it yet.*
+3. **The reconciliation invariant guards the bookkeeping itself.** Per-stage sums MUST reconcile
+   with the run total: `accounted + unaccounted = run total`, as raw integer equality. A mismatch is
+   a **NAMED defect** (`Unaccounted` / `DoubleAttributed` / `ForeignSample` /
+   `MissingStageTranscript` / `MalformedRecord`), never a rounding remainder — the same discipline as
+   the event-chain ledger. Without it a by-stage table can quietly lie: it already caught a real run
+   where 12 agent transcripts had no stage entry at all.
+4. **The honest limit, stated next to the benefits.** Totals are LOCAL TRANSCRIPT ESTIMATES — no
+   billing API is consulted. So the invariant catches **attribution** errors (a double-counted stage,
+   a missing one), **not pricing** errors. There is no "accurate to the cent" promise here, and the
+   USD column marks with `*` every row priced by the sonnet-class fallback.
+
+#### Зачем это
+
+Прогон `/feature-adr` отчитывается **одним** числом. У записанного прогона `wf_0576bd7d-797` это
+`623290` токенов (MEASURED — воспроизводится: `dz usage --by-stage --run wf_0576bd7d-797`) — счёт из
+ресторана без позиций. `dz usage --by-stage` превращает его в **детализированный счёт** по тем самым
+меткам стадий, которые пайплайн уже проставляет, — и «где горит бюджет» перестаёт быть ощущением и
+становится числом.
+
+1. **Видимость → управляемость.** Строка на стадию (`code` · `qe:brutal` · `fleet:cov` ·
+   `delivery:*`) с моделью, взвешенными токенами, числом вызовов и оценкой в долларах, отсортированные
+   по расходу: дорогая стадия — первая строка, которую вы читаете.
+2. **Живые данные для auto-cost роутинга.** Сейчас `args.models.<stage> = 'auto-cost'` выбирает
+   модель по СТАТИЧЕСКОЙ таблице предположений. Реестр отдаёт ИЗМЕРЕННЫЕ агрегаты по стадиям
+   (`{stage, model, avgTokens, runs}`) — недостающий орган чувств для системы, которая должна
+   оптимизировать собственную стоимость. *Подключение к роутингу сознательно вынесено за рамки:
+   читатель есть, потребителя пока нет.*
+3. **Инвариант сверки страхует саму бухгалтерию.** Сумма по стадиям ОБЯЗАНА сходиться с итогом
+   прогона: `учтено + неучтённое = итог`, точное целочисленное равенство. Расхождение — это
+   **именованный дефект**, а не «остаток от округления»: та же дисциплина, что у event-chain-реестра.
+   Без него таблица по стадиям может тихо врать — и она уже поймала реальный прогон, где 12
+   транскриптов агентов не имели записи ни об одной стадии.
+4. **Честная граница — рядом с пользой.** Итоги считаются по ЛОКАЛЬНЫМ транскриптам (никакого
+   биллингового API), поэтому инвариант ловит ошибки **атрибуции** (двойной счёт, потерянную стадию),
+   а НЕ ошибки **цены**. Обещания «до цента» здесь нет, а строки, посчитанные по резервному
+   sonnet-тарифу, помечены `*`.
+
+```bash
+dz usage --by-stage                                # the most recent workflow run
+dz usage --by-stage --slug portable-gates          # by feature slug
+dz usage --by-stage --run wf_0576bd7d-797          # by run id
+dz usage --by-stage --json                         # rows + reconciliation, machine-readable
+dz usage --by-stage --write features/x/09_cost_ledger.jsonl   # materialize the derived report
+```
+
+Real output (MEASURED — reproducer: the `--run wf_0576bd7d-797` command above, abridged):
+
+```
+usage --by-stage: run wf_0576bd7d-797 · slug recall-usage-instrumentation · feature-adr · completed
+  stage                                                model                       weighted    calls    ~USD
+  adr:claude-fb                                        claude-opus-4-8[1m]          253,649       11   $1.27
+  design:confirm-landed                                claude-opus-4-8[1m]          196,013        7 $0.9801
+  qcsd · codex:gpt-5.6:xhigh (usage-switched)          claude-sonnet-5              109,122        7 $0.3274
+  usage:probe                                          claude-haiku-4-5-20251001     76,441        6 $0.0764
+  reconciliation: accounted 1,112,167 + unaccounted 0 = run total 1,112,167 (epsilon 0.00%)
+  identity: holds (raw integer equality)
+  verdict: BALANCED
+  scope: local transcript ESTIMATES, not billed amounts — the reconciliation invariant catches
+         ATTRIBUTION errors (double-counted or missing stages), NOT pricing errors
+```
+
+**Three verdicts, and `INSUFFICIENT_DATA` is not one of the good ones.** `BALANCED` means measured
+and reconciled; `DEFECT` names what is wrong; `INSUFFICIENT_DATA` means nothing was measured — never
+read `!== 'DEFECT'` as success. Nothing is written unless you pass `--write`, and what it writes is a
+regenerable report, not a store.
+
+**When to use:** after an expensive run, before deciding which stage to re-route or downgrade; when
+a run's cost surprises you; and any time a by-stage number is about to be quoted to someone.
+
 ### Do your skills actually register? — `dz skills-verify`
 
 Shipping a skill pack is not the same as a skill **registering**. A layout test that asserts
@@ -888,6 +975,7 @@ dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC me
 dz teach --harmonize [--apply] [--threshold <0..1>]                # alias of `dz vector harmonize`
 dz statusline        [--json] [--install]   # compact Claude Code statusline: live self-learning pattern count + brain sources
 dz usage             [--json] [--project <dir>] | --calibrate --session <pct> --weekly <pct> [--model fable=<pct>]   # ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS
+                     --by-stage [--run <id> | --slug <s>] [--epsilon <0..1>] [--write <file.jsonl>] [--json]         # per-stage cost ledger for ONE feature-adr run + reconciliation invariant (BALANCED | DEFECT | INSUFFICIENT_DATA)
 dz claim-check       [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]   # enforce the Integrity Rule: flag untagged/overstated accuracy claims; default scan = READMEs + features' 08_qe_report.md; exit 1 only at/above --fail-on (default high)
 dz brain list        [--json]                                        # the durable cross-project knowledge brain
 dz brain query       "<q>" [--source <slug>] [--limit <N>] [--any] [--rerank] [--json]  # cross-source recall (--any = OR match; --rerank reorders on-point first). Auto-broadens: if strict all-terms match yields 0 hits, it retries once as OR and labels the result "broadened" (text note + broadened:true in --json) instead of returning empty. Explicit --any is OR from the start (never labeled broadened).

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6WH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACvD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAyjO9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4J5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmXH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KACvD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAonO9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA4J5E"}

package/dist/cli.js

@@ -9,7 +9,7 @@ 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.
@@ -79,6 +79,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 +1130,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 +1206,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;