@dzhechkov/harness-cli 0.4.3 → 0.4.4

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "532051106b153c0d9bb7ad2abbeb71d418f88f1bc88e60a35e29cf42162af243"
+        "sha256": "2f053f11ea49780919d0557877302e70adb8f33949299b0b0637ece2809c1b67"
       },
       {
         "path": "coverage/coverage-final.json",
@@ -69,7 +69,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "4a164e5ac53ceec178463c1bdab9f80c1755311d5e4202c1f6234ca22c473b37"
+        "sha256": "5bd26341b4a5885c116432bf621b7fdb4172b2604db47ad3c1c001deb4fe6ed4"
       },
       {
         "path": "src/bin.ts",
@@ -221,5 +221,5 @@
       }
     ]
   },
-  "signature": "wIo2tChkUqPT1qEHFeLlgbuzL29rRhhpVer4yaDmeuq7CsvdMeYN2QcttC496DwlepKeZ1EE3h2sSoY5w16qAA=="
+  "signature": "dzYono+I+DXsxk1h8k2DAiNYKHmdzhwaUMDvvfFjCqzVFvYZecPnJQCLgT8i5NrpkaOQl2mbwU8bd3tyxQueDg=="
 }

package/README.md

@@ -1141,6 +1141,108 @@ 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
@@ -3303,7 +3405,7 @@ npx @dzhechkov/p-replicator init
 
 ## Status
 
-`v0.4.3` — 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "532051106b153c0d9bb7ad2abbeb71d418f88f1bc88e60a35e29cf42162af243"
+          "content": "2f053f11ea49780919d0557877302e70adb8f33949299b0b0637ece2809c1b67"
         }
       ]
     },
@@ -175,7 +175,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4a164e5ac53ceec178463c1bdab9f80c1755311d5e4202c1f6234ca22c473b37"
+          "content": "5bd26341b4a5885c116432bf621b7fdb4172b2604db47ad3c1c001deb4fe6ed4"
         }
       ]
     },