@dzhechkov/harness-cli 0.3.256 → 0.3.258

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.256",
+  "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.145",
+    "@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": "5f73e2c6d9c0ea38d5324f058cbd921bdb28dab60aa97ded97979ed994426731"
+          "content": "a38e5ef6a741aec138af0de7bd3616d4356d613ba1616bd8b5417194c1ee5f03"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "18d5f55ed3c56718e470fef8bd677c55de08f4505e188b1dd29a0f0bbec09d4b"
+          "content": "f954d1e2e3d9f5941481a2b2ccbf553bab892dfa9ba1e7aefb4bf7d1800e9203"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c47d11fd3ed7e6049b1080cd9292ed3498e113d8bc74a9af65a027d70fa96435"
+          "content": "5fb105be335591fb20401a3b23bac9829777e7ba96c2a2480c29970f4ffa2774"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "684ea0c6fa4edbbbea1ffcd943167cd374166eb196100433d4e8d02d70560794"
+          "content": "a4be3aac6dadec03c1fc85fc5354d9a286ac0a21b4983349c4e511cae49dec79"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "154755702a4652597bf8ca1410f9a3303b76c6a8dae8dacd867921a88c7b3626"
+          "content": "b502ba368d29e25413ce35e8853bc5650c06f686202e51f997f67db0fac03224"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0dce827134ab5f7aaf55bd76325b5e1e17881770310e64e0d66bafbedc91687e"
+          "content": "a369561502f08d9dd4993a294adcb3a38349f543959fa8de31cd1580778062b0"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7d6ba26ec1188db3b3ac89f50b015ba1f0c6117b5c30d99b22da41da10c96c12"
+          "content": "555aed692218a73f23a343df2f2b38ce028e694dd9d4aff37e727096f88eb50e"
         }
       ]
     },

package/src/cli.ts

@@ -4,7 +4,7 @@
  * @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';
@@ -80,6 +80,11 @@ import {
   statuslineData,
   writeFeatureAdrState,
   computeUsage,
+  deriveCostLedger,
+  renderCostLedger,
+  verifyCostLedgerReport,
+  writeCostLedgerJsonl,
+  COST_LEDGER_SCOPE,
   deriveUsageCalibration,
   normalizeClaudeUsageModelKey,
   readUsageLimits,
@@ -107,6 +112,11 @@ import {
   RECALL_USAGE_LOG_MAX_BYTES,
   parseRecallUsageLog,
   buildRecallUsageReport,
+  EVENT_CHAIN_TAIL_BYTES,
+  EMPTY_LOG_TAIL,
+  readTailInfo,
+  appendChainedLines,
+  verifyEventChainText,
   buildManifest,
   buildSbom,
   resolveTrustRoot,
@@ -269,6 +279,7 @@ import {
 import type { IdeaRecord, IdeaStatus } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
+import type { LogTail } from '@dzhechkov/harness-core';
 import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow, GateExecution, GateStep } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
@@ -334,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>"
@@ -1503,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
@@ -1534,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);
@@ -5045,11 +5116,44 @@ function runGuardEvaluation(root: string, op: string, text: string | undefined,
   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: string): LogTail {
+  let fd: number | undefined;
+  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');
@@ -6290,7 +6394,19 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
     /* 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: { log: string; text: string }[] = [];
+  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 write(renderCompoundingReport(report));
   return 0;