@bongos/core 1.19.303 → 1.19.304

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.303",
-  "core_contract": "1.19.303",
-  "source_commit": "fd08cc750b621521b54d357645136366c89f0316",
+  "core_version": "1.19.304",
+  "core_contract": "1.19.304",
+  "source_commit": "8c22da0cc4ab95a1684933ef98112abb201bc850",
   "source_ref": "HEAD",
-  "built_at": "2026-08-22T23:32:40.774Z",
+  "built_at": "2026-08-23T19:13:32.623Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1412,
+    "functional_verbatim": 1413,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1756,
-  "tree_sha256": "42829db3492386930a68c9936d55f1e7d7895fc1e6194a65e6d659e81be98c05",
+  "file_count": 1757,
+  "tree_sha256": "644acfeea1c7e902934e366c56379f0191e6de8e08e6338567155722b916b2fd",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1557,7 +1557,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "dff7371d1874f3072213e8d094a26ca13c8e1d53a202b82445dc7cfcf47ad0b7"
+      "sha256": "ffd052f893ea0ef47a65e66a6d260fd43c1ccc653fa277f11f13805099e73d45"
     },
     {
       "path": "docs/handoff-template.md",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "5721cb7973d1dc844692348aeb2462d3adfcba9929f7146f6a872c6de15dd710"
+      "sha256": "3f027a59178132ea747301cbcc78f7404c0f0ec820c6651affcf8854b1cf70f3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "441e6e4bea0f538d4c0e63eb17cee0f65077775be47c930b8876cb022bc0966b"
+      "sha256": "79d94ba55244fa52d3f8f35717803666064daecb4d91d5547060baaa2143692d"
     },
     {
       "path": "public-docs/index.html",
@@ -5037,7 +5037,7 @@
     {
       "path": "scripts/gds/capture.js",
       "mode": "0000644",
-      "sha256": "208bfd6c6a73f4234c06bb26e3319ec43ecf865927333bc810ca99efa9745e90"
+      "sha256": "950a65cf4766f795622c6780dcfa9a1b3f9aefe38f406ec6759b129028958aa9"
     },
     {
       "path": "scripts/gds/cf-tunnel.js",
@@ -6237,7 +6237,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "dcb27806a84ffee473f8e69ca78530535b7d7c51e30780e09982ba8489768f9c"
+      "sha256": "b8db1ca313e0156a5891a779be650f8c56069015529e064a18b8e4970e7e312f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7519,6 +7519,11 @@
       "mode": "0000644",
       "sha256": "ea992d1ab2ddedc27aaa5348a397356bef91a4c1ad9b295eb1a0ed1c4fc707e9"
     },
+    {
+      "path": "tests/idea_capture_grades.mjs",
+      "mode": "0000644",
+      "sha256": "fb129f6ee327d946ba2e7ee46bab3b9795621f7f405637e1e8ed2b29807a84cf"
+    },
     {
       "path": "tests/idea_completeness.mjs",
       "mode": "0000644",

package/docs/file-map.md

@@ -174,7 +174,7 @@
 │       ├── box.js               ← (#598/ADR 0031) per-builder dev box lifecycle CLI: provision·park·wake·deprovision·sweep-idle·sweep-dormant·status (dry-run default, --apply to act; rank-gated)
 │       ├── smoke-box.sh         ← (#598) hermetic box-lifecycle smoke (no DB/DO/network): runs tests/boxes.mjs + tests/cf_tunnel.mjs (#771 named tunnel) + route-rank + module-load
 │       ├── recall.js            ← `/recall` CLI: two-call progressive-disclosure search (summary → `--expand <id>`) over Bongos retrieval layer (ADR 0060); `node scripts/gds/recall.js <query>`
-│       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills
+│       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills. Task 1002927 / R151 taught it the GRADES: `--full --fields-file f.json` files a Full Idea, `--spark` is capture-then-mark (two requests — the route refuses a pre-marked capture), and after a plain quick capture it OFFERS to develop further. That offer is TTY-gated (`--no-prompt` too): capture.js is run by agents with no terminal and reads its body from stdin, so an unguarded prompt would hang every non-interactive caller
 │       ├── spark.js            ← (tasks 1002920 / R144 + 1002921 / R145 + 1002922 / R146) the whole spark handoff from the terminal: mark one of your OWN quick ideas as a Big Idea Spark (`--undo` withdraws it), `--list` is the SPARK QUEUE, `--template` prints the five Full Idea fields, `--develop <id> --fields-file <json>` is the PICKUP (any builder; author + developer both recorded). Author-only server-side for the mark (it is the consent); its own command because sparking acts on an EXISTING idea, which is why capture.js refuses grade='spark'
 │       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.303",
+  "version": "1.19.304",
   "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/capture.js

@@ -7,7 +7,30 @@
 //     [--kind feature] \
 //     [--body-file path] \
 //     [--version V1|PMS-V2|GDS-V3] \
-//     [--priority N]
+//     [--priority N] \
+//     [--spark] \
+//     [--full --fields-file path.json] \
+//     [--no-prompt]
+//
+// THE GRADE AXIS (task 1002927 / BV1.R151, goal 1000062). Three grades exist and
+// this CLI reaches all three, but NOT symmetrically, because they are not
+// symmetrical acts:
+//   quick  — the default. Title + body. Unchanged.
+//   full   — `--full --fields-file f.json`, the five R141 fields. One request.
+//   spark  — `--spark`, which is TWO requests: capture, then mark. The route
+//            deliberately REFUSES grade='spark' at capture (R144: an idea does not
+//            arrive pre-marked; sparking is the author's later act on an existing
+//            idea), and that invariant is not being worked around here — the
+//            author is simply performing both acts in one command, and the mark
+//            still goes through the author-only route that checks captured_by.
+//
+// THE POST-CAPTURE OFFER, and the one thing that must not break: after a plain
+// quick capture, an interactive terminal is asked whether to develop the thought
+// into a Full Idea. It is TTY-GATED. capture.js is run by agents and scripts with
+// no terminal (and reads its BODY from stdin when --body-file is absent), so an
+// unguarded prompt would hang every non-interactive caller. No TTY, or
+// --no-prompt, means the offer never appears and the behaviour is exactly what it
+// was before this task.
 //
 // Defaults:
 //   --kind     → server auto-classifies from title+body (keyword heuristics
@@ -27,7 +50,8 @@
 //   Inbox now: 8 open
 
 const fs = require('node:fs/promises');
-const { cliClient, requireSession, arg } = require('./cli-lib');
+const readline = require('node:readline');
+const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
 
 
 async function resolveDefaultVersion() {
@@ -59,12 +83,49 @@ function formatCaptureFailure(status, data) {
   return `capture failed (${status}): ${rendered}`;
 }
 
+// DEFAULT IS NO, and only an explicit yes counts. Extracted so the done-when
+// ("declinable in one keystroke") is a testable predicate rather than a regex
+// buried in a readline callback: a bare Enter, a stray space, an EOF (null), or
+// anything that is not y/yes all decline.
+function acceptsOffer(answer) {
+  return /^y(es)?$/i.test(String(answer == null ? '' : answer).trim());
+}
+
+// The offer. DEFAULT IS NO: a bare Enter declines and leaves a plain quick idea,
+// which is the done-when. It prints the command rather than launching an
+// interactive five-field interview — the fields are prose, the terminal is a bad
+// place to write five paragraphs, and the two surfaces built for it (the hall
+// form and /ideate) are better at it than a readline loop would ever be. So the
+// offer's job is to make the NEXT step obvious, not to become that step.
+async function offerToDevelop(ideaId) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question('\nDevelop this into a Full Idea? It gets a completeness score and can earn on the ideator lane. [y/N] ', resolve);
+    });
+    if (!acceptsOffer(answer)) {
+      // Declined. Nothing further happens — the quick idea stands exactly as filed.
+      console.log('Left as a quick idea.');
+      return;
+    }
+    console.log('\nTwo ways to write it:');
+    console.log(`  in the hall:      /builders/ideas   (a live completeness meter as you type)`);
+    console.log(`  in the terminal:  node scripts/gds/spark.js --template   (then --fields-file)`);
+    console.log(`\nOr offer it up for someone else to develop:`);
+    console.log(`  node scripts/gds/spark.js ${ideaId}`);
+  } finally {
+    rl.close();
+  }
+}
+
 async function main() {
-  await requireSession();
   const args = process.argv.slice(2);
   const title = args[0];
   if (!title || title.startsWith('--')) {
     console.error('usage: node scripts/gds/capture.js "title" [--kind feature] [--body-file path] [--version V1|PMS-V2] [--priority N]');
+    console.error('       ... [--spark]                       offer it up for someone else to develop');
+    console.error('       ... [--full --fields-file f.json]   file a Full Idea (five fields; see spark.js --template)');
+    console.error('       ... [--no-prompt]                   never ask anything (default when not a terminal)');
     process.exit(2);
   }
 
@@ -72,6 +133,37 @@ async function main() {
   const bodyFile = arg('--body-file', args);
   const versionFromArg = arg('--version', args);
   const priorityStr = arg('--priority', args);
+  const wantSpark = hasFlag('--spark', args);
+  const wantFull = hasFlag('--full', args);
+  const fieldsFile = arg('--fields-file', args);
+  const noPrompt = hasFlag('--no-prompt', args);
+
+  // Refused rather than resolved: --spark and --full are contradictory requests
+  // (a spark is a thought offered up BECAUSE it is not developed), and silently
+  // picking one would file something the caller did not ask for.
+  if (wantSpark && wantFull) {
+    console.error('--spark and --full are contradictory: a spark is a thought you are NOT developing yet. Pick one.');
+    process.exit(2);
+  }
+  if (wantFull && !fieldsFile) {
+    console.error('--full needs --fields-file PATH (a JSON object of the five fields).');
+    console.error('Run: node scripts/gds/spark.js --template   to see them.');
+    process.exit(2);
+  }
+  if (fieldsFile && !wantFull) {
+    console.error('--fields-file only means something with --full.');
+    process.exit(2);
+  }
+
+  let fieldValues = null;
+  if (wantFull) {
+    try {
+      fieldValues = JSON.parse(await fs.readFile(fieldsFile, 'utf8'));
+    } catch (err) {
+      console.error(`failed to read --fields-file as JSON: ${err.message}`);
+      process.exit(2);
+    }
+  }
 
   let bodyMd = '';
   if (bodyFile) {
@@ -93,6 +185,13 @@ async function main() {
     priority = p;
   }
 
+  // The session is demanded HERE, not at the top of main(): every exit above this
+  // line is an argument error, and answering "you are not signed in" to a mistyped
+  // flag sends the caller to /builder-reauth for a session that is fine — while a
+  // builder who is NOT signed in cannot read the usage block to find out how to
+  // sign in. resolveDefaultVersion() is the first call that actually needs a token.
+  await requireSession();
+
   const version = versionFromArg || (await resolveDefaultVersion());
 
   const payload = {
@@ -102,6 +201,12 @@ async function main() {
     suggested_priority: priority,
   };
   if (kindFromArg) payload.kind = kindFromArg;
+  if (wantFull) {
+    // The server validates these against the R141 declaration and scores them
+    // with R142 — this CLI sends them and states nothing about their shape.
+    payload.grade = 'full';
+    payload.field_values = fieldValues;
+  }
 
   const api = await cliClient();
   const r = await api.inbox.postInbox({ body: payload });
@@ -115,11 +220,48 @@ async function main() {
   const versionLabel = idea.suggested_version || 'none';
   const priorityLabel = idea.suggested_priority == null ? 'null' : `P${idea.suggested_priority}`;
 
+  const gradeLabel = idea.grade && idea.grade !== 'quick' ? `, grade=${idea.grade}` : '';
   console.log(
-    `Captured idea #${idea.id}: kind=${kindLabel}, version=${versionLabel}, priority=${priorityLabel}`
+    `Captured idea #${idea.id}: kind=${kindLabel}, version=${versionLabel}, priority=${priorityLabel}${gradeLabel}`
   );
+  if (wantFull) {
+    // The server is the authority on whether the grade write landed: capture is
+    // FAIL-OPEN on grading (R143), so an idea can land as quick with a warning.
+    // Reporting what was ASKED for instead of what happened is how a builder
+    // ends up believing they filed a Full Idea when they did not.
+    if (idea.grade === 'full') {
+      const s = idea.completeness_score;
+      console.log(`Filed as a Full Idea — completeness ${Number.isInteger(s) ? `${s}/100` : 'unscored'}.`);
+    } else {
+      console.log('NOTE: stored as a QUICK idea — the grade could not be written. The text is safe; re-file the fields when you can.');
+    }
+  }
   console.log(`Inbox now: ${open_count} open`);
 
+  // --spark: capture, then MARK. Two requests by design, not a workaround — the
+  // capture route refuses grade='spark' (R144) because an idea does not arrive
+  // pre-marked, and the mark still goes through the author-only route.
+  if (wantSpark) {
+    const sp = await api.inbox.postInboxIdSpark({ id: idea.id, body: {} });
+    if (sp.ok) {
+      console.log('Marked as a Big Idea Spark — it is in the queue at /builders/ideas for someone to develop.');
+    } else {
+      // The idea is filed and that is the part that mattered. Say plainly that
+      // only the mark failed, and how to retry just the mark.
+      console.error(`Filed, but the spark mark failed (${sp.status}). The idea is safe; retry with:`);
+      console.error(`  node scripts/gds/spark.js ${idea.id}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // THE POST-CAPTURE OFFER (the brief: "Claude asks if you would like to submit
+  // as a full idea after a quick idea is made"). Only for a plain quick capture,
+  // only at a real terminal, and declinable with a single Enter.
+  if (!wantFull && !noPrompt && process.stdin.isTTY && process.stdout.isTTY) {
+    await offerToDevelop(idea.id);
+  }
+
   // Migration detection lives only on the server now (POST /api/gds/tasks sets
   // tasks.needs_migration from the title/description on create — migration 081,
   // task 876). Ideas carry no touches[] and aren't tasks, so the old CLI-side
@@ -127,7 +269,7 @@ async function main() {
   // referred to; promotion to a task re-runs the detection automatically.
 }
 
-module.exports = { resolveDefaultVersion, formatCaptureFailure };
+module.exports = { resolveDefaultVersion, formatCaptureFailure, acceptsOffer };
 
 if (require.main === module) {
   main().catch((err) => {

package/src/module-api.js

@@ -1033,8 +1033,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.301 with no explicit bump. run 32604538465. (task 1002620)
 //   1.19.303 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.302 with no explicit bump. run 32605477232. (task 1002620)
+//   1.19.304 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.303 with no explicit bump. run 32660527575. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.303'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.304'; // 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');

package/tests/idea_capture_grades.mjs

@@ -0,0 +1,159 @@
+// tests/idea_capture_grades.mjs
+//
+// task 1002927 (BV1.R151, goal 1000062) — capture.js learns the grades.
+//
+// The done-when: capture.js can file all three grades; the post-capture offer
+// appears after a quick capture and is DECLINABLE IN ONE KEYSTROKE; declining
+// leaves a plain quick idea.
+//
+// The riskiest part of this task is not the grades, it is the PROMPT. capture.js
+// is run by agents and scripts with no terminal, and it already reads its body
+// from stdin when --body-file is absent — so an unguarded question would hang
+// every non-interactive caller, silently, forever. The TTY gate is therefore
+// asserted twice: as a source invariant, and by actually running the process with
+// piped stdin and watching it not hang.
+//
+// Run:  node tests/idea_capture_grades.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CAPTURE = path.join(ROOT, 'scripts/gds/capture.js');
+const SRC = fs.readFileSync(CAPTURE, 'utf8');
+const { acceptsOffer } = require('../scripts/gds/capture.js');
+
+// Run capture.js as a real process with piped stdio. Every case below is refused
+// by argument validation BEFORE any network call, so this needs no session.
+function run(args, { input = '' } = {}) {
+  return spawnSync(process.execPath, [CAPTURE, ...args], {
+    input, encoding: 'utf8', timeout: 20000,
+  });
+}
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// --- declinable in ONE keystroke ----------------------------------------
+
+test('a bare Enter declines — that is the one keystroke', () => {
+  assert.equal(acceptsOffer(''), false);
+});
+
+test('only an explicit yes accepts', () => {
+  for (const yes of ['y', 'Y', 'yes', 'YES', ' y ', 'Yes']) {
+    assert.equal(acceptsOffer(yes), true, JSON.stringify(yes));
+  }
+  for (const no of ['n', 'no', 'N', 'maybe', 'yep', 'ya', '1', 'ok']) {
+    assert.equal(acceptsOffer(no), false, JSON.stringify(no));
+  }
+});
+
+test('an EOF or a closed pipe declines rather than throwing', () => {
+  // readline resolves with undefined on EOF; treating that as a yes would drag a
+  // non-interactive caller into a flow it never asked for.
+  assert.equal(acceptsOffer(null), false);
+  assert.equal(acceptsOffer(undefined), false);
+});
+
+// --- the TTY gate --------------------------------------------------------
+
+test('the offer is gated on a REAL terminal, both directions', () => {
+  assert.match(SRC, /process\.stdin\.isTTY/, 'stdin must be a terminal');
+  assert.match(SRC, /process\.stdout\.isTTY/, 'and stdout, or the question goes into a pipe unseen');
+});
+
+test('the offer is skipped for a Full Idea capture and by --no-prompt', () => {
+  // Asking "develop this into a Full Idea?" right after someone filed one would
+  // be absurd; --no-prompt is the explicit opt-out for a caller that has a TTY
+  // but does not want to be asked.
+  assert.match(SRC, /if \(!wantFull && !noPrompt && process\.stdin\.isTTY/);
+});
+
+test('running with PIPED stdin does not hang or prompt', () => {
+  // The real regression this guards: a prompt with no TTY blocks forever. These
+  // args are refused at validation, which is enough to prove the process exits.
+  const r = run(['a title', '--spark', '--full'], { input: '' });
+  assert.equal(r.status, 2, `exited cleanly (signal=${r.signal})`);
+  assert.equal(r.signal, null, 'not killed by the timeout');
+  assert.doesNotMatch(String(r.stdout), /Develop this into a Full Idea\?/);
+});
+
+// --- all three grades reachable -----------------------------------------
+
+test('--full requires the five fields, and says where to find them', () => {
+  const r = run(['a title', '--full']);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /--full needs --fields-file/);
+  assert.match(r.stderr, /spark\.js --template/, 'it points at the thing that prints the fields');
+});
+
+test('--fields-file without --full is refused rather than silently ignored', () => {
+  const r = run(['a title', '--fields-file', '/tmp/nope.json']);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /only means something with --full/);
+});
+
+test('--spark and --full are refused together, with the reason', () => {
+  const r = run(['a title', '--spark', '--full']);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /contradictory/);
+  // The reason matters: it is not an arbitrary exclusion, a spark is BY DEFINITION
+  // a thought you are not developing yet.
+  assert.match(r.stderr, /NOT developing yet/);
+});
+
+test('an unreadable --fields-file fails before any capture', () => {
+  const r = run(['a title', '--full', '--fields-file', '/tmp/definitely-not-here.json']);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /failed to read --fields-file as JSON/);
+});
+
+test('--spark is capture-then-MARK, not a pre-marked capture', () => {
+  // The route refuses grade='spark' at capture (R144: an idea does not arrive
+  // pre-marked), and this CLI does not work around that — it performs the second
+  // act through the author-only mark route.
+  assert.match(SRC, /postInboxIdSpark/, 'it calls the mark route');
+  // Asserted over the PAYLOAD ASSIGNMENT, not over the file text: the file
+  // explains the rule in prose, and forbidding the string anywhere would fail on
+  // the comment that documents why the rule exists. (Fourth time this session an
+  // "absent from the source" assertion needed narrowing to what it meant —
+  // learning 1000196.)
+  const assignments = [...SRC.matchAll(/payload\.grade\s*=\s*'([a-z]+)'/g)].map((m) => m[1]);
+  assert.deepEqual(assignments, ['full'], 'the only grade this CLI ever sends at capture is full');
+});
+
+test('a full capture reports what the SERVER stored, not what was asked for', () => {
+  // Capture is fail-open on grading (R143): the idea can land as quick with a
+  // warning. Reporting the request is how someone believes they filed a Full Idea
+  // when they did not.
+  assert.match(SRC, /idea\.grade === 'full'/);
+  assert.match(SRC, /stored as a QUICK idea/);
+});
+
+test('a failed spark mark still reports the idea as safe, and how to retry', () => {
+  // The capture already committed; losing the mark must not read as losing the
+  // thought.
+  assert.match(SRC, /the idea is safe|The idea is safe/);
+  assert.match(SRC, /spark\.js \$\{idea\.id\}/, 'it prints the exact retry command');
+});
+
+test('usage names all three grades', () => {
+  const r = run([]);
+  assert.equal(r.status, 2);
+  for (const flag of ['--spark', '--full', '--no-prompt']) {
+    assert.ok(r.stderr.includes(flag), `usage mentions ${flag}`);
+  }
+});
+
+console.log(`\nidea_capture_grades: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);