@bongos/core 1.19.288 → 1.19.289

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.288",
-  "core_contract": "1.19.288",
-  "source_commit": "9ad9d2000bfddb7710afeb83f8a33e072ffee604",
+  "core_version": "1.19.289",
+  "core_contract": "1.19.289",
+  "source_commit": "7fcb844542a0043f5c5beff9a14978d08dba62a9",
   "source_ref": "HEAD",
-  "built_at": "2026-08-22T02:33:44.096Z",
+  "built_at": "2026-08-22T03:47:31.708Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 320,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1386,
+    "functional_verbatim": 1388,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1728,
-  "tree_sha256": "40a6f311bd544cbfef6bc326a7d0eb6767685f660dea1dbb1ece69f205603cce",
+  "file_count": 1730,
+  "tree_sha256": "08c303ce54af46b2a131d468064b1ec877f3120d3d6df123a8a5e4c88be18af6",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -347,12 +347,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "75389c8fbcfeb39ce0320d182ea25cc97d2292814743521f834bd98de0ff83da"
+      "sha256": "aaf0bb7dae10d271e9999093935fef5ae8d85c3a2e3d5b4c52e0c11fed8c581e"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "f008fd2b92e818e1734bbbd4388af483730050780d14822daf16ca5e05110401"
+      "sha256": "372a5584ddad52fb524815fc7b50d1aab9163e974aac6f2c64f479e4034914a1"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -362,17 +362,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "ac7eba0af25322341547f46f9daa385bd557e52c1f580d4873a5d4b35a633ca7"
+      "sha256": "7faac7fc48e714c76c2b19feaaf9c730b2c9b10ab71ddc5697c21497d02f10ef"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "6d151ca60431e5346007c1939f10f711111c7b7a38f9914be7c8a6ff12d6a75d"
+      "sha256": "7aba0fe1d782cb6308f57dc2e5f6fe0d5ffe0f537d4ffe846bdc7a03e0f8064d"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "60a6ec5d2b7a41e8727769953bd5b38a6746e2373cd8a271ee7b0ba750b84f34"
+      "sha256": "5f1d221bfbf8d329f883a5dc3e84414728c67201d66faceff04d48732e44b13c"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1407,12 +1407,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "ae992fbebcc171bbc4e669a45f01d3a5dd840bcaad334262136a2060fc362a43"
+      "sha256": "2c4a9b56aea5a8e1a42c70ad5c2646c0d6db6d713c13b8d2068bd3a2fa6ac27e"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "55c2cbd3c8473ed041d0df0c6d9eebe16ed3d333afae9f7dbe3b0ef1a211b4c6"
+      "sha256": "fcb40a7d655517e6dd24b2d4e0e00a9fcace75b2eb0aa89348d2546abf8df422"
     },
     {
       "path": "docs/architecture.md",
@@ -3814,6 +3814,11 @@
       "mode": "0000644",
       "sha256": "0367f88aefa890d8d7f2472dd847467d632150a93db8a96b85717b5fb1cc8c9e"
     },
+    {
+      "path": "modules/lifecycle/goal-suggest.js",
+      "mode": "0000644",
+      "sha256": "5fac15e501d6e5639b9e14d08ab34723b60e3569af913f4d15bb703a4e126a77"
+    },
     {
       "path": "modules/lifecycle/hierarchy.js",
       "mode": "0000644",
@@ -3882,7 +3887,7 @@
     {
       "path": "modules/lifecycle/routes/goals.js",
       "mode": "0000644",
-      "sha256": "a94284db44e4108b21ff3a5f60ac25c0b16ff4330839f9d37045e90e763d430e"
+      "sha256": "3fcc0339927bcc7f426e93c7a5762b45496ecf4e9b841f905fb5f1c468b5f8c0"
     },
     {
       "path": "modules/lifecycle/routes/lifecycle.js",
@@ -4517,12 +4522,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d9e17adc0e87df8ff8a0c36f03b483d48824fe5eba09ff0859dbebad9f79a90c"
+      "sha256": "4a910e78786de976213abedacfe08553775d9651b46579e1388941d416be82db"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "750961d5bd5a5377928326efbdd529d4d2c5be2ab7e864e55416645e97133086"
+      "sha256": "9919d125bfcfaccf90bc06727eeec3f410882a6e1c83481e63f79f7a5d2d7a0b"
     },
     {
       "path": "public-docs/index.html",
@@ -6032,7 +6037,7 @@
     {
       "path": "src/bongos/route-rank-check.js",
       "mode": "0000644",
-      "sha256": "be8bc6ecd3ab1dbec4d3224d684b64d100920ad2cf7d08c51898160fefdaf534"
+      "sha256": "97b8345a1d891151c3bc134926124a0ac929db661e0cfb26c6760c8c6030bafc"
     },
     {
       "path": "src/bongos/routes.js",
@@ -6167,7 +6172,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "410c4b2cfa57fddbcfa3e4d6b2a66a8c3c286b49822cc49c53759f6fb6a6aea7"
+      "sha256": "fbb190fb4b0b50ef8374412a009f1a4799ecbdb15b37caabac3c8a138ca29622"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7129,6 +7134,11 @@
       "mode": "0000644",
       "sha256": "447e6376ae5f5e2bedf1a80b3355604544a5e349da87d110fc0135cc3cd98fac"
     },
+    {
+      "path": "tests/goal_suggest.mjs",
+      "mode": "0000644",
+      "sha256": "7fc1d81afc49311a3c8525b644319e4831bff295bef8be244220fea5ebfbbbd1"
+    },
     {
       "path": "tests/goal_tier.mjs",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 293 operations across 47 resource groups
+- 294 operations across 47 resource groups
 
 ## Install
 

package/clients/bongos-client/bongos-client.global.js

@@ -355,6 +355,8 @@ function createClient(opts = {}) {
       getGoalsInbox: (args) => request("GET", "/goals/inbox", { hasBody: false }, args),
       // POST /goals/reorder — rank: metic+archon — POST /goals/reorder
       postGoalsReorder: (args) => request("POST", "/goals/reorder", { hasBody: true }, args),
+      // GET /goals/suggestions — rank: any-builder — GET /goals/suggestions
+      getGoalsSuggestions: (args) => request("GET", "/goals/suggestions", { hasBody: false }, args),
     },
     "government": {
       // GET /government/assignments — rank: archon — GET /government/assignments

package/clients/bongos-client/index.cjs

@@ -354,6 +354,8 @@ function createClient(opts = {}) {
       getGoalsInbox: (args) => request("GET", "/goals/inbox", { hasBody: false }, args),
       // POST /goals/reorder — rank: metic+archon — POST /goals/reorder
       postGoalsReorder: (args) => request("POST", "/goals/reorder", { hasBody: true }, args),
+      // GET /goals/suggestions — rank: any-builder — GET /goals/suggestions
+      getGoalsSuggestions: (args) => request("GET", "/goals/suggestions", { hasBody: false }, args),
     },
     "government": {
       // GET /government/assignments — rank: archon — GET /government/assignments

package/clients/bongos-client/index.d.ts

@@ -40,7 +40,6 @@ export interface GetGithubReposResponse { repos: unknown }
 export interface GetGoalsIdConflictsResponse { ok: boolean; goal_id: unknown; conflicts: unknown; cross_goals_considered: unknown }
 export interface GetGoalsIdRequestsResponse { requests: unknown }
 export interface GetGoalsIdResponse { goal: unknown; members: unknown; criteria: unknown; dependencies: unknown }
-export interface GetGoalsIdSuggestCriteriaResponse { goal_id: unknown; suggestions: unknown }
 export interface GetGoalsResponse { goals: unknown }
 export interface GetGovernmentAssignmentsResponse { assignments: unknown }
 export interface GetGovernmentPermissionsResponse { permissions: unknown; principals: unknown }
@@ -605,7 +604,7 @@ export interface BongosClient {
     /** POST /goals/{id}/scope — rank: metic+archon */
     postGoalsIdScope(args: RequestArgs & { body: PostGoalsIdScopeRequest }): Promise<PostGoalsIdScopeResponse>;
     /** GET /goals/{id}/suggest-criteria — rank: any-builder */
-    getGoalsIdSuggestCriteria(args?: RequestArgs): Promise<GetGoalsIdSuggestCriteriaResponse>;
+    getGoalsIdSuggestCriteria(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /goals/{id}/tasks — rank: any-builder */
     postGoalsIdTasks(args: RequestArgs & { body: PostGoalsIdTasksRequest }): Promise<PostGoalsIdTasksResponse>;
     /** POST /goals/{id}/transfer — rank: any-builder */
@@ -616,6 +615,8 @@ export interface BongosClient {
     getGoalsInbox(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /goals/reorder — rank: metic+archon */
     postGoalsReorder(args: RequestArgs & { body: PostGoalsReorderRequest }): Promise<PostGoalsReorderResponse>;
+    /** GET /goals/suggestions — rank: any-builder */
+    getGoalsSuggestions(args?: RequestArgs): Promise<ApiResponse>;
   };
   "government": {
     /** GET /government/assignments — rank: archon */

package/clients/bongos-client/index.mjs

@@ -351,6 +351,8 @@ export function createClient(opts = {}) {
       getGoalsInbox: (args) => request("GET", "/goals/inbox", { hasBody: false }, args),
       // POST /goals/reorder — rank: metic+archon — POST /goals/reorder
       postGoalsReorder: (args) => request("POST", "/goals/reorder", { hasBody: true }, args),
+      // GET /goals/suggestions — rank: any-builder — GET /goals/suggestions
+      getGoalsSuggestions: (args) => request("GET", "/goals/suggestions", { hasBody: false }, args),
     },
     "government": {
       // GET /government/assignments — rank: archon — GET /government/assignments

package/docs/api/openapi.json

@@ -4228,6 +4228,37 @@
         ]
       }
     },
+    "/goals/suggestions": {
+      "get": {
+        "operationId": "get_goals_suggestions",
+        "tags": [
+          "goals"
+        ],
+        "summary": "GET /goals/suggestions",
+        "description": "GET /goals/suggestions — \"which goal should this draft live in?\", answered before anything is created (task 1003062 / R07). Handler + the ranking and visibility rationale: ../goal-suggest.js. Mounted BEFORE GET /goals/:id so 'suggestions' is never captured as an id. rank: any-builder — a read of open goal titles, same surface as GET /goals.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals/{id}": {
       "get": {
         "operationId": "get_goals_id",
@@ -5257,14 +5288,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetGoalsIdSuggestCriteriaResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -13780,17 +13804,6 @@
           "dependencies"
         ]
       },
-      "GetGoalsIdSuggestCriteriaResponse": {
-        "type": "object",
-        "properties": {
-          "goal_id": {},
-          "suggestions": {}
-        },
-        "required": [
-          "goal_id",
-          "suggestions"
-        ]
-      },
       "GetGoalsResponse": {
         "type": "object",
         "properties": {
@@ -18546,9 +18559,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 293,
-  "x-schema-count": 328,
+  "x-endpoint-count": 294,
+  "x-schema-count": 327,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 219,
+  "x-response-schemas": 218,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 293 endpoints across 47 route files.
+> **Generated from the live route files** — the route file is authoritative. 294 endpoints across 47 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -197,7 +197,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/github/repos` | `any-builder` | — | acts only on the caller's OWN GitHub identity (the token they granted). |
 | POST | `/api/bongos/github/repos` | `any-builder` | `name` | creates a repo in the caller's OWN account. |
 
-## `goals` (25)
+## `goals` (26)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -226,6 +226,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | PATCH | `/api/bongos/goals/:id/visibility` | `any-builder` | — | PATCH /goals/:id/visibility — make a goal public\|private (task 1952 / ADR 0112). |
 | GET | `/api/bongos/goals/inbox` | `any-builder` | — | GET /goals/inbox — the caller's private-goals inbox (task 1952 / ADR 0112): { invitations: invites addressed to me (accept/decline); join… |
 | POST | `/api/bongos/goals/reorder` | `metic+archon` | `version_id`, `ordered_ids` | POST /goals/reorder — Archon drag-to-reorder: set the priority order of every goal WITHIN one version (task 1760). |
+| GET | `/api/bongos/goals/suggestions` | `any-builder` | — | GET /goals/suggestions — "which goal should this draft live in?", answered before anything is created (task 1003062 / R07). |
 
 ## `government` (13)
 

package/modules/lifecycle/goal-suggest.js

@@ -0,0 +1,171 @@
+'use strict';
+
+// modules/lifecycle/goal-suggest.js — "which goal should this work live in?",
+// answered BEFORE anything is created (task 1003062 / R07 of goal 1000071).
+//
+// THE GAP. `buildGoalAdvisory` (goal-advisory.js) already answers this — but only
+// AFTER a task exists, as a hint attached to the 201. Every consumer R07 feeds
+// needs it BEFORE: the hall filing surface offering a goal picker (R08), the CLI
+// asking at capture time (R09), and the Discord suggestion (R11) all have a draft
+// title and no row yet. So the candidate logic is lifted into a pure read that
+// creates nothing.
+//
+// WHY THIS RANKS, rather than returning "the first five open goals". Unranked
+// candidates are useless here: BONGOS-V1 carries dozens of open goals, so an
+// arbitrary five is noise dressed as a suggestion. Ranking is what makes it a
+// suggester. It reuses `tokenize` from criterion-suggest.js — a sibling, already
+// covering the weighting idea (title terms 2, body terms 1) and already tested —
+// so there is one notion of "these two texts are about the same thing" in the
+// module, not two.
+//
+// WHAT A GOAL IS MATCHED ON: its title and its scope_modules. Deliberately NOT
+// its description — a goal description is where a whole planning spec lives (goal
+// 1000062 carries an entire decision record in its), so it shares tokens with
+// almost any draft and would flatten every score toward the same number. Modules
+// are included because they are a strong, cheap signal: a draft about the hall
+// really does belong with a goal scoped to `hall-ui`.
+
+const { tokenize } = require('./criterion-suggest.js');
+const { candidateGoals } = require('./goal-advisory.js');
+const api = require('../../src/module-api');
+// Through the published logger seam, not a raw console call (est-advisory.js precedent).
+const proseErr = (err) => api.logger('lifecycle').error({ err: err && err.message }, 'GET /goals/suggestions failed');
+
+// Matches suggestCriteria's default so the two suggesters feel the same.
+const SUGGEST_LIMIT = 5;
+
+// Rank open goals against a DRAFT capture. Pure — no DB, no writes; the caller
+// supplies the goal rows.
+//
+//   goals   — open goal rows { id, title, scope_modules }
+//   draft   — { title, body } (body optional: a capture's prose, weighted lower)
+//   opts    — { versionId, limit, includeZero }
+//
+// Returns [{ id, title, scope_modules, score, matched_terms }] best-first, ties
+// broken by ascending id so output is stable for a picker.
+//
+// `includeZero` defaults FALSE, following suggestCriteria: a draft that matches
+// nothing returns [] — "no confident suggestion" — rather than five arbitrary
+// goals. The route reports the open-goal count alongside so a caller can still
+// offer "browse all" without this function pretending to a confidence it lacks.
+function suggestGoals(goals, draft = {}, opts = {}) {
+  const { title = '', body = '' } = draft;
+  const { versionId = null, limit = SUGGEST_LIMIT, includeZero = false } = opts;
+
+  // Weighted term map: body terms at 1, title terms override to 2 (a term in
+  // both IS a title term — the stronger signal wins). suggestCriteria's rule.
+  const weights = new Map();
+  for (const t of tokenize(body)) weights.set(t, 1);
+  for (const t of tokenize(title)) weights.set(t, 2);
+
+  // candidateGoals drops the "<version> — general" catch-all and normalises the
+  // row shape. Reused rather than re-filtered so "which goals may be suggested"
+  // has one definition — the catch-all is never a suggestion, it is the fallback
+  // when there is no home, which is a different question (R03 owns that).
+  const ranked = candidateGoals(goals, versionId).map((g) => {
+    const goalTerms = new Set([
+      ...tokenize(g.title),
+      // A module key like `hall-ui` tokenizes to ['hall','ui']; 'ui' is dropped
+      // by the >=3-char filter, which is fine — 'hall' is the signal.
+      ...tokenize((g.scope_modules || []).join(' ')),
+    ]);
+    let score = 0;
+    const matched = [];
+    for (const [term, w] of weights) {
+      if (goalTerms.has(term)) { score += w; matched.push(term); }
+    }
+    return { ...g, score, matched_terms: matched.sort() };
+  }).sort((a, b) => (b.score - a.score) || (Number(a.id) - Number(b.id)));
+
+  const kept = includeZero ? ranked : ranked.filter((r) => r.score > 0);
+  return kept.slice(0, Math.max(0, limit));
+}
+
+
+// goalSuggestHandler — GET /goals/suggestions. Handler lives here, not inline in
+// routes/goals.js, because that file is over the fitness oversize threshold and
+// the ratchet is shrink-only; collaborators are injected so this module still
+// requires nothing but its siblings.
+//
+// Creates NOTHING — that is the point of R07. A caller with a draft title gets
+// candidates and decides; POST /inbox (R01) is what actually routes.
+//
+// VISIBILITY, stated rather than silently decided: this returns open goals
+// without filtering on `visibility`, which MATCHES the existing GET /goals — that
+// route already lists private goals' titles to any signed-in builder
+// (db.listGoals has no visibility predicate). So this neither widens nor narrows
+// the status quo. It is worth knowing that the status quo is wider than the
+// private-goal leak rule the CLAIM refusal follows (goal-authz
+// goalMembershipClaimRefusal withholds a private goal's title); reconciling the
+// two is a real decision about the goal board as a whole, not something a
+// suggester should settle on its own.
+function goalSuggestHandler({ db, LIMITS }) {
+  return async function getGoalSuggestions(req, res) {
+    const versionId = String(req.query.version || '').trim();
+    if (!versionId) return res.fail('version_required', 400, { message: 'Pass ?version=<version_id> — suggestions are scoped to one version.' });
+    const title = String(req.query.title || '').slice(0, (LIMITS && LIMITS.TITLE) || 200);
+    const body = String(req.query.body || '').slice(0, 4000);
+    if (!title && !body) {
+      return res.fail('draft_text_required', 400, { message: 'Pass ?title= (and optionally ?body=) — there is nothing to rank against otherwise.' });
+    }
+    const rawLimit = Number(req.query.limit);
+    const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(1, Math.trunc(rawLimit)), 20) : SUGGEST_LIMIT;
+    // Wrapped like criteriaSuggestHandler below: without it a db error escapes to
+    // Express's default handler, which can put internal detail on a JSON API
+    // response. The sibling in this same file already did this; not matching it
+    // was an oversight, not a decision.
+    try {
+      const open = await db.listGoals({ versionId, status: 'open' });
+      const suggestions = suggestGoals(open, { title, body }, { versionId, limit });
+      return res.json({
+        version_id: versionId,
+        // `kind` is echoed, NOT ranked on. Kind decides how a capture LANDS (the
+        // R05 landing matrix: a bug hard-lands, a feature soft-lands); it does not
+        // indicate WHICH goal the work belongs to. Saying so here stops a caller
+        // reading the echo as a ranking input.
+        kind: req.query.kind ? String(req.query.kind).slice(0, 64) : null,
+        suggestions,
+        // So a caller can offer "browse all" honestly when nothing scored: an empty
+        // `suggestions` means "no confident match", never "this version has no goals".
+        open_goal_count: (open || []).length,
+        created: null,
+      });
+    } catch (err) {
+      proseErr(err);
+      return res.fail('suggest_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+// criteriaSuggestHandler — GET /goals/:id/suggest-criteria (task 2165), moved
+// here in task 1003062. Same reason as its sibling above: routes/goals.js is over
+// the fitness oversize threshold and the ratchet is shrink-only, so adding the
+// goal suggester there had to be PAID FOR — and paying with a cohesion
+// improvement beats shaving comments. It belongs beside the other suggester
+// anyway: both answer "what should this draft attach to", one at goal level and
+// one at criterion level. Behaviour byte-identical; only the registration line
+// stays in the route file so route-rank-check still classifies it.
+function criteriaSuggestHandler({ db, suggestCriteria, parseId }) {
+  return async function getSuggestCriteria(req, res) {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      const criteria = await db.listCriteriaForGoal(id);
+      const limit = Math.min(10, Math.max(1, Number(req.query.limit) || 3));
+      const suggestions = suggestCriteria(
+        criteria,
+        { title: req.query.title, description: req.query.description },
+        { limit }
+      );
+      return res.json({ goal_id: goal.id, suggestions });
+    } catch (err) {
+      // Same seam as its sibling above — one error-handling pattern per file.
+      api.logger('lifecycle').error({ err: err && err.message }, 'GET /goals/:id/suggest-criteria failed');
+      return res.fail('fetch_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = { suggestGoals, goalSuggestHandler, criteriaSuggestHandler, SUGGEST_LIMIT };

package/modules/lifecycle/routes/goals.js

@@ -26,6 +26,7 @@ const api = require('../../../src/module-api');
 const auth = api;
 const db = require('../db');
 const hierarchy = require('../hierarchy');
+const goalSuggest = require('../goal-suggest.js'); // task 1003062 — pre-creation goal suggester
 const goalEdits = require('../goal-edits.js'); // task 1003102 — goal self-edit handlers
 const { suggestCriteria } = require('../criterion-suggest');
 const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, TASK_FIELD_BOUNDS } = require('../task-classifier');
@@ -535,6 +536,13 @@ module.exports = function buildGoalsRouter() {
     }
   });
 
+  // GET /goals/suggestions — "which goal should this draft live in?", answered
+  // before anything is created (task 1003062 / R07). Handler + the ranking and
+  // visibility rationale: ../goal-suggest.js. Mounted BEFORE GET /goals/:id so
+  // 'suggestions' is never captured as an id.
+  // rank: any-builder — a read of open goal titles, same surface as GET /goals.
+  router.get('/goals/suggestions', auth.requireBuilder, goalSuggest.goalSuggestHandler({ db, LIMITS }));
+
   // GET /goals/inbox — the caller's private-goals inbox (task 1952 / ADR 0112):
   // { invitations: invites addressed to me (accept/decline); joinRequests: pending
   // join-requests on goals I own or manage (approve/deny); myPendingRequests: my own
@@ -578,25 +586,7 @@ module.exports = function buildGoalsRouter() {
   // task, so a create flow can SUGGEST which done-when criterion to link (the
   // author confirms/overrides — nothing is auto-linked). Read-only + advisory;
   // rank: any-builder (same as GET /goals/:id).
-  router.get('/goals/:id/suggest-criteria', auth.requireBuilder, async (req, res) => {
-    const id = parseId(req, res, { code: 'bad_goal_id' });
-    if (id === null) return;
-    try {
-      const goal = await db.getGoal(id);
-      if (!goal) return res.fail('goal_not_found', 404);
-      const criteria = await db.listCriteriaForGoal(id);
-      const limit = Math.min(10, Math.max(1, Number(req.query.limit) || 3));
-      const suggestions = suggestCriteria(
-        criteria,
-        { title: req.query.title, description: req.query.description },
-        { limit }
-      );
-      return res.json({ goal_id: goal.id, suggestions });
-    } catch (err) {
-      console.error('[gds] GET /goals/:id/suggest-criteria', err);
-      return res.fail('fetch_failed', { status: 500, message: 'internal error' });
-    }
-  });
+  router.get('/goals/:id/suggest-criteria', auth.requireBuilder, goalSuggest.criteriaSuggestHandler({ db, suggestCriteria, parseId }));
 
   // POST /goals/:id/join — join an open goal.
   // rank: any-builder — open join for a NORMAL goal. A PROTECTED-scope goal is

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.288",
+  "version": "1.19.289",
   "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/bongos/route-rank-check.js

@@ -362,6 +362,9 @@ const MODULE_EXPECTED_RANKS = {
     // Pinning catches an accidental requireRank re-gate that would lock builders
     // out of asking/accepting, and any gate removal.
     'GET /goals/inbox': 'any-builder',
+    // task 1003062 (R07): a pre-creation READ of open goal titles — same surface
+    // and same rank as GET /goals. Creates nothing.
+    'GET /goals/suggestions': 'any-builder',
     'PATCH /goals/:id/visibility': 'any-builder',
     // task 1003102: a goal's own authority (owner|manager|Archon, in-handler
     // authorizeGoalManagement) corrects its own title/description — same shape
@@ -506,8 +509,20 @@ function classifyGate(lines, i, { floors } = {}) {
   // (not any `=>`) avoids cutting at an inline-arrow middleware like
   // `rateLimit({ key: (req) => req.ip })`. If there's no `=> {` in the window
   // (e.g. a `function` handler), fall back to the full window — prior behaviour.
-  const handlerAt = window.search(/=>\s*\{/);
-  const tail = handlerAt === -1 ? window : window.slice(0, handlerAt);
+  // task 1003062: FIRST clamp the window to THIS route's own declaration. The
+  // `=> {` truncation below only fires for an inline-arrow handler; a route whose
+  // handler is a FACTORY CALL — `router.get(p, auth.requireBuilder, mk({...}))` —
+  // contains no `=> {`, so the old code fell back to the full 20 lines and
+  // absorbed the NEXT route's requirePermission, recording an any-builder read as
+  // metic+archon. Wrong in the tightening direction, but still wrong: the pin and
+  // the audit then describe a gate that is not there. Factory handlers became
+  // common because the fitness oversize ratchet pushes handler bodies out of large
+  // route files, so this is not an exotic shape. A window must never cross into a
+  // sibling declaration.
+  const nextRouteAt = window.search(/\n\s*router\.(get|post|patch|put|delete|use)\s*\(/);
+  const own = nextRouteAt === -1 ? window : window.slice(0, nextRouteAt);
+  const handlerAt = own.search(/=>\s*\{/);
+  const tail = handlerAt === -1 ? own : own.slice(0, handlerAt);
 
   const perms = permissionKeysIn(tail);
   const byRank = rankFromRankGate(tail);

package/src/module-api.js

@@ -1003,8 +1003,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.286 with no explicit bump. run 32539649191. (task 1002620)
 //   1.19.288 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.287 with no explicit bump. run 32546561232. (task 1002620)
+//   1.19.289 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.288 with no explicit bump. run 32549912116. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.288'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.289'; // 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/goal_suggest.mjs

@@ -0,0 +1,195 @@
+// tests/goal_suggest.mjs — the pre-creation goal suggester (task 1003062 / R07 of
+// goal 1000071).
+//
+// "Which goal should this work live in?", answered BEFORE anything is created.
+// buildGoalAdvisory already answered it, but only AFTER a task existed; R08 (hall
+// picker), R09 (CLI) and R11 (Discord) all have a draft title and no row yet.
+//
+// What these pin:
+//  1. It CREATES NOTHING. That is the entire point of a pre-creation read, and the
+//     easiest thing for a later refactor to break by routing it through a writer.
+//  2. RANKING, not "the first five open goals" — with the honest limits of token
+//     overlap written down rather than papered over (see the false-positive test).
+//  3. The catch-all is never suggested (it is the fallback when there is no home —
+//     a different question, owned by R03).
+//  4. No confident match returns [] rather than noise, and the route still tells
+//     the caller how many goals exist so it can offer "browse all" honestly.
+//
+// Run:  node tests/goal_suggest.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { suggestGoals, goalSuggestHandler, SUGGEST_LIMIT } = require('../modules/lifecycle/goal-suggest.js');
+const { test, summary } = makeRunner();
+
+const V = 'BONGOS-V1';
+const GOALS = [
+  { id: 1000024, title: 'Build-pipeline integrity', scope_modules: ['lifecycle', 'grading'] },
+  { id: 1000025, title: 'Builder experience — hall, dev box, and skills', scope_modules: ['hall-ui', 'dev-box'] },
+  { id: 1000071, title: 'Idea routing — work that has a home lands in it', scope_modules: ['ideas', 'discord'] },
+  { id: 1000003, title: `${V} — general`, scope_modules: [] },
+];
+
+// ---- 2. it ranks, and the ranking is explainable --------------------------
+
+await test('RANKS: a draft about the ship pipeline puts Build-pipeline integrity first', () => {
+  const r = suggestGoals(GOALS, { title: 'ship pipeline grading is flaky' }, { versionId: V });
+  assert.equal(r[0].id, 1000024);
+  assert.ok(r[0].score >= 4, `two title terms should score >=4, got ${r[0].score}`);
+  assert.deepEqual(r[0].matched_terms, ['grading', 'pipeline'], 'and it SAYS why it matched');
+});
+
+await test('RANKS: a module key is a matchable signal, not just the title', () => {
+  // 'discord' appears only in scope_modules for goal 1000071.
+  const r = suggestGoals(GOALS, { title: 'discord filing loses the author' }, { versionId: V });
+  assert.equal(r[0].id, 1000071);
+  assert.ok(r[0].matched_terms.includes('discord'));
+});
+
+await test('RANKS: title terms outweigh body terms (2 vs 1), same rule as suggestCriteria', () => {
+  const inTitle = suggestGoals(GOALS, { title: 'grading' }, { versionId: V })[0];
+  const inBody = suggestGoals(GOALS, { title: 'unrelated', body: 'grading' }, { versionId: V })[0];
+  assert.equal(inTitle.score, 2);
+  assert.equal(inBody.score, 1);
+});
+
+await test('RANKS: a term in BOTH title and body counts once, at the title weight', () => {
+  const r = suggestGoals(GOALS, { title: 'grading', body: 'grading grading' }, { versionId: V })[0];
+  assert.equal(r.score, 2, 'the stronger signal wins; it does not accumulate');
+});
+
+await test('RANKS: ties break by ascending id so a picker renders stably', () => {
+  const goals = [
+    { id: 900, title: 'routing', scope_modules: [] },
+    { id: 100, title: 'routing', scope_modules: [] },
+    { id: 500, title: 'routing', scope_modules: [] },
+  ];
+  assert.deepEqual(suggestGoals(goals, { title: 'routing' }, { versionId: V }).map((g) => g.id), [100, 500, 900]);
+});
+
+// ---- the honest limit, written down --------------------------------------
+
+await test('LIMIT (known + accepted): token overlap can match on an incidental word', () => {
+  // Real example found while building this: "the goals page search BOX is broken"
+  // scores the DEV BOX goal, because both contain the token 'box'. Bag-of-words
+  // matching cannot tell "search box" from "dev box".
+  //
+  // This is NOT hidden — it is why every suggestion carries `score` and
+  // `matched_terms`: a caller can show WHY it matched and a human decides. A
+  // suggester that silently guessed, with no visible reason, would be worse.
+  // Fixing it properly means real relevance scoring (embeddings/FTS), which is a
+  // separate decision, not something to smuggle into R07.
+  const r = suggestGoals(GOALS, { title: 'the goals page search box is broken' }, { versionId: V });
+  assert.equal(r[0].id, 1000025, 'the incidental match is what happens today');
+  assert.deepEqual(r[0].matched_terms, ['box'], 'and the single weak term is VISIBLE to the caller');
+  assert.equal(r[0].score, 2, 'one title term — a low score, which is the signal it is weak');
+});
+
+// ---- 3. the catch-all is never a suggestion ------------------------------
+
+await test('CATCH-ALL: the "<version> — general" goal is never suggested, even on an exact hit', () => {
+  const r = suggestGoals(GOALS, { title: `${V} general` }, { versionId: V });
+  assert.ok(!r.some((g) => g.id === 1000003), 'the catch-all is the no-home FALLBACK (R03), not a suggestion');
+});
+
+await test('CATCH-ALL: without a versionId it cannot be identified, so nothing is dropped', () => {
+  // candidateGoals keys the catch-all off the version name; no version => no filter.
+  const r = suggestGoals(GOALS, { title: 'general' }, {});
+  assert.ok(r.some((g) => g.id === 1000003), 'documented consequence of omitting versionId');
+});
+
+// ---- 4. no confident match, and bounds ----------------------------------
+
+await test('NO MATCH: a draft matching nothing returns [] rather than arbitrary goals', () => {
+  assert.deepEqual(suggestGoals(GOALS, { title: 'xyzzy plugh frobnicate' }, { versionId: V }), []);
+});
+
+await test('NO MATCH: includeZero:true is available for a caller that wants the full list', () => {
+  const r = suggestGoals(GOALS, { title: 'xyzzy' }, { versionId: V, includeZero: true });
+  assert.equal(r.length, 3, 'all three non-catch-all goals, all scoring 0');
+  assert.ok(r.every((g) => g.score === 0));
+});
+
+await test('BOUNDS: limit defaults to SUGGEST_LIMIT and is respected; degenerate input is safe', () => {
+  assert.equal(SUGGEST_LIMIT, 5);
+  assert.equal(suggestGoals(GOALS, { title: 'routing' }, { versionId: V, limit: 1 }).length, 1);
+  assert.deepEqual(suggestGoals(GOALS, { title: 'routing' }, { versionId: V, limit: 0 }), []);
+  assert.deepEqual(suggestGoals(null, { title: 'x' }, {}), []);
+  assert.deepEqual(suggestGoals(GOALS, {}, { versionId: V }), [], 'no draft text => no suggestions');
+});
+
+// ---- 1. IT CREATES NOTHING ----------------------------------------------
+
+function fakeRes() {
+  return {
+    code: null, payload: null, statusCode: 200,
+    json(p) { this.payload = p; return this; },
+    status(c) { this.statusCode = c; return this; },
+    fail(code, s, extra) { this.code = code; this.statusCode = typeof s === 'number' ? s : (s && s.status) || 500; this.payload = extra || s; return this; },
+  };
+}
+
+await test('CREATES NOTHING: the handler only READS goals — no writer is reachable from it', async () => {
+  const calls = [];
+  const db = { listGoals: async (a) => { calls.push(['listGoals', a]); return GOALS; } };
+  const handler = goalSuggestHandler({ db, LIMITS: { TITLE: 200 } });
+  const res = fakeRes();
+  await handler({ query: { version: V, title: 'ship pipeline grading' } }, res);
+  assert.equal(res.code, null, `expected success, got ${res.code}`);
+  assert.equal(res.payload.suggestions[0].id, 1000024);
+  assert.deepEqual(calls.map((c) => c[0]), ['listGoals'], 'exactly one read, and it is a read');
+  assert.equal(res.payload.created, null, 'the response says so explicitly');
+  // Source contract: nothing in this module may call a create/insert/update path.
+  const src = readFileSync(new URL('../modules/lifecycle/goal-suggest.js', import.meta.url), 'utf8');
+  assert.ok(!/\b(createTask|createGoal|insert|INSERT|UPDATE|captureIdea)\b/.test(src),
+    'a pre-creation suggester must contain no write path at all');
+});
+
+await test('the handler refuses without a version, and without any draft text', async () => {
+  const handler = goalSuggestHandler({ db: { listGoals: async () => GOALS }, LIMITS: { TITLE: 200 } });
+  let res = fakeRes();
+  await handler({ query: { title: 'x' } }, res);
+  assert.equal(res.code, 'version_required');
+  res = fakeRes();
+  await handler({ query: { version: V } }, res);
+  assert.equal(res.code, 'draft_text_required', 'ranking against nothing is not a suggestion');
+});
+
+await test('the handler reports open_goal_count so an empty result is not mistaken for an empty version', async () => {
+  const handler = goalSuggestHandler({ db: { listGoals: async () => GOALS }, LIMITS: { TITLE: 200 } });
+  const res = fakeRes();
+  await handler({ query: { version: V, title: 'xyzzy plugh' } }, res);
+  assert.deepEqual(res.payload.suggestions, []);
+  assert.equal(res.payload.open_goal_count, 4, 'four goals exist; none matched — different facts');
+});
+
+await test('kind is ECHOED but never ranked on (it decides landing, not which goal)', async () => {
+  const handler = goalSuggestHandler({ db: { listGoals: async () => GOALS }, LIMITS: { TITLE: 200 } });
+  const withKind = fakeRes();
+  await handler({ query: { version: V, title: 'grading', kind: 'bug' } }, withKind);
+  const noKind = fakeRes();
+  await handler({ query: { version: V, title: 'grading' } }, noKind);
+  assert.equal(withKind.payload.kind, 'bug', 'echoed');
+  assert.equal(noKind.payload.kind, null);
+  assert.deepEqual(
+    withKind.payload.suggestions.map((s) => [s.id, s.score]),
+    noKind.payload.suggestions.map((s) => [s.id, s.score]),
+    'kind must not change the ranking — the R05 landing matrix owns kind',
+  );
+});
+
+await test('the handler clamps limit into a sane range', async () => {
+  const handler = goalSuggestHandler({ db: { listGoals: async () => GOALS }, LIMITS: { TITLE: 200 } });
+  for (const [q, expectMax] of [[{ limit: '999' }, 20], [{ limit: '0' }, 1], [{ limit: 'abc' }, SUGGEST_LIMIT]]) {
+    const res = fakeRes();
+    await handler({ query: { version: V, title: 'routing grading hall', ...q } }, res);
+    assert.ok(res.payload.suggestions.length <= expectMax, `limit ${JSON.stringify(q)} must clamp`);
+  }
+});
+
+summary();