@bongos/core 1.19.495 → 1.19.497

package/modules/lifecycle/goal-advisory.js

@@ -40,8 +40,14 @@ function generalGoalTitle(versionId) {
 // authorization gate. This is advice appended to a request that ALREADY SUCCEEDED;
 // a wrong guess here nags a builder about a task that is fine, which is worse than
 // staying quiet. A missing versionId or an unreadable goal title yields null.
-function adviseGoal({ versionId, goalId, goalTitle } = {}) {
+//
+// kind='bug' is a THIRD silent case (task 1003214, idea 1000828 — the owner
+// directive against manufacturing small goals): a fix sitting in the catch-all,
+// or with no goal at all, is already where it belongs, so both reasons above
+// collapse to null for a bug. The nudge is for homeless FEATURE work only.
+function adviseGoal({ versionId, goalId, goalTitle, kind } = {}) {
   if (goalId == null) {
+    if (kind === 'bug') return null;
     return {
       reason: 'no_goal',
       message: 'This task has no goal to live in — no scope wall, no done-when criteria gating it, '
@@ -53,6 +59,7 @@ function adviseGoal({ versionId, goalId, goalTitle } = {}) {
   }
   if (versionId == null || typeof goalTitle !== 'string') return null;
   if (goalTitle !== generalGoalTitle(versionId)) return null;
+  if (kind === 'bug') return null;
   return {
     reason: 'catch_all',
     message: `This task landed in "${goalTitle}", the version's catch-all bucket rather than a real goal — `
@@ -93,6 +100,7 @@ async function buildGoalAdvisory({ db, versionId, task }) {
       versionId,
       goalId: task.goal_id,
       goalTitle: homeGoal && homeGoal.title,
+      kind: task.kind,
     });
     if (!verdict) return null;
     // LIMIT 6, not 6-in-JS: Postgres truncates instead of shipping every open goal

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.495",
+  "version": "1.19.497",
   "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

@@ -8,6 +8,7 @@
 //     [--body-file path] \
 //     [--version V1|PMS-V2|GDS-V3] \
 //     [--priority N] \
+//     [--goal N | --goal none] \
 //     [--spark] \
 //     [--full --fields-file path.json] \
 //     [--no-prompt]
@@ -38,6 +39,27 @@
 //   --version  → most recent version with status='building' (queried from
 //                /api/gds/versions); leave null if there isn't one
 //   --priority → null (set later at triage time)
+//   --goal     → capture-time ROUTING (task 1003070, R09 of goal 1000071,
+//                interview decision 4). Naming a goal turns this filing into a
+//                task IN that goal in the same request (POST /inbox's own
+//                landing matrix — task 1003065 — still decides whether it
+//                hard-lands 'ready' or soft-lands 'backlog'; this CLI duplicates
+//                none of that, it only decides WHICH goal to send). Three ways:
+//                  --goal N     → route to goal N, verbatim.
+//                  --goal none  → explicitly homeless: no goal_id is sent, and
+//                                 the active-claim default below is skipped —
+//                                 an opt-out that still guessed a goal would not
+//                                 be an opt-out.
+//                  (neither)    → default to the ACTIVE CLAIM's goal, if this
+//                                 builder holds one and its task has a goal
+//                                 ("capturing mid-work almost always concerns
+//                                 the work" — the interview's own words). With
+//                                 no default to offer, the R07 suggester
+//                                 (GET /goals/suggestions) prints its best guess
+//                                 as a one-line hint — never an auto-pick; C5 is
+//                                 "the system OFFERS the home", not chooses it.
+//                Both the active-claim lookup and the suggester are best-effort:
+//                either failing degrades to "no goal", never to a fatal error.
 //
 // Exit codes:
 //   0  captured
@@ -71,6 +93,103 @@ function formatCaptureFailure(status, data) {
   return `capture failed (${status}): ${rendered}`;
 }
 
+// parseGoalArg — pure parse of --goal's raw value (task 1003070 / R09). 'none'
+// (case-insensitive) is the explicit opt-out; anything else must be a positive
+// integer id. Never throws — a bad value comes back as { kind: 'invalid' } so
+// main() can print one usage line and exit 2, same shape as the --priority check
+// above it.
+function parseGoalArg(raw) {
+  if (raw == null) return { kind: 'unset' };
+  const trimmed = String(raw).trim();
+  if (trimmed.toLowerCase() === 'none') return { kind: 'none' };
+  const n = Number(trimmed);
+  if (Number.isInteger(n) && n > 0) return { kind: 'id', id: n };
+  return { kind: 'invalid' };
+}
+
+// resolveActiveClaimGoal — the active-claim default (interview decision 4). /me's
+// active_claims rows (the same read claim.js/release.js already use to find "the
+// claim I'm holding") carry the task's title but not its goal, so this adds one
+// GET /tasks/:id to read it. Returns null — never throws — on no session, no
+// active claim, or a claimed task with no goal: a claim-lookup hiccup must not
+// block a capture that would otherwise have filed fine with no goal at all.
+async function resolveActiveClaimGoal({ client = cliClient } = {}) {
+  try {
+    const api = await client();
+    const me = await api.me.getMe();
+    if (!me.ok || !me.data) return null;
+    const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+    const claim = claims[0];
+    if (!claim || claim.task_id == null) return null;
+    const t = await api.tasks.getTasksId({ id: claim.task_id });
+    if (!t.ok || !t.data || !t.data.task) return null;
+    const goalId = Number(t.data.task.goal_id);
+    if (!Number.isInteger(goalId) || goalId <= 0) return null;
+    return { goalId, taskId: claim.task_id, taskTitle: claim.title || t.data.task.title };
+  } catch (_) {
+    return null;
+  }
+}
+
+// fetchGoalSuggestion — the R07 suggester (GET /goals/suggestions), consulted
+// only when nothing else named a goal: criterion C5's "the filer never has to
+// know the goal map" promise. Returns the top candidate or null — no confident
+// match, no version to rank against, and any outage all degrade the same way,
+// because a suggester hiccup must never block a capture that would otherwise
+// file fine with no goal.
+async function fetchGoalSuggestion({ client = cliClient, version, title, kind } = {}) {
+  if (!version) return null;
+  try {
+    const api = await client();
+    // The GENERATED typed method (triage.js's precedent) — a path/param rename
+    // reds the client build instead of failing silently at runtime.
+    const r = await api.goals.getGoalsSuggestions({ query: { version, title: title || '', kind, limit: 1 } });
+    const top = r.ok && r.data && Array.isArray(r.data.suggestions) ? r.data.suggestions[0] : null;
+    return top ? { id: top.id, title: top.title, score: top.score } : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// sanitizeForTerminal — strip C0 control bytes (ANSI escapes among them) before
+// a builder/goal TITLE reaches the terminal unescaped. A title is user-authored
+// text this CLI does not own, and printing it raw would let one embed
+// cursor-control sequences in output a caller reads as plain status text
+// (grader finding, task 1003070).
+function sanitizeForTerminal(s) {
+  return String(s == null ? '' : s).replace(/[\x00-\x1f\x7f]/g, '');
+}
+
+// resolveGoalForCapture — the WHOLE of --goal resolution for one capture, in the
+// interview's own precedence: an explicit id wins outright; 'none' is a hard
+// opt-out (no default, no hint); otherwise the active-claim default runs, and
+// only when THAT yields nothing does the suggester offer a hint. `lines` are
+// ready-to-print strings rather than direct console.log calls, so the decision
+// is testable without capturing stdout. Never throws (both collaborators above
+// already degrade to null on their own).
+async function resolveGoalForCapture({ goalArg, version, title, kind, client = cliClient } = {}) {
+  const parsed = parseGoalArg(goalArg);
+  if (parsed.kind === 'id') return { goalId: parsed.id, lines: [] };
+  if (parsed.kind === 'none') return { goalId: null, lines: [] };
+
+  const defaulted = await resolveActiveClaimGoal({ client });
+  if (defaulted) {
+    return {
+      goalId: defaulted.goalId,
+      lines: [`↪ defaulting --goal to ${defaulted.goalId} from your active claim on task #${defaulted.taskId} ("${sanitizeForTerminal(defaulted.taskTitle)}") — override with --goal <id>, or --goal none to file homeless.`],
+    };
+  }
+
+  const hint = await fetchGoalSuggestion({ client, version, title, kind });
+  if (hint) {
+    return {
+      goalId: null,
+      lines: [`💡 possible home: goal ${hint.id} "${sanitizeForTerminal(hint.title)}" (score ${hint.score}) — re-run with --goal ${hint.id} (or --goal none to stay homeless on purpose).`],
+    };
+  }
+  return { goalId: null, lines: [] };
+}
+
 // 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
@@ -111,6 +230,7 @@ async function main() {
   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('       ... [--goal N | --goal none]        route into goal N; "none" files homeless on purpose');
     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)');
@@ -125,6 +245,12 @@ async function main() {
   const wantFull = hasFlag('--full', args);
   const fieldsFile = arg('--fields-file', args);
   const noPrompt = hasFlag('--no-prompt', args);
+  const goalArg = arg('--goal', args);
+
+  if (parseGoalArg(goalArg).kind === 'invalid') {
+    console.error(`--goal must be a positive goal id, or the literal "none" to file homeless (got "${goalArg}").`);
+    process.exit(2);
+  }
 
   // Refused rather than resolved: --spark and --full are contradictory requests
   // (a spark is a thought offered up BECAUSE it is not developed), and silently
@@ -182,6 +308,13 @@ async function main() {
 
   const version = versionFromArg || (await resolveDefaultVersion());
 
+  // --goal resolution (task 1003070 / R09): explicit id, explicit 'none', the
+  // active-claim default, or a suggester hint — see resolveGoalForCapture's own
+  // header for the precedence. Printed before the capture call so the operator
+  // sees the routing decision as context, not an afterthought.
+  const goalResolution = await resolveGoalForCapture({ goalArg, version, title, kind: kindFromArg });
+  for (const line of goalResolution.lines) console.log(line);
+
   const payload = {
     title,
     body_md: bodyMd,
@@ -189,6 +322,7 @@ async function main() {
     suggested_priority: priority,
   };
   if (kindFromArg) payload.kind = kindFromArg;
+  if (goalResolution.goalId != null) payload.goal_id = goalResolution.goalId;
   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.
@@ -199,11 +333,14 @@ async function main() {
   const api = await cliClient();
   const r = await api.inbox.postInbox({ body: payload });
   if (!r.ok) {
+    // Surfaced verbatim, on purpose (task 1003070): the server-side rank matrix
+    // (task 1003066) is the one place that decides whether a routed filing is
+    // authorized, and this CLI does not re-derive or soften its refusal.
     console.error(formatCaptureFailure(r.status, r.data));
     process.exit(1);
   }
 
-  const { idea, open_count, kind_auto } = r.data;
+  const { idea, open_count, kind_auto, routed_task } = r.data;
   const kindLabel = kind_auto ? `${idea.kind} (auto)` : idea.kind;
   const versionLabel = idea.suggested_version || 'none';
   const priorityLabel = idea.suggested_priority == null ? 'null' : `P${idea.suggested_priority}`;
@@ -212,6 +349,15 @@ async function main() {
   console.log(
     `Captured idea #${idea.id}: kind=${kindLabel}, version=${versionLabel}, priority=${priorityLabel}${gradeLabel}`
   );
+  // task 1003070 (R09): say where a named goal actually landed. `idea.routing`
+  // is always present when goal_id was sent (routed, or a named reason it
+  // wasn't — POST /inbox's own landing matrix decides, not this CLI).
+  if (routed_task) {
+    console.log(`  → routed into goal ${idea.routing?.goal_id ?? goalResolution.goalId} as task #${routed_task.id} (${idea.routing?.status || routed_task.status})`);
+  } else if (goalResolution.goalId != null) {
+    const reason = idea.routing?.reason;
+    console.log(`  (goal ${goalResolution.goalId} named, but filed to the inbox instead${reason ? ` — ${reason}` : ''})`);
+  }
   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.
@@ -257,7 +403,10 @@ async function main() {
   // referred to; promotion to a task re-runs the detection automatically.
 }
 
-module.exports = { resolveDefaultVersion, formatCaptureFailure, acceptsOffer };
+module.exports = {
+  resolveDefaultVersion, formatCaptureFailure, acceptsOffer,
+  parseGoalArg, resolveActiveClaimGoal, fetchGoalSuggestion, resolveGoalForCapture, sanitizeForTerminal,
+};
 
 if (require.main === module) {
   main().catch((err) => {

package/scripts/gds/seed-bongos-v1-idea-routing-tasks.js

@@ -1,9 +1,13 @@
 // Seed the tasks for goal 1000071 "Idea routing — work that has a home lands in it" (BONGOS-V1).
 // Source of truth: docs/specs/bongos-v1-idea-routing.md (status: final).
 // Idempotent on (source, source_ref). Re-running resolves to the existing rows.
+// Reference implementation (task 1003076) for the seeding contract's self-check:
+// ends by tallying the criterion_ids it actually POSTed and diffing that plan
+// against GET /goals/<id>'s real linked_tasks — see seed-verify-criteria.js.
 //
 // Run: node scripts/gds/seed-bongos-v1-idea-routing-tasks.js
 const os = require('os');
+const { expectedCriterionCounts, verifySeedCriteriaLinks } = require('./seed-verify-criteria');
 const sess = require(os.homedir() + '/.config/cloudbongos/gds-session.json');
 const BASE = sess.api_base.replace(/\/$/, '');
 const TOKEN = sess.token;
@@ -73,14 +77,24 @@ const ROOTS = ['R02', 'R03', 'R07', 'R10', 'R14']; // zero-dep, non-spike → op
 (async () => {
   const idByRef = {};
   let created = 0, existing = 0;
+  // Resolved (post-CRIT-mapping) criterion_ids per task — the plan the final
+  // self-check diffs against, kept in lockstep with what's actually POSTed
+  // below rather than re-derived from the raw "Cn" tokens.
+  const criterionIdListsPerTask = [];
   console.log(`Seeding ${TASKS.length} tasks under goal ${GOAL} (${VER})…`);
   for (const t of TASKS) {
+    const criterionIds = t.crit.map((c) => CRIT[c]);
     const r = await api('POST', '/tasks', {
       version_id: VER, goal_id: GOAL, title: t.title, description: t.desc,
       kind: t.kind, discipline: t.disc, priority: t.prio, est_minutes: t.est,
-      criterion_ids: t.crit.map((c) => CRIT[c]), source: SRC, source_ref: `bongos-v1-idea-routing-${t.ref}`,
+      criterion_ids: criterionIds, source: SRC, source_ref: `bongos-v1-idea-routing-${t.ref}`,
     });
     if (!r.ok) { console.log(`  ${t.ref}: FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    // Only a task that actually landed contributes to the self-check's plan —
+    // a failed POST is already reported above as FAILED, not as a criterion
+    // mismatch (task 1003076 grade finding: counting it here regardless of
+    // r.ok blamed a real create failure on the wrong cause).
+    criterionIdListsPerTask.push(criterionIds);
     const task = r.json.task || r.json;
     idByRef[t.ref] = task.id;
     if (r.json.idempotent || r.json.existing) existing++; else created++;
@@ -118,4 +132,14 @@ const ROOTS = ['R02', 'R03', 'R07', 'R10', 'R14']; // zero-dep, non-spike → op
 
   console.log(`\nDONE. created=${created} existing=${existing} depEdges=${edges}. Roots opened: ${ROOTS.join(', ')}.`);
   console.log('ref→id:', JSON.stringify(idByRef));
+
+  // Self-check (task 1003076): fetch the goal back and confirm every
+  // criterion's linked_tasks matches what was actually POSTed — exits 1 loudly
+  // on any mismatch instead of a seed that mislinks and reports success.
+  console.log('Verifying criterion links against the plan…');
+  await verifySeedCriteriaLinks({
+    goalId: GOAL,
+    expectedCounts: expectedCriterionCounts(criterionIdListsPerTask),
+    fetchGoal: (id) => api('GET', `/goals/${id}`),
+  });
 })();

package/scripts/gds/seed-verify-criteria.js

@@ -0,0 +1,69 @@
+// scripts/gds/seed-verify-criteria.js — the seed-script self-check: did the
+// criterion links actually land where the plan said (task 1003076, retro on
+// goal 1000071 — the idea-routing seeder linked all 15 tasks to the WRONG
+// criteria via positional "Cn" tokens (learning 1000188) and still printed
+// success; only a manual GET /goals rollup caught it, after the fact). A seed
+// script tallies the criterion_ids it actually POSTed per task into its own
+// plan, then calls verifySeedCriteriaLinks() as its LAST step to fetch
+// GET /api/gds/goals/<id> and diff `criteria[].linked_tasks` against that
+// plan — loud and non-zero-exit on any mismatch, zero included.
+//
+// Transport-agnostic on purpose: seed scripts don't share one HTTP client
+// (some use cli-lib's apiCall, others a local throttled fetch — see the
+// scripts/gds/CLAUDE.md roster), so this takes a `fetchGoal(goalId)` callback
+// rather than assuming a client shape.
+
+// diffCriterionLinks — pure comparison: expected (slug -> count, tallied from
+// the criterion_ids actually POSTed) vs actual (the `criteria` rows
+// GET /goals/:id returns, each carrying criterion_id + linked_tasks). Returns
+// every mismatching slug, including one present on only one side.
+function diffCriterionLinks(expectedCounts, criteriaRows) {
+  const actual = {};
+  for (const row of criteriaRows || []) {
+    actual[row.criterion_id] = Number(row.linked_tasks) || 0;
+  }
+
+  const slugs = new Set([...Object.keys(expectedCounts || {}), ...Object.keys(actual)]);
+  const mismatches = [];
+  for (const slug of slugs) {
+    const expected = (expectedCounts && expectedCounts[slug]) || 0;
+    const got = actual[slug] || 0;
+    if (expected !== got) mismatches.push({ criterion_id: slug, expected, actual: got });
+  }
+  return mismatches.sort((a, b) => a.criterion_id.localeCompare(b.criterion_id));
+}
+
+// expectedCriterionCounts — tally a seed script's per-task criterion_ids
+// (already resolved to real slugs, post any "Cn" -> slug mapping) into
+// { slug: count }. Callers pass one array per task so the plan is derived from
+// exactly what got POSTed, not a second hand-maintained total.
+function expectedCriterionCounts(criterionIdListsPerTask) {
+  const counts = {};
+  for (const ids of criterionIdListsPerTask || []) {
+    for (const slug of ids || []) counts[slug] = (counts[slug] || 0) + 1;
+  }
+  return counts;
+}
+
+// verifySeedCriteriaLinks — Phase-5 self-check: fetch the goal, diff its
+// linked_tasks against the plan, and exit(1) loudly on any mismatch (a zero
+// where tasks were expected is the shape that shipped silently in the
+// RETRO2 incident, but any drift is worth stopping the seed for).
+async function verifySeedCriteriaLinks({ goalId, expectedCounts, fetchGoal, log = console.log, exit = process.exit }) {
+  const r = await fetchGoal(goalId);
+  const body = (r && (r.json || r.data)) || null;
+  if (!r || !r.ok || !body || !Array.isArray(body.criteria)) {
+    log(`VERIFY FAILED: GET goal ${goalId} did not return a criteria list (status ${r && r.status}). Cannot confirm criterion links landed.`);
+    return exit(1);
+  }
+  const mismatches = diffCriterionLinks(expectedCounts, body.criteria);
+  if (mismatches.length) {
+    log(`VERIFY FAILED: criterion links on goal ${goalId} do not match the plan (${mismatches.length} mismatch${mismatches.length === 1 ? '' : 'es'}):`);
+    for (const m of mismatches) log(`  ${m.criterion_id}: expected ${m.expected} linked task(s), got ${m.actual}`);
+    log('Likely cause: a criterion_ids mapping bug (e.g. a positional "Cn" token resolved against the wrong scope — learning 1000188). Fix and re-run before trusting this seed.');
+    return exit(1);
+  }
+  log(`VERIFY OK: all ${Object.keys(expectedCounts || {}).length} criteria on goal ${goalId} carry their planned task count.`);
+}
+
+module.exports = { diffCriterionLinks, expectedCriterionCounts, verifySeedCriteriaLinks };

package/src/module-api.js

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

package/tests/capture_goal_routing.mjs

@@ -0,0 +1,242 @@
+// tests/capture_goal_routing.mjs
+//
+// task 1003070 (R09 of goal 1000071, idea routing) — capture.js gains --goal.
+// Interview decision 4: "CLI capture defaults the goal to the active claim's
+// goal. The suggester still shows alternatives; --goal overrides." This pins
+// the WHOLE of that precedence (parseGoalArg → resolveGoalForCapture) DB-free,
+// the promote_goal_id.mjs way: stub the generated typed client, drive the real
+// exported functions, assert both the outcome and which collaborators ran.
+//
+// Run:  node tests/capture_goal_routing.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+
+const capture = require('../scripts/gds/capture.js');
+const CAPTURE_SRC = readFileSync(new URL('../scripts/gds/capture.js', import.meta.url), 'utf8');
+
+// A stub of the generated typed client (triage.js / promote_goal_id.mjs's
+// pattern): records every call, answers from a fixed script. `client` is the
+// injectable collaborator every function under test accepts.
+function stubClient({ me, task, suggestions } = {}) {
+  const calls = { me: 0, tasksId: [], suggestions: [] };
+  const client = async () => ({
+    me: { getMe: async () => { calls.me++; return me; } },
+    tasks: { getTasksId: async (req) => { calls.tasksId.push(req); return task; } },
+    goals: { getGoalsSuggestions: async (req) => { calls.suggestions.push(req); return suggestions; } },
+  });
+  return { client, calls };
+}
+
+// ---------------------------------------------------------------------------
+// parseGoalArg — pure
+// ---------------------------------------------------------------------------
+
+await test('parseGoalArg: "none" (any case/whitespace) is the explicit opt-out', () => {
+  for (const raw of ['none', 'None', 'NONE', '  none  ']) {
+    assert.deepEqual(capture.parseGoalArg(raw), { kind: 'none' });
+  }
+});
+
+await test('parseGoalArg: a positive integer string is an id', () => {
+  assert.deepEqual(capture.parseGoalArg('1000071'), { kind: 'id', id: 1000071 });
+  assert.deepEqual(capture.parseGoalArg('7'), { kind: 'id', id: 7 });
+});
+
+await test('parseGoalArg: absent (null/undefined) is unset, not invalid', () => {
+  assert.deepEqual(capture.parseGoalArg(null), { kind: 'unset' });
+  assert.deepEqual(capture.parseGoalArg(undefined), { kind: 'unset' });
+});
+
+await test('parseGoalArg: junk is invalid, never silently coerced to a goal', () => {
+  for (const raw of ['0', '-3', '4.5', 'abc', '', 'goal 7']) {
+    assert.deepEqual(capture.parseGoalArg(raw), { kind: 'invalid' }, `"${raw}" must be invalid`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// sanitizeForTerminal — strip control bytes (grader finding, task 1003070):
+// a task/goal TITLE reaches the terminal unescaped otherwise.
+// ---------------------------------------------------------------------------
+
+await test('sanitizeForTerminal: strips C0 control bytes (ANSI escapes among them)', () => {
+  assert.equal(capture.sanitizeForTerminal('\x1b[31mred\x1b[0m title'), '[31mred[0m title');
+  assert.equal(capture.sanitizeForTerminal('a\tb\nc'), 'abc');
+});
+
+await test('sanitizeForTerminal: plain text and null/undefined pass through safely', () => {
+  assert.equal(capture.sanitizeForTerminal('ordinary title'), 'ordinary title');
+  assert.equal(capture.sanitizeForTerminal(null), '');
+  assert.equal(capture.sanitizeForTerminal(undefined), '');
+});
+
+await test('WIRING: the printed default/hint lines route the title through sanitizeForTerminal', () => {
+  assert.match(CAPTURE_SRC, /sanitizeForTerminal\(defaulted\.taskTitle\)/);
+  assert.match(CAPTURE_SRC, /sanitizeForTerminal\(hint\.title\)/);
+});
+
+// ---------------------------------------------------------------------------
+// resolveActiveClaimGoal — one /me + one GET /tasks/:id
+// ---------------------------------------------------------------------------
+
+await test('resolveActiveClaimGoal: reads the goal off the active claim\'s task', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Fix the thing', claim_id: 9 }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000071, title: 'Fix the thing' } } },
+  });
+  const r = await capture.resolveActiveClaimGoal({ client });
+  assert.deepEqual(r, { goalId: 1000071, taskId: 55, taskTitle: 'Fix the thing' });
+});
+
+await test('resolveActiveClaimGoal: no active claim → null, no task lookup', async () => {
+  const { client, calls } = stubClient({ me: { ok: true, data: { active_claims: [] } } });
+  const r = await capture.resolveActiveClaimGoal({ client });
+  assert.equal(r, null);
+  assert.equal(calls.tasksId.length, 0);
+});
+
+await test('resolveActiveClaimGoal: claimed task has no goal → null', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claim: { task_id: 55, title: 'x' } } },
+    task: { ok: true, data: { task: { id: 55, goal_id: null, title: 'x' } } },
+  });
+  assert.equal(await capture.resolveActiveClaimGoal({ client }), null);
+});
+
+await test('resolveActiveClaimGoal: a /me outage degrades to null, never throws', async () => {
+  const client = async () => ({ me: { getMe: async () => { throw new Error('ECONNREFUSED'); } } });
+  assert.equal(await capture.resolveActiveClaimGoal({ client }), null);
+});
+
+await test('resolveActiveClaimGoal: a non-ok /me degrades to null', async () => {
+  const { client } = stubClient({ me: { ok: false, status: 500, data: null } });
+  assert.equal(await capture.resolveActiveClaimGoal({ client }), null);
+});
+
+// ---------------------------------------------------------------------------
+// fetchGoalSuggestion — the R07 suggester, consulted last
+// ---------------------------------------------------------------------------
+
+await test('fetchGoalSuggestion: no version → null, no network call at all', async () => {
+  const { client, calls } = stubClient({ suggestions: { ok: true, data: { suggestions: [{ id: 1, title: 't', score: 9 }] } } });
+  const r = await capture.fetchGoalSuggestion({ client, version: null, title: 't' });
+  assert.equal(r, null);
+  assert.equal(calls.suggestions.length, 0);
+});
+
+await test('fetchGoalSuggestion: top suggestion returned', async () => {
+  const { client, calls } = stubClient({
+    suggestions: { ok: true, data: { suggestions: [{ id: 1000071, title: 'Idea routing', score: 7 }] } },
+  });
+  const r = await capture.fetchGoalSuggestion({ client, version: 'BV1', title: 'fix the routing', kind: 'bug' });
+  assert.deepEqual(r, { id: 1000071, title: 'Idea routing', score: 7 });
+  assert.equal(calls.suggestions[0].query.version, 'BV1');
+  assert.equal(calls.suggestions[0].query.title, 'fix the routing');
+  assert.equal(calls.suggestions[0].query.limit, 1);
+});
+
+await test('fetchGoalSuggestion: no confident match → null', async () => {
+  const { client } = stubClient({ suggestions: { ok: true, data: { suggestions: [] } } });
+  assert.equal(await capture.fetchGoalSuggestion({ client, version: 'BV1', title: 't' }), null);
+});
+
+await test('fetchGoalSuggestion: an outage degrades to null, never throws', async () => {
+  const client = async () => ({ goals: { getGoalsSuggestions: async () => { throw new Error('boom'); } } });
+  assert.equal(await capture.fetchGoalSuggestion({ client, version: 'BV1', title: 't' }), null);
+});
+
+// ---------------------------------------------------------------------------
+// resolveGoalForCapture — the whole precedence, as capture.js's main() sees it
+// ---------------------------------------------------------------------------
+
+await test('--goal N: sends that goal id verbatim; no active-claim or suggester lookup', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 1, title: 'x' }] } },
+    task: { ok: true, data: { task: { id: 1, goal_id: 999 } } },
+    suggestions: { ok: true, data: { suggestions: [{ id: 5, title: 'y', score: 1 }] } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: '42', version: 'BV1', title: 't', client });
+  assert.deepEqual(r, { goalId: 42, lines: [] });
+  assert.equal(calls.me, 0, 'the active-claim default must not even be consulted');
+  assert.equal(calls.suggestions.length, 0, 'the suggester must not even be consulted');
+});
+
+await test('--goal none: sends no goal_id and skips the active-claim default entirely', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 1, title: 'x' }] } },
+    task: { ok: true, data: { task: { id: 1, goal_id: 999 } } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: 'none', version: 'BV1', title: 't', client });
+  assert.deepEqual(r, { goalId: null, lines: [] });
+  assert.equal(calls.me, 0, '--goal none is a hard opt-out — it must not look up the active claim');
+});
+
+await test('no --goal: the active-claim default fires and names how to opt out', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'Fix the thing' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: 1000071, title: 'Fix the thing' } } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 't', client });
+  assert.equal(r.goalId, 1000071);
+  assert.equal(r.lines.length, 1);
+  assert.match(r.lines[0], /1000071/);
+  assert.match(r.lines[0], /#55/);
+  assert.match(r.lines[0], /--goal none/, 'must say how to opt out');
+  assert.equal(calls.suggestions.length, 0, 'a resolved default skips the suggester');
+});
+
+await test('no --goal, no active claim: the suggester hint prints, with the re-run command', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claims: [] } },
+    suggestions: { ok: true, data: { suggestions: [{ id: 1000058, title: 'Some other goal', score: 5 }] } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 't', client });
+  assert.equal(r.goalId, null, 'a hint is an offer, never an auto-pick');
+  assert.equal(r.lines.length, 1);
+  assert.match(r.lines[0], /1000058/);
+  assert.match(r.lines[0], /--goal 1000058/, 'must give the exact re-run command');
+});
+
+await test('no --goal, no active claim, no confident suggestion: silent — no lines', async () => {
+  const { client } = stubClient({
+    me: { ok: true, data: { active_claims: [] } },
+    suggestions: { ok: true, data: { suggestions: [] } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 't', client });
+  assert.deepEqual(r, { goalId: null, lines: [] });
+});
+
+await test('active claim exists but its task has no goal: falls through to the suggester', async () => {
+  const { client, calls } = stubClient({
+    me: { ok: true, data: { active_claims: [{ task_id: 55, title: 'x' }] } },
+    task: { ok: true, data: { task: { id: 55, goal_id: null, title: 'x' } } },
+    suggestions: { ok: true, data: { suggestions: [{ id: 3, title: 'z', score: 2 }] } },
+  });
+  const r = await capture.resolveGoalForCapture({ goalArg: null, version: 'BV1', title: 't', client });
+  assert.equal(r.goalId, null);
+  assert.equal(calls.suggestions.length, 1, 'a goal-less claimed task must still fall through to the hint');
+});
+
+// ---------------------------------------------------------------------------
+// STATIC — main()'s wiring a unit test cannot invoke directly (argv, TTY, fs).
+// ---------------------------------------------------------------------------
+
+await test('WIRING: main() sends resolveGoalForCapture\'s id on the capture payload, only when resolved', () => {
+  assert.match(CAPTURE_SRC, /if \(goalResolution\.goalId != null\) payload\.goal_id = goalResolution\.goalId;/);
+});
+
+await test('WIRING: main() reads routed_task off the response and reports where it landed', () => {
+  assert.match(CAPTURE_SRC, /const \{ idea, open_count, kind_auto, routed_task \} = r\.data;/);
+  assert.match(CAPTURE_SRC, /routed into goal/);
+});
+
+await test('WIRING: a routing refusal is surfaced through the existing verbatim error path, not re-derived', () => {
+  assert.match(CAPTURE_SRC, /console\.error\(formatCaptureFailure\(r\.status, r\.data\)\);/);
+});
+
+summary();