@dzhechkov/harness-core 0.7.12 → 0.8.2

package/src/qe-rounds.ts

@@ -0,0 +1,226 @@
+/**
+ * qe-rounds — how many Step-8 review rounds has one feature already had?
+ *
+ * The stopping rule existed ONLY as a sentence in a prose module:
+ *
+ *     .claude/skills/feature-adr/modules/08-qe.md:246
+ *     "Max iterations: 3. After 3 iterations, flag remaining gaps for user decision."
+ *
+ * MEASURED 2026-08-27: no counter existed anywhere — `grep -rl 'ReviewScope|scopeId|findingId|
+ * lineage'` over harness-core/src and harness-cli/src returned nothing. So the rule sat at layer 4 of
+ * the cost-of-detection ladder, and every restart of the agent forgot the sentence. One real slug
+ * accumulated **38** graded rounds and 4 failed attempts against a documented ceiling of 3.
+ *
+ * This module READS what `dz qe-bridge` already writes. It records nothing of its own — deliberately:
+ * a counter that starts recording today could not answer for the 38 rounds already on disk, which are
+ * the only real evidence this feature has.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** One graded review round, as `dz qe-bridge` recorded it. */
+export interface QeRound {
+  runId: string;
+  emittedAt: string;
+  grade: string;
+  /** Findings by severity, lowercased. Absent severities are simply not present. */
+  severities: Record<string, number>;
+  /** The file this round was read from, so a caller can point at it. */
+  file: string;
+}
+
+/** An attempt that produced NO verdict. Never merged into the round count, never dropped. */
+export interface QeFailedAttempt {
+  runId: string;
+  emittedAt: string;
+  reason: string;
+  file: string;
+}
+
+export type QeRoundsStatus = 'under-ceiling' | 'at-or-over-ceiling' | 'not-established';
+
+export interface QeRoundsReport {
+  status: QeRoundsStatus;
+  /** Present only when status is 'not-established'. */
+  notEstablishedReason?: string | undefined;
+  /** The directory actually read. One directory — never a union. */
+  dir: string;
+  ceiling: number;
+  /** Distinct runIds among graded sign-offs. THIS is the number the ceiling applies to. */
+  rounds: number;
+  /** Graded rounds in emission order. */
+  roundList: QeRound[];
+  /** Attempts that produced no verdict. Reported separately, on purpose. */
+  failedAttempts: QeFailedAttempt[];
+  /** Files that would not parse or carried no runId. Named, never silently skipped. */
+  unreadable: { file: string; why: string }[];
+  /** Grades in emission order, e.g. ['C','C','B'] — a shape a reader can judge at a glance. */
+  grades: string[];
+  firstAt?: string | undefined;
+  lastAt?: string | undefined;
+}
+
+export const QE_ROUNDS_DEFAULT_CEILING = 3;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Severity tallies from a sign-off's findings. Unknown shapes contribute nothing rather than throwing. */
+function severitiesOf(findings: unknown): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!Array.isArray(findings)) return out;
+  for (const f of findings) {
+    if (!isRecord(f)) continue;
+    const s = typeof f.severity === 'string' ? f.severity.toLowerCase() : '';
+    if (!s) continue;
+    out[s] = (out[s] ?? 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Read ONE feature directory's review rounds.
+ *
+ * `featureDir` is a directory, never a slug — and that is load-bearing. MEASURED 2026-08-27: the slug
+ * `package-story-page-hardening` exists in two separate checkouts holding 38 and 7 records. A function
+ * that resolved a slug by searching would have summed them to 45 for a run that had 38, and the
+ * output would look identical to a correct one. Resolving a slug to a directory is the caller's job.
+ */
+export function readQeRounds(featureDir: string, opts?: { ceiling?: number }): QeRoundsReport {
+  // A non-finite ceiling is the quietest fail-open there is: `Math.max(1, Math.floor(NaN))` is NaN,
+  // and `rounds >= NaN` is FALSE for every count, so the loop never stops. The CLI validates its own
+  // input, but this is a public export and a direct caller bypasses that guard. MEASURED: 2 >= NaN
+  // is false. Every numeric clamp needs Number.isFinite — a lesson this repo has already paid for.
+  const rawCeiling = opts?.ceiling ?? QE_ROUNDS_DEFAULT_CEILING;
+  const ceiling = Number.isFinite(rawCeiling)
+    ? Math.max(1, Math.floor(rawCeiling as number))
+    : QE_ROUNDS_DEFAULT_CEILING;
+  const dir = join(featureDir, '.fa-state', 'qe-bridge');
+
+  const base: QeRoundsReport = {
+    status: 'not-established', dir, ceiling, rounds: 0,
+    roundList: [], failedAttempts: [], unreadable: [], grades: [],
+  };
+
+  // "No bridge has ever run here" and "zero rounds so far" are DIFFERENT facts. Reporting the first
+  // as the second would tell a caller to keep going on the basis of a measurement never taken.
+  let entries: string[];
+  try {
+    if (!statSync(dir).isDirectory()) {
+      return { ...base, notEstablishedReason: `${dir} exists but is not a directory` };
+    }
+    entries = readdirSync(dir);
+  } catch {
+    return {
+      ...base,
+      notEstablishedReason:
+        `no ${dir} — this feature has no qe-bridge history, which is not the same as zero rounds`,
+    };
+  }
+
+  const byRunId = new Map<string, QeRound>();
+  const failed: QeFailedAttempt[] = [];
+  const unreadable: { file: string; why: string }[] = [];
+
+  for (const name of entries.slice().sort()) {
+    const isSignoff = name.startsWith('signoff-') && name.endsWith('.json');
+    const isFailed = name.startsWith('failed-') && name.endsWith('.json');
+    if (!isSignoff && !isFailed) continue;
+
+    const file = join(dir, name);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    } catch (e) {
+      // NAMED, not skipped. A silently dropped record makes the count quietly too low — in a counter
+      // whose whole job is to stop a loop, that fails OPEN.
+      unreadable.push({ file: name, why: `unparseable JSON: ${(e as Error).message}` });
+      continue;
+    }
+    if (!isRecord(parsed)) { unreadable.push({ file: name, why: 'not a JSON object' }); continue; }
+
+    const runId = typeof parsed.runId === 'string' ? parsed.runId : '';
+    const emittedAt = typeof parsed.emittedAt === 'string' ? parsed.emittedAt : '';
+
+    // A ROUND needs a runId, because that is what deduplicates it. An ATTEMPT does not: it produced
+    // no verdict, so there is nothing to deduplicate against, and dropping it would hide a run
+    // burning attempts. FOUND BY DOGFOODING 2026-08-27 — the first live run of this command against
+    // this repo's own `wave1-scorer-negation` reported 4 unreadable records, and all four were
+    // `failed-*.json` written before `runId` was added to that record shape. Calling them unreadable
+    // was wrong twice: it lost real attempts, and it declared the round count a lower bound when the
+    // rounds themselves were complete.
+    if (isFailed) {
+      failed.push({
+        runId: runId || `(no runId: ${name})`,
+        emittedAt,
+        reason: typeof parsed.reason === 'string' ? parsed.reason : 'unstated',
+        file: name,
+      });
+      continue;
+    }
+
+    if (!runId) { unreadable.push({ file: name, why: 'no runId — a round cannot be deduplicated without one' }); continue; }
+
+    // A round is a runId. Two records sharing one are ONE round — first wins, and the collision is
+    // not an error: a re-emitted sign-off for the same run is still that run.
+    if (byRunId.has(runId)) continue;
+    byRunId.set(runId, {
+      runId, emittedAt,
+      grade: typeof parsed.grade === 'string' ? parsed.grade : '',
+      severities: severitiesOf(parsed.findings),
+      file: name,
+    });
+  }
+
+  const roundList = [...byRunId.values()].sort((a, b) => a.emittedAt.localeCompare(b.emittedAt));
+  failed.sort((a, b) => a.emittedAt.localeCompare(b.emittedAt));
+
+  if (roundList.length === 0 && failed.length === 0) {
+    return {
+      ...base, unreadable,
+      notEstablishedReason: unreadable.length
+        ? `${dir} holds ${unreadable.length} record(s), none of them readable`
+        : `${dir} holds no signoff or failed records`,
+    };
+  }
+
+  const stamps = [...roundList.map((r) => r.emittedAt), ...failed.map((f) => f.emittedAt)]
+    .filter((t) => t !== '').sort();
+  const bounds = { first: stamps[0], last: stamps[stamps.length - 1] };
+
+  const rounds = roundList.length;
+
+  // FAIL CLOSED. Until cross-family review caught it, an unreadable record only downgraded the
+  // count to a "lower bound" in the printed text while the STATUS still came out `under-ceiling` —
+  // so the command answered "another round is within budget" when the true count might already be
+  // at the ceiling. That is the exact fail-open this whole module was written against, sitting in
+  // the module itself. If ANY candidate record could not be counted, the honest verdict is that the
+  // number is not established — not a smaller number presented as if it were the answer.
+  if (unreadable.length > 0 && rounds < ceiling) {
+    return {
+      status: 'not-established',
+      notEstablishedReason:
+        `${rounds} readable round(s) plus ${unreadable.length} record(s) that could not be counted — `
+        + `the true count may already be at the ceiling of ${ceiling}, so this cannot say another `
+        + `round is within budget`,
+      dir, ceiling, rounds, roundList, failedAttempts: failed, unreadable,
+      grades: roundList.map((r) => r.grade),
+      firstAt: bounds.first, lastAt: bounds.last,
+    };
+  }
+
+  return {
+    status: rounds >= ceiling ? 'at-or-over-ceiling' : 'under-ceiling',
+    dir, ceiling, rounds, roundList, failedAttempts: failed, unreadable,
+    grades: roundList.map((r) => r.grade),
+    firstAt: bounds.first,
+    lastAt: bounds.last,
+  };
+}
+
+/** The number alone, for a caller that only needs to compare it. `-1` means NOT ESTABLISHED. */
+export function countQeRounds(featureDir: string, opts?: { ceiling?: number }): number {
+  const r = readQeRounds(featureDir, opts);
+  return r.status === 'not-established' ? -1 : r.rounds;
+}

package/src/registry.ts

@@ -270,7 +270,11 @@ function categoryFromPack(pack: string): string {
     pack.includes('presentation') ||
     // decision-mockups: an owner-facing decision page is stakeholder communication, the same
     // cluster as PRDs and presentations — not design, and not a QE artifact.
-    pack.includes('decision-mockups')
+    pack.includes('decision-mockups') ||
+    // package-story-page: a story page that explains one package to non-specialists is stakeholder
+    // communication by the same rationale as decision-mockups — and its own README separates it
+    // from the tutorial-course sibling, so it is not 'learning'.
+    pack.includes('story')
   )
     return 'product';
   // Digitized-book knowledge packs (ADR-001 book-knowledge-digitizer) — `skills-book-*` and named

package/src/run-records.ts

@@ -13,6 +13,8 @@
  * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
  */
 
+import { redactTrainingPayload } from './feature-adr-checkpoints.js';
+
 export type RecordKind = 'ledger' | 'training-pair';
 
 export type RecordVerdict =
@@ -127,7 +129,13 @@ export function decideRecordWrite(input: {
   if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
     return refuse('the payload must be a JSON object');
   }
-  const obj = payload as Record<string, unknown>;
+  // Operator-profile redaction AT THE PERSIST SEAM (ADR-001 Decision 5 / CF-6 of operator-profile).
+  // Every witnessed training-pair write funnels through this decision, so redacting HERE covers the
+  // workflow's inline pair builder and any future caller — the core buildTrainingPair redaction
+  // alone guarded a path that does not run (Codex cross-family finding, 2026-08-28). Redaction runs
+  // BEFORE the shape check, the line cap and the serialisation, so nothing downstream — the file,
+  // the read-back, the refusal texts — ever sees a byte of the profile block.
+  const obj = (kind === 'training-pair' ? redactTrainingPayload(payload) : payload) as Record<string, unknown>;
 
   const mismatch = shapeMismatch(kind, obj);
   if (mismatch !== null) return refuse(mismatch);

package/src/setup.ts

@@ -6,7 +6,8 @@
  * 1. Skills installation (via init)
  * 2. Claude Code session hooks (start/end) — with `--memory agentdb`, a real vector-store
  *    write via `.dz/agentdb-writer.mjs`; otherwise a `.dz/sessions.jsonl` marker
- * 3. Memory store: `.dz/agentdb.db` (agentdb, shared with the MCP server via AGENTDB_PATH)
+ * 3. Memory store: `.dz/agentdb.db` (agentdb — the session-hook writer's OWN file; the agentdb
+ *    MCP server gets a SEPARATE `.dz/agentdb-mcp.db` via AGENTDB_PATH, never this one)
  *    or `.dz/sessions.jsonl` + `.dz/patterns.jsonl` (jsonl default)
  * 4. Pretrain (project analysis → auto-recommend)
  *
@@ -53,11 +54,54 @@ export interface SetupStep {
   readonly detail: string;
 }
 
-/** Absolute path to the agentdb store shared by the hook writer and the MCP server. */
-function agentdbStorePath(projectRoot: string): string {
+/**
+ * Absolute path to the store the generated session-hook writer opens NATIVELY (better-sqlite3).
+ * It is the writer's own file: the agentdb MCP server must never be pointed at it — see
+ * {@link agentdbMcpStorePath}.
+ */
+export function agentdbStorePath(projectRoot: string): string {
   return join(projectRoot, '.dz', 'agentdb.db');
 }
 
+/**
+ * Absolute path to the agentdb MCP server's OWN store — never the hook writer's
+ * (ADR-001 `agentdb-setup-shared-store-fix`, 2026-08-26).
+ *
+ * WHY two files: a single SQLite file opened by two different engines is a measured data-loss
+ * path. `agentdb` falls back to sql.js when better-sqlite3 has no usable binary (no prebuild for
+ * Node 24+/ABI 137, no binary in the npm tarball) — and sql.js persists by rewriting the WHOLE
+ * file from its in-memory image, discarding whatever the native writer committed meanwhile.
+ * MEASURED in this repo 2026-07-09 (commits 1d47a916 / 9ede3fb5): of 20 samples, 5 were zero
+ * bytes and 4 were torn. The cure is separation, not a lock: a lock cannot bind a third-party
+ * `npx` process, and sql.js ignores SQLite locking outright.
+ */
+export function agentdbMcpStorePath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'agentdb-mcp.db');
+}
+
+/**
+ * The ONE separation predicate — used by both printers (`runSetup`'s `agentdb wiring` step and
+ * `runDoctor`'s `agentdb store separation` check), so a surface can never drift into its own
+ * copied comparison.
+ *
+ * @param projectRoot the project whose `.mcp.json` was read
+ * @param pinned the observed `mcpServers.agentdb.env.AGENTDB_PATH` (`undefined` when absent)
+ * @returns `null` when the registration is correctly separated, else the WHY message
+ */
+export function agentdbStoreSeparationProblem(projectRoot: string, pinned: string | undefined): string | null {
+  if (pinned === agentdbStorePath(projectRoot)) {
+    return 'SHARED STORE — .mcp.json pins the agentdb MCP server at the same file the session-hook '
+      + 'writer opens (.dz/agentdb.db). Two engines on one SQLite file: an agentdb server that '
+      + 'falls back to sql.js rewrites the WHOLE file and discards the writer\'s pages. Measured '
+      + '2026-07-09: 5 of 20 samples zero bytes, 4 torn. Re-run `dz setup --memory agentdb` to '
+      + 'repoint the server at .dz/agentdb-mcp.db.';
+  }
+  if (pinned !== agentdbMcpStorePath(projectRoot)) {
+    return '.mcp.json agentdb missing or not pinned to the MCP store (.dz/agentdb-mcp.db)';
+  }
+  return null;
+}
+
 /**
  * Absolute path to the throttle marker holding the epoch-ms timestamp of the last consolidate the
  * writer spawned. Read before every SessionEnd/PreCompact consolidate: within THROTTLE_MS the spawn
@@ -73,14 +117,15 @@ function consolidateMarkerPath(projectRoot: string): string {
  * `dz-writer-version` stamp is older, WITHOUT requiring `--force` (audit gap G4: generated code
  * must not fossilize outside the package lifecycle).
  */
-export const AGENTDB_WRITER_VERSION = 4;
+export const AGENTDB_WRITER_VERSION = 5;
 
 /**
  * Generate the `.dz/agentdb-writer.mjs` helper invoked by the session hooks.
  *
  * v2 (ADR-002, audit gaps G3 + code#1 + code#4): session markers are **metadata-only telemetry** —
- * a plain row in the `dz_session_events` table inside the SAME shared `.dz/agentdb.db` the MCP
- * server is pinned to (`AGENTDB_PATH`). No embedding, no model load, no `successRate`:
+ * a plain row in the `dz_session_events` table inside the writer's OWN `.dz/agentdb.db` (v5: the
+ * MCP server is pinned to a SEPARATE `.dz/agentdb-mcp.db`). No embedding, no model load, no
+ * `successRate`:
  * - ~ms latency (v1 loaded a ~90 MB transformers model → 12 s cold-timeout losing the marker);
  * - zero pollution of the HNSW index real learnings live in (those enter via `agentdb_*` MCP tools);
  * - uses better-sqlite3 DIRECTLY (WAL + busy_timeout) — if it is unavailable the writer falls back
@@ -98,9 +143,11 @@ export function generateAgentdbWriter(projectRoot: string): string {
 // dz-writer-version: ${AGENTDB_WRITER_VERSION}
 // Auto-generated by \`dz setup --memory agentdb\`. Do not edit — re-run \`dz setup\` to upgrade
 // (setup regenerates automatically when this version stamp is outdated; --force not required).
-// Writes a metadata-only session-event row into the shared AgentDB store (.dz/agentdb.db — the
-// same file the agentdb MCP server is pinned to via AGENTDB_PATH). Real learnings go into the
-// vector index via the agentdb_* MCP tools; this is deliberately non-semantic telemetry.
+// Writes a metadata-only session-event row into the writer's OWN AgentDB store (.dz/agentdb.db).
+// This file is NEVER shared with the agentdb MCP server — that server has its own
+// .dz/agentdb-mcp.db, because two engines on one SQLite file is a measured corruption path
+// (2026-07-09: 5 of 20 samples zero bytes, 4 torn). Real learnings go into the vector index via
+// the agentdb_* MCP tools; this is deliberately non-semantic telemetry.
 // On SessionEnd AND PreCompact it ALSO fires a detached \`dz consolidate\` (Option C, ADR-003):
 // harvest this session's learnings into the lexical store and mirror them — with real embeddings —
 // into the shared AgentDB vector index. PreCompact is the RELIABLE periodic trigger: it fires on
@@ -117,7 +164,13 @@ import { spawn } from 'node:child_process';
 const arg = process.argv[2];
 const event = arg === 'end' ? 'end' : arg === 'precompact' ? 'precompact' : 'start';
 const ts = new Date().toISOString();
-const DB = process.env.AGENTDB_PATH || ${JSON.stringify(dbPath)};
+// PINNED, deliberately NOT read from the ambient environment. Honouring an ambient store path re-opened the
+// exact hole this feature closes: export AGENTDB_PATH=.dz/agentdb-mcp.db and the writer and the MCP
+// server share ONE file again — two engines, one database — while the separation invariant still
+// reports PASS, because it inspects the registration and not the writer's runtime resolution.
+// Found by cross-family QE (Codex gpt-5.6-sol) against the first version of this fix. A store that
+// needs to move is a REGENERATION (\`dz setup --memory agentdb\`), never an env override.
+const DB = ${JSON.stringify(dbPath)};
 const SESSIONS = ${JSON.stringify(sessionsPath)};
 const ROOT = ${JSON.stringify(projectRoot)};
 const CONSOLIDATE_MARKER = ${JSON.stringify(markerPath)};
@@ -134,7 +187,7 @@ function fallback(err) {
 
 try {
   // Native better-sqlite3 ONLY (prebuilt; synchronous; WAL). Never the sql.js fallback — its
-  // whole-file-in-memory persistence is unsafe against a concurrently-writing MCP server.
+  // whole-file-in-memory persistence is the mechanism that corrupted a shared store.
   // Records start/end AND the lightweight precompact row via the SAME insert path.
   const { default: Database } = await import('better-sqlite3');
   const db = new Database(DB);
@@ -263,16 +316,18 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
     },
     memory: {
       backend,
-      // agentdb: the native SQLite vector store shared by the session-hook writer and the
-      // agentdb MCP server (both pinned via AGENTDB_PATH). Real ReasoningBank patterns land here.
+      // agentdb: the native SQLite vector store the session-hook writer opens. The agentdb MCP
+      // server is pinned (via AGENTDB_PATH) to a SEPARATE file — see `mcpStorePath` below.
       path: backend === 'agentdb' ? '.dz/agentdb.db' : '.dz/sessions.jsonl',
       maxSizeMb: backend === 'agentdb' ? 100 : 10,
       agentdb: backend === 'agentdb' ? {
         learning: true,
         vectorDim: 384,
         mcpServer: 'agentdb',
-        // Both the hook writer and the MCP server read/write THIS path (env AGENTDB_PATH).
+        // The hook writer's own file. The MCP server gets `mcpStorePath` (env AGENTDB_PATH) —
+        // the two are deliberately different files (ADR-001, 2026-08-26).
         storePath: '.dz/agentdb.db',
+        mcpStorePath: '.dz/agentdb-mcp.db',
         embeddingModel: 'Xenova/paraphrase-multilingual-MiniLM-L12-v2',
         sessionHookWrites: true,
       } : undefined,
@@ -615,9 +670,10 @@ export function runSetup(opts: SetupOptions): SetupResult {
       // Pin to the INSTALLED agentdb version (not @latest) so the MCP server and the hook
       // writer run the same alpha schema against one DB.
       args: [installedAgentdbSpec(opts.projectRoot), 'mcp', 'start'],
-      // Pin the store to the SAME native DB the session-hook writer targets, so hook telemetry
-      // and agentdb_* pattern/reflexion data live in one shared store.
-      env: { AGENTDB_PATH: agentdbStorePath(opts.projectRoot) },
+      // Pin the server to its OWN store — NEVER the writer's .dz/agentdb.db. Two engines on one
+      // SQLite file (native better-sqlite3 + a silent sql.js fallback) whole-file-rewrite each
+      // other: measured 2026-07-09, 5 of 20 samples zero bytes and 4 torn (ADR-001, 2026-08-26).
+      env: { AGENTDB_PATH: agentdbMcpStorePath(opts.projectRoot) },
     };
     const mcpConfigPath = join(opts.projectRoot, '.mcp.json');
     try {
@@ -630,7 +686,13 @@ export function runSetup(opts: SetupOptions): SetupResult {
       mcpConfig.mcpServers = servers;
       if (before !== JSON.stringify(agentdbEntry)) {
         writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-        steps.push({ name: 'Register agentdb MCP', status: 'done', detail: '.mcp.json: 41 tools, store pinned to .dz/agentdb.db' });
+        steps.push({
+          name: 'Register agentdb MCP',
+          status: 'done',
+          // No tool count: a hardcoded number is a lie waiting to age (the live server answered
+          // 35 while its own banner said 32 and the README said 41 — measured 2026-08-26).
+          detail: `.mcp.json: ${installedAgentdbSpec(opts.projectRoot)} → .dz/agentdb-mcp.db (own store; hooks keep .dz/agentdb.db)`,
+        });
       } else {
         steps.push({ name: 'Register agentdb MCP', status: 'skipped', detail: 'already registered and current' });
       }
@@ -676,14 +738,14 @@ export function runSetup(opts: SetupOptions): SetupResult {
       const mcp = JSON.parse(readFileSync(join(opts.projectRoot, '.mcp.json'), 'utf-8')) as {
         mcpServers?: Record<string, { env?: Record<string, string> }>;
       };
-      if (mcp.mcpServers?.['agentdb']?.env?.['AGENTDB_PATH'] !== agentdbStorePath(opts.projectRoot)) {
-        problems.push('.mcp.json agentdb missing or not pinned to .dz/agentdb.db');
-      }
+      // Separation is the REQUIRED state; a shared store is the error (inverted 2026-08-26).
+      const sep = agentdbStoreSeparationProblem(opts.projectRoot, mcp.mcpServers?.['agentdb']?.env?.['AGENTDB_PATH']);
+      if (sep) problems.push(sep);
     } catch {
       problems.push('.mcp.json unreadable');
     }
     steps.push(problems.length === 0
-      ? { name: 'agentdb wiring', status: 'done', detail: 'hooks → writer → .dz/agentdb.db ← MCP (one shared store)' }
+      ? { name: 'agentdb wiring', status: 'done', detail: 'hooks → writer → .dz/agentdb.db   ·   MCP → .dz/agentdb-mcp.db (separate stores, by design)' }
       : { name: 'agentdb wiring', status: 'error', detail: `INCOMPLETE: ${problems.join('; ')}` });
   }
 
@@ -692,7 +754,9 @@ export function runSetup(opts: SetupOptions): SetupResult {
   // on the documented jsonl→agentdb `--force` switch, leaking the binary store into git.
   const gitignorePath = join(opts.projectRoot, '.gitignore');
   const dzIgnoreLines = backend === 'agentdb'
-    ? ['.dz/agentdb.db', '.dz/agentdb.db-wal', '.dz/agentdb.db-shm', '.dz/sessions.jsonl']
+    ? ['.dz/agentdb.db', '.dz/agentdb.db-wal', '.dz/agentdb.db-shm',
+       '.dz/agentdb-mcp.db', '.dz/agentdb-mcp.db-wal', '.dz/agentdb-mcp.db-shm',
+       '.dz/sessions.jsonl']
     : ['.dz/sessions.jsonl', '.dz/patterns.jsonl'];
   const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
   const missing = dzIgnoreLines.filter((line) => !existing.split(/\r?\n/).includes(line));