@bongos/core 1.19.294 → 1.19.296

package/modules/ideas/inbox.js

@@ -782,6 +782,91 @@ async function countRoutedAwaitingNod(deps = {}) {
   return rows[0] ? rows[0].n : 0;
 }
 
+// -------------------------------------------------------------------------
+// The spark queue (task 1002921 / BV1.R145, goal 1000062)
+//
+// "What Big Idea Sparks are awaiting development?" — the ideator craft's pickup
+// surface, and the first place in this codebase where one craft sources work
+// from another craft's output.
+//
+// THE PREDICATE IS grade='spark' AND status='open', AND THAT IS THE WHOLE
+// QUEUE. There is deliberately no `developed` flag and no separate queue table:
+// R146 develops a spark into a Full Idea IN PLACE on the same idea_inbox row
+// (same id, same captured_by), which flips its grade spark→full — so a developed
+// spark leaves this queue as a CONSEQUENCE of being developed, not because
+// anything remembered to remove it. A second source of truth for "still
+// waiting" is a thing that can disagree with the grade; this cannot.
+//
+// AN INNER JOIN, WHICH INVERTS THIS MODULE'S USUAL RULE ON PURPOSE. Every other
+// idea read LEFT JOINs ideas_grades and COALESCEs to 'quick', because an
+// un-graded idea must still appear. Here the opposite is correct and safe:
+// grade='spark' can never be implicit — absence of a row means quick — so a
+// spark ALWAYS has a real row, and starting from ideas_grades lets
+// ideas_grades_grade_score_idx (ideas_001, written for this very read) drive the
+// scan instead of filtering a full idea_inbox pass afterwards.
+//
+// ORDERING — "newest-or-best first", and only the newest half is real. A spark
+// carries no completeness score by construction (it has no template fields to
+// score), so there is no "best" signal to sort by: upvotes live on builders as
+// karma, not per-idea, and inventing a quality metric for an undeveloped thought
+// is exactly the guess this queue should not be making. captured_at DESC, id
+// DESC as a stable tiebreak for same-timestamp rows. When a real per-idea
+// signal exists, this ORDER BY is the one line that changes.
+//
+// The skill-friction visibility gate (V3.R70) is applied here too, on the same
+// title-prefix rule listOpenIdeas uses. A routine-filed friction row is unlikely
+// to ever be sparked (marking requires an author), but the two idea listings
+// agreeing by construction beats them agreeing by accident.
+function sparkQueueWhere(viewerRank, params) {
+  const where = [`g.grade = 'spark'`, `i.status = 'open'`];
+  if (!rankCanSeeSkillFriction(viewerRank)) {
+    params.push(`${SKILL_FRICTION_TAG}%`);
+    where.push(`i.title NOT LIKE $${params.length}`);
+  }
+  return where;
+}
+
+async function listSparkQueue({ limit = 50, viewerRank = null } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const params = [];
+  const where = sparkQueueWhere(viewerRank, params);
+  params.push(limit);
+  const { rows } = await activePool.query(
+    // `b.github_login` because attribution is the POINT of this surface: an
+    // ideator picking work up should see whose thought they are developing, and
+    // R146 has to preserve that name. LEFT JOIN — a builder row can be missing.
+    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
+            b.github_login AS filed_by_login
+       FROM ideas_grades g
+       JOIN idea_inbox i ON i.id = g.idea_id
+       LEFT JOIN builders b ON b.id = i.captured_by
+      WHERE ${where.join(' AND ')}
+      ORDER BY i.captured_at DESC, i.id DESC
+      LIMIT $${params.length}`,
+    params
+  );
+  return rows;
+}
+
+// The count behind the queue's pill — the SAME predicate as the list (the
+// countRoutedAwaitingNod / countOpenIdeas precedent), so the number a viewer is
+// shown can never disagree with the rows they can actually see. It deliberately
+// takes viewerRank too: a count that ignored the visibility gate would tell a
+// Xenos there are sparks they cannot find.
+async function countSparkQueue({ viewerRank = null } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const params = [];
+  const where = sparkQueueWhere(viewerRank, params);
+  const { rows } = await activePool.query(
+    `SELECT COUNT(*)::int AS n
+       FROM ideas_grades g
+       JOIN idea_inbox i ON i.id = g.idea_id
+      WHERE ${where.join(' AND ')}`,
+    params
+  );
+  return rows[0] ? rows[0].n : 0;
+}
+
 // -------------------------------------------------------------------------
 // Grade writes (task 1002916 / BV1.R140)
 //
@@ -1109,6 +1194,9 @@ module.exports = {
   // the nod queue (task 1003066, BV1.R05)
   listRoutedAwaitingNod,
   countRoutedAwaitingNod,
+  // the spark queue (task 1002921, BV1.R145) — sparks awaiting development
+  listSparkQueue,
+  countSparkQueue,
   // criterion-proposal ratification (V3.R31 / #252)
   ratifyCriterionProposal,
   parseProposalBody,

package/modules/ideas/routes/inbox.js

@@ -312,6 +312,43 @@ module.exports = function buildInboxRouter() {
     }
   });
 
+
+  // GET /inbox/sparks — THE SPARK QUEUE (task 1002921 / BV1.R145, goal 1000062).
+  //
+  // Big Idea Sparks awaiting development: the ideator craft's pickup surface,
+  // and the first place one craft sources work from another craft's output.
+  //
+  // READABLE BY ANY BUILDER, by design and by the done-when. A pickup surface
+  // that only trusted builders could read would defeat its own purpose — the
+  // whole point is that someone OTHER than the author comes along and develops
+  // the thought. The author's consent is already recorded (the R144 mark is what
+  // put the row here), so no further gate belongs on the read. Contrast
+  // /inbox/awaiting-nod directly above, which IS gated: that queue exists to be
+  // ACTED on by a triager, this one to be BROWSED by anyone.
+  //
+  // DECLARED BEFORE `GET /inbox/:id` DELIBERATELY — and this ordering is
+  // load-bearing, not stylistic. Express matches in declaration order, so with
+  // the routes the other way round `/inbox/sparks` binds `:id = 'sparks'` and
+  // parseId turns the whole queue into a 400 bad_id. Same reason
+  // /inbox/awaiting-nod sits above it. tests/idea_spark_queue.mjs pins the
+  // relative order so a future insertion cannot quietly re-shadow it.
+  //
+  // rank: any-builder — a pickup surface is public to builders (the R144 mark is
+  // the consent). Deliberately NOT pinned in route-rank-check: a read with no
+  // gate to protect has no downgrade to catch, and pinning it would only assert
+  // that a read stays open.
+  router.get('/inbox/sparks', api.requireBuilder, api.asyncHandler('GET /inbox/sparks', async (req, res) => {
+    const limitRaw = Number(req.query.limit);
+    const limit = Number.isInteger(limitRaw) && limitRaw > 0 && limitRaw <= 100 ? limitRaw : 50;
+    // Both halves take the viewer's rank so the pill can never claim sparks the
+    // list will not show (the countRoutedAwaitingNod precedent).
+    const viewerRank = req.builder && req.builder.rank;
+    const [sparks, count] = await Promise.all([
+      inbox.listSparkQueue({ limit, viewerRank }),
+      inbox.countSparkQueue({ viewerRank }),
+    ]);
+    return res.json({ sparks, count });
+  }, { errorCode: 'spark_queue_failed' }));
   // rank: any-builder — single idea read for the "#NNN" deep-link resolver
   // (#1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but
   // the /inbox LIST returns only the open-first-50, so a closed/older idea ref
@@ -443,6 +480,119 @@ module.exports = function buildInboxRouter() {
     }
   });
 
+  // -----------------------------------------------------------------------
+  // The Big Idea Spark mark (task 1002920 / BV1.R144, goal 1000062)
+  //
+  // "I have the spark but not the full picture — someone develop this."
+  //
+  // AUTHOR-ONLY, AND THAT IS THE WHOLE POINT. The owner's decision: this mark IS
+  // the consent that makes cross-builder development fair. Without it a Quick
+  // Idea is simply NOT available for someone else to develop — a quick idea is
+  // for turning a thought into a task fast, and it is explicitly *not* an
+  // unfinished Full Idea waiting to be finished by a stranger. So the gate is
+  // not "who is senior enough", it is "whose thought is this": enforced
+  // in-handler against `captured_by`, the same ownership posture as
+  // POST /inbox/:id/resubmit above and PATCH /inbox/:id/body below.
+  //
+  // A MARK, MODELLED AS A RESOURCE: POST puts it on, DELETE takes it off. The
+  // done-when requires the mark be REVERSIBLE, and un-sparking is the plain
+  // reading of that — an author who marked a thought as needing development may
+  // decide they had the full picture after all. Un-sparking writes an EXPLICIT
+  // grade='quick' row, which the R140 design states reads identically to having
+  // no row at all, so a reversal leaves no residue a reader has to interpret.
+  //
+  // ONLY A QUICK IDEA CAN BE SPARKED. A Full Idea already carries the developed
+  // picture (the five template fields + a score); asking for it to be developed
+  // is a contradiction, and sparking it would hand setIdeaGrade a `spark` write
+  // whose empty fieldValues would WIPE that work — exactly the stale/lost-field
+  // hazard setIdeaGrade's whole-row contract warns about. Refused 409, before
+  // any write.
+  //
+  // Both directions are IDEMPOTENT: sparking a spark, or un-sparking a quick,
+  // reports `unchanged` at 200 rather than erroring. A double-click on the R154
+  // hall control is not a failure, and the caller's intent is already satisfied.
+  //
+  // rank: any-builder (requireBuilder) + the in-handler author gate.
+  // Pinned in route-rank-check.MODULE_EXPECTED_RANKS['ideas'].
+
+  // Shared by both directions: load the idea, prove ownership, and refuse a
+  // grade this mark has no business touching. Returns the idea, or null when it
+  // has already answered the request (so the caller just returns).
+  async function loadSparkable(req, res, { requireOpen }) {
+    const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
+    if (id === null) return null;
+    const idea = await inbox.getIdea(id);
+    if (!idea) { res.fail('idea_not_found', 404); return null; }
+    // Authority first, and it leaks nothing: any builder can already read this
+    // idea from the inbox, so a 403 here reveals only that they are not its author.
+    if (idea.captured_by == null || String(idea.captured_by) !== String(req.builder.id)) {
+      res.fail('not_your_idea', 403, {
+        reason: 'the spark mark is the AUTHOR\'s consent to have their idea developed; only they can give or withdraw it',
+      });
+      return null;
+    }
+    if (idea.grade === 'full') {
+      res.fail('not_a_quick_idea', 409, {
+        grade: idea.grade,
+        reason: 'a Full Idea already carries the developed picture; the spark mark asks for one',
+      });
+      return null;
+    }
+    // Only MARKING requires an open idea. A promoted or discarded idea is not
+    // awaiting development, and admitting it would seed the R145 spark queue
+    // with work nobody can pick up. WITHDRAWING the mark stays legal at any
+    // status — clearing a stale mark is housekeeping, and blocking it would be
+    // the one way to leave a permanent spark on a dead idea.
+    if (requireOpen && idea.status !== 'open') {
+      res.fail('idea_not_open', 409, {
+        status: idea.status,
+        reason: 'only an open idea can be marked as awaiting development',
+      });
+      return null;
+    }
+    return idea;
+  }
+
+  // Mark a Quick Idea as a Big Idea Spark — "I have the spark but not the full
+  // picture, someone develop this". AUTHOR-ONLY: the mark is the author's consent
+  // to have their idea developed, so only they can set it. A Full Idea is refused
+  // (409) and a non-open idea cannot be newly marked; re-marking is a 200 no-op.
+  router.post('/inbox/:id/spark', api.requireBuilder, api.asyncHandler('POST /inbox/:id/spark', async (req, res) => {
+    const idea = await loadSparkable(req, res, { requireOpen: true });
+    if (!idea) return;
+    if (idea.grade === 'spark') {
+      return res.json({ idea, sparked: true, unchanged: true });
+    }
+    // grade only — a spark carries no template fields and no score (the R140
+    // migration's own shape: field_values is for a Full Idea). setIdeaGrade's
+    // defaults say exactly that, so they are left to speak for themselves.
+    const row = await inbox.setIdeaGrade(idea.id, { grade: 'spark' });
+    return res.json({
+      idea: { ...idea, grade: row.grade, template_key: row.template_key, field_values: row.field_values, completeness_score: row.completeness_score },
+      sparked: true,
+      unchanged: false,
+    });
+  }, { errorCode: 'idea_spark_failed' }));
+
+  // Withdraw the Big Idea Spark mark — the reversibility half of R144. AUTHOR-ONLY
+  // like the mark itself, and legal at ANY status so a stale mark on a promoted or
+  // discarded idea can always be cleared. Writes an explicit grade='quick' row,
+  // which reads identically to no grade row at all. Un-marking a quick idea is a
+  // 200 no-op; a Full Idea is refused (409) — it is not a withdrawn spark.
+  router.delete('/inbox/:id/spark', api.requireBuilder, api.asyncHandler('DELETE /inbox/:id/spark', async (req, res) => {
+    const idea = await loadSparkable(req, res, { requireOpen: false });
+    if (!idea) return;
+    if (idea.grade !== 'spark') {
+      return res.json({ idea, sparked: false, unchanged: true });
+    }
+    const row = await inbox.setIdeaGrade(idea.id, { grade: 'quick' });
+    return res.json({
+      idea: { ...idea, grade: row.grade, template_key: row.template_key, field_values: row.field_values, completeness_score: row.completeness_score },
+      sparked: false,
+      unchanged: false,
+    });
+  }, { errorCode: 'idea_unspark_failed' }));
+
   // Metic+ (#360 / ADR 0018): idea triage (promote/discard/merge) shapes the
   // backlog. Criterion C2 assigns triage to Metic, so this widened from
   // archon-only to metic+archon when the three-rank model went live. Any

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.294",
+  "version": "1.19.296",
   "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/spark.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Mark one of YOUR OWN quick ideas as a Big Idea Spark — "I have the spark but
+// not the full picture, someone develop this" (task 1002920 / BV1.R144, goal
+// 1000062).
+//
+// The mark is the CONSENT that makes cross-builder development fair: until an
+// author sets it, their quick idea is not available for someone else to develop.
+// So this command only ever works on ideas you filed — the server enforces that
+// against idea_inbox.captured_by, and no rank can override it.
+//
+// It exists as its own command rather than a flag on capture.js because sparking
+// is an act on an EXISTING idea, not a way to file one (capture refuses
+// grade='spark' for the same reason). The builders-hall control is R154; this is
+// the terminal path, and the two hit the same route.
+//
+// --list is the other side of the same idea: the SPARK QUEUE (task 1002921 /
+// BV1.R145) — what other builders have marked as needing development. It lives
+// here rather than in its own script because "mark it" and "see what is marked"
+// are one mental model, and a queue nobody can read is not a pickup surface. The
+// queue is readable by ANY builder: the author's mark is already the consent.
+//
+// Usage:
+//   node scripts/gds/spark.js --list           # the spark queue: what awaits development
+//   node scripts/gds/spark.js --list --limit 10
+//   node scripts/gds/spark.js 123              # mark idea 123 as a spark
+//   node scripts/gds/spark.js 123 --undo       # withdraw the mark (back to quick)
+//
+// Exit codes:
+//   0  the idea now carries the grade you asked for (including when it already did)
+//   1  api / network error, or the server refused (not yours / not a quick idea)
+//   2  bad invocation
+
+const { cliClient, requireSession, hasFlag, arg, hallBase } = require('./cli-lib');
+
+// The server's refusals, in the ideator's own words. Anything unmapped falls
+// through to the raw envelope — a new server-side rule should be visible, not
+// swallowed by a generic "failed".
+const REFUSALS = {
+  not_your_idea: (d) =>
+    'That idea is not yours to mark. The spark mark is the author\'s consent to have their\n'
+    + 'idea developed, so only the builder who filed it can give or withdraw it.',
+  not_a_quick_idea: (d) =>
+    `That idea is already a Full Idea (grade=${d.grade || 'full'}). It carries the developed\n`
+    + 'picture the spark mark asks for — there is nothing to hand off.',
+  idea_not_open: (d) =>
+    `That idea is ${d.status || 'no longer open'}, so it is not awaiting development.\n`
+    + '(You can still withdraw an existing mark with --undo.)',
+  idea_not_found: () => 'No idea with that id.',
+};
+
+// The envelope is ADR 0116's { error: { code, message, details } } — the extras a
+// route passes as res.fail's third argument land under `details`, NOT spread onto
+// `error`. Reading them off the wrong level is a silent "undefined" in the
+// message rather than a crash, so tests/idea_spark_mark.mjs pins explain()
+// against the real envelope() builder.
+function explain(status, data) {
+  const err = data && data.error;
+  const code = err && typeof err === 'object' ? err.code : err;
+  const detail = (err && typeof err === 'object' && err.details) || {};
+  const say = typeof code === 'string' ? REFUSALS[code] : null;
+  if (say) return say(detail);
+  let rendered;
+  try { rendered = JSON.stringify(data, null, 2); } catch { rendered = String(data); }
+  return `spark failed (${status}): ${rendered}`;
+}
+
+// Render the queue. Kept separate from the fetch so it is testable without a
+// session, and so the empty case reads as an answer ("nothing is waiting")
+// rather than as a blank screen that looks like a failure.
+function renderQueue({ sparks, count }) {
+  const lines = [];
+  if (!sparks || sparks.length === 0) {
+    lines.push('No sparks are awaiting development.');
+    lines.push('A spark is a quick idea whose AUTHOR marked it as needing development —');
+    lines.push('mark one of your own with: node scripts/gds/spark.js <idea-id>');
+    return lines.join('\n');
+  }
+  const shown = sparks.length;
+  const total = Number.isInteger(count) ? count : shown;
+  lines.push(`${total} spark${total === 1 ? '' : 's'} awaiting development${shown < total ? ` (showing ${shown})` : ''}:`);
+  lines.push('');
+  for (const s of sparks) {
+    // The hall link, never a bare "#NNN" — that autolinks to a GitHub issue and
+    // 404s, since our idea ids are not GitHub's (the CLAUDE.md refs rule).
+    lines.push(`  ${hallBase()}/#/idea/${s.id}`);
+    lines.push(`    ${s.title}`);
+    const who = s.filed_by_login ? `@${s.filed_by_login}` : 'an unnamed builder';
+    lines.push(`    had by ${who}${s.captured_at ? ` · ${String(s.captured_at).slice(0, 10)}` : ''}`);
+    lines.push('');
+  }
+  lines.push('Develop one into a Full Idea and the author keeps the attribution.');
+  return lines.join('\n');
+}
+
+async function listQueue() {
+  const api = await cliClient();
+  const limitRaw = arg('--limit');
+  const limit = limitRaw != null && /^[0-9]+$/.test(limitRaw) ? Number(limitRaw) : null;
+  const r = await api.inbox.getInboxSparks(limit ? { query: { limit } } : {});
+  if (!r.ok) {
+    console.error(explain(r.status, r.data));
+    process.exit(1);
+  }
+  console.log(renderQueue(r.data || {}));
+}
+
+async function main() {
+  await requireSession();
+
+  if (hasFlag('--list')) return listQueue();
+
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith('-'));
+  const id = Number(positional[0]);
+  const undo = hasFlag('--undo');
+
+  if (!Number.isInteger(id) || id <= 0) {
+    console.error('usage: node scripts/gds/spark.js <idea-id> [--undo]');
+    console.error('       node scripts/gds/spark.js --list [--limit N]');
+    process.exit(2);
+  }
+
+  const api = await cliClient();
+  const r = undo
+    ? await api.inbox.deleteInboxIdSpark({ id })
+    : await api.inbox.postInboxIdSpark({ id, body: {} });
+
+  if (!r.ok) {
+    console.error(explain(r.status, r.data));
+    process.exit(1);
+  }
+
+  const { idea, sparked, unchanged } = r.data;
+  const title = idea && idea.title ? ` — ${idea.title}` : '';
+  if (unchanged) {
+    console.log(`Idea ${id} was already ${sparked ? 'a spark' : 'a quick idea'}${title}. Nothing changed.`);
+  } else if (sparked) {
+    console.log(`Idea ${id} is now a Big Idea Spark${title}.`);
+    console.log('Another builder can develop it into a Full Idea; you keep the attribution.');
+  } else {
+    console.log(`Idea ${id} is a quick idea again${title}. The mark is withdrawn.`);
+  }
+}
+
+// explain() and renderQueue() are exported because both are pinned by tests —
+// explain against the real envelope shape, renderQueue for the empty case and the
+// hall-link form. REFUSALS stays private: it is the message table, reachable
+// through explain(), and a third export would be dead surface.
+module.exports = { explain, renderQueue };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}

package/src/bongos/route-rank-check.js

@@ -416,6 +416,15 @@ const MODULE_EXPECTED_RANKS = {
     // requireBuilder + an in-handler author|triage gate. Deliberately a separate
     // route from the triage-gated PATCH /inbox/:id, which keeps its own rank.
     'PATCH /inbox/:id/body': 'any-builder',
+    // task 1002920 (BV1.R144): the Big Idea Spark mark is AUTHOR-ONLY, which is a
+    // narrower rule than any rank expresses — the gate is "whose thought is this",
+    // enforced in-handler against captured_by. Pinned 'any-builder' for the same
+    // reason POST /goals/:id/members is: the pin's job here is to catch an
+    // accidental TIGHTENING to a rank floor (which would lock authors out of their
+    // own ideas and break the consent the mark exists to record) as loudly as it
+    // catches a gate being dropped.
+    'POST /inbox/:id/spark': 'any-builder',
+    'DELETE /inbox/:id/spark': 'any-builder',
     'POST /inbox/:id/ratify': 'perm:idea.ratify',
   },
   // Cross-builder memory READS — the counterpart to the BFG cross-builder WRITE the

package/src/module-api.js

@@ -1015,8 +1015,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.292 with no explicit bump. run 32586174253. (task 1002620)
 //   1.19.294 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.293 with no explicit bump. run 32588977219. (task 1002620)
+//   1.19.295 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.294 with no explicit bump. run 32590508145. (task 1002620)
+//   1.19.296 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.295 with no explicit bump. run 32591155887. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.294'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.296'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');