@dzhechkov/harness-cli 0.4.4 → 0.4.6

package/.dz-manifest.json

@@ -69,7 +69,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "5bd26341b4a5885c116432bf621b7fdb4172b2604db47ad3c1c001deb4fe6ed4"
+        "sha256": "00a53276d145112e3c2ae5ca2950ac74877ea4b069b2b81040d49c5903eb6482"
       },
       {
         "path": "src/bin.ts",
@@ -221,5 +221,5 @@
       }
     ]
   },
-  "signature": "dzYono+I+DXsxk1h8k2DAiNYKHmdzhwaUMDvvfFjCqzVFvYZecPnJQCLgT8i5NrpkaOQl2mbwU8bd3tyxQueDg=="
+  "signature": "6IQyjN4aazsr6EyD1+y/VrZ1+bclvxc9nXsCLR3WVDomAn6AhNtlTJQWdfbvw49A4/HH+KTW+KkJlj/gFFnqCw=="
 }

package/README.md

@@ -1027,7 +1027,7 @@ Each pack is an npm package — click through for the **full per-skill documenta
 | [@dzhechkov/skills-qe](https://www.npmjs.com/package/@dzhechkov/skills-qe) | 20 | Quality engineering — test-gen, coverage, chaos, defect intelligence, QCSD swarms |
 | [@dzhechkov/skills-reasoning](https://www.npmjs.com/package/@dzhechkov/skills-reasoning) | 4 | Generic reasoning & code-quality — investigate (root-cause), solid (SOLID/TDD), karpathy-guidelines, agents-md-creator |
 | [@dzhechkov/skills-ecc](https://www.npmjs.com/package/@dzhechkov/skills-ecc) | 20 | Claude-Code engineering craft — agent architecture, autonomous loops, framework patterns |
-| [@dzhechkov/skills-meta](https://www.npmjs.com/package/@dzhechkov/skills-meta) | 18 | Dev-process meta skills — explore, feature-adr, design-thinking, audit, skill-advisor |
+| [@dzhechkov/skills-meta](https://www.npmjs.com/package/@dzhechkov/skills-meta) | 19 | Dev-process meta skills — explore, feature-adr, design-thinking, audit, skill-advisor, loop-plan-author |
 | [@dzhechkov/skills-academic](https://www.npmjs.com/package/@dzhechkov/skills-academic) | 5 | Thesis-defense toolkit — dissertation review, questions, doc-check, defense eval |
 | [@dzhechkov/skills-news](https://www.npmjs.com/package/@dzhechkov/skills-news) | 3 | *dz-original* — news digests (`news-digest`) + delta watches (`news-monitor`) + bundled `goap-research-ed25519` verified-research backend (mandatory) |
 | [@dzhechkov/skills-idea2prd](https://www.npmjs.com/package/@dzhechkov/skills-idea2prd) | 1 | *dz-original* — `idea2prd-manual`: idea/problem → PRD+ADR+DDD+C4+Pseudocode+Tests+Completion (9 checkpoints); bundles the analyst trio as a sources.json-tracked vendor ([ADR-0001](https://github.com/djd1m/dz-harness-hub/blob/main/docs/adr/0001-skill-canonicalization-and-dependency-model.md)) |
@@ -1097,7 +1097,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 Custom loops used to be born by copy-pasting a 1470-line workflow script; nothing deterministic
 checked the copy. The loop-designer meta-factory replaces that: a versioned typed plan
-(`loop-plan/1`), a schema-driven generator, a 17-rule lint gate, and a local trace plane.
+(`loop-plan/1`), a schema-driven generator, an 18-rule lint gate, and a local trace plane.
 
 ```bash
 # 1. Scaffold a plan (pipeline | barrier | fanout | gate), edit the TODO prompts:
@@ -1116,7 +1116,7 @@ dz workflow render triage-loop.plan.json --o triage-loop.js
 
 # 4. Gate it (generated-loop CI mode; exit 0/1/3 — inconclusive is NEVER a pass):
 dz workflow-lint triage-loop.js --plan triage-loop.plan.json --require-plan
-# → dz workflow-lint: PASS (mode=require-plan; 0 fail, 0 warn, 0 inconclusive over 17 rules)
+# → dz workflow-lint: PASS (mode=require-plan; 0 fail, 0 warn, 0 inconclusive over 18 rules)
 
 # 5. Run it via Workflow({scriptPath:'triage-loop.js', args:{traceDir:'/abs/run-dir'}}), then read
 #    the run's own trace (seq-ordered; wallTime is diagnostic only):
@@ -1141,12 +1141,16 @@ 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
+### Build a loop for YOUR scenario — the end-to-end use case (a real one)
 
-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.
+This walkthrough is not an invented example. It is the loop that closed a real roadmap item in this
+very repo: a test pinned `34 canonical packages` while the workspace had grown past 50 directories —
+red forever, and nobody trusted a hand count. The job: produce a **verified inventory** of every
+directory under `packages/@dzhechkov` (canonical vs private vs not-a-package), too much for one
+sitting → an audit fanout: package chunks audited in parallel lanes, one synthesis, and a quality
+gate that rejects an inventory that doesn't cover every directory. Every command and output below is
+a capture from the run that actually fixed the test (MEASURED — reproducer
+`node --test tests/canonical-packages.test.mjs`: 289 pass / 0 fail after the re-pin).
 
 **Install (once):**
 
@@ -1162,8 +1166,8 @@ RUNS one. Execution belongs to a host with the `Workflow({scriptPath})` runtime,
 #### 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)
+dz workflow init --name pkg-inventory-audit --pattern fanout --o audit.plan.json
+# → wrote audit.plan.json (pattern: fanout)
 # → Next: edit the TODO prompts, then `dz workflow validate` + `dz workflow render`.
 ```
 
@@ -1173,14 +1177,20 @@ 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:
+Fill the `TODO` prompts, name your work units in `fanouts[].registry`, and add the quality gate
+with a redo route. The real plan's shape (abridged from
+`features/pkg-inventory-audit/audit.plan.json` in this repo):
 
 ```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 } ]
+"fanouts": [ { "stage": "fan", "chain": ["lane"], "maxFanout": 3,
+               "registry": ["chunk-1","chunk-2","chunk-3","chunk-4","chunk-5","chunk-6"] } ],
+"joins":   [ { "stage": "jn", "forStage": "fan", "joinPolicy": "all-activated",
+               "onInvalid": "named-failure" } ],
+"steps":   [ …lanes…, { "stepId": "synthesize", "kind": "agent", "deps": ["jn"],
+                        "prompt": "Merge the lane JSONs into one inventory. Return STRICT JSON…" },
+             { "stepId": "check", "kind": "gate", "deps": ["synthesize"],
+               "prompt": "…counts.total must equal 52… answer GATE: PASS or GATE: FAIL" } ],
+"gates":   [ { "stepId": "check", "kind": "quality", "failRoute": "synthesize", "maxRedos": 1 } ]
 ```
 
 The plan surface is deliberately NARROW and fully enacted: anything the generated loop would not
@@ -1190,34 +1200,87 @@ 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 validate audit.plan.json
+# → dz workflow validate: OK (digest sha256:70992d9ddc86de15…)
 
-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 render audit.plan.json --o audit.loop.js
+# → wrote audit.loop.plan.json then audit.loop.js (exec-fp sha256:49feb8a2c1e17038…, 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)
+dz workflow-lint audit.loop.js --plan audit.loop.plan.json --require-plan
+# → dz workflow-lint: PASS (mode=require-plan; 0 fail, 1 warn, 0 inconclusive over 18 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)
+#### Declare each step's tool perimeter — `LoopStep.tools`
 
-In **Claude Code**, paste exactly this:
+**When to use it:** any loop whose steps reach external systems (a ticket tracker, a wiki, a repo
+host) through MCP, and you want the intended perimeter written down, well-formed, and gated rather
+than living in a prompt someone will edit.
 
-> Запусти мой цикл: `Workflow({ scriptPath: 'digest.loop.js', args: { items: ["acme","globex","initech"], traceDir: '<run dir>', runId: 'digest-2026-08-18' } })` — и когда закончит, покажи `dz workflow-trace` по этому прогону.
+```jsonc
+// in your plan.json — one array per DISPATCHING step (agent | gate)
+{"stepId":"discovery","kind":"agent","phase":"Discovery",
+ "tools":["gitlab:read","jira:read","wiki:read"],  "budget":{"maxAgents":1}},
+{"stepId":"verdict-gate","kind":"gate","phase":"Discovery","deps":["discovery"],
+ "tools":[],                                        "budget":{"maxAgents":1}}
+```
 
-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:
+`tools: []` is the **meaningful** value for a step that touches no external tool — absence is a lint
+finding, because silence is never permission:
 
 ```bash
-dz workflow-trace <runDir> --html report.html   # timeline + SEQ invariants over the loop's own trace
+dz workflow-lint my-loop.js --plan my-loop.plan.json --require-plan
+# → FAIL  tool-perimeter-declared: dispatching step sa declares no `tools` perimeter — absence
+#         FLAGS: silence is never permission (declare `tools: []` if the step touches no external tool)
+```
+
+A non-empty array is **enacted**, not decorative: it renders a fixed contract line into that step's
+prompt, and the lint rule cross-checks the script against the plan (so a plan edit you forgot to
+re-render fails too). Severity is staged — **WARN by default, FAIL only under `--require-plan`.**
+
+**It is a DECLARATION, not enforcement.** `agent()` exposes no tool restriction; real enforcement
+lives at the MCP server. Do not read this field as a sandbox.
+
+Worked consumer in this repo: `.claude/workflows/cfr-pipeline.js` — a 12-step, 6-gate Customer
+Feature Request pipeline with seven typed terminal exits, whose five source-touching stages each
+declare their perimeter (`features/cfr-pipeline/`).
+
+#### Step 4 — run it (Claude Code), read it back (anywhere)
+
+In **Claude Code**, paste exactly this shape:
+
+> Запусти мой цикл: `Workflow({ scriptPath: 'audit.loop.js', args: { traceDir: '.dz/loop-trace/pkg-audit-1', runId: 'pkg-audit-1' } })` — и когда закончит, покажи `dz workflow-trace --run pkg-audit-1`.
+
+What the real run produced (captured verbatim; the trace lives at `.dz/loop-trace/pkg-audit-1/` in
+this repo):
+
+```
+run pkg-audit-1; sources: trace, ledger
+      1  run.opened  plan=70992d9ddc86 exec-fp=49feb8a2c1e1
+      2  dispatch lane:chunk-1#1  phase=Lanes
+      3  dispatch lane:chunk-2#1  phase=Lanes
+      4  dispatch lane:chunk-3#1  phase=Lanes
+      5..7  settle lane:chunk-{1,2,3}  outcome=ok
+      8  dispatch synthesize#1  phase=Synthesize
+      9  settle synthesize#4  outcome=ok
+     10  dispatch check#1  phase=Gate causedBy=[9]
+     11  settle check#5  outcome=ok        ← GATE: PASS
+     12  run.closed  {"dispatched":5,"settled":5}
 ```
 
+The gate passed, the inventory (52 directories = 49 canonical + 2 private + 1 non-package) was
+cross-checked deterministically against the filesystem, and the stale test was re-pinned to it.
+
+**And the run surfaced a real defect — kept here on purpose.** Read the trace again: the registry
+names six chunks, but only `chunk-1..3` ever dispatched — `maxFanout: 3` **silently truncated** the
+other three lanes, and the run stayed green only because the synthesize agent noticed the gap and
+audited the missing chunks with its own tools. That is exactly what the trace is for: it shows what
+your loop *did*, not what the plan promised. (Filed in this repo's backlog: over-registry items must
+become a named failure or a loud trace event, never a silent drop. Until then: keep
+`fanouts[].registry.length ≤ maxFanout`, and read the trace after the first run of any new plan.)
+
 #### 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):
@@ -1396,7 +1459,7 @@ dz drift-check       [--all] [--json] [--project <dir>]   # CI gate: exit 1 on N
 dz sync-canonical    <skill> [--check] [--from <dir>] [--auto] [--project <dir>]   # heal every copy from skills-meta/<skill> or --from; no canonical + --check = compare copies to each other (exit 1 on drift); no canonical + write = refuse unless --auto (LOUD, picks most-complete copy); --check writes nothing
 dz scout             [--topics <list>] [--since <date>] [--deep] [--output <file>] [--diff] [--report]
 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-lint     <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   # 18-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
@@ -1411,6 +1474,44 @@ dz import-ecc       [--local-path <dir>] [--select id,id,...] [--limit N] [--out
 dz help
 ```
 
+## Global: `dz --version` / `-v` / `dz version`
+
+```bash
+dz --version          # 0.4.6
+dz --version --json   # {"name":"dz","version":"0.4.6","node":"v22.22.0","schemas":{"loopPlan":"loop-plan/1"}}
+```
+
+One line, exit 0. Unresolvable ⇒ the literal `unknown` and exit **1** — never a fabricated number,
+and never a zero exit for "I could not tell you".
+
+This is a pre-dispatch GLOBAL FLAG, not a 67th command: the count above is unchanged, and a test
+derives it from the rendered `dz --help` command list so a reformat cannot move it silently.
+
+**Why it exists.** `dz --version` used to print the entire USAGE manual and exit 0 (MEASURED
+2026-08-17 on 0.4.5 — reproducer: `node dist/bin.js --version` before this change). Any wrapper
+guarding a version range — `@dzhechkov/loop-designer-plugin` is the first — would read exit 0 as "it
+answered me" while finding no version to parse, and then call a possibly-stale binary. Recognised
+only as the FIRST argument, so a later positional `-v` still belongs to its subcommand.
+
+## `dz skills-verify` also sees SLASH COMMANDS now
+
+```bash
+# does a plugin's skill AND its five commands actually register?
+dz skills-verify --dir /tmp/probe --plugin-dir packages/@dzhechkov/loop-designer-plugin \
+  --expect loop-designer:loop-plan-author \
+  --expect-commands loop-designer:init,loop-designer:validate,loop-designer:render,loop-designer:lint,loop-designer:trace
+```
+
+- `--plugin-dir <dir>` loads a plugin into the probe session (session-scoped, no marketplace). With
+  no `--expect-commands`, the expectation DEFAULTS to the manifest's own `commands[]`; an unreadable
+  manifest is refused rather than defaulted to an empty (vacuously passing) expectation.
+- `--expect-commands a,b` names the slash commands that must appear in the authoritative listing.
+- An **absent** `slash_commands` key is `inconclusive`, never an empty list — schema drift and "your
+  commands did not load" are different facts and must not be collapsed.
+- `--static` now also PRINTS its advisories. A `.claude-plugin/plugin.json` under `.claude/skills/`
+  previously produced `no layout problems found` and nothing else; the shape most likely to be a
+  silent non-registration was invisible in the mode CI runs. It is reported, and still never fatal.
+
 ### Grounding: three tiers + the token trade-off (`dz brain ground` / `dz brain expand`)
 
 The `dz brain ground` hook fires on **every turn**, so what it injects is a token trade-off. There are
@@ -3405,7 +3506,9 @@ npx @dzhechkov/p-replicator init
 
 ## Status
 
-`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).
+`v0.4.6` — published on npm. Also available as [Claude Plugin](#claude-plugin). Part of [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub).
+
+New in this change: the global `dz --version` / `-v` / `dz version` surface (one parseable line), and `dz skills-verify --plugin-dir` / `--expect-commands` so slash-command registration is gate-visible. Both exist for `@dzhechkov/loop-designer-plugin`, which requires `dz` in `^0.4`, verifies it at run time, and falls back to `npx -y @dzhechkov/harness-cli@^0.4` when the `dz` on PATH is stale, unparseable or missing.
 
 ## 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;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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAucH,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;AA4oR9E,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwL5E"}

package/dist/cli.js

@@ -12,7 +12,7 @@ import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 import { createSkill, getSkillInfo, isTargetName, listSkills, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
 // guard-promotion (feature guard-promotion, scout idea #1)
-assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, harvestStageOutcomes, recommendModels, planFeed, GRADE_SUCCESS_FLOOR, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
+assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, harvestStageOutcomes, recommendModels, planFeed, GRADE_SUCCESS_FLOOR, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, declaredPluginSurface, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
@@ -119,6 +119,8 @@ Usage:
   dz import-ecc [--local-path <dir>] [--select id,id,...] [--limit N] [--output <dir>] [--force]
   dz help
 
+Global: --version | -v [--json]   (prints this CLI's own semver on one line, exit 0; "unknown" + exit 1 when unresolvable)
+
 Workflows: author loop-plan/1 plans with dz workflow init/validate/render; gate them with dz workflow-lint; read runs with dz workflow-trace (the ADR-005 templates are retired)
 
 Targets: ${TARGET_NAMES.join(', ')}
@@ -529,8 +531,8 @@ function workflowInitPlan(name, pattern) {
             ...base,
             steps: [
                 { stepId: 'fan', kind: 'fanout', phase: 'Work', concurrency: 'pipeline', budget: { maxAgents: 8 } },
-                { stepId: 'a', kind: 'agent', phase: 'Work', prompt: 'TODO: stage A per item', budget: { maxAgents: 4 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
-                { stepId: 'b', kind: 'agent', phase: 'Work', prompt: 'TODO: stage B per item', budget: { maxAgents: 4 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'a', kind: 'agent', phase: 'Work', prompt: 'TODO: stage A per item', budget: { maxAgents: 4 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'b', kind: 'agent', phase: 'Work', prompt: 'TODO: stage B per item', budget: { maxAgents: 4 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
                 { stepId: 'jn', kind: 'join', phase: 'Work', deps: ['fan'] },
             ],
             fanouts: [{ stage: 'fan', registry: ['item1', 'item2', 'item3'], maxFanout: 3, chain: ['a', 'b'] }],
@@ -542,10 +544,10 @@ function workflowInitPlan(name, pattern) {
             ...base,
             steps: [
                 { stepId: 'fan', kind: 'fanout', phase: 'Lanes', concurrency: 'barrier', budget: { maxAgents: 6 } },
-                { stepId: 'lane', kind: 'agent', phase: 'Lanes', prompt: 'TODO: one lane', budget: { maxAgents: 6 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'lane', kind: 'agent', phase: 'Lanes', prompt: 'TODO: one lane', budget: { maxAgents: 6 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
                 { stepId: 'jn', kind: 'join', phase: 'Lanes', deps: ['fan'] },
                 // the consumer hangs off the BARRIER (jn), never the fork — barrier-postdominates teaches this
-                { stepId: 'synthesize', kind: 'agent', phase: 'Synthesize', deps: ['jn'], prompt: 'TODO: synthesize across lanes', budget: { maxAgents: 1 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'synthesize', kind: 'agent', phase: 'Synthesize', deps: ['jn'], prompt: 'TODO: synthesize across lanes', budget: { maxAgents: 1 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
             ],
             fanouts: [{ stage: 'fan', registry: ['lane1', 'lane2', 'lane3'], maxFanout: 3, chain: ['lane'] }],
             joins: [{ stage: 'jn', forStage: 'fan', joinPolicy: 'all-activated', onInvalid: 'named-failure' }],
@@ -555,8 +557,8 @@ function workflowInitPlan(name, pattern) {
         return {
             ...base,
             steps: [
-                { stepId: 'work', kind: 'agent', phase: 'Work', prompt: 'TODO: produce the artifact', budget: { maxAgents: 2 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
-                { stepId: 'gate', kind: 'gate', phase: 'Gate', deps: ['work'], prompt: 'TODO: gate check (parse the verdict, never synthesize one)', budget: { maxAgents: 1 } }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'work', kind: 'agent', phase: 'Work', prompt: 'TODO: produce the artifact', budget: { maxAgents: 2 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+                { stepId: 'gate', kind: 'gate', phase: 'Gate', deps: ['work'], prompt: 'TODO: gate check (parse the verdict, never synthesize one)', budget: { maxAgents: 1 }, tools: [] }, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
             ],
             gates: [{ stepId: 'gate', kind: 'parse-verdict', failRoute: 'work', maxRedos: 1 }],
         };
@@ -564,7 +566,7 @@ function workflowInitPlan(name, pattern) {
     // minimal default: one agent step
     return {
         ...base,
-        steps: [{ stepId: 'main', kind: 'agent', phase: 'Work', prompt: 'TODO: the one step', budget: { maxAgents: 1 } }], // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+        steps: [{ stepId: 'main', kind: 'agent', phase: 'Work', prompt: 'TODO: the one step', budget: { maxAgents: 1 }, tools: [] }], // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
     };
 }
 /**
@@ -762,8 +764,12 @@ function cmdWorkflowLint(options, flags, cwd, write) {
 /** `dz workflow-trace` — timeline + invariant runner over a run's trace.jsonl. Scope is CAPPED
  * (AM-8): <runDir|--slug|--run>, --invariants, --html, --json. NO watch/filter/compare/search/
  * retention/access-control — adding one needs an ADR amendment (the surface test pins this). */
-/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
-function traceBundleToolVersion() {
+/**
+ * This CLI's OWN semver, read from its package.json. `unknown` is honest; a throw is not, and an
+ * invented number is worse than either — a downstream version guard that is handed a fabricated
+ * version happily calls a binary it should have refused.
+ */
+function dzOwnVersion() {
     try {
         const req = createRequire(import.meta.url);
         const pkg = req('../package.json');
@@ -773,6 +779,10 @@ function traceBundleToolVersion() {
         return 'unknown';
     }
 }
+/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
+function traceBundleToolVersion() {
+    return dzOwnVersion();
+}
 /** Resolve a run the SAME three ways the timeline reader does — positional, --slug, --run — so a
  * bundle can never address a run by a scheme the rest of the command does not understand. */
 function resolveTraceRun(options, cwd, positional) {
@@ -7926,7 +7936,7 @@ const PROBE_SCRUB_ENV = [
  * lands, then kill it — the model never answers, so the probe costs ~no tokens. Never throws:
  * every failure becomes an `error` string, which the pure classifier turns into `inconclusive`.
  */
-function probeInitStream(projectDir, timeoutMs) {
+function probeInitStream(projectDir, timeoutMs, pluginDir = null) {
     return new Promise((resolveProbe) => {
         const env = { ...process.env };
         for (const key of PROBE_SCRUB_ENV)
@@ -7952,7 +7962,13 @@ function probeInitStream(projectDir, timeoutMs) {
         const timer = setTimeout(() => finish(`no init event within ${Math.round(timeoutMs / 1000)}s (is \`claude\` logged in?)`), timeoutMs);
         try {
             // NOT `--bare`: that mode skips plugin credentials and fails with "Not logged in".
-            child = spawn('claude', ['-p', 'ok', '--output-format', 'stream-json', '--verbose'], {
+            const args = ['-p', 'ok', '--output-format', 'stream-json', '--verbose'];
+            // Session-scoped plugin load — the marketplace-free vehicle (ADR-003 D-3). Without this the
+            // probe reads a session in which the plugin was never loaded, and reports its commands
+            // missing for a reason that has nothing to do with the package under test.
+            if (pluginDir !== null)
+                args.push('--plugin-dir', pluginDir);
+            child = spawn('claude', args, {
                 cwd: projectDir,
                 env,
                 stdio: ['ignore', 'pipe', 'pipe'],
@@ -8026,8 +8042,11 @@ function probeContent(projectDir, prompt, timeoutMs) {
 async function cmdSkillsVerify(options, flags, cwd, write) {
     const json = flags.has('json');
     if (flags.has('help')) {
-        write('dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--timeout <s>] [--json]');
+        write('dz skills-verify [--dir <project>] [--expect a,b] [--expect-commands a,b] [--plugin-dir <dir>] [--static] [--strict] [--timeout <s>] [--json]');
         write('  Verifies that a project\'s .claude/skills/ actually register in Claude Code.');
+        write('  --plugin-dir <dir>  load a plugin into the probe session (session-scoped, no marketplace);');
+        write('                      with no --expect-commands, the expectation defaults to the manifest\'s own commands[]');
+        write('  --expect-commands   slash commands that MUST appear in the session listing, e.g. loop-designer:init');
         write('  --static  layout scan only (no Claude session, CI-safe): flags dirs that can never register');
         write('  --live-content  ADVISORY extra turn: ask a live model to name the skills and quote one, proving');
         write('                  the CONTENT is usable — registration is not usability. Never changes the exit code.');
@@ -8036,8 +8055,8 @@ async function cmdSkillsVerify(options, flags, cwd, write) {
         return 0;
     }
     const allowedFlags = new Set(['json', 'help', 'static', 'strict', 'live-content']);
-    const allowedOptions = new Set(['dir', 'expect', 'timeout']);
-    const usage = '  allowed: --dir <project>, --expect a,b, --timeout <s>, --static, --strict, --live-content, --json';
+    const allowedOptions = new Set(['dir', 'expect', 'expect-commands', 'plugin-dir', 'timeout']);
+    const usage = '  allowed: --dir <project>, --expect a,b, --expect-commands a,b, --plugin-dir <dir>, --timeout <s>, --static, --strict, --live-content, --json';
     if (options.has('_positional_0')) {
         const message = `unexpected argument "${options.get('_positional_0')}"`;
         write(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz skills-verify: ${message}\n${usage}`);
@@ -8065,6 +8084,27 @@ async function cmdSkillsVerify(options, flags, cwd, write) {
             .map((s) => s.trim())
             .filter(Boolean)
         : scan.registrable;
+    // A plugin loaded with `--plugin-dir` is session-scoped, so its surface is NOT on the project's
+    // disk and `scan.registrable` cannot describe it. The manifest can — and defaulting to the
+    // manifest's own `commands[]` keeps the gate honest without a hand-typed list that silently
+    // drifts from the manifest it is supposed to be checking. An UNREADABLE manifest is refused
+    // rather than defaulted to an empty expectation: an empty expectation passes without checking.
+    const pluginDir = options.has('plugin-dir') ? resolve(cwd, options.get('plugin-dir') ?? '') : null;
+    let expectedCommands = options.has('expect-commands')
+        ? (options.get('expect-commands') ?? '')
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+    if (pluginDir !== null && !options.has('expect-commands')) {
+        const surface = declaredPluginSurface(pluginDir);
+        if (surface === null) {
+            const message = `cannot read ${join(pluginDir, '.claude-plugin', 'plugin.json')} (or it declares no name) — pass --expect-commands explicitly`;
+            write(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz skills-verify: ${message}`);
+            return 1;
+        }
+        expectedCommands = surface.commands;
+    }
     // ── L1 only: deterministic, no session, safe for CI ──
     if (flags.has('static')) {
         const exitCode = scan.findings.length > 0 ? 1 : 0;
@@ -8078,6 +8118,12 @@ async function cmdSkillsVerify(options, flags, cwd, write) {
             for (const f of scan.findings)
                 write(`  [${f.kind}] ${f.detail}`);
             write(scan.findings.length ? `  ${scan.findings.length} layout problem(s) — these can never register` : '  no layout problems found');
+            // Advisories were collected but never PRINTED in static mode: a `.claude-plugin/plugin.json`
+            // under `.claude/skills` produced "no layout problems found" and nothing else, so the one
+            // shape most likely to be a silent non-registration was invisible in exactly the mode CI and
+            // humans run most. Reported, still never fatal (that distinction is the whole point).
+            for (const a of scan.advisories)
+                write(`  [${a.kind}] ADVISORY: ${a.detail}`);
             write('  (static is a PROXY — run without --static to read the real registration listing)');
         }
         return exitCode;
@@ -8087,7 +8133,7 @@ async function cmdSkillsVerify(options, flags, cwd, write) {
     const timeoutMs = Number.isFinite(timeoutSec) && timeoutSec > 0 ? timeoutSec * 1000 : 180_000;
     if (!json)
         write(`dz skills-verify: starting a session in ${projectDir} to read the real registration listing…`);
-    const { stream, error } = await probeInitStream(projectDir, timeoutMs);
+    const { stream, error } = await probeInitStream(projectDir, timeoutMs, pluginDir);
     // `init.skills` carries names, not provenance: a USER-level skill of the same name would satisfy
     // the expectation while the project's own copy stays broken. Collect the collisions so the
     // classifier can refuse to attribute registration to this project (Codex QE #2).
@@ -8109,6 +8155,7 @@ async function cmdSkillsVerify(options, flags, cwd, write) {
         // The provenance check RAN (that is what `checked: true` asserts) — see `ambiguous` above.
         provenance: { checked: true, ambiguous },
         ...(options.has('expect') ? { expected } : {}),
+        ...(expectedCommands.length > 0 ? { expectedCommands } : {}),
     }, { resolvePath: canonical });
     const exitCode = registrationExitCode(result.verdict, flags.has('strict'));
     // ADVISORY layer: registration is not usability. Costs a real model turn, so it is opt-in, and it
@@ -9164,6 +9211,26 @@ export async function runCli(argv, io = {}) {
         }
     };
     const { command, options, optionLists, flags } = parseArgs(argv);
+    // ── `dz --version` / `dz -v` / `dz version` — PRE-DISPATCH, before the help branch ──
+    //
+    // Until now `dz --version` printed the whole USAGE manual and exited 0 (MEASURED 2026-08-17,
+    // reproducer `node dist/bin.js --version`). Exit 0 plus prose is the worst possible answer for a
+    // caller that must decide whether a `dz` it found on PATH is safe to invoke: the status code says
+    // "fine" and there is no number to parse. Any wrapper guarding a version range needs exactly one
+    // parseable line. Recognised only as the FIRST token (or the `version` subcommand) so that a
+    // later positional `-v` belonging to a subcommand keeps its own meaning.
+    if (argv[0] === '--version' || argv[0] === '-v' || command === 'version') {
+        const version = dzOwnVersion();
+        if (flags.has('json')) {
+            write(JSON.stringify({ name: 'dz', version, node: process.version, schemas: { loopPlan: 'loop-plan/1' } }));
+        }
+        else {
+            write(version);
+        }
+        // An unresolvable version is a FAILURE, not a value: exiting 0 with the literal `unknown` would
+        // let a guard treat "I could not tell you" as "I answered you".
+        return version === 'unknown' ? 1 : 0;
+    }
     if (command === '' || command === 'help' || flags.has('help')) {
         write(USAGE);
         return 0;