@dzhechkov/harness-cli 0.3.261 → 0.4.1

package/dist/cli.js

@@ -3,19 +3,22 @@
  *
  * @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, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, 
+import { createSkill, getSkillInfo, isTargetName, listSkills, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
 // guard-promotion (feature guard-promotion, scout idea #1)
 assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
-readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, BACKLOG_BACKENDS, applyDomainBoost, countDisplacedByCut, renderDomainBoostNote, renderDomainCutNote, parseReqeDebt, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, } from '@dzhechkov/harness-core';
+readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, ensureBacklogEmbedForm, readBacklogEmbedFormVersion, recordAbsorption, DEDUP_EMBED_FORM_VERSION, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, 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, parseReqeDebt, buildReqeBrief, 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 { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -30,7 +33,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)
@@ -49,11 +57,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)
@@ -103,7 +115,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(', ')}`;
@@ -495,27 +507,322 @@ async function cmdScout(options, flags, cwd, write) {
         return 1;
     }
 }
+/** 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, pattern) {
+    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, flags, cwd, write) {
-    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;
+        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, flags, cwd, write) {
+    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') });
-    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;
+    const scriptText = readFileSync(absScript, 'utf8');
+    const planPath = options.get('plan');
+    let plan = null;
+    let digestValue = 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]++;
+        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);
+}
+/** `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, flags, cwd, write) {
+    const runDirArg = options.get('_positional_0');
+    const slug = options.get('slug');
+    const runId = options.get('run');
+    let runDir;
+    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 = [];
+    let projection = 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, cwd, write) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
@@ -659,7 +966,7 @@ function cmdBundle(options, flags, cwd, write) {
     }
     return 0;
 }
-async function cmdInstall(options, flags, cwd, write) {
+async function cmdInstall(options, flags, cwd, write, installRunner) {
     const pkg = options.get('_positional_0');
     if (!pkg) {
         write('dz install: package name required (e.g., dz install @dzhechkov/skills-devops)');
@@ -671,10 +978,14 @@ async function cmdInstall(options, flags, cwd, write) {
         return 1;
     }
     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)}`);
@@ -686,26 +997,36 @@ async function cmdInstall(options, flags, cwd, write) {
         write(`dz install: package not found at ${pkgDir}`);
         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;
     }
-    // Step 3: Use dz init with the package as skills source
+    const root = roots[0];
+    // 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'),
     });
     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;
 }
 function cmdCompose(options, cwd, write) {
@@ -1367,6 +1688,23 @@ async function cmdTeach(options, flags, cwd, write) {
         }
         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');
@@ -1459,6 +1797,20 @@ async function cmdTeach(options, flags, cwd, write) {
     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');
     }
@@ -1626,13 +1978,42 @@ function fmtUsageRow(row) {
     return `${row.reads}×${last}${score} ${row.dzId}${domain} ${row.pattern.slice(0, 100)}`;
 }
 function cmdRecallUsage(options, flags, projectRoot, write) {
-    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;
     }
     const displayLimit = Math.max(1, parseInt(options.get('limit') ?? '20', 10) || 20);
@@ -1662,6 +2043,9 @@ function cmdRecallUsage(options, flags, projectRoot, write) {
         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;
 }
 /**
@@ -1768,15 +2152,55 @@ async function cmdRecall(options, flags, cwd, write) {
     // --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}`);
@@ -1788,12 +2212,19 @@ async function cmdRecall(options, flags, cwd, write) {
             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;
     }
@@ -1848,6 +2279,14 @@ async function cmdRecall(options, flags, cwd, write) {
     // never receive its promised lift — the feature was weakest in exactly the case it
     // exists for (foreign-domain dilution pushing a relevant lesson just past the cut).
     // Fetch a bounded surplus, re-rank, then trim to the limit the caller asked for.
+    // EVERY value that reaches an output line goes through this, not just stored fields.
+    // Round 5: `pattern` and `domain` were sanitised but the QUERY and the requested
+    // domain were not, so a caller-supplied newline could still forge a line that looks
+    // like the tool's own — including the boost note a peer reads as a capability probe.
+    // The rule is "one line out per line of output", and it has to hold for every field.
+    const oneLine = (v) => String(v).replace(/[\r\n\u2028\u2029\u0085\v\f]+/g, ' ⏎ ');
+    const shownQuery = oneLine(query);
+    const shownDomain = wantedDomain === undefined ? undefined : oneLine(wantedDomain);
     const fetchLimit = wantedDomain !== undefined ? Math.min(limit * 3, limit + 20) : limit;
     const result = await recallHybrid(projectRoot, query, { limit: fetchLimit, mode });
     if (mode === 'semantic' && result.vectorEngine === 'none') {
@@ -1870,22 +2309,31 @@ async function cmdRecall(options, flags, cwd, write) {
         // 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;
     }
     if (hits.length === 0) {
-        write(`dz recall "${query}"`);
+        write(`dz recall "${shownQuery}"`);
         write(`  No matching patterns (teach some with \`dz teach\`, or consolidate sessions).`);
         // The domain note must print here too (Codex QE #10): a --domain run with zero hits
         // silently said nothing about the domain, so the reader could not tell whether the
         // boost had been applied and found nothing, or had not run at all.
-        if (boost !== null && wantedDomain !== undefined)
-            write(renderDomainBoostNote(boost, wantedDomain));
+        if (boost !== null && shownDomain !== undefined)
+            write(renderDomainBoostNote(boost, shownDomain));
         return 0;
     }
     const vectorOn = result.vectorEngine !== 'none' && result.vectorError === undefined && mode !== 'lexical';
     const lexLabel = result.lexicalBackend === 'sqlite' ? 'SQLite FTS5' : 'keyword (JSON)';
     const ranking = vectorOn ? `${lexLabel} + vector (${result.vectorEngine}) ranking` : `${lexLabel} ranking (lexical)`;
-    write(`dz recall "${query}"  —  ${hits.length} hit(s), ${ranking}`);
+    write(`dz recall "${shownQuery}"  —  ${hits.length} hit(s), ${ranking}`);
     let sawQuarantined = false;
     for (const h of hits) {
         const backendTag = vectorOn ? ` ⟨${h.backend}⟩` : '';
@@ -1901,7 +2349,6 @@ async function cmdRecall(options, flags, cwd, write) {
         // might treat as a break — not just CR/LF. Round 4 forged the domain-boost note
         // twice over: once through `domain`, which was rendered raw, and once through a
         // U+2028 that Python's splitlines() honours and this replace did not.
-        const oneLine = (v) => v.replace(/[\r\n\u2028\u2029\u0085\v\f]+/g, ' ⏎ ');
         const shown = oneLine(h.pattern.pattern).slice(0, 80);
         write(`  [${h.pattern.reward.toFixed(2)}] (${oneLine(h.pattern.domain)})${backendTag}${qTag} ${shown}`);
     }
@@ -1909,10 +2356,10 @@ async function cmdRecall(options, flags, cwd, write) {
         // The loop stays VISIBLE (ADR D2): a quarantined hit is shown, marked, and explained.
         write('  ⚠q = quarantined (unproven hypothesis, rank damped) — confirm with dz teach --reinforce, or dz recall --promote <dzId> --apply');
     }
-    if (boost !== null && wantedDomain !== undefined) {
+    if (boost !== null && shownDomain !== undefined) {
         // Say what the boost did — INCLUDING when it did nothing. A silent reorder would
         // let the reader believe the ranking was domain-aware when it had no match to work with.
-        write(renderDomainBoostNote(boost, wantedDomain));
+        write(renderDomainBoostNote(boost, shownDomain));
         const cutNote = renderDomainCutNote(displaced, limit);
         if (cutNote !== '')
             write(cutNote);
@@ -2054,6 +2501,29 @@ async function cmdVector(options, flags, cwd, write) {
             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}`);
@@ -3006,7 +3476,7 @@ async function cmdAutoCanonicalize(options, cwd, write) {
             const skillName = parts[parts.length - 2] ?? parts[0] ?? 'unknown';
             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('/');
@@ -3377,6 +3847,8 @@ function cmdPublish(options, flags, cwd, write) {
                 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
     // refuses `--provenance` where no OIDC token can be minted. `off` is an escape hatch that names itself.
@@ -4577,7 +5049,13 @@ function cmdDriftCheck(options, flags, cwd, write) {
     return driftExit || sigFatal;
 }
 const DEFAULT_STORE_CAP = 5000;
-/** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number }`. Missing/broken ⇒ defaults. */
+/**
+ * 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) {
     const p = join(root, '.dz', 'guard.json');
     if (!existsSync(p))
@@ -4660,6 +5138,34 @@ function gatherGuardFacts(op, root, text, storeCap) {
             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 = [];
+            for (const { dir, m } of located) {
+                if (!m || m.licenseHold === undefined || m.licenseHold === null)
+                    continue;
+                const read = (rel) => {
+                    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);
         }
@@ -4726,11 +5232,26 @@ function gatherGuardFacts(op, root, text, storeCap) {
         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())
@@ -4739,34 +5260,58 @@ function gatherGuardFacts(op, root, text, storeCap) {
             const formatGlobs = (Array.isArray(loadGuardConfig(root).rules) ? loadGuardConfig(root).rules : [])
                 .filter((r) => r?.template === 'format-match' && typeof r?.params?.file === 'string')
                 .map((r) => r.params.file);
+            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 = {};
-            if (formatGlobs.length > 0) {
+            if (formatGlobs.length > 0 || stubWanted.size > 0) {
                 for (const f of files) {
-                    if (!formatGlobs.some((g) => globMatch(g, f)))
+                    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))
+                    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())
+                        if (!st.isFile()) {
+                            if (wanted)
+                                stubSkipped++;
                             continue;
-                        if (st.size > MAX_CONTENT_BYTES)
-                            continue; // too large to be a spec file — undecidable, never guessed
+                        }
+                        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 {
@@ -5240,6 +5785,10 @@ function cmdGuard(options, flags, cwd, write) {
         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');
@@ -5297,6 +5846,8 @@ function cmdGuard(options, flags, cwd, write) {
     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')
@@ -5973,6 +6524,379 @@ function cmdDiscriminationCheck(options, flags, cwd, write) {
 function nameFor(t, outcome) {
     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, text) {
+    const ext = extname(absFile).toLowerCase();
+    try {
+        if (ext === '.ts' || ext === '.tsx' || ext === '.mts' || ext === '.cts') {
+            let ts = null;
+            for (const from of [absFile, import.meta.url]) {
+                try {
+                    ts = createRequire(from)('typescript');
+                    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.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.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;
+                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.message).slice(0, 120)}` };
+    }
+}
+function cmdMutationGate(options, flags, cwd, write) {
+    const json = flags.has('json');
+    const fail = (what) => {
+        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 = 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 = 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 = [];
+    const observations = [];
+    const warnings = [];
+    let baseline;
+    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 = () => {
+            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;
+                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 = null;
+            try {
+                sourceText = readFileSync(filePath, 'utf-8');
+            }
+            catch { /* missing file ⇒ occurrences 0 ⇒ NOT_APPLIED */ }
+            if (sourceText === null) {
+                const obs = { 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 = { 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 = 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 = null;
+            let parseError;
+            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;
+            let outputUnrecognised;
+            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;
+            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 = {
+                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,
@@ -7090,6 +8014,23 @@ async function cmdBacklog(options, flags, cwd, write) {
         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.
@@ -7102,19 +8043,38 @@ async function cmdBacklog(options, flags, cwd, write) {
             // 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;
             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));
+                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;
         }
@@ -7136,15 +8096,22 @@ async function cmdBacklog(options, flags, cwd, write) {
         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));
+                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;
         }
@@ -7156,12 +8123,14 @@ async function cmdBacklog(options, flags, cwd, write) {
         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));
+            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)
@@ -7365,6 +8334,43 @@ async function cmdBacklog(options, flags, cwd, write) {
         }
         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 = [];
+        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)
@@ -7415,6 +8421,13 @@ async function cmdBacklog(options, flags, cwd, write) {
     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));
@@ -7438,6 +8451,9 @@ async function cmdBacklog(options, flags, cwd, write) {
     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');
@@ -7796,12 +8812,16 @@ export async function runCli(argv, io = {}) {
                 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':
@@ -7880,6 +8900,8 @@ export async function runCli(argv, io = {}) {
                 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':