@dzhechkov/harness-cli 0.3.257 → 0.3.259

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "7333dd44bcbeb6536e8ee0f0490a57fefca211e706535da7f44cea7012388213"
+        "sha256": "6b3bcc252253732b9703f1eb43ac1f0e9f0599979b09d0fea3208932fd0f33a8"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -41,15 +41,15 @@
       },
       {
         "path": "dist/cli.d.ts.map",
-        "sha256": "818293a250cdf1bd10b5d69267b714d9a8ab90017c1fa18de29fc24e28ad8a55"
+        "sha256": "4c5fa8c51cc350874413efceb0a2e4dce2f0c71f39914ddd8be425336a37ae2d"
       },
       {
         "path": "dist/cli.js",
-        "sha256": "9c37499ed55b571232b5718c863b83b31f7a79faab46a9dcbe3283b993b1862a"
+        "sha256": "a75034dfe70f0b57811dfad831366bd5c7995583a57db0f218621b026ac8d854"
       },
       {
         "path": "dist/cli.js.map",
-        "sha256": "6cf537925ccb4b1ffff84c8fd255b487438b78b56a46f9d91d33b25500ae520d"
+        "sha256": "dbe8fa418aedcb77dead3a374bba7cbf0fb5e305dd9a06002946a19604279684"
       },
       {
         "path": "dist/index.d.ts",
@@ -73,7 +73,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "7abb07cdda09bea2b8e948cecdbaed4579371e8d0e8cee4436e7fcb20f430cdd"
+        "sha256": "72858a1f0199832c7ad781f892b7b117ec980af33ff9598587e1ed1544046a35"
       },
       {
         "path": "src/bin.ts",
@@ -81,7 +81,7 @@
       },
       {
         "path": "src/cli.ts",
-        "sha256": "d64af623372238bb5f2ead34e733130d7b013c49058a26f4795f09586b2b5dda"
+        "sha256": "1481238a2fc3a60051f678dcf6b415f8052ce954a9e55ee7577d8c3b2261e062"
       },
       {
         "path": "src/index.ts",
@@ -89,7 +89,7 @@
       },
       {
         "path": "test/cli.test.ts",
-        "sha256": "555aed692218a73f23a343df2f2b38ce028e694dd9d4aff37e727096f88eb50e"
+        "sha256": "24f2feb4c5c4fa939beb79cd658b03fbc7ce4bd87f15da563240abcb252c472c"
       },
       {
         "path": "test/epoch-replay-cli.test.ts",
@@ -109,5 +109,5 @@
       }
     ]
   },
-  "signature": "SGosjJne1+J5lgK/bAptsnGAciI95Bi4z2zHjB1QC8yWic0SGvKE3rj2mZqvjBfwmwzxvpmYBv/laFmWIQEtAw=="
+  "signature": "uYnxiEzDxjwdXlp1SGaC0Zv2x/MW39skbUKw3+xpvnLcoNsEV4pp8kFD5q7urBvC87fC+lRKsIpatoXCNGzwBA=="
 }

package/README.md

@@ -132,7 +132,7 @@ point any tool at (a skill is just Markdown). Dedicated targets are on the [road
 
 ## User Journey — from install to mastery
 
-All 62 commands mapped to a real workflow:
+All 63 commands mapped to a real workflow:
 
 ```
 DISCOVER → INSTALL → USE → CREATE → MAINTAIN → SHARE
@@ -604,6 +604,41 @@ ever enter a work order.
 **When to use:** after `dz compounding` reports the replay as READY; before claiming that recall
 "works"; and any time you want the claim re-checked as the corpus grows.
 
+### Пересмотр после аварийного само-ревью — `dz reqe`
+
+The feature-adr pipeline's cross-model guard says *the model that writes code must not review it*.
+Under limit pressure (usage-adaptive `>=70%` switch) that guard is CONSCIOUSLY suspended: coder AND
+Step-8 QE both run on Codex (FR-2.9 — a Claude reviewer is exactly the agent that dies at the
+limit). The rule used to say "re-review manually after limits reset" — an instruction nobody
+remembers. `dz reqe` turns it into a **debt with a lifecycle**: the run records
+`features/<slug>/.fa-state/reqe-due.json`, `dz usage` surfaces the count the moment you check your
+freed-up limits, and settlement is FAIL-CLOSED.
+
+```bash
+$ dz usage
+usage: session ~12% (resets 03:00) · week ~41% (resets 06:00) · estimated
+re-QE due: 1 usage-switched run(s) kept same-family QE — run `dz reqe` for the cross-family pass
+
+$ dz reqe                        # the ledger
+dz reqe — 1 unsettled re-QE debt(s):
+  add-x  coder=openai qe=openai grade=B  2026-07-30T10:00:00Z  → dz reqe --slug add-x
+
+$ dz reqe --slug add-x           # the ready cross-family review brief (the OTHER family than the coder)
+$ dz reqe --slug add-x --done --report features/add-x/08b_reqe_report.md
+dz reqe: debt settled: re-QE grade C (report …) — settlement appended to features/add-x/08_qe_report.md
+```
+
+**When to use:** any time `dz usage` prints a `re-QE due` line, or a feature-adr result carried
+`reqeDue: true`. **Fail-closed settlement:** the report must exist, be non-trivial, and name exactly
+one line-anchored `GRADE` (the boilerplate phrase `GRADE A-F` does not count); the run's own
+`08_qe_report.md` can never settle its own debt (real-path AND inode compared — a hard link doesn't
+fool it); the settlement epilogue lands in `08_qe_report.md` and the due-file rotates to
+`reqe-settled.json` (evidence kept, never deleted). **Honest scope** (printed by the command):
+nothing re-runs QE automatically, and the validator proves the settlement is procedurally sound —
+which model authored the report stays with the human running the brief. RU: гард «кодер не ревьюит
+сам себя» осознанно снимается под лимитом; `dz reqe` превращает инструкцию «перепроверь потом»
+в долг на диске — виден в `dz usage`, гасится только настоящим кросс-семейным отчётом с грейдом.
+
 ### Usage estimates you can act on — `dz usage`
 
 `dz usage` estimates how much of your Claude session (5h block) and week you have spent, from local
@@ -632,6 +667,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
@@ -866,7 +988,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (62)
+## All Commands (63)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -888,6 +1010,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).
@@ -929,6 +1052,7 @@ dz epoch-replay --emit  [--project <dir>] [--limit <N>] [--seed <N>] [--margin <
 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
 dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   # un-blind against the VERIFIED pre-registered assignment; ONE paired binomial over DECISIVE pairs (ties excluded, reported) → SUPPORTED only when the lift interval (2p−1) lies entirely above zero; FALSIFIED only on harm or a passed non-superiority test (lift upper bound below the margin PRE-REGISTERED in the work order, default 0.05, at 10+ decisive pairs); else INCONCLUSIVE (min 5 decisive pairs). Refuses a forged work order, a --margin flag, or duplicate judgement ids; the verdict is data, not an exit code
 dz score             --slug <feature> [--project <dir>] [--json]   # process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination proof, cross-model QE grade, live verification, README-first, learning loop, amendments — DESCRIPTIVE-ONLY (a low score exits 0); evidence lines are shown so the reader judges the heuristics
+dz reqe              [--slug <feature> [--done --report <f>]] [--project <dir>] [--json]   # the re-QE debt ledger: a usage-switched feature-adr run whose Step-8 QE ran on the coder's OWN family (cross-model guard suspended, FR-2.9) records a debt; list debts (also surfaced by dz usage), print the cross-family review brief, settle FAIL-CLOSED against an existing GRADED report (the run's own 08_qe_report.md — even hard-linked — can never settle its own debt); settlement lands in 08_qe_report.md, evidence rotates to reqe-settled.json
 dz backlog <sub>     add "<idea>" | list | show <id> | goals [--validate] | roulette [--seed n] [--commit <id>] | enrich <id> | jira <id> | harmonize [--apply]   # brain-backed idea backlog: capture an idea → semantic dedup against past ideas/features via the REUSED agentdb vector engine (DUPLICATE≥0.92 / RELATED / NEW) + GoalMap alignment ("map+compass") → weighted seeded roulette picks one to work on → enrich STAGES an idea2prd hand-off → jira writes an auditable outbox via a configurable MCP adapter seam (jira-mcp|copilot-mcp|none). No 2nd vector store; without agentdb it degrades to exact-text dedup (honest)
 dz sign --init --out <path>  |  --pack <dir> --key <path>   # --init: generate the Ed25519 keypair (private OUTSIDE the repo, prints the public key for keys/dz.pub); else sign a pack's manifest + CycloneDX SBOM
 dz sbom --pack <dir> [--out <file>]   # emit the CycloneDX 1.5 SBOM for a pack standalone (file-level bill of materials); print to stdout or write to a file
@@ -2641,7 +2765,7 @@ npx @dzhechkov/p-replicator init
 
 ## Status
 
-`v0.3.236` — published on npm. Also available as [Claude Plugin](#claude-plugin). Part of [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub).
+`v0.3.259` — published on npm. Also available as [Claude Plugin](#claude-plugin). Part of [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub).
 
 ## Claude Plugin
 

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;AA0XH,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;AA+0O9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8J5E"}