@bongos/core 1.19.586 → 1.19.588

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.586",
+  "version": "1.19.588",
   "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/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.586'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.588'; // 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/filing_abuse_matrix.mjs

@@ -33,8 +33,12 @@
 //   F16 file through #bugs as an UNLINKED author               → an inbox row, never work
 //   F13 declare touches[] outside the goal to widen blast area → the real wall refuses
 //   F14 file against a SHIPPED version's goal                  → refused (version not building)
+//   F17 get a keyword-guessed 'bug' from #ideas to mint work   → cannot: vector not trusted
+//   F18 forge/omit the vector to reach the homeless-bug door   → fail-closed, an inbox row
+//   F19 file a homeless NON-bug hoping for a free home         → inbox; only bugs get one
 //   P1  a Metic+ files a bug in an ordinary goal               → 'ready' (the C1 grant)
 //   P2  a Metic+ files into protected scope                    → allowed, floored to metic
+//   P3  a Metic+ files a HOMELESS bug from a trusted vector    → 'ready', in the maintenance goal
 //
 // AND THE ANTI-DRIFT PIN (the point of the file, really). The rows above are true
 // of the capture vectors that exist TODAY. Nothing stops a fifth being added
@@ -337,6 +341,101 @@ await test('[F16] an unlinked #bugs author gets an inbox row and CANNOT reach wo
   const code = src.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
   assert.match(code, /if \(builder\) \{[\s\S]{0,200}suggestGoalForCapture/,
     'a goal is only ever sought for a LINKED builder');
+
+  // ADR 0262 REOPENED THIS AND IT HAD TO BE CLOSED AGAIN — a grader blocker on
+  // task 1003691, and the reason the vector is CONDITIONAL at the call site.
+  //
+  // The rows above pass a rank but no VECTOR, so they kept passing while the real
+  // path had already changed: #bugs briefly set `vector: 'discord-bugs'`
+  // unconditionally, which meant an unlinked poster (filerRank null, goalId null —
+  // the goal is only sought `if (builder)`) took the homeless-bug branch and minted
+  // a real backlog task. Worse, the rolling rate cap is counted per builder id and
+  // so does not run at all for them: unattributed task creation at no cost.
+  //
+  // Both halves are pinned now — the decision, and the call site that feeds it.
+  assert.equal(
+    decideLanding({ goalId: null, kind: 'bug', filerRank: null, vector: 'discord-bugs' }).route,
+    true,
+    'sanity: the vector DOES open the homeless branch, so the gate below is what protects it'
+  );
+  assert.match(code, /vector:\s*builder\s*\?\s*'discord-bugs'\s*:\s*null/,
+    'the trusted vector is claimed ONLY for a linked builder — never the bare string');
+  assert.ok(!/vector:\s*'discord-bugs'\s*,/.test(code),
+    'an unconditional vector here is the blocker this row exists to catch');
+});
+
+// =========================================================================
+// F17–F19 + P3 — the HOMELESS-BUG door (task 1003691, ADR 0262)
+//
+// ADR 0262 opened one new way for a filing to become work: a kind='bug' with NO
+// goal now routes to the version's maintenance goal instead of parking in the
+// inbox. A new door is a new attack surface, so it gets its own rows.
+//
+// THE ATTACKER'S BEST MOVE HERE is not rank — it is the VECTOR. #ideas passes no
+// kind, so inbox.classify() guesses one from keywords, and its bug pattern fires
+// on fix/broken/bug/crash/error anywhere in the text. If the kind alone opened the
+// door, "we should fix the copy on the landing page" would mint a task, and ADR
+// 0234's owner-interview decision ("#ideas files with HINTS only, never routes")
+// would be dead without anyone deciding to kill it.
+// =========================================================================
+
+await test('[F17] a keyword-guessed bug from #ideas still cannot mint work', () => {
+  // The guess is real: prove the classifier does fire, then prove it buys nothing.
+  const inbox = require('../modules/ideas/inbox.js');
+  for (const text of ['we should fix the copy on the landing page',
+    'the onboarding flow feels broken to me',
+    'error messages could be friendlier']) {
+    assert.equal(inbox.classify(text, ''), 'bug', `classifier guesses bug for: ${text}`);
+  }
+  // …and #ideas's vector is not on the allowlist, so every one of them is an inbox row.
+  assert.deepEqual(
+    decideLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector: 'discord-ideas' }),
+    { route: false, reason: 'no_goal' },
+    'ADR 0234 holds: #ideas files hints, never work'
+  );
+});
+
+await test('[F18] the vector fails CLOSED — forged, absent or unknown never opens the door', () => {
+  for (const vector of [undefined, null, '', 'api ', 'API', 'discord_bugs', 'cli',
+    'internal', 'trusted', true, 1, {}, ['api']]) {
+    assert.equal(
+      decideLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector }).route,
+      false,
+      `vector ${JSON.stringify(vector)} must not route`
+    );
+  }
+  // The allowlist is exactly two members, and both are server-set at their call
+  // site — never read from a request body, which is what makes forging it a
+  // non-move rather than a merely-hard one.
+  assert.deepEqual([...routing.HOMELESS_ROUTING_VECTORS].sort(), ['api', 'discord-bugs']);
+  const routeSrc = read('modules/ideas/routes/inbox.js');
+  assert.match(routeSrc, /vector: 'api'/, 'the route hardcodes its own vector');
+  assert.ok(!/vector:\s*body\.|vector:\s*req\.body/.test(routeSrc),
+    'and never takes it from the request body');
+});
+
+await test('[F19] only a BUG gets a free home — every other homeless kind stays in the inbox', () => {
+  // Otherwise the door empties the inbox by fabricating homes for work that
+  // genuinely has none, which is the opposite of what ADR 0262 decided.
+  for (const kind of ['feature', 'cleanup', 'refactor', 'infra', 'spike',
+    'learning-capture', 'blocker-resolution', 'unclassified',
+    'criterion-proposal', 'decision']) {
+    assert.equal(
+      decideLanding({ goalId: null, kind, filerRank: 'archon', vector: 'api' }).route,
+      false,
+      `kind ${kind}`
+    );
+  }
+});
+
+await test('[P3] a Metic+ homeless bug IS claimable — the grant the door exists for', () => {
+  const d = decideLanding({ goalId: null, kind: 'bug', filerRank: 'metic', vector: 'api' });
+  assert.equal(d.route, true);
+  assert.equal(d.status, 'ready', 'no triage stop between reported and in the queue (C1)');
+  assert.equal(d.homeless, true, 'and it is flagged, so the transaction knows to resolve a home');
+  // A sub-Metic gets the same door but not the same speed.
+  assert.equal(decideLanding({ goalId: null, kind: 'bug', filerRank: 'xenos', vector: 'api' }).status,
+    'backlog');
 });
 
 // =========================================================================

package/tests/idea_routing.mjs

@@ -41,11 +41,25 @@ const seams = require('../src/module-seams.js');
 seams._reset();
 let createTaskCalls = [];
 let createTaskImpl = async () => ({ id: 9001, status: 'backlog', goal_id: 7 });
+// task 1003691 (ADR 0262): the homeless-bug home. Both are port calls, so the
+// stub is what lets the transaction be driven without a Postgres — and the CALL
+// LOG is the assertion surface: `deps.client` proving they ran inside the tx.
+let maintenanceCalls = [];
+let currentVersionImpl = async () => 'BONGOS-V1';
+let ensureMaintenanceImpl = async () => ({ id: 77, version_id: 'BONGOS-V1', status: 'open' });
 seams.registerProvider('lifecycle', {
   createTask: async (args, deps) => {
     createTaskCalls.push({ args, deps });
     return createTaskImpl(args, deps);
   },
+  currentBuildingVersionId: async (deps) => {
+    maintenanceCalls.push({ fn: 'currentBuildingVersionId', deps });
+    return currentVersionImpl(deps);
+  },
+  ensureMaintenanceGoal: async (versionId, deps) => {
+    maintenanceCalls.push({ fn: 'ensureMaintenanceGoal', versionId, deps });
+    return ensureMaintenanceImpl(versionId, deps);
+  },
 });
 
 const inbox = require('../modules/ideas/inbox.js');
@@ -91,13 +105,21 @@ function routableHandler(overrides = {}) {
 function reset() {
   createTaskCalls = [];
   createTaskImpl = async () => ({ id: 9001, status: 'backlog', goal_id: 7 });
+  maintenanceCalls = [];
+  currentVersionImpl = async () => 'BONGOS-V1';
+  ensureMaintenanceImpl = async () => ({ id: 77, version_id: 'BONGOS-V1', status: 'open' });
 }
 
+// The maintenance goal a homeless bug is routed into: id 77, open, on a building
+// version — the same shape the goal read returns for any other routed filing, so
+// everything downstream of (a0) runs unchanged.
+const MAINT_GOAL = { id: 77, status: 'open', version_id: 'BONGOS-V1', version_status: 'building', scope_modules: [] };
+
 // =========================================================================
 // 1. The landing matrix — pure, every cell
 // =========================================================================
 
-await test('matrix: NO GOAL means the inbox, and that is the default path', () => {
+await test('matrix: NO GOAL and no trusted vector means the inbox, and that is the default path', () => {
   for (const goalId of [null, undefined, '']) {
     const d = decideLanding({ goalId, kind: 'bug', filerRank: 'archon' });
     assert.equal(d.route, false, `goalId=${JSON.stringify(goalId)} must not route`);
@@ -105,6 +127,14 @@ await test('matrix: NO GOAL means the inbox, and that is the default path', () =
   }
   // A bug filed by an Archon is the MOST routable thing there is — proving it
   // still stays put without a goal is what pins "routing is strictly additive".
+  //
+  // TASK 1003691 (ADR 0262) NARROWED THIS PIN RATHER THAN DELETING IT, and the
+  // distinction matters. A homeless BUG now routes — but only from a vector on
+  // routing.HOMELESS_ROUTING_VECTORS, and no `vector` is passed above. So this
+  // case is still exactly true, and it is now pinning something sharper than it
+  // was: that the vector allowlist FAILS CLOSED. An absent vector is untrusted,
+  // so every caller that predates ADR 0262 keeps landing in the inbox, and so
+  // does any capture path added later that forgets to declare itself.
 });
 
 await test('matrix: a bug from a trusted filer HARD-LANDS at ready (criterion C1)', () => {
@@ -132,6 +162,83 @@ await test('matrix: FAIL-CLOSED — an absent or unrecognised rank never hard-la
   }
 });
 
+// -------------------------------------------------------------------------
+// 1b. THE HOMELESS BUG (task 1003691, ADR 0262) — "a bug never lands in the inbox"
+//
+// The hole this closed: the no-goal early return above made the kind==='bug'
+// branch UNREACHABLE without a goal, so `kind` only ever chose a routed task's
+// STATUS, never whether it routed. A reported defect with no goal named sat in
+// idea_inbox waiting for the triage pass criterion C1 exists to remove.
+// -------------------------------------------------------------------------
+
+await test('matrix: a homeless BUG from a trusted vector routes, and keeps the rank split', () => {
+  for (const vector of ['api', 'discord-bugs']) {
+    assert.deepEqual(
+      decideLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector }),
+      { route: true, status: 'ready', homeless: true, reason: 'bug_homeless_trusted_filer' },
+      `trusted filer via ${vector}`
+    );
+    assert.deepEqual(
+      decideLanding({ goalId: null, kind: 'bug', filerRank: 'xenos', vector }),
+      { route: true, status: 'backlog', homeless: true, reason: 'bug_homeless_awaiting_nod' },
+      `sub-Metic via ${vector}`
+    );
+  }
+});
+
+await test('matrix: a homeless bug FAILS CLOSED on rank, exactly as a homed one does', () => {
+  // Same property as the homed case: no rank input reaches 'ready' except a real
+  // trusted tier. A homeless bug is filed by definition without a goal's scope
+  // wall in play, so this is the only rank gate standing on this path.
+  for (const rank of [null, undefined, '', 'archon-ish', 'admin', 'root', 0, {}, []]) {
+    const d = decideLanding({ goalId: null, kind: 'bug', filerRank: rank, vector: 'api' });
+    assert.equal(d.status, 'backlog', `rank ${JSON.stringify(rank)} must not reach ready`);
+    assert.equal(d.reason, 'bug_homeless_awaiting_nod');
+  }
+});
+
+await test('matrix: the VECTOR is the gate — an untrusted or unknown door never routes homeless', () => {
+  // The ADR 0234 guarantee, kept: #ideas passes no kind at all, so inbox.classify
+  // GUESSES one from keywords ("should we fix the copy" ⇒ 'bug'). A guess must not
+  // mint work, and the allowlist is what stops it. Unknown values fail closed too,
+  // so a typo'd or attacker-supplied vector is inert rather than trusted.
+  for (const vector of ['discord-ideas', null, undefined, '', 'API', 'api ', 'cli',
+    'discord_bugs', 'unknown', 0, {}, []]) {
+    assert.deepEqual(
+      decideLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector }),
+      { route: false, reason: 'no_goal' },
+      `vector ${JSON.stringify(vector)} must not route a homeless bug`
+    );
+  }
+});
+
+await test('matrix: homeless routing is for BUGS only — no other kind gets a free home', () => {
+  // A homeless feature/cleanup/refactor is exactly the "work that has no home"
+  // the inbox is FOR. Widening this to every kind would empty the inbox by
+  // fabricating homes, which is the opposite of what ADR 0262 decided.
+  for (const kind of ['feature', 'cleanup', 'refactor', 'infra', 'spike',
+    'learning-capture', 'blocker-resolution', 'unclassified',
+    'criterion-proposal', 'decision']) {
+    assert.deepEqual(
+      decideLanding({ goalId: null, kind, filerRank: 'archon', vector: 'api' }),
+      { route: false, reason: 'no_goal' },
+      `kind ${kind} must not route without a goal`
+    );
+  }
+});
+
+await test('matrix: a homeless FULL IDEA never routes, even kinded bug from an Archon (F8 holds)', () => {
+  // The Board Room's subject is ratified by peers, never converted by its own
+  // filer — and that must not become reachable through the new door.
+  for (const grade of ['full', 'FULL', 'Full']) {
+    assert.deepEqual(
+      decideLanding({ goalId: null, kind: 'bug', grade, filerRank: 'archon', vector: 'api' }),
+      { route: false, reason: 'no_goal' },
+      `grade ${grade}`
+    );
+  }
+});
+
 await test('matrix: every non-bug kind soft-lands, whoever files it (interview Q1)', () => {
   // "Bugs are urgent-true; the rest gets a nod." cleanup/refactor/infra were the
   // open question the owner settled — they soft-land like features, not like bugs.
@@ -888,4 +995,122 @@ await test('GET /inbox/awaiting-nod is registered BEFORE /inbox/:id, or it is un
   assert.ok(iNod < iParam, `literal segment must precede the wildcard (got ${iNod} vs ${iParam})`);
 });
 
+// =========================================================================
+// 5. THE HOMELESS-BUG TRANSACTION (task 1003691, ADR 0262)
+//
+// The matrix decides; this is the transaction that acts on it. The property
+// under test is the same one the rest of this file exists for: the idea row, the
+// TASK and its lineage commit together, and the home the task lands in is a REAL
+// open goal — so ADR 0250 D4's "every task belongs to a goal" holds on the one
+// path that has no goal to be given.
+// =========================================================================
+
+await test('homeless bug: resolves the version, then its maintenance goal, INSIDE the transaction', async () => {
+  reset();
+  const pool = fakePool((s) => {
+    if (/FROM goals g JOIN versions v/.test(s)) return { rows: [MAINT_GOAL] };
+    if (/INSERT INTO idea_inbox/.test(s)) return { rows: [{ ...IDEA_ROW, suggested_goal_id: 77 }] };
+    return null;
+  });
+  const idea = await captureIdea(
+    { title: 'the build is broken', kind: 'bug', capturedBy: 42, filerRank: 'archon', vector: 'api' },
+    { pool }
+  );
+
+  const sqls = seq(pool.queries);
+  assert.ok(sqls.some((q) => /^BEGIN$/.test(q)), 'a transaction IS opened — unlike the inbox path');
+  assert.ok(sqls.some((q) => /^COMMIT$/.test(q)), 'and it commits');
+
+  // Both port calls ran, in order, ON THE TRANSACTION CLIENT. The client is the
+  // whole point: a goal created on its own connection would survive a rolled-back
+  // route as an empty goal nobody asked for.
+  assert.deepEqual(maintenanceCalls.map((c) => c.fn),
+    ['currentBuildingVersionId', 'ensureMaintenanceGoal'],
+    'version first — the order inverts here, because there is no goal to read it off');
+  for (const c of maintenanceCalls) {
+    assert.ok(c.deps && c.deps.client, `${c.fn} runs on the tx client, not the pool`);
+  }
+  assert.equal(maintenanceCalls[1].versionId, 'BONGOS-V1', 'the resolved version is the one asked about');
+
+  // The task landed in the maintenance goal, at the matrix's status.
+  assert.equal(createTaskCalls.length, 1, 'exactly one task');
+  assert.equal(createTaskCalls[0].args.goalId, 77, 'the task carries a REAL goal id — ADR 0250 D4 holds');
+  assert.equal(createTaskCalls[0].args.versionId, 'BONGOS-V1', "and the goal's version, as every routed filing does");
+  assert.equal(createTaskCalls[0].args.status, 'ready', 'an Archon bug is claimable immediately (C1)');
+  assert.equal(createTaskCalls[0].args.kind, 'bug');
+  // createTask's own catch-all escape hatch is NOT used — this vector adds no
+  // third `allowCatchAll` caller, which db-tasks.js explicitly warns against.
+  assert.ok(!('allowCatchAll' in createTaskCalls[0].args),
+    'allowCatchAll is never passed: the goal is real, so the fallback is unreachable');
+
+  const ins = find(pool.queries, /INSERT INTO idea_inbox/);
+  assert.match(norm(ins.sql), /'promoted'/, 'the idea row is promoted in the same act');
+  assert.equal(ins.params[6], 77, 'and records the home it actually went to, not the null it arrived with');
+  assert.equal(idea.routing.routed, true);
+  assert.equal(idea.routing.reason, 'bug_homeless_trusted_filer');
+});
+
+await test('homeless bug: a sub-Metic filer lands at backlog, never claimable', async () => {
+  reset();
+  const pool = fakePool((s) => {
+    if (/FROM goals g JOIN versions v/.test(s)) return { rows: [MAINT_GOAL] };
+    if (/INSERT INTO idea_inbox/.test(s)) return { rows: [{ ...IDEA_ROW, suggested_goal_id: 77 }] };
+    return null;
+  });
+  await captureIdea(
+    { title: 'crash on save', kind: 'bug', capturedBy: 9, filerRank: 'xenos', vector: 'discord-bugs' },
+    { pool }
+  );
+  assert.equal(createTaskCalls[0].args.status, 'backlog',
+    'the report becomes tracked work, but a Metic+ still says go before anyone can take it');
+});
+
+await test('homeless bug: NO BUILDING VERSION refuses and leaves NOTHING behind', async () => {
+  // Fail closed. There is nowhere honest to file, and inventing a version is how
+  // idea 1000771 happened — every Discord report entombed in a SHIPPED version.
+  reset();
+  currentVersionImpl = async () => null;
+  const pool = fakePool((s) => (/INSERT INTO idea_inbox/.test(s) ? { rows: [IDEA_ROW] } : null));
+  await assert.rejects(
+    () => captureIdea(
+      { title: 'broken', kind: 'bug', capturedBy: 42, filerRank: 'archon', vector: 'api' },
+      { pool }
+    ),
+    (e) => e && e.code === 'NO_BUILDING_VERSION'
+  );
+  const sqls = seq(pool.queries);
+  assert.ok(sqls.some((q) => /^ROLLBACK$/.test(q)), 'the transaction rolls back');
+  assert.ok(!sqls.some((q) => /^COMMIT$/.test(q)), 'and never commits');
+  assert.equal(createTaskCalls.length, 0, 'no task');
+  assert.ok(!sqls.some((q) => /INSERT INTO idea_inbox/.test(q)),
+    'and no idea row — the refusal happens before any write');
+});
+
+await test('homeless bug: a version whose maintenance goal cannot be made refuses too', async () => {
+  reset();
+  ensureMaintenanceImpl = async () => null; // e.g. the version is not open to work
+  const pool = fakePool((s) => (/INSERT INTO idea_inbox/.test(s) ? { rows: [IDEA_ROW] } : null));
+  await assert.rejects(
+    () => captureIdea(
+      { title: 'broken', kind: 'bug', capturedBy: 42, filerRank: 'archon', vector: 'api' },
+      { pool }
+    ),
+    (e) => e && e.code === 'NO_MAINTENANCE_GOAL' && e.version_id === 'BONGOS-V1'
+  );
+  assert.ok(seq(pool.queries).some((q) => /^ROLLBACK$/.test(q)), 'rolls back');
+  assert.equal(createTaskCalls.length, 0, 'no task');
+});
+
+await test('a NAMED goal never consults the maintenance path — the two doors stay separate', async () => {
+  reset();
+  const pool = fakePool(routableHandler());
+  await captureIdea(
+    { title: 'broken', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'archon', vector: 'api' },
+    { pool }
+  );
+  assert.deepEqual(maintenanceCalls, [],
+    'a filer who named a goal gets that goal — the system never second-guesses it');
+  assert.equal(createTaskCalls[0].args.goalId, 7);
+});
+
 summary('idea_routing');

package/tests/maintenance_goal.mjs

@@ -0,0 +1,191 @@
+// tests/maintenance_goal.mjs
+//
+// The two lifecycle SQL helpers behind the HOMELESS-BUG HOME (task 1003691,
+// ADR 0262): `db.ensureMaintenanceGoal` and `db.currentBuildingVersionId`.
+//
+// WHY THIS FILE EXISTS SEPARATELY FROM tests/idea_routing.mjs. That file drives
+// the routing TRANSACTION, and to do so it registers a stub `lifecycle` port —
+// so `currentBuildingVersionId` and `ensureMaintenanceGoal` are mocked functions
+// there and their actual SQL never executes. Everything that makes these two
+// correct lives in that SQL: the advisory lock that makes find-or-create
+// race-safe, the version-status gate, and the `started_at DESC NULLS LAST`
+// tiebreak. None of it was covered until this file (a grader finding on the task).
+//
+// DB-free, the tests/goal_tier.mjs posture for this same file family: each helper
+// honours the #538 deps injection seam (NODE_ENV==='test'), so a SQL-aware fake
+// client drives it with no live Postgres, and we assert the STATEMENT SHAPE and
+// the bound params — because the shape IS the contract here.
+//
+// Run:  node tests/maintenance_goal.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/lifecycle/db.js');
+const { ensureMaintenanceGoal, currentBuildingVersionId } = db;
+const { maintenanceGoalTitle, generalGoalTitle } = require('../modules/lifecycle/goal-advisory.js');
+
+const { test, summary } = makeRunner();
+
+function fakePool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+const norm = (s) => String(s).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(norm(q.sql)));
+const seq = (queries) => queries.map((q) => norm(q.sql));
+
+const MAINT_ROW = {
+  id: 77, version_id: 'BONGOS-V1', title: 'BONGOS-V1 — maintenance', subtitle: null,
+  description: 'Where a reported defect lands…', scope_modules: [], status: 'open',
+  visibility: 'public', accepting_requests: true, created_by: null,
+  succeeded_by_goal_id: null, sort_order: 4, category_id: null, created_at: 'T0', updated_at: 'T0',
+};
+
+// =========================================================================
+// The title — the lookup key, so its exact bytes are the contract
+// =========================================================================
+
+await test('the maintenance title uses an EM DASH, and is not the catch-all', () => {
+  // There is no boolean column saying "this is the maintenance goal": the TITLE is
+  // the key. An ASCII hyphen or an en dash is a different, ordinary goal that would
+  // never match — the same trap generalGoalTitle's own comment warns about.
+  assert.equal(maintenanceGoalTitle('BONGOS-V1'), 'BONGOS-V1 — maintenance');
+  assert.ok(maintenanceGoalTitle('X').includes('—'), 'em dash U+2014, spaced');
+  assert.ok(!maintenanceGoalTitle('X').includes(' - '), 'never an ASCII hyphen');
+  assert.ok(!maintenanceGoalTitle('X').includes('–'), 'never an en dash');
+  // And it is deliberately NOT the catch-all BV1.R11 is deleting.
+  assert.notEqual(maintenanceGoalTitle('BONGOS-V1'), generalGoalTitle('BONGOS-V1'));
+});
+
+// =========================================================================
+// currentBuildingVersionId — the tiebreak, in SQL
+// =========================================================================
+
+await test('currentBuildingVersionId: building only, newest first, nulls last, id breaks ties', async () => {
+  const pool = fakePool(() => ({ rows: [{ id: 'BONGOS-V1' }] }));
+  assert.equal(await currentBuildingVersionId({ pool }), 'BONGOS-V1');
+  const q = norm(pool.queries[0].sql);
+  assert.match(q, /status = 'building'/, 'only a version open to work can receive a bug');
+  assert.match(q, /ORDER BY started_at DESC NULLS LAST, id/,
+    'the pickDefaultVersion rule in SQL — a half-filled row must not decide the answer');
+  assert.match(q, /LIMIT 1/);
+});
+
+await test('currentBuildingVersionId: nothing building ⇒ null, never a guess', async () => {
+  // Fail closed. Inventing a version is idea 1000771's exact failure.
+  const pool = fakePool(() => ({ rows: [] }));
+  assert.equal(await currentBuildingVersionId({ pool }), null);
+});
+
+// =========================================================================
+// ensureMaintenanceGoal — the version gate, the lock, find-or-create
+// =========================================================================
+
+await test('ensureMaintenanceGoal: an EXISTING goal is returned, and nothing is inserted', async () => {
+  const pool = fakePool((s) => {
+    if (/FROM versions/.test(s)) return { rows: [{ status: 'building' }] };
+    if (/pg_advisory_xact_lock/.test(s)) return { rows: [{}] };
+    if (/^SELECT .* FROM goals WHERE version_id/.test(s.trim())) return { rows: [MAINT_ROW] };
+    return null;
+  });
+  const goal = await ensureMaintenanceGoal('BONGOS-V1', { pool });
+  assert.equal(goal.id, 77);
+  assert.ok(!find(pool.queries, /INSERT INTO goals/), 'find-or-create must not create when it finds');
+  // The lookup is keyed on the exact title, bound as a parameter.
+  const lookup = find(pool.queries, /^SELECT .* FROM goals WHERE version_id/);
+  assert.deepEqual(lookup.params, ['BONGOS-V1', 'BONGOS-V1 — maintenance']);
+});
+
+await test('ensureMaintenanceGoal: the LOCK is taken BEFORE the read, or find-or-create races', async () => {
+  // The whole point. `goals` has no unique constraint on (version_id, title), so
+  // two bugs reported in the same second would both read "absent" and both insert,
+  // leaving the title lookup permanently ambiguous. A lock taken AFTER the read
+  // would serialise nothing.
+  const pool = fakePool((s) => {
+    if (/FROM versions/.test(s)) return { rows: [{ status: 'building' }] };
+    if (/pg_advisory_xact_lock/.test(s)) return { rows: [{}] };
+    if (/^INSERT INTO goals/.test(s.trim())) return { rows: [MAINT_ROW] };
+    if (/^SELECT .* FROM goals WHERE version_id/.test(s.trim())) return { rows: [] };
+    return null;
+  });
+  await ensureMaintenanceGoal('BONGOS-V1', { pool });
+  const sqls = seq(pool.queries);
+  const iLock = sqls.findIndex((q) => /pg_advisory_xact_lock/.test(q));
+  const iRead = sqls.findIndex((q) => /^SELECT .* FROM goals WHERE version_id/.test(q));
+  const iIns = sqls.findIndex((q) => /INSERT INTO goals/.test(q));
+  assert.ok(iLock >= 0, 'a lock is taken at all');
+  assert.ok(iLock < iRead && iRead < iIns, `lock → read → insert (got ${iLock}, ${iRead}, ${iIns})`);
+  // xact-scoped: it releases at COMMIT/ROLLBACK, so there is no unlock to forget.
+  assert.match(sqls[iLock], /pg_advisory_xact_lock/);
+  assert.ok(!sqls.some((q) => /pg_advisory_unlock/.test(q)), 'never a manual unlock');
+});
+
+await test('ensureMaintenanceGoal: the created goal is system-owned and UNSCOPED, both bound', async () => {
+  const pool = fakePool((s) => {
+    if (/FROM versions/.test(s)) return { rows: [{ status: 'building' }] };
+    if (/pg_advisory_xact_lock/.test(s)) return { rows: [{}] };
+    if (/^INSERT INTO goals/.test(s.trim())) return { rows: [MAINT_ROW] };
+    if (/^SELECT .* FROM goals WHERE version_id/.test(s.trim())) return { rows: [] };
+    return null;
+  });
+  const goal = await ensureMaintenanceGoal('BONGOS-V1', { pool });
+  assert.equal(goal.id, 77);
+  const ins = find(pool.queries, /INSERT INTO goals/);
+  const q = norm(ins.sql);
+  assert.match(q, /created_by/);
+  assert.match(q, /NULL/, 'system-attributed — no owner, no member row (the migration-160 posture)');
+  assert.match(q, /'open'/, 'it must be OPEN or routeIdeaToGoal would refuse its own home');
+  // scope_modules is BOUND, not a SQL literal — matching sibling createGoal.
+  assert.ok(!/'\{\}'/.test(q), 'scope_modules is a bound param, never an inline literal');
+  assert.deepEqual(ins.params[3], [], 'and it is empty: a defect can land in any module');
+  assert.match(q, /COALESCE\(MAX\(sort_order\) \+ 1, 0\)/, 'sort_order derived, as createGoal does');
+});
+
+await test('ensureMaintenanceGoal: a version NOT building is refused before the lock or any write', async () => {
+  // Filing a defect into a version closed to work is the 1000771 bug — a report
+  // entombed where nobody looks. Checked here rather than trusted from the caller.
+  for (const status of ['shipped', 'planning', 'archived', 'nonsense']) {
+    const pool = fakePool((s) => {
+      if (/FROM versions/.test(s)) return { rows: [{ status }] };
+      return null;
+    });
+    assert.equal(await ensureMaintenanceGoal('GDS-V3', { pool }), null, `status ${status}`);
+    const sqls = seq(pool.queries);
+    assert.ok(!sqls.some((q) => /INSERT INTO goals/.test(q)), `status ${status}: no write`);
+    assert.ok(!sqls.some((q) => /pg_advisory_xact_lock/.test(q)),
+      `status ${status}: not even a lock — the refusal is the first thing that happens`);
+  }
+});
+
+await test('ensureMaintenanceGoal: an absent version, or no versionId at all, refuses', async () => {
+  const pool = fakePool((s) => (/FROM versions/.test(s) ? { rows: [] } : null));
+  assert.equal(await ensureMaintenanceGoal('NOPE', { pool }), null, 'no such version');
+
+  const pool2 = fakePool(() => ({ rows: [{ status: 'building' }] }));
+  assert.equal(await ensureMaintenanceGoal(null, { pool: pool2 }), null, 'null versionId');
+  assert.equal(pool2.queries.length, 0, 'and it short-circuits before touching the DB');
+});
+
+await test('ensureMaintenanceGoal: runs on deps.client so it commits with the route, or not at all', async () => {
+  // A goal created on its own connection would outlive a rolled-back route as an
+  // empty goal nobody asked for. The client seam is what prevents that.
+  const c = makeSqlAwareClient((s) => {
+    if (/FROM versions/.test(s)) return { rows: [{ status: 'building' }] };
+    if (/pg_advisory_xact_lock/.test(s)) return { rows: [{}] };
+    if (/^SELECT .* FROM goals WHERE version_id/.test(s.trim())) return { rows: [MAINT_ROW] };
+    return null;
+  });
+  const client = c._client;
+  const poolThatMustNotBeUsed = fakePool(() => { throw new Error('the module pool was used instead of the tx client'); });
+  const goal = await ensureMaintenanceGoal('BONGOS-V1', { client, pool: poolThatMustNotBeUsed });
+  assert.equal(goal.id, 77);
+  assert.ok(client.queries.length >= 2, 'every statement went to the caller\'s client');
+  assert.equal(poolThatMustNotBeUsed.queries.length, 0);
+});
+
+summary('maintenance_goal');

package/tests/task_goal_required.mjs

@@ -186,7 +186,8 @@ test('no FIFTH vector has appeared', () => {
   // which case delete its opt-in and this line, do not extend the list.
   const roster = new Set([...OPT_INS.map(([f]) => f), 'modules/lifecycle/db-tasks.js']);
   const suspects = [
-    'modules/ideas/inbox.js', 'modules/lifecycle/routes/goals.js',
+    'modules/ideas/inbox.js', 'modules/ideas/homeless-home.js',
+    'modules/lifecycle/routes/goals.js',
     'modules/lifecycle/routes/task-write-routes.js',
   ];
   for (const f of suspects) {