@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/smoke-write.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# GDS write-path smoke test (production). Renamed from PMS in V3.R01.
+#
+# Exercises the full claim → ship round-trip against the live API:
+#   1. Read session token from ~/.config/otb/bongos-session.json (or the legacy
+#      gds-session.json / pms-session.json names, all still accepted on read)
+#   2. POST /api/bongos/tasks → create a synthetic task titled '__smoke__ <ts>'
+#   3. POST /api/bongos/claims → claim it
+#   4. POST /api/bongos/claims/:id/resolve outcome=shipped
+#   5. Validate: tasks.status flipped to 'shipped'
+#                session_logs row exists for this claim
+#                public/recent-shipped does NOT contain the smoke title
+#                public/progress weighting unchanged (smoke tasks filtered)
+#   6. On PASS, abandon the throwaway task so the ledger does not refill with
+#      test noise (task 1002018). A FAILED run deliberately KEEPS its task and
+#      claim so the failure can be read from the ledger afterwards.
+#
+# The synthetic task has credits_reward=0 so no credit_log row is written
+# and the leaderboard is unaffected. The credit-award path is implicitly
+# validated by every real /builder-ship in production.
+#
+# Usage:
+#   bash scripts/bongos/smoke-write.sh
+# Optional env:
+#   GDS_API_BASE / PMS_API_BASE  override the API host (default: this instance's own,
+#                                resolved from the session + branding pack — see lib.sh)
+
+set -euo pipefail
+
+# shellcheck source=scripts/bongos/lib.sh
+source "$(dirname "$0")/lib.sh"
+
+API="$(gds_api_base)"
+TOKEN="$(gds_resolve_token)" || exit $?
+
+ts=$(date +%Y%m%d-%H%M%S)
+SMOKE_TITLE="__smoke__ write-path ${ts}"
+
+call() {
+  # call METHOD PATH [BODY] → echoes JSON, exits non-zero if HTTP non-2xx
+  local method="$1" path="$2" body="${3:-}"
+  local args=(-sS -X "${method}" -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -w "\n%{http_code}")
+  if [[ -n "${body}" ]]; then args+=(-d "${body}"); fi
+  local out
+  out=$(curl "${args[@]}" "${API}${path}")
+  local code="${out##*$'\n'}"
+  local payload="${out%$'\n'*}"
+  echo "${payload}"
+  if [[ "${code}" -ge 300 ]]; then
+    echo "FAIL: ${method} ${path} → HTTP ${code}" >&2
+    return 1
+  fi
+}
+
+snapshot_progress() {
+  curl -sS "${API}/api/bongos/public/progress" \
+    | python3 -c "import json,sys; d=json.load(sys.stdin); print(','.join(f\"{r['version_id']}:{r['shipped_weight']}/{r['total_weight']}\" for r in d['progress']))"
+}
+
+echo "=== GDS write-path smoke test ==="
+echo "API: ${API}"
+echo "Title: ${SMOKE_TITLE}"
+echo
+
+# task 1003166 (G02): resolve the version at RUNTIME. This file used to hardcode
+# one; that version shipped, `version_closed` refused every create, and the smoke
+# could not pass while /merge-mode still advertised it green (idea 1000823).
+VERSION_ID=$(node "$(dirname "$0")/version-select.js") || {
+  echo "FAIL: could not resolve a building version — see version-select.js" >&2
+  exit 1
+}
+echo "Version: ${VERSION_ID}"
+
+# Caused by task 1003598 (BV1.R11, ADR 0250 D4), found and fixed under task
+# 1002018: goal_id became REQUIRED on POST /tasks and this script still sent none, so step 1 died on a 400 goal_id_required
+# and the whole smoke could not run. Resolved at RUNTIME, not hardcoded, for the
+# same reason version-select.js exists (task 1003166): an id literal goes stale
+# the moment the version rolls, and the failure then looks like a broken API
+# rather than a stale constant. Every version auto-creates exactly ONE
+# is_maintenance goal (BV1.R18), and a synthetic row is maintenance-goal work.
+#
+# node, not python3, on purpose: this script already shells out to node for
+# version-select.js, and node is the interpreter a Windows builder box actually
+# has — the python3 the rest of this file depends on is frequently absent there
+# (it is the Microsoft Store stub), so a python3 step cannot be verified locally.
+GOAL_ID=$(call GET "/api/bongos/goals?version=${VERSION_ID}" | node -e '
+let s = "";
+process.stdin.on("data", (d) => { s += d; });
+process.stdin.on("end", () => {
+  const goals = JSON.parse(s).goals || [];
+  const m = goals.filter((g) => g.is_maintenance && g.status === "open");
+  if (m.length !== 1) {
+    process.stderr.write("expected exactly 1 open maintenance goal, found " + m.length + "\n");
+    process.exit(1);
+  }
+  // The caller splices this straight into a python3 -c SOURCE string, unquoted,
+  // so a non-numeric id would be executed as Python rather than read as data.
+  // Validating the COUNT is not validating the ID: check its shape too.
+  const id = String(m[0].id);
+  if (!/^[0-9]+$/.test(id)) {
+    process.stderr.write("goal id is not numeric: " + JSON.stringify(id) + "\n");
+    process.exit(1);
+  }
+  process.stdout.write(id);
+});
+') || {
+  echo "FAIL: could not resolve the maintenance goal for ${VERSION_ID}" >&2
+  exit 1
+}
+# Belt-and-braces at the point of use: the resolver above already refuses a
+# non-numeric id, but this value is interpolated into python3 source below as
+# CODE, not as a quoted literal, so it is re-checked where the risk actually is.
+[[ "${GOAL_ID}" =~ ^[0-9]+$ ]] || {
+  echo "FAIL: resolved goal id is not numeric: ${GOAL_ID}" >&2
+  exit 1
+}
+echo "Goal: ${GOAL_ID}"
+
+echo "--- 0. snapshot progress before ---"
+PROGRESS_BEFORE=$(snapshot_progress)
+echo "${PROGRESS_BEFORE}"
+
+echo
+echo "--- 1. create task ---"
+CREATE_BODY=$(python3 -c "
+import json
+print(json.dumps({
+  'version_id': '${VERSION_ID}',
+  'goal_id': ${GOAL_ID},
+  'title': '${SMOKE_TITLE}',
+  'description': 'Synthetic smoke task. Auto-shipped by smoke-write.sh.',
+  'status': 'ready',
+  'touches': ['__smoke__/${ts}'],
+  'est_minutes': 1,
+  'manual_degree': 1,
+  'priority': 5,
+  'automation_tag': 'overnight-safe',
+  'credits_reward': 0,
+  'source': 'smoke',
+  'source_ref': '${ts}'
+}))
+")
+TASK_JSON=$(call POST /api/bongos/tasks "${CREATE_BODY}")
+TASK_ID=$(echo "${TASK_JSON}" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['id'])")
+echo "created task #${TASK_ID}"
+
+echo
+echo "--- 2. claim task ---"
+CLAIM_BODY=$(python3 -c "import json; print(json.dumps({'task_id': ${TASK_ID}, 'worktree_name': '__smoke__'}))")
+CLAIM_JSON=$(call POST /api/bongos/claims "${CLAIM_BODY}")
+CLAIM_ID=$(echo "${CLAIM_JSON}" | python3 -c "import json,sys; print(json.load(sys.stdin)['claim']['id'])")
+echo "claim #${CLAIM_ID}"
+
+echo
+echo "--- 3. resolve claim shipped (verification.passed=true → lands at completed; grade gates confirm) ---"
+RESOLVE_BODY='{"outcome":"shipped","notes_md":"smoke-test","value_summary":"smoke-test","verification":{"passed":true,"scanner_clean":true,"smoke_clean":true}}'
+RESOLVE_JSON=$(call POST "/api/bongos/claims/${CLAIM_ID}/resolve" "${RESOLVE_BODY}")
+echo "${RESOLVE_JSON}"
+
+echo
+echo "--- 4. validate ---"
+fail=0
+
+# 4a. recent-shipped does NOT contain the smoke title
+RECENT=$(curl -sS "${API}/api/bongos/public/recent-shipped")
+if echo "${RECENT}" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+titles = [t['title'] for t in data.get('tasks', [])]
+needle = '${SMOKE_TITLE}'
+sys.exit(0 if needle not in titles else 1)
+"; then
+  echo "PASS recent-shipped excludes smoke task"
+else
+  echo "FAIL recent-shipped LEAKED smoke task"
+  fail=1
+fi
+
+# 4b. progress unchanged (smoke filtered from version_progress view)
+PROGRESS_AFTER=$(snapshot_progress)
+if [[ "${PROGRESS_BEFORE}" == "${PROGRESS_AFTER}" ]]; then
+  echo "PASS progress unchanged (smoke filtered from version_progress)"
+else
+  echo "FAIL progress changed:"
+  echo "  before: ${PROGRESS_BEFORE}"
+  echo "  after:  ${PROGRESS_AFTER}"
+  fail=1
+fi
+
+# 4c. task.status lands at 'completed' after resolve.
+# Under the MAS grader-gated lifecycle (V3.R18 #209 / ADR 0024), resolveClaim
+# with verification.passed=true lands the task at 'completed' and STOPS — the
+# completed→confirmed transition is gated by the subagent quality grader
+# (POST /tasks/:id/grade), NOT by resolve. This smoke test exercises only the
+# resolve round-trip, so 'completed' is the correct terminal state here.
+# (Pre-#209 this asserted 'confirmed', which has been failing on every run
+# since the grader gate landed — fixed in #468.) The task should never reach
+# 'shipped' (that needs a merge). credits_reward=0, so no credit_log row.
+TASK_AFTER=$(call GET "/api/bongos/tasks/${TASK_ID}")
+STATUS_AFTER=$(echo "${TASK_AFTER}" | python3 -c "import json,sys; print(json.load(sys.stdin)['task']['status'])")
+if [[ "${STATUS_AFTER}" == "completed" ]]; then
+  echo "PASS task.status = completed (resolve landed it at completed; grade gates confirm — V3.R18 #209)"
+else
+  echo "FAIL task.status = ${STATUS_AFTER} (expected completed)"
+  fail=1
+fi
+
+# 4d. session_logs row exists — checked via DB (needs ssh to the instance's host).
+# The ssh target + DB name come from the operator (GDS_SMOKE_DB_SSH /
+# GDS_SMOKE_DB_NAME) with NO default, so this simply SKIPs unless someone opted
+# in. It used to hardcode one instance's box IP, login and DB name, which made it
+# dead weight on every other instance — the same blindness as the base/token
+# defaults this script inherited from lib.sh (task 1002567).
+DB_SSH="${GDS_SMOKE_DB_SSH:-}"
+DB_NAME="${GDS_SMOKE_DB_NAME:-}"
+if [[ -n "${DB_SSH}" && -n "${DB_NAME}" ]] && command -v ssh >/dev/null \
+   && ssh -o BatchMode=yes -o ConnectTimeout=3 "${DB_SSH}" true 2>/dev/null; then
+  SLOG_COUNT=$(ssh "${DB_SSH}" "psql -d ${DB_NAME} -tAc \"SELECT count(*) FROM session_logs WHERE claim_id = ${CLAIM_ID}\"")
+  if [[ "${SLOG_COUNT}" == "1" ]]; then
+    echo "PASS session_logs row exists (claim_id=${CLAIM_ID})"
+  else
+    echo "FAIL session_logs row missing (claim_id=${CLAIM_ID}, count=${SLOG_COUNT})"
+    fail=1
+  fi
+else
+  echo "SKIP session_logs DB check (set GDS_SMOKE_DB_SSH + GDS_SMOKE_DB_NAME to enable)"
+fi
+
+echo
+echo "--- 5. clean up the throwaway task ---"
+# task 1002018 — this smoke CREATES a real task to exercise the create API, and
+# used to leave it in the ledger forever: 94 rows accumulated under PMS-V1 before
+# the task-2016 sweep cleared them by hand. Abandon is the right terminal state —
+# a smoke row is not shipped work, and the route refuses to abandon a shipped one
+# anyway (cannot_abandon_shipped). The row sits at 'completed' after step 3, and
+# only 'shipped' and an unreleased claim are refused, so this is always legal here.
+#
+# ONLY on success, deliberately: a FAILED run leaves its task and claim in place
+# so the failure can be inspected in the ledger, which is why the FAIL branch of
+# the summary below still prints both ids.
+#
+# Strictly best-effort. A cleanup that cannot run must never turn a passing smoke
+# into a failing one, so this never touches ${fail} and never trips set -e:
+# task.abandon is floor-metic (ADR 0152), so a Xenos/Thetes token gets a 403 here
+# while every assertion above genuinely passed.
+cleanup_throwaway_task() {
+  local out code
+  local reason='{"reason":"smoke cleanup (task 1002018) - write-path smoke passed; the throwaway row has served its purpose"}'
+  out=$(curl -sS -X POST \
+    -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
+    -d "${reason}" -w "\n%{http_code}" \
+    "${API}/api/bongos/tasks/${TASK_ID}/abandon") || true
+  code="${out##*$'\n'}"
+  case "${code}" in
+    2*)  echo "PASS cleaned up throwaway task #${TASK_ID} (abandoned)" ;;
+    403) echo "SKIP cleanup — task.abandon needs Metic+ (ADR 0152); task #${TASK_ID} left in the ledger" ;;
+    000) echo "SKIP cleanup — POST /tasks/${TASK_ID}/abandon got no response; task #${TASK_ID} left in the ledger" ;;
+    *)   echo "SKIP cleanup — POST /tasks/${TASK_ID}/abandon returned HTTP ${code:-none}; task #${TASK_ID} left in the ledger" ;;
+  esac
+}
+
+if [[ "${fail}" -eq 0 ]]; then
+  cleanup_throwaway_task
+else
+  echo "SKIP cleanup — run FAILED; task #${TASK_ID} and claim #${CLAIM_ID} kept for post-mortem"
+fi
+
+echo
+echo "--- summary ---"
+if [[ "${fail}" -eq 0 ]]; then
+  echo "OK: write-path smoke passed (task #${TASK_ID}, claim #${CLAIM_ID})"
+else
+  echo "FAIL: one or more checks failed (task #${TASK_ID}, claim #${CLAIM_ID})"
+fi
+exit "${fail}"

package/scripts/bongos/source-text-test-scan.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+// source-text-test-scan.js — the detector behind the `source_text_only_tests`
+// ratchet in fitness-ratchets.js (task 1004868, goal 1000135, code audit
+// 2026-10-25 finding R11).
+//
+// WHAT IT COUNTS. Test files whose ONLY way of checking the code is to read a
+// source file (.js / .cjs / .mjs / .html / .sh / .css) as text and match its
+// wording. Such a test breaks when someone rewords a harmless line and stays
+// green when the behaviour is wrong — it pins the spelling, not the result.
+//
+// WHY A COUNT AND NOT ZERO. The audit found ~31-40 of these, the largest being
+// tests/projects_hub.mjs (2,400 lines). The owner ruled (2026-10-25): no mass
+// rewrite — stop the growth and convert them as files are touched. So the gate
+// holds the number where it is; it may fall, never rise.
+//
+// THE RULE (a heuristic, deliberately conservative — it under-counts rather
+// than flag a real behaviour test). A file counts when it
+//   1. reads a file (readFileSync / readFile) AND names a source file as a
+//      path-like string literal ('x.js', "page.html" — no spaces), and
+//   2. does NOTHING that exercises code:
+//        - no import/require of anything but a plain Node built-in (a relative
+//          path, a test helper, or a package all count as exercising), and
+//        - no executing built-in: child_process, vm, worker_threads, http,
+//          https, net (spawning a CLI, evaluating extracted code, or talking to
+//          a server are behaviour), and
+//        - no dynamic import()/require() of a computed path, no `new Function`
+//          and no eval.
+// Comment lines are ignored for both halves, so a header that merely mentions
+// `ship.js` does not make a test "read source".
+//
+// Scope: tests/*.mjs and modules/<key>/tests/*.mjs — exactly what the unit
+// runner (scripts/bongos/run-unit-tests.js) discovers. Fixtures are skipped.
+//
+// List the counted files:  node scripts/bongos/source-text-test-scan.js --files
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { builtinModules } = require('module');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+const BUILTINS = new Set(builtinModules);
+const EXECUTING_BUILTINS = new Set(['child_process', 'vm', 'worker_threads', 'http', 'https', 'net']);
+
+const READS_FILE_RE = /\breadFileSync\s*\(|\breadFile\s*\(/;
+const SOURCE_PATH_RE = /['"][^'"\s]*\.(?:c?js|mjs|html|sh|css)['"]/;
+const COMMENT_LINE_RE = /^\s*(?:\/\/|\/?\*)/;
+// Static `import … from 'x'`, bare `import 'x'`, `import('x')`, `require('x')`.
+const SPECIFIER_RE = /(?:^\s*import\b[^;'"`]*?\bfrom\s*|^\s*import\s*|\bimport\s*\(\s*|(?<![.\w$])require\s*\(\s*)(['"`])([^'"`\n]+)\1/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*[^'"`\s)]/;
+const DYNAMIC_REQUIRE_RE = /(?<![.\w$])require\s*\(\s*[A-Za-z_$]/;
+const EVAL_RE = /\bnew\s+Function\s*\(|(?<![.\w$])eval\s*\(/;
+
+function stripCommentLines(text) {
+  return text.split('\n').filter((l) => !COMMENT_LINE_RE.test(l)).join('\n');
+}
+
+/** Why a test file counts as exercising behaviour, or null when it does not. */
+function exercisesCode(code) {
+  SPECIFIER_RE.lastIndex = 0;
+  let m;
+  while ((m = SPECIFIER_RE.exec(code))) {
+    const spec = m[2];
+    const base = spec.replace(/^node:/, '').split('/')[0];
+    if (!spec.startsWith('node:') && !BUILTINS.has(base)) return `imports ${spec}`;
+    if (EXECUTING_BUILTINS.has(base)) return `uses ${spec}`;
+  }
+  if (DYNAMIC_IMPORT_RE.test(code)) return 'dynamic import()';
+  if (DYNAMIC_REQUIRE_RE.test(code)) return 'dynamic require()';
+  if (EVAL_RE.test(code)) return 'evaluates code';
+  return null;
+}
+
+/** True when a test file's only checks are reads of source-file text. */
+function isSourceTextOnly(text) {
+  const code = stripCommentLines(String(text).replace(/\r\n/g, '\n'));
+  if (!READS_FILE_RE.test(code) || !SOURCE_PATH_RE.test(code)) return false;
+  return exercisesCode(code) === null;
+}
+
+function trackedTestFiles(root = ROOT) {
+  const out = execFileSync('git', ['ls-files', 'tests/*.mjs', 'modules/*/tests/*.mjs'], { cwd: root, encoding: 'utf8' });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean).filter((f) => !f.includes('/fixtures/'));
+}
+
+/**
+ * Count source-text-only test files. `files` and `read` are injectable so a test
+ * can add a virtual file without writing into the repo. `scanned` is the number
+ * of files enumerated — 0 means the scan collapsed, never "a clean tree".
+ */
+function scanSourceTextTests({ root = ROOT, files = null, read = null } = {}) {
+  const list = files || trackedTestFiles(root);
+  const reader = read || ((f) => fs.readFileSync(path.join(root, f), 'utf8'));
+  const counted = list.filter((f) => isSourceTextOnly(reader(f)));
+  return { total: counted.length, scanned: list.length, files: counted };
+}
+
+module.exports = { scanSourceTextTests, isSourceTextOnly, exercisesCode, trackedTestFiles };
+
+if (require.main === module) {
+  const r = scanSourceTextTests();
+  if (process.argv.includes('--files')) for (const f of r.files) console.log(f);
+  console.log(`source_text_only_tests=${r.total} (of ${r.scanned} test files scanned)`);
+}

package/scripts/bongos/spark.js

@@ -0,0 +1,294 @@
+#!/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.
+//
+// --develop is the PICKUP (task 1002922 / BV1.R146): fill in the five template
+// fields and the spark becomes a Full Idea, in place, with the original author
+// preserved and you recorded as its developer. Open to any builder — the author's
+// mark was the consent. The five fields are prose, so they come from a JSON file
+// rather than five shell flags; --template prints the shape to fill in. The hall
+// form (R152) and conversational authoring (R155) are the richer surfaces; this
+// is the terminal path, and all three hit the same route.
+//
+// Usage:
+//   node scripts/bongos/spark.js --template       # print the five fields to fill in
+//   node scripts/bongos/spark.js --develop 123 --fields-file idea.json
+//   node scripts/bongos/spark.js --list           # the spark queue: what awaits development
+//   node scripts/bongos/spark.js --list --limit 10
+//   node scripts/bongos/spark.js 123              # mark idea 123 as a spark
+//   node scripts/bongos/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 fs = require('node:fs/promises');
+const { cliClient, requireSession, hasFlag, arg, hallBase } = require('./cli-lib');
+// A CLI may reach into its own domain module — the capture.js / autonomy-gate.js
+// precedent. Pure and DB-free: this only reads the R141 template declaration so
+// the prompt below cannot drift from what the server validates against.
+const { BASE_TEMPLATE } = require('../../modules/ideas/templates');
+
+// 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_spark: (d) =>
+    d.grade === 'full'
+      ? `That idea has already been developed into a Full Idea${d.developed_by ? ` (by builder ${d.developed_by})` : ''}.\n`
+        + 'A spark can only be developed once.'
+      : 'That idea is not a Big Idea Spark, so it is not available to develop.\n'
+        + 'Its author has to mark it first — that mark is what makes developing it fair.',
+  spark_already_developed: () =>
+    'Another builder developed this spark first, moments ago. Their version stands.\n'
+    + 'Run --list to see what else is waiting.',
+  invalid_field_values: (d) => {
+    const errs = Array.isArray(d) ? d : (d.errors || []);
+    const lines = ['That is not a complete Full Idea yet:'];
+    for (const e of errs) {
+      lines.push(`  - ${e.field || '(the whole set)'}: ${String(e.reason || '').replace(/_/g, ' ')}`);
+    }
+    lines.push('Run --template to see the five fields and re-run with the file fixed.');
+    return lines.join('\n');
+  },
+  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/bongos/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 || {}));
+}
+
+// The five fields, printed as a fill-in-the-blanks JSON skeleton. Read from the
+// R141 declaration rather than restated, so it cannot drift from what the server
+// validates — and it names the substance floor, because "present but three words"
+// is the failure the scorer actually punishes.
+function templateSkeleton() {
+  const lines = ['The five fields of a Full Idea (template ' + BASE_TEMPLATE.key + '):', ''];
+  for (const f of BASE_TEMPLATE.fields) {
+    lines.push(`  ${f.key}`);
+    lines.push(`    ${f.label}`);
+    if (f.substanceMin) lines.push(`    at least ~${f.substanceMin} characters of real content — padding scores nothing`);
+  }
+  lines.push('');
+  lines.push('Write them into a JSON file, then develop a spark with it:');
+  lines.push('');
+  lines.push('  ' + JSON.stringify(Object.fromEntries(BASE_TEMPLATE.fields.map((f) => [f.key, '...'])), null, 2).replace(/\n/g, '\n  '));
+  lines.push('');
+  lines.push('  node scripts/bongos/spark.js --develop <idea-id> --fields-file <that-file.json>');
+  return lines.join('\n');
+}
+
+// How the freshly-opened ratification window is described to its author.
+//
+// A NULL `closes_at` is the no-clock constitution, not a missing deadline —
+// several pass rules run a sitting with no clock at all, and the window simply
+// never expires. Printing the field raw turned that into "open until null" for
+// every author on a clockless instance (task 1003654, caught five times by the
+// R157 proof walk). So the rule decides the sentence, and the wording tracks
+// the Board Room's own clockLine() (modules/hall-ui/public/board-room.js) —
+// one vocabulary for one fact, whichever surface the author reads it on.
+//
+// ALL FOUR of config.js's PASS_RULES get a branch, `consent` included: it is
+// not clock-safe (CLOCK_SAFE_PASS_RULES is majority + unanimous only), so a
+// consent constitution is one of the likeliest to arrive here with no deadline
+// at all. The default arm is for an unreadable rule, not for a known one.
+function boardWindowLine(w) {
+  if (w.closes_at) return `  A board ratification window is open until ${w.closes_at}.`;
+  switch (w.pass_rule) {
+    case 'first_ratifier': return '  A board ratification window is open — no clock; it closes on the first vote.';
+    case 'consent': return '  A board ratification window is open — no clock; it stands unless someone objects.';
+    case 'majority': return '  A board ratification window is open — no clock; it waits for a majority.';
+    case 'unanimous': return '  A board ratification window is open — no clock; it waits for a unanimous yes.';
+    default: return '  A board ratification window is open — no clock; it stays open until the board decides.';
+  }
+}
+
+// What the developer is told once it lands. The completeness score is the number
+// the R147 credit split and the board bar both read, so it is the headline.
+function renderDeveloped(data) {
+  const { idea, author_id, developer_id, self_developed, board_window } = data || {};
+  const lines = [];
+  lines.push(`Idea ${idea.id} is now a Full Idea — completeness ${idea.completeness_score ?? 'unscored'}/100.`);
+  lines.push(`  ${hallBase()}/#/idea/${idea.id}`);
+  lines.push(self_developed
+    ? '  You had the thought and you developed it.'
+    : `  The thought stays credited to builder ${author_id}; you are recorded as its developer (${developer_id}).`);
+  if (board_window) {
+    lines.push(boardWindowLine(board_window));
+  } else if (idea.rejection) {
+    lines.push(`  Not yet at the bar — thinnest section: ${idea.rejection.section_key}.`);
+    if (idea.rejection.reason_md) lines.push(`    ${idea.rejection.reason_md}`);
+  }
+  return lines.join('\n');
+}
+
+async function developSpark(ideaId) {
+  const file = arg('--fields-file');
+  if (!file) {
+    console.error('--develop needs --fields-file <path.json> (the five fields).');
+    console.error('Run: node scripts/bongos/spark.js --template');
+    process.exit(2);
+  }
+  let fieldValues;
+  try {
+    fieldValues = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (err) {
+    console.error(`could not read ${file} as JSON: ${err.message}`);
+    process.exit(2);
+  }
+  const api = await cliClient();
+  const templateKey = arg('--template-key');
+  const r = await api.inbox.postInboxIdDevelop({
+    id: ideaId,
+    body: { field_values: fieldValues, ...(templateKey ? { template_key: templateKey } : {}) },
+  });
+  if (!r.ok) {
+    console.error(explain(r.status, r.data));
+    process.exit(1);
+  }
+  console.log(renderDeveloped(r.data));
+}
+
+async function main() {
+  await requireSession();
+
+  if (hasFlag('--template')) {
+    console.log(templateSkeleton());
+    return;
+  }
+  if (hasFlag('--list')) return listQueue();
+  const developIdRaw = arg('--develop');
+  if (developIdRaw != null) {
+    const devId = Number(developIdRaw);
+    if (!Number.isInteger(devId) || devId <= 0) {
+      console.error('usage: node scripts/bongos/spark.js --develop <idea-id> --fields-file <path.json>');
+      process.exit(2);
+    }
+    return developSpark(devId);
+  }
+
+  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/bongos/spark.js <idea-id> [--undo]');
+    console.error('       node scripts/bongos/spark.js --list [--limit N]');
+    console.error('       node scripts/bongos/spark.js --develop <idea-id> --fields-file <path.json>');
+    console.error('       node scripts/bongos/spark.js --template');
+    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.`);
+  }
+}
+
+// The four renderers are exported because each is pinned by a test — explain
+// against the real envelope shape, and the three renderers for the shapes a
+// human actually reads. REFUSALS stays private: it is the message table,
+// reachable through explain(), and a fifth export would be dead surface.
+module.exports = { explain, renderQueue, renderDeveloped, templateSkeleton };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}