@dzhechkov/harness-core 0.3.138 → 0.3.141

package/src/backlog.ts

@@ -0,0 +1,978 @@
+/**
+ * `dz backlog` — the Smart Backlog: a personal, goal-directed idea pipeline (feature smart-backlog).
+ *
+ * Capture an idea → semantic dedup against existing ideas via the EXISTING Brain vector engine
+ * (agentdb + the shared embedder — ADR-001; NO second store) → score alignment against a GoalMap
+ * (ADR-003) → weighted-roulette pick (ADR-004) → stage an idea2prd enrich hand-off → draft a Jira
+ * issue through a configurable, stub-first adapter seam (ADR-006).
+ *
+ * ARCHITECTURE (05): every load-bearing decision is a PURE function tested on a layer-1 deterministic
+ * test; the CLI handler (`cmdBacklog`) is a thin arg-parse + call. Semantic work (embedding, cosine,
+ * vector search) is an OUTBOUND PORT to harness-core's Brain engine — this file defines NO embedder,
+ * NO cosine, and imports NO MCP client (ADR-001 / ADR-006, both grep-guarded).
+ *
+ * Ideas carry `task_type:'dz-backlog'` in the shared `.dz/agentdb.db`, so they never surface in
+ * `dz recall`'s lesson namespace (ADR-005 T-005b, the discriminating isolation test). Structured
+ * records live in a dedicated `.dz/backlog/ideas.jsonl`, never in `.dz/memory/patterns.*`.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// ── Outbound ports to the Brain engine (ADR-001): reuse VERBATIM, define none locally. ──
+// Backlog vectors are written DIRECTLY to the agentdb `dz-backlog` namespace via
+// `importVectorsToAgentdb` (NOT the configurable `mirrorEntriesToVector` engine), so write and read
+// ALWAYS hit the SAME store regardless of `memory.vector.engine` (ADR-001/005 — the single-store
+// property; routing through the generic engine let `engine:'rvf'` split writes from reads).
+import { cosineSimilarity, deleteAgentdbByDzIds, importVectorsToAgentdb, resolveAgentdbEmbedder, searchAgentdbPatterns } from './agentdb-index.js';
+import { resolveEmbedModel } from './embedding-config.js';
+// Seeded PRNG — reuse the ONE mulberry32 already in the repo (no second RNG; ADR-004 determinism).
+import { mulberry32 } from './compounding.js';
+
+/** The vector-store namespace that isolates ideas from lessons (ADR-001/005). */
+export const BACKLOG_TASK_TYPE = 'dz-backlog';
+
+/* ================================================================== */
+/*  DOMAIN TYPES (04 Domain Model)                                      */
+/* ================================================================== */
+
+export type IdeaStatus = 'new' | 'enriched' | 'in-progress' | 'shipped' | 'dropped';
+
+/** The aggregate root — one captured idea. `id` is content-addressed (no `Date.now()` in identity). */
+export interface IdeaRecord {
+  readonly id: string;
+  readonly text: string;
+  status: IdeaStatus;
+  readonly createdTs: string;
+  effort: number; // 1..5, user estimate; default 3
+  goalId: string | null; // argmax goal (ADR-003)
+  goalAlignment: number; // [0,1] weighted-max cosine
+  relatedIds: string[]; // top-K RELATED ideas (ADR-002)
+  uses: number; // reinforcement count — a DUPLICATE bumps the existing root's uses (ADR-002 T-002b)
+  proposal?: string; // agent-authored (FR-3.2); the CLI NEVER fabricates this
+  enrichedPath?: string; // features/<slug>/ once enriched (FR-5)
+  jiraKey?: string; // IssueRef.key or the outbox ref (ADR-006)
+  tags: string[];
+}
+
+/** The compass (ADR-003) — user-owned, edited as a file. */
+export interface Goal {
+  readonly id: string;
+  readonly statement: string;
+  readonly weight: number; // (0,1]
+  readonly keywords: readonly string[];
+}
+export interface GoalMap {
+  readonly version: number;
+  readonly goals: readonly Goal[];
+}
+
+export type DedupAction = 'duplicate' | 'related' | 'new';
+
+/** Pure output of the classifier (04) — consumed by capture. */
+export interface DedupVerdict {
+  readonly action: DedupAction;
+  /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
+  readonly cosine: number;
+  readonly matchedId: string | undefined;
+  readonly relatedIds: readonly string[];
+  /** True when the embedder was unavailable and dedup degraded to exact-text (ADR-002 §degrade). */
+  readonly exactTextOnly: boolean;
+}
+
+/* ================================================================== */
+/*  CONFIG (readBacklogConfig) — defensive, Number.isFinite clamps.     */
+/* ================================================================== */
+
+export const DEFAULT_DUPLICATE_THRESHOLD = 0.92; // measured house constant (02 §R-D)
+export const DEFAULT_RELATEDNESS_FLOOR = 0.35; // GROUND_VECTOR_SIMILARITY_FLOOR (02 §R-D)
+export const DEFAULT_ROULETTE_ALPHA = 1.5;
+export const DEFAULT_HALF_LIFE_DAYS = 30;
+export const DEFAULT_RECENCY_FLOOR = 0.3;
+export const DEFAULT_EFFORT = 3;
+
+export interface BacklogConfig {
+  readonly dedup: { readonly duplicateThreshold: number; readonly relatednessFloor: number };
+  readonly roulette: {
+    readonly alpha: number;
+    readonly halfLifeDays: number;
+    readonly recencyFloor: number;
+    readonly defaultEffort: number;
+  };
+  readonly jira: { readonly adapter: BacklogBackend };
+}
+
+/** Finite-and-in-range or the fallback (the recurring Infinity-clamp lesson). */
+function clampNum(v: unknown, lo: number, hi: number, fallback: number, opts: { intOnly?: boolean } = {}): number {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < lo || v > hi) return fallback;
+  return opts.intOnly ? Math.floor(v) : v;
+}
+
+export function readBacklogConfig(projectRoot: string): BacklogConfig {
+  const fallback: BacklogConfig = {
+    dedup: { duplicateThreshold: DEFAULT_DUPLICATE_THRESHOLD, relatednessFloor: DEFAULT_RELATEDNESS_FLOOR },
+    roulette: {
+      alpha: DEFAULT_ROULETTE_ALPHA,
+      halfLifeDays: DEFAULT_HALF_LIFE_DAYS,
+      recencyFloor: DEFAULT_RECENCY_FLOOR,
+      defaultEffort: DEFAULT_EFFORT,
+    },
+    jira: { adapter: 'none' },
+  };
+  const configPath = join(projectRoot, '.dz', 'config.json');
+  if (!existsSync(configPath)) return fallback;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf-8')) as {
+      backlog?: {
+        dedup?: { duplicateThreshold?: unknown; relatednessFloor?: unknown };
+        roulette?: { alpha?: unknown; halfLifeDays?: unknown; recencyFloor?: unknown; defaultEffort?: unknown };
+        jira?: { adapter?: unknown };
+      };
+    };
+    const b = parsed.backlog ?? {};
+    // `> 0 && <= 1` — a value of 2 or NaN falls back to 0.92 (ADR-002 T-002d).
+    const dup = clampNum(b.dedup?.duplicateThreshold, Number.MIN_VALUE, 1, DEFAULT_DUPLICATE_THRESHOLD);
+    // The floor must sit in [0, dup]. MED-7: re-range-check the ADJUSTED value (clamp the RESULT, not
+    // just the input) — a tiny `dup` (e.g. 5e-324) previously drove `dup - EPSILON` NEGATIVE, so a
+    // cosine of -1e-16 fell into the RELATED band. Force the repaired floor back into [0, dup].
+    let floor = clampNum(b.dedup?.relatednessFloor, 0, 1, DEFAULT_RELATEDNESS_FLOOR);
+    if (floor >= dup) floor = DEFAULT_RELATEDNESS_FLOOR < dup ? DEFAULT_RELATEDNESS_FLOOR : dup;
+    floor = Math.min(Math.max(floor, 0), dup);
+    const adapter = isBacklogBackend(b.jira?.adapter) ? b.jira!.adapter : 'none'; // unknown ⇒ none (ADR-006 T-006d)
+    return {
+      dedup: { duplicateThreshold: dup, relatednessFloor: floor },
+      roulette: {
+        alpha: clampNum(b.roulette?.alpha, Number.MIN_VALUE, Number.MAX_VALUE, DEFAULT_ROULETTE_ALPHA),
+        halfLifeDays: clampNum(b.roulette?.halfLifeDays, Number.MIN_VALUE, Number.MAX_VALUE, DEFAULT_HALF_LIFE_DAYS),
+        recencyFloor: clampNum(b.roulette?.recencyFloor, Number.MIN_VALUE, 1, DEFAULT_RECENCY_FLOOR),
+        defaultEffort: clampNum(b.roulette?.defaultEffort, 1, 5, DEFAULT_EFFORT, { intOnly: true }),
+      },
+      jira: { adapter },
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+/* ================================================================== */
+/*  STORE (AM-1) — .dz/backlog/ideas.jsonl (append-only JSONL, ADR-005) */
+/* ================================================================== */
+
+export function backlogDir(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'backlog');
+}
+export function ideasPath(projectRoot: string): string {
+  return join(backlogDir(projectRoot), 'ideas.jsonl');
+}
+export function goalsPath(projectRoot: string): string {
+  return join(backlogDir(projectRoot), 'goals.json');
+}
+export function jiraOutboxDir(projectRoot: string): string {
+  return join(backlogDir(projectRoot), 'jira-outbox');
+}
+
+/** Content-addressed id — `sha1(text|createdTs).slice(0,16)`; NO `Date.now()` (mirrors patterns.ts). */
+export function ideaId(text: string, createdTs: string): string {
+  return createHash('sha1').update(`${text}|${createdTs}`).digest('hex').slice(0, 16);
+}
+
+/**
+ * Strict id whitelist (mirrors `dz score`'s slug guard) — the ONLY shape that may be interpolated into
+ * a filesystem path (jira-outbox/<id>.json, enrich slug fallback). Rejects `.`/`..`/`/`/`\` and any
+ * traversal, so an idea id like `../../../owned` from a hand-edited store can NEVER escape its dir
+ * (HIGH-1). A content-addressed `ideaId()` (16 hex) always passes; anything else is refused, not sanitised
+ * into a surprising path.
+ */
+export function isSafeId(id: unknown): id is string {
+  return typeof id === 'string' && id.length > 0 && id.length <= 64 && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) && !id.includes('..');
+}
+
+/** Strip an id to a filesystem-safe token (defence-in-depth for a slug fallback — never a path). */
+function safeIdToken(id: string): string {
+  const t = id.replace(/[^A-Za-z0-9]/g, '').slice(0, 12);
+  return t === '' ? 'idea' : t;
+}
+
+/** Normalise a partial/loaded object into a full IdeaRecord (defensive: bad fields ⇒ safe defaults). */
+function normaliseIdea(raw: Record<string, unknown>): IdeaRecord | undefined {
+  // HIGH-1: an id that is not filesystem-safe can NEVER enter the store — it would later interpolate
+  // into an outbox filename or an enrich slug and escape its directory. Drop the record entirely.
+  if (!isSafeId(raw.id) || typeof raw.text !== 'string') return undefined;
+  const status = ['new', 'enriched', 'in-progress', 'shipped', 'dropped'].includes(raw.status as string)
+    ? (raw.status as IdeaStatus)
+    : 'new';
+  // MED-6: a bad createdTs (`Date.parse` ⇒ NaN) would poison the roulette weight; coerce it to a
+  // valid, maximally-old ISO timestamp so recency degrades to the neutral floor, never NaN.
+  const createdRaw = typeof raw.createdTs === 'string' && Number.isFinite(Date.parse(raw.createdTs)) ? raw.createdTs : new Date(0).toISOString();
+  const rec: IdeaRecord = {
+    id: raw.id,
+    text: raw.text,
+    status,
+    createdTs: createdRaw,
+    effort: clampNum(raw.effort, 1, 5, DEFAULT_EFFORT, { intOnly: true }),
+    goalId: typeof raw.goalId === 'string' ? raw.goalId : null,
+    goalAlignment: clampNum(raw.goalAlignment, 0, 1, 0),
+    relatedIds: Array.isArray(raw.relatedIds) ? raw.relatedIds.filter((x): x is string => typeof x === 'string') : [],
+    uses: clampNum(raw.uses, 0, Number.MAX_VALUE, 0, { intOnly: true }),
+    tags: Array.isArray(raw.tags) ? raw.tags.filter((x): x is string => typeof x === 'string') : [],
+  };
+  if (typeof raw.proposal === 'string') rec.proposal = raw.proposal;
+  if (typeof raw.enrichedPath === 'string') rec.enrichedPath = raw.enrichedPath;
+  if (typeof raw.jiraKey === 'string') rec.jiraKey = raw.jiraKey;
+  return rec;
+}
+
+/** Read the append-only store. A corrupt line is SKIPPED (never fatal) — the whole store never throws. */
+export function readIdeas(projectRoot: string): IdeaRecord[] {
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) return [];
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const out: IdeaRecord[] = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      const rec = normaliseIdea(JSON.parse(trimmed) as Record<string, unknown>);
+      if (rec !== undefined) out.push(rec);
+    } catch {
+      /* skip corrupt line */
+    }
+  }
+  return out;
+}
+
+/** Atomic full rewrite (tmp + rename) so a crash mid-write never truncates the store. */
+export function writeIdeas(projectRoot: string, ideas: readonly IdeaRecord[]): void {
+  const path = ideasPath(projectRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const body = ideas.map((i) => JSON.stringify(i)).join('\n') + (ideas.length > 0 ? '\n' : '');
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, body);
+  renameSync(tmp, path);
+}
+
+/** Pre-mutation snapshot (NFR-6) — mirrors `snapshotStore`. A failed snapshot returns `{error}` so
+ *  the caller ABORTS the mutation (no partial merge). */
+export interface SnapshotResult {
+  readonly path: string;
+  readonly count: number;
+  readonly error?: string;
+}
+export function snapshotIdeas(projectRoot: string, dest: string): SnapshotResult {
+  try {
+    const ideas = readIdeas(projectRoot);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, ideas.map((i) => JSON.stringify(i)).join('\n') + (ideas.length > 0 ? '\n' : ''));
+    return { path: dest, count: ideas.length };
+  } catch (err) {
+    return { path: dest, count: 0, error: `snapshot failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/* ================================================================== */
+/*  DEDUP (AM-2 / ADR-002) — raw cosine bands, NOT RRF.                 */
+/* ================================================================== */
+
+/** One existing-idea comparison candidate: its id and the RAW cosine of the new idea against it. */
+export interface DedupCandidate {
+  readonly id: string;
+  readonly cosine: number;
+}
+
+/**
+ * THE LOAD-BEARING CLASSIFIER (ADR-002 T-002a) — PURE. Bands the top-1 raw cosine:
+ *   DUPLICATE  cosine ≥ duplicateThreshold        (default 0.92)
+ *   RELATED    relatednessFloor ≤ cosine < dup    (default [0.35, 0.92))  ⇒ create + attach relatedIds
+ *   NEW        cosine < relatednessFloor
+ * Flip either cut and exactly one boundary fixture crosses a band — the test REDS.
+ */
+export function classifyDedup(
+  candidates: readonly DedupCandidate[],
+  cfg: BacklogConfig['dedup'],
+  opts: { exactTextOnly?: boolean } = {},
+): DedupVerdict {
+  // HIGH-4: a non-finite cosine (NaN/±Infinity) sorts unpredictably and can shove a real 0.97 duplicate
+  // out of the top slot → misclassified NEW. Drop non-finite candidates BEFORE sorting/banding (the
+  // recurring repo `Number.isFinite` lesson).
+  const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
+  const top = sorted[0];
+  const exactTextOnly = opts.exactTextOnly === true;
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly };
+  if (top.cosine >= cfg.duplicateThreshold) {
+    return { action: 'duplicate', cosine: top.cosine, matchedId: top.id, relatedIds: [], exactTextOnly };
+  }
+  const related = sorted.filter((c) => c.cosine >= cfg.relatednessFloor && c.cosine < cfg.duplicateThreshold);
+  if (related.length > 0) {
+    return { action: 'related', cosine: top.cosine, matchedId: undefined, relatedIds: related.map((c) => c.id), exactTextOnly };
+  }
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, relatedIds: [], exactTextOnly };
+}
+
+/** Injectable deps so the production dedup path is testable without a live agentdb. */
+export interface DedupDeps {
+  /** Semantic search over the `dz-backlog` namespace — defaults to the real `searchAgentdbPatterns`. */
+  readonly search?: (
+    projectRoot: string,
+    query: string,
+  ) => Promise<{ hits: { dzId?: string | undefined; similarity: number }[]; error?: string | undefined }>;
+  /** Existing structured ideas (for the exact-text degrade path) — defaults to `readIdeas`. */
+  readonly ideas?: readonly IdeaRecord[];
+}
+
+/**
+ * Production dedup: embed+search the `dz-backlog` vectors (RAW COSINE via `searchAgentdbPatterns`,
+ * NEVER the RRF `recallHybrid().score` — ADR-002 T-002c), then band via {@link classifyDedup}. If the
+ * embedder/search is unavailable it DEGRADES to exact-text dedup (identical text ⇒ DUPLICATE), never
+ * blocking capture (NFR-2 / ADR-002 T-002e).
+ */
+export async function dedupIdea(projectRoot: string, text: string, cfg: BacklogConfig, deps: DedupDeps = {}): Promise<DedupVerdict> {
+  const ideas = deps.ideas ?? readIdeas(projectRoot);
+  const search =
+    deps.search ??
+    ((root: string, query: string) => searchAgentdbPatterns(root, query, { taskTypes: [BACKLOG_TASK_TYPE], limit: 20 }));
+  // Match the stored embed form `${taskType}: ${text}` (02 §R-B) so query and row vectors co-locate.
+  const result = await search(projectRoot, `${BACKLOG_TASK_TYPE}: ${text}`);
+  // MED-5: build the VALID candidate set FIRST (a hit must carry a dzId AND a finite cosine). Only
+  // then decide — a malformed hit (missing dzId / NaN cosine) must NOT bypass the exact-text net.
+  // HIGH-A: a hit whose dzId is NOT a member of the CURRENT ideas.jsonl is an ORPHAN vector (its
+  // structured record was removed, e.g. by `harmonize --apply`); matching it would report a DUPLICATE
+  // of a nonexistent idea (a dead match). Drop orphans before deciding — defense in depth alongside the
+  // prune-on-removal in `harmonizeBacklog`.
+  const liveIds = new Set(ideas.map((i) => i.id));
+  const candidates: DedupCandidate[] = [];
+  for (const h of result.hits) {
+    if (typeof h.dzId === 'string' && liveIds.has(h.dzId) && Number.isFinite(h.similarity)) candidates.push({ id: h.dzId, cosine: h.similarity });
+  }
+  if (result.error !== undefined || candidates.length === 0) {
+    // No usable semantic signal (embedder unavailable, nothing mirrored, or only malformed hits) ⇒
+    // EXACT-text safety net: identical text among existing ideas is still a DUPLICATE (content-addressed
+    // idempotency, ADR-002 §degrade). Otherwise NEW — the RELATED band needs cosine and is skipped.
+    const match = ideas.find((i) => i.text === text);
+    if (match !== undefined) return { action: 'duplicate', cosine: 1, matchedId: match.id, relatedIds: [], exactTextOnly: true };
+    return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly: result.error !== undefined };
+  }
+  return classifyDedup(candidates, cfg.dedup);
+}
+
+/* ================================================================== */
+/*  ALIGNMENT (AM-3 / ADR-003) — weighted-MAX cosine over the GoalMap.  */
+/* ================================================================== */
+
+/** Defensive GoalMap reader — never throws; a missing/corrupt file ⇒ empty compass. */
+export function readGoalMap(projectRoot: string): GoalMap {
+  const path = goalsPath(projectRoot);
+  if (!existsSync(path)) return { version: 1, goals: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown; goals?: unknown };
+    const goals: Goal[] = Array.isArray(parsed.goals)
+      ? parsed.goals
+          .map((g): Goal | undefined => {
+            const o = g as Record<string, unknown>;
+            if (typeof o.id !== 'string' || typeof o.statement !== 'string') return undefined;
+            return {
+              id: o.id,
+              statement: o.statement,
+              weight: clampNum(o.weight, Number.MIN_VALUE, 1, 1),
+              keywords: Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === 'string') : [],
+            };
+          })
+          .filter((g): g is Goal => g !== undefined)
+      : [];
+    return { version: typeof parsed.version === 'number' ? parsed.version : 1, goals };
+  } catch {
+    return { version: 1, goals: [] };
+  }
+}
+
+/** The text embedded for a goal: statement + keywords (same convention across cache + score). */
+export function goalEmbedText(goal: Goal): string {
+  return goal.keywords.length > 0 ? `${goal.statement} ${goal.keywords.join(' ')}` : goal.statement;
+}
+
+export interface AlignmentResult {
+  readonly goalId: string | null;
+  readonly goalAlignment: number;
+}
+
+/** One goal with its precomputed embedding + weight — the input to the pure scorer. */
+export interface GoalVector {
+  readonly id: string;
+  readonly vec: Float32Array;
+  readonly weight: number;
+}
+
+/**
+ * THE LOAD-BEARING ALIGNMENT SCORER (ADR-003 T-003a) — PURE. Alignment =
+ * `max over goals of ( cosine(ideaVec, goalVec) * weight )`, clamped to [0,1]. Weighted-MAX (not
+ * sum/mean) so a focused idea advancing ONE goal strongly scores high. No goals ⇒ 0 / null.
+ */
+export function scoreAlignment(ideaVec: Float32Array, goals: readonly GoalVector[]): AlignmentResult {
+  let bestId: string | null = null;
+  let best = 0;
+  for (const g of goals) {
+    const raw = Math.max(0, cosineSimilarity(ideaVec, g.vec)) * g.weight;
+    if (raw > best) {
+      best = raw;
+      bestId = g.id;
+    }
+  }
+  return { goalId: bestId, goalAlignment: Math.min(1, best) };
+}
+
+/** Injectable embedder so the production alignment path is testable. */
+export interface AlignDeps {
+  readonly embed?: (text: string) => Promise<Float32Array>;
+}
+
+/**
+ * Production alignment: embed the idea + each goal (same reused embedder) and score. No embedder or no
+ * GoalMap ⇒ `{goalId:null, goalAlignment:0}` — capture and roulette still work (ADR-003 T-003d).
+ */
+export async function alignIdea(projectRoot: string, text: string, goalMap: GoalMap, deps: AlignDeps = {}): Promise<AlignmentResult> {
+  if (goalMap.goals.length === 0) return { goalId: null, goalAlignment: 0 };
+  let embed = deps.embed;
+  if (embed === undefined) {
+    const resolved = await resolveAgentdbEmbedder(projectRoot);
+    if ('error' in resolved) return { goalId: null, goalAlignment: 0 };
+    embed = resolved.embed;
+  }
+  try {
+    const ideaVec = await embed(`${BACKLOG_TASK_TYPE}: ${text}`);
+    // LOW-10: USE the goal-embed cache (the ADR-003 design) — goal vectors are stable across captures,
+    // so re-embedding them every `add` is waste. The cache is keyed by embed model+dim (a model change
+    // invalidates it, T-003e) and by each goal's text hash. Cache use is best-effort: any failure just
+    // falls through to a live embed, never breaks alignment.
+    const model = resolveEmbedModel(projectRoot);
+    const useCache = !('error' in model);
+    const cache = useCache ? readGoalEmbedCache(projectRoot) : undefined;
+    const nextGoals: GoalEmbedCache['goals'] = {};
+    const goalVecs: GoalVector[] = [];
+    let cacheChanged = false;
+    for (const g of goalMap.goals) {
+      let vec = useCache && !('error' in model) ? goalCacheHit(cache, model.model, model.dim, g) : undefined;
+      if (vec === undefined) {
+        vec = await embed(`${BACKLOG_TASK_TYPE}: ${goalEmbedText(g)}`);
+        cacheChanged = true;
+      }
+      goalVecs.push({ id: g.id, vec, weight: g.weight });
+      if (useCache) nextGoals[g.id] = { hash: goalTextHash(g), vec: Array.from(vec) };
+    }
+    if (useCache && !('error' in model) && cacheChanged) {
+      try {
+        writeGoalEmbedCache(projectRoot, { model: model.model, dim: model.dim, goals: nextGoals });
+      } catch {
+        /* cache write is best-effort — a failure never affects the score */
+      }
+    }
+    return scoreAlignment(ideaVec, goalVecs);
+  } catch {
+    return { goalId: null, goalAlignment: 0 };
+  }
+}
+
+/* ── Goal-embed cache + manifest invalidation (ADR-003 T-003e) ── */
+
+export interface GoalEmbedCache {
+  readonly model: string;
+  readonly dim: number;
+  /** id → { hash of the embed text, vector as a plain number[] } */
+  readonly goals: Record<string, { readonly hash: string; readonly vec: number[] }>;
+}
+
+function goalCachePath(projectRoot: string): string {
+  return join(backlogDir(projectRoot), 'goal-embeds.json');
+}
+
+function goalTextHash(goal: Goal): string {
+  return createHash('sha1').update(goalEmbedText(goal)).digest('hex').slice(0, 16);
+}
+
+/**
+ * PURE cache validity check (ADR-003 T-003e): a cache is valid for a goal ONLY when the embed
+ * model+dim manifest matches AND the goal's embed-text hash is unchanged. A model change (different
+ * `model`/`dim`) invalidates EVERY cached goal vector — forcing a recompute, never a stale alignment.
+ */
+export function goalCacheHit(cache: GoalEmbedCache | undefined, model: string, dim: number, goal: Goal): Float32Array | undefined {
+  if (cache === undefined || cache.model !== model || cache.dim !== dim) return undefined;
+  const entry = cache.goals[goal.id];
+  if (entry === undefined || entry.hash !== goalTextHash(goal)) return undefined;
+  return Float32Array.from(entry.vec);
+}
+
+export function readGoalEmbedCache(projectRoot: string): GoalEmbedCache | undefined {
+  const path = goalCachePath(projectRoot);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as GoalEmbedCache;
+    if (typeof parsed.model !== 'string' || typeof parsed.dim !== 'number' || typeof parsed.goals !== 'object') return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeGoalEmbedCache(projectRoot: string, cache: GoalEmbedCache): void {
+  const path = goalCachePath(projectRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cache, null, 2));
+}
+
+/* ================================================================== */
+/*  ROULETTE (AM-5 / ADR-004) — WEIGHTED, seeded, no starvation.        */
+/* ================================================================== */
+
+/** Tiny base added to the compass term so an unaligned idea keeps a non-zero weight (no starvation). */
+export const ROULETTE_EPSILON = 0.02;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Ideas eligible for a spin: only `new` and `enriched` (ADR-004). */
+export function eligibleIdeas(ideas: readonly IdeaRecord[]): IdeaRecord[] {
+  return ideas.filter((i) => i.status === 'new' || i.status === 'enriched');
+}
+
+/** Bounded recency decay ∈ [floor, 1]: `2^(-ageDays/halfLife)`, floored so old ideas are down-weighted, never zero. */
+export function recencyDecay(ageMs: number, halfLifeDays: number, floor: number): number {
+  const ageDays = Math.max(0, ageMs) / DAY_MS;
+  const decay = Math.pow(2, -ageDays / halfLifeDays);
+  return Math.max(floor, Math.min(1, decay));
+}
+
+/**
+ * THE selection weight (ADR-004): `(alignment^alpha + EPS) · recencyDecay(age) · (1/effort)`. Strictly
+ * positive for every idea (EPS>0, floor>0, effort≥1) ⇒ no permanent starvation (T-004c). Equal
+ * alignment+age+effort ⇒ equal weights ⇒ a uniform draw (the T-004a control).
+ */
+export function ideaWeight(idea: IdeaRecord, cfg: BacklogConfig['roulette'], nowMs: number): number {
+  // MED-6: EVERY factor is Number.isFinite-guarded so one bad field (NaN alignment, an unparseable
+  // createdTs) degrades to a neutral contribution — it can NEVER poison the whole spin's total (which
+  // would make the draw always pick the last item). A bad timestamp ⇒ neutral (floor) recency.
+  const alignment = Number.isFinite(idea.goalAlignment) ? Math.max(0, Math.min(1, idea.goalAlignment)) : 0;
+  const compass = Math.pow(alignment, cfg.alpha) + ROULETTE_EPSILON;
+  const parsed = Date.parse(idea.createdTs);
+  const age = Number.isFinite(parsed) ? nowMs - parsed : Number.POSITIVE_INFINITY; // bad ts ⇒ maximally old ⇒ floor
+  const recency = recencyDecay(age, cfg.halfLifeDays, cfg.recencyFloor);
+  const effort = Number.isFinite(idea.effort) && idea.effort >= 1 ? Math.max(1, Math.min(5, idea.effort)) : cfg.defaultEffort;
+  const w = compass * recency * (1 / effort);
+  return Number.isFinite(w) && w > 0 ? w : ROULETTE_EPSILON; // last-resort finite floor
+}
+
+/** Deterministic ranked shortlist (`--pick N`): by weight desc, id asc — no RNG. */
+export function rankRoulette(ideas: readonly IdeaRecord[], cfg: BacklogConfig['roulette'], nowMs: number): IdeaRecord[] {
+  return eligibleIdeas(ideas)
+    .map((i) => ({ i, w: ideaWeight(i, cfg, nowMs) }))
+    .sort((a, b) => b.w - a.w || (a.i.id < b.i.id ? -1 : 1))
+    .map((x) => x.i);
+}
+
+/**
+ * A single WEIGHTED-RANDOM spin over normalised weights, using an injected seeded RNG (`rng()∈[0,1)`).
+ * Same seed ⇒ identical pick (ADR-004 T-004b determinism). Returns `undefined` when nothing is eligible.
+ */
+export function spinRoulette(
+  ideas: readonly IdeaRecord[],
+  cfg: BacklogConfig['roulette'],
+  rng: () => number,
+  nowMs: number,
+): IdeaRecord | undefined {
+  const pool = eligibleIdeas(ideas);
+  if (pool.length === 0) return undefined;
+  const weights = pool.map((i) => ideaWeight(i, cfg, nowMs));
+  const total = weights.reduce((a, b) => a + b, 0);
+  if (total <= 0) return pool[0];
+  let r = rng() * total;
+  for (let k = 0; k < pool.length; k += 1) {
+    r -= weights[k]!;
+    if (r < 0) return pool[k];
+  }
+  return pool[pool.length - 1];
+}
+
+/** Build a seeded RNG from a `--seed` integer (reuses the one repo mulberry32). */
+export function seededRng(seed: number): () => number {
+  return mulberry32(Number.isFinite(seed) ? Math.floor(seed) : 0);
+}
+
+/* ================================================================== */
+/*  ENRICH (AM-7 / FR-5) — stage the idea2prd hand-off, do NOT expand.  */
+/* ================================================================== */
+
+/** kebab-case, Latin-only, ≤40 chars (feature-adr slug convention). */
+export function ideaSlug(idea: IdeaRecord): string {
+  const base = idea.text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/g, '');
+  // HIGH-1: the fallback must be a filesystem-safe token, NOT the raw id — a hand-edited id like
+  // `../../../owned` would otherwise make the slug traverse out of `features/`.
+  return base === '' ? `idea-${safeIdToken(idea.id)}` : base;
+}
+
+export interface EnrichmentStaging {
+  readonly slug: string;
+  readonly scaffoldPath: string;
+}
+
+/**
+ * Stage the idea2prd INPUT and hand off to the `idea2prd-manual` skill (an AGENT phase — 02 §R-G).
+ * The CLI writes the scaffold ONLY; it never fabricates a PRD (idea2prd is a skill, not a synchronous
+ * transform). Returns the hand-off target so the agent can pick it up.
+ */
+export function stageEnrichment(
+  projectRoot: string,
+  idea: IdeaRecord,
+  related: readonly IdeaRecord[],
+  goalMap: GoalMap,
+): EnrichmentStaging {
+  const slug = ideaSlug(idea);
+  const dir = join(projectRoot, 'features', slug);
+  const scaffoldPath = join(dir, 'idea2prd-input.md');
+  const goal = idea.goalId !== null ? goalMap.goals.find((g) => g.id === idea.goalId) : undefined;
+  const lines = [
+    `# idea2prd input — ${slug}`,
+    '',
+    '> STAGED by `dz backlog enrich`. This is the HAND-OFF scaffold, not a PRD. Run the',
+    '> `idea2prd-manual` skill (agent phase) to expand it — the CLI never fabricates the PRD.',
+    '',
+    '## Idea',
+    '',
+    idea.text,
+    '',
+    `- id: \`${idea.id}\``,
+    `- effort: ${idea.effort}/5`,
+    `- goal alignment: ${idea.goalAlignment.toFixed(3)}${goal !== undefined ? ` (top goal: ${goal.id} — ${goal.statement})` : ' (no aligned goal)'}`,
+    '',
+    '## Related ideas (dedup RELATED band)',
+    '',
+    related.length > 0 ? related.map((r) => `- \`${r.id}\` — ${r.text}`).join('\n') : '_none_',
+    '',
+    '## Goal context (the compass)',
+    '',
+    goalMap.goals.length > 0 ? goalMap.goals.map((g) => `- \`${g.id}\` (w=${g.weight}): ${g.statement}`).join('\n') : '_no GoalMap_',
+    '',
+    '## Verification & honesty (owned at the BACKLOG layer, per the user steer)',
+    '',
+    '- Apply claim-check discipline: every accuracy claim MEASURED with a reproducer.',
+    '- Run an adversarial red-team pass on the resulting PRD/ADRs.',
+    '- Recall Brain lessons before asserting what exists (`dz recall`).',
+    '',
+  ];
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(scaffoldPath, lines.join('\n'));
+  return { slug, scaffoldPath };
+}
+
+/* ================================================================== */
+/*  JIRA PORT (AM-6 / ADR-006) — closed vocab + registry + real stub.   */
+/*  ⚠ NO MCP CLIENT IMPORT ANYWHERE IN THIS SEAM (grep-guard T-006b).   */
+/* ================================================================== */
+
+export const BACKLOG_BACKENDS = ['jira-mcp', 'copilot-mcp', 'none'] as const;
+export type BacklogBackend = (typeof BACKLOG_BACKENDS)[number];
+
+export function isBacklogBackend(v: unknown): v is BacklogBackend {
+  return typeof v === 'string' && (BACKLOG_BACKENDS as readonly string[]).includes(v);
+}
+
+/** Built by the domain from an IdeaRecord (+ enrichedPath if any). */
+export interface JiraIssueDraft {
+  readonly summary: string;
+  readonly description: string;
+  readonly labels: readonly string[];
+  readonly sourceIdeaId: string;
+}
+export interface IssueRef {
+  readonly backend: BacklogBackend;
+  readonly key: string | null;
+  readonly url?: string;
+  readonly stub: boolean;
+  readonly outboxPath: string;
+}
+export type VerifyForm = 'full' | 'manual';
+export interface JiraVerifyResult {
+  readonly form: VerifyForm;
+  readonly ready: boolean;
+  /** The exact wiring step the user must run — non-empty for a `manual` backend (T-006e). */
+  readonly instruction: string;
+}
+
+/** The I/O the adapters need — injected so `createIssue` is testable without touching disk. */
+export interface BacklogIO {
+  /** Persist an outbox payload for `<ideaId>`; returns the path written. */
+  writeOutbox(ideaId: string, payload: unknown): string;
+}
+
+/** THE SEAM (ADR-006): a port with pure methods; NO MCP client is imported here or by its impls. */
+export interface JiraPort {
+  readonly backend: BacklogBackend;
+  createIssue(draft: JiraIssueDraft, io: BacklogIO): Promise<IssueRef>;
+  verify(): Promise<JiraVerifyResult>;
+}
+
+/** Pure draft builder from an idea. */
+export function buildJiraDraft(idea: IdeaRecord, goalMap: GoalMap): JiraIssueDraft {
+  const goal = idea.goalId !== null ? goalMap.goals.find((g) => g.id === idea.goalId) : undefined;
+  const descLines = [
+    idea.proposal ?? idea.text,
+    '',
+    `Source idea: ${idea.id} (effort ${idea.effort}/5, alignment ${idea.goalAlignment.toFixed(3)})`,
+    goal !== undefined ? `Top goal: ${goal.id} — ${goal.statement}` : 'No aligned goal',
+    idea.relatedIds.length > 0 ? `Related ideas: ${idea.relatedIds.join(', ')}` : '',
+    idea.enrichedPath !== undefined ? `Enriched: ${idea.enrichedPath}` : '',
+  ].filter((l) => l !== '');
+  return {
+    summary: idea.text.length > 120 ? `${idea.text.slice(0, 117)}...` : idea.text,
+    description: descLines.join('\n'),
+    labels: ['dz-backlog', ...idea.tags],
+    sourceIdeaId: idea.id,
+  };
+}
+
+/** The `none` adapter — a REAL stub (not an absence check): writes the full draft to the outbox. */
+const noneAdapter: JiraPort = {
+  backend: 'none',
+  async createIssue(draft, io) {
+    const outboxPath = io.writeOutbox(draft.sourceIdeaId, { backend: 'none', draft });
+    return { backend: 'none', key: null, stub: true, outboxPath };
+  },
+  async verify() {
+    return {
+      form: 'manual',
+      ready: true, // the stub IS ready — it writes an auditable outbox with no external wiring
+      instruction: 'The `none` backend writes .dz/backlog/jira-outbox/<id>.json — no external wiring needed.',
+    };
+  },
+};
+
+/** A declared-not-wired MCP seam: builds+persists the SAME outbox payload; verify() reports `manual`. */
+function declaredMcpAdapter(backend: 'jira-mcp' | 'copilot-mcp', instruction: string): JiraPort {
+  return {
+    backend,
+    async createIssue(draft, io) {
+      // v1: build + persist the same payload; NO live MCP call (FR-8.2). Honest stub — the wire is a TODO.
+      const outboxPath = io.writeOutbox(draft.sourceIdeaId, { backend, draft, note: 'declared-not-wired seam (v1)' });
+      return { backend, key: null, stub: true, outboxPath };
+    },
+    async verify() {
+      return { form: 'manual', ready: false, instruction };
+    },
+  };
+}
+
+/** The registry — coverage-tested (ADR-006 T-006a): keys ≡ BACKLOG_BACKENDS as a set. */
+export const JIRA_ADAPTERS: Record<BacklogBackend, JiraPort> = {
+  'jira-mcp': declaredMcpAdapter(
+    'jira-mcp',
+    'Wire a Jira MCP server: `claude mcp add jira ...` then add it to .mcp.json `mcpServers`. Live wiring is a post-v1 adapter.',
+  ),
+  'copilot-mcp': declaredMcpAdapter(
+    'copilot-mcp',
+    'Wire a Copilot MCP server into .mcp.json `mcpServers`. Live wiring is a post-v1 adapter.',
+  ),
+  none: noneAdapter,
+};
+
+/** Factory: pick the configured adapter; an unknown value fell back to `none` in readBacklogConfig. */
+export function resolveJiraAdapter(cfg: BacklogConfig): JiraPort {
+  return JIRA_ADAPTERS[cfg.jira.adapter] ?? JIRA_ADAPTERS.none;
+}
+
+/** Production BacklogIO — writes `.dz/backlog/jira-outbox/<id>.json`. */
+export function makeBacklogIO(projectRoot: string): BacklogIO {
+  return {
+    writeOutbox(id, payload) {
+      // HIGH-1: refuse any id that is not filesystem-safe — the filename is derived from it. A
+      // traversal id can never write outside jira-outbox/. Legit content-addressed ids always pass.
+      if (!isSafeId(id)) throw new Error(`refusing unsafe idea id for outbox path: ${JSON.stringify(id)}`);
+      const dir = jiraOutboxDir(projectRoot);
+      mkdirSync(dir, { recursive: true });
+      const path = join(dir, `${id}.json`);
+      writeFileSync(path, JSON.stringify(payload, null, 2));
+      return path;
+    },
+  };
+}
+
+/* ================================================================== */
+/*  HARMONIZE (AM-7) — batch semantic dedup of the backlog ideas.       */
+/* ================================================================== */
+
+export interface BacklogHarmonizeReport {
+  readonly mode: 'dry-run' | 'apply';
+  /** True when no embedder was available and clustering fell back to EXACT text. */
+  readonly fellBackToExact: boolean;
+  readonly threshold: number;
+  /** One cluster per group of size ≥ 2: the surviving keeper id + the merged-away ids. */
+  readonly clusters: readonly { readonly keep: string; readonly drops: readonly string[] }[];
+  readonly kept: number;
+  readonly dropped: number;
+  readonly unique: number;
+  readonly snapshotPath?: string;
+  readonly error?: string;
+  /**
+   * MED-E: set when the structured ideas were removed but their agentdb `dz-backlog` vectors could NOT be
+   * pruned (locked/unavailable store). Backlog dedup stays correct (the membership guard drops orphans),
+   * but the store is left with dangling vectors — a non-clean outcome the caller MUST surface, never a
+   * silent success. `dz backlog harmonize` prints this as a warning; the idea removal still stands.
+   */
+  readonly pruneError?: string;
+}
+
+/** Deterministic keeper within a cluster: most uses → oldest → smallest id (stable, testable). */
+function pickKeeper(members: readonly IdeaRecord[]): IdeaRecord {
+  return [...members].sort(
+    (a, b) => b.uses - a.uses || Date.parse(a.createdTs) - Date.parse(b.createdTs) || (a.id < b.id ? -1 : 1),
+  )[0]!;
+}
+
+/**
+ * Batch-dedup the backlog: cluster near-duplicate ideas (cosine ≥ threshold when an embedder is
+ * available, EXACT text otherwise), keep one deterministic keeper per cluster, merge the others'
+ * `uses` into it. DRY-RUN by default (writes nothing); `--apply` SNAPSHOTS FIRST then mutates and
+ * ABORTS the mutation if the snapshot fails (NFR-6). Injectable `embed` for tests.
+ */
+export async function harmonizeBacklog(
+  projectRoot: string,
+  opts: { apply?: boolean; threshold?: number; embed?: ((t: string) => Promise<Float32Array>) | null } = {},
+): Promise<BacklogHarmonizeReport> {
+  const apply = opts.apply === true;
+  const threshold = opts.threshold !== undefined && opts.threshold > 0 && opts.threshold <= 1 ? opts.threshold : DEFAULT_DUPLICATE_THRESHOLD;
+  const ideas = readIdeas(projectRoot);
+
+  let embed = opts.embed;
+  if (embed === undefined) {
+    const resolved = await resolveAgentdbEmbedder(projectRoot);
+    embed = 'error' in resolved ? null : resolved.embed;
+  }
+  let fellBackToExact = embed === null;
+
+  // Build clusters (union-find over ≥threshold cosine, or exact-text groups).
+  const parent = ideas.map((_, i) => i);
+  const find = (x: number): number => {
+    while (parent[x] !== x) {
+      parent[x] = parent[parent[x]!]!;
+      x = parent[x]!;
+    }
+    return x;
+  };
+  const union = (a: number, b: number): void => {
+    parent[find(a)] = find(b);
+  };
+  if (embed !== null && ideas.length >= 2) {
+    try {
+      const vecs = await Promise.all(ideas.map((i) => embed!(`${BACKLOG_TASK_TYPE}: ${i.text}`)));
+      for (let a = 0; a < ideas.length; a += 1) {
+        for (let b = a + 1; b < ideas.length; b += 1) {
+          if (cosineSimilarity(vecs[a]!, vecs[b]!) >= threshold) union(a, b);
+        }
+      }
+    } catch {
+      fellBackToExact = true;
+    }
+  }
+  if (fellBackToExact) {
+    const byText = new Map<string, number>();
+    ideas.forEach((idea, i) => {
+      const first = byText.get(idea.text);
+      if (first === undefined) byText.set(idea.text, i);
+      else union(i, first);
+    });
+  }
+
+  const groups = new Map<number, IdeaRecord[]>();
+  ideas.forEach((idea, i) => {
+    const root = find(i);
+    (groups.get(root) ?? groups.set(root, []).get(root)!).push(idea);
+  });
+
+  const clusters: { keep: string; drops: string[] }[] = [];
+  const keepById = new Map<string, IdeaRecord>();
+  const dropIds = new Set<string>();
+  for (const members of groups.values()) {
+    if (members.length < 2) continue;
+    const keeper = pickKeeper(members);
+    const drops = members.filter((m) => m.id !== keeper.id);
+    clusters.push({ keep: keeper.id, drops: drops.map((d) => d.id) });
+    keepById.set(keeper.id, keeper);
+    for (const d of drops) dropIds.add(d.id);
+  }
+
+  const report: BacklogHarmonizeReport = {
+    mode: apply ? 'apply' : 'dry-run',
+    fellBackToExact,
+    threshold,
+    clusters,
+    kept: clusters.length,
+    dropped: dropIds.size,
+    unique: ideas.length - clusters.length - dropIds.size,
+  };
+  if (!apply || dropIds.size === 0) return report;
+
+  // --apply: snapshot FIRST, then merge uses into keepers and drop the rest.
+  const snapDest = join(backlogDir(projectRoot), `ideas.pre-harmonize-${Date.now()}.jsonl`);
+  const snap = snapshotIdeas(projectRoot, snapDest);
+  if (snap.error !== undefined) return { ...report, error: `backup failed — drop aborted: ${snap.error}` };
+  const merged = new Map<string, IdeaRecord>();
+  for (const [id, keeper] of keepById) merged.set(id, { ...keeper });
+  for (const c of clusters) {
+    const keeper = merged.get(c.keep)!;
+    keeper.uses += c.drops.length;
+  }
+  const survivors = ideas
+    .filter((i) => !dropIds.has(i.id))
+    .map((i) => merged.get(i.id) ?? i);
+  writeIdeas(projectRoot, survivors);
+  // HIGH-A: prune the agentdb `dz-backlog` vectors for every removed idea, so a later `add` can't match
+  // an ORPHAN dzId (a DUPLICATE of a nonexistent idea). Best-effort for the structured store (already
+  // snapshotted + written) — but MED-E: the prune outcome must NOT be swallowed. If it failed, the store
+  // has dangling vectors; report it (a non-clean status) so the user knows, rather than a false success.
+  const prune = deleteAgentdbByDzIds(projectRoot, [...dropIds], { taskTypes: [BACKLOG_TASK_TYPE] });
+  return {
+    ...report,
+    snapshotPath: snapDest,
+    ...(prune.error !== undefined
+      ? { pruneError: `${dropIds.size} idea(s) removed from ideas.jsonl, but their agentdb vectors were NOT pruned: ${prune.error}` }
+      : {}),
+  };
+}
+
+/* ================================================================== */
+/*  MIRROR seam (ADR-001) — write idea vectors through the ONE seam.    */
+/* ================================================================== */
+
+/**
+ * Mirror one idea's vector into the SHARED `.dz/agentdb.db` under `task_type:'dz-backlog'`, written
+ * DIRECTLY through `importVectorsToAgentdb` (upsert-by-dzId) — NOT the configurable vector engine.
+ * This is the load-bearing single-store guarantee (ADR-001/005): dedup ALWAYS searches agentdb, so
+ * the write must ALWAYS land in agentdb, no matter what `memory.vector.engine` says. Upsert-by-dzId
+ * makes a re-mirror idempotent (0 duplicate rows). `guardEmbedSpace` inside `importVectorsToAgentdb`
+ * covers the write (ADR-001 T-001c). Best-effort: NEVER blocks capture (I-1) — honest `{error}`.
+ */
+export async function mirrorIdeaVector(projectRoot: string, idea: IdeaRecord): Promise<{ mirrored: number; error?: string | undefined }> {
+  const emb = await resolveAgentdbEmbedder(projectRoot);
+  if ('error' in emb) return { mirrored: 0, error: emb.error };
+  let vector: Float32Array;
+  try {
+    vector = await emb.embed(`${BACKLOG_TASK_TYPE}: ${idea.text}`); // SAME embed form the dedup query uses
+  } catch (err) {
+    return { mirrored: 0, error: `embed failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const res = await importVectorsToAgentdb(projectRoot, [
+    {
+      dzId: idea.id,
+      vector,
+      text: idea.text,
+      taskType: BACKLOG_TASK_TYPE,
+      score: Math.max(0, Math.min(1, Number.isFinite(idea.goalAlignment) ? idea.goalAlignment : 0)),
+      metadata: { kind: 'dz-backlog-idea' },
+    },
+  ]);
+  return { mirrored: res.imported, ...(res.error !== undefined ? { error: res.error } : {}) };
+}