@bongos/core 1.19.274 → 1.19.276

package/modules/ideas/routing.js

@@ -0,0 +1,232 @@
+'use strict';
+
+// modules/ideas/routing.js — THE LANDING MATRIX (task 1003065, BV1.R01,
+// goal 1000071 "Idea routing — work that has a home lands in it").
+// Spec: docs/specs/bongos-v1-idea-routing.md §"Landing matrix (C1/C2/C4)".
+//
+// THE PROBLEM THIS ANSWERS. Most filed "ideas" are really bug tasks or
+// goal-bound feature tasks. Today they park in idea_inbox and wait for a human
+// triage pass that, when it finally promotes them, drops the task into a version
+// catch-all — because nothing in the idea path ever names a goal. Routing makes
+// the home real: work that HAS a home lands in it at filing time, and the inbox
+// keeps only work that doesn't.
+//
+// This file is the DECISION and nothing else: given what was filed and who filed
+// it, does it route, and if so at what status. It is PURE — no DB, no clock, no
+// rank lookup — so every cell of the matrix is pinned by a DB-free unit test
+// (tests/idea_routing.mjs). The transaction that acts on the decision lives in
+// inbox.captureIdea; keeping them apart is what makes the matrix auditable
+// without a Postgres.
+//
+// FAIL-CLOSED IS THE POSTURE HERE, and it is the opposite of the advisory
+// modules' fail-open. An advisory that misfires prints a wrong sentence; a
+// landing decision that misfires puts UNVETTED WORK IN THE CLAIMABLE QUEUE.
+// So every uncertainty resolves toward "don't route" or "route to backlog",
+// never toward 'ready': an unrecognised kind soft-lands, an unknown/absent
+// filer rank soft-lands, and anything the matrix has no opinion about stays in
+// the inbox exactly as it does today.
+
+// The one rule the owner interview (2026-08-17, Q1) settled: BUGS ARE
+// URGENT-TRUE, THE REST GETS A NOD. A bug filed by a trusted builder is
+// claimable the moment it is reported — that is the whole "no triage stop
+// between reported and in the work queue" claim of criterion C1. Everything
+// else — feature, cleanup, refactor, infra — soft-lands at 'backlog', one
+// Metic+ promote from claimable, because those reshape what gets built and a
+// filer should not be able to set the queue's agenda alone.
+const HARD_LAND_KINDS = new Set(['bug']);
+
+// Kinds that are JUDGMENT WORK and must never auto-route, no matter who files
+// them with what goal. A criterion-proposal reshapes a version's scope-truth and
+// is ratified by an Archon (POST /inbox/:id/ratify); a decision is a question
+// awaiting an answer, not a unit of work. Converting either into a task would
+// turn "we should think about this" into "someone should go do this".
+const NEVER_ROUTE_KINDS = new Set(['criterion-proposal', 'decision']);
+
+// The trusted tier, spelled here rather than imported so this file stays pure and
+// DB-free. It is the same Metic+ boundary docs/canonical-permissions.md draws and
+// the routes enforce; this module only READS a rank string it was handed. It
+// grants nothing — the server-side rank floor and the goal's scope wall are
+// separate, load-bearing gates (R05), and this decision is subordinate to both.
+const METIC_PLUS = new Set(['metic', 'archon']);
+
+// A Full Idea (grade='full') is the Board Room's subject — it is ratified by
+// peers (goal 1000069), not converted into a task by its own filer. 'spark' and
+// 'quick' carry no such meaning and route normally.
+const NEVER_ROUTE_GRADE = 'full';
+
+// decideLanding — the matrix, as one pure function.
+//
+// Returns { route: false, reason } when the thing belongs in the inbox, or
+// { route: true, status, reason } when it becomes a task. `reason` is a stable
+// machine token (not prose): the route echoes it, /idea-triage reads it, and the
+// R15 reclassification sweep counts by it. Never throws.
+function decideLanding(input) {
+  // Destructured defaults only fire on `undefined`, so an explicit `null` — what
+  // a caller spreading an absent object hands over — would throw. A landing
+  // decision that CRASHES is the worst of the three outcomes: it takes down the
+  // capture that was supposed to fail closed. Normalise first, decide after.
+  const { goalId = null, kind = null, grade = null, filerRank = null } = input || {};
+  // No goal named ⇒ the inbox is exactly right, and this is the DEFAULT PATH.
+  // Every capture vector that never learns about goals keeps working unchanged;
+  // routing is strictly additive (criterion C1 testable #5).
+  if (goalId == null || goalId === '') return { route: false, reason: 'no_goal' };
+
+  if (String(grade || '').toLowerCase() === NEVER_ROUTE_GRADE) {
+    return { route: false, reason: 'full_idea_never_routes' };
+  }
+  if (NEVER_ROUTE_KINDS.has(kind)) {
+    return { route: false, reason: 'judgment_kind' };
+  }
+
+  if (HARD_LAND_KINDS.has(kind)) {
+    // The rank split. An absent/unknown rank is NOT treated as trusted — see the
+    // fail-closed note above. This is the DECISION only; R05 adds the
+    // server-side enforcement (auto-derived requires_rank floor + scope wall).
+    return METIC_PLUS.has(String(filerRank || '').toLowerCase())
+      ? { route: true, status: 'ready', reason: 'bug_trusted_filer' }
+      : { route: true, status: 'backlog', reason: 'bug_awaiting_nod' };
+  }
+
+  // Everything else with a home: it lands IN that home, at backlog. Note this
+  // deliberately swallows an unrecognised kind into the soft landing rather than
+  // refusing it — a task in a real goal at backlog is strictly better than a row
+  // rotting in the inbox, and 'backlog' means a human still says go.
+  return { route: true, status: 'backlog', reason: 'soft_landing' };
+}
+
+// The default priority for a routed task when the filer suggested none. 3 is the
+// middle of the 1–5 band — a routed task is not automatically urgent, and not
+// automatically bottom-of-queue either. (Decided without interview and recorded
+// in the spec: "routed-task priority defaults to the idea's suggested_priority
+// else 3".)
+const DEFAULT_ROUTED_PRIORITY = 3;
+
+// routedPriority — the idea's own suggestion, clamped to the task band. An idea's
+// suggested_priority column is validated 1..5 at capture, but a routed idea can
+// arrive from a vector that never validated it (Discord inbound, a seed), so this
+// re-clamps rather than trusting the input. Out-of-band or absent ⇒ the default.
+function routedPriority(suggestedPriority) {
+  const p = Number(suggestedPriority);
+  if (!Number.isInteger(p) || p < 1 || p > 5) return DEFAULT_ROUTED_PRIORITY;
+  return p;
+}
+
+// -------------------------------------------------------------------------
+// ENFORCEMENT (task 1003066, BV1.R05) — the matrix decides, this gate BINDS.
+//
+// R01 landed decideLanding: what status a filing lands at. That is a decision
+// about the QUEUE. It is not authority, and on its own it left a real hole:
+// a routed task declares no touches[], so createTask's ADR 0084/0085 rank floor
+// derives from an empty list and comes out 'xenos' — meaning a bug routed into a
+// goal scoped to PROTECTED modules (permission/ship-grade/deploy/migration core)
+// was born claimable by a Xenos the moment any Metic+ nodded it. The matrix's
+// rank split does not close that: it governs who can make work READY, not who
+// can then take it.
+//
+// WHY THIS ISN'T goalScopeCheck.check() CALLED VERBATIM, which is what
+// POST /goals/:id/tasks does. That function DENIES on `empty_touches` — by
+// design, because an AUTHORED task whose blast radius nobody declared cannot be
+// bounded. Applied to a route it would refuse every single filing, since a person
+// reporting a bug does not know which files it lives in; demanding touches[] as
+// the price of reporting is exactly the triage tax this goal removes. So the wall
+// is applied where it has something to bite on:
+//
+//   * touches DECLARED (a programmatic filer that does know) → the real wall,
+//     verbatim, refusals and all.
+//   * touches ABSENT (every human filing) → nothing to subset-check, so the
+//     protection moves to the CLAIM side: the goal's protected scope raises the
+//     task's rank floor, and no sub-Metic can claim it however it got promoted.
+//
+// That is the same protected-roster source (permission-path-check via
+// goalScopeCheck / moduleScopeMap), just enforced at the gate that still exists
+// when touches[] doesn't.
+//
+// MEMBERSHIP IS DELIBERATELY *NOT* REQUIRED, and this is the one place the routed
+// path diverges from the authored one on purpose. authorizeGoalTaskCreate refuses
+// a non-member with not_a_member, because authoring work inside someone's
+// workspace is a member's privilege. REPORTING is not authoring: criterion C5's
+// whole promise is that "the filer never has to know the goal map", and C1's is
+// that a bug filed anywhere lands in its home. Requiring membership would mean
+// only insiders could report against a goal — the opposite of the goal. The
+// safety that membership was carrying is carried here instead by the rank floor
+// (claim side) and the matrix (ready side). Pinned by a test, so a later change
+// has to argue with the test rather than quietly reinstate the wall.
+
+// The rank a routed task must require when its goal's scope reaches protected
+// territory. Metic is the trust boundary docs/canonical-permissions.md draws for
+// the permission/ship/deploy core; createTask's highestRank() clamps UPWARD only,
+// so handing this in can raise a floor and never lower one.
+const PROTECTED_SCOPE_FLOOR = 'metic';
+
+// authorizeRoutedLanding — the FINAL, binding landing decision. PURE: it takes
+// facts the caller already resolved (the matrix verdict, whether the goal's scope
+// includes a protected module, and the scope wall's own verdict if touches were
+// declared) and returns what to stamp on the task, or a refusal.
+//
+// Ordered + fail-closed, the authorizeGoalTaskCreate precedent:
+//   not routing → scope-wall verdict → the floor.
+// Returns { ok: true, status, requiresRank } or { ok: false, code, reason, details }.
+function authorizeRoutedLanding(input) {
+  const { landing = null, scopeProtected = false, scopeCheck = null, filerRank = null } = input || {};
+
+  // Defensive: only a routing verdict may reach here. A caller that lost track of
+  // its own matrix result must not fall through into "authorized".
+  if (!landing || landing.route !== true) {
+    return { ok: false, code: 'not_routing', reason: 'authorizeRoutedLanding was asked to authorize a filing the matrix did not route.', details: null };
+  }
+
+  // The wall, when touches gave it something to check. Its verdict is passed
+  // through UNCHANGED — code, reason and details — so a refusal reads identically
+  // whether it came from a routed filing or an authored task, and there is only
+  // ever one definition of "out of scope" / "protected path".
+  if (scopeCheck && scopeCheck.ok === false) {
+    return { ok: false, code: scopeCheck.code, reason: scopeCheck.reason, details: scopeCheck.details ?? null };
+  }
+
+  // PROTECTED SCOPE + SUB-METIC FILER ⇒ REFUSE, not merely floor-stamp.
+  //
+  // This closes the one place the first cut of R05 was genuinely weaker than the
+  // authored gate rather than differently-shaped. With no touches[] there is no
+  // path for the protected-path arm to inspect, so the earlier version let a
+  // sub-Metic CREATE a task in protected territory and relied on the rank floor to
+  // stop them CLAIMING it. But POST /goals/:id/tasks refuses that author outright
+  // (protected_path), and admission refuses them the goal entirely
+  // (authorizeInvitationAccept: a sub-Metic may not even join a protected-scope
+  // goal). Letting the routed path mint a row there was the odd one out.
+  //
+  // Refusing costs the filer nothing they had before: omit goal_id and the report
+  // files to the inbox exactly as it always did, where a Metic+ triages it. What
+  // it removes is a sub-Metic's ability to put rows — however unclaimable — into
+  // the permission/ship/deploy core's queue, which is precisely what "the scope
+  // wall runs on routed tasks as on authored ones" is asking for.
+  //
+  // The rank floor below still applies to Metic+ filings in protected scope; the
+  // two are layers, not alternatives.
+  if (scopeProtected && !METIC_PLUS.has(String(filerRank || '').toLowerCase())) {
+    return {
+      ok: false,
+      code: 'protected_scope',
+      reason: `This goal's scope reaches protected territory (the permission / ship-grade / deploy / migration core), so a filer below Metic cannot route work into it. File it without a goal — it lands in the inbox and a Metic+ routes it from there.`,
+      details: { required_rank: PROTECTED_SCOPE_FLOOR, filer_rank: filerRank ?? null },
+    };
+  }
+
+  return {
+    ok: true,
+    status: landing.status,
+    // null ⇒ say nothing and let createTask derive the floor exactly as it does
+    // for every other create vector. Only the protected case speaks up.
+    requiresRank: scopeProtected ? PROTECTED_SCOPE_FLOOR : null,
+  };
+}
+
+module.exports = {
+  decideLanding,
+  authorizeRoutedLanding,
+  PROTECTED_SCOPE_FLOOR,
+  routedPriority,
+  DEFAULT_ROUTED_PRIORITY,
+  HARD_LAND_KINDS,
+  NEVER_ROUTE_KINDS,
+  METIC_PLUS,
+};

package/modules/lifecycle/db.js

@@ -1421,7 +1421,7 @@ async function createTask({
   // (requiresRank stays null for the goal vector → derived purely from touches +
   // sensitivity), so goal_id never influences the requires_rank clamp.
   goalId = null,
-}) {
+}, deps = {}) { // deps.client enlists this INSERT in the CALLER'S transaction (task 1003065, BV1.R01); the argument for it is at modules/ideas/inbox.js routeIdeaToGoal
   // task 1498 / ADR 0085: every task carries a deliberate rank floor. Derive it
   // from touches + sensitivity, then let an explicit requiresRank override only
   // UPWARD (highestRank) — a requested rank below the derived floor is clamped
@@ -1456,7 +1456,7 @@ async function createTask({
   if (goalIdEffective == null) {
     goalIdEffective = await generalGoalIdForVersion(versionId);
   }
-  const { rows } = await pool.query(
+  const { rows } = await (deps.client || pool).query(
     `INSERT INTO tasks (version_id, title, description, status, touches,
                         est_minutes, est_cost_usd, manual_degree, priority,
                         automation_tag, credits_reward, source, source_ref, value_summary,

package/package-lock.json

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

package/package.json

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

@@ -975,8 +975,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.272 with no explicit bump. run 32441024959. (task 1002620)
 //   1.19.274 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.273 with no explicit bump. run 32490024209. (task 1002620)
+//   1.19.275 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.274 with no explicit bump. run 32492414871. (task 1002620)
+//   1.19.276 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.275 with no explicit bump. run 32499257959. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.274'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.276'; // 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');