@dzhechkov/harness-cli 0.4.5 → 0.5.0

package/dist/cli.js

@@ -10,9 +10,9 @@ import { execFileSync, execSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 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, 
+import { createSkill, getSkillInfo, listSkillsDetailed, formatSkillLoadFailures, formatSkillApplyFailures, resolveTargetName, formatTargetProblem, formatTargetAliasNote, TARGET_NAMES_SORTED, 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, runSyncAgentsPolicy, runSyncCodexHooks, POLICY_SOURCES, detectPolicyDrift, hasPolicyFence, 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, classifyExecutionEvidence, 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.
@@ -110,6 +110,8 @@ Usage:
               (build-time: reconcile project grants vs installed skills' declared capabilities; dz never enforces — the host does)
   dz sync-upstream [--package <dir>] [--list] [--all]
   dz drift-check [--json] [--project <dir>]                             (CI gate: exit 1 if any shared skill drifted between its monorepo copies)
+  dz agents-sync [--project <dir>] [--check] [--json]                   (sync/verify the always-on policy fence in root AGENTS.md; exit 0 synced/written, 1 drift, 3 inconclusive)
+  dz hooks-sync --target codex [--check] [--verify] [--remove] [--json]  (install/verify the dz veto + recall hooks in $CODEX_HOME/hooks.json; exit 0 armed+trusted, 1 not armed/drift, 3 inconclusive)
   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 plugin [--version <ver>]
   dz downloads
@@ -119,6 +121,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(', ')}
@@ -206,9 +210,11 @@ async function installSkills(opts) {
             written += s.written;
             skipped += s.skipped;
         }
-        return { results, dirsSearched: skillsDirs.length, written, skipped, missing: [...report.missing] };
+        return { results, dirsSearched: skillsDirs.length, written, skipped, missing: [...report.missing], failures: [...report.failures], applyFailures: [...report.applyFailures] };
     }
     const results = [];
+    const failures = [];
+    const applyFailures = [];
     for (const skillsDir of skillsDirs) {
         const r = await runInit({
             target,
@@ -221,6 +227,8 @@ async function installSkills(opts) {
         for (const skill of r.skills) {
             results.push({ id: skill.id, written: skill.written.length, skipped: skill.skipped.length });
         }
+        failures.push(...r.failures);
+        applyFailures.push(...r.applyFailures);
     }
     let written = 0;
     let skipped = 0;
@@ -230,7 +238,7 @@ async function installSkills(opts) {
     }
     const installed = new Set(results.map((s) => s.id));
     const missing = select !== undefined ? [...select].filter((id) => !installed.has(id)) : [];
-    return { results, dirsSearched: skillsDirs.length, written, skipped, missing };
+    return { results, dirsSearched: skillsDirs.length, written, skipped, missing, failures, applyFailures };
 }
 /** Warn about preset/select ids that weren't found in any installed pack. */
 function writeMissingSkillsHint(write, missing, presetName) {
@@ -246,12 +254,24 @@ function writeMissingSkillsHint(write, missing, presetName) {
         write(`     Install their packs first (e.g. dz install @dzhechkov/skills-<pack>) or check the ids.`);
     }
 }
-async function cmdInit(options, flags, cwd, write) {
-    const target = options.get('target');
-    if (target === undefined || !isTargetName(target)) {
-        write(`dz init: --target must be one of: ${TARGET_NAMES.join(', ')}`);
+async function cmdInit(options, flags, cwd, write, writeErr) {
+    const targetOpt = options.get('target');
+    if (targetOpt === undefined) {
+        // A missing `--target` is the same accusation as an unresolvable one, so it takes
+        // the same channel: diagnostics on stderr, stdout stays a data channel (ADR-002
+        // §Decision 2 / driver D6; fix round 1, QE F2).
+        writeErr(`dz init: --target must be one of: ${TARGET_NAMES_SORTED.join(', ')}`);
         return 1;
     }
+    const resolution = resolveTargetName(targetOpt);
+    if (resolution.kind === 'unknown') {
+        for (const line of formatTargetProblem('dz init', resolution))
+            writeErr(line);
+        return 1;
+    }
+    const target = resolution.target;
+    if (resolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz init', targetOpt, target));
     const explicitSkillsDir = options.get('skills-dir');
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const presetName = options.get('preset');
@@ -287,18 +307,48 @@ async function cmdInit(options, flags, cwd, write) {
         write(`  (searched ${r.dirsSearched} skill directories)`);
     }
     writeMissingSkillsHint(write, r.missing, presetName);
+    // Skip-and-collect must not become skip-and-SILENCE: a skill that failed to load is
+    // named on stderr and the command exits 1 (it exited 1 before too — by throwing).
+    if (r.failures.length > 0 || r.applyFailures.length > 0) {
+        // Counts first, then the named block — the same shape `dz list` uses. The block's
+        // own header already says "N skipped", so this line carries what it cannot: how many
+        // DID install, so a reader can tell a mostly-fine install from a mostly-broken one.
+        //
+        // The two failure kinds are counted and rendered SEPARATELY (fix round 1, QE F4):
+        // an unwritable target directory is not a broken pack, and printing it as one names
+        // the wrong file.
+        const parts = [`${r.results.length} installed`];
+        if (r.failures.length > 0)
+            parts.push(`${r.failures.length} skipped`);
+        if (r.applyFailures.length > 0)
+            parts.push(`${r.applyFailures.length} failed to write`);
+        writeErr(`dz init: ${parts.join(', ')}`);
+        for (const line of formatSkillLoadFailures(r.failures))
+            writeErr(line);
+        for (const line of formatSkillApplyFailures(r.applyFailures))
+            writeErr(line);
+        return 1;
+    }
     return 0;
 }
-async function cmdVerify(options, cwd, write) {
+async function cmdVerify(options, cwd, write, writeErr) {
     const skillsDir = resolve(cwd, options.get('skills-dir') ?? '.claude/skills');
     const targetOpt = options.get('target');
-    if (targetOpt !== undefined && !isTargetName(targetOpt)) {
-        write(`dz verify: --target must be one of: ${TARGET_NAMES.join(', ')}`);
-        return 1;
+    let target;
+    if (targetOpt !== undefined) {
+        const resolution = resolveTargetName(targetOpt);
+        if (resolution.kind === 'unknown') {
+            for (const line of formatTargetProblem('dz verify', resolution))
+                writeErr(line);
+            return 1;
+        }
+        target = resolution.target;
+        if (resolution.via === 'alias')
+            writeErr(formatTargetAliasNote('dz verify', targetOpt, target));
     }
     const report = await runVerify({
         skillsDir,
-        ...(targetOpt !== undefined ? { target: targetOpt } : {}),
+        ...(target !== undefined ? { target } : {}),
     });
     write(`dz verify (${report.target}): ${report.valid}/${report.total} skill(s) valid`);
     for (const skill of report.skills) {
@@ -307,7 +357,7 @@ async function cmdVerify(options, cwd, write) {
     }
     return report.valid === report.total ? 0 : 1;
 }
-async function cmdSync(options, flags, cwd, write) {
+async function cmdSync(options, flags, cwd, write, writeErr) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const canonicalArg = options.get('canonical');
     // Auto-discover all skills-* packs, or use explicit --canonical
@@ -331,6 +381,15 @@ async function cmdSync(options, flags, cwd, write) {
     });
     const { total, inSync, missing, drift } = report.summary;
     write(`dz sync${report.dryRun ? ' --dry-run' : ''}: ${inSync}/${total} in sync, ${missing} missing, ${drift} drift`);
+    // Skip-and-collect (D1): the broken canonical skills are NAMED on stderr, and their
+    // presence keeps the exit code non-zero — a partial sync is not a clean sync.
+    if (report.failures.length > 0) {
+        // See `cmdInit` above: counts here, names in the block below.
+        writeErr(`dz sync: ${report.skills.length} compared, ${report.failures.length} skipped`);
+        for (const line of formatSkillLoadFailures(report.failures))
+            writeErr(line);
+        return 1;
+    }
     return missing === 0 && drift === 0 ? 0 : 1;
 }
 function cmdCreateSkill(options, flags, cwd, write) {
@@ -372,19 +431,44 @@ function cmdCreateSkill(options, flags, cwd, write) {
     }
     return 0;
 }
-function cmdList(options, cwd, write) {
+/**
+ * `dz list` — skip-and-collect (feature dz-cli-defects, D1).
+ *
+ * One unparseable `SKILL.md` used to discard the ENTIRE listing with a message naming
+ * neither the file nor the count. Now the parseable skills list on stdout and the
+ * broken ones are named on stderr. The whole emit contract, in one place:
+ *
+ * | valid | skipped | stdout | stderr | exit |
+ * |-------|---------|--------|--------|------|
+ * | >0    | 0       | listing | *empty* | 0 |
+ * | >0    | >0      | listing of the valid ones | named summary | 1 |
+ * | 0     | >0      | *nothing* | named summary | 1 |
+ * | 0     | 0       | *nothing* | `no skills found in <dir>` | 1 |
+ *
+ * The last row is the ONE intentional departure from byte-identical output: that line
+ * used to go to stdout. Moving it keeps *stdout is data, stderr is diagnosis* whole —
+ * the invariant that makes `dz list > out.txt` trustworthy.
+ */
+function cmdList(options, cwd, write, writeErr) {
     const skillsDir = resolve(cwd, options.get('skills-dir') ?? '.claude/skills');
-    const skills = listSkills(skillsDir);
-    if (skills.length === 0) {
-        write(`dz list: no skills found in ${skillsDir}`);
+    const { skills, failures } = listSkillsDetailed(skillsDir);
+    if (skills.length === 0 && failures.length === 0) {
+        writeErr(`dz list: no skills found in ${skillsDir}`);
         return 1;
     }
-    write(`${skills.length} skill(s) in ${skillsDir}:\n`);
-    for (const skill of skills) {
-        const desc = skill.description.length > 80 ? skill.description.slice(0, 77) + '...' : skill.description;
-        write(`  ${skill.id.padEnd(35)} ${desc}`);
+    if (skills.length > 0) {
+        write(`${skills.length} skill(s) in ${skillsDir}:\n`);
+        for (const skill of skills) {
+            const desc = skill.description.length > 80 ? skill.description.slice(0, 77) + '...' : skill.description;
+            write(`  ${skill.id.padEnd(35)} ${desc}`);
+        }
     }
-    return 0;
+    if (failures.length === 0)
+        return 0;
+    writeErr(`dz list: ${skills.length} listed, ${failures.length} skipped in ${skillsDir}`);
+    for (const line of formatSkillLoadFailures(failures))
+        writeErr(line);
+    return 1;
 }
 function cmdInfo(options, args, cwd, write) {
     const skillsDir = resolve(cwd, options.get('skills-dir') ?? '.claude/skills');
@@ -529,8 +613,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 +626,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 +639,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 +648,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 +846,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 +861,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) {
@@ -1207,17 +1299,22 @@ function cmdBundle(options, flags, cwd, write) {
     }
     return 0;
 }
-async function cmdInstall(options, flags, cwd, write, installRunner) {
+async function cmdInstall(options, flags, cwd, write, writeErr, installRunner) {
     const pkg = options.get('_positional_0');
     if (!pkg) {
         write('dz install: package name required (e.g., dz install @dzhechkov/skills-devops)');
         return 1;
     }
     const targetOpt = options.get('target') ?? 'claude-code';
-    if (!isTargetName(targetOpt)) {
-        write(`dz install: --target must be one of: ${TARGET_NAMES.join(', ')}`);
+    const targetResolution = resolveTargetName(targetOpt);
+    if (targetResolution.kind === 'unknown') {
+        for (const line of formatTargetProblem('dz install', targetResolution))
+            writeErr(line);
         return 1;
     }
+    const target = targetResolution.target;
+    if (targetResolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz install', targetOpt, target));
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     // Step 1: npm install the package (installRunner is the CliIo test seam — unset in production)
     write(`Installing ${pkg}...`);
@@ -1251,7 +1348,7 @@ async function cmdInstall(options, flags, cwd, write, installRunner) {
     const root = roots[0];
     // Step 3: Use dz init with the resolved skills root as source
     const report = await runInit({
-        target: targetOpt,
+        target,
         skillsDir: root.dir,
         projectRoot,
         force: flags.has('force'),
@@ -1268,20 +1365,38 @@ async function cmdInstall(options, flags, cwd, write, installRunner) {
     if (root.layout === 'npx-template' && root.hasCompanionAssets) {
         write(`  note: ${pkg} also ships commands/hooks/agents — \`npx -y ${pkg} init\` installs the full kit.`);
     }
+    // Skip-and-collect at install time (D1 / the report's D2 amendment): the offending
+    // SKILL.md came out of the DOWNLOADED TARBALL, so the path is rendered relative to
+    // the package root (a `node_modules/**` absolute path is not actionable) and the
+    // message says whose defect it is. Exit 1 — a pack that shipped an unloadable skill
+    // did not fully install.
+    if (report.failures.length > 0) {
+        writeErr(`dz install: ${pkg} ships ${report.failures.length} unparseable skill(s) —`);
+        for (const line of formatSkillLoadFailures(report.failures, { relativeTo: pkgDir }))
+            writeErr(line);
+        writeErr('This is a defect in the package, not in your project.');
+        writeErr(`Workaround: npx -y ${pkg} init`);
+        return 1;
+    }
     return 0;
 }
-function cmdCompose(options, cwd, write) {
+function cmdCompose(options, cwd, write, writeErr) {
     const combo = options.get('_positional_0');
     if (!combo) {
         write('dz compose: preset combination required (e.g., dz compose devops+mcp+web3)');
         return 1;
     }
     // --target is documented; honor it in the suggested install command (was hardcoded claude-code).
-    const target = options.get('target') ?? 'claude-code';
-    if (!isTargetName(target)) {
-        write(`dz compose: --target must be one of: ${TARGET_NAMES.join(', ')}`);
+    const targetOpt = options.get('target') ?? 'claude-code';
+    const composeResolution = resolveTargetName(targetOpt);
+    if (composeResolution.kind === 'unknown') {
+        for (const line of formatTargetProblem('dz compose', composeResolution))
+            writeErr(line);
         return 1;
     }
+    const target = composeResolution.target;
+    if (composeResolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz compose', targetOpt, target));
     const presetNames = combo.split('+').map((s) => s.trim());
     const allSkills = new Set();
     const resolved = [];
@@ -3479,12 +3594,21 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
     write(BRAIN_USAGE);
     return sub === undefined ? 0 : 1;
 }
-async function cmdSetup(options, flags, cwd, write) {
-    const target = options.get('target');
-    if (!target || !isTargetName(target)) {
-        write(`dz setup: --target required (${TARGET_NAMES.join(', ')})`);
+async function cmdSetup(options, flags, cwd, write, writeErr) {
+    const targetOpt = options.get('target');
+    if (!targetOpt) {
+        writeErr(`dz setup: --target required (${TARGET_NAMES_SORTED.join(', ')})`);
         return 1;
     }
+    const setupResolution = resolveTargetName(targetOpt);
+    if (setupResolution.kind === 'unknown') {
+        for (const line of formatTargetProblem('dz setup', setupResolution))
+            writeErr(line);
+        return 1;
+    }
+    const target = setupResolution.target;
+    if (setupResolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz setup', targetOpt, target));
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const presetName = options.get('preset');
     write(`\n╔══════════════════════════════════════════════════════╗`);
@@ -3649,12 +3773,19 @@ function cmdRecommend(options, cwd, write) {
     write(`   Get it: dz init --target claude-code --select skill-advisor   (or --preset meta)`);
     return 0;
 }
-function cmdUpgrade(options, flags, cwd, write) {
+function cmdUpgrade(options, flags, cwd, write, writeErr) {
     const targetOpt = options.get('target') ?? 'claude-code';
-    if (!isTargetName(targetOpt)) {
-        write(`dz upgrade: --target must be one of: ${TARGET_NAMES.join(', ')}`);
+    const upgradeResolution = resolveTargetName(targetOpt);
+    if (upgradeResolution.kind === 'unknown') {
+        for (const line of formatTargetProblem('dz upgrade', upgradeResolution))
+            writeErr(line);
         return 1;
     }
+    // The dir map is keyed by the RESOLVED name — keying it by the raw `--target` would
+    // let an alias validate and then miss the map.
+    const upgradeTarget = upgradeResolution.target;
+    if (upgradeResolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz upgrade', targetOpt, upgradeTarget));
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const targetDirMap = {
         'claude-code': '.claude/skills', codex: '.agents/skills', opencode: '.opencode/skills',
@@ -3662,9 +3793,9 @@ function cmdUpgrade(options, flags, cwd, write) {
         'agents-md': 'AGENTS.md', cursor: '.cursor/rules', gemini: 'GEMINI.md',
         windsurf: '.windsurf/rules',
     };
-    const mappedDir = targetDirMap[targetOpt];
+    const mappedDir = targetDirMap[upgradeTarget];
     if (mappedDir === undefined) {
-        write(`dz upgrade: no skills directory mapping for target ${targetOpt}`);
+        write(`dz upgrade: no skills directory mapping for target ${upgradeTarget}`);
         return 1;
     }
     const targetDir = join(projectRoot, mappedDir);
@@ -3679,14 +3810,14 @@ function cmdUpgrade(options, flags, cwd, write) {
         }
     }
     const report = checkUpgrades(targetDir, canonicalDirs);
-    write(`\ndz upgrade — ${targetOpt} (${targetDir})`);
+    write(`\ndz upgrade — ${upgradeTarget} (${targetDir})`);
     write(`  Installed: ${report.installed}  Needs update: ${report.needsUpdate}  Up-to-date: ${report.upToDate}  Custom: ${report.notInCanonical}\n`);
     for (const check of report.skills) {
         const icon = check.needsUpdate ? '△' : check.canonicalSize === undefined ? '?' : '✓';
         write(`  ${icon} ${check.id.padEnd(25)} ${check.reason}`);
     }
     if (report.needsUpdate > 0) {
-        write(`\n${report.needsUpdate} skill(s) need update. Run: dz init --target ${targetOpt} --force`);
+        write(`\n${report.needsUpdate} skill(s) need update. Run: dz init --target ${upgradeTarget} --force`);
     }
     // ADR-001 (verify-apply-leg): verify what we just left on disk. A TAMPERED pack aborts.
     const sigFatal = reportPackVerification(projectRoot, options.get('pubkey'), flags.has('require-signing'), write);
@@ -4239,7 +4370,7 @@ function cmdPublish(options, flags, cwd, write) {
 /*  dz parity — the honest feature×target map (target-parity-matrix,   */
 /*  ADR-001): computed from the declarative model, never hand-written  */
 /* ------------------------------------------------------------------ */
-function cmdParity(options, flags, write) {
+function cmdParity(options, flags, write, writeErr) {
     const json = flags.has('json');
     if (flags.has('help')) {
         write('dz parity [--target <name>] [--json] — the computed feature×target map (never hand-written)');
@@ -4268,13 +4399,31 @@ function cmdParity(options, flags, write) {
         }
     }
     const matrix = buildParityMatrix();
-    const target = options.get('target');
-    if (target !== undefined && !TARGET_NAMES.includes(target)) {
-        if (json)
-            write(JSON.stringify({ error: `unknown target "${target}"`, targets: TARGET_NAMES, exitCode: 1 }, null, 2));
-        else
-            write(`dz parity: unknown target "${target}" — one of: ${TARGET_NAMES.join(', ')}`);
-        return 1;
+    // Site 8 of the D3 rewiring, closed in fix round 1 (QE F1). It shipped spelling its
+    // own bare guard `TARGET_NAMES.includes(...)` and was therefore invisible to the AM-2
+    // grep-guard, which searched for the token `isTargetName(` — a PRESENCE check on one
+    // spelling where the property was "no call site bypasses the resolver". The guard in
+    // `test/target-alias-cli.test.ts` now checks the class, and the sweep list is derived
+    // from the help text so a ninth command cannot be missed the same way.
+    const targetOpt = options.get('target');
+    let target;
+    if (targetOpt !== undefined) {
+        const parityResolution = resolveTargetName(targetOpt);
+        if (parityResolution.kind === 'unknown') {
+            // Both forms go to stderr: an error is not data, and `dz parity --json | jq`
+            // must not be fed a diagnostic (ADR-002 §Decision 2 / driver D6).
+            if (json) {
+                writeErr(JSON.stringify({ error: `unknown target ${JSON.stringify(targetOpt)}`, suggestion: parityResolution.suggestion, targets: TARGET_NAMES_SORTED, exitCode: 1 }, null, 2));
+            }
+            else {
+                for (const line of formatTargetProblem('dz parity', parityResolution))
+                    writeErr(line);
+            }
+            return 1;
+        }
+        target = parityResolution.target;
+        if (parityResolution.via === 'alias')
+            writeErr(formatTargetAliasNote('dz parity', targetOpt, target));
     }
     if (json) {
         const rows = matrix.map((r) => ({
@@ -5263,6 +5412,172 @@ function readDriftAllowlist(root) {
         return [];
     }
 }
+/** Refresh or verify the root AGENTS.md bearing-policy projection. */
+/**
+ * `dz hooks-sync --target codex` (`crossrt-2-codex-hooks`, AM-14).
+ *
+ * ONE verb in the existing target vocabulary (`parity`, `delivery-check`, `--target`), extensible to
+ * a future runtime without a third surface. **No alias** — `dz codex-hooks` resolves to nothing.
+ *
+ * Exit map (ADR-002 §5, pinned by test):
+ *   0 = `armed` AND `trust: 'trusted'` — the ONLY outcome that may print a success word (AM-17)
+ *   1 = not armed, armed-but-trust-pending, drift, or a refusal
+ *   3 = inconclusive (including "no codex binary on PATH")
+ */
+function cmdHooksSync(options, flags, cwd, write, writeErr) {
+    const json = flags.has('json');
+    const usage = 'dz hooks-sync --target codex [--check] [--verify] [--remove] [--json] [--project <dir>] [--no-verify]';
+    if (flags.has('help')) {
+        write(`${usage} — install/verify the dz veto + recall hooks in $CODEX_HOME/hooks.json`);
+        return 0;
+    }
+    for (const flag of flags) {
+        if (!['check', 'verify', 'no-verify', 'remove', 'json', 'help'].includes(flag)) {
+            const message = `dz hooks-sync: unknown option --${flag}\n${usage}`;
+            (json ? write : writeErr)(json ? JSON.stringify({ error: `unknown option --${flag}`, exitCode: 1 }) : message);
+            return 1;
+        }
+    }
+    for (const key of options.keys()) {
+        if (key !== 'target' && key !== 'project' && key !== 'codex-home') {
+            const message = key.startsWith('_positional_') ? `unexpected argument ${JSON.stringify(options.get(key))}` : `unknown option --${key}`;
+            (json ? write : writeErr)(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz hooks-sync: ${message}\n${usage}`);
+            return 1;
+        }
+    }
+    // Every `--target` read in this CLI goes through resolveTargetName (alias support + one spelling
+    // of the unknown-target message), pinned by `everyTargetGuardUsesResolveTargetName`.
+    const targetOpt = options.get('target');
+    if (targetOpt === undefined) {
+        const message = '--target is required';
+        (json ? write : writeErr)(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz hooks-sync: ${message}\n${usage}`);
+        return 1;
+    }
+    const resolution = resolveTargetName(targetOpt);
+    if (resolution.kind === 'unknown') {
+        if (json) {
+            write(JSON.stringify({ error: `unknown target ${targetOpt}`, exitCode: 1 }));
+        }
+        else {
+            for (const line of formatTargetProblem('dz hooks-sync', resolution))
+                writeErr(line);
+        }
+        return 1;
+    }
+    const target = resolution.target;
+    if (resolution.via === 'alias')
+        writeErr(formatTargetAliasNote('dz hooks-sync', targetOpt, target));
+    if (target !== 'codex') {
+        // Deliberately narrow: only Codex has a hook carrier today. Naming the reason keeps a future
+        // reader from assuming the other nine are simply unimplemented here.
+        const message = `unsupported --target ${target} (only "codex" has a hook carrier today)`;
+        (json ? write : writeErr)(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz hooks-sync: ${message}\n${usage}`);
+        return 1;
+    }
+    const codexHome = options.get('codex-home');
+    const report = runSyncCodexHooks({
+        ...(codexHome !== undefined ? { codexHome } : {}),
+        check: flags.has('check'),
+        remove: flags.has('remove'),
+    });
+    if (json) {
+        write(JSON.stringify({ ...report, exitCode: report.exitCode }));
+        return report.exitCode;
+    }
+    for (const err of report.errors)
+        writeErr(`dz hooks-sync: ${err}`);
+    for (const warn of report.warnings)
+        writeErr(`dz hooks-sync: warning: ${warn}`);
+    // SILENT in a home that never opted in — the leg-1 F12 lesson: a --check that chatters in every
+    // unrelated project trains its reader to ignore it.
+    if (flags.has('check') && !report.installed && report.errors.length === 0)
+        return report.exitCode;
+    if (flags.has('remove')) {
+        write(`dz hooks-sync: removed ${report.removed} managed entr(ies) from ${report.registryPath}`);
+        return report.exitCode;
+    }
+    // AM-17 / G-G: the success word is reachable ONLY from armed AND trusted. The trust clause is
+    // asserted HERE as well as in the exit map — a read-only `--check` that could not establish trust
+    // once returned exit 0 with `trust: 'unknown'`, and this line printed "ready" for it.
+    if (report.exitCode === 0 && report.trust === 'trusted' && report.installed) {
+        write(`dz hooks-sync: codex hooks installed and ARMED (trust: ${report.trust}) — ready`);
+    }
+    else if (report.installed) {
+        writeErr(`dz hooks-sync: installed, NOT verified — ARMED = NO (trust: ${report.trust}, executable: ${report.executable})`);
+        writeErr('→ open an interactive Codex session in this directory and approve the two dz hooks, then re-run with --verify');
+    }
+    else {
+        writeErr('dz hooks-sync: ARMED = NO — the managed entries are not present in the registry');
+    }
+    return report.exitCode;
+}
+function cmdAgentsSync(options, flags, cwd, write, writeErr) {
+    const json = flags.has('json');
+    const usage = 'dz agents-sync [--project <dir>] [--check] [--json]';
+    if (flags.has('help')) {
+        write(`${usage} — sync/verify the dz:policies fence in root AGENTS.md`);
+        return 0;
+    }
+    for (const flag of flags) {
+        if (!['check', 'json', 'help'].includes(flag)) {
+            const message = `dz agents-sync: unknown option --${flag}\n${usage}`;
+            (json ? write : writeErr)(json ? JSON.stringify({ error: `unknown option --${flag}`, exitCode: 1 }) : message);
+            return 1;
+        }
+    }
+    for (const key of options.keys()) {
+        if (key !== 'project') {
+            const message = key.startsWith('_positional_') ? `unexpected argument ${JSON.stringify(options.get(key))}` : `unknown option --${key}`;
+            (json ? write : writeErr)(json ? JSON.stringify({ error: message, exitCode: 1 }) : `dz agents-sync: ${message}\n${usage}`);
+            return 1;
+        }
+    }
+    const root = resolve(cwd, options.get('project') ?? '.');
+    try {
+        const report = runSyncAgentsPolicy({ projectRoot: root, check: flags.has('check') });
+        const drifted = report.drift.filter((finding) => finding.status !== 'ok');
+        const inconclusive = report.missing.length > 0;
+        const failed = flags.has('check')
+            ? report.changed || report.budget.overflow || drifted.length > 0
+            : !report.inSync;
+        const exitCode = inconclusive ? 3 : failed ? 1 : 0;
+        if (json) {
+            write(JSON.stringify({ ...report, sections: report.blocks, exitCode }));
+            return exitCode;
+        }
+        if (inconclusive) {
+            writeErr(`dz agents-sync: INCONCLUSIVE — unreadable or unanchored policy source(s): ${report.missing.join(', ')}`);
+            writeErr('→ heal with: restore the named source anchors, then run dz agents-sync');
+            return 3;
+        }
+        if (failed) {
+            const effect = flags.has('check') ? 'AGENTS.md would change' : 'AGENTS.md was not rewritten';
+            writeErr(`dz agents-sync: DRIFT — ${drifted.length} stale/missing section(s); ${effect}`);
+            for (const finding of drifted)
+                writeErr(`  ${finding.id}: ${finding.file} (${finding.status})`);
+            if (drifted.some((finding) => finding.id === 'dz:policies')) {
+                writeErr('→ heal with: repair duplicate/unmatched dz:policies markers, then run dz agents-sync');
+            }
+            else {
+                writeErr('→ heal with: dz agents-sync');
+            }
+            return 1;
+        }
+        const verb = report.written ? 'wrote' : 'in sync';
+        write(`dz agents-sync: ${verb} — ${report.blocks.length} policy section(s), ${report.budget.bytes} bytes (${report.budget.pct}% of ${report.budget.cap})`);
+        for (const warning of report.warnings)
+            writeErr(`dz agents-sync: warning: ${warning}`);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (json)
+            write(JSON.stringify({ error: message, exitCode: 1 }));
+        else
+            writeErr(`dz agents-sync: ${message}`);
+        return 1;
+    }
+}
 function cmdDriftCheck(options, flags, cwd, write) {
     const root = resolve(cwd, options.get('project') ?? '.');
     // Default scope = PUBLISHED packages only: the `.claude/skills` dogfood copies legitimately lag the
@@ -5370,6 +5685,38 @@ function gatherReadmeCounts(root) {
 function gatherGuardFacts(op, root, text, storeCap) {
     const facts = { op };
     if (op === 'publish') {
+        // agents-md-policy-sync: fixed registry, no tree walk. The pure detector
+        // recomputes every expected hash from current source text; this gatherer
+        // only supplies bytes. Any unexpected gather failure omits the fact, and
+        // evaluateGuard records that advisory coverage gap in `notes`.
+        try {
+            const policyFiles = new Map();
+            for (const file of new Set(POLICY_SOURCES.map((source) => source.file))) {
+                try {
+                    policyFiles.set(file, readFileSync(join(root, file), 'utf8'));
+                }
+                catch {
+                    policyFiles.set(file, null);
+                }
+            }
+            let agentsMd = null;
+            try {
+                agentsMd = readFileSync(join(root, 'AGENTS.md'), 'utf8');
+            }
+            catch { /* missing stamp evidence */ }
+            const policyDrift = detectPolicyDrift(policyFiles, agentsMd, POLICY_SOURCES);
+            facts['policyDrift'] = {
+                applicable: policyDrift.applicable,
+                // Did this repo OPT IN? A `dz:policies` fence in AGENTS.md is the only durable signal that
+                // someone ran `dz agents-sync` here. Without it the advisory rule is out of scope and stays
+                // silent; with it, unreadable sources become a loud note instead of a silent skip.
+                fenced: hasPolicyFence(agentsMd),
+                drifted: policyDrift.findings
+                    .filter((finding) => finding.status !== 'ok')
+                    .map((finding) => `${finding.id}:${finding.file}:${finding.status}`),
+            };
+        }
+        catch { /* unexpected gather failure — omission becomes a visible guard note */ }
         const manifests = [];
         const located = [];
         try {
@@ -6484,7 +6831,7 @@ async function cmdRetro(options, flags, cwd, write) {
  *   --from-spec <spec.json>    preview the scaffold (create / augment per file); the SKILL fills the spec
  *   --apply                    with --from-spec: WRITE (create missing, AUGMENT existing — never clobber)
  */
-function cmdFeatureAdrSetup(options, flags, cwd, write) {
+function cmdFeatureAdrSetup(options, flags, cwd, write, writeErr) {
     let repoRoot = cwd;
     try {
         repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd;
@@ -6504,11 +6851,25 @@ function cmdFeatureAdrSetup(options, flags, cwd, write) {
     // Its "runnable here" list is computed for --target (default agents-md, the AGENTS.md-class target class).
     const wantGates = flags.has('gates');
     const targetOpt = options.get('target');
-    if (targetOpt !== undefined && !isTargetName(targetOpt)) {
-        write(`dz feature-adr-setup: --target must be one of: ${TARGET_NAMES.join(', ')}`);
-        return 1;
+    // Sites 7 AND 8 of the D3 rewiring. Site 8 (the coercion below) is NOT a guard — it
+    // is a silent fallback, and a mechanical "replace isTargetName with resolveTargetName"
+    // pass would miss it. With aliasing in place and the coercion left alone,
+    // `dz feature-adr-setup --gates --target claude` would pass validation and then emit
+    // for **agents-md**. So the coercion CONSUMES the resolution computed once, above;
+    // `agents-md` is the default only when `--target` is ABSENT.
+    let gatesTarget = 'agents-md';
+    if (targetOpt !== undefined) {
+        const gatesResolution = resolveTargetName(targetOpt);
+        if (gatesResolution.kind === 'unknown') {
+            for (const line of formatTargetProblem('dz feature-adr-setup', gatesResolution))
+                writeErr(line);
+            return 1;
+        }
+        gatesTarget = gatesResolution.target;
+        if (gatesResolution.via === 'alias') {
+            writeErr(formatTargetAliasNote('dz feature-adr-setup', targetOpt, gatesTarget));
+        }
     }
-    const gatesTarget = isTargetName(targetOpt ?? '') ? targetOpt : 'agents-md';
     const specPath = options.get('from-spec');
     if (specPath === undefined && !wantGuards && !wantGates) {
         // default + --plan: the read-only "which documents, and where?" answer.
@@ -6642,7 +7003,15 @@ function cmdChallenge(options, flags, cwd, write) {
  *   --base <ref>                    the base ref to fail against (default HEAD)
  *   --name '<filter>'               optional -t test-name filter applied to every target
  *   --runner '<cmd>'                test runner (default `npx vitest run`)
- *   --json                          machine-readable {plan, results, verdict, finding}
+ *   --timeout <ms>                  per-run timeout (default 300000; a timed-out run is CANNOT_ISOLATE)
+ *   --json                          machine-readable {plan, results, tipTree, perTest, aggregate,
+ *                                   findings, measurementValid, primaryAction}
+ *
+ * This executor is THIN by design (house style: pure classifier + thin executor). It performs exactly the
+ * I/O the pure gate cannot — stat, worktree, run, capture — and hands OBSERVATIONS back. It no longer
+ * interprets anything: the pre-epoch load-error regex that lived here (`/cannot find module|failed to
+ * load|.../i`) is DELETED, because a regex over a runner's stderr, written in the executor, is exactly the
+ * probabilistic channel that minted `DISCRIMINATES` for `--runner false`.
  *
  * NEVER auto-aborts: a non-discriminating (false-green) test is reported as a HIGH finding for the owner to
  * decide (dz's rule — a false gate kills trust). Exit code is 0 on a clean run regardless of verdict; 2 only on
@@ -6663,6 +7032,9 @@ function cmdDiscriminationCheck(options, flags, cwd, write) {
     const propertyTests = testArg.split(',').map((s) => s.trim()).filter(Boolean).map((file) => nameFilter !== undefined && nameFilter.trim() !== '' ? { file, name: nameFilter.trim() } : { file });
     const baseRef = options.get('base') ?? 'HEAD';
     const runnerOpt = options.get('runner');
+    // R11: a hung runner is a loud non-answer, never a pass. Same default + parse shape as mutation-gate.
+    const timeoutOpt = Number(options.get('timeout') ?? '300000');
+    const timeoutMs = Number.isFinite(timeoutOpt) && timeoutOpt > 0 ? timeoutOpt : 300000;
     const plan = planDiscriminationCheck(runnerOpt !== undefined ? { baseRef, propertyTests, runner: runnerOpt } : { baseRef, propertyTests });
     if (!plan.runnable) {
         // No safe target to run → this is the existing "property untested" finding (empty propertyTests classify).
@@ -6677,113 +7049,218 @@ function cmdDiscriminationCheck(options, flags, cwd, write) {
         write(`  → ${result.finding?.detail ?? 'no property test to check'}`);
         return 0;
     }
-    // Execute the plan in a temp worktree WE own; substitute {{WORKTREE}} and always clean up.
-    // `git worktree add` must CREATE the path, so compute a fresh non-existent one (do NOT mkdtemp it).
-    const worktree = join(mkdtempSync(join(tmpdir(), 'dz-disc-')), 'wt');
-    const results = [];
-    try {
-        // 1) add the detached worktree at base (git creates `worktree`; its parent already exists).
-        const addCmd = plan.commands[0].replace(/\{\{WORKTREE\}\}/g, worktree);
-        execSync(addCmd, { cwd: repoRoot, stdio: 'pipe', encoding: 'utf-8' });
-        // 1b) a fresh worktree has NO node_modules — without this, every test fails to load (runner + deps
-        // unresolvable) and the gate collapses to always-VIA_ERROR, blind to false greens. Absolute-path
-        // symlinks point back at the main checkout's already-installed trees, robust across pnpm's layout.
-        const linkNodeModules = (relDir) => {
-            const srcNm = join(repoRoot, relDir, 'node_modules');
-            if (!existsSync(srcNm))
-                return;
-            const dstNm = join(worktree, relDir, 'node_modules');
-            if (existsSync(dstNm))
-                return;
-            try {
-                mkdirSync(dirname(dstNm), { recursive: true });
-                symlinkSync(srcNm, dstNm, 'dir');
-            }
-            catch { /* best effort */ }
-        };
-        linkNodeModules('.'); // root (hoisted deps + .bin)
-        const pkgDirs = new Set();
-        for (const t of plan.targets) {
-            let d = dirname(t.file);
-            while (d && d !== '.' && d !== sep) {
-                if (existsSync(join(repoRoot, d, 'package.json'))) {
-                    pkgDirs.add(d);
-                    break;
+    // ── (1) stat + isFile, BEFORE the worktree (AM-6 / FR-A1) ──────────────────────────────────
+    // R12: `stat` FOLLOWS symlinks on purpose. A dangling symlink lstat-exists but has no readable
+    // content — that IS absence of the named check. A directory stat-exists but is not a regular
+    // file. Pre-epoch both reached the copy step, threw, and were caught into `outcome:'error'`,
+    // which minted the near-pass DISCRIMINATES_VIA_ERROR (MEASURED — acid A1 / the dangling-symlink
+    // and directory rows of features/wave1-instrument-repair/07_code_changes/acid-red-runs.md).
+    const absent = [];
+    const present = [];
+    for (const t of plan.targets) {
+        let isRegular = false;
+        let isDirectory = false;
+        try {
+            const st = statSync(resolve(repoRoot, t.file));
+            isRegular = st.isFile();
+            isDirectory = st.isDirectory();
+        }
+        catch { /* ENOENT / dangling symlink / permission — absence, either way */ }
+        if (isRegular) {
+            present.push(t.name !== undefined ? { file: t.file, name: t.name } : { file: t.file });
+            continue;
+        }
+        const row = t.name !== undefined ? { file: t.file, name: t.name, outcome: 'absent' } : { file: t.file, outcome: 'absent' };
+        // Out-of-band detail channel: TEST_FILE_ABSENT is evidence-EXEMPT (its evidence is the stat
+        // itself), and absent rows never consult the evidence gate — so this object cannot degrade the
+        // row. It exists only so the finding can tell the operator WHY the path is not a test file.
+        absent.push(isDirectory
+            ? { ...row, evidence: { exitCode: null, runner: 'unrecognised', failureKind: 'unrecognised', testsExecuted: null, targetSeen: false, evidenceLine: 'not-a-regular-file' } }
+            : row);
+    }
+    const results = [...absent];
+    let tipTree = null;
+    // Confirmation 12: with nothing present there is nothing to run — no worktree is built at all.
+    if (present.length > 0) {
+        const runner = runnerOpt !== undefined && plan.commands.some((c) => c.includes(runnerOpt)) ? runnerOpt : 'npx vitest run';
+        // Execute the plan in a temp worktree WE own; substitute {{WORKTREE}} and always clean up.
+        // `git worktree add` must CREATE the path, so compute a fresh non-existent one (do NOT mkdtemp it).
+        const worktree = join(mkdtempSync(join(tmpdir(), 'dz-disc-')), 'wt');
+        try {
+            // 1) add the detached worktree at base (git creates `worktree`; its parent already exists).
+            const addCmd = plan.commands[0].replace(/\{\{WORKTREE\}\}/g, worktree);
+            execSync(addCmd, { cwd: repoRoot, stdio: 'pipe', encoding: 'utf-8' });
+            // 1b) a fresh worktree has NO node_modules — without this, every test fails to load (runner + deps
+            // unresolvable) and the gate collapses to always-VIA_ERROR, blind to false greens. Absolute-path
+            // symlinks point back at the main checkout's already-installed trees, robust across pnpm's layout.
+            const linkNodeModules = (relDir) => {
+                const srcNm = join(repoRoot, relDir, 'node_modules');
+                if (!existsSync(srcNm))
+                    return;
+                const dstNm = join(worktree, relDir, 'node_modules');
+                if (existsSync(dstNm))
+                    return;
+                try {
+                    mkdirSync(dirname(dstNm), { recursive: true });
+                    symlinkSync(srcNm, dstNm, 'dir');
+                }
+                catch { /* best effort */ }
+            };
+            linkNodeModules('.'); // root (hoisted deps + .bin)
+            const pkgDirs = new Set();
+            for (const t of present) {
+                let d = dirname(t.file);
+                while (d && d !== '.' && d !== sep) {
+                    if (existsSync(join(repoRoot, d, 'package.json'))) {
+                        pkgDirs.add(d);
+                        break;
+                    }
+                    d = dirname(d);
                 }
-                d = dirname(d);
             }
-        }
-        for (const d of pkgDirs)
-            linkNodeModules(d);
-        // 2) copy each property test into the base worktree, then 3) run it and record pass/fail/error per target.
-        for (const t of plan.targets) {
-            try {
-                const src = resolve(repoRoot, t.file);
-                // containment guard (defense in depth beyond planDiscriminationCheck's path sanitation).
-                if (!resolve(src).startsWith(resolve(repoRoot) + sep)) {
+            for (const d of pkgDirs)
+                linkNodeModules(d);
+            // 2) copy each property test into the base worktree, then 3) run it and record the OBSERVATION.
+            for (const t of present) {
+                try {
+                    const src = resolve(repoRoot, t.file);
+                    // containment guard (defense in depth beyond planDiscriminationCheck's path sanitation).
+                    if (!resolve(src).startsWith(resolve(repoRoot) + sep)) {
+                        results.push(nameFor(t, 'error'));
+                        continue;
+                    }
+                    const dst = join(worktree, t.file);
+                    mkdirSync(dirname(dst), { recursive: true });
+                    writeFileSync(dst, readFileSync(src));
+                }
+                catch {
+                    // the file STAT-PASSED and the copy still failed: degrade LOUDLY as an error with NO
+                    // evidence (the gate reads it as CANNOT_ISOLATE), never as absence and never as a pass.
                     results.push(nameFor(t, 'error'));
                     continue;
                 }
-                const dst = join(worktree, t.file);
-                mkdirSync(dirname(dst), { recursive: true });
-                writeFileSync(dst, readFileSync(src));
+                // t.file + t.name already passed the engine's strict sanitation (no quotes/metacharacters/leading-dash);
+                // still quote + `--` so a path can never be read as a runner option or split a word.
+                const nameArg = t.name ? ` -t '${t.name}'` : '';
+                const cmd = `${runner}${nameArg} -- '${t.file}'`;
+                const base = runCapturedTest(cmd, worktree, timeoutMs);
+                const evidence = classifyExecutionEvidence(base.output, base.exitCode, t.file);
+                const outcome = discriminationOutcomeOf(base.exitCode, evidence);
+                const row = t.name !== undefined
+                    ? { file: t.file, name: t.name, outcome, evidence }
+                    : { file: t.file, outcome, evidence };
+                // 4) TIP CONTROL (FR-A2 + Confirmation 17). Run it for ALL non-assertion redness — file-load
+                // redness (the matrix's EVIDENCED-error rows) AND unrecognised redness (so the invocation
+                // ledger can prove the tip was REACHED). The CLASSIFIER still ignores the tip for unevidenced
+                // base rows per the matrix; running it is cheap and only ever on an already-broken path.
+                // Do NOT "simplify" this to evidenced-error-only — that silently breaks Confirmation 17.
+                if (base.exitCode !== null && base.exitCode !== 0 && evidence.failureKind !== 'assertions') {
+                    const tip = runCapturedTest(cmd, repoRoot, timeoutMs);
+                    const tipEvidence = classifyExecutionEvidence(tip.output, tip.exitCode, t.file);
+                    row['tipOutcome'] = discriminationOutcomeOf(tip.exitCode, tipEvidence);
+                    row['tipEvidence'] = tipEvidence;
+                    // R15, named honestly: the base run is isolated in a worktree, but the tip runs in the LIVE
+                    // tree, where a concurrent writer can flip the observation mid-gate. No lock is taken
+                    // (deferred to backlog 9520e506); instead every tip-derived reading carries the tree
+                    // CONDITIONS it was taken under, so a surprising verdict can be re-read against them.
+                    if (tipTree === null)
+                        tipTree = readTipTreeConditions(repoRoot);
+                }
+                results.push(row);
             }
-            catch {
-                results.push(nameFor(t, 'error'));
-                continue;
+        }
+        catch (e) {
+            if (flags.has('json')) {
+                write(JSON.stringify({ plan, error: 'worktree-setup-failed', detail: String(e.message).slice(0, 300) }, null, 2));
             }
-            const runner = (runnerOpt !== undefined && plan.commands.some((c) => c.includes(runnerOpt))) ? runnerOpt : 'npx vitest run';
-            // t.file + t.name already passed the engine's strict sanitation (no quotes/metacharacters/leading-dash);
-            // still quote + `--` so a path can never be read as a runner option or split a word.
-            const nameArg = t.name ? ` -t '${t.name}'` : '';
+            else
+                write(`discrimination-check: could not create worktree at ${baseRef}: ${String(e.message).slice(0, 200)}`);
+            return 2;
+        }
+        finally {
             try {
-                execSync(`${runner}${nameArg} -- '${t.file}'`, { cwd: worktree, stdio: 'pipe', encoding: 'utf-8' });
-                results.push(nameFor(t, 'pass')); // exit 0 → test PASSED at base → false green
+                execSync(`git worktree remove --force ${worktree}`, { cwd: repoRoot, stdio: 'pipe' });
             }
-            catch (e) {
-                // vitest exits non-zero on failure AND on load/compile error. Distinguish: a load error usually names
-                // "Cannot find module"/"Failed to load"/"No test files"; otherwise treat as an assertion failure (red).
-                const out = String(e.stdout ?? '') + String(e.stderr ?? '');
-                const isLoadError = /cannot find module|failed to load|no test (files )?found|error: cannot|transform failed|esbuild/i.test(out);
-                results.push(nameFor(t, isLoadError ? 'error' : 'fail'));
+            catch { /* fall through to rm */ }
+            // remove the whole mkdtemp parent (worktree is `<mkdtemp>/wt`), so nothing leaks under tmp even on error.
+            try {
+                rmSync(dirname(worktree), { recursive: true, force: true });
             }
+            catch { /* best effort */ }
+            try {
+                execSync('git worktree prune', { cwd: repoRoot, stdio: 'pipe' });
+            }
+            catch { /* best effort */ }
         }
     }
-    catch (e) {
-        if (flags.has('json')) {
-            write(JSON.stringify({ plan, error: 'worktree-setup-failed', detail: String(e.message).slice(0, 300) }, null, 2));
-        }
-        else
-            write(`discrimination-check: could not create worktree at ${baseRef}: ${String(e.message).slice(0, 200)}`);
-        return 2;
-    }
-    finally {
-        try {
-            execSync(`git worktree remove --force ${worktree}`, { cwd: repoRoot, stdio: 'pipe' });
-        }
-        catch { /* fall through to rm */ }
-        // remove the whole mkdtemp parent (worktree is `<mkdtemp>/wt`), so nothing leaks under tmp even on error.
-        try {
-            rmSync(dirname(worktree), { recursive: true, force: true });
-        }
-        catch { /* best effort */ }
-        try {
-            execSync('git worktree prune', { cwd: repoRoot, stdio: 'pipe' });
-        }
-        catch { /* best effort */ }
-    }
     const result = classifyDiscrimination({ propertyTests, results });
     if (flags.has('json')) {
-        write(JSON.stringify({ plan, results, ...result }, null, 2));
+        write(JSON.stringify({ plan, results, tipTree, ...result }, null, 2));
         return 0;
     }
     write(`discrimination-check @ ${baseRef} — verdict: ${result.aggregate}`);
-    for (const p of result.perTest)
-        write(`  ${p.verdict === 'NON_DISCRIMINATING' ? '✗' : '✓'} ${p.file}${p.name ? ` (${p.name})` : ''}: ${p.verdict}`);
-    if (result.finding)
-        write(`\n  [${result.finding.severity}] ${result.finding.title}\n  ${result.finding.detail}`);
+    for (const p of result.perTest) {
+        // FR-A6: ✓ is reserved for the two ESTABLISHED trust verdicts. Every other value — including
+        // every degraded reading — renders ✗, because a ✗ the operator investigates beats a ✓ that
+        // silently meant "we could not tell".
+        const mark = p.verdict === 'DISCRIMINATES' || p.verdict === 'DISCRIMINATES_VIA_ERROR' ? '✓' : '✗';
+        write(`  ${mark} ${p.file}${p.name ? ` (${p.name})` : ''}: ${p.verdict}${p.reason ? ` (reason: ${p.reason})` : ''}`);
+    }
+    write(`  measurementValid: ${String(result.measurementValid)} · primaryAction: ${result.primaryAction}`);
+    // ALL findings print, not just the worst: the scalar aggregate names one state, and a corpus with
+    // a false green AND an absent file has two problems, each with its own operator action.
+    for (const f of result.findings)
+        write(`\n  [${f.severity}] ${f.title}\n  ${f.detail}`);
     return 0;
 }
+/**
+ * Run one test command and CAPTURE the observation — output plus the exit code, including the
+ * "no exit code at all" case. `execSync`'s timeout kills the child via signal and leaves
+ * `status` null; a spawn failure does the same. That null is not an error to swallow, it is the
+ * evidence (`CANNOT_ISOLATE` reason `'timeout'`), so it is returned as data.
+ */
+function runCapturedTest(cmd, cwd, timeoutMs) {
+    try {
+        const stdout = execSync(cmd, { cwd, stdio: 'pipe', encoding: 'utf-8', timeout: timeoutMs });
+        return { output: String(stdout ?? ''), exitCode: 0 };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            output: String(err.stdout ?? '') + String(err.stderr ?? ''),
+            exitCode: typeof err.status === 'number' ? err.status : null,
+        };
+    }
+}
+/**
+ * The outcome VALUE for one captured run. The executor's whole remaining judgment, and it is
+ * mechanical: exit 0 is a pass, no exit code is an error, and a non-zero exit is an error only when
+ * the classifier RECOGNISED a file-load failure. An unrecognised red is deliberately recorded as a
+ * `fail` VALUE whose evidence then degrades it — exactly acid A6's pinned shape, and the reason the
+ * executor no longer owns a regex.
+ */
+function discriminationOutcomeOf(exitCode, evidence) {
+    if (exitCode === null)
+        return 'error';
+    if (exitCode === 0)
+        return 'pass';
+    return evidence.failureKind === 'file-load' ? 'error' : 'fail';
+}
+/** The live tree's identity at tip-run time (R15). Best-effort: unknown conditions read as such. */
+function readTipTreeConditions(repoRoot) {
+    let headSha = 'unknown';
+    let dirtyFiles = -1;
+    try {
+        headSha = execSync('git rev-parse HEAD', { cwd: repoRoot, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    }
+    catch { /* best effort */ }
+    try {
+        const porcelain = execSync('git status --porcelain', { cwd: repoRoot, stdio: 'pipe', encoding: 'utf-8' });
+        dirtyFiles = String(porcelain).split('\n').filter((l) => l.trim() !== '').length;
+    }
+    catch { /* best effort */ }
+    return { headSha, dirtyFiles };
+}
 /** small helper: build a result row, omitting `name` when absent (exactOptionalPropertyTypes). */
 function nameFor(t, outcome) {
     return t.name !== undefined ? { file: t.file, name: t.name, outcome } : { file: t.file, outcome };
@@ -7926,7 +8403,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 +8429,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 +8509,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 +8522,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 +8551,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 +8585,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 +8600,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 +8622,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
@@ -9148,6 +9662,8 @@ async function cmdImportEcc(options, flags, cwd, write) {
 export async function runCli(argv, io = {}) {
     const cwd = io.cwd ?? process.cwd();
     const write = io.write ?? ((line) => { console.log(line); });
+    // Diagnostics go to stderr so `dz <cmd> > out.txt` yields clean data (feature dz-cli-defects).
+    const writeErr = io.writeErr ?? ((line) => { console.error(line); });
     // Lazy STDIN reader — only `dz brain ground` reads it, and only when no positional prompt is
     // given. Never blocks: injected `io.stdin` wins; else read fd 0 synchronously, but bail to '' on
     // a TTY (nothing piped) or any read error. Grounding must never hang waiting on an empty pipe.
@@ -9164,6 +9680,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;
@@ -9171,14 +9707,14 @@ export async function runCli(argv, io = {}) {
     try {
         switch (command) {
             case 'init':
-                return await cmdInit(options, flags, cwd, write);
+                return await cmdInit(options, flags, cwd, write, writeErr);
             case 'verify':
-                return await cmdVerify(options, cwd, write);
+                return await cmdVerify(options, cwd, write, writeErr);
             case 'sync':
             case 'update':
-                return await cmdSync(options, flags, cwd, write);
+                return await cmdSync(options, flags, cwd, write, writeErr);
             case 'list':
-                return cmdList(options, cwd, write);
+                return cmdList(options, cwd, write, writeErr);
             case 'create-skill':
                 return cmdCreateSkill(options, flags, cwd, write);
             case 'info':
@@ -9196,7 +9732,7 @@ export async function runCli(argv, io = {}) {
             case 'doctor':
                 return await cmdDoctor(options, flags, cwd, write);
             case 'install':
-                return await cmdInstall(options, flags, cwd, write, io.installRunner);
+                return await cmdInstall(options, flags, cwd, write, writeErr, io.installRunner);
             case 'bundle':
                 return cmdBundle(options, flags, cwd, write);
             case 'teach':
@@ -9224,17 +9760,17 @@ export async function runCli(argv, io = {}) {
             case 'verify-pack':
                 return cmdVerifyPack(options, flags, cwd, write);
             case 'setup':
-                return await cmdSetup(options, flags, cwd, write);
+                return await cmdSetup(options, flags, cwd, write, writeErr);
             case 'pretrain':
                 return cmdPretrain(options, cwd, write);
             case 'compose':
-                return cmdCompose(options, cwd, write);
+                return cmdCompose(options, cwd, write, writeErr);
             case 'diff':
                 return cmdDiff(options, cwd, write);
             case 'recommend':
                 return cmdRecommend(options, cwd, write);
             case 'upgrade':
-                return cmdUpgrade(options, flags, cwd, write);
+                return cmdUpgrade(options, flags, cwd, write, writeErr);
             case 'auto-canonicalize':
                 return await cmdAutoCanonicalize(options, cwd, write);
             case 'publish':
@@ -9242,7 +9778,7 @@ export async function runCli(argv, io = {}) {
             case 'release':
                 return cmdRelease(options, flags, cwd, write, io.releaseRunner);
             case 'parity':
-                return cmdParity(options, flags, write);
+                return cmdParity(options, flags, write, writeErr);
             case 'registry':
                 return cmdRegistry(options, cwd, write);
             case 'benchmark':
@@ -9253,6 +9789,10 @@ export async function runCli(argv, io = {}) {
                 return await cmdSyncUpstream(options, flags, cwd, write);
             case 'drift-check':
                 return cmdDriftCheck(options, flags, cwd, write);
+            case 'hooks-sync':
+                return cmdHooksSync(options, flags, cwd, write, writeErr);
+            case 'agents-sync':
+                return cmdAgentsSync(options, flags, cwd, write, writeErr);
             case 'sync-canonical':
                 return cmdSyncCanonical(options, flags, cwd, write);
             case 'plugin':
@@ -9270,7 +9810,7 @@ export async function runCli(argv, io = {}) {
             case 'retro':
                 return await cmdRetro(options, flags, cwd, write);
             case 'feature-adr-setup':
-                return cmdFeatureAdrSetup(options, flags, cwd, write);
+                return cmdFeatureAdrSetup(options, flags, cwd, write, writeErr);
             case 'challenge':
                 return cmdChallenge(options, flags, cwd, write);
             case 'discrimination-check':
@@ -9308,7 +9848,9 @@ export async function runCli(argv, io = {}) {
         }
     }
     catch (error) {
-        write(`dz: ${error instanceof Error ? error.message : String(error)}`);
+        // stderr, not stdout: an uncaught failure is a diagnostic, and routing it through
+        // `write` is what made `dz list > skills.txt` write the error into the data file.
+        writeErr(`dz: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }
 }