@dzhechkov/harness-core 0.3.140 → 0.3.142

package/dist/backlog.js

@@ -0,0 +1,755 @@
+/**
+ * `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';
+/* ================================================================== */
+/*  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;
+/** Finite-and-in-range or the fallback (the recurring Infinity-clamp lesson). */
+function clampNum(v, lo, hi, fallback, opts = {}) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < lo || v > hi)
+        return fallback;
+    return opts.intOnly ? Math.floor(v) : v;
+}
+export function readBacklogConfig(projectRoot) {
+    const fallback = {
+        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'));
+        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) {
+    return join(projectRoot, '.dz', 'backlog');
+}
+export function ideasPath(projectRoot) {
+    return join(backlogDir(projectRoot), 'ideas.jsonl');
+}
+export function goalsPath(projectRoot) {
+    return join(backlogDir(projectRoot), 'goals.json');
+}
+export function jiraOutboxDir(projectRoot) {
+    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, createdTs) {
+    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) {
+    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) {
+    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) {
+    // 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)
+        ? raw.status
+        : '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 = {
+        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) => typeof x === 'string') : [],
+        uses: clampNum(raw.uses, 0, Number.MAX_VALUE, 0, { intOnly: true }),
+        tags: Array.isArray(raw.tags) ? raw.tags.filter((x) => 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) {
+    const path = ideasPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const rec = normaliseIdea(JSON.parse(trimmed));
+            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, ideas) {
+    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);
+}
+export function snapshotIdeas(projectRoot, dest) {
+    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)}` };
+    }
+}
+/**
+ * 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, cfg, opts = {}) {
+    // 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 };
+}
+/**
+ * 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, text, cfg, deps = {}) {
+    const ideas = deps.ideas ?? readIdeas(projectRoot);
+    const search = deps.search ??
+        ((root, query) => 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 = [];
+    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) {
+    const path = goalsPath(projectRoot);
+    if (!existsSync(path))
+        return { version: 1, goals: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        const goals = Array.isArray(parsed.goals)
+            ? parsed.goals
+                .map((g) => {
+                const o = g;
+                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) => typeof k === 'string') : [],
+                };
+            })
+                .filter((g) => 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) {
+    return goal.keywords.length > 0 ? `${goal.statement} ${goal.keywords.join(' ')}` : goal.statement;
+}
+/**
+ * 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, goals) {
+    let bestId = 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) };
+}
+/**
+ * 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, text, goalMap, deps = {}) {
+    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 = {};
+        const goalVecs = [];
+        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 };
+    }
+}
+function goalCachePath(projectRoot) {
+    return join(backlogDir(projectRoot), 'goal-embeds.json');
+}
+function goalTextHash(goal) {
+    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, model, dim, goal) {
+    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) {
+    const path = goalCachePath(projectRoot);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (typeof parsed.model !== 'string' || typeof parsed.dim !== 'number' || typeof parsed.goals !== 'object')
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeGoalEmbedCache(projectRoot, cache) {
+    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) {
+    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, halfLifeDays, floor) {
+    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, cfg, nowMs) {
+    // 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, cfg, nowMs) {
+    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, cfg, rng, nowMs) {
+    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) {
+    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) {
+    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;
+}
+/**
+ * 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, idea, related, goalMap) {
+    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'];
+export function isBacklogBackend(v) {
+    return typeof v === 'string' && BACKLOG_BACKENDS.includes(v);
+}
+/** Pure draft builder from an idea. */
+export function buildJiraDraft(idea, goalMap) {
+    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 = {
+    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, instruction) {
+    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 = {
+    '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) {
+    return JIRA_ADAPTERS[cfg.jira.adapter] ?? JIRA_ADAPTERS.none;
+}
+/** Production BacklogIO — writes `.dz/backlog/jira-outbox/<id>.json`. */
+export function makeBacklogIO(projectRoot) {
+    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;
+        },
+    };
+}
+/** Deterministic keeper within a cluster: most uses → oldest → smallest id (stable, testable). */
+function pickKeeper(members) {
+    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, opts = {}) {
+    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) => {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        return x;
+    };
+    const union = (a, b) => {
+        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();
+        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();
+    ideas.forEach((idea, i) => {
+        const root = find(i);
+        (groups.get(root) ?? groups.set(root, []).get(root)).push(idea);
+    });
+    const clusters = [];
+    const keepById = new Map();
+    const dropIds = new Set();
+    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 = {
+        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();
+    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, idea) {
+    const emb = await resolveAgentdbEmbedder(projectRoot);
+    if ('error' in emb)
+        return { mirrored: 0, error: emb.error };
+    let vector;
+    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 } : {}) };
+}
+//# sourceMappingURL=backlog.js.map