@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/triage.js

@@ -0,0 +1,742 @@
+#!/usr/bin/env node
+// /builder-triage — walk every open idea_inbox row and verdict it
+// one-at-a-time. The structural cure for the markdown-graveyard pattern:
+// if the inbox never gets walked, it dies; if it gets walked daily (or at
+// session-end), each idea lives at most ~24h before becoming a task,
+// a duplicate marker, or a discarded row.
+//
+// Usage:
+//   node scripts/bongos/triage.js
+//   node scripts/bongos/triage.js --development <path>   (or env OTB_IDEA_DEVELOPMENT)
+//
+// --development <path> loads a "development cache" — a JSON blob the
+// /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',
+//                      reviewed_at=now, promoted_to_task_id=<new>
+//   [m]erge with #N  → mark idea 'merged' with merged_into_idea_id=N
+//                      (N is the canonical IDEA to keep). The body remains
+//                      on the merged idea row for history — there is no
+//                      description-append vector, so nothing is copied to N.
+//   [d]iscard        → mark idea 'discarded', reviewed_at=now
+//   [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
+//   2  no session
+
+const readline = require('node:readline');
+const fs = require('node:fs');
+const { cliClient, requireSession } = require('./cli-lib');
+const { resolveDefaultVersion } = require('./version-select.js');
+const { resolveWriteDiscipline } = require('../../modules/lifecycle/task-classifier.js');
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, (a) => resolve(a)));
+}
+
+function trim(s, n) {
+  if (!s) return '';
+  return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+
+// ── development cache ────────────────────────────────────────────────────────
+// The /idea-triage skill spawns one subagent per open idea (in parallel with
+// the walk) to flesh it out, then writes the results here. Shape (both forms
+// accepted): {"generated_at":"…","ideas":{"<id>":<block>}}  OR  a bare array
+// [{"idea_id":<id>, …block}]. A block is:
+//   { summary, integration_surfaces[], open_questions[], challenges[],
+//     risks[], rough_effort, recommendation }
+// All fields optional — we render whatever is present.
+
+function resolveDevelopmentPath(argv = process.argv, env = process.env) {
+  const i = argv.indexOf('--development');
+  if (i !== -1 && argv[i + 1]) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith('--development='));
+  if (eq) return eq.slice('--development='.length);
+  return env.OTB_IDEA_DEVELOPMENT || null;
+}
+
+// Parse a development cache (already-read JSON text) into a Map keyed by
+// string idea id. Tolerant of both the object-map and the bare-array form,
+// and of junk (returns an empty Map rather than throwing).
+function parseDevelopment(text) {
+  const out = new Map();
+  if (!text || !text.trim()) return out;
+  let doc;
+  try { doc = JSON.parse(text); } catch { return out; }
+  let entries = [];
+  if (Array.isArray(doc)) {
+    entries = doc.map((b) => [b && (b.idea_id ?? b.id), b]);
+  } else if (doc && typeof doc === 'object' && doc.ideas && typeof doc.ideas === 'object') {
+    entries = Object.entries(doc.ideas);
+  } else if (doc && typeof doc === 'object') {
+    // Last-resort: a bare {"<id>": block} map.
+    entries = Object.entries(doc);
+  }
+  for (const [k, block] of entries) {
+    if (k == null || !block || typeof block !== 'object') continue;
+    out.set(String(k), block);
+  }
+  return out;
+}
+
+// Read + parse a development cache from disk. Missing/unreadable file → empty
+// Map (the walk simply proceeds without developed blocks).
+function loadDevelopment(path) {
+  if (!path) return new Map();
+  let text;
+  try { text = fs.readFileSync(path, 'utf8'); }
+  catch { return new Map(); }
+  return parseDevelopment(text);
+}
+
+function bullets(label, arr) {
+  if (!Array.isArray(arr) || arr.length === 0) return [];
+  const lines = [`  ${label}:`];
+  for (const item of arr) {
+    if (item == null || String(item).trim() === '') continue;
+    lines.push(`    • ${String(item).trim()}`);
+  }
+  return lines.length > 1 ? lines : [];
+}
+
+// Render a developed block for the terminal. Returns '' if the block is empty.
+function formatDevelopment(block) {
+  if (!block || typeof block !== 'object') return '';
+  const sep = '  ' + '┄'.repeat(70);
+  const lines = [sep, '  ▸ developed by idea-triage subagent'];
+  if (block.summary) lines.push(`  summary: ${String(block.summary).trim()}`);
+  if (Array.isArray(block.integration_surfaces) && block.integration_surfaces.length) {
+    lines.push(`  surfaces: ${block.integration_surfaces.map((s) => String(s).trim()).filter(Boolean).join(', ')}`);
+  }
+  lines.push(...bullets('open questions', block.open_questions));
+  lines.push(...bullets('challenges', block.challenges));
+  lines.push(...bullets('risks', block.risks));
+  const footer = [];
+  if (block.rough_effort) footer.push(`effort: ${String(block.rough_effort).trim()}`);
+  if (block.recommendation) footer.push(`recommendation: ${String(block.recommendation).trim()}`);
+  if (footer.length) lines.push(`  ${footer.join('    ')}`);
+  // Nothing but the header/sep → treat as empty.
+  if (lines.length <= 2) return '';
+  lines.push(sep);
+  return lines.join('\n');
+}
+
+async function listOpenIdeas() {
+  const api = await cliClient();
+  const r = await api.inbox.getInbox({ query: { status: 'open', limit: 500 } });
+  // GET /inbox in routes/inbox.js only returns open ideas regardless of
+  // query — but the explicit param is forward-safe.
+  if (!r.ok) {
+    throw new Error(`GET /api/bongos/inbox failed: ${r.status} ${JSON.stringify(r.data)}`);
+  }
+  return r.data?.ideas ?? [];
+}
+
+async function patchIdea(id, patch) {
+  const api = await cliClient();
+  const r = await api.inbox.patchInboxId({ id, body: patch });
+  if (!r.ok) {
+    throw new Error(`PATCH /api/bongos/inbox/${id} failed: ${r.status} ${JSON.stringify(r.data)}`);
+  }
+  return r.data?.idea;
+}
+
+// resolveGoalDefault — what goal should a triaged promotion land in? (task
+// 1003071 / R13.)
+//
+// PRECEDENCE IS DELIBERATE:
+//   1. `idea.suggested_goal_id` — the STORED hint. inbox.captureIdea writes it
+//      even when the matrix declined to route, precisely so "/idea-triage
+//      inherits the guess instead of re-deriving it" (core_222, its own comment).
+//      A human or a filing surface already named this goal; a heuristic must not
+//      overrule that.
+//   2. the R07 suggester (GET /goals/suggestions) — only when there is no hint.
+//      Best-scoring candidate, and its score/matched_terms are shown so the
+//      operator can see WHY before accepting.
+// Returns { goalId, label, source } — goalId null when neither yields anything.
+// The caller prints `source` as provenance, because "the suggester guessed this"
+// and "the filing already named this" deserve different trust. Never throws: a
+// suggester outage degrades to "no default", it does not block a triage verdict.
+//
+// `client` is injectable so the precedence can be driven end-to-end in a test
+// rather than pattern-matched in the source. (Task 1003102 shipped a handler
+// whose collaborators were not injectable; its tests read the source, passed,
+// and the route 500'd on every call. Not repeating that.)
+async function resolveGoalDefault(idea, versionId, { client = cliClient } = {}) {
+  // Guarded: a junk stored value must not become goalId NaN and then a goal_id
+  // the server rejects with 400 on every retry.
+  const hint = Number(idea.suggested_goal_id);
+  if (Number.isInteger(hint) && hint > 0) {
+    return { goalId: hint, label: `goal ${hint}`, source: 'hint' };
+  }
+  try {
+    const api = await client();
+    // The GENERATED typed method (regenerated when R07 landed), not the generic
+    // request() escape hatch — so a path or param rename reds the client build.
+    const r = await api.goals.getGoalsSuggestions({
+      query: { version: versionId, title: idea.title || '', body: (idea.body_md || '').slice(0, 2000), limit: 3 },
+    });
+    const top = r.ok && r.data && Array.isArray(r.data.suggestions) ? r.data.suggestions[0] : null;
+    if (!top) return { goalId: null, label: null, source: 'none' };
+    const why = (top.matched_terms || []).join('/');
+    return { goalId: Number(top.id), label: `${top.id} ${trim(top.title, 44)} (score ${top.score}${why ? ' · ' + why : ''})`, source: 'suggester' };
+  } catch (_) {
+    return { goalId: null, label: null, source: 'unavailable' };
+  }
+}
+
+// What the operator's answer to the goal prompt means. Blank ACCEPTS the shown
+// default — declining has to be said ('-' or 'none'), because silently dropping a
+// real default on a bare Enter is how work ends up in the general bucket by
+// accident. Declining is legal: the server then applies the catch-all itself.
+// applyGoalAnswer — read the operator's goal answer at the triage prompt.
+//
+// BV1.R22 (task 1003609, goal 1000086): THE GENERAL BUCKET IS GONE. Every branch
+// that used to resolve to `goalId: null` did so because a goal-less create fell
+// into the version's catch-all "<version> — general" goal. R11 (task 1003598)
+// deleted that fallback and made `goal_id` required, so `null` is no longer an
+// opt-out — it is a `400 goal_id_required` from the server, arriving after the
+// operator has typed a title, a description and a priority, and losing all of it.
+//
+// So the two escapes become refusals, and they refuse HERE, before the round trip:
+//   '-' / 'none'  — was "file it in the general bucket"; there is no bucket.
+//   a junk answer — was silently downgraded to the bucket with a warning, which
+//                   is the worse of the two: a typo'd goal id read as a decision.
+//
+// `ok: false` means re-ask. The caller loops rather than aborting the whole
+// triage run, because the operator's other answers are still good.
+function applyGoalAnswer(defaultGoalId, rawAnswer) {
+  const answer = String(rawAnswer == null ? '' : rawAnswer).trim();
+  if (answer === '') {
+    return defaultGoalId != null
+      ? { ok: true, goalId: defaultGoalId, warn: null }
+      : { ok: false, goalId: null, warn: 'a goal is required — every task belongs to one. Enter a goal id (GET /goals?version=<id> lists them), or "s" to skip this idea.' };
+  }
+  if (answer === '-' || answer.toLowerCase() === 'none') {
+    return { ok: false, goalId: null, warn: 'the version\'s "general" catch-all no longer exists (task 1003598) — a task must name a real goal. Enter a goal id, or "s" to skip this idea.' };
+  }
+  const parsed = Number(answer);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    return { ok: false, goalId: null, warn: `"${answer}" is not a goal id. Enter a number, or "s" to skip this idea.` };
+  }
+  return { ok: true, goalId: parsed, warn: null };
+}
+
+async function createTask({ versionId, title, description, priority, sourceRef, goalId = null }) {
+  // (The old note here said POST /api/bongos/tasks does not accept 'kind'. That is
+  // no longer true — routes/tasks.js takes it, and the hall promote path already
+  // sends it. Left un-sent from THIS path deliberately: changing what kind a
+  // triaged promotion lands with is a behaviour change task R13 was not asked to
+  // make, and the server classifier still runs. Corrected rather than deleted so
+  // the next reader does not re-derive it.)
+  //
+  // task 1003071 (R13) named the goal here; BV1.R22 (task 1003609) makes it
+  // MANDATORY. R11 (task 1003598) deleted the "<version> — general" catch-all that
+  // a goal-less create used to fall into, so omitting goal_id is now a server
+  // `400 goal_id_required` rather than a quiet mis-filing. Reaching this function
+  // without one is a bug in the caller, and it throws rather than posting: the
+  // prompt above re-asks until it has a real id, so the only way here with null is
+  // a new call site that forgot — which should fail at its author, not in prod.
+  const body = {
+    version_id: versionId,
+    title,
+    description,
+    status: 'backlog',
+    priority: priority ?? null,
+    source: 'idea_inbox',
+    source_ref: sourceRef ?? null,
+    // task 1002988: the server now refuses a task whose craft it cannot infer, and
+    // a 400 in the middle of an interactive triage loop would cost the operator the
+    // promotion they just decided on. So resolve it here with the SAME function the
+    // server uses, and name a fallback rather than letting the loop break — the
+    // identical trade modules/ideas/inbox.js makes for capture.
+    discipline: resolveWriteDiscipline({ title, description }).discipline || 'engineer',
+  };
+  if (goalId == null) {
+    throw new Error('createTask: goal_id is required — every task belongs to a goal (task 1003598 deleted the catch-all fallback).');
+  }
+  body.goal_id = Number(goalId);
+  const api = await cliClient();
+  const r = await api.tasks.postTasks({ body });
+  if (!r.ok) {
+    throw new Error(`POST /api/bongos/tasks failed: ${r.status} ${JSON.stringify(r.data)}`);
+  }
+  return r.data?.task;
+}
+
+// The grade, spelled out (task 1002924 / BV1.R148). Reused from render-ideas.js
+// rather than restated so the two triage surfaces cannot describe the same idea
+// differently — the whole point of a grade at a glance is that it reads the same
+// everywhere.
+const { gradeLabel } = require('./render-ideas');
+
+function printIdea(idea, idx, total) {
+  const sep = '─'.repeat(72);
+  console.log(`\n${sep}`);
+  // The grade leads the line: it decides what kind of verdict this idea needs at
+  // all (a Full Idea gets a recommended shape — R149; a quick one promotes
+  // straight to a task), so a triager should not have to hunt for it.
+  console.log(`Idea ${idx + 1}/${total}  #${idea.id}  [${gradeLabel(idea)}]  kind=${idea.kind || '—'}  suggested_version=${idea.suggested_version || '—'}  priority=${idea.suggested_priority ?? '—'}`);
+  console.log(`Captured: ${idea.captured_at}  by builder #${idea.captured_by ?? '—'}`);
+  console.log(`Title:    ${idea.title}`);
+  if (idea.body_md && idea.body_md.trim()) {
+    console.log('');
+    console.log(idea.body_md);
+  }
+  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 records so a walk can offer one batch verdict per
+// group instead of re-litigating each member individually. Heuristic, not
+// semantic: two records cluster only when `kindOf` agrees (a bug and a
+// feature asking the same underlying question are not the same triage
+// decision) AND `textOf`'s word sets clear both a minimum SHARED-word floor
+// and a Jaccard similarity threshold — the floor stops two long, unrelated
+// records from clustering on a borderline ratio built from a single
+// coincidental word. Pure (no I/O, no randomness, nothing mutated) — directly
+// unit-testable; the interactive merge/discard/skip choice lives in each
+// caller's own walk. Returns { clusters, clusteredIds }: clusters is an array
+// of record-arrays (each length >= 2, sorted oldest-`timeOf`-first — the
+// natural "keep this one" default), clusteredIds is a Set of every id (by
+// `.id`) inside some cluster.
+//
+// Extracted from the idea-only `clusterIdeas` below (task 1001478) so
+// /bug-triage's kind=bug tasks can reuse the same union-find/Jaccard core
+// against `description`/`created_at` instead of `body_md`/`captured_at` —
+// duplicating the algorithm would be the one thing worth avoiding twice.
+function clusterRecords(records, { textOf, kindOf, timeOf, threshold = 0.34, minShared = 2 }) {
+  const words = records.map((r) => significantWords(textOf(r)));
+  const kinds = records.map((r) => kindOf(r));
+  const n = records.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 (kinds[i] !== kinds[j]) 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(records[i]);
+  }
+  const clusters = [];
+  const clusteredIds = new Set();
+  for (const members of groups.values()) {
+    if (members.length < 2) continue;
+    members.sort((a, b) => timeOf(a) - timeOf(b));
+    clusters.push(members);
+    for (const m of members) clusteredIds.add(m.id);
+  }
+  return { clusters, clusteredIds };
+}
+
+// The idea-shaped call: Full Ideas are never eligible (they get their own
+// shape recommendation, SKILL.md Step 2.5, and batching one away would skip
+// that judgment), nor are sparks (not triage's to convert, SKILL.md); the rest
+// cluster on title+body_md / kind / captured_at. Same signature as before the
+// clusterRecords extraction.
+const NON_CLUSTER_GRADES = new Set(['full', 'spark']);
+function clusterIdeas(ideas, { threshold = 0.34, minShared = 2 } = {}) {
+  const eligible = ideas.filter((i) => !NON_CLUSTER_GRADES.has(i.grade || 'quick'));
+  return clusterRecords(eligible, {
+    textOf: (i) => `${i.title || ''} ${i.body_md || ''}`,
+    kindOf: (i) => i.kind || null,
+    timeOf: (i) => new Date(i.captured_at),
+    threshold, minShared,
+  });
+}
+
+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 === '') { state.summary.skipped += cluster.length; 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 (/^k(eep)?(\s|#|$)/.test(ans)) {
+      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();
+
+  const devPath = resolveDevelopmentPath();
+  const development = loadDevelopment(devPath);
+  if (devPath) {
+    console.log(development.size > 0
+      ? `🧪 development cache: ${development.size} developed idea${development.size === 1 ? '' : 's'} from ${devPath}`
+      : `🧪 development cache: none found at ${devPath} (walking without developed blocks)`);
+  }
+
+  let ideas;
+  try {
+    ideas = await listOpenIdeas();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (ideas.length === 0) {
+    console.log('inbox empty — nothing to triage.');
+    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);
+    }
+  }
+  // Cluster verdicts bump the summary too, but those ideas are already out of
+  // `ideas`; remember the tally so "unseen" only counts the individual walk.
+  const clusterHandled = summary.promoted + summary.discarded + summary.merged + summary.skipped;
+  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
+  // puts every unscored idea after every scored one, and in a long inbox nobody
+  // reaches them. Grouping gives each kind its own top.
+  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 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++) {
+      const idea = ideas[i];
+      printIdea(idea, i, ideas.length);
+
+      const devBlock = development.get(String(idea.id));
+      if (devBlock) {
+        const rendered = formatDevelopment(devBlock);
+        if (rendered) console.log(rendered);
+      }
+
+      let handled = false;
+      while (!handled) {
+        const ans = (await prompt(rl, '[p]romote / [m]erge / [d]iscard / [s]kip / [q]uit > ')).trim().toLowerCase();
+
+        if (ans === 'q' || ans === 'quit') {
+          quit = true;
+          handled = true;
+          break;
+        }
+
+        if (ans === 's' || ans === 'skip' || ans === '') {
+          summary.skipped++;
+          handled = true;
+          break;
+        }
+
+        if (ans === 'd' || ans === 'discard') {
+          const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+          try {
+            await patchIdea(idea.id, { status: 'discarded', reviewed_at: new Date().toISOString() });
+            summary.discarded++;
+            discardedIds.push(idea.id);
+            console.log(`  ✖ discarded #${idea.id}${reason ? ` — ${trim(reason, 60)}` : ''}`);
+          } catch (err) {
+            console.error(`  ! ${err.message}`);
+          }
+          handled = true;
+          break;
+        }
+
+        if (/^m(erge)?(\s|#|$)/.test(ans)) {
+          // Accept "m 12" or "m #12" inline, otherwise prompt.
+          let target = null;
+          const inline = ans.replace(/^m(erge)?(\s|#)*/, '').trim();
+          if (inline) target = Number(inline.replace(/^#/, ''));
+          if (!Number.isFinite(target) || target <= 0) {
+            const a = (await prompt(rl, '  merge into idea #: ')).trim().replace(/^#/, '');
+            target = Number(a);
+          }
+          if (!Number.isFinite(target) || target <= 0) {
+            console.log('  ! bad id; skipping');
+            handled = false;
+            continue;
+          }
+          try {
+            // task 1002447 / migration core_195: the merge target belongs in
+            // merged_into_idea_id. This used to write promoted_to_task_id — a
+            // column that is REFERENCES tasks(id), so an idea id there either
+            // tripped the FK or silently named an unrelated task.
+            await patchIdea(idea.id, {
+              status: 'merged',
+              merged_into_idea_id: target,
+              reviewed_at: new Date().toISOString(),
+            });
+            summary.merged++;
+            mergedIds.push(idea.id);
+            console.log(`  ⇢ merged #${idea.id} → #${target}`);
+            console.log(`    (note: idea body preserved on the merged row; PATCH /tasks/:id does not currently support description-append)`);
+          } catch (err) {
+            console.error(`  ! ${err.message}`);
+          }
+          handled = true;
+          break;
+        }
+
+        if (ans === 'p' || ans === 'promote') {
+          // Promote: version, priority, title, goal — each defaulted from the idea.
+          // task 1003166 (G02): the fallback was 'PMS-V2', which has shipped —
+          // promoting into it would have been refused as version_closed.
+          const defaultVersion = idea.suggested_version || await resolveDefaultVersion();
+          const versionAns = (await prompt(rl, `  version [${defaultVersion}]: `)).trim();
+          const versionId = versionAns || defaultVersion;
+
+          const defaultPriority = idea.suggested_priority ?? 3;
+          const priorityAns = (await prompt(rl, `  priority [${defaultPriority}]: `)).trim();
+          const priority = priorityAns === '' ? defaultPriority : Number(priorityAns);
+
+          const titleAns = (await prompt(rl, `  title [${trim(idea.title, 60)}]: `)).trim();
+          const title = titleAns || idea.title;
+
+          // task 1003071 (R13): a triaged promotion NAMES its goal. The default
+          // comes from the stored hint, else the R07 suggester. The EFFECTIVE
+          // title, not idea.title: the suggester matches on title terms, and the
+          // operator may just have retitled this.
+          //
+          // BV1.R22 (task 1003609): the opt-out is gone, so this RE-ASKS instead of
+          // falling through. Skipping is still available and is now spelled 's' —
+          // it leaves the idea open for the next pass rather than filing it
+          // somewhere it does not belong, which is what the general bucket was.
+          const gd = await resolveGoalDefault({ ...idea, title }, versionId);
+          if (gd.source === 'suggester') console.log(`  suggested goal: ${gd.label}`);
+          if (gd.source === 'unavailable') console.log('  (goal suggester unreachable — enter a goal id yourself; GET /goals?version=<id> lists them)');
+          let goalId = null;
+          let skipIdea = false;
+          for (;;) {
+            const goalPrompt = gd.goalId != null
+              ? `  goal [${gd.goalId}] ("s" to skip this idea): `
+              : '  goal id ("s" to skip this idea): ';
+            const goalAns = (await prompt(rl, goalPrompt)).trim();
+            if (goalAns.toLowerCase() === 's') { skipIdea = true; break; }
+            const picked = applyGoalAnswer(gd.goalId, goalAns);
+            if (picked.ok) { goalId = picked.goalId; break; }
+            console.log(`  ! ${picked.warn}`);
+          }
+          if (skipIdea) { console.log('  – skipped (still open in the inbox)'); summary.skipped++; continue; }
+
+          try {
+            const task = await createTask({
+              versionId,
+              title,
+              description: idea.body_md || '',
+              priority: Number.isFinite(priority) ? priority : null,
+              sourceRef: `idea:${idea.id}`,
+              goalId,
+            });
+            await patchIdea(idea.id, {
+              status: 'promoted',
+              promoted_to_task_id: task.id,
+              reviewed_at: new Date().toISOString(),
+            });
+            summary.promoted++;
+            promotedIds.push({ ideaId: idea.id, taskId: task.id });
+            console.log(`  ✓ promoted #${idea.id} → task #${task.id} (${versionId}, P${priority}, goal ${goalId})`);
+          } catch (err) {
+            console.error(`  ! ${err.message}`);
+          }
+          handled = true;
+          break;
+        }
+
+        console.log('  ? unknown — type p, m, d, s, or q');
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  const walked = summary.promoted + summary.discarded + summary.merged + summary.skipped - clusterHandled;
+  const remaining = ideas.length - walked;
+
+  console.log('\n' + '═'.repeat(72));
+  console.log(`triage complete: ${summary.promoted} promoted, ${summary.discarded} discarded, ${summary.merged} merged, ${summary.skipped} skipped${remaining > 0 ? `, ${remaining} unseen (quit early)` : ''}`);
+  if (promotedIds.length) {
+    console.log(`  promoted: ${promotedIds.map((p) => `idea#${p.ideaId}→task#${p.taskId}`).join(', ')}`);
+  }
+  if (discardedIds.length) console.log(`  discarded: ${discardedIds.map((id) => `#${id}`).join(', ')}`);
+  if (mergedIds.length) console.log(`  merged:    ${mergedIds.map((id) => `#${id}`).join(', ')}`);
+
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  resolveGoalDefault,
+  applyGoalAnswer,
+  createTask,
+  resolveDevelopmentPath,
+  parseDevelopment,
+  loadDevelopment,
+  formatDevelopment,
+  clusterIdeas,
+  handleCluster,
+  clusterRecords,
+  significantWords,
+  jaccard,
+};