@dzhechkov/harness-cli 0.3.257 → 0.3.258

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.257",
+  "version": "0.3.258",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
-    "@dzhechkov/harness-core": "^0.3.146",
+    "@dzhechkov/harness-core": "^0.3.147",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7333dd44bcbeb6536e8ee0f0490a57fefca211e706535da7f44cea7012388213"
+          "content": "a38e5ef6a741aec138af0de7bd3616d4356d613ba1616bd8b5417194c1ee5f03"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "818293a250cdf1bd10b5d69267b714d9a8ab90017c1fa18de29fc24e28ad8a55"
+          "content": "f954d1e2e3d9f5941481a2b2ccbf553bab892dfa9ba1e7aefb4bf7d1800e9203"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9c37499ed55b571232b5718c863b83b31f7a79faab46a9dcbe3283b993b1862a"
+          "content": "5fb105be335591fb20401a3b23bac9829777e7ba96c2a2480c29970f4ffa2774"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6cf537925ccb4b1ffff84c8fd255b487438b78b56a46f9d91d33b25500ae520d"
+          "content": "a4be3aac6dadec03c1fc85fc5354d9a286ac0a21b4983349c4e511cae49dec79"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7abb07cdda09bea2b8e948cecdbaed4579371e8d0e8cee4436e7fcb20f430cdd"
+          "content": "b502ba368d29e25413ce35e8853bc5650c06f686202e51f997f67db0fac03224"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d64af623372238bb5f2ead34e733130d7b013c49058a26f4795f09586b2b5dda"
+          "content": "a369561502f08d9dd4993a294adcb3a38349f543959fa8de31cd1580778062b0"
         }
       ]
     },

package/src/cli.ts

@@ -80,6 +80,11 @@ import {
   statuslineData,
   writeFeatureAdrState,
   computeUsage,
+  deriveCostLedger,
+  renderCostLedger,
+  verifyCostLedgerReport,
+  writeCostLedgerJsonl,
+  COST_LEDGER_SCOPE,
   deriveUsageCalibration,
   normalizeClaudeUsageModelKey,
   readUsageLimits,
@@ -340,6 +345,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>"
@@ -1509,6 +1515,64 @@ function cmdUsageCalibrate(
   }
 }
 
+/**
+ * `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: Map<string, string>,
+  flags: Set<string>,
+  write: Write,
+): number {
+  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: boolean | null = 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
@@ -1540,6 +1604,7 @@ function cmdUsage(
     });
   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);