@dzhechkov/harness-cli 0.4.5 → 0.5.0

package/src/cli.ts

@@ -15,8 +15,13 @@ import { createRequire } from 'node:module';
 import {
   createSkill,
   getSkillInfo,
-  isTargetName,
-  listSkills,
+  listSkillsDetailed,
+  formatSkillLoadFailures,
+  formatSkillApplyFailures,
+  resolveTargetName,
+  formatTargetProblem,
+  formatTargetAliasNote,
+  TARGET_NAMES_SORTED,
   runDoctor,
   runInit,
   resolvePackageSkillRoots,
@@ -49,6 +54,11 @@ import {
   runVerify,
   runInitAgentsMd,
   runInitGeminiMd,
+  runSyncAgentsPolicy,
+  runSyncCodexHooks,
+  POLICY_SOURCES,
+  detectPolicyDrift,
+  hasPolicyFence,
   TARGET_NAMES,
   buildParityMatrix,
   TARGET_CAPABILITIES,
@@ -215,6 +225,7 @@ import {
   buildChallengeBrief,
   planDiscriminationCheck,
   classifyDiscrimination,
+  classifyExecutionEvidence,
   pickAdversaryModel,
   CHALLENGE_QUESTIONS,
   loadOutcomes,
@@ -242,6 +253,7 @@ import {
   isUsablePlaneResult,
   renderDeliveryReview,
   scanSkillsLayout,
+  declaredPluginSurface,
   parseInitFacts,
   verifyRegistration,
   buildContentProbePrompt,
@@ -342,7 +354,9 @@ import {
   planImport,
 } from '@dzhechkov/harness-core';
 import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
+import type { SkillApplyFailure, SkillLoadFailure } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
+import type { ClassifyResultRow, ExecutionEvidence } from '@dzhechkov/harness-core';
 import type { IdeaRecord, IdeaStatus } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
@@ -440,6 +454,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
@@ -449,6 +465,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(', ')}
@@ -458,6 +476,18 @@ Presets: ${PRESET_NAMES.join(', ')}`;
 export interface CliIo {
   readonly cwd?: string;
   readonly write?: (line: string) => void;
+  /**
+   * Diagnostics sink — **stderr**, defaulting to `console.error`.
+   *
+   * Before feature dz-cli-defects `CliIo` had no stderr seam at all, so every
+   * diagnostic (including the top-level error handler) landed on stdout and
+   * `dz list > skills.txt` wrote the error INTO the data file. `write` stays "data
+   * only"; `writeErr` is "diagnosis only".
+   *
+   * There is deliberately **no** fall-back to `write`: a test that wants to assert on
+   * stderr must inject `writeErr`, or the assertion would be theatre.
+   */
+  readonly writeErr?: (line: string) => void;
   /**
    * Pre-read STDIN content (injectable so `dz brain ground`'s hook path is testable without
    * an actual pipe). When omitted, the CLI reads fd 0 synchronously — but only for the one
@@ -528,6 +558,8 @@ function parseArgs(argv: string[]): ParsedArgs {
 }
 
 type Write = (line: string) => void;
+/** Mirrors {@link Write}, but for the stderr seam (see {@link CliIo.writeErr}). */
+type WriteErr = (line: string) => void;
 
 /**
  * Discover skill source directories: explicit `--skills-dir` if given, else
@@ -557,6 +589,14 @@ interface InstallSkillsResult {
   readonly skipped: number;
   /** Selected ids found in NO searched directory (empty when no `select` was given). */
   readonly missing: string[];
+  /** Skill dirs that could not be LOADED, across every searched directory (D1). */
+  readonly failures: SkillLoadFailure[];
+  /**
+   * Skills that loaded but could not be COMPILED or WRITTEN (fix round 1, QE F4).
+   * A separate list because it accuses a different artifact — the target tree, not
+   * the source `SKILL.md`.
+   */
+  readonly applyFailures: SkillApplyFailure[];
 }
 
 /**
@@ -594,10 +634,12 @@ async function installSkills(opts: {
     let written = 0;
     let skipped = 0;
     for (const s of results) { 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: { id: string; written: number; skipped: number }[] = [];
+  const failures: SkillLoadFailure[] = [];
+  const applyFailures: SkillApplyFailure[] = [];
   for (const skillsDir of skillsDirs) {
     const r = await runInit({
       target,
@@ -610,6 +652,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;
@@ -617,7 +661,7 @@ async function installSkills(opts: {
   for (const s of results) { written += s.written; skipped += s.skipped; }
   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. */
@@ -633,12 +677,22 @@ function writeMissingSkillsHint(write: Write, missing: string[], presetName: str
   }
 }
 
-async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
-  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: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
+  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') ?? '.');
 
@@ -676,19 +730,43 @@ async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: st
     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: Map<string, string>, cwd: string, write: Write): Promise<number> {
+async function cmdVerify(options: Map<string, string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
   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: TargetName | undefined;
+  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) {
@@ -697,7 +775,7 @@ async function cmdVerify(options: Map<string, string>, cwd: string, write: Write
   return report.valid === report.total ? 0 : 1;
 }
 
-async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const canonicalArg = options.get('canonical');
 
@@ -724,6 +802,14 @@ async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: st
   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;
 }
 
@@ -770,19 +856,42 @@ function cmdCreateSkill(options: Map<string, string>, flags: Set<string>, cwd: s
   return 0;
 }
 
-function cmdList(options: Map<string, string>, cwd: string, write: Write): number {
+/**
+ * `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: Map<string, string>, cwd: string, write: Write, writeErr: WriteErr): number {
   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: Map<string, string>, args: ParsedArgs, cwd: string, write: Write): number {
@@ -935,8 +1044,8 @@ function workflowInitPlan(name: string, pattern: string): object {
       ...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'] }],
@@ -948,10 +1057,10 @@ function workflowInitPlan(name: string, pattern: string): object {
       ...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' }],
@@ -961,8 +1070,8 @@ function workflowInitPlan(name: string, pattern: string): object {
     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 }],
     };
@@ -970,7 +1079,7 @@ function workflowInitPlan(name: string, pattern: string): object {
   // 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)
   };
 }
 
@@ -1161,8 +1270,12 @@ function cmdWorkflowLint(options: Map<string, string>, flags: Set<string>, cwd:
 /** `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(): string {
+/**
+ * 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(): string {
   try {
     const req = createRequire(import.meta.url);
     const pkg = req('../package.json') as { version?: unknown };
@@ -1170,6 +1283,11 @@ function traceBundleToolVersion(): string {
   } catch { return 'unknown'; }
 }
 
+/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
+function traceBundleToolVersion(): string {
+  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: Map<string, string>, cwd: string, positional: string | undefined):
@@ -1587,6 +1705,7 @@ async function cmdInstall(
   flags: Set<string>,
   cwd: string,
   write: Write,
+  writeErr: WriteErr,
   installRunner?: (command: string, cwd: string) => void,
 ): Promise<number> {
   const pkg = options.get('_positional_0');
@@ -1596,10 +1715,13 @@ async function cmdInstall(
   }
 
   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') ?? '.');
 
@@ -1635,7 +1757,7 @@ async function cmdInstall(
 
   // 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'),
@@ -1654,21 +1776,36 @@ async function cmdInstall(
   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: Map<string, string>, cwd: string, write: Write): number {
+function cmdCompose(options: Map<string, string>, cwd: string, write: Write, writeErr: WriteErr): number {
   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<string>();
   const resolved: string[] = [];
@@ -3885,12 +4022,19 @@ async function cmdBrain(
   return sub === undefined ? 0 : 1;
 }
 
-async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
-  const target = options.get('target');
-  if (!target || !isTargetName(target)) {
-    write(`dz setup: --target required (${TARGET_NAMES.join(', ')})`);
+async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
+  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');
@@ -4077,12 +4221,17 @@ function cmdRecommend(options: Map<string, string>, cwd: string, write: Write):
   return 0;
 }
 
-function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): number {
   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: Record<string, string> = {
     'claude-code': '.claude/skills', codex: '.agents/skills', opencode: '.opencode/skills',
@@ -4090,9 +4239,9 @@ function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: strin
     '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);
@@ -4110,7 +4259,7 @@ function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: strin
 
   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) {
@@ -4119,7 +4268,7 @@ function cmdUpgrade(options: Map<string, string>, flags: Set<string>, cwd: strin
   }
 
   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);
@@ -4663,7 +4812,7 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
 /*  ADR-001): computed from the declarative model, never hand-written  */
 /* ------------------------------------------------------------------ */
 
-function cmdParity(options: Map<string, string>, flags: Set<string>, write: Write): number {
+function cmdParity(options: Map<string, string>, flags: Set<string>, write: Write, writeErr: WriteErr): number {
   const json = flags.has('json');
   if (flags.has('help')) {
     write('dz parity [--target <name>] [--json] — the computed feature×target map (never hand-written)');
@@ -4692,27 +4841,44 @@ function cmdParity(options: Map<string, string>, flags: Set<string>, write: Writ
   }
 
   const matrix = buildParityMatrix();
-  const target = options.get('target');
-  if (target !== undefined && !TARGET_NAMES.includes(target as (typeof TARGET_NAMES)[number])) {
-    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: TargetName | undefined;
+  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) => ({
       id: r.feature.id,
       title: r.feature.title,
-      cells: target !== undefined ? { [target]: r.cells[target as (typeof TARGET_NAMES)[number]] } : r.cells,
+      cells: target !== undefined ? { [target]: r.cells[target] } : r.cells,
     }));
     // A filtered response stays internally consistent: capabilities are filtered too (Codex QE gap 9).
-    const caps = target !== undefined ? { [target]: TARGET_CAPABILITIES[target as (typeof TARGET_NAMES)[number]] } : TARGET_CAPABILITIES;
+    const caps = target !== undefined ? { [target]: TARGET_CAPABILITIES[target] } : TARGET_CAPABILITIES;
     write(JSON.stringify({ targets: target !== undefined ? [target] : TARGET_NAMES, capabilities: caps, features: rows }, null, 2));
     return 0;
   }
 
   if (target !== undefined) {
-    const t = target as (typeof TARGET_NAMES)[number];
+    const t = target;
     write(`\ndz parity — ${t}  (capabilities: ${TARGET_CAPABILITIES[t].join(', ')})\n`);
     for (const r of matrix) {
       const c = r.cells[t];
@@ -5678,6 +5844,179 @@ function readDriftAllowlist(root: string): string[] {
   }
 }
 
+/** 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: Map<string, string>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+  writeErr: WriteErr,
+): number {
+  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: Map<string, string>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+  writeErr: WriteErr,
+): number {
+  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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const root = resolve(cwd, options.get('project') ?? '.');
   // Default scope = PUBLISHED packages only: the `.claude/skills` dogfood copies legitimately lag the
@@ -5791,6 +6130,31 @@ function gatherReadmeCounts(root: string): { label: string; a: number; b: number
 function gatherGuardFacts(op: string, root: string, text: string | undefined, storeCap: number): Record<string, unknown> {
   const facts: Record<string, unknown> = { 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<string, string | null>();
+      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: string | null = 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 */ }
+
     // Read every workspace manifest ONCE: build a name→version map, then resolve each `workspace:*` dep to the
     // version pnpm WOULD publish it as. In a pnpm workspace (pnpm-workspace.yaml present) `workspace:*` in source
     // is correct and gets rewritten at publish — so reporting it raw would be a FALSE gate. We mirror the rewrite:
@@ -6825,7 +7189,7 @@ async function cmdRetro(options: Map<string, string>, flags: Set<string>, cwd: s
  *   --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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+function cmdFeatureAdrSetup(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): number {
   let repoRoot = cwd;
   try { repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; } catch { /* not git */ }
 
@@ -6844,11 +7208,24 @@ function cmdFeatureAdrSetup(options: Map<string, string>, flags: Set<string>, cw
   // 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: TargetName = '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: TargetName = isTargetName(targetOpt ?? '') ? (targetOpt as TargetName) : 'agents-md';
 
   const specPath = options.get('from-spec');
   if (specPath === undefined && !wantGuards && !wantGates) {
@@ -6964,7 +7341,15 @@ function cmdChallenge(options: Map<string, string>, flags: Set<string>, cwd: str
  *   --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
@@ -6984,6 +7369,9 @@ function cmdDiscriminationCheck(options: Map<string, string>, flags: Set<string>
     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 });
 
@@ -6997,82 +7385,186 @@ function cmdDiscriminationCheck(options: Map<string, string>, flags: Set<string>
     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: { file: string; name?: string; outcome: 'pass' | 'fail' | 'error' }[] = [];
-  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: string): void => {
-      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<string>();
-    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; }
-        d = dirname(d);
+  // ── (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: { file: string; name?: string; outcome: 'absent'; evidence?: ExecutionEvidence }[] = [];
+  const present: { file: string; name?: string }[] = [];
+  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' as const } : { file: t.file, outcome: 'absent' as const };
+    // 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: ClassifyResultRow[] = [...absent];
+  let tipTree: { headSha: string; dirtyFiles: number } | null = 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: string): void => {
+        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<string>();
+      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);
+        }
       }
-    }
-    for (const d of pkgDirs) linkNodeModules(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)) { results.push(nameFor(t, 'error')); continue; }
-        const dst = join(worktree, t.file);
-        mkdirSync(dirname(dst), { recursive: true });
-        writeFileSync(dst, readFileSync(src));
-      } catch { results.push(nameFor(t, 'error')); continue; }
-
-      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}'` : '';
-      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
-      } 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 as { stdout?: string; stderr?: string }).stdout ?? '') + String((e as { stderr?: string }).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'));
+      // 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;
+        }
+
+        // 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: Record<string, unknown> = 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 as unknown as ClassifyResultRow);
       }
+    } catch (e) {
+      if (flags.has('json')) { write(JSON.stringify({ plan, error: 'worktree-setup-failed', detail: String((e as Error).message).slice(0, 300) }, null, 2)); }
+      else write(`discrimination-check: could not create worktree at ${baseRef}: ${String((e as Error).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 */ }
     }
-  } catch (e) {
-    if (flags.has('json')) { write(JSON.stringify({ plan, error: 'worktree-setup-failed', detail: String((e as Error).message).slice(0, 300) }, null, 2)); }
-    else write(`discrimination-check: could not create worktree at ${baseRef}: ${String((e as Error).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)); return 0; }
+  if (flags.has('json')) { 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: string, cwd: string, timeoutMs: number): { output: string; exitCode: number | null } {
+  try {
+    const stdout = execSync(cmd, { cwd, stdio: 'pipe', encoding: 'utf-8', timeout: timeoutMs });
+    return { output: String(stdout ?? ''), exitCode: 0 };
+  } catch (e) {
+    const err = e as { stdout?: string; stderr?: string; status?: unknown };
+    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: number | null, evidence: ExecutionEvidence): 'pass' | 'fail' | 'error' {
+  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: string): { headSha: string; dirtyFiles: number } {
+  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: { file: string; name?: string }, outcome: 'pass' | 'fail' | 'error'): { file: string; name?: string; outcome: 'pass' | 'fail' | 'error' } {
   return t.name !== undefined ? { file: t.file, name: t.name, outcome } : { file: t.file, outcome };
@@ -8151,7 +8643,11 @@ 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: string, timeoutMs: number): Promise<{ stream: string; error: string | null }> {
+function probeInitStream(
+  projectDir: string,
+  timeoutMs: number,
+  pluginDir: string | null = null,
+): Promise<{ stream: string; error: string | null }> {
   return new Promise((resolveProbe) => {
     const env: NodeJS.ProcessEnv = { ...process.env };
     for (const key of PROBE_SCRUB_ENV) delete env[key];
@@ -8181,7 +8677,12 @@ function probeInitStream(projectDir: string, timeoutMs: number): Promise<{ strea
 
     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'],
@@ -8255,8 +8756,11 @@ async function cmdSkillsVerify(
 ): Promise<number> {
   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.');
@@ -8266,8 +8770,9 @@ async function cmdSkillsVerify(
   }
 
   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}`);
@@ -8297,6 +8802,28 @@ async function cmdSkillsVerify(
         .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;
@@ -8307,6 +8834,11 @@ async function cmdSkillsVerify(
       if (!scan.exists) write('  no .claude/skills/ directory here');
       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;
@@ -8317,7 +8849,7 @@ async function cmdSkillsVerify(
   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
@@ -8342,6 +8874,7 @@ async function cmdSkillsVerify(
       // 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 },
   );
@@ -9281,6 +9814,8 @@ async function cmdImportEcc(options: Map<string, string>, flags: Set<string>, cw
 export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   const cwd = io.cwd ?? process.cwd();
   const write: 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: 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.
@@ -9295,6 +9830,26 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   };
   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;
@@ -9303,14 +9858,14 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   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':
@@ -9328,7 +9883,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       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':
@@ -9356,17 +9911,17 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       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':
@@ -9374,7 +9929,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       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':
@@ -9385,6 +9940,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         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':
@@ -9402,7 +9961,7 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       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':
@@ -9439,7 +9998,9 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return 1;
     }
   } 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;
   }
 }