@dzhechkov/harness-cli 0.3.256 → 0.3.258

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "5f73e2c6d9c0ea38d5324f058cbd921bdb28dab60aa97ded97979ed994426731"
+        "sha256": "a38e5ef6a741aec138af0de7bd3616d4356d613ba1616bd8b5417194c1ee5f03"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -41,15 +41,15 @@
       },
       {
         "path": "dist/cli.d.ts.map",
-        "sha256": "18d5f55ed3c56718e470fef8bd677c55de08f4505e188b1dd29a0f0bbec09d4b"
+        "sha256": "f954d1e2e3d9f5941481a2b2ccbf553bab892dfa9ba1e7aefb4bf7d1800e9203"
       },
       {
         "path": "dist/cli.js",
-        "sha256": "c47d11fd3ed7e6049b1080cd9292ed3498e113d8bc74a9af65a027d70fa96435"
+        "sha256": "5fb105be335591fb20401a3b23bac9829777e7ba96c2a2480c29970f4ffa2774"
       },
       {
         "path": "dist/cli.js.map",
-        "sha256": "684ea0c6fa4edbbbea1ffcd943167cd374166eb196100433d4e8d02d70560794"
+        "sha256": "a4be3aac6dadec03c1fc85fc5354d9a286ac0a21b4983349c4e511cae49dec79"
       },
       {
         "path": "dist/index.d.ts",
@@ -73,7 +73,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "154755702a4652597bf8ca1410f9a3303b76c6a8dae8dacd867921a88c7b3626"
+        "sha256": "b502ba368d29e25413ce35e8853bc5650c06f686202e51f997f67db0fac03224"
       },
       {
         "path": "src/bin.ts",
@@ -81,7 +81,7 @@
       },
       {
         "path": "src/cli.ts",
-        "sha256": "0dce827134ab5f7aaf55bd76325b5e1e17881770310e64e0d66bafbedc91687e"
+        "sha256": "a369561502f08d9dd4993a294adcb3a38349f543959fa8de31cd1580778062b0"
       },
       {
         "path": "src/index.ts",
@@ -89,7 +89,7 @@
       },
       {
         "path": "test/cli.test.ts",
-        "sha256": "7d6ba26ec1188db3b3ac89f50b015ba1f0c6117b5c30d99b22da41da10c96c12"
+        "sha256": "555aed692218a73f23a343df2f2b38ce028e694dd9d4aff37e727096f88eb50e"
       },
       {
         "path": "test/epoch-replay-cli.test.ts",
@@ -109,5 +109,5 @@
       }
     ]
   },
-  "signature": "5nXiD5ii68CSKw5EWFT2WXxbELjZYvHBup3O5E4oLDcTszEC2kyuHXBy7VBzcrkgzNtICsxp8+hJJMcGXa2+Cw=="
+  "signature": "CXaYCYQIKEVpAB29MZ5rG0/VUWtihZaeJh86r6x8uFpzKrgzHnrzmg/MmTUW3R/rqeA5w12hcfyfr4kl85ZxBA=="
 }

package/README.md

@@ -456,6 +456,8 @@ $ dz compounding
     ↓ readme-first: 49 → 4
   COLD-VS-WARM REPLAY: 2 unique prompt event(s); 5 needed — queries are recorded as of 2026-07-28
   INSTRUMENTATION: last apply-leg record … — live
+  EVIDENCE CHAIN .dz/recall-usage.jsonl: verified · 3 chained · 133 pre-chain (uncovered)
+  EVIDENCE CHAIN .dz/guard-audit.jsonl: verified · 3 chained · 82 pre-chain (uncovered)
 ```
 
 Three honesty rules are load-bearing:
@@ -469,6 +471,47 @@ The prompt queries that make replay possible stay on your machine: `.dz/recall-u
 git-ignored, entries are truncated at 200 chars and flagged when truncated (a prefix is not a prompt,
 so flagged rows never count as replayable).
 
+#### Is the evidence itself intact? — the event chain
+
+Every number above is computed from two JSONL files, and a compaction bug already inflated one of
+them once (read totals grew `2 → 4 → 6` across three compactions, fixed 2026-07-28). So each record
+appended to `.dz/recall-usage.jsonl` and `.dz/guard-audit.jsonl` now carries a sequence number and a
+hash of the line before it, and both `dz compounding` and `dz doctor` verify the chain:
+
+```
+$ dz compounding | grep 'EVIDENCE CHAIN'
+  EVIDENCE CHAIN .dz/recall-usage.jsonl: verified · 3 chained · 133 pre-chain (uncovered)
+
+$ dz doctor            # silent while clean; on damage:
+  [XX] evidence chain (.dz/guard-audit.jsonl) - 1 defect(s): BrokenLink@L3 —
+       learning verdicts computed from this log are unsafe
+```
+
+Defects are named, not lumped: `BrokenLink` (an edited or lost record), `DuplicateSeq` (a duplicated
+record, or two writers racing), `NonMonotonicSeq` (an unrecorded restart), `TornTail` (a partial
+write), `DoubleCounted` (a rewrite that emits more events than it read — the `2 → 4 → 6` class),
+plus three that keep a rewrite from certifying itself: `LedgerImbalance`, `MalformedLedger` and
+`ClaimInterrupted`.
+
+Two rules make the check hard to fool, both learned from cross-model review:
+
+- **compaction refuses to launder.** A rewrite that re-chains a damaged file would turn corruption
+  into a clean chain — so compaction verifies its input first and REFUSES a defective one. The log
+  then grows past its size cap, on purpose: the cap is a convenience, the evidence is the product.
+- **a rewrite cannot silently eat a concurrent append.** The whole-file rewrite takes an exclusive
+  lock and re-reads the live file immediately before the rename; an append that landed in between
+  aborts the attempt and is folded into the retry instead of being overwritten.
+
+**Honest scope, stated everywhere it appears:** this is corruption detection for *our own* bugs —
+compaction, torn writes, races. FNV-1a is not cryptography and the threat model has no adversary:
+anyone who can edit the log can recompute the chain. **When to use:** read the line before you quote
+any `dz compounding` number, and after any crash that interrupted a write.
+
+Three properties make it safe to run on a per-prompt hook: chain fields come from the **last line
+only** (no full-file scan per append); records written before chaining existed stay valid and are
+reported as an uncovered `pre-chain` prefix rather than flagged; and a tail that cannot be read
+**never blocks the write** — the writer starts a fresh, explicitly marked segment.
+
 ### Did the lessons actually change outcomes? — `dz epoch-replay`
 
 `dz compounding` says a cold-vs-warm replay **can** be run. `dz epoch-replay` **runs** it and reports
@@ -589,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
@@ -845,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).
@@ -880,7 +1011,7 @@ dz bto-optimize --split|--plan|--select|--scope-check|--diff [--json]   # determ
 dz discrimination-check --test <f[,f]> [--base <ref>] [--name <filter>] [--runner <cmd>] [--json]   # §42 test-discrimination gate for feature-adr Step-8: run the ADR's property test in an isolated git worktree at pre-feature base — it MUST go red without the fix; a green is a false green (HIGH finding, advisory, never auto-aborts)
 dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   # portable Step-10 Delivery Gate: the `manual` form that travels to every shell target — prints the 4-plane review brief (regressions ‖ security ‖ code-quality ‖ product-honesty) + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off (only cross-validated BLOCKER/HIGH count) and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked
 dz skills-verify     [--dir <project>] [--expect a,b] [--static] [--strict] [--timeout <s>] [--json]   # does .claude/skills/ actually REGISTER? --static = instant layout scan (CI-safe, no session): flags dirs that can never register; default also starts a real session and reads the authoritative system/init listing. exit 0 pass / 1 fail / 2 inconclusive — an unobservable registration is NEVER a pass
-dz compounding       [--project <dir>] [--json]   # honest learning-loop payoff report: pool write-only ratio, guard repeat-violation trajectory (rate per audit-half), cold-vs-warm replay readiness over unique untruncated prompt events, apply-leg staleness — a gate without enough data says INSUFFICIENT_DATA, never a verdict
+dz compounding       [--project <dir>] [--json]   # honest learning-loop payoff report: pool write-only ratio, guard repeat-violation trajectory (rate per audit-half), cold-vs-warm replay readiness over unique untruncated prompt events, apply-leg staleness, and EVENT-CHAIN health of the two evidence logs (verified / defects / uncovered pre-chain prefix) — a gate without enough data says INSUFFICIENT_DATA, never a verdict
 dz epoch-replay --mock  [--n <N>] [--effect <-1..1>] [--tie-rate <0..1>] [--seed <N>] [--slice <name>] [--margin <0..0.5>] [--json]   # $0 synthetic run through the REAL verdict math; labelled SYNTHETIC, same seed = byte-identical
 dz epoch-replay --emit  [--project <dir>] [--limit <N>] [--seed <N>] [--margin <0..0.5>] [--out <file>] [--json]   # cold-vs-warm work order: replayable instances + PRE-REGISTERED blind A/B assignment + the PRE-REGISTERED non-superiority margin + a sha256 integrity digest + emittedAt/corpus fingerprint (raw prompts — defaults into the git-ignored .dz/epoch-replay/)
 dz epoch-replay --judge <filled-work-order.json> [--out <file>] [--json]   # blind judge prompts from the filled plans — the file carries {id, prompt} ONLY (no assignment, no arm names); refuses an order whose digest or seed-derived assignment does not check out; half-pairs skipped WITH A REASON, on stdout

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuWH,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;AA4gO9E,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

@@ -3,13 +3,13 @@
  *
  * @packageDocumentation
  */
-import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, 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, 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;
@@ -4686,11 +4740,50 @@ function runGuardEvaluation(root, op, text, overrideReason) {
     try {
         const rec = auditRecord(result, new Date().toISOString(), overrideReason !== undefined ? { reason: overrideReason } : undefined);
         mkdirSync(join(root, '.dz'), { recursive: true });
-        writeFileSync(join(root, '.dz', 'guard-audit.jsonl'), JSON.stringify(rec) + '\n', { flag: 'a' });
+        const auditPath = join(root, '.dz', 'guard-audit.jsonl');
+        // event-chain (ADR-001): seq + prevHash derived from the LAST LINE ONLY — this file is the
+        // evidence base `dz guard promote` decides on, and a rewrite that loses or duplicates a record
+        // must not be able to look intact. A tail that cannot be read starts a MARKED segment rather
+        // than blocking the audit: the verdict is never held hostage to a broken log.
+        writeFileSync(auditPath, appendChainedLines([rec], readLogTail(auditPath)), { flag: 'a' });
     }
     catch { /* audit is best-effort, never blocks the verdict */ }
     return result;
 }
+/**
+ * The tail facts of an append-only log, read from its END — O(1) in the file size, which is what
+ * lets the chain be extended on every append without a full-file scan (FR-2). Anything unreadable
+ * yields {@link EMPTY_LOG_TAIL}; the caller then starts a marked segment rather than blocking.
+ */
+function readLogTail(path) {
+    let fd;
+    try {
+        if (!existsSync(path))
+            return EMPTY_LOG_TAIL;
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        if (!Number.isFinite(size) || size <= 0)
+            return EMPTY_LOG_TAIL;
+        const want = Math.min(size, EVENT_CHAIN_TAIL_BYTES);
+        const buf = Buffer.alloc(want);
+        readSync(fd, buf, 0, want, size - want);
+        return readTailInfo(buf.toString('utf-8'), { partial: want < size });
+    }
+    catch {
+        // A read FAILURE is not an empty file (Codex re-QE LOW): EMPTY_LOG_TAIL means "there is
+        // nothing", which lets the writer open an UNMARKED genesis on a file we merely failed to
+        // read. An unreadable tail must force a marked reset, per the AM-6 contract.
+        return { ...EMPTY_LOG_TAIL, unreadable: true };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* nothing to do */ }
+        }
+    }
+}
 // ── `dz guard promote` (feature guard-promotion, scout idea #1) ─────────────────────────────────
 const PROMOTIONS_DIR = join('features', 'guard-promotion', 'promotions');
 const PROMOTION_STATE_FILE = join('.dz', 'promotion-state.json');
@@ -6019,7 +6112,19 @@ function cmdCompounding(options, flags, cwd, write) {
     catch {
         /* no audit yet */
     }
-    const report = assembleCompoundingReport({ lessons, usage, guard, nowTs: new Date().toISOString() });
+    // The evidence logs themselves, verbatim: the report verifies their hash chains (feature
+    // event-chain). Handing over the TEXT rather than a pre-computed verdict keeps one definition of
+    // "the chain is intact" — a second copy here is how a gate and its report start disagreeing.
+    const evidenceLogs = [];
+    for (const rel of ['.dz/recall-usage.jsonl', '.dz/guard-audit.jsonl']) {
+        try {
+            evidenceLogs.push({ log: rel, text: readFileSync(join(root, ...rel.split('/')), 'utf-8') });
+        }
+        catch {
+            /* absent log — reported by its own gate above, not invented here */
+        }
+    }
+    const report = assembleCompoundingReport({ lessons, usage, guard, nowTs: new Date().toISOString(), evidenceLogs });
     if (json)
         write(JSON.stringify({ ...report, exitCode: 0 }, null, 2));
     else