@bongos/core 1.19.549 → 1.19.550

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.549",
-  "core_contract": "1.19.549",
-  "source_commit": "a554c51b4ea9134b53e0f99617a051c65cf1fb34",
+  "core_version": "1.19.550",
+  "core_contract": "1.19.550",
+  "source_commit": "c1759a04d89ed06abdc8dfe92880259633704aeb",
   "source_ref": "HEAD",
-  "built_at": "2026-09-04T18:37:41.417Z",
+  "built_at": "2026-09-04T18:42:59.133Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 441,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2478,
-  "tree_sha256": "9cee93593f3443ba78ae1c00bb5cd092008ed33ee8c024f4e61a7d17d67bffb5",
+  "tree_sha256": "d36204b8544ce3a80ec2ac8a90bd182e3157116d8944fddb8b72468558c0244b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -177,7 +177,7 @@
     {
       "path": ".claude/skills/idea-triage/SKILL.md",
       "mode": "0000644",
-      "sha256": "b64fe42bb2a542304802b48bea348ae817608ac47f026d98c4de9bea5aa90174"
+      "sha256": "2519755269ff2d55e3c060569f7d16c440428ba005d206a3bf12fe2275830285"
     },
     {
       "path": ".claude/skills/ideate/SKILL.md",
@@ -2647,7 +2647,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "c4f07821d5cae7bacdc51e2d7a0f0c5672beb7ba623069c9b4f88e565d8f77b6"
+      "sha256": "d3af686f65da15d8a3c4e8e291b7c4e2a9c025e2cc78305d509165978412329f"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7452,12 +7452,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8a3f8bc746c2704c4859a36a3f365d6c24305019ba6270aa2c25abbd6bba1bef"
+      "sha256": "a0768e258949174041e701e168aeab239b06a4e1ccc58298a0438c241a34cc58"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2a7d837ba22c70e21b083f3189108a90a974312b07bccf634bca4175e7213697"
+      "sha256": "24085dcaa56b6f1085b7f75682d68d4f124c7ff51a8eef763a9e2296dfee9e10"
     },
     {
       "path": "public-docs/index.html",
@@ -8702,7 +8702,7 @@
     {
       "path": "scripts/gds/triage.js",
       "mode": "0000644",
-      "sha256": "831de1914642a7dcf7c591c9cc69b37c917122e04428cb1e28fc00b07170b603"
+      "sha256": "39cbb3b02f4dd8fab80ad53d39b95c3d94666c65b3eed5fbb38995551d170617"
     },
     {
       "path": "scripts/gds/turn-end-sound.js",
@@ -9147,7 +9147,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9808388b3f47f916911b59d0434a3e67f466869be9a3c7fa9adde9fb1274770c"
+      "sha256": "9ac49d0373037ef2fa93837e2483adb5bda5c40514a2c8458489092c03f4d9fc"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12302,7 +12302,7 @@
     {
       "path": "tests/triage_development.mjs",
       "mode": "0000644",
-      "sha256": "74798ce81280d4fcfa5844b575c3c64db582308f7a0726fc420317fe83eadd96"
+      "sha256": "56ff1fab014462291349ac200aab9d12e11a73c028aebeb564866b7a1b309fbd"
     },
     {
       "path": "tests/ui_design_kit.mjs",

package/.claude/skills/idea-triage/SKILL.md

@@ -53,9 +53,10 @@ capture-time suggester (R08/R09/R11 surfaces) is where the fix belongs.
 ## What this skill does
 
 1. Lists open ideas via `GET /api/gds/inbox`.
-2. **Develops the open ideas in parallel** — spawns one subagent per idea (the Agent tool) that fleshes the one-liner out into a structured *open-questions / challenges / risks* block, so the Archon verdicts on a developed idea instead of a bare title (task 930).
-3. For each, prompts the user with: **promote** (create a task and link it), **discard** (closed, no action), or **merge** (this duplicates idea N, mark merged into N).
-4. Updates each idea via `PATCH /api/gds/inbox/:id` with the verdict.
+2. **Batches near-duplicate ideas** into one verdict per cluster (`node scripts/gds/triage.js`'s `clusterIdeas`), so a backlog of similar asks doesn't cost one decision each (task 1001465).
+3. **Develops what's left with a LEAN inline pass by default** — reasoning from context already in the session, no subagent spend — and escalates to a FEW targeted subagents only where repo grounding would actually flip the verdict (task 1001465; the old unconditional 12-subagent fan-out is now opt-in, task 930's original mechanism).
+4. For each, prompts the user with: **promote** (create a task and link it), **discard** (closed, no action), or **merge** (this duplicates idea N, mark merged into N).
+5. Updates each idea via `PATCH /api/gds/inbox/:id` with the verdict.
 
 ## How to use
 
@@ -91,33 +92,46 @@ this order and prints the grade on each card, and `render-ideas.js` renders the
 same two sections — so the interactive walk, the generated file and this skill all
 show the same idea the same way.
 
-**Step 1.5 — develop the open ideas in parallel (task 930).**
+**Step 1.4 — a cheap staleness pass, before anything else costs a token.** Quick-skim each open idea's title/body against the current codebase/CLAUDE.md to catch ones already implemented, already superseded, or otherwise obviously stale. A recent triage found 47 of 170 open ideas already stale — filtering those first means neither the batching pass nor the development pass below is spent on an idea that just needs a discard.
 
-**Before spawning any subagents, run a cheap staleness pass over the list first** — a quick skim of each idea's title/body against the current codebase/CLAUDE.md to catch ideas that are already implemented, already superseded, or otherwise obviously stale. A recent triage found 47 of 170 open ideas already stale; filtering those out first means the expensive multi-agent development pass below is only spent on ideas that still need it.
+**Step 1.5a — batch near-duplicate ideas BEFORE developing anything (task 1001465).**
 
-Then, before walking the list, **flesh out each remaining open idea with a subagent** so the verdict lands on a developed idea, not a one-liner. Spawn the subagents **in parallel** (multiple `Agent` tool calls in a single message) — they run while you prepare the walk, so there's no serial wait.
+Run `clusterIdeas` (`scripts/gds/triage.js` — pure, no I/O): it groups open quick/spark ideas that share a `kind` and a high title/body word overlap. For each cluster it returns, offer the user ONE decision covering the whole group instead of walking each member — this is the actual fix for "triage costs a ton of credits" (idea 377): a backlog of near-identical asks used to cost one full development + verdict PER idea, and now costs one:
 
-- **Model:** `opus` for every development subagent. This is research / design analysis against the live repo, which per CLAUDE.md §2's routing table is Opus work — never inherit silently, never downgrade to Haiku.
-- **Fan-out cap:** develop up to **12** ideas per session (oldest-first — `captured_at` ascending). If there are more than 12 open, note "developed the 12 oldest; the rest are walked undeveloped" so nothing is silently dropped.
-- **One idea per subagent.** Give each subagent the idea's `id`, `title`, `body_md`, `kind`, and `captured_by`, and this instruction:
+> Cluster of 3 likely duplicates: #101 "Add dark mode toggle", #145 "Dark mode support", #203 "Support a dark theme". **Keep #101 and merge the rest, discard all, walk them individually, or skip?**
 
-  > Flesh out this Example idea for an Archon triage verdict. Read the relevant code/docs to ground yourself (start from CLAUDE.md and the surfaces the idea touches). Return ONLY a JSON object with these keys: `summary` (one sentence, what integrating it actually means), `integration_surfaces` (array of files/areas it would touch), `open_questions` (array — the decisions a human must make before this can be a task), `challenges` (array — what's hard or unclear), `risks` (array — what could break or regress), `rough_effort` (one of `S`/`M`/`L`), `recommendation` (one of `promote`, `discard`, `merge:#<id>`, `needs-info`). Keep each array item to one line. Do not invent surfaces you didn't verify exist.
+- **Keep #N** → merge every other member into #N (`merged_into_idea_id`), leaving #N itself open — it still gets the normal Step 2 walk below, since "which of these duplicates is real" and "should the real one become a task" are different decisions.
+- **Discard all** → every member closed, one shared `triage_note`.
+- **Individually** → ignore the grouping for this cluster; each member returns to the normal walk.
+- **Skip** → leave the whole cluster open; it clusters again next triage.
 
-- **Collect the results into a development cache** keyed by idea id and write it to a temp file so the deterministic walker can also surface it:
+`node scripts/gds/triage.js` already runs this pass automatically before its interactive walk — if a human is running the deterministic walker instead of you, they get it for free with no flag.
+
+**Step 1.5b — develop what's LEFT with a lean inline pass by default (task 1001465).**
+
+**The subagent fan-out below is now OPT-IN, not the default.** The prior design ran a 12-Opus-subagent fan-out unconditionally on every session — the main cost driver idea 377 was filed about. Default instead to a **lean inline pass**: for each remaining open idea (after batching), reason about it yourself using context you already have — CLAUDE.md, `/recall`, a quick grep if genuinely needed — and write a short inline note (one or two lines: what it touches, the one open question that matters) directly in the session. No `Agent` tool call, no JSON cache file, no per-idea cost.
+
+**Escalate to a targeted subagent only when the inline pass can't tell whether repo grounding would flip the verdict** — a technical/GDS idea where "is this already implemented?", "does this surface still exist?", or "would this conflict with X" needs an actual code read to answer, not a guess. Cap this at a **FEW** ideas per session (3, not 12) — if more than 3 are genuinely ambiguous, develop the 3 oldest and note the rest are walked on the inline pass alone.
+
+- **Model:** `opus` for a targeted subagent — this is still research/design analysis against the live repo (CLAUDE.md §2's routing table), never downgrade to Haiku just because there are fewer of them now.
+- **One idea per subagent**, same instruction as before: give it the idea's `id`, `title`, `body_md`, `kind`, `captured_by`, and ask for the same JSON shape (`summary`, `integration_surfaces`, `open_questions`, `challenges`, `risks`, `rough_effort`, `recommendation`) — only the FAN-OUT WIDTH changed, not the shape a developed idea returns.
+- **Collect results into the same development cache**, written to `${TMPDIR:-/tmp}/otb-idea-development.json` (Windows: `%TEMP%\otb-idea-development.json`):
 
   ```json
   { "generated_at": "<ISO>", "ideas": { "228": { "summary": "...", "integration_surfaces": ["..."], "open_questions": ["..."], "challenges": ["..."], "risks": ["..."], "rough_effort": "M", "recommendation": "needs-info" } } }
   ```
 
-  Write it to `${TMPDIR:-/tmp}/otb-idea-development.json` (Windows: `%TEMP%\otb-idea-development.json`). A subagent that fails or returns unparseable JSON is simply omitted from the cache — that idea is walked undeveloped, not blocked.
+  A subagent that fails or returns unparseable JSON is simply omitted — that idea is walked on the inline pass alone, not blocked.
+
+**The full 12-idea fan-out is still available, explicitly, when the queue genuinely needs it** — a big backlog day, or the user asks for "the deep pass" / "develop all of these with subagents". When asked for it: spawn one Opus subagent per open idea (not just the ambiguous few), up to the same 12-idea cap (oldest-first), same instruction and cache shape as above. This is the OLD default, now a deliberate choice rather than something that runs unasked every time.
 
-If a human will run the interactive walker instead of the Claude-driven walk below, hand it the cache:
+If a human will run the interactive walker instead of the Claude-driven walk below, hand it the cache (works the same whether it came from the lean pass's few subagents or the full deep pass):
 
 ```
 node scripts/gds/triage.js --development "${TMPDIR:-/tmp}/otb-idea-development.json"
 ```
 
-`triage.js` prints each idea's developed block above its verdict prompt. It never *generates* the analysis (that's this skill's subagent fan-out) — it only displays what the cache holds, and runs exactly as before when no cache is present.
+`triage.js` prints each idea's developed block above its verdict prompt, and runs its own batch-cluster pass (Step 1.5a) automatically first. It never *generates* the analysis (that's this skill's job); it only displays what the cache holds, and runs exactly as before when no cache is present.
 
 > **Not in this cut (follow-up leg).** The next step is to let the Archon push the developed `open_questions` *back to the submitter* — a round-trip in the Discord `#ideas` thread / DM before promotion — so the submitter says how they'd want it integrated. That needs the Discord bot interaction + idea↔thread linking (idea `#216` / [ADR 0033](../../../docs/adr/<redacted>.md)) and is tracked separately. For now the open questions are answered by the Archon in-session.
 

package/docs/module-api-changelog.md

@@ -1547,5 +1547,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.547 with no explicit bump. run 33905411089. (task 1002620)
   1.19.549 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.548 with no explicit bump. run 33906859934. (task 1002620)
+  1.19.550 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.549 with no explicit bump. run 33907331050. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.549",
+  "version": "1.19.550",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.549",
+      "version": "1.19.550",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.549",
+  "version": "1.19.550",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/triage.js

@@ -10,14 +10,26 @@
 //   node scripts/gds/triage.js --development <path>   (or env OTB_IDEA_DEVELOPMENT)
 //
 // --development <path> loads a "development cache" — a JSON blob the
-// /idea-triage skill writes after its parallel idea-development subagents run
-// (task 930). When present, each idea's developed block (summary, integration
-// surfaces, open questions, challenges, risks, rough effort, recommendation)
-// is printed above the verdict prompt, so a human at a terminal verdicts on a
-// developed idea instead of the one-liner — the same context the skill's
-// Claude-driven walk holds in-session. This script never *generates* that
-// analysis (LLM fan-out is the skill's job); it only surfaces it. Backward-
-// compatible: with no flag/env and no file, the walk is exactly as before.
+// /idea-triage skill writes after a (now OPT-IN, task 1001465) parallel
+// idea-development subagent fan-out runs (task 930). When present, each
+// idea's developed block (summary, integration surfaces, open questions,
+// challenges, risks, rough effort, recommendation) is printed above the
+// verdict prompt, so a human at a terminal verdicts on a developed idea
+// instead of the one-liner — the same context the skill's Claude-driven walk
+// holds in-session. This script never *generates* that analysis (LLM fan-out
+// is the skill's job, and only for the FEW ideas it targets); it only
+// surfaces it. Backward-compatible: with no flag/env and no file, the walk is
+// exactly as before.
+//
+// BATCH CLUSTER PASS (task 1001465). Before the one-at-a-time walk, near-
+// duplicate open ideas (same `kind`, high title/body word overlap — see
+// clusterIdeas below) are grouped and offered ONE verdict for the whole
+// group: keep a canonical idea and merge the rest into it, discard the whole
+// group, walk them individually anyway, or skip the cluster (leave all open).
+// This is the actual credit-cost fix idea 377 asked for — the unconditional
+// 12-subagent development fan-out this replaced was expensive PRECISION on
+// each idea; it never reduced the NUMBER of verdicts a triager had to make on
+// a backlog of near-identical asks, which batching does directly.
 //
 // Prompts per idea:
 //   [p]romote        → create a backlog task, mark idea 'promoted',
@@ -30,6 +42,14 @@
 //   [s]kip           → no patch; idea surfaces again next triage
 //   [q]uit           → exit early, print partial summary
 //
+// Prompts per duplicate cluster (before the per-idea walk):
+//   [k]eep #N        → merge every other member into #N (default: the
+//                      oldest); #N itself is NOT verdicted here — it still
+//                      gets the normal per-idea walk below
+//   [d]iscard        → mark every member in the cluster 'discarded'
+//   [i]ndividually   → ignore the cluster grouping; walk each member normally
+//   [s]kip           → no patch; the whole cluster surfaces again next triage
+//
 // Exit codes:
 //   0  walked cleanly (incl. empty inbox)
 //   1  api / network error
@@ -266,6 +286,162 @@ function printIdea(idea, idx, total) {
   console.log(sep);
 }
 
+// ── duplicate clustering (task 1001465) ─────────────────────────────────────
+//
+// Words that carry no topical signal — stripped before comparing two ideas so
+// two totally unrelated asks that both happen to say "should" and "add" don't
+// register as similar.
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'the', 'of', 'to', 'in', 'on', 'for', 'is', 'are', 'with',
+  'this', 'that', 'it', 'as', 'be', 'at', 'by', 'from', 'or', 'not', 'into',
+  'out', 'up', 'can', 'we', 'should', 'also', 'add', 'support', 'would',
+  'have', 'has', 'when', 'so', 'if', 'but', 'than', 'then', 'over',
+]);
+
+function significantWords(text) {
+  const words = String(text || '').toLowerCase().match(/[a-z0-9]+/g) || [];
+  return new Set(words.filter((w) => w.length > 2 && !STOPWORDS.has(w)));
+}
+
+// Jaccard similarity over two word sets: |intersection| / |union|. 0 when
+// either set is empty (an idea with no significant words can't be "similar"
+// to anything — that would be a false match, not a true one).
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const w of a) if (b.has(w)) shared++;
+  return shared / (a.size + b.size - shared);
+}
+
+// Group likely-duplicate OPEN ideas so the walk can offer one batch verdict
+// per group instead of re-litigating each member individually. Heuristic, not
+// semantic: two ideas cluster only when they share the same `kind` (a bug and
+// a feature asking the same underlying question are not the same triage
+// decision) AND their title+body word sets clear both a minimum SHARED-word
+// floor and a Jaccard similarity threshold — the floor stops two long,
+// unrelated ideas from clustering on a borderline ratio built from a single
+// coincidental word. Full Ideas are never eligible: they get their own shape
+// recommendation (SKILL.md Step 2.5), and batching one away would skip that
+// judgment. Pure (no I/O, no randomness, no idea mutated) — directly
+// unit-testable; the interactive merge/discard/skip choice lives in main().
+// Returns { clusters, clusteredIds }: clusters is an array of idea-arrays
+// (each length >= 2, oldest member first — the natural "keep this one"
+// default), clusteredIds is a Set of every idea id inside some cluster.
+function clusterIdeas(ideas, { threshold = 0.34, minShared = 2 } = {}) {
+  const eligible = ideas.filter((i) => (i.grade || 'quick') !== 'full');
+  const words = eligible.map((i) => significantWords(`${i.title || ''} ${i.body_md || ''}`));
+  const n = eligible.length;
+  const parent = Array.from({ length: n }, (_, i) => i);
+  function find(x) { while (parent[x] !== x) { parent[x] = parent[parent[x]]; x = parent[x]; } return x; }
+  function union(a, b) { const ra = find(a); const rb = find(b); if (ra !== rb) parent[ra] = rb; }
+
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      if ((eligible[i].kind || null) !== (eligible[j].kind || null)) continue;
+      let shared = 0;
+      for (const w of words[i]) if (words[j].has(w)) shared++;
+      if (shared < minShared) continue;
+      if (jaccard(words[i], words[j]) >= threshold) union(i, j);
+    }
+  }
+
+  const groups = new Map();
+  for (let i = 0; i < n; i++) {
+    const root = find(i);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(eligible[i]);
+  }
+  const clusters = [];
+  const clusteredIds = new Set();
+  for (const members of groups.values()) {
+    if (members.length < 2) continue;
+    members.sort((a, b) => new Date(a.captured_at) - new Date(b.captured_at));
+    clusters.push(members);
+    for (const m of members) clusteredIds.add(m.id);
+  }
+  return { clusters, clusteredIds };
+}
+
+function printCluster(cluster) {
+  const sep = '┄'.repeat(72);
+  console.log(`\n${sep}`);
+  console.log(`Cluster of ${cluster.length} likely duplicates (oldest first — the suggested keeper):`);
+  for (const m of cluster) console.log(`  #${m.id}  [${m.kind || '—'}]  ${trim(m.title, 80)}`);
+  console.log(sep);
+}
+
+// The interactive batch pass over one cluster. Mutates `state` (summary
+// counts + the promoted/discarded/merged id lists main() already tracks) and
+// returns nothing; `clusteredIds` is mutated in place so a choice of
+// "individually" or "keep #N" puts the affected idea(s) back into the normal
+// per-idea walk that runs after every cluster has been offered.
+async function handleCluster(rl, cluster, clusteredIds, state) {
+  printCluster(cluster);
+  let handled = false;
+  while (!handled) {
+    const ans = (await prompt(rl, `  [k]eep #${cluster[0].id} & merge the rest / [d]iscard all / [i]ndividually / [s]kip cluster > `)).trim().toLowerCase();
+
+    if (ans === 's' || ans === 'skip' || ans === '') { handled = true; break; }
+
+    if (ans === 'i' || ans === 'individually') {
+      for (const m of cluster) clusteredIds.delete(m.id);
+      console.log('  → walking this cluster\'s ideas individually');
+      handled = true; break;
+    }
+
+    if (ans === 'd' || ans === 'discard') {
+      const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+      for (const m of cluster) {
+        try {
+          await patchIdea(m.id, {
+            status: 'discarded',
+            reviewed_at: new Date().toISOString(),
+            triage_note: reason ? trim(reason, 60) : 'discarded as part of a batch-verdicted duplicate cluster',
+          });
+          state.summary.discarded++;
+          state.discardedIds.push(m.id);
+        } catch (err) {
+          console.error(`  ! #${m.id}: ${err.message}`);
+        }
+      }
+      console.log(`  ✖ discarded ${cluster.length} duplicate ideas`);
+      handled = true; break;
+    }
+
+    if (ans === 'k' || ans === 'keep' || ans.startsWith('k ') || ans.startsWith('k#')) {
+      let canonicalId = cluster[0].id;
+      const inline = ans.replace(/^k(eep)?(\s|#)*/, '').trim();
+      if (inline) {
+        const n = Number(inline.replace(/^#/, ''));
+        if (Number.isFinite(n) && n > 0 && cluster.some((m) => String(m.id) === String(n))) canonicalId = n;
+        else if (Number.isFinite(n) && n > 0) console.log(`  ! #${n} isn't in this cluster; keeping #${canonicalId}`);
+      }
+      for (const m of cluster) {
+        if (String(m.id) === String(canonicalId)) continue;
+        try {
+          await patchIdea(m.id, {
+            status: 'merged',
+            merged_into_idea_id: Number(canonicalId),
+            reviewed_at: new Date().toISOString(),
+            triage_note: `duplicate cluster batch-merged into #${canonicalId}`,
+          });
+          state.summary.merged++;
+          state.mergedIds.push(m.id);
+        } catch (err) {
+          console.error(`  ! #${m.id}: ${err.message}`);
+        }
+      }
+      // The keeper is untouched by the batch verdict — it still needs its own
+      // promote/discard/merge decision, so it goes back into the normal walk.
+      clusteredIds.delete(canonicalId);
+      console.log(`  ⇢ merged ${cluster.length - 1} duplicate(s) into #${canonicalId} — #${canonicalId} still needs its own verdict below`);
+      handled = true; break;
+    }
+
+    console.log('  ? unknown — type k, d, i, or s');
+  }
+}
+
 async function main() {
   await requireSession();
 
@@ -290,6 +466,32 @@ async function main() {
     process.exit(0);
   }
 
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const summary = { promoted: 0, discarded: 0, merged: 0, skipped: 0 };
+  const promotedIds = [];
+  const discardedIds = [];
+  const mergedIds = [];
+  let quit = false;
+
+  // BATCH CLUSTER PASS (task 1001465) — before the per-idea walk, so a
+  // near-duplicate group is offered ONE verdict instead of N. Runs on the RAW
+  // open-idea list (not yet ordered/filtered) since it operates on identity
+  // (kind + word overlap), not on the grade-based walk order below.
+  const { clusters, clusteredIds } = clusterIdeas(ideas);
+  if (clusters.length > 0) {
+    console.log(`\n🔗 ${clusters.length} likely-duplicate cluster${clusters.length === 1 ? '' : 's'} found (${clusteredIds.size} ideas) — batch verdict available before the individual walk.`);
+    const state = { summary, discardedIds, mergedIds };
+    for (const cluster of clusters) {
+      await handleCluster(rl, cluster, clusteredIds, state);
+    }
+  }
+  ideas = ideas.filter((i) => !clusteredIds.has(i.id));
+  if (ideas.length === 0) {
+    console.log('\nnothing left to walk individually — every open idea was resolved in a batch cluster verdict.');
+    rl.close();
+    process.exit(0);
+  }
+
   // WALK ORDER (task 1002924 / R148): Full Ideas first, best-formed first, then
   // quick ideas and sparks newest-first. Two runs rather than one score-sorted
   // list, for the reason render-ideas.js records: a single list sorted by score
@@ -298,14 +500,7 @@ async function main() {
   const { partition } = require('./render-ideas');
   const grouped = partition(ideas);
   ideas = grouped.openFull.concat(grouped.openRest);
-  console.log(`📥 ${ideas.length} open idea${ideas.length === 1 ? '' : 's'} to triage — ${grouped.openFull.length} Full Idea${grouped.openFull.length === 1 ? '' : 's'} first (best-formed first), then ${grouped.openRest.length} quick/spark (newest first).`);
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const summary = { promoted: 0, discarded: 0, merged: 0, skipped: 0 };
-  const promotedIds = [];
-  const discardedIds = [];
-  const mergedIds = [];
-  let quit = false;
+  console.log(`📥 ${ideas.length} open idea${ideas.length === 1 ? '' : 's'} to triage individually — ${grouped.openFull.length} Full Idea${grouped.openFull.length === 1 ? '' : 's'} first (best-formed first), then ${grouped.openRest.length} quick/spark (newest first).`);
 
   try {
     for (let i = 0; i < ideas.length && !quit; i++) {
@@ -475,4 +670,7 @@ module.exports = {
   parseDevelopment,
   loadDevelopment,
   formatDevelopment,
+  clusterIdeas,
+  significantWords,
+  jaccard,
 };

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.549'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.550'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

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);