@dzhechkov/harness-cli 0.8.6 → 0.8.9

package/src/cli.ts

@@ -29,6 +29,8 @@ import {
   TARGET_NAMES_SORTED,
   runDoctor,
   runInit,
+  discoverSkillIds,
+  runIntegrationsVerify,
   resolvePackageSkillRoots,
   PACKAGE_SKILL_LAYOUTS,
   benchmarkSkill,
@@ -81,6 +83,7 @@ import {
   NamedLockTimeoutError,
   NamedLockCompromisedError,
   type CodexHooksSyncReport,
+  type IntegrationManifestSource,
   type ParityCell,
   type ParityFeature,
   type ParityReportCell,
@@ -116,6 +119,8 @@ import {
   renderTimelineHtml,
   importEcc,
   recordPattern,
+  recordLessonForms,
+  normalizeLessonForms,
   resolveLearningBackend,
   storeStats,
   consolidateSessions,
@@ -141,6 +146,17 @@ import {
   importRvfCheckpoint,
   statuslineData,
   writeFeatureAdrState,
+  CHECKPOINT_STAGES,
+  estimateEta,
+  extractStageSamples,
+  formatEta,
+  parseCheckpointLines,
+  segmentRun,
+  type CheckpointStage,
+  type EtaEstimate,
+  type FeatureAdrState,
+  type RunSegment,
+  type StageSample,
   computeUsage,
   deriveCostLedger,
   planLedgerBackfill,
@@ -167,6 +183,8 @@ import {
   queryBookKnowledge,
   loadStorePatternsSync,
   patternRecordId,
+  patternIdentityOf,
+  mergeLessonMatchedForms,
   loadStoreRecords,
   recordToPattern,
   bundleSkills,
@@ -204,12 +222,22 @@ import {
   DEFAULT_RULES,
   parsePnpmLockImporters,
   scannableStubPath,
+  type FeatureArtifactFact,
+  type FeatureTier,
+  type FeatureVolumeFact,
+  type GuardObservation,
+  type TemplateVolumeFileFact,
+  type TemplateVolumeTargetFact,
+  type VolumeShadowInput,
   // guard-promotion (feature guard-promotion, scout idea #1)
   assembleCandidates,
   renderPromotionReport,
   renderPromotionAdr,
   normalizePromotionState,
   nextPromotionState,
+  recordPromotionRunEvidence,
+  isLessonRuleContentAnchor,
+  isOffsetIsoTimestamp,
   globMatch,
   promotionAdrRelPath,
   DEFAULT_WINDOW_DAYS,
@@ -219,6 +247,10 @@ import {
   type ChangeSet,
   type ExistingRuleView,
   type PromotionReport,
+  type PromotionAcceptanceEvidence,
+  type PromotionRunEvidence,
+  type FunnelEvidenceSource,
+  type GuardEvent,
   decideProvenance,
   isInsideTree,
   signManifest,
@@ -522,7 +554,7 @@ import type { SetupSpec } from '@dzhechkov/harness-core';
 import type { LogTail } from '@dzhechkov/harness-core';
 import type { DeadwoodInventoryItem } from '@dzhechkov/harness-core';
 import type { ContractDiagnostic, ContractEvidenceReader } from '@dzhechkov/harness-core';
-import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow, GateExecution, GateStep, SlopFinding, SlopLintConfig, SlopRegistry } from '@dzhechkov/harness-core';
+import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, RecallPatternsOptions, TeachGuardResult, TargetName, IntegrationOutcome, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow, GateExecution, GateStep, SlopFinding, SlopLintConfig, SlopRegistry } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -534,7 +566,7 @@ export const DZ_COMMANDS: readonly string[] = [
   'usage', 'claim-check', 'lint', 'sign', 'sbom', 'guard', 'verify-pack', 'setup',
   'pretrain', 'compose', 'diff', 'recommend', 'upgrade', 'auto-canonicalize',
   'publish', 'release', 'parity', 'registry', 'benchmark', 'mcp-scan',
-  'sync-upstream', 'drift-check', 'hooks-sync', 'agents-sync', 'sync-canonical',
+  'sync-upstream', 'drift-check', 'hooks-sync', 'integrations-verify', 'agents-sync', 'sync-canonical',
   'plugin', 'downloads', 'stats', 'architecture', 'project-skills', 'mr-rakes',
   'retro', 'feature-adr-setup', 'challenge', 'discrimination-check',
   'mutation-gate', 'delivery-check', 'skills-verify', 'compounding', 'deadwood',
@@ -547,7 +579,7 @@ export const DZ_COMMANDS: readonly string[] = [
 const USAGE = `dz - DZ cross-platform harness CLI
 
 Usage:
-  dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--preset <name>] [--select id,id,...] [--force] [--enrich] [--no-hooks] [--no-verify]   (--target codex ALSO installs the user-global dz veto+recall hooks and LIVE-verifies them (ADR-001 §8); --no-hooks = skills only; --no-verify skips the live probe and can never report ready)
+  dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--preset <name>] [--select id,id,...] [--force] [--enrich] [--allow-integrations <sha256:digest>] [--no-integrations] [--no-hooks] [--no-verify]   (integration manifests require exact digest consent; --no-integrations = explicit skills-only)
   dz verify [--skills-dir <dir>] [--target <name>]
   dz sync   [--canonical <dir>] [--project <dir>] [--dry-run] [--force]
   dz update   (alias of sync)
@@ -576,7 +608,7 @@ Usage:
   dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   (portable Step-10 Delivery Gate: prints the 4-plane review brief + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked)
   dz challenge --plan <plan.md> [--author <model>]   (the deterministic cartridge behind the challenge-panel adversarial plan-gate (R6): assembles the wide brief — plan + architecture/vision.md + testing.md + map.json + degradations.md — and prints the C1-C8 adversary prompt naming the cross-family reviewer to dispatch. exit 0 brief printed / 1 plan missing or empty)
   dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--json]   (does .claude/skills/ actually REGISTER? --static = instant layout scan for CI; default reads the authoritative system/init listing from a real session. exit 0 pass / 1 fail / 2 inconclusive — never a false pass)
-  dz compounding [--project <dir>] [--json]   (honest learning-loop payoff report: pool write-only ratio, guard repeat-violation trajectory, cold-vs-warm replay readiness, instrumentation health — a gate without enough data says INSUFFICIENT_DATA, never a fake verdict)
+  dz compounding [--project <dir>] [--json]   (honest learning-loop payoff report: pool/replay/guard instrumentation + monthly eligible→attempted→accepted→executions; unavailable is NOT MEASURED, and only a named empty stage after a non-empty predecessor for 3 measured months is a funnel finding)
   dz deadwood [--weeks <n>] [--json]   (advisory zero-usage candidates for human deprecation review; safety-excluded surfaces carry reasons; never deletes or deprecates anything; shallow history says INSUFFICIENT_DATA)
   dz epoch-replay --mock [--n <N>] [--effect <-1..1>] [--tie-rate <0..1>] [--seed <N>] [--slice <name>] [--json]   ($0 synthetic run — exercises the verdict math, NOT evidence)
   dz epoch-replay --emit [--project <dir>] [--limit <N>] [--seed <N>] [--out <file>]   (cold-vs-warm work order: instances + PRE-REGISTERED blind A/B assignment; the runner never calls a model)
@@ -617,7 +649,7 @@ Usage:
   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)
   dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--no-verify] [--install-driver] [--force] [--enrich]   (--target codex ALSO installs + LIVE-verifies the codex hooks; an unverified hook exits non-zero WITHOUT aborting the rest of setup)
-  dz teach "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (--project pins the learned store to <dir>/.dz, not the cwd — pin to a canonical brain)
+  dz teach "<pattern>" [--class-form "<template with :slot>"] [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   (class form is optional; rejection never blocks the specific write; --project pins the learned store to <dir>/.dz)
   dz teach --from-json <file> [--project <dir>] [--no-mirror]   (bulk-import a 'dz recall --all --json' export — share a learned store across machines)
   dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]] [--prune-quarantine [--apply]]   (both prunes: DRY-RUN by default; --apply snapshots then deletes; prune-quarantine = expired unproven lessons ONLY, never coupled to noise)
   dz recall "<query>" [--limit <N>] [--domain <name>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply] | dz recall --promote <dzId>[,<dzId>] [--apply]   (--domain <name> BOOSTS lessons of that domain without dropping foreign ones — a shared store keeps its cross-domain transfers; forget/promote: dry-run default; forget snapshots before removing; promote lifts lesson-quarantine)
@@ -656,6 +688,7 @@ Usage:
   dz drift-check [--json] [--project <dir>]                             (CI gate: exit 1 if any shared skill drifted between its monorepo copies)
   dz agents-sync [--project <dir>] [--check] [--json]                   (sync/verify the always-on policy fence in root AGENTS.md; exit 0 synced/written, 1 drift, 3 inconclusive)
   dz hooks-sync --target codex [--check] [--verify] [--remove] [--json]  (install/verify the dz veto + recall hooks in $CODEX_HOME/hooks.json; exit 0 armed+trusted, 1 not armed/drift, 3 inconclusive)
+  dz integrations-verify --target <name> --component <mcp|hooks> [--project <dir>] [--json]  (non-executing exact-version registration probe; exit 0 observed / 1 refused)
   dz sync-canonical <skill> [--check] [--from <dir>] [--auto] [--project <dir>]  (heal every copy from skills-meta/<skill> or --from; no canonical + --check = compare copies to each other (exit 1 on drift); no canonical + write = refuse unless --auto (LOUD, picks most-complete copy); --check writes nothing)
   dz plugin [--version <ver>]
   dz downloads
@@ -706,6 +739,14 @@ export interface CliIo {
    * command that needs it (`brain ground`), and never when stdin is a TTY (nothing piped).
    */
   readonly stdin?: string;
+  /** Human-terminal rendering seam; production defaults to stdout TTY detection. */
+  readonly interactive?: boolean;
+  /** Fault seam proving that class-form recall degrades to specific recall with a stderr receipt. */
+  readonly classMatcher?: RecallPatternsOptions['classMatcher'];
+  /** Guard decision seam; production always uses the real vector-backed teach guard. */
+  readonly teachGuardRunner?: (projectRoot: string, text: string, opts: { readonly reward?: number }) => Promise<TeachGuardResult>;
+  /** Reinforcement flush seam paired with `teachGuardRunner`; production uses the configured backend. */
+  readonly teachReinforceRunner?: (projectRoot: string, dzId: string, reward: number) => Promise<{ readonly flushed: number }>;
   /**
    * Test seam for `dz release`: overrides subprocess execution for gate steps and the
    * gh/git side channels (production leaves it unset → real `execSync`, stdio piped).
@@ -823,6 +864,8 @@ interface InstallSkillsResult {
    * the source `SKILL.md`.
    */
   readonly applyFailures: SkillApplyFailure[];
+  readonly integrations: readonly IntegrationOutcome[];
+  readonly integrationDigest?: string;
 }
 
 /**
@@ -838,6 +881,10 @@ async function installSkills(opts: {
   select?: readonly string[] | undefined;
   force: boolean;
   enrich: boolean;
+  noHooks?: boolean;
+  noIntegrations?: boolean;
+  noVerify?: boolean;
+  allowIntegrations?: string;
 }): Promise<InstallSkillsResult> {
   const { target, projectRoot, cwd, explicitSkillsDir, select, force, enrich } = opts;
 
@@ -850,8 +897,8 @@ async function installSkills(opts: {
   // route them through one aggregation.
   if (target === 'agents-md' || target === 'gemini') {
     const report = target === 'gemini'
-      ? runInitGeminiMd({ skillsDirs, projectRoot, ...(select !== undefined ? { select } : {}) })
-      : runInitAgentsMd({ skillsDirs, projectRoot, ...(select !== undefined ? { select } : {}) });
+      ? runInitGeminiMd({ skillsDirs, projectRoot, ...(select !== undefined ? { select } : {}), ...(opts.noHooks !== undefined ? { noHooks: opts.noHooks } : {}), ...(opts.noIntegrations !== undefined ? { noIntegrations: opts.noIntegrations } : {}) })
+      : runInitAgentsMd({ skillsDirs, projectRoot, ...(select !== undefined ? { select } : {}), ...(opts.noHooks !== undefined ? { noHooks: opts.noHooks } : {}), ...(opts.noIntegrations !== undefined ? { noIntegrations: opts.noIntegrations } : {}) });
     const results = report.skills.map((s) => ({
       id: s.id,
       written: s.written.length,
@@ -860,13 +907,21 @@ async function installSkills(opts: {
     let written = 0;
     let skipped = 0;
     for (const s of results) { written += s.written; skipped += s.skipped; }
-    return { results, dirsSearched: skillsDirs.length, written, skipped, missing: [...report.missing], failures: [...report.failures], applyFailures: [...report.applyFailures] };
+    return { results, dirsSearched: skillsDirs.length, written, skipped, missing: [...report.missing], failures: [...report.failures], applyFailures: [...report.applyFailures], integrations: [...report.integrations], ...(report.integrationDigest !== undefined ? { integrationDigest: report.integrationDigest } : {}) };
   }
 
   const results: { id: string; written: number; skipped: number }[] = [];
   const failures: SkillLoadFailure[] = [];
   const applyFailures: SkillApplyFailure[] = [];
-  for (const skillsDir of skillsDirs) {
+  let integrations: readonly IntegrationOutcome[] = [];
+  let integrationDigest: string | undefined;
+  const integrationManifestSources: readonly IntegrationManifestSource[] = skillsDirs.flatMap((skillsDir) => {
+    const discovered = discoverSkillIds(skillsDir);
+    return discovered
+      .filter((id) => select === undefined || select.includes(id))
+      .map((skillId) => ({ skillId, skillDir: skillsDir }));
+  });
+  for (const [dirIndex, skillsDir] of skillsDirs.entries()) {
     const r = await runInit({
       target,
       skillsDir,
@@ -874,12 +929,24 @@ async function installSkills(opts: {
       force,
       enrich,
       ...(select !== undefined ? { select } : {}),
+      ...(opts.noHooks !== undefined ? { noHooks: opts.noHooks } : {}),
+      ...(dirIndex === 0
+        ? {
+            integrationManifestSources,
+            ...(opts.noIntegrations !== undefined ? { noIntegrations: opts.noIntegrations } : {}),
+          }
+        : { noIntegrations: true }),
+      ...(opts.noVerify !== undefined ? { noVerify: opts.noVerify } : {}),
+      ...(opts.allowIntegrations !== undefined ? { allowIntegrations: opts.allowIntegrations } : {}),
     });
     for (const skill of r.skills) {
       results.push({ id: skill.id, written: skill.written.length, skipped: skill.skipped.length });
     }
     failures.push(...r.failures);
     applyFailures.push(...r.applyFailures);
+    if (r.integrations.some((row) => row.status !== 'not-requested')) integrations = [...r.integrations];
+    else if (integrations.length === 0) integrations = [...r.integrations];
+    if (r.integrationDigest !== undefined) integrationDigest = r.integrationDigest;
   }
 
   let written = 0;
@@ -887,7 +954,7 @@ async function installSkills(opts: {
   for (const s of results) { written += s.written; skipped += s.skipped; }
   const installed = new Set(results.map((s) => s.id));
   const missing = select !== undefined ? [...select].filter((id) => !installed.has(id)) : [];
-  return { results, dirsSearched: skillsDirs.length, written, skipped, missing, failures, applyFailures };
+  return { results, dirsSearched: skillsDirs.length, written, skipped, missing, failures, applyFailures, integrations, ...(integrationDigest !== undefined ? { integrationDigest } : {}) };
 }
 
 /** Warn about preset/select ids that weren't found in any installed pack. */
@@ -949,26 +1016,46 @@ async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: st
     select,
     force: flags.has('force'),
     enrich: flags.has('enrich'),
+    noHooks: flags.has('no-hooks'),
+    noIntegrations: flags.has('no-integrations'),
+    noVerify: flags.has('no-verify'),
+    ...(options.get('allow-integrations') !== undefined ? { allowIntegrations: options.get('allow-integrations')! } : {}),
   });
 
-  write(`dz init --target ${target}: ${r.results.length} skill(s), ${r.written} file(s) written, ${r.skipped} skipped`);
-  if (r.dirsSearched > 1) {
-    write(`  (searched ${r.dirsSearched} skill directories)`);
-  }
-  writeMissingSkillsHint(write, r.missing, presetName);
-
-  // Codex-targeted init DELIVERS the hooks and verifies them (ADR-001 §8). Skills alone are not the
-  // target's harness: the veto + recall legs are what `--target codex` promises.
-  // `--no-hooks` is the documented escape for "skills only" (the same flag `dz setup` already
-  // carries): hook delivery writes USER-GLOBAL config, so a command that only wants skills compiled
-  // must be able to say so — and every test that is about skills says it.
+  // Codex keeps its established user-registry writer, but its result is normalized into the same
+  // two-outcome contract before JSON/human rendering. A write without a live ready observation is
+  // a refusal with applied=true, never a second success channel.
+  let integrationOutcomes: readonly IntegrationOutcome[] = r.integrations;
   let codexHooksOk = true;
   if (target === 'codex' && !flags.has('no-hooks')) {
     const delivery = deliverCodexHooks({ project: projectRoot, verify: !flags.has('no-verify') }, undefined, 'dz init');
     codexHooksOk = delivery.ok;
     for (const line of delivery.stdout) write(line);
     for (const line of delivery.stderr) writeErr(line);
+    const hookIndex = integrationOutcomes.findIndex((row) => row.component === 'hooks' && row.status !== 'not-requested');
+    if (hookIndex !== -1) {
+      const hook = normalizeCodexHookOutcome(integrationOutcomes[hookIndex]!, delivery, flags.has('no-verify'));
+      integrationOutcomes = integrationOutcomes.map((row, index) => index === hookIndex ? hook : row);
+    }
   }
+
+  if (flags.has('json')) {
+    write(JSON.stringify({ target, skills: { count: r.results.length, written: r.written, skipped: r.skipped }, integrations: integrationOutcomes, integrationDigest: r.integrationDigest ?? null }));
+  } else {
+    write(`dz init --target ${target}: ${r.results.length} skill(s), ${r.written} file(s) written, ${r.skipped} skipped`);
+    if (r.dirsSearched > 1) write(`  (searched ${r.dirsSearched} skill directories)`);
+    for (const outcome of integrationOutcomes) {
+      const label = outcome.component === 'mcp' ? 'MCP' : 'Hooks';
+      const detail = outcome.status === 'refused'
+        ? `${outcome.reasonCode ?? 'LIVE_PROBE_FAILED'}${outcome.remediation ? ` — ${outcome.remediation}` : ''}`
+        : outcome.status === 'emitted'
+          ? `${outcome.carrier?.path ?? 'registered'}${outcome.registrations.some((row) => row.approval === 'pending') ? '; Pending approval; ready=false' : ''}`
+          : 'explicitly not requested';
+      write(`${label}: ${outcome.status.toUpperCase()} (${detail})`);
+    }
+  }
+  writeMissingSkillsHint(write, r.missing, presetName);
+
   // Skip-and-collect must not become skip-and-SILENCE: a skill that failed to load is
   // named on stderr and the command exits 1 (it exited 1 before too — by throwing).
   if (r.failures.length > 0 || r.applyFailures.length > 0) {
@@ -987,7 +1074,35 @@ async function cmdInit(options: Map<string, string>, flags: Set<string>, cwd: st
     for (const line of formatSkillApplyFailures(r.applyFailures)) writeErr(line);
     return 1;
   }
-  return codexHooksOk ? 0 : 1;
+  const integrationOk = !integrationOutcomes.some((row) => row.status === 'refused');
+  return codexHooksOk && integrationOk ? 0 : 1;
+}
+
+function cmdIntegrationsVerify(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write, writeErr: WriteErr): number {
+  const targetInput = options.get('target');
+  const component = options.get('component');
+  if (targetInput === undefined || (component !== 'mcp' && component !== 'hooks')) {
+    writeErr('dz integrations-verify: requires --target <name> --component <mcp|hooks>');
+    return 1;
+  }
+  const resolution = resolveTargetName(targetInput);
+  if (resolution.kind === 'unknown') {
+    for (const line of formatTargetProblem('dz integrations-verify', resolution)) writeErr(line);
+    return 1;
+  }
+  if (resolution.via === 'alias') writeErr(formatTargetAliasNote('dz integrations-verify', targetInput, resolution.target));
+  const result = runIntegrationsVerify({
+    target: resolution.target,
+    component,
+    projectRoot: resolve(cwd, options.get('project') ?? '.'),
+  });
+  if (flags.has('json')) write(JSON.stringify(result));
+  else if (result.ok) {
+    write(`dz integrations-verify: ${resolution.target}/${component} registered (runtime ${result.runtimeVersion ?? 'unknown'}; ready=${result.registrations.every((row) => row.ready === true)})`);
+  } else {
+    writeErr(`dz integrations-verify: ${resolution.target}/${component} REFUSED (${result.reasonCode ?? 'LIVE_PROBE_FAILED'}) — ${result.remediation ?? 'no qualifying receipt'}`);
+  }
+  return result.ok ? 0 : 1;
 }
 
 async function cmdVerify(options: Map<string, string>, cwd: string, write: Write, writeErr: WriteErr): Promise<number> {
@@ -2423,6 +2538,146 @@ function cmdStatuslineFaRecord(options: Map<string, string>, cwd: string, write:
   return 0;
 }
 
+interface EtaCorpusRead {
+  readonly history: StageSample[];
+  readonly currentRunSamples: StageSample[];
+  readonly currentTier: string | undefined;
+  readonly activeStages: CheckpointStage[];
+  readonly lastCheckpointTsMs: number | undefined;
+  readonly hasCurrentCheckpoints: boolean;
+}
+
+function statuslineEtaStage(step: string): CheckpointStage | undefined {
+  const match = step.match(/\bStep\s*-?\s*(0|[1-9](?:\.5)?)(?:\b|\s)/i);
+  if (match === null) return undefined;
+  const value = Number(match[1]);
+  if (value === 0) return 'router';
+  if (value > 0 && value < 6) return 'design';
+  if (value === 6) return 'plan';
+  if (value === 7) return 'code';
+  if (value === 8) return 'qe';
+  if (value === 9) return 'fleet';
+  return undefined;
+}
+
+function routerMetadata(router: RunSegment['router']): { tier?: string; activeSteps?: number[] } {
+  const result = router?.result;
+  if (result === null || typeof result !== 'object') return {};
+  const record = result as Record<string, unknown>;
+  const tier = typeof record['tier'] === 'string' && record['tier'].length > 0 ? record['tier'] : undefined;
+  const activeSteps = Array.isArray(record['activeSteps'])
+    ? record['activeSteps'].filter((value): value is number => typeof value === 'number' && Number.isFinite(value))
+    : undefined;
+  return {
+    ...(tier !== undefined ? { tier } : {}),
+    ...(activeSteps !== undefined ? { activeSteps } : {}),
+  };
+}
+
+function activeCheckpointStages(tier: string | undefined, activeSteps: readonly number[] | undefined): CheckpointStage[] {
+  const stages = new Set<CheckpointStage>();
+  if (activeSteps !== undefined) {
+    for (const step of activeSteps) {
+      if (step === 0) stages.add('router');
+      else if (step > 0 && step < 6) stages.add('design');
+      else if (step === 6) stages.add('plan');
+      else if (step === 7) stages.add('code');
+      else if (step === 8) stages.add('qe');
+      else if (step === 9) stages.add('fleet');
+    }
+  } else if (tier !== undefined) {
+    for (const stage of CHECKPOINT_STAGES) {
+      if (stage !== 'fleet' || tier === 'L' || tier === 'XL') stages.add(stage);
+    }
+  }
+  return CHECKPOINT_STAGES.filter((stage) => stages.has(stage));
+}
+
+/** All checkpoint I/O for ETA lives in this CLI-only wrapper and degrades per file. */
+function readEtaCorpus(projectRoot: string, currentSlug: string): EtaCorpusRead {
+  const trace = process.env['DZ_ETA_TRACE'];
+  if (trace !== undefined && trace.length > 0) {
+    try {
+      appendFileSync(trace, `${JSON.stringify({ projectRoot, currentSlug, ts: new Date().toISOString() })}\n`);
+    } catch { /* a test/debug receipt can never take down the statusline */ }
+  }
+
+  const samples: StageSample[] = [];
+  let currentSegments: RunSegment[] = [];
+  let hasCurrentCheckpoints = false;
+  let entries: Dirent[] = [];
+  try {
+    entries = readdirSync(join(projectRoot, 'features'), { withFileTypes: true });
+  } catch {
+    return {
+      history: [], currentRunSamples: [], currentTier: undefined, activeStages: [],
+      lastCheckpointTsMs: undefined, hasCurrentCheckpoints: false,
+    };
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const checkpointPath = join(projectRoot, 'features', entry.name, '.fa-state', 'checkpoints.jsonl');
+    try {
+      const text = readFileSync(checkpointPath, 'utf8');
+      const observations = parseCheckpointLines(text, entry.name);
+      const segments = segmentRun(observations);
+      samples.push(...extractStageSamples(segments));
+      if (entry.name === currentSlug) {
+        hasCurrentCheckpoints = observations.length > 0;
+        currentSegments = segments;
+      }
+    } catch {
+      // Missing, unreadable, or racing append: this run contributes no evidence.
+    }
+  }
+
+  const lastSegment = currentSegments.at(-1);
+  const currentRouter = lastSegment?.router;
+  const invocationSegments = currentRouter === undefined
+    ? []
+    : currentSegments.filter((segment) => segment.router === currentRouter);
+  const invocationRunIds = new Set(invocationSegments.map((segment) => segment.runId));
+  const currentRunSamples = extractStageSamples(invocationSegments);
+  const metadata = routerMetadata(currentRouter);
+  const currentTimestamps = invocationSegments
+    .flatMap((segment) => segment.observations)
+    .flatMap((observation) => observation.tsMs === undefined ? [] : [observation.tsMs]);
+
+  return {
+    history: samples.filter((sample) => !invocationRunIds.has(sample.runId)),
+    currentRunSamples,
+    currentTier: metadata.tier,
+    activeStages: activeCheckpointStages(metadata.tier, metadata.activeSteps),
+    lastCheckpointTsMs: currentTimestamps.length > 0 ? Math.max(...currentTimestamps) : undefined,
+    hasCurrentCheckpoints,
+  };
+}
+
+function statuslineEta(projectRoot: string, state: FeatureAdrState, nowMs: number): EtaEstimate | undefined {
+  const currentStage = statuslineEtaStage(state.step);
+  if (currentStage === undefined) return undefined;
+  const corpus = readEtaCorpus(projectRoot, state.slug);
+  const currentIndex = CHECKPOINT_STAGES.indexOf(currentStage);
+  const remainingStages = corpus.activeStages.filter((stage) => CHECKPOINT_STAGES.indexOf(stage) >= currentIndex && stage !== 'router');
+  // Preserve honest absence as a machine-readable union member. The text formatter intentionally
+  // omits both variants, but `--json` must still distinguish no file from a file with no tier.
+  const stagesForEstimate = remainingStages.length > 0
+    ? remainingStages
+    : (currentStage === 'router' ? [] : [currentStage]);
+  if (stagesForEstimate.length === 0 && corpus.hasCurrentCheckpoints && corpus.currentTier !== undefined) return undefined;
+  return estimateEta({
+    samples: corpus.history,
+    currentTier: corpus.currentTier,
+    currentStage,
+    remainingStages: stagesForEstimate,
+    currentRunSamples: corpus.currentRunSamples,
+    nowMs,
+    ...(corpus.lastCheckpointTsMs !== undefined ? { lastCheckpointTsMs: corpus.lastCheckpointTsMs } : {}),
+    hasCurrentCheckpoints: corpus.hasCurrentCheckpoints,
+  });
+}
+
 /**
  * `dz statusline` — render dz's OWN self-learning counts as one compact, emoji-tagged line for
  * Claude Code's status bar (modeled on agentic-qe's "🎓 12 patterns"). Claude Code pipes a JSON
@@ -2447,9 +2702,22 @@ function cmdStatusline(
   try {
     const projectRoot = statuslineProjectRoot(readStdin(), options, cwd);
     const data = statuslineData(projectRoot);
+    const fa = data.featureAdr;
+    let eta: EtaEstimate | undefined;
+    let etaFragment: string | undefined;
+    if (fa !== undefined && fa.kind !== 'loop') {
+      try {
+        eta = statuslineEta(projectRoot, fa, Date.now());
+        if (eta !== undefined) etaFragment = formatEta(eta);
+      } catch {
+        // ETA is advisory: any corpus/resource failure omits only this fragment.
+        eta = undefined;
+        etaFragment = undefined;
+      }
+    }
 
     if (flags.has('json')) {
-      write(JSON.stringify(data));
+      write(JSON.stringify({ ...data, ...(eta !== undefined ? { eta } : {}) }));
       return 0;
     }
 
@@ -2459,13 +2727,12 @@ function cmdStatusline(
     if (data.consolidatedAgeH !== undefined) line += ` · ⟳ ${data.consolidatedAgeH}h`;
 
     // Live /feature-adr run in flight → PREPEND the pipeline learning segment to the base dz line.
-    const fa = data.featureAdr;
     if (fa !== undefined) {
       // The producer marker reached data and arbitration in a previous round but not this label, so the bar asserted a pipeline that was not running.
       if (fa.kind === 'loop') {
         line = `🔁 loop ${fa.step} · ${line}`;
       } else {
-        line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
+        line = `📐 feature-adr ${fa.step} · ${etaFragment !== undefined ? `${etaFragment} · ` : ''}🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
       }
     }
 
@@ -3092,7 +3359,22 @@ function learningStoreLine(
   ) + (reason ? '  [' + reason + ']' : '');
 }
 
-async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+async function runTeachGuardReinforcement(
+  projectRoot: string,
+  dzId: string,
+  reward: number,
+): Promise<{ readonly flushed: number }> {
+  const backend = resolveLearningBackend(projectRoot);
+  backend.addSample({ dzId, kind: 'reinforce', reward, ts: new Date().toISOString() });
+  return backend.train();
+}
+
+async function cmdTeach(
+  options: Map<string, string>, flags: Set<string>, cwd: string, write: Write,
+  writeErr: WriteErr = (line) => { console.error(line); }, interactive = false,
+  guardRunner: (projectRoot: string, text: string, opts: { readonly reward?: number }) => Promise<TeachGuardResult> = teachGuard,
+  reinforceRunner: (projectRoot: string, dzId: string, reward: number) => Promise<{ readonly flushed: number }> = runTeachGuardReinforcement,
+): Promise<number> {
   // WHICH store this lesson belongs to, and WHO decided (teach-chooses-its-store).
   // `--to` → `DZ_LEARN` → `.dz/config.json` learning.teachTo → project. The owner asked for a
   // per-session choice; for a CLI every invocation is a fresh process, so the only honest session
@@ -3176,26 +3458,39 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
       write('dz teach --from-json: expected a JSON array (produced by `dz recall --all --json`)');
       return 1;
     }
-    const existing = new Set(loadStorePatternsSync(storeRoot).map((p) => p.pattern));
+    const importedKey = (p: PatternRecord): string => p.lessonForm !== undefined && p.lessonPairId !== undefined
+      ? `${p.pattern}\u0000${p.lessonForm}\u0000${p.lessonPairId}`
+      : `legacy\u0000${p.pattern}`;
+    const existing = new Set(loadStorePatternsSync(storeRoot).map(importedKey));
     let imported = 0;
     let skipped = 0;
     const importedRecs: PatternRecord[] = [];
     for (const item of parsed) {
       const p = item as Partial<PatternRecord>;
-      if (!p || typeof p.pattern !== 'string' || p.pattern.trim() === '' || existing.has(p.pattern)) {
+      if (!p || typeof p !== 'object') {
         skipped += 1;
         continue;
       }
-      const rec: PatternRecord = {
-        pattern: p.pattern,
+      const pair = (p.lessonForm === 'specific' || p.lessonForm === 'class')
+        && typeof p.lessonPairId === 'string' && p.lessonPairId !== ''
+        ? { lessonForm: p.lessonForm, lessonPairId: p.lessonPairId }
+        : {};
+      const candidate = {
+        pattern: typeof p.pattern === 'string' ? p.pattern : '',
         type: (typeof p.type === 'string' ? p.type : 'lesson-learned') as PatternRecord['type'],
         reward: typeof p.reward === 'number' ? Math.max(0, Math.min(1, p.reward)) : 0.8,
         domain: typeof p.domain === 'string' ? p.domain : 'general',
         ts: typeof p.ts === 'string' ? p.ts : new Date().toISOString(),
         source: 'dz-teach-import',
-      };
+        ...pair,
+      } satisfies PatternRecord;
+      if (candidate.pattern.trim() === '' || existing.has(importedKey(candidate))) {
+        skipped += 1;
+        continue;
+      }
+      const rec: PatternRecord = candidate;
       await recordPattern(storeRoot, rec);
-      existing.add(p.pattern);
+      existing.add(importedKey(rec));
       importedRecs.push(rec);
       imported += 1;
     }
@@ -3279,23 +3574,30 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
 
   const reward = parseFloat(options.get('reward') ?? '0.8');
   const domain = options.get('domain') ?? 'general';
+  const classWasRequested = options.has('class-form') || flags.has('class-form');
+  const lessonForms = normalizeLessonForms(pattern, options.get('class-form'));
+  let guardedExisting: { readonly dzId: string; readonly cosine: number; readonly pattern: PatternRecord } | undefined;
 
   if (flags.has('guard')) {
-    const verdict = await teachGuard(storeRoot, pattern, { reward: Math.max(0, Math.min(1, reward)) });
+    const verdict = await guardRunner(storeRoot, pattern, { reward: Math.max(0, Math.min(1, reward)) });
     if (verdict.action === 'reinforce') {
-      const backend = resolveLearningBackend(storeRoot);
-      backend.addSample({ dzId: verdict.dzId, kind: 'reinforce', reward: Math.max(0, Math.min(1, reward)), ts: new Date().toISOString() });
-      const trained = await backend.train();
-      // HIGH-fix: only claim success when the reinforce actually FLUSHED. With backend 'off'
-      // (NoopLearningBackend) or a flush failure, flushed === 0 — falling through to the plain
-      // teach below so the lesson is NEVER silently discarded (the exact silent-drop the ADR forbids).
-      if (trained.flushed > 0) {
-        write(`↳ reinforced existing pattern ${verdict.dzId} (cos=${verdict.cosine.toFixed(2)}) — not re-added`);
-        const clearedQ = clearAgentdbQuarantine(storeRoot, [verdict.dzId]);
-        if (clearedQ.cleared > 0) write('  ↳ promoted out of quarantine (mirror updated)');
-        return 0;
+      if (lessonForms.classForm !== undefined) {
+        const existing = loadStoreRecords(storeRoot).find((record) => record.id === verdict.dzId);
+        if (existing !== undefined) {
+          guardedExisting = { dzId: verdict.dzId, cosine: verdict.cosine, pattern: recordToPattern(existing) };
+        } else {
+          write(`dz teach --guard: matched pattern ${verdict.dzId} was not found in the lexical store — teaching the lesson normally`);
+        }
+      } else {
+        const trained = await reinforceRunner(storeRoot, verdict.dzId, Math.max(0, Math.min(1, reward)));
+        if (trained.flushed > 0) {
+          write(`↳ reinforced existing pattern ${verdict.dzId} (cos=${verdict.cosine.toFixed(2)}) — not re-added`);
+          const clearedQ = clearAgentdbQuarantine(storeRoot, [verdict.dzId]);
+          if (clearedQ.cleared > 0) write('  ↳ promoted out of quarantine (mirror updated)');
+          return 0;
+        }
+        write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
       }
-      write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
     }
   }
 
@@ -3310,24 +3612,63 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   // Typed through the shared schema (harness-core owns PatternRecord) so the
   // write side and the read side (recommend's loadPatterns) can never drift —
   // a field rename here is a compile error, not a silently re-muted loop (audit #2).
-  const entry: PatternRecord = {
-    pattern,
-    type: type as PatternRecord['type'],
-    reward: Math.max(0, Math.min(1, reward)),
-    domain,
-    ts: new Date().toISOString(),
-    source: 'dz-teach',
-  };
+  const entry: PatternRecord = guardedExisting?.pattern ?? {
+      pattern: lessonForms.specific,
+      type: type as PatternRecord['type'],
+      reward: Math.max(0, Math.min(1, reward)),
+      domain,
+      ts: new Date().toISOString(),
+      source: 'dz-teach',
+    };
 
   // Tier-2 (ADR-005): persist through the unified @dzhechkov/memory store. recordPattern
   // folds any legacy .dz/patterns.jsonl into the backend (idempotent) and returns the
   // total count. The lossy `npx agentdb add` dual-write was removed in Tier-1 (audit #6).
   // lesson-quarantine (opt-in): a fresh lesson is a HYPOTHESIS until it earns promotion.
   const quarantineOn = readMemoryLearningConfig(storeRoot).quarantine;
-  const count = await recordPattern(storeRoot, entry, quarantineOn ? { quarantine: true } : {});
+  const stored = await recordLessonForms(
+    storeRoot,
+    entry,
+    lessonForms.classForm,
+    quarantineOn ? { quarantine: true } : {},
+  );
+  let recordsToMirror = stored.records;
+  let commandFailed = stored.class === 'failed';
+  let reinforced = false;
+  if (guardedExisting !== undefined) {
+    let reinforceId = guardedExisting.dzId;
+    if (stored.class === 'stored') {
+      const specificRow = stored.records.find((row) => row.lessonForm === 'specific');
+      if (specificRow !== undefined) reinforceId = patternRecordId(specificRow);
+      if (reinforceId !== guardedExisting.dzId) {
+        const removed = removePatternsByIds(storeRoot, new Set([guardedExisting.dzId]));
+        if (removed.error !== undefined || removed.removed === 0) {
+          commandFailed = true;
+          writeErr(`dz teach --guard: class pair stored, but old pattern cleanup failed${removed.error === undefined ? '' : ` — ${removed.error}`}`);
+        }
+      }
+    } else if (stored.class === 'failed') {
+      const partialSpecific = stored.records.find((row) => row.lessonForm === 'specific');
+      if (partialSpecific !== undefined && patternRecordId(partialSpecific) !== guardedExisting.dzId) {
+        const rolledBack = removePatternsByIds(storeRoot, new Set([patternRecordId(partialSpecific)]));
+        if (rolledBack.error !== undefined) writeErr(`dz teach --guard: partial enrichment rollback failed — ${rolledBack.error}`);
+      }
+      recordsToMirror = [];
+      reinforceId = guardedExisting.dzId;
+    }
+    if (!commandFailed) {
+      const trained = await reinforceRunner(storeRoot, reinforceId, Math.max(0, Math.min(1, reward)));
+      reinforced = trained.flushed > 0;
+      if (reinforced) {
+        const clearedQ = clearAgentdbQuarantine(storeRoot, [reinforceId]);
+        if (clearedQ.cleared > 0) write('  ↳ promoted out of quarantine (mirror updated)');
+      }
+    }
+  }
+  const count = guardedExisting === undefined ? stored.count : loadStorePatternsSync(storeRoot).length;
 
-  write(`Learned: "${pattern.slice(0, 60)}${pattern.length > 60 ? '...' : ''}"`);
-  write(`  Domain: ${domain}  Reward: ${reward}  Backend: memory (@dzhechkov/memory)`);
+  write(`${guardedExisting !== undefined && stored.class === 'stored' ? 'Enriched' : 'Learned'}: "${pattern.slice(0, 60)}${pattern.length > 60 ? '...' : ''}"`);
+  write(`  Domain: ${entry.domain}  Reward: ${entry.reward}  Backend: memory (@dzhechkov/memory)`);
   write(`  Total patterns: ${count}`);
   // WHERE the write landed. MEASURED before this line existed: teach printed the pattern, the
   // domain, the reward and the backend — and not one word about the path, so a store written to
@@ -3337,6 +3678,20 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   // sees a path, cannot tell what chose it, and has no reason to question it. `default` adds
   // nothing, so the line stays byte-identical for everyone who set nothing.
   write(storeLine('written'));
+  if (stored.class === 'stored') write('  Class form: stored separately and linked to the specific lesson');
+  if (classWasRequested && stored.class === 'absent') write('  Class form: skipped; the specific lesson was saved');
+  if (stored.class === 'rejected') writeErr(`dz teach: class form rejected — ${stored.reason ?? 'invalid class form'}; the specific lesson was saved`);
+  if (stored.class === 'failed') writeErr(`dz teach: specific stored; class failed — ${stored.reason ?? 'unknown storage failure'}`);
+  if (guardedExisting !== undefined && stored.class === 'stored') {
+    write(commandFailed
+      ? '  Guard: class enrichment stored; reinforcement skipped because old-pattern cleanup failed'
+      : reinforced
+        ? `  Guard: enriched existing pattern (cos=${guardedExisting.cosine.toFixed(2)}), then reinforced the linked specific form`
+        : '  Guard: class enrichment stored; reinforcement did not flush');
+  }
+  if (!classWasRequested && interactive) {
+    write('  Rule of one place or of a class? Optional: add --class-form when a future reader needs the why for structure, interfaces, or maintainability; skip when scope, risk, time, and cost are low or standards, policy, or documentation already cover it.');
+  }
   // 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
@@ -3351,8 +3706,8 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     write('  ⚠ quarantined: excluded from auto-inject, damped in recall — promote by confirming it (dz teach --reinforce "<text>") or dz recall --promote <dzId> --apply');
   }
   // The lexical write above is durable — the vector mirror is strictly best-effort (I-3).
-  await emitMirrorQ(storeRoot, [entry], 'dz-teach', quarantineOn);
-  return 0;
+  await emitMirrorQ(storeRoot, recordsToMirror, 'dz-teach', quarantineOn);
+  return commandFailed ? 1 : 0;
 }
 
 async function cmdConsolidate(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
@@ -3704,7 +4059,14 @@ async function cmdRecallPromote(
   return 0;
 }
 
-async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+async function cmdRecall(
+  options: Map<string, string>,
+  flags: Set<string>,
+  cwd: string,
+  write: Write,
+  writeErr: WriteErr,
+  classMatcher?: RecallPatternsOptions['classMatcher'],
+): Promise<number> {
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
   const asJson = flags.has('json');
   const all = flags.has('all');
@@ -3723,7 +4085,17 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // 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 classByPair = new Map(
+      holdout.exported
+        .filter((row) => row.lessonForm === 'class' && row.lessonPairId !== undefined)
+        .map((row) => [row.lessonPairId as string, row.pattern]),
+    );
+    const patterns = holdout.exported.map((row) => {
+      const classForm = row.lessonForm === 'specific' && row.lessonPairId !== undefined
+        ? classByPair.get(row.lessonPairId)
+        : undefined;
+      return classForm === undefined ? row : { ...row, classForm };
+    });
     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
@@ -3757,7 +4129,15 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       const perDomain = Object.fromEntries(
         Object.entries(rawStats.perDomain).filter(([d]) => !holdout.domains.includes(canonicalDomainKey(d))),
       );
-      const stats = { ...rawStats, topUses: topHoldout.exported, perDomain };
+      const generalizedPairs = new Set(patterns.flatMap((p) => p.lessonPairId === undefined ? [] : [p.lessonPairId]));
+      const unpairedLessons = patterns.filter((p) => p.lessonPairId === undefined).length;
+      const stats = {
+        ...rawStats,
+        topUses: topHoldout.exported,
+        perDomain,
+        generalized: generalizedPairs.size,
+        logicalLessons: generalizedPairs.size + unpairedLessons,
+      };
       const backendStats = resolveLearningBackend(projectRoot).getStats();
       if (asJson) {
         write(JSON.stringify({ patterns, stats, learning: backendStats, withheld: holdout.withheld.length, withheldDomains: holdout.domains }));
@@ -3769,6 +4149,7 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       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}`);
+      write(`  generalized: ${stats.generalized} of ${stats.logicalLessons} lessons`);
       write(`  re-teach trend: ${stats.teachEvents} teach event(s), ${stats.reinforceEvents} reinforce event(s)`);
       write('  top uses:');
       for (const row of stats.topUses) write(`    ${row.uses}× [${row.reward.toFixed(2)}] (${row.domain}) ${row.pattern.slice(0, 80)}`);
@@ -3889,6 +4270,10 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       ? ('lexical' as const)
       : ('hybrid' as const);
   const wantedDomain = options.get('domain');
+  const classRecallOptions = {
+    onClassDegraded: writeErr,
+    ...(classMatcher === undefined ? {} : { classMatcher }),
+  };
   // OVER-FETCH before boosting (Codex QE #5): the boost used to run on hits ALREADY
   // truncated to `limit`, so an exact-domain lesson sitting at rank limit+1 could
   // never receive its promised lift — the feature was weakest in exactly the case it
@@ -3911,8 +4296,8 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   // second occurrence. Foreign stdout is routed to stderr for the duration of the engine call — our
   // own output is written after it returns.
   const result = asJson
-    ? await withForeignStdoutOnStderr(() => recallHybrid(projectRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) }))
-    : await recallHybrid(projectRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) });
+    ? await withForeignStdoutOnStderr(() => recallHybrid(projectRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...classRecallOptions, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) }))
+    : await recallHybrid(projectRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...classRecallOptions, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) });
 
   if (mode === 'semantic' && result.vectorEngine === 'none') {
     // --semantic is an explicit ask — degrading it silently would be dishonest (FR-3).
@@ -3948,13 +4333,26 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   let globalHits: typeof result.hits = [];
   if (readGlobal) {
     const g = asJson
-      ? await withForeignStdoutOnStderr(() => recallHybrid(globalRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) }))
-      : await recallHybrid(globalRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) });
+      ? await withForeignStdoutOnStderr(() => recallHybrid(globalRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...classRecallOptions, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) }))
+      : await recallHybrid(globalRoot, query, { limit: fetchLimit, mode, deferExposures: true, ...classRecallOptions, ...(wantedDomain !== undefined ? { domain: wantedDomain } : {}) });
     globalHits = g.hits;
   }
+  const projectHits = boost ? boost.hits : result.hits;
+  // TWO different keys on purpose, and they must not be unified. The cross-store MERGE key is the
+  // lesson TEXT: the same lesson taught into the project store and the global store is one lesson
+  // shown once, labelled `both`, and those two records legitimately differ in timestamp, reward and
+  // domain. The matchedForm LOOKUP key may be narrower. Folding the merge key into
+  // patternIdentityOf (which includes ts) made two `dz teach` calls of identical text stop
+  // collapsing — it reddened the pre-existing P3 case in recall-reads-both-stores.test.ts.
+  const mergeKey = (hit: (typeof projectHits)[number]): string => hit.pattern.pattern;
+  const globalByIdentity = new Map(globalHits.map((hit) => [mergeKey(hit), hit]));
   const merged = readGlobal
-    ? mergeStoreHits(boost ? boost.hits : result.hits, globalHits, (h) => h.pattern.pattern)
-    : (boost ? boost.hits : result.hits);
+    ? mergeStoreHits(projectHits, globalHits, mergeKey).map((hit) => {
+        if (hit.origin !== 'both') return hit;
+        const matchedForm = mergeLessonMatchedForms(hit.matchedForm, globalByIdentity.get(mergeKey(hit))?.matchedForm);
+        return matchedForm === undefined ? hit : { ...hit, matchedForm };
+      })
+    : projectHits;
   const hits = merged.slice(0, limit);
   // Computed ONCE, honoured by EVERY return path. It used to live only on the text tail, so the two
   // paths that return earlier — `--json` and the zero-hits branch — still reported success. That
@@ -4002,6 +4400,7 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // version emitted the number while its own comment promised null (found by independent review).
     write(JSON.stringify(hits.map((h) => ({
       ...h.pattern,
+      ...(h.matchedForm === undefined ? {} : { matchedForm: h.matchedForm }),
       relevance: boost === null && 'score' in h && typeof h.score === 'number' ? h.score : null,
       // The TRUE cosine, as a second companion key — the design named it and the first ship missed
       // it, so a scripted consumer STILL could not threshold (found while recalibrating the floors:
@@ -4066,6 +4465,10 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // guessing which second one answered.
     write(`  store (read): ${join(globalRoot, '.dz')}  [cross-project]`);
   }
+  const classMatches = hits.filter((h) => h.matchedForm === 'class' || h.matchedForm === 'both').length;
+  if (hits.some((h) => h.pattern.classForm !== undefined)) {
+    write(`  class-form matches: ${classMatches} of ${hits.length}`);
+  }
   let sawQuarantined = false;
   for (const h of hits) {
     const backendTag = vectorOn ? ` ⟨${h.backend}⟩` : '';
@@ -4090,9 +4493,21 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // 160, not 80: at 80 characters the evidence a reader needs to judge relevance sits in the
     // hidden remainder, and the cosine then appears to describe the visible fragment rather than
     // the whole lesson. `--full` prints it all, still on one line.
-    const width = flags.has('full') ? Number.POSITIVE_INFINITY : 160;
-    const oneLined = oneLine(h.pattern.pattern);
-    const shown = width === Number.POSITIVE_INFINITY ? oneLined : oneLined.slice(0, width);
+    const specificText = oneLine(h.pattern.pattern);
+    const classText = h.pattern.classForm === undefined ? undefined : oneLine(h.pattern.classForm);
+    let shown = specificText;
+    if (classText !== undefined) {
+      const suffix = ` [match: ${h.matchedForm ?? 'specific'}]`;
+      if (flags.has('full')) {
+        shown = `specific: ${specificText} · class: ${classText}${suffix}`;
+      } else {
+        const contentWidth = Math.max(2, 160 - 'specific: '.length - ' · class: '.length - suffix.length);
+        const specificWidth = Math.floor(contentWidth / 2);
+        shown = `specific: ${specificText.slice(0, specificWidth)} · class: ${classText.slice(0, contentWidth - specificWidth)}${suffix}`;
+      }
+    } else if (!flags.has('full')) {
+      shown = shown.slice(0, 160);
+    }
     // WHICH store this hit came from. A merged list that does not say re-creates the fragmentation
     // blindness the store-location line just removed, one level down: the reader would see more
     // results and have no way to tell whether the global store is even connected.
@@ -5096,7 +5511,13 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
     ? selectArg.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
     : getPreset(preset)?.skills;
   const install = select !== undefined && select.length > 0
-    ? await installSkills({ target, projectRoot, cwd, explicitSkillsDir: options.get('skills-dir'), select, force: flags.has('force'), enrich: flags.has('enrich') })
+    ? await installSkills({
+        target, projectRoot, cwd, explicitSkillsDir: options.get('skills-dir'), select,
+        force: flags.has('force'), enrich: flags.has('enrich'), noHooks: flags.has('no-hooks'),
+        noIntegrations: flags.has('no-integrations'),
+        noVerify: flags.has('no-verify'),
+        ...(options.get('allow-integrations') !== undefined ? { allowIntegrations: options.get('allow-integrations')! } : {}),
+      })
     : undefined;
   if (install) {
     write(`║     ${String(install.results.length).padStart(2)} skill(s), ${String(install.written).padStart(3)} file(s) written${' '.repeat(15)}║`);
@@ -5106,6 +5527,7 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
 
   // Step 5 (ADR-001 §8): DELIVER the codex hooks and verify them live. Non-aborting — the rest of
   // setup has already run and the summary still prints; only the exit code carries the failure.
+  let setupIntegrationOutcomes: readonly IntegrationOutcome[] = install?.integrations ?? [];
   let codexHooksOk = true;
   if (target === 'codex' && !flags.has('no-hooks')) {
     write(`║  5. Delivering codex hooks (live verify)...           ║`);
@@ -5113,6 +5535,11 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
     codexHooksOk = delivery.ok;
     for (const line of delivery.stdout) write(line);
     for (const line of delivery.stderr) writeErr(line);
+    const hookIndex = setupIntegrationOutcomes.findIndex((row) => row.component === 'hooks' && row.status !== 'not-requested');
+    if (hookIndex !== -1) {
+      const hook = normalizeCodexHookOutcome(setupIntegrationOutcomes[hookIndex]!, delivery, flags.has('no-verify'));
+      setupIntegrationOutcomes = setupIntegrationOutcomes.map((row, index) => index === hookIndex ? hook : row);
+    }
   }
 
   write(`╠══════════════════════════════════════════════════════╣`);
@@ -5132,6 +5559,9 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
   if (install) {
     write(`dz setup: ${install.results.length} skill(s), ${install.written} file(s) written, ${install.skipped} skipped`
       + (install.dirsSearched > 1 ? `  (searched ${install.dirsSearched} skill dirs)` : ''));
+    for (const outcome of setupIntegrationOutcomes) {
+      write(`dz setup integration ${outcome.component}: ${outcome.status.toUpperCase()}${outcome.reasonCode ? ` (${outcome.reasonCode})` : ''}`);
+    }
     writeMissingSkillsHint(write, install.missing, selectArg !== undefined ? undefined : preset);
   }
   // A hook that was written but never witnessed firing is NOT a completed setup (ADR-002 §5): the
@@ -5146,7 +5576,8 @@ async function cmdSetup(options: Map<string, string>, flags: Set<string>, cwd: s
   if (erroredSteps.length > 0) {
     write(`\n✗ setup reported ${erroredSteps.length} failed step(s): ${erroredSteps.join(', ')} — exit 1`);
   }
-  return codexHooksOk && erroredSteps.length === 0 ? 0 : 1;
+  const integrationsOk = !setupIntegrationOutcomes.some((row) => row.status === 'refused');
+  return codexHooksOk && erroredSteps.length === 0 && integrationsOk ? 0 : 1;
 }
 
 function cmdPretrain(options: Map<string, string>, cwd: string, write: Write): number {
@@ -5804,6 +6235,9 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     if (guardResult.verdict === 'block') write(`dz publish: ⚠ guard BLOCK overridden via --no-guard: ${noGuard} (logged)`);
     else if (guardResult.verdict === 'warn') for (const v of guardResult.violations) write(`dz publish: ⚠ guard warn — ${v.rule}: ${v.detail}`);
     else write('dz publish: ✓ guard pre-flight passed');
+    for (const observation of guardResult.observations ?? []) {
+      write(`dz publish: ℹ guard observation — ${observation.rule} ${observation.scope}: ${observation.detail} [${observation.status}]`);
+    }
     for (const n of guardResult.notes ?? []) write(`dz publish: ℹ guard note — ${n}`); // FN-7: on the record, never blocking
   }
 
@@ -7503,6 +7937,31 @@ export interface CodexHooksSummary {
   readonly stderr: readonly string[];
 }
 
+/** Map the retained Codex hook writer's one live verdict into the common integration contract. */
+export function normalizeCodexHookOutcome(
+  base: IntegrationOutcome,
+  delivery: CodexHooksSummary & { readonly report: CodexHooksSyncReport },
+  noVerify = false,
+): IntegrationOutcome {
+  if (delivery.report.ready) {
+    return {
+      target: 'codex', component: 'hooks', status: 'emitted',
+      registrations: [{ id: 'dz-codex-hooks', scope: 'user', registered: delivery.report.installed, approval: delivery.report.trust === 'trusted' ? 'approved' : 'unknown', ready: true }],
+      carrier: { scope: 'user', path: '$CODEX_HOME/hooks.json' },
+      ...(delivery.report.codexVersion !== null ? { runtimeVersion: delivery.report.codexVersion } : {}),
+      evidenceVersion: 'codex-hooks-live-v1',
+    };
+  }
+  return {
+    ...base,
+    target: 'codex', component: 'hooks', status: 'refused',
+    registrations: [{ id: 'dz-codex-hooks', scope: 'user', registered: delivery.report.installed, approval: delivery.report.trust === 'trusted' ? 'approved' : 'unknown', ready: false }],
+    reasonCode: 'CURRENT_LIVE_CHECK_FAILED',
+    remediation: noVerify ? '--no-verify cannot establish ready; rerun with live verification' : 'approve the managed hooks and rerun the live verification',
+    applied: delivery.report.written || delivery.report.installed,
+  };
+}
+
 /**
  * What the user is told about a sync report — the ONE place the success word can be printed.
  *
@@ -7831,6 +8290,392 @@ function gatherReadmeCounts(root: string): { label: string; a: number; b: number
   return pairs;
 }
 
+const MAX_VOLUME_FILES_PER_SCOPE = 512;
+const MAX_VOLUME_BYTES_PER_SCOPE = 32 * 1024 * 1024;
+const CYRILLIC_CHARACTER = /\p{Script=Cyrillic}/u;
+
+function volumePathInside(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(root + sep);
+}
+
+function cyrillicUtf8Bytes(buffer: Buffer): number {
+  let bytes = 0;
+  for (const character of buffer.toString('utf8')) {
+    if (CYRILLIC_CHARACTER.test(character)) bytes += Buffer.byteLength(character, 'utf8');
+  }
+  return bytes;
+}
+
+function gatherTemplateVolumeTarget(
+  packageDir: string,
+  target: string,
+): TemplateVolumeTargetFact | undefined {
+  const templateRoot = join(packageDir, 'templates', '.claude');
+  if (!existsSync(templateRoot)) return undefined;
+  const files: TemplateVolumeFileFact[] = [];
+  const realFiles = new Set<string>();
+  let totalBytes = 0;
+  let failure: { reason: string; detail: string } | undefined;
+  let packageReal: string;
+  let templateReal: string;
+  try {
+    packageReal = realpathSync(packageDir);
+    templateReal = realpathSync(templateRoot);
+    if (!volumePathInside(packageReal, templateReal)) {
+      failure = { reason: 'template-root-escape', detail: templateRoot };
+    }
+  } catch (error) {
+    return {
+      target,
+      files,
+      collection: { complete: false, reason: 'template-root-unreadable', detail: error instanceof Error ? error.message : String(error) },
+    };
+  }
+
+  const fail = (reason: string, detail: string): void => {
+    failure ??= { reason, detail: detail.replace(/\s+/g, ' ').slice(0, 240) };
+  };
+  const addFile = (absolute: string, kind: 'rules' | 'commands' | 'skills'): void => {
+    if (failure !== undefined) return;
+    if (files.length >= MAX_VOLUME_FILES_PER_SCOPE) {
+      fail('template-file-cap-exceeded', `${MAX_VOLUME_FILES_PER_SCOPE} files`);
+      return;
+    }
+    try {
+      const stat = lstatSync(absolute);
+      if (!stat.isFile()) { fail('template-input-not-regular', absolute); return; }
+      const real = realpathSync(absolute);
+      if (!volumePathInside(templateReal, real)) { fail('template-input-escape', absolute); return; }
+      if (realFiles.has(real)) { fail('template-input-duplicate', absolute); return; }
+      if (stat.size <= 0 || stat.size > MAX_VOLUME_BYTES_PER_SCOPE - totalBytes) {
+        fail(stat.size <= 0 ? 'template-input-empty' : 'template-byte-cap-exceeded', absolute);
+        return;
+      }
+      const content = readFileSync(absolute);
+      if (content.byteLength <= 0 || content.byteLength > MAX_VOLUME_BYTES_PER_SCOPE - totalBytes) {
+        fail(content.byteLength <= 0 ? 'template-input-empty' : 'template-byte-cap-exceeded', absolute);
+        return;
+      }
+      realFiles.add(real);
+      totalBytes += content.byteLength;
+      files.push({
+        path: relative(packageDir, absolute).split(sep).join('/'),
+        kind,
+        bytes: content.byteLength,
+        cyrillicUtf8Bytes: cyrillicUtf8Bytes(content),
+      });
+    } catch (error) {
+      fail('template-input-unreadable', `${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const scanFlat = (name: 'rules' | 'commands'): void => {
+    const dir = join(templateRoot, name);
+    if (!existsSync(dir) || failure !== undefined) return;
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.name.endsWith('.md')) continue;
+        addFile(join(dir, entry.name), name);
+      }
+    } catch (error) {
+      fail('template-directory-unreadable', `${dir}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const scanSkills = (dir: string): void => {
+    if (!existsSync(dir) || failure !== undefined) return;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      fail('template-directory-unreadable', `${dir}: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    for (const entry of entries) {
+      if (failure !== undefined) return;
+      const absolute = join(dir, entry.name);
+      if (entry.isSymbolicLink()) { fail('template-input-not-regular', absolute); return; }
+      if (entry.isDirectory()) scanSkills(absolute);
+      else if (entry.name === 'SKILL.md') addFile(absolute, 'skills');
+    }
+  };
+
+  scanFlat('rules');
+  scanFlat('commands');
+  scanSkills(join(templateRoot, 'skills'));
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    target,
+    files,
+    collection: failure === undefined
+      ? { complete: true }
+      : { complete: false, reason: failure.reason, detail: failure.detail },
+  };
+}
+
+function volumeGitText(root: string, args: readonly string[], allowedStatuses: readonly number[] = [0]): string {
+  const result = spawnSync('git', [...args], {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (result.status === null || !allowedStatuses.includes(result.status)) {
+    throw result.error ?? new Error(`git ${args[0] ?? ''} exited ${String(result.status)}`);
+  }
+  return result.stdout ?? '';
+}
+
+function parseGuardStatusPaths(root: string): { readonly code: string; readonly path: string }[] {
+  const text = volumeGitText(root, ['status', '--porcelain', '-uall']);
+  return text.split('\n').flatMap((line) => {
+    if (line.length < 4) return [];
+    const code = line.slice(0, 2);
+    const raw = line.slice(3).trim();
+    const path = (raw.includes(' -> ') ? raw.split(' -> ')[1] : raw)?.trim();
+    return path ? [{ code, path }] : [];
+  });
+}
+
+function parseFeatureTier(text: string): FeatureTier | undefined {
+  const match = text.match(/^##\s+Tier:\s*(S|M|L|XL)\s*$/m);
+  return match?.[1] as FeatureTier | undefined;
+}
+
+function parseFeatureActiveSteps(text: string): (number | string)[] | undefined {
+  const section = text.match(/^## Active steps[^\n]*\n([\s\S]*?)(?=^## |(?![\s\S]))/mi)?.[1];
+  if (section === undefined) return undefined;
+  const steps = [...section.matchAll(/\b(?:10|[0-9](?:\.5)?)\b/g)].map((match) => match[0]!);
+  return [...new Set(steps)];
+}
+
+function featureLifecycle(root: string, slug: string, assessment: string | undefined): FeatureVolumeFact['lifecycle'] {
+  if (assessment !== undefined && /^Lifecycle:\s*complete\s*$/mi.test(assessment)) return { phase: 'complete' };
+  try {
+    const state = JSON.parse(readFileSync(join(root, '.dz', 'feature-adr', 'learning-state', `${slug}.json`), 'utf8')) as { step?: unknown };
+    const match = typeof state.step === 'string' ? state.step.match(/\bStep\s+(\d+(?:\.5)?)/i) : null;
+    if (!match?.[1]) return undefined;
+    const current = Number(match[1]);
+    if (!Number.isFinite(current)) return undefined;
+    return { phase: 'in-progress', completedThroughStep: current <= 0 ? 0 : Math.ceil(current) - 1 };
+  } catch {
+    return undefined;
+  }
+}
+
+interface GatheredFeatureVolume {
+  readonly fact: FeatureVolumeFact;
+  readonly manifestText?: string;
+}
+
+function gatherFeatureVolumeFact(root: string, slug: string): GatheredFeatureVolume {
+  const featureDir = join(root, 'features', slug);
+  const artifacts: FeatureArtifactFact[] = [];
+  const contents = new Map<string, Buffer>();
+  let totalBytes = 0;
+  let failure: { reason: string; detail: string } | undefined;
+  let rootReal: string;
+  let featureReal: string;
+  try {
+    rootReal = realpathSync(root);
+    featureReal = realpathSync(featureDir);
+    if (!volumePathInside(rootReal, featureReal)) failure = { reason: 'feature-root-escape', detail: featureDir };
+  } catch (error) {
+    return { fact: {
+      slug,
+      artifacts,
+      collection: { complete: false, reason: 'feature-root-unreadable', detail: error instanceof Error ? error.message : String(error) },
+    } };
+  }
+  const fail = (reason: string, detail: string): void => {
+    failure ??= { reason, detail: detail.replace(/\s+/g, ' ').slice(0, 240) };
+  };
+  const addArtifact = (absolute: string): void => {
+    if (failure !== undefined) return;
+    if (artifacts.length >= MAX_VOLUME_FILES_PER_SCOPE) {
+      fail('feature-file-cap-exceeded', `${MAX_VOLUME_FILES_PER_SCOPE} files`);
+      return;
+    }
+    try {
+      const stat = lstatSync(absolute);
+      if (!stat.isFile()) { fail('feature-input-not-regular', absolute); return; }
+      const real = realpathSync(absolute);
+      if (!volumePathInside(featureReal, real)) { fail('feature-input-escape', absolute); return; }
+      if (stat.size <= 0 || stat.size > MAX_VOLUME_BYTES_PER_SCOPE - totalBytes) {
+        fail(stat.size <= 0 ? 'feature-input-empty' : 'feature-byte-cap-exceeded', absolute);
+        return;
+      }
+      const content = readFileSync(absolute);
+      if (content.byteLength <= 0 || content.byteLength > MAX_VOLUME_BYTES_PER_SCOPE - totalBytes) {
+        fail(content.byteLength <= 0 ? 'feature-input-empty' : 'feature-byte-cap-exceeded', absolute);
+        return;
+      }
+      const path = relative(featureDir, absolute).split(sep).join('/');
+      totalBytes += content.byteLength;
+      contents.set(path, content);
+      artifacts.push({ path, bytes: content.byteLength });
+    } catch (error) {
+      fail('feature-input-unreadable', `${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const scanNested = (dir: string): void => {
+    if (!existsSync(dir) || failure !== undefined) return;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      fail('feature-directory-unreadable', `${dir}: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    for (const entry of entries) {
+      if (failure !== undefined) return;
+      const absolute = join(dir, entry.name);
+      if (entry.isSymbolicLink()) { fail('feature-input-not-regular', absolute); return; }
+      if (entry.isDirectory()) scanNested(absolute);
+      else addArtifact(absolute);
+    }
+  };
+  try {
+    const entries = readdirSync(featureDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (failure !== undefined) break;
+      const absolute = join(featureDir, entry.name);
+      if (entry.name === '03_adr' || entry.name === '07_code_changes') {
+        if (entry.isSymbolicLink() || !entry.isDirectory()) fail('feature-input-not-regular', absolute);
+        else scanNested(absolute);
+      } else if (entry.name === 'README.md' || /^0[0-9](?:[_.-][^/]*)?\.md$/.test(entry.name)) {
+        addArtifact(absolute);
+      }
+    }
+  } catch (error) {
+    fail('feature-directory-unreadable', `${featureDir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  artifacts.sort((a, b) => a.path.localeCompare(b.path));
+  const assessment = contents.get('00_complexity_assessment.md')?.toString('utf8');
+  const tier = assessment !== undefined ? parseFeatureTier(assessment) : undefined;
+  const activeSteps = assessment !== undefined ? parseFeatureActiveSteps(assessment) : undefined;
+  const lifecycle = featureLifecycle(root, slug, assessment);
+  const fact: FeatureVolumeFact = {
+    slug,
+    ...(tier !== undefined ? { tier } : {}),
+    ...(activeSteps !== undefined ? { activeSteps } : {}),
+    namedConsumers: [],
+    ...(lifecycle !== undefined ? { lifecycle } : {}),
+    artifacts,
+    collection: failure === undefined
+      ? { complete: true }
+      : { complete: false, reason: failure.reason, detail: failure.detail },
+  };
+  const manifestText = contents.get('07_code_changes/change_manifest.md')?.toString('utf8');
+  return { fact, ...(manifestText !== undefined ? { manifestText } : {}) };
+}
+
+function manifestPaths(text: string, slug: string): string[] {
+  const paths = new Set<string>();
+  for (const line of text.split('\n')) {
+    const match = line.match(/^\s*-\s+`?([^`]+?)`?(?:\s+[—-]\s+.*)?$/);
+    if (!match?.[1]) continue;
+    const path = match[1].trim().replace(/\\/g, '/').replace(/^\.\//, '');
+    if (path === '' || path.startsWith('/') || path.split('/').some((part) => part === '..')) continue;
+    if (path.startsWith(`features/${slug}/`)) continue;
+    paths.add(path);
+  }
+  return [...paths].sort();
+}
+
+function attributableDiff(
+  root: string,
+  slug: string,
+  feature: GatheredFeatureVolume,
+  status: readonly { readonly code: string; readonly path: string }[],
+  changedSlugs: readonly string[],
+): NonNullable<FeatureVolumeFact['diff']> {
+  if (changedSlugs.length !== 1 || changedSlugs[0] !== slug) {
+    return { attributable: false, reason: changedSlugs.length > 1 ? 'ambiguous-feature-attribution' : 'feature-not-attributable' };
+  }
+  if (feature.manifestText === undefined) return { attributable: false, reason: 'change-manifest-unavailable' };
+  const listed = manifestPaths(feature.manifestText, slug);
+  const changedByPath = new Map(status.map((item) => [item.path, item.code]));
+  const changed = listed.filter((path) => changedByPath.has(path));
+  if (changed.length === 0) return { attributable: true, bytes: 0, base: 'HEAD', head: 'working-tree', method: 'git-unified-diff-bytes/v1', excludedFeaturePath: `features/${slug}/**` };
+  const tracked: string[] = [];
+  const untracked: string[] = [];
+  for (const path of changed) {
+    const absolute = resolve(root, path);
+    if (!volumePathInside(root, absolute)) return { attributable: false, reason: 'manifest-path-escape' };
+    if (changedByPath.get(path) === '??') {
+      try {
+        const stat = lstatSync(absolute);
+        const real = realpathSync(absolute);
+        if (!stat.isFile() || !volumePathInside(root, real) || stat.size > MAX_VOLUME_BYTES_PER_SCOPE) {
+          return { attributable: false, reason: 'untracked-diff-input-refused' };
+        }
+      } catch { return { attributable: false, reason: 'untracked-diff-input-unreadable' }; }
+      untracked.push(path);
+    } else {
+      tracked.push(path);
+    }
+  }
+  let bytes = 0;
+  try {
+    if (tracked.length > 0) {
+      const diff = volumeGitText(root, ['diff', '--binary', '--no-ext-diff', 'HEAD', '--', ...tracked]);
+      bytes += Buffer.byteLength(diff, 'utf8');
+    }
+    for (const path of untracked) {
+      const diff = volumeGitText(root, ['diff', '--no-index', '--binary', '--', '/dev/null', resolve(root, path)], [0, 1]);
+      bytes += Buffer.byteLength(diff, 'utf8');
+      if (bytes > MAX_VOLUME_BYTES_PER_SCOPE) return { attributable: false, reason: 'diff-byte-cap-exceeded' };
+    }
+  } catch {
+    return { attributable: false, reason: 'git-diff-failed' };
+  }
+  return {
+    attributable: true,
+    bytes,
+    base: 'HEAD',
+    head: 'working-tree',
+    method: 'git-unified-diff-bytes/v1',
+    excludedFeaturePath: `features/${slug}/**`,
+  };
+}
+
+function gatherVolumeShadowFacts(
+  root: string,
+  packages: readonly { readonly dir: string; readonly name: string; readonly privateFlag: boolean }[],
+): VolumeShadowInput {
+  const templates = packages
+    .filter((item) => !item.privateFlag)
+    .sort((a, b) => a.name.localeCompare(b.name) || a.dir.localeCompare(b.dir))
+    .flatMap((item) => {
+      const fact = gatherTemplateVolumeTarget(join(root, item.dir), item.name);
+      return fact === undefined ? [] : [fact];
+    });
+  let status: { code: string; path: string }[];
+  try { status = parseGuardStatusPaths(root); }
+  catch { return templates.length > 0 ? { templates } : {}; }
+  const slugs = [...new Set(status.flatMap((item) => {
+    const match = item.path.match(/^features\/([^/]+)\//);
+    return match?.[1] ? [match[1]] : [];
+  }))].sort();
+  const gathered = slugs.slice(0, 32).map((slug) => gatherFeatureVolumeFact(root, slug));
+  const measuredFeatures = gathered.map((feature) => ({
+    ...feature.fact,
+    diff: attributableDiff(root, feature.fact.slug, feature, status, slugs),
+  }));
+  const cappedFeatures: FeatureVolumeFact[] = slugs.slice(32).map((slug) => ({
+    slug,
+    artifacts: [],
+    collection: {
+      complete: false,
+      reason: 'feature-scope-cap-exceeded',
+      detail: 'only the first 32 lexicographically sorted changed feature scopes were traversed',
+    },
+  }));
+  const features = [...measuredFeatures, ...cappedFeatures];
+  return {
+    ...(templates.length > 0 ? { templates } : {}),
+    ...(features.length > 0 ? { features } : {}),
+  };
+}
+
 /** Gather the facts one op needs. All I/O is best-effort — a missing signal skips its rule, never crashes. */
 function gatherGuardFacts(op: string, root: string, text: string | undefined, storeCap: number): Record<string, unknown> {
   const facts: Record<string, unknown> = { op };
@@ -7954,7 +8799,7 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
     const manifests: Manifest[] = [];
     const located: { dir: string; m: Manifest }[] = [];
     try {
-      const out = execSync('git ls-files "packages/@dzhechkov/*/package.json"', { cwd: root, encoding: 'utf-8' });
+      const out = volumeGitText(root, ['ls-files', 'packages/@dzhechkov/*/package.json']);
       for (const rel of out.split('\n').map((s) => s.trim()).filter(Boolean)) {
         try {
           const m = JSON.parse(readFileSync(join(root, rel), 'utf8')) as Manifest;
@@ -7978,6 +8823,11 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       packages.push({ name: m.name ?? '(unnamed)', deps });
     }
     facts['packages'] = packages;
+    facts['volume'] = gatherVolumeShadowFacts(root, located.map(({ dir, m }) => ({
+      dir,
+      name: m.name ?? dir,
+      privateFlag: m.private === true,
+    })));
 
     // 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
@@ -8202,6 +9052,11 @@ function runGuardEvaluation(root: string, op: string, text: string | undefined,
   return result;
 }
 
+function renderGuardObservation(observation: GuardObservation): string {
+  const tag = observation.status === 'unknown' ? 'note' : 'observe';
+  return `  [${tag}] ${observation.rule} ${observation.scope}: ${observation.detail} [${observation.status}]`;
+}
+
 /**
  * The tail facts of an append-only log, read from its END — O(1) in the file size, which is what
  * lets the chain be extended on every append without a full-file scan (FR-2). Anything unreadable
@@ -8542,7 +9397,8 @@ function cmdGuardPromote(options: Map<string, string>, flags: Set<string>, root:
       ...next,
       entries: Object.fromEntries(Object.entries(next.entries).map(([k, v]) => (applied.includes(k) ? [k, { ...v, appliedTs: nowTs }] : [k, v]))),
     };
-    try { writeJsonAtomic(join(root, PROMOTION_STATE_FILE), withApplied); } catch { /* best-effort */ }
+    const withEvidence = recordPromotionRunEvidence(withApplied, report, nowTs);
+    try { writeJsonAtomic(join(root, PROMOTION_STATE_FILE), withEvidence); } catch { /* best-effort */ }
   }
 
   // A refused conflict means the requested apply did NOT fully happen — exit non-zero rather than
@@ -8634,6 +9490,7 @@ function cmdGuard(options: Map<string, string>, flags: Set<string>, cwd: string,
 
   const glyph = result.verdict === 'block' ? '✗' : result.verdict === 'warn' ? '⚠' : '✓';
   write(`dz guard (${op}): ${glyph} ${result.verdict.toUpperCase()}  [checked: ${result.checked.join(', ') || 'no rules for this op'}]`);
+  for (const observation of result.observations ?? []) write(renderGuardObservation(observation));
   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)`);
@@ -13058,6 +13915,160 @@ function readOptionalText(path: string): string {
   }
 }
 
+function localEvidenceReadReason(resource: 'promotion-journal' | 'guard-audit', error: unknown): string {
+  const code = error && typeof error === 'object' && 'code' in error ? String((error as { code?: unknown }).code) : '';
+  return code === 'ENOENT' ? `${resource}-missing` : `${resource}-unreadable`;
+}
+
+interface PromotionEvidenceRead {
+  readonly source: FunnelEvidenceSource<PromotionRunEvidence>;
+  readonly acceptances: readonly PromotionAcceptanceEvidence[];
+  readonly truncatedPeriods: readonly string[];
+  readonly acceptanceHistoryComplete: boolean;
+}
+
+function unavailablePromotionEvidence(reason: string): PromotionEvidenceRead {
+  return { source: { status: 'not-measured', reason }, acceptances: [], truncatedPeriods: [], acceptanceHistoryComplete: false };
+}
+
+function readPromotionRunEvidence(root: string): PromotionEvidenceRead {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(join(root, PROMOTION_STATE_FILE), 'utf-8')) as unknown;
+  } catch (error) {
+    const reason = error instanceof SyntaxError
+      ? 'promotion-journal-malformed'
+      : localEvidenceReadReason('promotion-journal', error);
+    return unavailablePromotionEvidence(reason);
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return unavailablePromotionEvidence('promotion-journal-malformed');
+  }
+  const record = raw as Record<string, unknown>;
+  if (record['version'] !== 1 || !Object.hasOwn(record, 'runs')) {
+    return unavailablePromotionEvidence(
+      record['version'] === 1 ? 'promotion-history-not-recorded' : 'promotion-journal-malformed',
+    );
+  }
+  if (!Array.isArray(record['runs'])) {
+    return unavailablePromotionEvidence('promotion-history-malformed');
+  }
+  const state = normalizePromotionState(raw);
+  if (state.runs === undefined || state.runs.length !== record['runs'].length) {
+    return unavailablePromotionEvidence('promotion-history-malformed');
+  }
+  if (
+    (Object.hasOwn(record, 'acceptances') && (
+      !Array.isArray(record['acceptances']) || state.acceptances?.length !== record['acceptances'].length
+    )) ||
+    (Object.hasOwn(record, 'truncatedRunPeriods') && (
+      !Array.isArray(record['truncatedRunPeriods']) || state.truncatedRunPeriods?.length !== record['truncatedRunPeriods'].length
+    )) ||
+    (Object.hasOwn(record, 'acceptanceHistoryComplete') && typeof record['acceptanceHistoryComplete'] !== 'boolean')
+  ) {
+    return unavailablePromotionEvidence('promotion-history-malformed');
+  }
+  const derivedAcceptances = state.runs.flatMap((run) => run.candidates
+    .filter((candidate) => candidate.verdict === 'promote' && candidate.ruleContentAnchor !== null)
+    .map((candidate) => ({ ruleContentAnchor: candidate.ruleContentAnchor!, acceptedTs: run.ts })));
+  const claimedAcceptanceComplete = state.acceptanceHistoryComplete ??
+    ((state.truncatedRunPeriods?.length ?? 0) === 0 && state.runs.every((run) => run.complete === true));
+  if (claimedAcceptanceComplete && state.acceptances !== undefined && derivedAcceptances.some((derived) =>
+    !state.acceptances!.some((stored) =>
+      stored.ruleContentAnchor === derived.ruleContentAnchor &&
+      Date.parse(stored.acceptedTs) <= Date.parse(derived.acceptedTs),
+    ),
+  )) {
+    return unavailablePromotionEvidence('promotion-history-malformed');
+  }
+  const acceptancesByAnchor = new Map<string, PromotionAcceptanceEvidence>();
+  for (const acceptance of [...(state.acceptances ?? []), ...derivedAcceptances]) {
+    const prior = acceptancesByAnchor.get(acceptance.ruleContentAnchor);
+    if (prior === undefined || Date.parse(acceptance.acceptedTs) < Date.parse(prior.acceptedTs)) {
+      acceptancesByAnchor.set(acceptance.ruleContentAnchor, acceptance);
+    }
+  }
+  return {
+    source: { status: 'measured', rows: state.runs },
+    acceptances: [...acceptancesByAnchor.values()],
+    truncatedPeriods: state.truncatedRunPeriods ?? [],
+    acceptanceHistoryComplete: claimedAcceptanceComplete,
+  };
+}
+
+interface GuardAuditEvidenceRead {
+  readonly source: FunnelEvidenceSource<GuardEvent>;
+  readonly rows: readonly GuardEvent[];
+  readonly text: string | null;
+}
+
+function readGuardAuditEvidence(root: string): GuardAuditEvidenceRead {
+  let text: string;
+  try {
+    text = readFileSync(join(root, '.dz', 'guard-audit.jsonl'), 'utf-8');
+  } catch (error) {
+    return {
+      source: { status: 'not-measured', reason: localEvidenceReadReason('guard-audit', error) },
+      rows: [],
+      text: null,
+    };
+  }
+  const rows: GuardEvent[] = [];
+  let malformed = false;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const raw = JSON.parse(line) as Record<string, unknown>;
+      if (
+        !isOffsetIsoTimestamp(raw['ts']) ||
+        !['publish', 'teach', 'consolidate', 'reindex'].includes(String(raw['op'])) ||
+        !['pass', 'warn', 'block'].includes(String(raw['verdict']))
+      ) {
+        malformed = true;
+        continue;
+      }
+      const violations: { rule: string; contentAnchor?: string }[] = [];
+      if (!Array.isArray(raw['violations'])) {
+        malformed = true;
+        continue;
+      }
+      for (const item of raw['violations']) {
+        const rule = item && typeof item === 'object' ? (item as { rule?: unknown }).rule : undefined;
+        if (typeof rule !== 'string' || rule === '' || rule.length > 200) {
+          malformed = true;
+          continue;
+        }
+        const anchor = (item as { contentAnchor?: unknown }).contentAnchor;
+        if (anchor !== undefined && !isLessonRuleContentAnchor(anchor)) {
+          malformed = true;
+          continue;
+        }
+        violations.push({ rule, ...(typeof anchor === 'string' ? { contentAnchor: anchor } : {}) });
+      }
+      const verdict = raw['verdict'] as 'pass' | 'warn' | 'block';
+      if ((verdict === 'pass') !== (violations.length === 0)) malformed = true;
+      rows.push({
+        ts: raw['ts'],
+        op: raw['op'] as 'publish' | 'teach' | 'consolidate' | 'reindex',
+        verdict,
+        rules: violations.map((item) => item.rule),
+        violations,
+      });
+    } catch {
+      malformed = true;
+    }
+  }
+  return {
+    source: malformed
+      ? { status: 'not-measured', reason: 'guard-audit-malformed' }
+      : !verifyEventChainText(text).ok
+        ? { status: 'not-measured', reason: 'guard-audit-chain-corrupt' }
+        : { status: 'measured', rows },
+    rows,
+    text,
+  };
+}
+
 function deadwoodAllowlistText(): string {
   const require = createRequire(import.meta.url);
   const corePackage = require.resolve('@dzhechkov/harness-core/package.json');
@@ -13143,7 +14154,7 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
   const json = flags.has('json');
   if (flags.has('help')) {
     write('dz compounding [--project <dir>] [--json] — honest learning-loop payoff report');
-    write('  pool payoff (write-only ratio) · guard repeat-violation trajectory · cold-vs-warm replay readiness · instrumentation health');
+    write('  pool payoff · guard trajectory · replay readiness · instrumentation · monthly eligible→attempted→accepted→executions funnel');
     return 0;
   }
   for (const flag of flags) {
@@ -13175,40 +14186,24 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
   // apply-leg usage events (read records only; aggregate rows carry no query by construction)
   const usage = readRecallUsageEvents(root);
 
-  // guard audit events
-  const guard: { ts: string; verdict: string; rules: string[] }[] = [];
-  try {
-    const text = readFileSync(join(root, '.dz', 'guard-audit.jsonl'), 'utf-8');
-    for (const line of text.split('\n')) {
-      if (line.trim() === '') continue;
-      try {
-        const o = JSON.parse(line) as { ts?: unknown; verdict?: unknown; violations?: { rule?: unknown }[] };
-        if (typeof o.ts === 'string' && typeof o.verdict === 'string') {
-          guard.push({
-            ts: o.ts,
-            verdict: o.verdict,
-            rules: Array.isArray(o.violations) ? o.violations.map((v) => (typeof v?.rule === 'string' ? v.rule : '')).filter(Boolean) : [],
-          });
-        }
-      } catch {
-        /* skip */
-      }
-    }
-  } catch {
-    /* no audit yet */
-  }
+  const promotionEvidence = readPromotionRunEvidence(root);
+  const guardEvidence = readGuardAuditEvidence(root);
+  const guard = [...guardEvidence.rows];
 
   // The evidence logs themselves, verbatim: the report verifies their hash chains (feature
   // event-chain). Handing over the TEXT rather than a pre-computed verdict keeps one definition of
   // "the chain is intact" — a second copy here is how a gate and its report start disagreeing.
   const evidenceLogs: { log: string; text: string }[] = [];
-  for (const rel of ['.dz/recall-usage.jsonl', '.dz/guard-audit.jsonl']) {
+  for (const rel of ['.dz/recall-usage.jsonl']) {
     try {
       evidenceLogs.push({ log: rel, text: readFileSync(join(root, ...rel.split('/')), 'utf-8') });
     } catch {
       /* absent log — reported by its own gate above, not invented here */
     }
   }
+  if (guardEvidence.text !== null) {
+    evidenceLogs.push({ log: '.dz/guard-audit.jsonl', text: guardEvidence.text });
+  }
 
   const now = new Date();
   const report = assembleCompoundingReport({
@@ -13218,6 +14213,13 @@ function cmdCompounding(options: Map<string, string>, flags: Set<string>, cwd: s
     nowTs: now.toISOString(),
     evidenceLogs,
     cmdUsageDepthDays: cmdUsageDepthDays(root, now),
+    lessonToRule: {
+      promotionRuns: promotionEvidence.source,
+      guardAudits: guardEvidence.source,
+      promotionAcceptances: promotionEvidence.acceptances,
+      truncatedPromotionPeriods: promotionEvidence.truncatedPeriods,
+      acceptanceHistoryComplete: promotionEvidence.acceptanceHistoryComplete,
+    },
   });
   // lesson-bandit-rerank §11: the payoff axis joins THIS report rather than growing a private
   // dashboard — the `rewardEvents : exposureEvents` row asks exactly the question this command
@@ -15110,11 +16112,20 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
       case 'bundle':
         return cmdBundle(options, flags, cwd, write);
       case 'teach':
-        return await cmdTeach(options, flags, cwd, write);
+        return await cmdTeach(
+          options,
+          flags,
+          cwd,
+          write,
+          writeErr,
+          io.interactive ?? process.stdout.isTTY === true,
+          io.teachGuardRunner ?? teachGuard,
+          io.teachReinforceRunner ?? runTeachGuardReinforcement,
+        );
       case 'consolidate':
         return await cmdConsolidate(options, flags, cwd, write);
       case 'recall':
-        return await cmdRecall(options, flags, cwd, write);
+        return await cmdRecall(options, flags, cwd, write, writeErr, io.classMatcher);
       case 'vector':
         return await cmdVector(options, flags, cwd, write);
       case 'brain':
@@ -15167,6 +16178,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdDriftCheck(options, flags, cwd, write);
       case 'hooks-sync':
         return cmdHooksSync(options, flags, cwd, write, writeErr);
+      case 'integrations-verify':
+        return cmdIntegrationsVerify(options, flags, cwd, write, writeErr);
       case 'agents-sync':
         return cmdAgentsSync(options, flags, cwd, write, writeErr);
       case 'sync-canonical':