@dzhechkov/harness-cli 0.3.262 → 0.4.1

package/src/cli.ts

@@ -4,21 +4,23 @@
  * @packageDocumentation
  */
 
-import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { appendFileSync, chmodSync, closeSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 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,
-  getWorkflow,
   isTargetName,
   listSkills,
   runDoctor,
   runInit,
+  resolvePackageSkillRoots,
+  PACKAGE_SKILL_LAYOUTS,
   benchmarkSkill,
   benchmarkSkills,
   scanMcp,
@@ -51,7 +53,22 @@ import {
   buildParityMatrix,
   TARGET_CAPABILITIES,
   TARGET_SHORT_LABELS,
-  WORKFLOW_NAMES,
+  WORKFLOW_TEMPLATES_RETIRED_MESSAGE,
+  parsePlan,
+  isParseErrors,
+  validatePlan,
+  normalizePlan,
+  planDigest,
+  toTraceProjection,
+  renderPlan,
+  mergeRender,
+  lint,
+  lintExitCode,
+  LOOP_BLOBS,
+  parseTrace,
+  assembleTimeline,
+  runInvariants,
+  renderTimelineHtml,
   importEcc,
   recordPattern,
   resolveLearningBackend,
@@ -128,6 +145,7 @@ import {
   guardExitCode,
   DEFAULT_RULES,
   parsePnpmLockImporters,
+  scannableStubPath,
   // guard-promotion (feature guard-promotion, scout idea #1)
   assembleCandidates,
   renderPromotionReport,
@@ -264,6 +282,10 @@ import {
   isSafeId,
   alignIdea,
   mirrorIdeaVector,
+  ensureBacklogEmbedForm,
+  readBacklogEmbedFormVersion,
+  recordAbsorption,
+  DEDUP_EMBED_FORM_VERSION,
   snapshotIdeas,
   spinRoulette,
   rankRoulette,
@@ -274,8 +296,18 @@ import {
   resolveJiraAdapter,
   makeBacklogIO,
   harmonizeBacklog,
+  transitionIdeas,
   BACKLOG_BACKENDS,
   applyDomainBoost,
+  DZ_OWNED_TASK_TYPES,
+  applyExportHoldout,
+  DEFAULT_HELD_OUT_DOMAINS,
+  canonicalDomainKey,
+  readAgentdbRowsByTaskType,
+  heldOutAfterOptIn,
+  renderHoldoutNote,
+  renderSharedStoreAdvice,
+  decideVectorExport,
   countDisplacedByCut,
   renderDomainBoostNote,
   renderDomainCutNote,
@@ -284,7 +316,18 @@ import {
   settleReqeDebt,
   renderReqeList,
   REQE_SCOPE,
+  // Mutation gate (feature ha-mutation-gate) — break each named protection, run the suite, require red.
+  parseMutationRegistry,
+  applyMutationToText,
+  countFailingTests,
+  classifyBaseline,
+  classifyRunFailure,
+  classifyMutationOutcome,
+  mutationGateExitCode,
+  summarizeMutationResults,
+  renderMutationReport,
 } from '@dzhechkov/harness-core';
+import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
 import type { IdeaRecord, IdeaStatus } from '@dzhechkov/harness-core';
 import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
@@ -306,7 +349,12 @@ Usage:
   dz migrate [--project <dir>]
   dz create-skill --name <id> [--description <text>] [--skills-dir <dir>] [--tier <1-3>] [--with-references] [--no-evals] [--bto]
   dz scout   [--topics <list>] [--since <date>] [--deep] [--output <file>] [--diff] [--report]
-  dz workflow <task> [--dry-run]
+  dz workflow init --name <n> [--pattern pipeline|barrier|fanout|gate] [--o <plan.json>]   (scaffold a loop-plan/1 plan)
+  dz workflow validate <plan.json> [--json]                 (schema + INV-1..8 checks; CI-runnable, non-zero on failure)
+  dz workflow render <plan.json> --o <script.js> [--check] [--force]   (plan → region-delimited loop script; USER regions preserved)
+  dz workflow blobs [--check]                               (list/self-check the subsystem blob registry)
+  dz workflow-lint <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   (layer-1 gate; exit 0/1/3 — inconclusive is never a pass)
+  dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]   (timeline + SEQ invariant runner)
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
   dz doctor  [--project <dir>] [--pubkey <path>] [--require-signing]   (health + signature check of installed packs)
@@ -325,11 +373,15 @@ Usage:
   dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
   dz reqe [--slug <feature> [--done --report <f>]] [--json]   (the re-QE debt ledger: a usage-switched run whose Step-8 QE ran on the coder's OWN family records a debt; list debts, print the cross-family review brief, settle FAIL-CLOSED against a graded report — the settlement lands in 08_qe_report.md)
+  dz mutation-gate [--package <dir>] [--registry <file>] [--test-cmd "<cmd>"] [--only <id[,id]>] [--timeout <ms>] [--rebaseline per-entry|final] [--keep-scratch] [--json]   (prove each NAMED protection has a test that DISCRIMINATES: copy the package to a scratch dir, verify the baseline suite is green, apply each registry mutation, run the suite, REQUIRE red, restore. The red must be BEHAVIOURAL: a mutation that no longer parses is MUTATION_UNPARSEABLE; a red run whose OWN output reports a test FILE failing to load (node --test file-level not-ok with exitCode, vitest Failed Suites) is MUTATION_LOAD_FATAL — the signal comes from the same run as the failing count, never from a separate isolated import; red output whose shape matches no known runner is INCONCLUSIVE (a runner-coverage gap, loud, never PROVEN); a count far above the entry's bound is OVER_FAILING; a restored tree that does not reproduce green makes the entry INCONCLUSIVE (flaky). Mutation writes are realpath-contained to the scratch copy: a symlink escape or a node_modules/ target is refused (exit 2), the real tree is never written. A mutation that does not apply, a green suite, or an inconclusive run is a FAILURE — never a skip. exit 0 all proven / 1 gate failed / 2 setup error)
   dz backlog add "<idea>" [--effort 1-5] [--proposal <text>] [--dry-run] [--project <dir>] [--json]   (capture an idea: semantic dedup against existing ideas via the Brain vector engine (DUPLICATE>=0.92 merges, RELATED links, NEW creates) + GoalMap alignment; --dry-run classifies without writing)
   dz backlog list [--status <s>] [--goal <id>] [--project <dir>] [--json]   (list captured ideas, filterable by status/goal)
   dz backlog show <id> [--project <dir>] [--json]                          (full record for one idea)
   dz backlog goals [--validate] [--project <dir>] [--json]                 (list/validate the compass at .dz/backlog/goals.json)
-  dz backlog roulette [--pick <N>] [--seed <n>] [--commit] [--project <dir>] [--json]   (WEIGHTED draw over eligible ideas: alignment^alpha * recencyDecay * 1/effort, seeded; --pick N = ranked shortlist; --commit flips the pick to in-progress (the only mutation))
+  dz backlog roulette [--pick <N>] [--seed <n>] [--commit] [--project <dir>] [--json]   (WEIGHTED draw over eligible ideas: alignment^alpha * recencyDecay * 1/effort, seeded; --pick N = ranked shortlist; --commit flips the pick to in-progress)
+  dz backlog ship <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (mark work DONE: new|enriched|in-progress → shipped, removing it from the roulette pool — run it after finishing a task; short id prefixes ok, ambiguous = loud error)
+  dz backlog drop <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (retire an idea: new|enriched|in-progress → dropped)
+  dz backlog reopen <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (back to the pool: shipped|dropped|in-progress → new)
   dz backlog enrich <id> [--project <dir>] [--json]                        (stage the idea2prd input scaffold in features/<slug>/ and hand off to the idea2prd-manual skill — the CLI never fabricates a PRD)
   dz backlog jira <id> [--project <dir>] [--json]                          (draft a Jira issue via the configurable adapter (backlog.jira.adapter: jira-mcp|copilot-mcp|none); none writes an auditable jira-outbox/<id>.json stub)
   dz backlog harmonize [--apply] [--threshold <0-1>] [--project <dir>] [--json]   (batch semantic dedup of the backlog ideas; --dry-run default, --apply snapshots first)
@@ -379,7 +431,7 @@ Usage:
   dz import-ecc [--local-path <dir>] [--select id,id,...] [--limit N] [--output <dir>] [--force]
   dz help
 
-Workflows: coverage-lift, mutation-kill, canonicalize, security-audit
+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(', ')}
 Presets: ${PRESET_NAMES.join(', ')}`;
@@ -401,6 +453,13 @@ export interface CliIo {
    * without spawning anything.
    */
   readonly releaseRunner?: ReleaseExecRunner;
+  /**
+   * Test seam for `dz install`: overrides the `npm install` subprocess (production leaves
+   * it unset → real `execSync`, stdio piped). A stub runner that pre-stages a fixture
+   * package under `node_modules/` makes `cmdInstall`'s layout resolution testable
+   * offline, hermetically — mirrors the {@link CliIo.releaseRunner} idiom.
+   */
+  readonly installRunner?: (command: string, cwd: string) => void;
 }
 
 /** Injected subprocess runner used by `dz release` (see {@link CliIo.releaseRunner}). */
@@ -840,28 +899,310 @@ async function cmdScout(options: Map<string, string>, flags: Set<string>, cwd: s
   }
 }
 
+/** Scaffold plans for `dz workflow init` — one per pattern (each validates + renders lint-clean:
+ * the ADR-002 property "the generator cannot emit a script its own lint rejects" is enforced by
+ * workflow-init-lint-clean.test.ts, not convention). */
+function workflowInitPlan(name: string, pattern: string): object {
+  const base = {
+    schema: 'loop-plan/1',
+    name,
+    description: `TODO: describe the ${name} loop`, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+    whenToUse: `TODO: when to invoke ${name}`, // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+    checkpointing: { enabled: false },
+    subsystems: { checkpoints: false, trainingPairs: false, usageAdaptive: false, challengePanel: false, codexDispatch: false },
+    trace: { emit: true },
+  };
+  if (pattern === 'pipeline') {
+    return {
+      ...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: 'jn', kind: 'join', phase: 'Work', deps: ['fan'] },
+      ],
+      fanouts: [{ stage: 'fan', registry: ['item1', 'item2', 'item3'], maxFanout: 3, chain: ['a', 'b'] }],
+      joins: [{ stage: 'jn', forStage: 'fan', joinPolicy: 'all-activated', onInvalid: 'named-failure' }],
+    };
+  }
+  if (pattern === 'fanout' || pattern === 'barrier') {
+    return {
+      ...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: '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)
+      ],
+      fanouts: [{ stage: 'fan', registry: ['lane1', 'lane2', 'lane3'], maxFanout: 3, chain: ['lane'] }],
+      joins: [{ stage: 'jn', forStage: 'fan', joinPolicy: 'all-activated', onInvalid: 'named-failure' }],
+    };
+  }
+  if (pattern === 'gate') {
+    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)
+      ],
+      gates: [{ stepId: 'gate', kind: 'parse-verdict', failRoute: 'work', maxRedos: 1 }],
+    };
+  }
+  // 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)
+  };
+}
+
+/**
+ * `dz workflow` — the loop-designer authoring verbs (ADR-002; the ADR-005 template emitter is
+ * RETIRED — AM-6). Subverbs: init | validate | render | blobs. Any other invocation (including
+ * every legacy `--task <name>` / `--name <name>` / bare positional template spelling) prints the
+ * pinned retirement message and exits 1 — no legacy format is silently reachable.
+ */
 function cmdWorkflow(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
-  const taskName = options.get('task') ?? options.get('name') ?? '';
-  if (taskName === '' || !WORKFLOW_NAMES.includes(taskName)) {
-    write(`dz workflow: specify a task — one of: ${WORKFLOW_NAMES.join(', ')}`);
+  const sub = options.get('_positional_0') ?? '';
+  const legacyTask = options.get('task') ?? options.get('name');
+
+  if (sub === 'init') {
+    const name = options.get('name') ?? options.get('_positional_1') ?? 'my-loop';
+    const pattern = options.get('pattern') ?? 'pipeline';
+    const outPath = resolve(cwd, options.get('o') ?? options.get('out') ?? `${name}.plan.json`);
+    const planObj = workflowInitPlan(name, pattern);
+    const parsed = parsePlan(planObj);
+    if (isParseErrors(parsed)) {
+      write(`dz workflow init: internal scaffold error — ${parsed.map((e) => e.message).join('; ')}`);
+      return 1;
+    }
+    const diags = validatePlan(parsed);
+    if (diags.length > 0) {
+      write(`dz workflow init: internal scaffold failed validation — ${diags.map((d) => `${d.invariant} ${d.message}`).join('; ')}`);
+      return 1;
+    }
+    writeFileSync(outPath, JSON.stringify(normalizePlan(parsed), null, 2) + '\n');
+    write(`dz workflow init: wrote ${outPath} (pattern: ${pattern})`);
+    write('Next: edit the TODO prompts, then `dz workflow validate` + `dz workflow render`.'); // no-stubs: workflow-init scaffold sentinel the author replaces (deliberate authoring cue, not unfinished code)
+    return 0;
+  }
+
+  if (sub === 'validate') {
+    const planPath = options.get('_positional_1') ?? options.get('plan') ?? '';
+    if (planPath === '') {
+      write('dz workflow validate: usage — dz workflow validate <plan.json> [--json]');
+      return 1;
+    }
+    const abs = resolve(cwd, planPath);
+    if (!existsSync(abs)) {
+      write(`dz workflow validate: no such plan file: ${abs}`);
+      return 1;
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(abs, 'utf8'));
+    } catch (e) {
+      write(`dz workflow validate: unparseable JSON — ${e instanceof Error ? e.message : String(e)}`);
+      return 1;
+    }
+    const parsed = parsePlan(raw);
+    if (isParseErrors(parsed)) {
+      if (flags.has('json')) write(JSON.stringify({ ok: false, parseErrors: parsed }, null, 2));
+      else for (const e of parsed) write(`PARSE ${e.path}: ${e.message}`);
+      return 1;
+    }
+    const diags = validatePlan(parsed);
+    if (flags.has('json')) {
+      write(JSON.stringify({ ok: diags.length === 0, digest: planDigest(parsed), diagnostics: diags }, null, 2));
+    } else {
+      for (const d of diags) write(`${d.invariant} ${d.path}: ${d.message}`);
+      write(diags.length === 0 ? `dz workflow validate: OK (digest sha256:${planDigest(parsed).slice(0, 16)}…)` : `dz workflow validate: ${diags.length} invariant violation(s)`);
+    }
+    return diags.length === 0 ? 0 : 1;
+  }
+
+  if (sub === 'render') {
+    const planPath = options.get('_positional_1') ?? options.get('plan') ?? '';
+    const outPath = options.get('o') ?? options.get('out') ?? '';
+    if (planPath === '' || outPath === '') {
+      write('dz workflow render: usage — dz workflow render <plan.json> -o <script.js> [--check] [--force]');
+      return 1;
+    }
+    const absPlan = resolve(cwd, planPath);
+    if (!existsSync(absPlan)) {
+      write(`dz workflow render: no such plan file: ${absPlan}`);
+      return 1;
+    }
+    const parsed = parsePlan(JSON.parse(readFileSync(absPlan, 'utf8')));
+    if (isParseErrors(parsed)) {
+      for (const e of parsed) write(`PARSE ${e.path}: ${e.message}`);
+      return 1;
+    }
+    const diags = validatePlan(parsed);
+    if (diags.length > 0) {
+      for (const d of diags) write(`${d.invariant} ${d.path}: ${d.message}`);
+      write('dz workflow render: refusing to render an invalid plan');
+      return 1;
+    }
+    const rendered = renderPlan(parsed);
+    const absOut = resolve(cwd, outPath);
+    const sidecar = absOut.replace(/\.js$/, '') + '.plan.json';
+    const prev = existsSync(absOut) ? readFileSync(absOut, 'utf8') : '';
+    const merged = prev === '' ? { text: rendered.text, conflicts: [], refused: false } : mergeRender(prev, rendered, { force: flags.has('force') });
+    if (flags.has('check')) {
+      const same = prev === merged.text && !merged.refused;
+      write(same ? 'dz workflow render --check: up to date' : 'dz workflow render --check: DRIFT — a fresh render differs from the file on disk');
+      return same ? 0 : 1;
+    }
+    if (merged.refused) {
+      const proposed = absOut + '.proposed.js';
+      writeFileSync(proposed, merged.proposedText ?? rendered.text);
+      write(`dz workflow render: ${absOut} carries NO region markers (hand-written loop) — REFUSING to overwrite.`);
+      write(`Proposed render written to ${proposed}; re-run with --force to replace the target.`);
+      return 1;
+    }
+    // sidecar plan FIRST, independently of the script (FR-4.1 — the oracle diffs against it)
+    writeFileSync(sidecar, rendered.planJson);
+    writeFileSync(absOut, merged.text);
+    for (const c of merged.conflicts) write(`CONFLICT step ${c.stepId}: ${c.reason}`);
+    write(`dz workflow render: wrote ${sidecar} then ${absOut} (exec-fp sha256:${rendered.execFingerprint.slice(0, 16)}…, blobs: ${rendered.manifest.blobs.map((b) => b.name).join(', ') || 'none'})`);
+    write('Gate it: dz workflow-lint ' + outPath + ' --plan ' + sidecar + ' --require-plan');
+    return merged.conflicts.length > 0 ? 1 : 0;
+  }
+
+  if (sub === 'blobs') {
+    let bad = 0;
+    for (const b of Object.values(LOOP_BLOBS)) {
+      const actual = createHash('sha256').update(b.code, 'utf8').digest('hex');
+      const ok = actual === b.contentHash;
+      if (!ok) bad++;
+      write(`${b.name}@${b.version} sha256:${b.contentHash.slice(0, 16)}… ${ok ? 'OK' : 'HASH MISMATCH (loop-blobs.generated.ts was hand-edited — regenerate: node scripts/gen-loop-blobs.mjs)'} (requires: [${b.requires.join(', ')}])`);
+    }
+    if (flags.has('check')) {
+      write(bad === 0 ? 'dz workflow blobs --check: registry self-consistent (authoritative canon-vs-committed diff runs in CI via loop-blobs-regen.test.ts / scripts/gen-loop-blobs.mjs --check)' : `dz workflow blobs --check: ${bad} blob(s) inconsistent`);
+      return bad === 0 ? 0 : 1;
+    }
+    return 0;
+  }
+
+  // Everything else — the retired ADR-005 surface, BOTH spellings (bare positional task name and
+  // --task/--name) — prints the pinned shim message. AM-6: never silently reachable.
+  void legacyTask;
+  void flags;
+  write(WORKFLOW_TEMPLATES_RETIRED_MESSAGE);
+  return 1;
+}
+
+/** `dz workflow-lint` — layer-1 gate; exit 0/1/3 (pass/fail/inconclusive — INV-13: inconclusive is
+ * never a pass; the exit convention mirrors consult-gate). */
+function cmdWorkflowLint(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const scriptPath = options.get('_positional_0') ?? '';
+  if (scriptPath === '') {
+    write('dz workflow-lint: usage — dz workflow-lint <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]');
     return 1;
   }
-  const wf = getWorkflow(taskName);
-  if (wf === undefined) {
-    write(`dz workflow: unknown task ${JSON.stringify(taskName)}`);
+  const absScript = resolve(cwd, scriptPath);
+  if (!existsSync(absScript)) {
+    write(`dz workflow-lint: no such script: ${absScript}`);
     return 1;
   }
-  const projectRoot = resolve(cwd, options.get('project') ?? '.');
-  const script = wf.generate({ projectRoot, dryRun: flags.has('dry-run') });
+  const scriptText = readFileSync(absScript, 'utf8');
+  const planPath = options.get('plan');
+  let plan = null;
+  let digestValue: string | null = null;
+  if (planPath !== undefined) {
+    const absPlan = resolve(cwd, planPath);
+    if (!existsSync(absPlan)) {
+      write(`dz workflow-lint: no such plan: ${absPlan}`);
+      return 1;
+    }
+    const parsed = parsePlan(JSON.parse(readFileSync(absPlan, 'utf8')));
+    if (isParseErrors(parsed)) {
+      for (const e of parsed) write(`PARSE ${e.path}: ${e.message}`);
+      return 1;
+    }
+    plan = parsed;
+    digestValue = planDigest(parsed);
+  }
+  const mode = flags.has('require-plan') ? 'require-plan' : flags.has('legacy') ? 'legacy' : 'default';
+  const run = lint(scriptText, { plan, planDigestValue: digestValue, blobRegistry: LOOP_BLOBS, mode });
+  if (flags.has('json')) {
+    write(JSON.stringify(run, null, 2));
+  } else {
+    for (const f of run.findings) {
+      write(`${f.severity.toUpperCase().padEnd(12)} ${f.rule}: ${f.message}${f.anchor ? ` [anchor: ${f.anchor}]` : ''}`);
+    }
+    const counts = { fail: 0, warn: 0, inconclusive: 0 };
+    for (const f of run.findings) if (f.severity in counts) counts[f.severity as keyof typeof counts]++;
+    write(`dz workflow-lint: ${run.verdict.toUpperCase()} (mode=${run.mode}; ${counts.fail} fail, ${counts.warn} warn, ${counts.inconclusive} inconclusive over ${Object.keys(run.rules).length} rules)`);
+    if (run.verdict === 'inconclusive') write('inconclusive is NOT a pass (exit 3) — bind a plan (--plan … --require-plan) or acknowledge a legacy script with --legacy');
+  }
+  return lintExitCode(run);
+}
 
-  write(`// Dynamic Workflow: ${wf.name}`);
-  write(`// ${wf.description}`);
-  write('');
-  write(script);
-  write('');
-  write(`// To execute: paste the above into Claude Code with Opus 4.8+ and "ultracode" enabled.`);
-  write(`// Or save to a .js file and run: claude "Execute this workflow" < workflow.js`);
-  return 0;
+/** `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). */
+function cmdWorkflowTrace(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const runDirArg = options.get('_positional_0');
+  const slug = options.get('slug');
+  const runId = options.get('run');
+  let runDir: string;
+  if (runDirArg !== undefined && runDirArg !== '') runDir = resolve(cwd, runDirArg);
+  else if (slug !== undefined) runDir = resolve(cwd, 'features', slug);
+  else if (runId !== undefined) runDir = resolve(cwd, '.dz', 'loop-trace', runId);
+  else {
+    write('dz workflow-trace: usage — dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]');
+    return 1;
+  }
+  const traceFile = join(runDir, 'trace.jsonl');
+  if (!existsSync(traceFile)) {
+    write(`dz workflow-trace: no trace.jsonl under ${runDir} (the loop writes its own trace only when the plan sets trace.emit: true)`);
+    return 1;
+  }
+  const traceText = readFileSync(traceFile, 'utf8');
+  const ckptFile = join(runDir, '.fa-state', 'checkpoints.jsonl');
+  const ledgerFile = resolve(cwd, '.dz', 'feature-adr', 'run-cost-ledger.jsonl');
+  const journalFile = join(runDir, 'journal.jsonl');
+  const timeline = assembleTimeline({
+    trace: traceText,
+    checkpoints: existsSync(ckptFile) ? readFileSync(ckptFile, 'utf8') : null,
+    ledger: existsSync(ledgerFile) ? readFileSync(ledgerFile, 'utf8') : null,
+    journal: existsSync(journalFile) ? readFileSync(journalFile, 'utf8') : null,
+  });
+  let verdicts: ReturnType<typeof runInvariants> = [];
+  let projection: ReturnType<typeof toTraceProjection> | null = null;
+  const invariantsPlan = options.get('invariants');
+  if (invariantsPlan !== undefined) {
+    const absPlan = resolve(cwd, invariantsPlan);
+    if (!existsSync(absPlan)) {
+      write(`dz workflow-trace: no such plan: ${absPlan}`);
+      return 1;
+    }
+    const parsed = parsePlan(JSON.parse(readFileSync(absPlan, 'utf8')));
+    if (isParseErrors(parsed)) {
+      for (const e of parsed) write(`PARSE ${e.path}: ${e.message}`);
+      return 1;
+    }
+    projection = toTraceProjection(parsed);
+    verdicts = runInvariants(projection, parseTrace(traceText));
+  }
+  const htmlOut = options.get('html');
+  if (htmlOut !== undefined) {
+    const absHtml = resolve(cwd, htmlOut);
+    writeFileSync(absHtml, renderTimelineHtml(timeline, projection, verdicts));
+    write(`dz workflow-trace: wrote ${absHtml} (self-contained: mermaid topology + HTML waterfall)`);
+  }
+  if (flags.has('json')) {
+    write(JSON.stringify({ timeline, verdicts }, null, 2));
+    return verdicts.some((v) => v.status === 'fail') ? 1 : 0;
+  }
+  write(`run ${timeline.runId ?? '(unknown)'}${timeline.incomplete ? ' — INCOMPLETE (no run.closed; unflushed tail may be lost)' : ''}; sources: ${timeline.sources.join(', ')}`);
+  for (const r of timeline.rows.filter((x) => x.kind === 'trace')) {
+    write(`  ${String(r.seq).padStart(5)}  ${r.label}  ${r.detail}${r.wallTime ? `  [wall ${r.wallTime} — diagnostic only]` : ''}`);
+  }
+  for (const v of verdicts) write(`INVARIANT ${v.status.toUpperCase().padEnd(12)} ${v.id}: ${v.message}`);
+  return verdicts.some((v) => v.status === 'fail') ? 1 : 0;
 }
 
 function cmdMigrate(options: Map<string, string>, cwd: string, write: Write): number {
@@ -1015,7 +1356,13 @@ function cmdBundle(options: Map<string, string>, flags: Set<string>, cwd: string
   return 0;
 }
 
-async function cmdInstall(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+async function cmdInstall(
+  options: Map<string, string>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+  installRunner?: (command: string, cwd: string) => void,
+): Promise<number> {
   const pkg = options.get('_positional_0');
   if (!pkg) {
     write('dz install: package name required (e.g., dz install @dzhechkov/skills-devops)');
@@ -1030,10 +1377,12 @@ async function cmdInstall(options: Map<string, string>, flags: Set<string>, cwd:
 
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
 
-  // Step 1: npm install the package
+  // Step 1: npm install the package (installRunner is the CliIo test seam — unset in production)
   write(`Installing ${pkg}...`);
+  const installCmd = `npm install ${pkg} --save-dev --no-fund --no-audit`;
   try {
-    execSync(`npm install ${pkg} --save-dev --no-fund --no-audit`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf-8' });
+    if (installRunner) installRunner(installCmd, projectRoot);
+    else execSync(installCmd, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf-8' });
   } catch (err) {
     write(`dz install: npm install failed — ${err instanceof Error ? err.message : String(err)}`);
     return 1;
@@ -1046,19 +1395,22 @@ async function cmdInstall(options: Map<string, string>, flags: Set<string>, cwd:
     return 1;
   }
 
-  // Discover skills — look for dirs containing SKILL.md
-  const entries = readdirSync(pkgDir, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && existsSync(join(pkgDir, e.name, 'SKILL.md')));
-
-  if (entries.length === 0) {
-    write(`dz install: no SKILL.md files found in ${pkg}. Package may not contain agentskills.io skills.`);
-    return 0;
+  // Resolve the package's skills root across the known layouts (flat / npx-template /
+  // skills-dir) — feature dz-install-npx-init. Total resolution failure is an ERROR
+  // (exit 1), not the old advisory exit 0: a user asking to install skills that were
+  // not installed must not see success.
+  const roots = resolvePackageSkillRoots(pkgDir);
+  if (roots.length === 0) {
+    write(`dz install: no SKILL.md found in ${pkg}. Probed: ${PACKAGE_SKILL_LAYOUTS.map((l) => l.rel).join(', ')}.`);
+    write(`If this package installs itself, try: npx -y ${pkg} init`);
+    return 1;
   }
+  const root = roots[0]!;
 
-  // Step 3: Use dz init with the package as skills source
+  // Step 3: Use dz init with the resolved skills root as source
   const report = await runInit({
     target: targetOpt,
-    skillsDir: pkgDir,
+    skillsDir: root.dir,
     projectRoot,
     force: flags.has('force'),
   });
@@ -1066,10 +1418,16 @@ async function cmdInstall(options: Map<string, string>, flags: Set<string>, cwd:
   const totalWritten = report.skills.reduce((sum, s) => sum + s.written.length, 0);
   const totalSkipped = report.skills.reduce((sum, s) => sum + s.skipped.length, 0);
 
-  write(`dz install ${pkg}: ${report.skills.length} skill(s), ${totalWritten} file(s) written, ${totalSkipped} skipped`);
+  // Non-flat resolutions are tagged so a mis-resolution is legible in a user's paste;
+  // flat output stays byte-identical to the pre-feature behavior (NFR-1 / test T5.6).
+  const layoutTag = root.layout === 'flat' ? '' : ` [layout: ${root.layout}]`;
+  write(`dz install ${pkg}: ${report.skills.length} skill(s), ${totalWritten} file(s) written, ${totalSkipped} skipped${layoutTag}`);
   for (const skill of report.skills) {
     write(`  ${skill.id}: ${skill.written.length} written, ${skill.skipped.length} skipped`);
   }
+  if (root.layout === 'npx-template' && root.hasCompanionAssets) {
+    write(`  note: ${pkg} also ships commands/hooks/agents — \`npx -y ${pkg} init\` installs the full kit.`);
+  }
   return 0;
 }
 
@@ -1778,6 +2136,22 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     }
     write(`Imported ${imported} pattern(s) from ${fromJson}`);
     write(`  Skipped ${skipped} (duplicates already in the store, or invalid entries)`);
+    // Bulk import preserves the DOMAIN of every record, so it can put medical lessons in
+    // a shared store as silently as a hand-typed teach — and it returned before the
+    // advice single-teach prints. The same advice, at the same point in the flow: after
+    // the write, naming the choice, blocking nothing.
+    let resolvedImportRoot = projectRoot;
+    try { resolvedImportRoot = realpathSync(projectRoot); } catch { /* unresolvable is not the brain */ }
+    const importedMedical = importedRecs.filter(
+      (r) => DEFAULT_HELD_OUT_DOMAINS.map(canonicalDomainKey).includes(canonicalDomainKey(r.domain)),
+    );
+    if (importedMedical.length > 0) {
+      const advice = renderSharedStoreAdvice(importedMedical[0]?.domain, resolvedImportRoot);
+      if (advice !== '') {
+        write(`  ⚠ ${importedMedical.length} of the imported lesson(s) carry a medical domain.`);
+        write(advice);
+      }
+    }
     write(`  Backend: memory (@dzhechkov/memory)  Total now: ${loadStorePatternsSync(projectRoot).length}`);
     // ONE batched mirror call through the same seam as single-teach (QR-6 — no bespoke path).
     await emitMirror(projectRoot, importedRecs, 'dz-teach-import');
@@ -1876,6 +2250,16 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   write(`Learned: "${pattern.slice(0, 60)}${pattern.length > 60 ? '...' : ''}"`);
   write(`  Domain: ${domain}  Reward: ${reward}  Backend: memory (@dzhechkov/memory)`);
   write(`  Total patterns: ${count}`);
+  // ADVICE, not a gate. Someone putting medical lessons in a shared store owns both
+  // directories and this binary; refusing would be defending a user against themselves,
+  // which this design does not attempt. Making the choice INFORMED is the part that is
+  // ours to do — the write has already happened when this prints.
+  // RESOLVE before deciding. A symlink named `.health-brain` pointing at a shared project
+  // silenced this advice in exactly the case it exists for.
+  let resolvedRoot = projectRoot;
+  try { resolvedRoot = realpathSync(projectRoot); } catch { /* a path we cannot resolve is not the brain */ }
+  const sharedAdvice = renderSharedStoreAdvice(domain, resolvedRoot);
+  if (sharedAdvice !== '') write(sharedAdvice);
   if (quarantineOn) {
     write('  ⚠ quarantined: excluded from auto-inject, damped in recall — promote by confirming it (dz teach --reinforce "<text>") or dz recall --promote <dzId> --apply');
   }
@@ -2029,13 +2413,41 @@ function fmtUsageRow(row: RecallUsagePatternRow): string {
 }
 
 function cmdRecallUsage(options: Map<string, string>, flags: Set<string>, projectRoot: string, write: Write): number {
-  const report = readRecallUsageReport(projectRoot);
+  const raw = readRecallUsageReport(projectRoot);
+  // The hold-out applies to EVERY surface that hands out lesson TEXT, not only to the
+  // one labelled "export". `--usage --json` prints whole lessons in its `top` and
+  // `neverRead` lists, so it is an export by behaviour whatever it is called — a
+  // self-audit before review found health-research lesson text sitting in both. A
+  // guarantee that covers only the surface you were thinking about is not a guarantee.
+  const heldOut = heldOutAfterOptIn(options.get('include-domain'));
+  // EVERY list of records, not the two that were obvious. A first pass held out `top`
+  // and `neverRead` and a health lesson still came out — in `all`, a third list further
+  // down the same object. Enumerating the lists you remembered is how the surface leaks.
+  const top = applyExportHoldout(raw.top, heldOut);
+  const neverRead = applyExportHoldout(raw.neverRead, heldOut);
+  // `unknown` is deliberately NOT held out: RecallUsageStat carries counters and
+  // timestamps only — no domain, no lesson text — so there is nothing in it to withhold.
+  // Filtering it would be theatre, and theatre in a privacy control is worse than a gap
+  // because it looks like coverage.
+  const every = applyExportHoldout(raw.all ?? [], heldOut);
+  const withheld = top.withheld.length + neverRead.withheld.length + every.withheld.length;
+  const report = {
+    ...raw,
+    top: top.exported,
+    neverRead: neverRead.exported,
+    ...(raw.all === undefined ? {} : { all: every.exported }),
+  };
+  const holdoutNote = renderHoldoutNote([top, neverRead, every]
+    .reduce((a, b) => (b.withheld.length > a.withheld.length ? b : a)));
   if (flags.has('json')) {
     write(JSON.stringify({
       ...report,
       log: join(projectRoot, RECALL_USAGE_LOG_RELATIVE),
       retention: { maxBytes: RECALL_USAGE_LOG_MAX_BYTES },
+      withheld,
+      withheldDomains: [...new Set([...top.domains, ...neverRead.domains, ...every.domains])].sort(),
     }));
+    if (withheld > 0 && holdoutNote !== '') process.stderr.write(`${holdoutNote}\n`);
     return 0;
   }
 
@@ -2060,6 +2472,9 @@ function cmdRecallUsage(options: Map<string, string>, flags: Set<string>, projec
     for (const row of report.neverRead.slice(0, displayLimit)) write(`    ${row.dzId}${row.domain !== undefined ? ` (${row.domain})` : ''} ${row.pattern.slice(0, 100)}`);
     if (report.neverRead.length > displayLimit) write(`    ... ${report.neverRead.length - displayLimit} more (use --json for the full list)`);
   }
+  if (withheld > 0 && holdoutNote !== '') {
+    write(holdoutNote);
+  }
   return 0;
 }
 
@@ -2174,15 +2589,57 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   // --all: dump the entire learned store (backend-agnostic, via loadStorePatternsSync).
   // With --json this is the portable export the agentdb-memory MCP bridge consumes.
   if (all) {
-    const patterns = loadStorePatternsSync(projectRoot);
+    // ISOLATION (health-advisor slice H, ADR-003). This command is THE portable sharing
+    // form — it is documented as such and the agentdb bridge consumes it — so it is the
+    // realistic path by which a learned store leaves this machine. `health-research`
+    // carries lessons drawn from one person's investigations and is held back unless the
+    // caller names it. This replaced a text-inspecting privacy guard that seven rounds of
+    // review could not make correct: a tag set by the writer is decidable, prose is not.
+    const allPatterns = loadStorePatternsSync(projectRoot);
+    const holdout = applyExportHoldout(allPatterns, heldOutAfterOptIn(options.get('include-domain')));
+    const patterns = holdout.exported;
+    const holdoutNote = renderHoldoutNote(holdout);
+    // The opt-in is honoured without argument — and named out loud. A flag that silently
+    // includes medical lessons in a portable export is a flag whose consequence the user
+    // has to remember; one that says what it just handed over is a flag they can act on.
+    const optedIn = options.get('include-domain');
+    if (optedIn !== undefined && optedIn.trim() !== '') {
+      // Count against the SPLIT list, the same way heldOutAfterOptIn parses it. Comparing
+      // each record to the whole unsplit string reported `0 of 2` for a comma-separated
+      // opt-in that had just exported a medical lesson — a warning that undercounts the
+      // thing it warns about is worse than none.
+      const optedKeys = new Set(optedIn.split(',').map((d) => canonicalDomainKey(d)).filter((d) => d !== ''));
+      const medicalKeys = new Set(DEFAULT_HELD_OUT_DOMAINS.map(canonicalDomainKey));
+      const releasedKeys = [...optedKeys].filter((k) => medicalKeys.has(k));
+      const releasedCount = allPatterns.filter((p) => releasedKeys.includes(canonicalDomainKey(p.domain))).length;
+      if (releasedKeys.length > 0) {
+        process.stderr.write(
+          `  ⚠ --include-domain ${releasedKeys.join(',')}: this export CONTAINS lessons from a medical `
+          + `domain (${releasedCount} of ${allPatterns.length}). They travel with the file wherever it `
+          + `goes. Nothing was blocked — this is your call.\n`,
+        );
+      }
+    }
     if (flags.has('stats')) {
-      const stats = storeStats(projectRoot);
+      // `stats` is computed from the UNFILTERED store, and `topUses` carries whole
+      // lesson text. Filtering `patterns` two lines above and serialising this untouched
+      // exported exactly what had just been withheld — found by review immediately after
+      // I had written the lesson "cover every surface", in the same function. The
+      // per-domain histogram goes too: it names the domain and its size.
+      const rawStats = storeStats(projectRoot);
+      const topHoldout = applyExportHoldout(rawStats.topUses, heldOutAfterOptIn(options.get('include-domain')));
+      const perDomain = Object.fromEntries(
+        Object.entries(rawStats.perDomain).filter(([d]) => !holdout.domains.includes(canonicalDomainKey(d))),
+      );
+      const stats = { ...rawStats, topUses: topHoldout.exported, perDomain };
       const backendStats = resolveLearningBackend(projectRoot).getStats();
       if (asJson) {
-        write(JSON.stringify({ patterns, stats, learning: backendStats }));
+        write(JSON.stringify({ patterns, stats, learning: backendStats, withheld: holdout.withheld.length, withheldDomains: holdout.domains }));
+        if (holdoutNote !== '') process.stderr.write(`${holdoutNote}\n`);
         return 0;
       }
       write(`dz recall --all --stats  —  ${patterns.length} learned pattern(s)`);
+      if (holdoutNote !== '') write(holdoutNote);
       write(`  backend: ${backendStats.backend}${backendStats.advisory !== undefined ? ` (${backendStats.advisory})` : ''}`);
       write(`  domains: ${Object.entries(stats.perDomain).map(([k, v]) => `${k}=${v}`).join(', ') || 'none'}`);
       write(`  exact-dup groups: ${stats.exactDupGroups}`);
@@ -2193,10 +2650,15 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       return 0;
     }
     if (asJson) {
+      // The note goes to STDERR so the JSON on stdout stays machine-parsable — but it is
+      // still SAID. A silent hold-out would let the reader believe they exported the whole
+      // store, and would make a broken hold-out look exactly like an empty domain.
       write(JSON.stringify(patterns));
+      if (holdoutNote !== '') process.stderr.write(`${holdoutNote}\n`);
     } else {
       write(`dz recall --all  —  ${patterns.length} learned pattern(s)`);
       for (const p of patterns) write(`  [${p.reward.toFixed(2)}] (${p.domain}) ${p.pattern.slice(0, 80)}`);
+      if (holdoutNote !== '') write(holdoutNote);
     }
     return 0;
   }
@@ -2282,6 +2744,14 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // Portable contract UNCHANGED (I-7/AC-6): a plain PatternRecord[] — round-trips through
     // `dz teach --from-json` regardless of which backend ranked each hit.
     write(JSON.stringify(hits.map((h) => h.pattern)));
+    // The honesty notes go to STDERR here rather than being skipped: the JSON branch
+    // used to return before them, so a scripted caller was told nothing about a boost
+    // that had promoted a match and pushed a visible hit past the --limit cut.
+    if (boost !== null && shownDomain !== undefined) {
+      process.stderr.write(`${renderDomainBoostNote(boost, shownDomain)}\n`);
+      const cutNoteJson = renderDomainCutNote(displaced, limit);
+      if (cutNoteJson !== '') process.stderr.write(`${cutNoteJson}\n`);
+    }
     return 0;
   }
 
@@ -2467,6 +2937,32 @@ async function cmdVector(options: Map<string, string>, flags: Set<string>, cwd:
       write('  Patterns themselves stay portable via: dz recall --all --json  (import with: dz teach --from-json)');
       return 0;
     }
+    // The vector checkpoint carries EMBEDDINGS of the lesson text, and the RVF adapter
+    // copies the whole store — there is no per-record filter to apply. So this path
+    // fails CLOSED: if the store holds a held-out domain, the export is refused unless
+    // the caller names that domain. An embedding is not plaintext, but ADR-003's
+    // question is "does patient data leave this machine?", and a checkpoint that
+    // silently carried it would answer yes while the documentation said no.
+    // JUDGE THE FILE THIS COMMAND EXPORTS. The decision itself lives in harness-core as
+    // a pure function WITH TESTS: the RVF engine is opt-in and absent on most machines,
+    // so this branch could not be exercised in a normal checkout — reasoning about a
+    // safety check I could not run is exactly what this project calls unverified.
+    const optIn = options.get('include-domain');
+    const vecHoldout = applyExportHoldout(
+      loadStorePatternsSync(projectRoot).map((p) => ({ domain: p.domain })),
+      heldOutAfterOptIn(optIn),
+    );
+    const decision = decideVectorExport({
+      rvfExists: existsSync(join(projectRoot, '.dz', 'memory', 'patterns.rvf')),
+      heldOutLexicalCount: vecHoldout.withheld.length,
+      heldOutDomains: vecHoldout.domains,
+      optedIn: optIn,
+    });
+    if (!decision.allow) {
+      write(`dz vector export: REFUSED — ${decision.reason}.`);
+      write(`  A forgotten lesson's embedding outlives its lexical record. To export anyway, naming what travels: dz vector export ${dest} --include-domain ${decision.optInHint}`);
+      return 1;
+    }
     const r = await exporter(resolve(cwd, dest));
     if (r.error !== undefined) {
       write(`dz vector export: ${r.error}`);
@@ -3437,7 +3933,7 @@ async function cmdAutoCanonicalize(options: Map<string, string>, cwd: string, wr
       write(`  ${skillName.padEnd(30)} ${path}`);
     }
 
-    write(`\nTo canonicalize, run for each skill:`);
+    write(`\nTo bring each skill into the canonical tree, run:`);
     const packDir = resolve(cwd, pack);
     for (const path of skillMds) {
       const parts = path.split('/');
@@ -3781,6 +4277,7 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     if (guardResult.verdict === 'block') write(`dz publish: ⚠ guard BLOCK overridden via --no-guard: ${noGuard} (logged)`);
     else if (guardResult.verdict === 'warn') for (const v of guardResult.violations) write(`dz publish: ⚠ guard warn — ${v.rule}: ${v.detail}`);
     else write('dz publish: ✓ guard pre-flight passed');
+    for (const n of guardResult.notes ?? []) write(`dz publish: ℹ guard note — ${n}`); // FN-7: on the record, never blocking
   }
 
   // ADR-001 (publish-provenance): decide BEFORE any work — flag validation, then a pre-flight that
@@ -4989,8 +5486,15 @@ function cmdDriftCheck(options: Map<string, string>, flags: Set<string>, cwd: st
 
 const DEFAULT_STORE_CAP = 5000;
 
-/** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number }`. Missing/broken ⇒ defaults. */
-function loadGuardConfig(root: string): { rules?: unknown[]; storeCap?: number } {
+/**
+ * Ceiling on how many changed files the no-stubs scan reads per evaluation. Deterministic (the file
+ * list is `git status` order) and fail-open: files beyond it simply have no gathered contents, so
+ * the rule reports nothing for them — a pre-flight must never become a filesystem sweep.
+ */
+const MAX_STUB_SCAN_FILES = 400;
+
+/** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number, stubWaivers?: [...] }`. Missing/broken ⇒ defaults. */
+function loadGuardConfig(root: string): { rules?: unknown[]; storeCap?: number; stubWaivers?: unknown[] } {
   const p = join(root, '.dz', 'guard.json');
   if (!existsSync(p)) return {};
   try {
@@ -5044,7 +5548,7 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
     // a resolvable workspace dep becomes its real semver (safe → the rule passes); an UNRESOLVABLE one (points at
     // no workspace package, or not a pnpm workspace) stays `workspace:*` so the rule catches a dep that WOULD ship
     // raw. That is the genuinely dangerous case the rule exists for.
-    type Manifest = { name?: string; version?: string; private?: boolean; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    type Manifest = { name?: string; version?: string; private?: boolean; license?: string; licenseHold?: unknown; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
     const manifests: Manifest[] = [];
     const located: { dir: string; m: Manifest }[] = [];
     try {
@@ -5072,6 +5576,28 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       packages.push({ name: m.name ?? '(unnamed)', deps });
     }
     facts['packages'] = packages;
+
+    // licence-hold (ADR-001, hermes-claude-adaptation): for each pack DECLARING a hold via a
+    // `licenseHold` field, hand the raw evidence to the pure checker. Best-effort: an unreadable
+    // LICENSE reads as absent (null), which the checker treats as a violation for a publishable
+    // pack — the fail direction that protects the hold, never the publish.
+    try {
+      const holds: { name: string; privateFlag: boolean; licenseText: string | null; noticesText: string | null; licenseField: string | null }[] = [];
+      for (const { dir, m } of located) {
+        if (!m || m.licenseHold === undefined || m.licenseHold === null) continue;
+        const read = (rel: string): string | null => {
+          try { return readFileSync(join(root, dir, rel), 'utf8'); } catch { return null; }
+        };
+        holds.push({
+          name: m.name ?? dir,
+          privateFlag: m.private === true,
+          licenseText: read('LICENSE'),
+          noticesText: read('THIRD_PARTY_NOTICES.md') ?? read('THIRD_PARTY_NOTICES'),
+          licenseField: typeof m.license === 'string' ? m.license : null,
+        });
+      }
+      facts['licenceHold'] = holds;
+    } catch { /* unreadable tree — the rule reports nothing rather than inventing a violation */ }
     try { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
     facts['counts'] = gatherReadmeCounts(root);
     // readme-first: from the WORKING-TREE diff (publishes happen pre-commit here), per package: does the
@@ -5127,11 +5653,26 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       }
     } catch { facts['lockfile'] = { parsed: false }; /* no lockfile (not a pnpm workspace) — rule stays silent */ }
 
-    // change: the working-tree diff, for PROMOTED (template) rules. Without this fact a rule written
-    // by `dz guard promote --apply` would be INERT — present in the config and enforcing nothing.
-    // Contents are read only for the globs an active `format-match` rule actually asks about.
+    // change: the working-tree diff — the notion of "changed" shared by PROMOTED (template) rules
+    // and the no-stubs rule. (readme-first gathers its OWN pathspec-scoped porcelain call above and
+    // does not read this fact — so the -uall widening below does not alter readme-first at all;
+    // its collapsed-untracked-dir blind spot for a brand-new package dir is a separate, documented
+    // limit of THAT gatherer.) Without this fact a rule written by
+    // `dz guard promote --apply` would be INERT — present in the config and enforcing nothing.
+    // Contents are read for the globs an active `format-match` rule asks about PLUS the changed
+    // files the no-stubs scan reads (its explicit extension allowlist, capped: a pathological
+    // change-set must not turn a pre-flight into a filesystem sweep — beyond the cap the rule
+    // simply sees no contents for the excess files, the standing fail-open contract).
     try {
-      const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf-8' });
+      // -uall (FN-1): without it, a brand-new DIRECTORY reports as one collapsed `?? newdir/` line
+      // and every file INSIDE it is invisible to the change fact — and a fresh module directory is
+      // the most stub-prone artifact there is (REPRODUCED: newdir/stub.ts with a live marker ⇒
+      // PASS/0 findings). -uall lists the individual files; `.gitignore` semantics are unchanged
+      // (git status never lists ignored paths, -uall or not — tested live). maxBuffer is raised
+      // (default 1MB) because -uall can expand a huge untracked tree into a long listing; KNOWN
+      // LIMIT: a listing beyond even this bound throws, the catch below drops the whole `change`
+      // fact, and no-stubs + every template rule go silently fail-open together for that run.
+      const status = execSync('git status --porcelain -uall', { cwd: root, encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024 });
       const files = status
         .split('\n')
         .map((l) => l.slice(3).trim())
@@ -5140,28 +5681,40 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       const formatGlobs = (Array.isArray(loadGuardConfig(root).rules) ? (loadGuardConfig(root).rules as { template?: unknown; params?: { file?: unknown } }[]) : [])
         .filter((r) => r?.template === 'format-match' && typeof r?.params?.file === 'string')
         .map((r) => r.params!.file as string);
+      const stubScannable = files.filter((f) => scannableStubPath(f));
+      const stubWanted = new Set(stubScannable.slice(0, MAX_STUB_SCAN_FILES));
+      // FN-7: fail-open must not be fail-SILENT. Count every stub-scannable changed file whose
+      // contents we do NOT gather (beyond the cap here; deleted/non-regular/oversize/read-error
+      // below) — the no-stubs rule surfaces the count as ONE aggregate note, never a violation.
+      let stubSkipped = stubScannable.length - stubWanted.size;
       const contents: Record<string, string> = {};
-      if (formatGlobs.length > 0) {
+      if (formatGlobs.length > 0 || stubWanted.size > 0) {
         for (const f of files) {
-          if (!formatGlobs.some((g) => globMatch(g, f))) continue;
+          const wanted = stubWanted.has(f);
+          if (!wanted && !formatGlobs.some((g) => globMatch(g, f))) continue;
           const abs = resolve(root, f);
           // Containment: a `git status` path is repo-relative, but `..` in one must never let the
           // LIVE reader step outside the repo the HISTORICAL reader is confined to.
-          if (abs !== root && !abs.startsWith(root + sep)) continue;
+          if (abs !== root && !abs.startsWith(root + sep)) { if (wanted) stubSkipped++; continue; }
           try {
             // lstat, NOT stat (Codex QE MED-3). `git show <sha>:<path>` yields the SYMLINK TARGET
             // TEXT, never the file it points at, so a live reader that follows links answers a
             // different question than the replay — and `/dev/zero` behind a symlink hangs the read.
             // Skipping non-regular files restores replay/live equivalence and closes the DoS.
             const st = lstatSync(abs);
-            if (!st.isFile()) continue;
-            if (st.size > MAX_CONTENT_BYTES) continue; // too large to be a spec file — undecidable, never guessed
+            if (!st.isFile()) { if (wanted) stubSkipped++; continue; }
+            if (st.size > MAX_CONTENT_BYTES) { if (wanted) stubSkipped++; continue; } // too large to be a spec file — undecidable, never guessed
             contents[f] = readFileSync(abs, 'utf8');
-          } catch { /* deleted — leave it undecidable, never guess */ }
+          } catch { if (wanted) stubSkipped++; /* deleted — leave it undecidable, never guess */ }
         }
       }
-      facts['change'] = { files, ...(Object.keys(contents).length > 0 ? { contents } : {}) };
+      facts['change'] = { files, ...(Object.keys(contents).length > 0 ? { contents } : {}), ...(stubSkipped > 0 ? { stubSkipped } : {}) };
     } catch { /* not a git repo — every template rule stays silent (fail-open) */ }
+
+    // no-stubs config waivers: `.dz/guard.json` `stubWaivers: [{path, reason}]` — path-keyed, reason
+    // MANDATORY (the feature-adr-setup --guards shape; the pure checker refuses a reasonless entry).
+    const stubWaivers = loadGuardConfig(root).stubWaivers;
+    if (Array.isArray(stubWaivers)) facts['stubWaivers'] = stubWaivers;
   }
   if (op === 'consolidate') {
     try { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
@@ -5584,6 +6137,10 @@ function cmdGuard(options: Map<string, string>, flags: Set<string>, cwd: string,
     const scaffold = {
       storeCap: DEFAULT_STORE_CAP,
       rules: DEFAULT_RULES.map((r) => ({ id: r.id, severity: r.severity, enabled: true, description: r.description })),
+      // The scaffold QUOTES the stub marker names in the no-stubs rule description, and this file is
+      // itself a scannable changed file the moment it is written — so it carries its own reasoned
+      // waiver (explicit and justified, never a silent path skip).
+      stubWaivers: [{ path: '.dz/guard.json', reason: 'the guard config quotes the stub marker names in the no-stubs rule description' }],
     };
     mkdirSync(dirname(p), { recursive: true });
     writeFileSync(p, JSON.stringify(scaffold, null, 2) + '\n');
@@ -5631,6 +6188,7 @@ function cmdGuard(options: Map<string, string>, flags: Set<string>, cwd: string,
   const glyph = result.verdict === 'block' ? '✗' : result.verdict === 'warn' ? '⚠' : '✓';
   write(`dz guard (${op}): ${glyph} ${result.verdict.toUpperCase()}  [checked: ${result.checked.join(', ') || 'no rules for this op'}]`);
   for (const v of result.violations) write(`  [${v.severity === 'hard' ? 'BLOCK' : 'warn'}] ${v.rule}: ${v.detail}`);
+  for (const n of result.notes ?? []) write(`  [note] ${n}`); // information, never a verdict input (FN-7)
   if (result.verdict === 'block' && forced) write(`  → forced through: ${force} (logged to .dz/guard-audit.jsonl)`);
   else if (result.verdict === 'block') write('  → blocked. Fix the HARD violation(s), or override with --force "<reason>" (logged).');
   return guardExitCode(result, forced);
@@ -6271,6 +6829,352 @@ function nameFor(t: { file: string; name?: string }, outcome: 'pass' | 'fail' |
   return t.name !== undefined ? { file: t.file, name: t.name, outcome } : { file: t.file, outcome };
 }
 
+/**
+ * `dz mutation-gate` — the mutation gate (feature ha-mutation-gate, SPEC at
+ * features/ha-mutation-gate/SPEC.md). A green test proves the code works; it does NOT prove the
+ * test would notice the protection being DELETED. For each entry in a declarative registry this
+ * gate applies the entry's exact {find, replace} mutation to a SCRATCH COPY of the package, runs
+ * the package's test command there, and REQUIRES a non-zero exit (red). All logic is in
+ * harness-core's pure engine (mutation-gate.ts); this is the I/O executor.
+ *
+ *   --package <dir>     the package to gate (default: cwd; must contain package.json)
+ *   --registry <file>   registry path (default: <pkg>/test/mutation-registry.json, then
+ *                       <pkg>/mutation-registry.json)
+ *   --test-cmd '<cmd>'  suite command run in the scratch copy (default: registry.testCommand,
+ *                       then `npm test`)
+ *   --only <id[,id]>    run a subset of entries (unknown id = usage error, never a silent skip)
+ *   --timeout <ms>      per-suite-run timeout (default 300000). A timed-out run is INCONCLUSIVE —
+ *                       a FAILURE, never a pass.
+ *   --rebaseline <m>    route-b guard mode: 'per-entry' (default — every red entry re-runs the
+ *                       suite on the restored tree; not green ⇒ that entry is INCONCLUSIVE) or
+ *                       'final' (one re-run at the end; not green ⇒ every red-based verdict is
+ *                       downgraded). The gate's PROVEN now means the redness was ATTRIBUTABLE.
+ *   --keep-scratch      keep the scratch copy for inspection (default: removed in a finally)
+ *   --json              machine contract {packageDir, registryPath, testCommand, rebaselineMode,
+ *                       baseline, results, summary, warnings, exitCode}
+ *
+ * The four rules (SPEC §"Four rules") and where each is enforced:
+ *   1. does-not-apply = FAILURE  → core classifyMutationOutcome (occurrences !== 1 ⇒ NOT_APPLIED);
+ *   2. green suite    = FAILURE  → core (exit 0 ⇒ UNDEFENDED, names the property);
+ *   3. never mutate the working tree → HERE: every write targets the scratch copy under tmpdir();
+ *      the repo tree is opened read-only, and a crashed run leaves at worst a stale tmp dir;
+ *   4. the gate's own discrimination proof → harness-cli/test/fixtures/mutation-gate-undefended
+ *      (the gate MUST fail on it; asserted by test/mutation-gate-cli.test.ts).
+ *
+ * Exit codes: 0 every entry PROVEN · 1 the gate ran and failed (undefended / not-applied /
+ * below-min / unparseable / load-fatal / over-failing / inconclusive entry) · 2 usage or setup
+ * error (missing registry, red BASELINE — a red unmutated copy proves nothing and must not be
+ * read as a mutation result — or an entry whose file RESOLVES outside the scratch copy: a
+ * symlink escape is refused before anything is written, SPEC rule 3).
+ */
+/**
+ * Route-a guard for `dz mutation-gate`: parse-check a MUTATED file as its own language BEFORE the
+ * suite runs. A registry mutation must delete the protection while keeping the file loadable — a
+ * file that no longer parses kills the whole suite (or its import chain), and that STRUCTURAL
+ * redness says nothing about the named protection. Returns `{error}` when a parser ran and the
+ * text does not parse; `{skipped}` (reported loudly, never silently) when no parser is available.
+ */
+function parseCheckMutatedFile(absFile: string, text: string): { error?: string; skipped?: string } {
+  interface TsLike {
+    transpileModule(t: string, o: { reportDiagnostics: boolean; compilerOptions: Record<string, unknown> }): { diagnostics?: { category: number; code: number; messageText: unknown }[] };
+    flattenDiagnosticMessageText(m: unknown, s: string): string;
+    DiagnosticCategory: { Error: number };
+    ScriptTarget: { Latest: number };
+  }
+  const ext = extname(absFile).toLowerCase();
+  try {
+    if (ext === '.ts' || ext === '.tsx' || ext === '.mts' || ext === '.cts') {
+      let ts: TsLike | null = null;
+      for (const from of [absFile, import.meta.url]) {
+        try { ts = (createRequire(from)('typescript') as TsLike); break; } catch { /* try the next resolution root */ }
+      }
+      if (ts === null) return { skipped: 'no TypeScript parser resolvable (typescript installed neither near the package nor near the CLI)' };
+      const out = ts.transpileModule(text, { reportDiagnostics: true, compilerOptions: { target: ts.ScriptTarget.Latest } });
+      const first = (out.diagnostics ?? []).find((d) => d.category === (ts as TsLike).DiagnosticCategory.Error);
+      if (first === undefined) return {};
+      return { error: `TS${first.code}: ${ts.flattenDiagnosticMessageText(first.messageText, ' ')}` };
+    }
+    if (ext === '.json') {
+      try { JSON.parse(text); return {}; } catch (e) { return { error: String((e as Error).message).slice(0, 200) }; }
+    }
+    if (ext === '.js' || ext === '.cjs' || ext === '.mjs' || ext === '') {
+      try {
+        // `node --check` on the file IN PLACE, so the nearest package.json decides the module goal.
+        execFileSync(process.execPath, ['--check', absFile], { stdio: 'pipe' });
+        return {};
+      } catch (e) {
+        const err = e as { stderr?: Buffer | string };
+        const stderrLines = String(err.stderr ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '');
+        // prefer the actual `SyntaxError: …` line over node's trailing version footer.
+        const msg = [...stderrLines].reverse().find((l) => l.includes('Error')) ?? stderrLines.at(-1) ?? 'node --check failed';
+        return { error: msg.slice(0, 200) };
+      }
+    }
+    return { skipped: `no parser for '${ext}' files — parse-check unavailable` };
+  } catch (e) {
+    return { skipped: `parse-check errored: ${String((e as Error).message).slice(0, 120)}` };
+  }
+}
+
+function cmdMutationGate(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const fail = (what: string): number => {
+    write(json ? JSON.stringify({ error: what, exitCode: 2 }) : `dz mutation-gate: ${what}`);
+    return 2;
+  };
+
+  const pkgDir = resolve(cwd, options.get('package') ?? '.');
+  if (!existsSync(join(pkgDir, 'package.json'))) {
+    return fail(`no package.json at ${pkgDir} — pass --package <dir>`);
+  }
+
+  const registryOpt = options.get('registry');
+  const registryPath = registryOpt !== undefined
+    ? resolve(cwd, registryOpt)
+    : [join(pkgDir, 'test', 'mutation-registry.json'), join(pkgDir, 'mutation-registry.json')].find((p) => existsSync(p));
+  if (registryPath === undefined || !existsSync(registryPath)) {
+    return fail(`no mutation registry found (looked for test/mutation-registry.json and mutation-registry.json under ${pkgDir}) — pass --registry <file>`);
+  }
+
+  const parsed = parseMutationRegistry(readFileSync(registryPath, 'utf-8'));
+  if (parsed.registry === null) {
+    return fail(`registry ${registryPath} is invalid:\n  - ${parsed.errors.join('\n  - ')}`);
+  }
+
+  let entries: readonly MutationRegistryEntry[] = parsed.registry.entries;
+  const only = options.get('only');
+  if (only !== undefined) {
+    const ids = only.split(',').map((s) => s.trim()).filter(Boolean);
+    const known = new Set(entries.map((e) => e.id));
+    const unknown = ids.filter((id) => !known.has(id));
+    if (unknown.length > 0) return fail(`--only names unknown entry id(s): ${unknown.join(', ')}`);
+    entries = entries.filter((e) => ids.includes(e.id));
+  }
+
+  const testCmdRaw = options.get('test-cmd') ?? parsed.registry.testCommand ?? 'npm test';
+  if (/[\0\n\r]/.test(testCmdRaw)) return fail('--test-cmd may not contain NUL or newline characters');
+  const testCmd = testCmdRaw;
+
+  const timeoutOpt = Number(options.get('timeout') ?? '300000');
+  const timeout = Number.isFinite(timeoutOpt) && timeoutOpt > 0 ? timeoutOpt : 300000;
+
+  // Route-b guard mode: `per-entry` (default, strongest — each red entry re-baselines the restored
+  // tree, so a flaky neighbour flips THAT entry to INCONCLUSIVE) or `final` (cheap — one re-run at
+  // the end; if it is not green, every red-based verdict of the run is downgraded, because any of
+  // them may have been the flake). MEASURED on the 18-entry health-advisor registry (~15s/suite
+  // run): per-entry ≈ 37 runs, final ≈ 20 runs vs 19 pre-fix. An unknown mode is a usage error.
+  const rebaselineMode = options.get('rebaseline') ?? 'per-entry';
+  if (rebaselineMode !== 'per-entry' && rebaselineMode !== 'final') {
+    return fail(`--rebaseline must be 'per-entry' or 'final', got '${rebaselineMode}'`);
+  }
+
+  // Rule 3 — NEVER mutate the working tree: the package is copied into a scratch dir we own and
+  // mutated THERE. The copy must actually be RUNNABLE (SPEC rule 3's note), which took three
+  // measured layers on the seed package:
+  //   • the package's own node_modules is symlinked back (absolute), so deps + .bin resolve;
+  //   • the copy lives inside a SHADOW of the package's repo — every ancestor level mirrors the
+  //     real one with SYMLINKED siblings (root node_modules for hoisted deps, sibling packages
+  //     for repo-relative test paths like `../../harness-core/dist`); only the package under test
+  //     is a real, mutable copy (MEASURED: without this, 30 health-advisor tests failed at
+  //     baseline on ERR_MODULE_NOT_FOUND / a missing sibling dist);
+  //   • the copy is `git init`-ed and committed, because hygiene tests take `git status` before
+  //     and after the run — they compare before WITH after, so a pre-mutation commit keeps them
+  //     discriminating (MEASURED: without it, 2 tests failed at baseline on "not a git repository").
+  const scratchParent = mkdtempSync(join(tmpdir(), 'dz-mutgate-'));
+  let gitTop: string | null = null;
+  try { gitTop = execSync('git rev-parse --show-toplevel', { cwd: pkgDir, stdio: 'pipe', encoding: 'utf-8' }).trim() || null; } catch { /* not in a git repo */ }
+  let copyDir = join(scratchParent, 'pkg');
+  const results: MutationEntryResult[] = [];
+  const observations: MutationObservation[] = [];
+  const warnings: string[] = [];
+  let baseline: ReturnType<typeof classifyBaseline>;
+  try {
+    if (gitTop !== null && gitTop !== pkgDir && resolve(pkgDir).startsWith(resolve(gitTop) + sep)) {
+      // shadow tree: mirror <gitTop>/…/<pkg> under scratch, symlinking every sibling entry.
+      let realCursor = gitTop;
+      let shadowCursor = join(scratchParent, 'root');
+      mkdirSync(shadowCursor, { recursive: true });
+      const segs = relative(gitTop, pkgDir).split(sep);
+      segs.forEach((seg, i) => {
+        for (const entry of readdirSync(realCursor)) {
+          if (entry === seg || entry === '.git') continue;
+          try { symlinkSync(join(realCursor, entry), join(shadowCursor, entry)); } catch { /* best effort */ }
+        }
+        realCursor = join(realCursor, seg);
+        shadowCursor = join(shadowCursor, seg);
+        if (i < segs.length - 1) mkdirSync(shadowCursor, { recursive: true });
+      });
+      copyDir = shadowCursor;
+    }
+    cpSync(pkgDir, copyDir, {
+      recursive: true,
+      filter: (src) => {
+        const rel = relative(pkgDir, src);
+        return rel === '' || !rel.split(sep).some((seg) => seg === 'node_modules' || seg === '.git');
+      },
+    });
+    const srcNm = join(pkgDir, 'node_modules');
+    if (existsSync(srcNm) && !existsSync(join(copyDir, 'node_modules'))) {
+      symlinkSync(srcNm, join(copyDir, 'node_modules'), 'dir');
+    }
+    try {
+      execSync('git init -q && git add -A -f . && git -c user.email=mutation-gate@dz -c user.name=mutation-gate -c commit.gpgsign=false commit -qm scratch-baseline', { cwd: copyDir, stdio: 'pipe' });
+    } catch { /* no git available → a suite that needs it fails the BASELINE loudly, never silently */ }
+
+    // F-2 — rule-3 containment root: the scratch copy AS THE FILESYSTEM sees it. Every mutation
+    // write below is asserted to RESOLVE inside this root before it happens.
+    const realScratchRoot = realpathSync(copyDir);
+
+    const runSuite = (): { exitCode: number | null; output: string } => {
+      try {
+        const out = execSync(testCmd, { cwd: copyDir, stdio: 'pipe', encoding: 'utf-8', timeout, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, FORCE_COLOR: '0' } });
+        return { exitCode: 0, output: out };
+      } catch (e) {
+        const err = e as { status?: number | null; stdout?: string; stderr?: string };
+        return {
+          exitCode: typeof err.status === 'number' ? err.status : null,
+          output: `${String(err.stdout ?? '')}\n${String(err.stderr ?? '')}`,
+        };
+      }
+    };
+
+    // Baseline BEFORE any mutation: a red copy proves nothing, and reading it as a mutation
+    // result would be this gate shipping the defect class it exists to catch.
+    if (!json) write(`mutation-gate: baseline suite in scratch copy of ${pkgDir} …`);
+    const base = runSuite();
+    baseline = classifyBaseline(base.exitCode);
+    if (!baseline.ok) {
+      if (json) { write(JSON.stringify({ packageDir: pkgDir, registryPath, testCommand: testCmd, baseline, results: [], exitCode: 2 }, null, 2)); return 2; }
+      write(renderMutationReport([], baseline, pkgDir));
+      return 2;
+    }
+
+    for (const entry of entries) {
+      const filePath = join(copyDir, entry.file);
+      let sourceText: string | null = null;
+      try { sourceText = readFileSync(filePath, 'utf-8'); } catch { /* missing file ⇒ occurrences 0 ⇒ NOT_APPLIED */ }
+      if (sourceText === null) {
+        const obs: MutationObservation = { entry, occurrences: 0, exitCode: null, failingCount: null };
+        observations.push(obs);
+        results.push(classifyMutationOutcome(obs));
+        continue;
+      }
+      const applied = applyMutationToText(sourceText, entry.mutation.find, entry.mutation.replace);
+      if (!applied.ok || applied.text === undefined) {
+        const obs: MutationObservation = { entry, occurrences: applied.occurrences, exitCode: null, failingCount: null };
+        observations.push(obs);
+        results.push(classifyMutationOutcome(obs));
+        continue;
+      }
+      // F-2 — rule-3 containment (SPEC "Never mutate the working tree"): `join(copyDir, file)` is
+      // LEXICAL; a symlink cpSync preserved inside the package (or the intentionally symlinked
+      // node_modules) makes it RESOLVE outside the scratch tree, and the "scratch" write would
+      // follow the link and mutate the REAL working tree for the whole suite run — restored only
+      // by the finally, so a SIGKILL mid-run leaves the real tree permanently mutated (MEASURED
+      // pre-fix: a registry file behind a package-local symlink; the suite-run witness read the
+      // mutated text from the REAL file). Same primitive as health-advisor lock.js's
+      // realCaseDir/assertLockRootIsItself: decide on realpaths, refuse an escape — exit 2, a
+      // registry/setup error, never a mutation.
+      let realTarget: string | null = null;
+      try { realTarget = realpathSync(filePath); } catch { /* vanished between read and here → refuse below */ }
+      if (realTarget === null || (realTarget !== realScratchRoot && !realTarget.startsWith(realScratchRoot + sep))) {
+        return fail(`entry '${entry.id}': ${entry.file} resolves to ${realTarget ?? '<unresolvable>'} — OUTSIDE the scratch copy (${realScratchRoot}). A path component is a symlink escaping the scratch tree, so writing the mutation would mutate the REAL working tree (SPEC rule 3). Refused; nothing was written.`);
+      }
+      if (!json) write(`mutation-gate: ${entry.id} — mutating ${entry.file}, running suite …`);
+      let run: { exitCode: number | null; output: string } | null = null;
+      let parseError: string | undefined;
+      try {
+        writeFileSync(filePath, applied.text);
+        // Route-a guard: the mutated file must still PARSE — a load failure reddens the whole
+        // suite for structural, not behavioural, reasons, and must never read as discrimination.
+        const check = parseCheckMutatedFile(filePath, applied.text);
+        if (check.skipped !== undefined) {
+          warnings.push(`${entry.id}: parse-check SKIPPED — ${check.skipped}`);
+          if (!json) write(`mutation-gate: WARNING ${entry.id}: parse-check skipped — ${check.skipped}`);
+        }
+        if (check.error !== undefined) {
+          parseError = check.error; // no suite run: the verdict is MUTATION_UNPARSEABLE regardless
+        } else {
+          run = runSuite();
+        }
+      } finally {
+        writeFileSync(filePath, sourceText); // restore the COPY so the next entry starts pristine
+      }
+      // Route-a′ guard (round-6 rework): the file-load-vs-assertion signal is derived from THE
+      // SAME RUN that produced the failing count — no isolated child, no environment mismatch,
+      // nothing to disagree with itself (the round-5 isolated `import()` had three measured
+      // false-PASS routes, all artifacts of the isolation environment differing from the runner).
+      // 'file-load' ⇒ MUTATION_LOAD_FATAL (structural); 'unrecognised' ⇒ INCONCLUSIVE (a
+      // runner-coverage gap of this tool, loud, never PROVEN); 'assertions' ⇒ behavioural, the
+      // count-based verdicts apply.
+      let fileLoadFailure: string | undefined;
+      let outputUnrecognised: string | undefined;
+      if (run !== null && run.exitCode !== null && run.exitCode !== 0) {
+        const cls = classifyRunFailure(run.output);
+        if (cls.kind === 'file-load') {
+          fileLoadFailure = cls.evidence ?? 'test file failed to load (no evidence line)';
+        } else if (cls.kind === 'unrecognised') {
+          outputUnrecognised = cls.evidence ?? `no classifier for runner '${cls.runner}'`;
+        }
+      }
+      // Route-b guard (per-entry mode): a red mutated run is attributable only if the RESTORED
+      // tree reproduces green — otherwise a flaky neighbour may be what went red. Skipped when the
+      // classification already failed the entry structurally (file-load / unrecognised): those
+      // verdicts outrank the rebaseline check, so the extra suite run would buy nothing.
+      let rebaselineExitCode: number | null | undefined;
+      if (rebaselineMode === 'per-entry' && run !== null && run.exitCode !== null && run.exitCode !== 0
+        && fileLoadFailure === undefined && outputUnrecognised === undefined) {
+        if (!json) write(`mutation-gate: ${entry.id} — re-baselining the restored tree …`);
+        rebaselineExitCode = runSuite().exitCode;
+      }
+      const obs: MutationObservation = {
+        entry,
+        occurrences: 1,
+        exitCode: run === null ? null : run.exitCode,
+        failingCount: run === null ? null : countFailingTests(run.output),
+        ...(parseError !== undefined ? { parseError } : {}),
+        ...(fileLoadFailure !== undefined ? { fileLoadFailure } : {}),
+        ...(outputUnrecognised !== undefined ? { outputUnrecognised } : {}),
+        ...(rebaselineExitCode !== undefined ? { rebaselineExitCode } : {}),
+      };
+      observations.push(obs);
+      results.push(classifyMutationOutcome(obs));
+    }
+
+    // Route-b guard (final mode): one re-run after all entries. Not green ⇒ EVERY red-based
+    // verdict of this run is downgraded (any of them may have been the flake, and there is no
+    // per-entry evidence to say which) — re-classifying with the final exit turns them
+    // INCONCLUSIVE while leaving NOT_APPLIED / UNDEFENDED / MUTATION_UNPARSEABLE /
+    // MUTATION_LOAD_FATAL untouched.
+    if (rebaselineMode === 'final') {
+      if (!json) write('mutation-gate: final re-baseline of the restored tree …');
+      const finalExit = runSuite().exitCode;
+      if (finalExit !== 0) {
+        const what = finalExit === null ? 'no exit code' : `exit ${finalExit}`;
+        warnings.push(`final re-baseline NOT green (${what}) — the suite is flaky; red-based verdicts downgraded to INCONCLUSIVE`);
+        if (!json) write(`mutation-gate: final re-baseline NOT green (${what}) — red-based verdicts downgraded to INCONCLUSIVE`);
+        const reclassified = observations.map((obs) => classifyMutationOutcome({ ...obs, rebaselineExitCode: finalExit }));
+        results.length = 0;
+        results.push(...reclassified);
+      }
+    }
+  } finally {
+    if (flags.has('keep-scratch')) {
+      write(`mutation-gate: scratch copy kept at ${copyDir}`);
+    } else {
+      try { rmSync(scratchParent, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+  }
+
+  const exitCode = mutationGateExitCode(results, baseline.ok);
+  if (json) {
+    write(JSON.stringify({ packageDir: pkgDir, registryPath, testCommand: testCmd, rebaselineMode, baseline, results, summary: summarizeMutationResults(results), warnings, exitCode }, null, 2));
+    return exitCode;
+  }
+  write(renderMutationReport(results, baseline, pkgDir));
+  return exitCode;
+}
+
 /**
  * `dz delivery-check` — the portable Step-10 Delivery Gate (feature portable-gates). The `manual` form that
  * travels to every `shell` target: the deterministic parts (artifact probes, hand-off arithmetic,
@@ -7350,6 +8254,21 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     const eff = parseEffort(options.get('effort'), cfg.roulette.defaultEffort);
     if (eff.adjusted && !json && eff.note !== undefined) write(`dz backlog: ${eff.note}`);
     const dryRun = flags.has('dry-run');
+    // Embed-form migration (register-inflation fix): v1 vectors are FULL-TEXT embeds, v2 queries are
+    // bounded excerpts — comparing across the forms is a query-vs-row space split. Re-mirror once
+    // (idempotent upsert), before the dedup search. Dry-run writes nothing, so it only WARNS.
+    if (dryRun) {
+      if (readBacklogEmbedFormVersion(projectRoot) < DEDUP_EMBED_FORM_VERSION && readIdeas(projectRoot).length > 0 && !json) {
+        write(`dz backlog: ⚠ idea vectors are in the old (full-text) embed form — dedup may be unreliable until a non-dry add or \`dz backlog harmonize\` migrates them`);
+      }
+    } else {
+      const form = await ensureBacklogEmbedForm(projectRoot);
+      if (form.action === 'migrated' && !json) {
+        write(`dz backlog: re-embedded ${form.remirrored} idea vector(s) into the bounded dedup embed form (v${form.version})`);
+      } else if (form.action === 'deferred' && !json) {
+        write(`dz backlog: ⚠ embed-form migration deferred (${form.error ?? 'unknown error'}) — semantic dedup may compare against stale full-text vectors`);
+      }
+    }
     const verdict = await dedupIdea(projectRoot, text, cfg);
     // The TOP-MATCH pair (id @ cosine) is the ADR-002 calibration surface (idea ce914ac2) — observational
     // only: the band itself is unchanged, but a RELATED verdict now shows WHICH idea produced the cosine.
@@ -7362,16 +8281,35 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
       // DUPLICATE ⇒ snapshot + reinforce the existing root; NO new record (ADR-002 T-002b).
       const ideas = readIdeas(projectRoot);
       const match = ideas.find((i) => i.id === verdict.matchedId);
+      let absorbErr: string | undefined;
       if (!dryRun && match !== undefined) {
         const snap = snapshotIdeas(projectRoot, join(projectRoot, '.dz', 'backlog', `ideas.pre-merge-${Date.now()}.jsonl`));
         if (snap.error !== undefined) return emitErr(snap.error);
+        // The absorbed TEXT is preserved (absorbed.jsonl) — a duplicate verdict must never destroy
+        // user text: two documented false absorptions (2026-08-05, 2026-08-11) were unrecoverable.
+        absorbErr = recordAbsorption(projectRoot, {
+          ts: new Date().toISOString(),
+          matchedId: match.id,
+          cosine: verdict.cosine,
+          ...(verdict.containment !== undefined ? { containment: verdict.containment } : {}),
+          ...(verdict.subsetMatch === true ? { subsetMatch: true } : {}),
+          text,
+        }).error;
         match.uses += 1;
         writeIdeas(projectRoot, ideas);
       }
-      if (json) write(JSON.stringify({ action: 'duplicate', matchedId: verdict.matchedId, cosine: verdict.cosine, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), exitCode: 0 }, null, 2));
+      if (json) write(JSON.stringify({ action: 'duplicate', matchedId: verdict.matchedId, cosine: verdict.cosine, ...(verdict.containment !== undefined ? { containment: verdict.containment } : {}), ...(verdict.subsetMatch === true ? { subsetMatch: true } : {}), ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), ...(dryRun ? {} : { absorbedLogged: absorbErr === undefined, ...(absorbErr !== undefined ? { absorbedLogError: absorbErr } : {}) }), exitCode: 0 }, null, 2));
       else {
-        write(`dz backlog: DUPLICATE of ${verdict.matchedId} (cosine ${verdict.cosine.toFixed(3)}${verdict.exactTextOnly ? ', exact-text' : ''}) — reinforced, no new record`);
+        const via = verdict.subsetMatch === true
+          ? `subset match: containment ${(verdict.containment ?? 0).toFixed(3)} ≥ ${cfg.dedup.subsetContainment}, cosine ${verdict.cosine.toFixed(3)}`
+          : `cosine ${verdict.cosine.toFixed(3)}${verdict.exactTextOnly ? ', exact-text' : ''}`;
+        write(`dz backlog: DUPLICATE of ${verdict.matchedId} (${via}) — reinforced, no new record`);
         if (topMatch !== undefined) write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
+        if (!dryRun) {
+          write(absorbErr === undefined
+            ? '  absorbed text kept in .dz/backlog/absorbed.jsonl (re-add it from there if this verdict was wrong)'
+            : `  ⚠ could NOT log the absorbed text (${absorbErr}) — if this verdict is wrong, the wording above is the only copy`);
+        }
       }
       return 0;
     }
@@ -7392,13 +8330,19 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     };
     const proposal = options.get('proposal');
     if (proposal !== undefined) rec.proposal = proposal; // agent prose ONLY — the CLI never fabricates it
+    // A demotion (≥-threshold cosine that failed lexical corroboration) is NEVER silent — it is the
+    // register-only false-duplicate surface (the 2026-08-05 zombie x publish-gate absorption).
+    const demotedLine = verdict.demoted !== undefined
+      ? `  near-duplicate demoted: ${verdict.demoted.id} @ cosine ${verdict.demoted.cosine.toFixed(3)} cleared the band but shares no subject vocabulary (containment ${verdict.demoted.containment.toFixed(3)} < ${cfg.dedup.corroborationFloor}) — kept as related`
+      : undefined;
     if (dryRun) {
-      if (json) write(JSON.stringify({ action: verdict.action, dryRun: true, idea: rec, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), exitCode: 0 }, null, 2));
+      if (json) write(JSON.stringify({ action: verdict.action, dryRun: true, idea: rec, ...(verdict.demoted !== undefined ? { demoted: verdict.demoted } : {}), ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), exitCode: 0 }, null, 2));
       else {
         write(`dz backlog (dry-run): ${verdict.action.toUpperCase()} — would create ${rec.id}; align ${rec.goalAlignment.toFixed(3)}${rec.goalId !== null ? ` → ${rec.goalId}` : ''}`);
         // The calibration surface belongs on the dry-run too (QE LOW-8) — a dry-run is exactly where a
         // user checks whether a near-duplicate should have crossed the band.
         if (topMatch !== undefined) write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
+        if (demotedLine !== undefined) write(demotedLine);
       }
       return 0;
     }
@@ -7409,12 +8353,13 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     ideas.push(rec);
     writeIdeas(projectRoot, ideas);
     const mirror = await mirrorIdeaVector(projectRoot, rec); // best-effort — never blocks capture
-    if (json) write(JSON.stringify({ action: verdict.action, idea: rec, related: verdict.relatedIds, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), gitignore: ignore, exitCode: 0 }, null, 2));
+    if (json) write(JSON.stringify({ action: verdict.action, idea: rec, related: verdict.relatedIds, ...(verdict.demoted !== undefined ? { demoted: verdict.demoted } : {}), ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), gitignore: ignore, exitCode: 0 }, null, 2));
     else {
       write(`dz backlog: ${verdict.action.toUpperCase()} — captured ${rec.id}`);
       if (verdict.action === 'related' && topMatch !== undefined) {
         write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
       }
+      if (demotedLine !== undefined) write(demotedLine);
       if (rec.goalId !== null) write(`  top goal: ${rec.goalId} (alignment ${rec.goalAlignment.toFixed(3)})`);
       if (verdict.relatedIds.length > 0) write(`  related: ${verdict.relatedIds.join(', ')}`);
       if (ignore.action === 'created' || ignore.action === 'appended') {
@@ -7587,6 +8532,37 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     return 0;
   }
 
+  // ── ship | drop | reopen — the status-transition surface (the missing verb that let the roulette
+  // keep re-drawing already-shipped work: without it, work finished WITHOUT `roulette --commit` —
+  // the normal flow — stayed `new` forever). ALL logic lives in transitionIdeas (harness-core):
+  // short-prefix resolution (unique or a loud error), the IDEA_TRANSITIONS legality table,
+  // idempotent no-ops, all-or-nothing fail-closed batches, line-preserving atomic writes.
+  if (sub === 'ship' || sub === 'drop' || sub === 'reopen') {
+    const prefixes: string[] = [];
+    for (let i = 1; ; i += 1) {
+      const p = options.get(`_positional_${i}`);
+      if (p === undefined) break;
+      prefixes.push(p);
+    }
+    if (prefixes.length === 0) return emitErr(`an idea id is required: dz backlog ${sub} <id> [<id>…]`);
+    const report = transitionIdeas(projectRoot, sub, prefixes, {
+      ...(options.get('reason') !== undefined ? { reason: options.get('reason')! } : {}),
+      dryRun: flags.has('dry-run'),
+    });
+    if (json) {
+      write(JSON.stringify({ verb: sub, ...report, exitCode: report.ok ? 0 : 1 }, null, 2));
+      return report.ok ? 0 : 1;
+    }
+    for (const e of report.errors) write(`dz backlog ${sub}: ${e}`);
+    for (const c of report.changes) {
+      if (c.action === 'noop') write(`dz backlog ${sub}: ${c.id} is already ${c.to} — no-op`);
+      else write(`dz backlog ${sub}${report.dryRun ? ' (dry-run)' : ''}: ${c.id} ${c.from} → ${c.to}  ${c.text}`);
+    }
+    if (!report.ok) write(`  nothing was written (all-or-nothing: fix the batch and re-run)`);
+    else if (report.dryRun && report.changes.some((c) => c.action === 'transitioned')) write('  (dry-run — nothing written; re-run without --dry-run to apply)');
+    return report.ok ? 0 : 1;
+  }
+
   if (sub === 'enrich') {
     const id = options.get('_positional_1');
     if (id === undefined) return emitErr('an idea id is required: dz backlog enrich <id>');
@@ -7632,6 +8608,11 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   if (sub === 'harmonize') {
     const apply = flags.has('apply');
     const thr = options.get('threshold');
+    // Harmonize is the batch maintenance surface — migrate the mirrored vectors to the current
+    // bounded embed form here too (idempotent; a deferral is warned, never fatal).
+    const form = await ensureBacklogEmbedForm(projectRoot);
+    if (form.action === 'migrated' && !json) write(`dz backlog: re-embedded ${form.remirrored} idea vector(s) into the bounded dedup embed form (v${form.version})`);
+    else if (form.action === 'deferred' && !json) write(`dz backlog: ⚠ embed-form migration deferred (${form.error ?? 'unknown error'})`);
     const report = await harmonizeBacklog(projectRoot, { apply, ...(thr !== undefined ? { threshold: Number(thr) } : {}) });
     if (json) {
       write(JSON.stringify({ ...report, exitCode: 0 }, null, 2));
@@ -7652,6 +8633,9 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   write('  show <id>                                              full record');
   write('  goals [--validate]                                     the compass (.dz/backlog/goals.json)');
   write('  roulette [--pick N][--seed n][--commit <id>]           weighted draw; --commit takes the id you saw');
+  write('  ship <id> [<id>…] [--reason <t>][--dry-run]            mark done (new|enriched|in-progress → shipped) — run it after finishing a task, or the roulette re-draws it forever');
+  write('  drop <id> [<id>…] [--reason <t>][--dry-run]            retire an idea (→ dropped)');
+  write('  reopen <id> [<id>…] [--reason <t>][--dry-run]          back to the pool (shipped|dropped|in-progress → new)');
   write('  enrich <id>                                            stage the idea2prd hand-off (agent expands)');
   write(`  jira <id>                                              draft a Jira issue (adapter: ${[...BACKLOG_BACKENDS].join('|')})`);
   write('  harmonize [--apply][--threshold 0-1]                   batch semantic dedup of the backlog');
@@ -7998,12 +8982,16 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return await cmdScout(options, flags, cwd, write);
       case 'workflow':
         return cmdWorkflow(options, flags, cwd, write);
+      case 'workflow-lint':
+        return cmdWorkflowLint(options, flags, cwd, write);
+      case 'workflow-trace':
+        return cmdWorkflowTrace(options, flags, cwd, write);
       case 'migrate':
         return cmdMigrate(options, cwd, write);
       case 'doctor':
         return await cmdDoctor(options, flags, cwd, write);
       case 'install':
-        return await cmdInstall(options, flags, cwd, write);
+        return await cmdInstall(options, flags, cwd, write, io.installRunner);
       case 'bundle':
         return cmdBundle(options, flags, cwd, write);
       case 'teach':
@@ -8082,6 +9070,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdChallenge(options, flags, cwd, write);
       case 'discrimination-check':
         return cmdDiscriminationCheck(options, flags, cwd, write);
+      case 'mutation-gate':
+        return cmdMutationGate(options, flags, cwd, write);
       case 'delivery-check':
         return cmdDeliveryCheck(options, flags, cwd, write);
       case 'skills-verify':