@dzhechkov/harness-cli 0.4.2 → 0.4.4

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "4e4049b871ded58ff38fc36b60387a2324610db81dedcb623fb9cce6e77b057b"
+        "sha256": "2f053f11ea49780919d0557877302e70adb8f33949299b0b0637ece2809c1b67"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -37,15 +37,15 @@
       },
       {
         "path": "dist/cli.d.ts.map",
-        "sha256": "a260f0e8d698ac142b38e33ef4d4ed0a21ccee96b179514bcb01bf81c5dce00f"
+        "sha256": "5bdc153e789ac180543e9b4955ea36666dc27b7238637b05875e048fc49ae30f"
       },
       {
         "path": "dist/cli.js",
-        "sha256": "b8a9c6d50cea7eda1065d76adb83e7c853ed9d82db72e7b24f952598e9dbd9d9"
+        "sha256": "0183c01a98e232554a7460be48ee5fdf59dd3a7d09c719a31b08acc9c6b3528c"
       },
       {
         "path": "dist/cli.js.map",
-        "sha256": "4af214e9233bd8f37ab92b95b90fcf05bd46752ecdc0d9491484ee8a7e55c539"
+        "sha256": "c5bd1b0b852dd21de328494d7a99db336afbde4397b7c687d416f1a6f3c297b2"
       },
       {
         "path": "dist/index.d.ts",
@@ -69,7 +69,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "fa591b644f5abda81022a2cfe37996d739a2290ac46e09dcb958faa4e12be9f6"
+        "sha256": "5bd26341b4a5885c116432bf621b7fdb4172b2604db47ad3c1c001deb4fe6ed4"
       },
       {
         "path": "src/bin.ts",
@@ -77,7 +77,7 @@
       },
       {
         "path": "src/cli.ts",
-        "sha256": "c9847974744f5bfd383866eb1832e97cb856e73d6f65cad19abfb91f22998cae"
+        "sha256": "0a1097fc3a2294f934fc50f5871b287cfbc5ec85becdab914b7caeca42cb7d1a"
       },
       {
         "path": "src/index.ts",
@@ -189,12 +189,16 @@
       },
       {
         "path": "test/mutation-registry.json",
-        "sha256": "3dd056f9d05712e45173b0911fc5900f0f52f8deba506d57c0e2b8281eb36a74"
+        "sha256": "fe8e5792626cf58678c1e2bcb809f63413655c2e171439157b74deb8b4fd80fb"
       },
       {
         "path": "test/statusline-panel.test.ts",
         "sha256": "b09b42c4ece1a83e5d3f3765629b0756a8f30a7122f3fc30363f93f092a44c0d"
       },
+      {
+        "path": "test/trace-bundle-cli.test.ts",
+        "sha256": "fdaad63359ca7ce351e505e613b547bbc653e0847403edfae88d22a8a524b7a0"
+      },
       {
         "path": "test/workflow-init-lint-clean.test.ts",
         "sha256": "b7a64462983901adca86ecc29e76b3f95885210e5aaba68352356191e6bfac7f"
@@ -217,5 +221,5 @@
       }
     ]
   },
-  "signature": "nT7OzOloD2DCFR2ZYd4uWJ6isGyyfLiYk7v8hUKp4f0OTP0fTpsVvbDYJF9VvxASNVqwOGaQ7F6WQVu3NrkmBQ=="
+  "signature": "dzYono+I+DXsxk1h8k2DAiNYKHmdzhwaUMDvvfFjCqzVFvYZecPnJQCLgT8i5NrpkaOQl2mbwU8bd3tyxQueDg=="
 }

package/README.md

@@ -1141,6 +1141,159 @@ host run there is nothing to read, and it says so rather than inventing a timeli
 follows from the same boundary: on a non-Claude-Code target the authoring and lint verbs work
 unchanged, and only execution is absent.
 
+### Build a loop for YOUR scenario — the end-to-end use case
+
+You have a repeating multi-agent job of your own — say, **a weekly competitor digest: three
+competitors researched in parallel, one synthesis, and a quality gate that sends a weak digest back
+for a redo**. Here is the whole path, with real command output. Every command below was executed
+before being written down; the outputs are captures, not sketches.
+
+**Install (once):**
+
+```bash
+npm i -g @dzhechkov/harness-cli     # gives you the `dz` binary
+# or zero-install per call:  npx @dzhechkov/harness-cli workflow init …
+```
+
+**The division of labour, honestly stated up front:** `dz` AUTHORS, GATES and READS loops — it never
+RUNS one. Execution belongs to a host with the `Workflow({scriptPath})` runtime, which today means
+**Claude Code**. So: author anywhere (Codex included), run under Claude Code.
+
+#### Step 1 — scaffold the plan shape closest to your scenario
+
+```bash
+dz workflow init --name competitor-digest --pattern fanout --o digest.plan.json
+# → wrote digest.plan.json (pattern: fanout)
+# → Next: edit the TODO prompts, then `dz workflow validate` + `dz workflow render`.
+```
+
+Patterns: `pipeline` (A→B→C), `barrier` (all A, then B), `fanout` (N parallel lanes + a join),
+`gate` (a checked step with a redo route). The scaffold is a REAL plan with `TODO` prompts — not a
+template you fight.
+
+#### Step 2 — make it yours (edit the JSON)
+
+Fill the `TODO` prompts, name your lanes in `fanouts[].registry` (`["acme","globex","initech"]`),
+and add the quality gate with a redo route:
+
+```json
+"steps": [ …, { "stepId": "check", "kind": "gate", "phase": "Gate", "deps": ["synthesize"],
+                "prompt": "…answer strictly GATE: PASS or GATE: FAIL as the last line",
+                "budget": { "maxAgents": 2 } } ],
+"gates": [ { "stepId": "check", "kind": "quality", "failRoute": "synthesize", "maxRedos": 1 } ]
+```
+
+The plan surface is deliberately NARROW and fully enacted: anything the generated loop would not
+actually perform is REJECTED at validate time with a named `ENACT-*` diagnostic — never silently
+accepted and ignored.
+
+#### Step 3 — validate, render, lint (the three gates before any run)
+
+```bash
+dz workflow validate digest.plan.json
+# → dz workflow validate: OK (digest sha256:6b6e92fc31b781fa…)
+
+dz workflow render digest.plan.json --o digest.loop.js
+# → wrote digest.loop.plan.json then digest.loop.js (exec-fp sha256:a095d12e…, blobs: trace)
+
+dz workflow-lint digest.loop.js --plan digest.loop.plan.json --require-plan
+# → dz workflow-lint: PASS (0 fail, 1 warn, 0 inconclusive over 17 rules)
+```
+
+`inconclusive` is never a pass, and the rendered script keeps your hand edits across re-renders
+(USER regions are preserved).
+
+#### Step 4 — run it (Claude Code), read it back (anywhere)
+
+In **Claude Code**, paste exactly this:
+
+> Запусти мой цикл: `Workflow({ scriptPath: 'digest.loop.js', args: { items: ["acme","globex","initech"], traceDir: '<run dir>', runId: 'digest-2026-08-18' } })` — и когда закончит, покажи `dz workflow-trace` по этому прогону.
+
+What a real run of THIS plan looks like (captured from an offline harness run of the rendered
+script): `lane:acme, lane:globex, lane:initech` in parallel → `synthesize` → `check` answers
+`GATE: FAIL` → the redo route re-runs `synthesize` → `check` answers `GATE: PASS` → `COMPLETED`.
+13 agent calls, one ledger row, the trace flushed at every settle. Then:
+
+```bash
+dz workflow-trace <runDir> --html report.html   # timeline + SEQ invariants over the loop's own trace
+```
+
+#### How to phrase the ASK — Claude Code vs Codex
+
+**In Claude Code** (it has both `dz` and the `Workflow` runtime — one message does the whole thing):
+
+> Собери мне цикл под сценарий: «<опиши свой — источники, что делает каждая полоса, как сводить,
+> какой критерий качества>». Используй `dz workflow init/validate/render/workflow-lint`, покажи мне
+> план НА СОГЛАСОВАНИЕ до рендера, потом запусти через `Workflow({scriptPath})` и дай ссылку на
+> `workflow-trace` отчёт.
+
+The "покажи план до рендера" clause matters: the plan JSON is the one artifact worth your review —
+prompts, lanes, gate criteria, budgets — and it is small.
+
+**In Codex** (or any shell-capable agent — AUTHORING only, honestly):
+
+> In this repo, run `npx @dzhechkov/harness-cli workflow init --name <x> --pattern fanout --o x.plan.json`,
+> then edit the plan for this scenario: <describe>. Run `workflow validate` and fix every diagnostic
+> it names, then `workflow render` and `workflow-lint --require-plan`. Do NOT attempt to execute the
+> generated loop — it runs under Claude Code's `Workflow({scriptPath})` runtime; hand me the green
+> plan and the rendered script.
+
+Codex is a fine plan AUTHOR — the validate/lint diagnostics are named and machine-checkable, so its
+edit loop converges. What it cannot do is run the result: the generated script calls the host's
+`agent()`/`parallel()` sandbox, which only the Claude Code Workflow runtime provides. A green lint
+from Codex + a run under Claude Code is a legitimate two-agent split.
+
+### Move a run's telemetry to another machine (`workflow-trace export` / `import`)
+
+A run leaves traces on the machine that produced it. `export` puts one run's telemetry into a single
+movable file; `import` reconstructs that run under a root you name.
+
+```bash
+dz workflow-trace export --slug my-feature --o my-feature.bundle.json
+dz workflow-trace import my-feature.bundle.json --into /other/project
+```
+
+**What a bundle carries** — the raw event lines (`trace.jsonl`, `.fa-state/checkpoints.jsonl`), the
+ledger rows selected for that run, optionally the training pairs, and `runMeta`: WHO ran each stage,
+read from the harness's own workflow records. **Events, never aggregates.** The one derived value —
+`attribution`, "which model ran which stage" — travels ALONGSIDE the records it was folded from,
+marked `derived`, naming its rule and the record ids, so a consumer that disagrees can recompute it.
+The rule is stated rather than implied: last-writer-wins by timestamp is a CHOICE — a run whose
+phases used different models has no single honest answer, and the map reports who ran it *last*.
+
+**The ledger selector** matches a row by `runId`, or by `slug` when the row has no `runId` — because
+only `loop-run` rows carry a `runId`, so a `runId`-only filter would select nothing for a feature-adr
+run. The bundle reports rows scanned vs matched, so an empty slice is visibly empty rather than
+indistinguishable from an absent ledger.
+
+**Consent does not travel inside the bundle.** Training pairs may contain target-repo code, so
+including them needs `--include-pairs --yes` at export AND `--with-pairs` at import; a pairs-bearing
+bundle imported without the flag writes no pair content.
+
+**Import is fail-closed.** It reconstructs the run's native layout under `--into`, and REFUSES to
+write into a run directory that already has content unless it is the bundle's own run and `--force`
+is given; an identity mismatch refuses even under `--force`. A refused import writes nothing — not
+one file.
+
+**Degradation is loud and typed**, and exactly one reason asks for action:
+
+| reason | meaning | action |
+|---|---|---|
+| `records-absent` / `no-match` | no harness records, or none for this run | none |
+| `predates-model-routing` | a genuine older run, from before per-stage model routing | none — this is history |
+| `unreadable` | a record could not be parsed | look at that record |
+| `layout-unrecognised` | records exist and parse, but the fields we read are gone | **the harness record layout CHANGED — update the reader** |
+
+By default a degraded export still succeeds and prints one named line per degraded member; `--strict`
+makes it exit non-zero so automation fails closed. The split exists because the actionable reason
+used to fire on normal data — three of thirty-two runs in a real store were simply older than
+per-stage routing — and an alarm that sounds on normal operation stops being an alarm.
+
+**Honest scope:** `runMeta` is read from a store this project does not own, so its shape can change
+without notice. That is precisely what `layout-unrecognised` exists to announce, and why the reader
+refuses rather than half-parsing: a partially-read record would report a model-blind run as
+model-known.
+
 **The v1 plan surface is deliberately NARROW and fully enacted** — `dz workflow validate` REJECTS
 (named diagnostics, never a silent no-op) anything the generated loop would not perform: retry
 timing (`initialDelayMs`/`backoffMultiplier`/`maxDelayMs`/`jitter` — v1 retries are immediate;
@@ -1245,6 +1398,8 @@ dz scout             [--topics <list>] [--since <date>] [--deep] [--output <file
 dz workflow          init --name <n> [--pattern pipeline|barrier|fanout|gate] [--o <plan.json>] | validate <plan.json> [--json] | render <plan.json> --o <script.js> [--check] [--force] | blobs [--check]   # loop-plan/1 authoring (the ADR-005 templates are retired)
 dz workflow-lint     <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   # 17-rule deterministic gate; exit 0/1/3 — inconclusive is never a pass
 dz workflow-trace    <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]   # timeline + SEQ invariant runner over the loop's own trace.jsonl
+dz workflow-trace export <run> --o <file> [--include-pairs --yes] [--strict]   # one run's telemetry as ONE movable file
+dz workflow-trace import <bundle> --into <root> [--force] [--with-pairs]       # reconstruct that run; fail-closed against clobbering
 dz plugin            [--version <ver>]
 dz downloads
 dz migrate           [--project <dir>]
@@ -1336,6 +1491,13 @@ exits 1 rather than silently weakening panel arbitration. It is load-bearing in
   24 h. Use `--project <dir>` to pin the panel to a specific project root.
 
 ### Usage estimate (`dz usage`)
+> **Pin the weekly reset to an ABSOLUTE instant.** `weeklyResetAnchor: "Wed 08:59"` is
+> server-timezone-relative — measured: the same moment lands a week apart under UTC vs `+03:00`, so
+> after a real account reset the counter can keep showing the OLD week for hours while printing the
+> "correct" clock time. Add your offset: `"Wed 08:59 +03:00"` in `.dz/config.json` — the boundary
+> then never moves with the machine's timezone, and `dz usage` prints the full anchor
+> (`resets Wed 08:59 +03:00`). Without an offset it warns on every run.
+
 
 `dz usage` prints a READONLY, never-throw ESTIMATE of Claude SESSION and WEEKLY token usage,
 aggregated from your local `~/.claude/projects/**/*.jsonl` transcripts. Weekly counts start at the
@@ -1713,6 +1875,27 @@ dz backlog ship 268d3cb1 --reason "shipped in harness-core 0.3.151"
 #   → dz backlog ship: 268d3cb1… new → shipped  add a compounding metric …
 #   (shipping an already-shipped idea is a SAID no-op, exit 0 — safe in cleanup batches)
 dz backlog drop 9286f5eb --reason "superseded by 268d3cb1"    # retire without shipping (→ dropped)
+dz backlog edit 9286f5eb --text "corrected wording"           # rewrite ONE idea's text; every other field
+
+# feed the learned auto-cost routing from REAL run telemetry, then read its advice
+dz routing recommend                # per-stage args.models suggestion, printed WITH its basis:
+                                    # n runs, the time window, the grade-floor rule (success ⇔ QE grade ≥ B,
+                                    # attributed run-level — an inference, and it says so), and every skipped
+                                    # record with WHY. qe is FORCED to the cross-family of the code pick —
+                                    # a same-family qe recommendation is unrepresentable, not filtered.
+dz routing recommend --apply        # feed the samples into .dz/routing-outcomes.json (the store the
+                                    # `auto-cost` plan spec reads) — idempotent by runId: a second apply
+                                    # feeds 0 and names the skipped runs. Insufficient data is SAID
+                                    # (cold-start pick + escalation chain), never dressed as a bar-met pick.
+                                                              # (status, effort, goal, uses…) is preserved byte-for-byte,
+                                                              # the previous text lands in .dz/backlog/edits.jsonl, and the
+                                                              # dedup vector is re-embedded in the same bounded form.
+                                                              # If the re-embed FAILS the edit still lands, exits 1, and the
+                                                              # record is MARKED embedStale — dedup then refuses to trust its
+                                                              # similarity (exact-text identity still applies) until
+                                                              # `dz vector reindex` repairs it. The guard sits where the harm
+                                                              # would be (the future duplicate verdict), not in a warning
+                                                              # nobody re-reads. --append adds instead of replacing; --dry-run previews.
 dz backlog reopen 268d3cb1                                    # changed your mind → back to the pool (new)
 #   reopen on an already-new idea is REFUSED (exit 1) — that is almost always the wrong id.
 #   Terminal→terminal never happens silently: ship on a dropped idea (or drop on shipped) is refused;
@@ -3222,7 +3405,7 @@ npx @dzhechkov/p-replicator init
 
 ## Status
 
-`v0.4.2` — published on npm. Also available as [Claude Plugin](#claude-plugin). Part of [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub).
+`v0.4.4` — 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;AAkbH,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;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;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;AAyyQ9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAoK5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAocH,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;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;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;AA0lR9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAoK5E"}