@dzhechkov/harness-cli 0.4.5 → 0.4.6

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):
@@ -1207,12 +1207,46 @@ 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 audit.loop.js --plan audit.loop.plan.json --require-plan
-# → dz workflow-lint: PASS (mode=require-plan; 0 fail, 1 warn, 0 inconclusive over 17 rules)
+# → 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).
 
+#### Declare each step's tool perimeter — `LoopStep.tools`
+
+**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.
+
+```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}}
+```
+
+`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-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:
@@ -1425,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
@@ -1440,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
@@ -3434,7 +3506,9 @@ npx @dzhechkov/p-replicator init
 
 ## Status
 
-`v0.4.5` — 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;