@bongos/core 1.19.549 → 1.19.551

package/tests/bug_triage.mjs

@@ -0,0 +1,205 @@
+// tests/bug_triage.mjs
+//
+// Regression guard for task 1001478 — /bug-triage's task-shaped reuse of
+// triage.js's generalized clusterRecords (extracted from the idea-only
+// clusterIdeas so the union-find/Jaccard core is written once), the
+// OPEN_STATUSES set that decides which kind=bug tasks a triage walk sees, and
+// the three HTTP-facing functions (listOpenBugTasks/mergeTaskInto/
+// dismissTask) a grading round caught completely untested — which is exactly
+// how a real envelope-shape bug (GET /tasks responds `{ tasks: [...] }`, not
+// a bare array; `(r.data || []).filter` threw on every run) shipped green.
+//
+// cliClient() is mocked by mutating cli-lib.js's exports BEFORE requiring
+// bug-triage.js (same trick as tests/idea_triage.mjs patching
+// `api.pool.query` before requiring inbox.js): bug-triage.js destructures
+// `{ cliClient }` at require time, so the patched function is what it binds.
+//
+// Run:  node tests/bug_triage.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+
+// A fake api client whose `tasks.*` methods answer from a per-test script of
+// { ok, data, status } responses, and record every call for assertion.
+const calls = [];
+let responses = {};
+const cliLib = require('../scripts/gds/cli-lib.js');
+cliLib.cliClient = async () => ({
+  tasks: {
+    getTasks: async (args) => { calls.push({ method: 'getTasks', args }); return responses.getTasks; },
+    postTasksIdMerge: async (args) => { calls.push({ method: 'postTasksIdMerge', args }); return responses.merge; },
+    postTasksIdAbandon: async (args) => { calls.push({ method: 'postTasksIdAbandon', args }); return responses.abandon; },
+  },
+});
+
+const { clusterRecords } = require('../scripts/gds/triage.js');
+const { listOpenBugTasks, mergeTaskInto, dismissTask, OPEN_STATUSES } = require('../scripts/gds/bug-triage.js');
+
+const { test, summary } = makeRunner();
+
+const mkBug = (id, title, { goalId = 1000001, description = '', createdAt = '2026-01-01T00:00:00Z' } = {}) =>
+  ({ id, title, description, goal_id: goalId, created_at: createdAt });
+
+const bugCluster = (records, opts = {}) => clusterRecords(records, {
+  textOf: (t) => `${t.title || ''} ${t.description || ''}`,
+  kindOf: (t) => t.goal_id || null,
+  timeOf: (t) => new Date(t.created_at),
+  ...opts,
+});
+
+// ---------- OPEN_STATUSES ----------
+
+await test('OPEN_STATUSES: excludes shipped and abandoned (merged tasks reuse abandoned)', () => {
+  assert.ok(!OPEN_STATUSES.has('shipped'));
+  assert.ok(!OPEN_STATUSES.has('abandoned'));
+});
+
+await test('OPEN_STATUSES: includes every live status a bug can sit in', () => {
+  for (const s of ['backlog', 'ready', 'active', 'blocked', 'completed', 'confirmed']) {
+    assert.ok(OPEN_STATUSES.has(s), `${s} should be an open bug status`);
+  }
+});
+
+// ---------- clusterRecords, task-shaped ----------
+
+await test('clusterRecords: near-duplicate bug reports in the SAME goal cluster together', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { createdAt: '2026-01-03T00:00:00Z' }),
+    mkBug(2, 'Safari: login button unresponsive', { createdAt: '2026-01-01T00:00:00Z' }),
+    mkBug(3, 'The login button is broken in Safari', { createdAt: '2026-01-02T00:00:00Z' }),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 1, 'expected exactly one cluster');
+  assert.equal(clusters[0].length, 3);
+  assert.deepEqual(clusteredIds, new Set([1, 2, 3]));
+  assert.equal(clusters[0][0].id, 2, 'oldest first — the suggested keeper');
+});
+
+await test('clusterRecords: unrelated bug reports never cluster', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari'),
+    mkBug(2, 'Export to CSV drops the last row'),
+    mkBug(3, 'Dark mode flickers on page load'),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
+await test('clusterRecords: same-symptom bugs in DIFFERENT goals do not cluster', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { goalId: 1000001 }),
+    mkBug(2, 'Login button does nothing on Safari', { goalId: 1000002 }),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 0, 'two goals reporting the same symptom are not one triage decision');
+  assert.equal(clusteredIds.size, 0);
+});
+
+await test('clusterRecords: a single overlapping word alone is not enough (minShared floor)', () => {
+  const bugs = [
+    mkBug(1, 'Improve the deploy pipeline reliability with retries'),
+    mkBug(2, 'Improve onboarding copy for new builders'),
+  ];
+  const { clusters } = bugCluster(bugs);
+  assert.equal(clusters.length, 0, 'sharing only "improve" must not cluster two unrelated reports');
+});
+
+await test('clusterRecords: no goal_id (null) still partitions consistently', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { goalId: null }),
+    mkBug(2, 'Safari login button is unresponsive', { goalId: null }),
+  ];
+  const { clusters } = bugCluster(bugs);
+  assert.equal(clusters.length, 1, 'two homeless bug reports (goal_id null) can still cluster against each other');
+});
+
+await test('clusterRecords: empty input → no clusters', () => {
+  const { clusters, clusteredIds } = bugCluster([]);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
+// ---------- listOpenBugTasks (the envelope-shape blocker) ----------
+
+await test('listOpenBugTasks: reads the { tasks: [...] } envelope, not a bare array', async () => {
+  responses.getTasks = { ok: true, data: { tasks: [mkBug(1, 'x', {}), { ...mkBug(2, 'y'), status: 'ready' }] } };
+  responses.getTasks.data.tasks[0].status = 'ready';
+  const out = await listOpenBugTasks();
+  assert.equal(out.length, 2, '(r.data || []).filter would have thrown TypeError here — r.data is an object, not an array');
+});
+
+await test('listOpenBugTasks: filters out shipped/abandoned, keeps every open status', async () => {
+  responses.getTasks = {
+    ok: true,
+    data: { tasks: [
+      { ...mkBug(1, 'a'), status: 'ready' },
+      { ...mkBug(2, 'b'), status: 'shipped' },
+      { ...mkBug(3, 'c'), status: 'abandoned' },
+      { ...mkBug(4, 'd'), status: 'confirmed' },
+    ] },
+  };
+  const out = await listOpenBugTasks();
+  assert.deepEqual(out.map((t) => t.id), [1, 4]);
+});
+
+await test('listOpenBugTasks: queries kind=bug with a bounded limit', async () => {
+  calls.length = 0;
+  responses.getTasks = { ok: true, data: { tasks: [] } };
+  await listOpenBugTasks();
+  assert.equal(calls[0].method, 'getTasks');
+  assert.deepEqual(calls[0].args.query, { kind: 'bug', limit: 1000 });
+});
+
+await test('listOpenBugTasks: a non-ok response throws with the status + body', async () => {
+  responses.getTasks = { ok: false, status: 500, data: { error: 'boom' } };
+  await assert.rejects(() => listOpenBugTasks(), /500/);
+});
+
+// ---------- mergeTaskInto ----------
+
+await test('mergeTaskInto: posts into_task_id + reason to the merge route', async () => {
+  calls.length = 0;
+  responses.merge = { ok: true, data: { ok: true, taskId: 5, taskStatus: 'abandoned', mergedIntoTaskId: 9 } };
+  const out = await mergeTaskInto(5, 9, 'same report');
+  assert.equal(calls[0].method, 'postTasksIdMerge');
+  assert.deepEqual(calls[0].args, { id: 5, body: { into_task_id: 9, reason: 'same report' } });
+  assert.equal(out.mergedIntoTaskId, 9);
+});
+
+await test('mergeTaskInto: intoTaskId is coerced to a Number even if passed as a string', async () => {
+  calls.length = 0;
+  responses.merge = { ok: true, data: {} };
+  await mergeTaskInto(5, '9', '');
+  assert.equal(calls[0].args.body.into_task_id, 9);
+  assert.equal(typeof calls[0].args.body.into_task_id, 'number');
+});
+
+await test('mergeTaskInto: a refused merge throws with the server error code attached', async () => {
+  responses.merge = { ok: false, status: 409, data: { error: { code: 'MERGE_TARGET_MERGED' } } };
+  const err = await mergeTaskInto(5, 9, '').catch((e) => e);
+  assert.ok(err instanceof Error);
+  assert.equal(err.code, 'MERGE_TARGET_MERGED');
+});
+
+// ---------- dismissTask ----------
+
+await test('dismissTask: posts a reason to the abandon route', async () => {
+  calls.length = 0;
+  responses.abandon = { ok: true, data: { ok: true, taskId: 5, taskStatus: 'abandoned' } };
+  await dismissTask(5, 'cannot reproduce');
+  assert.equal(calls[0].method, 'postTasksIdAbandon');
+  assert.deepEqual(calls[0].args, { id: 5, body: { reason: 'cannot reproduce' } });
+});
+
+await test('dismissTask: a refused won\'t-fix throws with the server error code attached', async () => {
+  responses.abandon = { ok: false, status: 409, data: { error: { code: 'TASK_HAS_ACTIVE_CLAIM' } } };
+  const err = await dismissTask(5, '').catch((e) => e);
+  assert.equal(err.code, 'TASK_HAS_ACTIVE_CLAIM');
+});
+
+// -------------------------------------------------------------------------
+summary();

package/tests/task_merge.mjs

@@ -0,0 +1,198 @@
+// tests/task_merge.mjs
+//
+// Regression guard for task 1001478 — db.mergeTask, the idea_inbox merge
+// verdict's twin for `tasks` (the /bug-triage counterpart to /idea-triage's
+// merge). See modules/lifecycle/db-ship.js's mergeTask header for the full
+// design rationale (why 'abandoned' + merged_into_task_id, not a new status).
+//
+// Contract under test:
+//   - a live task merges into an existing, unmerged target: status flips to
+//     'abandoned', merged_into_task_id/triage_note/value_summary are written,
+//     the txn COMMITs.
+//   - self-merge → MERGE_SELF, no DB read even reached.
+//   - not found → TASK_NOT_FOUND, ROLLBACK.
+//   - 'shipped' → CANNOT_MERGE_SHIPPED, ROLLBACK, no UPDATE (immutable history).
+//   - already merged into the SAME target → idempotent no-op (alreadyMerged:true).
+//   - already merged into a DIFFERENT target → ALREADY_MERGED, names the
+//     existing target (no re-merge chains).
+//   - active claim → TASK_HAS_ACTIVE_CLAIM, ROLLBACK, no UPDATE.
+//   - the shipped/already-merged guards short-circuit BEFORE the claims lookup.
+//   - target doesn't exist → MERGE_TARGET_NOT_FOUND.
+//   - target is itself merged elsewhere → MERGE_TARGET_MERGED, names where the
+//     chain ends (mirrors idea merge's target-COLUMN check, not target status).
+//   - no reason → value_summary is PRESERVED (no synthesized default;
+//     merged_into_task_id is the queryable source of truth).
+//
+// mergeTask opens its own transaction via pool.connect(); the #538 deps.pool
+// injection seam (honored ONLY when NODE_ENV==='test') drives it with a
+// SQL-aware fakeClient — no live DB — same posture as abandon_task.mjs.
+//
+// Run:  node tests/task_merge.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/lifecycle/db.js');
+const { mergeTask } = db;
+
+const { test, summary } = makeRunner();
+
+// SQL-aware fake keyed on the two SELECTs mergeTask issues, by which id they
+// target — the source row (FOR UPDATE, taskId) and the target row (no lock,
+// intoTaskId). Distinguishing by bound param (not statement text, since both
+// are structurally different queries here) mirrors abandon_task.mjs's shape.
+function fakePool({
+  status = 'ready', notFound = false, mergedInto = null,
+  hasActiveClaim = false, targetNotFound = false, targetMergedInto = null,
+  updatedStatus = 'abandoned',
+} = {}) {
+  return makeSqlAwareClient((s, params) => {
+    if (/^SELECT id, title, status, merged_into_task_id FROM tasks WHERE id = \$1 FOR UPDATE/.test(s)) {
+      return { rows: notFound ? [] : [{ id: params[0], title: 'fixture bug', status, merged_into_task_id: mergedInto }] };
+    }
+    if (/^SELECT id FROM claims WHERE task_id = \$1 AND released_at IS NULL/.test(s)) {
+      return { rows: hasActiveClaim ? [{ id: 999 }] : [] };
+    }
+    if (/^SELECT id, merged_into_task_id FROM tasks WHERE id = \$1/.test(s)) {
+      return { rows: targetNotFound ? [] : [{ id: params[0], merged_into_task_id: targetMergedInto }] };
+    }
+    if (/^UPDATE tasks/.test(s)) {
+      return { rows: [{ id: params[0], title: 'fixture bug', status: updatedStatus }] };
+    }
+    return { rows: [] };   // BEGIN / COMMIT / ROLLBACK
+  });
+}
+
+const find = (queries, re) => queries.find((q) => re.test(String(q.sql).replace(/\s+/g, ' ')));
+const all = (queries, re) => queries.filter((q) => re.test(String(q.sql).replace(/\s+/g, ' ')));
+
+const TASK = 1001;
+const TARGET = 2002;
+
+// =========================================================================
+await test('merge: a ready task merges into an existing target, COMMITs', async () => {
+  const pool = fakePool({ status: 'ready' });
+  const out = await mergeTask({ taskId: TASK, intoTaskId: TARGET, reason: 'same report' }, { pool });
+
+  assert.equal(out.taskStatus, 'abandoned');
+  assert.equal(out.previousStatus, 'ready');
+  assert.equal(out.mergedIntoTaskId, TARGET);
+  assert.equal(out.alreadyMerged, false);
+  assert.ok(find(pool._client.queries, /^UPDATE tasks/), 'the tasks UPDATE must run');
+  assert.ok(find(pool._client.queries, /^COMMIT/), 'must COMMIT');
+  assert.ok(!find(pool._client.queries, /^ROLLBACK/), 'no ROLLBACK on the happy path');
+});
+
+await test('merge: writes merged_into_task_id + triage_note + reason-derived value_summary', async () => {
+  const pool = fakePool({ status: 'ready' });
+  await mergeTask({ taskId: TASK, intoTaskId: TARGET, reason: 'dup of #2002' }, { pool });
+  const upd = find(pool._client.queries, /^UPDATE tasks/);
+  assert.equal(upd.params[0], TASK);
+  assert.equal(upd.params[1], TARGET);
+  assert.equal(upd.params[2], 'dup of #2002');
+  assert.match(String(upd.sql), /merged_into_task_id = \$2/);
+  assert.match(String(upd.sql), /triage_note = NULLIF/);
+});
+
+await test('merge: no reason PRESERVES the existing value_summary (no synthesized default)', async () => {
+  // Round-2 grade finding: an earlier version fell back to a synthesized
+  // "Merged into #<N>" default, which unconditionally overwrote a
+  // completed/confirmed bug task's real value_summary. mergeTask now matches
+  // abandonTask's own COALESCE(NULLIF($n,''), value_summary) shape exactly —
+  // merged_into_task_id is the queryable source of truth for where it went.
+  const pool = fakePool({ status: 'ready' });
+  await mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool });
+  const upd = find(pool._client.queries, /^UPDATE tasks/);
+  assert.equal(upd.params[2], '', 'empty reason binds empty string');
+  assert.match(String(upd.sql), /COALESCE\(NULLIF\(\$3, ''\), value_summary\)/);
+});
+
+await test('merge: self-merge is refused before any SELECT (right after BEGIN)', async () => {
+  const pool = fakePool({ status: 'ready' });
+  await assert.rejects(
+    () => mergeTask({ taskId: TASK, intoTaskId: TASK }, { pool }),
+    (err) => err.code === 'MERGE_SELF',
+  );
+  assert.equal(all(pool._client.queries, /^SELECT/).length, 0, 'no SELECT reached — the check runs before the task row is even locked');
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('merge: a missing task throws TASK_NOT_FOUND and rolls back', async () => {
+  const pool = fakePool({ notFound: true });
+  await assert.rejects(
+    () => mergeTask({ taskId: 424242, intoTaskId: TARGET }, { pool }),
+    (err) => err.code === 'TASK_NOT_FOUND',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('merge: a shipped task is refused (immutable history) and rolls back', async () => {
+  const pool = fakePool({ status: 'shipped' });
+  await assert.rejects(
+    () => mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool }),
+    (err) => err.code === 'CANNOT_MERGE_SHIPPED',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('merge: the shipped guard short-circuits BEFORE the claims lookup', async () => {
+  const pool = fakePool({ status: 'shipped' });
+  await mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool }).catch(() => {});
+  assert.equal(all(pool._client.queries, /SELECT id FROM claims/).length, 0,
+    'a shipped task must not even query claims');
+});
+
+await test('merge: already merged into the SAME target is an idempotent no-op', async () => {
+  const pool = fakePool({ status: 'abandoned', mergedInto: TARGET });
+  const out = await mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool });
+  assert.equal(out.alreadyMerged, true);
+  assert.equal(out.mergedIntoTaskId, TARGET);
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0, 'idempotent — no second UPDATE');
+  assert.equal(all(pool._client.queries, /SELECT id FROM claims/).length, 0, 'no claims lookup needed');
+  assert.ok(find(pool._client.queries, /^COMMIT/), 'still COMMITs the (empty) txn');
+});
+
+await test('merge: already merged into a DIFFERENT target is refused, naming the existing one', async () => {
+  const pool = fakePool({ status: 'abandoned', mergedInto: 5005 });
+  const err = await mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool }).catch((e) => e);
+  assert.equal(err.code, 'ALREADY_MERGED');
+  assert.equal(err.merged_into, '5005');
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+});
+
+await test('merge: a task with an active claim is refused (release first) and rolls back', async () => {
+  const pool = fakePool({ status: 'ready', hasActiveClaim: true });
+  await assert.rejects(
+    () => mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool }),
+    (err) => err.code === 'TASK_HAS_ACTIVE_CLAIM',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('merge: a nonexistent target throws MERGE_TARGET_NOT_FOUND and rolls back', async () => {
+  const pool = fakePool({ status: 'ready', targetNotFound: true });
+  await assert.rejects(
+    () => mergeTask({ taskId: TASK, intoTaskId: 999999 }, { pool }),
+    (err) => err.code === 'MERGE_TARGET_NOT_FOUND',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('merge: a target that is itself merged elsewhere is refused, naming where the chain ends', async () => {
+  const pool = fakePool({ status: 'ready', targetMergedInto: 7007 });
+  const err = await mergeTask({ taskId: TASK, intoTaskId: TARGET }, { pool }).catch((e) => e);
+  assert.equal(err.code, 'MERGE_TARGET_MERGED');
+  assert.equal(err.merged_into, '7007');
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+});
+
+// -------------------------------------------------------------------------
+summary();

package/tests/triage_development.mjs

@@ -16,6 +16,9 @@ const {
   parseDevelopment,
   loadDevelopment,
   formatDevelopment,
+  clusterIdeas,
+  significantWords,
+  jaccard,
 } = require('../scripts/gds/triage.js');
 
 let passed = 0;
@@ -135,6 +138,108 @@ test('formatDevelopment: empty arrays render nothing', () => {
   assert.doesNotMatch(out, /challenges:/);
 });
 
+// ---------- significantWords / jaccard ----------
+
+test('significantWords: lowercases, strips stopwords + short tokens', () => {
+  const s = significantWords('Add a Dark Mode Toggle to the Settings Page');
+  assert.ok(s.has('dark'));
+  assert.ok(s.has('mode'));
+  assert.ok(s.has('toggle'));
+  assert.ok(s.has('settings'));
+  assert.ok(!s.has('a'), 'stopword "a" leaked through');
+  assert.ok(!s.has('the'), 'stopword "the" leaked through');
+  assert.ok(!s.has('to'), 'stopword "to" leaked through');
+});
+
+test('jaccard: identical sets → 1, disjoint sets → 0, empty set → 0', () => {
+  assert.equal(jaccard(new Set(['a', 'b']), new Set(['a', 'b'])), 1);
+  assert.equal(jaccard(new Set(['a']), new Set(['b'])), 0);
+  assert.equal(jaccard(new Set(), new Set(['a'])), 0);
+  assert.equal(jaccard(new Set(), new Set()), 0);
+});
+
+test('jaccard: partial overlap is intersection / union', () => {
+  // {a,b,c} ∩ {b,c,d} = {b,c} (2); ∪ = {a,b,c,d} (4) → 0.5
+  assert.equal(jaccard(new Set(['a', 'b', 'c']), new Set(['b', 'c', 'd'])), 0.5);
+});
+
+// ---------- clusterIdeas ----------
+
+const mkIdea = (id, title, { kind = 'feature', body_md = '', capturedAt = '2026-01-01T00:00:00Z', grade } = {}) =>
+  ({ id, title, body_md, kind, grade, captured_at: capturedAt });
+
+test('clusterIdeas: near-duplicate titles of the SAME kind cluster together', () => {
+  const ideas = [
+    mkIdea(1, 'Add dark mode toggle to settings', { capturedAt: '2026-01-03T00:00:00Z' }),
+    mkIdea(2, 'Dark mode toggle for settings page', { capturedAt: '2026-01-01T00:00:00Z' }),
+    mkIdea(3, 'Support a dark mode toggle in settings', { capturedAt: '2026-01-02T00:00:00Z' }),
+  ];
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 1, 'expected exactly one cluster');
+  assert.equal(clusters[0].length, 3);
+  assert.deepEqual(clusteredIds, new Set([1, 2, 3]));
+  // oldest first — the suggested keeper
+  assert.equal(clusters[0][0].id, 2);
+});
+
+test('clusterIdeas: unrelated ideas never cluster', () => {
+  const ideas = [
+    mkIdea(1, 'Add dark mode toggle to settings'),
+    mkIdea(2, 'Fix flaky CI test for the deploy pipeline'),
+    mkIdea(3, 'Write an ADR about the credit reward formula'),
+  ];
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
+test('clusterIdeas: same-topic ideas of DIFFERENT kind do not cluster (a bug is not a dup of a feature)', () => {
+  const ideas = [
+    mkIdea(1, 'Dark mode toggle is broken on mobile', { kind: 'bug' }),
+    mkIdea(2, 'Add a dark mode toggle', { kind: 'feature' }),
+  ];
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 0, 'a bug report and a feature ask must not be treated as the same duplicate');
+  assert.equal(clusteredIds.size, 0);
+});
+
+test('clusterIdeas: a Full Idea is never eligible for batch clustering', () => {
+  const ideas = [
+    mkIdea(1, 'Add dark mode toggle to settings', { grade: 'full' }),
+    mkIdea(2, 'Dark mode toggle for settings page', { grade: 'full' }),
+  ];
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 0, 'Full Ideas must go through the shape recommendation, never a batch merge');
+  assert.equal(clusteredIds.size, 0);
+});
+
+test('clusterIdeas: a single overlapping word alone is not enough (minShared floor)', () => {
+  const ideas = [
+    mkIdea(1, 'Improve the deploy pipeline reliability with retries'),
+    mkIdea(2, 'Improve onboarding copy for new builders'),
+  ];
+  const { clusters } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 0, 'sharing only "improve" must not cluster two unrelated ideas');
+});
+
+test('clusterIdeas: three ideas, two of which duplicate — only the pair clusters', () => {
+  const ideas = [
+    mkIdea(1, 'Add dark mode toggle to settings', { capturedAt: '2026-01-02T00:00:00Z' }),
+    mkIdea(2, 'Dark mode toggle for the settings page', { capturedAt: '2026-01-01T00:00:00Z' }),
+    mkIdea(3, 'Write an ADR about the credit reward formula'),
+  ];
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  assert.equal(clusters.length, 1);
+  assert.deepEqual(new Set(clusters[0].map((i) => i.id)), new Set([1, 2]));
+  assert.ok(!clusteredIds.has(3));
+});
+
+test('clusterIdeas: empty input → no clusters', () => {
+  const { clusters, clusteredIds } = clusterIdeas([]);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
 // ---------- summary ----------
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);