@bongos/core 1.19.935 → 1.19.937

package/modules/ideas/routes/inbox.js

@@ -122,6 +122,26 @@ function boardWindowPayload(item) {
   };
 }
 
+// THE RECOMMENDATION A FULL IDEA CARRIES (task 1004092 / BV2.R13, spec R22).
+// 'goal' or 'criterion' — the author's reading of how big the thought turned
+// out, carried from filing to the board item so voters see what was proposed.
+// IT IS NOT A DECISION (spec decision 9): the board decides, and no branch in
+// this module may treat it as the outcome.
+//
+// Spelled once because all three filing paths take the same field — capture,
+// develop and resubmit — and a second copy of the refusal is a second place for
+// the vocabulary to drift from ideas_grades_recommendation_chk. Returns true
+// when it has already answered the request.
+function refuseBadRecommendation(res, raw) {
+  if (inbox.isValidRecommendation(raw)) return false;
+  res.fail('bad_recommendation', 400, {
+    recommendation: raw,
+    allowed: inbox.VALID_RECOMMENDATIONS,
+    reason: 'a Full Idea recommends a goal or a criterion; the board decides which it becomes.',
+  });
+  return true;
+}
+
 module.exports = function buildInboxRouter() {
   registerSeams();
   const router = express.Router();
@@ -152,6 +172,10 @@ module.exports = function buildInboxRouter() {
       grade: { type: 'string', maxLength: 16 },
       template_key: { type: 'string', maxLength: inbox.TEMPLATE_KEY_MAX },
       field_values: { type: 'object' },
+      // task 1004092 / BV2.R13 — the author's own reading of how big this
+      // turned out: 'goal' or 'criterion'. OPTIONAL, permanently (see the
+      // refusal below and ideas_009's header).
+      recommendation: { type: 'string', maxLength: 16 },
     })) return;
     const body = req.body || {};
     if (body.kind === 'criterion-proposal') {
@@ -180,6 +204,18 @@ module.exports = function buildInboxRouter() {
       });
     }
     const templateKey = body.template_key ?? undefined;
+    // task 1004092 / BV2.R13. Checked BEFORE any write, like the field values
+    // below — and REFUSED on a non-full capture rather than dropped, because a
+    // quick idea writes no grade row at all, so silently accepting one would
+    // return 201 for a recommendation that was never stored anywhere.
+    if (refuseBadRecommendation(res, body.recommendation)) return;
+    if (body.recommendation !== undefined && grade !== 'full') {
+      return res.fail('recommendation_needs_full_grade', 400, {
+        grade: grade ?? 'quick',
+        reason: 'only a Full Idea recommends a scope — a quick idea has no grade row to carry one.',
+      });
+    }
+    const recommendation = inbox.normalizeRecommendation(body.recommendation);
     if (grade === 'full') {
       // Validate BEFORE any write, so a bad payload is a named 400 and no
       // orphan idea lands. Each error carries { field, reason } — the
@@ -236,11 +272,13 @@ module.exports = function buildInboxRouter() {
             ...(templateKey ? { templateKey } : {}),
             fieldValues: body.field_values,
             completenessScore: completenessScore(body.field_values, templateKey ? { templateKey } : undefined),
+            recommendation,
           });
           idea.grade = row.grade;
           idea.template_key = row.template_key;
           idea.field_values = row.field_values;
           idea.completeness_score = row.completeness_score;
+          idea.recommendation = row.recommendation ?? null;
 
           // Stream 2 (ADR 0172 / IC2): a Full Idea that clears the completeness
           // bar pays its author, once, on the IDEATOR credit lane — a separate
@@ -502,6 +540,22 @@ module.exports = function buildInboxRouter() {
             substance_min: f.substanceMin || 0,
           };
         }),
+        // task 1004092 / BV2.R13. The recommendation is NOT a sixth field — it
+        // is not prose, it is not scored, and it is the same closed question
+        // under every vintage — so it rides beside `fields` rather than in it.
+        // Served from here for the same reason the fields are: a hard-coded
+        // radio pair in the browser is the "second copy of the rules" defect
+        // one step earlier, and it would offer a vocabulary the CHECK
+        // constraint could already have widened past.
+        recommendation: {
+          label: 'What do you think this is',
+          hint: 'Your reading of how big it turned out. The board decides — this is what they read while deciding.',
+          required: false,
+          options: inbox.VALID_RECOMMENDATIONS.map((value) => ({
+            value,
+            label: value === 'goal' ? 'A goal of its own' : 'A criterion inside an existing goal',
+          })),
+        },
       },
     });
   }, { errorCode: 'template_read_failed' }));
@@ -748,7 +802,9 @@ module.exports = function buildInboxRouter() {
     if (validateOrRespond(req, res, {
       field_values: { required: true, type: 'object' },
       template_key: { type: 'string', maxLength: 64 },
+      recommendation: { type: 'string', maxLength: 16 },
     })) return;
+    if (refuseBadRecommendation(res, req.body.recommendation)) return;
     try {
       const idea = await inbox.getIdea(id);
       if (!idea) return res.fail('idea_not_found', 404);
@@ -798,8 +854,15 @@ module.exports = function buildInboxRouter() {
         ...(templateKey ? { templateKey } : {}),
         fieldValues: req.body.field_values,
         completenessScore: completenessScore(req.body.field_values, templateKey ? { templateKey } : undefined),
+        // task 1004092 / BV2.R13. CARRIED FORWARD FROM THE STORED ROW when the
+        // body names none — the same `?? idea.…` shape template_key uses two
+        // lines up, and for a sharper reason. setIdeaGrade writes the WHOLE
+        // row, so defaulting to null here would mean that answering a board
+        // objection silently withdrew the scope recommendation the board had
+        // been shown, on a request that never mentioned it.
+        recommendation: inbox.normalizeRecommendation(req.body.recommendation ?? idea.recommendation ?? undefined),
       });
-      const out = { ...idea, grade: row.grade, template_key: row.template_key, field_values: row.field_values, completeness_score: row.completeness_score };
+      const out = { ...idea, grade: row.grade, template_key: row.template_key, field_values: row.field_values, completeness_score: row.completeness_score, recommendation: row.recommendation ?? null };
 
       try {
         const reward = api.resolveOptional && api.resolveOptional('reward');
@@ -995,7 +1058,9 @@ module.exports = function buildInboxRouter() {
     if (validateOrRespond(req, res, {
       field_values: { required: true, type: 'object' },
       template_key: { type: 'string', maxLength: 64 },
+      recommendation: { type: 'string', maxLength: 16 },
     })) return;
+    if (refuseBadRecommendation(res, req.body.recommendation)) return;
 
     const idea = await inbox.getIdea(id);
     if (!idea) return res.fail('idea_not_found', 404);
@@ -1040,6 +1105,11 @@ module.exports = function buildInboxRouter() {
       ...(templateKey ? { templateKey } : {}),
       fieldValues: req.body.field_values,
       completenessScore: completenessScore(req.body.field_values, templateKey ? { templateKey } : undefined),
+      // task 1004092 / BV2.R13. No `?? idea.recommendation` fallback here, and
+      // that is not an omission: a spark has no recommendation to inherit (the
+      // question belongs to the full grade), so the developer is the first
+      // person ever asked it on this row.
+      recommendation: inbox.normalizeRecommendation(req.body.recommendation),
     });
     // Zero rows means the guard fired: somebody else developed this spark between
     // the read above and this write. Their work stands; this caller is told so
@@ -1070,6 +1140,7 @@ module.exports = function buildInboxRouter() {
       completeness_score: row.completeness_score,
       developed_by: row.developed_by,
       developed_at: row.developed_at,
+      recommendation: row.recommendation ?? null,
     };
 
     // Fail-open, exactly like the capture and resubmit paths: the development has

package/modules/ideas/routes/ratify-goal.js

@@ -0,0 +1,163 @@
+// modules/ideas/routes/ratify-goal.js — POST /inbox/:id/ratify-goal, the route
+// that turns a Full Idea the board has carried into a GOAL (task 1004096 /
+// BV2.R17, spec R23, goal 1000095, criterion `ideator-full-idea-shapes-the-space`).
+//
+// WHY IT IS ITS OWN FILE, and not one more route in inbox.js. That file sits at
+// the 1,500-line size ratchet (`scripts/gds/fitness-ratchets.js` OVERSIZE_LINES)
+// and this route pushed it 24 lines over. Trimming back under would have left it
+// at ~1,497 — a landmine for whoever adds the next line — so the route moved
+// out instead. It is the same call `trail-descent.js`, `trail-size.js` and
+// `projection.js` were carved out on, and projection.js's own header names the
+// failure mode being avoided: a ceiling that has "started deciding the design
+// rather than the domain".
+//
+// It is also a clean cut on the domain, not only on the line count. Everything
+// in inbox.js is INTAKE — a thought entering the system and becoming work, or
+// not. This is the opposite end: a thought that has already been through the
+// Board Room, becoming the structure other people's work lands in. The
+// criterion half of ratification (`POST /inbox/:id/ratify`) stays in inbox.js
+// where it has always been; moving it would be a rename with no argument behind
+// it, and the two halves are documented as deliberately asymmetrical anyway
+// (see `../ratify.js`).
+//
+// ROUTE ORDER IS NOT AT RISK HERE, unlike the literal paths inbox.js warns
+// about. Express matches whole paths, so `/inbox/:id` cannot swallow
+// `/inbox/:id/ratify-goal` however the two files are mounted. A literal segment
+// AFTER a param — the `/tasks/removal-proposals` trap the lifecycle map
+// records — is a different shape from a literal segment after a param plus a
+// further segment, which is what this is.
+//
+// MODULE BOUNDARY (ADR 0093 §1): auth gates and request validators reach through
+// the published doorway `src/module-api.js`; `../inbox` is an intra-module
+// sibling. Never a core internal, never another module.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const inbox = require('../inbox');
+
+const log = api.logger('ideas');
+const { validateOrRespond, LIMITS, parseId } = api;
+
+module.exports = function buildRatifyGoalRouter() {
+  const router = express.Router();
+
+  // The fields a ratify-goal refusal may put on the wire — an ALLOWLIST, not a
+  // `{ ...err }` spread. Every shape thrown by `ratifyFullIdeaAsGoal` today is a
+  // plain typed refusal this code constructs itself, so a spread is harmless
+  // TODAY; what it is not is harmless tomorrow. A later call site that let a
+  // real exception carrying a `.code` fall into this catch would echo whatever
+  // else that object holds, and the refusals here already spread two internal
+  // objects into themselves (the composer's result, the lifecycle port's
+  // verdict) — so `ok`, `description` and `criterionMd` are all one edit away
+  // from the response body. Naming them explicitly costs nothing and means a
+  // new internal field is invisible by default rather than published by default.
+  const RATIFY_GOAL_DETAIL_FIELDS = [
+    'message',      // a gate's own sentence, written to be read by the caller
+    'reason',       // why the composer refused
+    'field',        // which answer was missing
+    'template_key', // which vintage has no goal shape
+    'grade',        // what the idea actually is, when it is not Full
+    'status',       // the idea's status, when it is no longer open
+    'version_status', 'unknown', 'valid', 'scope_modules', 'detail',
+  ];
+  const ratifyGoalDetail = (err) => {
+    const out = {};
+    for (const k of RATIFY_GOAL_DETAIL_FIELDS) {
+      if (err[k] !== undefined) out[k] = err[k];
+    }
+    return out;
+  };
+
+  // BV2.R17 (task 1004096, spec R23, goal 1000095) — ratify a FULL IDEA into a
+  // GOAL, atomically:
+  //   - INSERT goals (title from the idea, description = its five answers)
+  //   - INSERT done_when_criteria on that goal from the "what does a successful
+  //     implementation look like" answer
+  //   - UPDATE idea_inbox SET status='promoted', reviewed_at=now()
+  //   - INSERT ideas_goal_ratifications — who ratified, under which board
+  //     decision, with the author's own recommendation recorded beside it
+  // All of it in one transaction; a partial failure rolls back to an open idea.
+  //
+  // A SEPARATE ROUTE FROM /ratify, not a mode of it. The two take different
+  // subjects (a `criterion-proposal` idea whose body_md is JSON vs. a graded Full
+  // Idea whose answers are prose), produce different rows, and differ on whether
+  // the board has a say. One route with a discriminator would have to document
+  // which half of its own body applies, and a caller who got the discriminator
+  // wrong would be told about a field rather than about the act.
+  //
+  // THE SCOPE AND THE VERSION COME FROM THE REQUEST because nothing else can
+  // supply them: no prose answer says which version a goal belongs to or which
+  // modules it may touch. THE GATES DO NOT come from the request — the handler
+  // passes the caller's LIVE rank through to the lifecycle port, which applies
+  // every check POST /goals applies (unknown module key, protected scope →
+  // Archon, a building version's goal set closed without a named Archon
+  // admission). `idea.ratify`'s floor is Metic, so those gates are load-bearing
+  // here rather than ceremonial.
+  //
+  // Statuses: 400 a bad body / an unratifiable idea / an unmappable template ·
+  // 403 a rank gate · 404 no such idea · 409 the idea is not open, the board has
+  // not passed it, the version will not take a goal, or it is already ratified.
+  router.post(
+    '/inbox/:id/ratify-goal',
+    api.requireBuilder,
+    api.requirePermission('idea.ratify'),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        target_version: { required: true, type: 'string', minLength: 1, maxLength: 64 },
+        scope_modules: { type: 'array', maxItems: 64, itemsType: 'string' },
+        // Mirrors POST /goals: the PRESENCE of a reason IS the override, so one
+        // cannot be requested without stating a cause, and minLength 8 because
+        // 'ok' is not a reason.
+        admit_reason: { type: 'string', minLength: 8, maxLength: 500 },
+        notes_md: { type: 'string', maxLength: LIMITS.NOTES },
+      })) return;
+      const id = parseId(req, res, { code: 'bad_id' });
+      if (id === null) return;
+      try {
+        const result = await inbox.ratifyFullIdeaAsGoal(id, req.builder.id, {
+          targetVersion: req.body.target_version,
+          scopeModules: req.body.scope_modules || [],
+          admitReason: (req.body.admit_reason || '').trim() || null,
+          // The live rank read off the authenticated request, never a body field
+          // (ADR 0016) — the port denies when it is absent.
+          actorRank: req.builder.rank,
+          notesMd: typeof req.body.notes_md === 'string' ? req.body.notes_md : '',
+        });
+        res.status(201).json({ ok: true, ...result });
+      } catch (err) {
+        if (err && err.code) {
+          // A refusal that already carries its own status is one the lifecycle
+          // port named (the goal-creation gates) — rendered as given rather than
+          // re-mapped here, so the two files cannot disagree about what a gate
+          // returns.
+          if (Number.isInteger(err.status)) {
+            return res.fail(err.code, err.status, ratifyGoalDetail(err));
+          }
+          const status =
+            err.code === 'IDEA_NOT_FOUND' ? 404 :
+            err.code === 'NOT_A_FULL_IDEA' ? 400 :
+            err.code === 'CANNOT_COMPOSE_GOAL' ? 400 :
+            err.code === 'TARGET_VERSION_REQUIRED' ? 400 :
+            err.code === 'BAD_ID' ? 400 :
+            err.code === 'BAD_RATIFIER' ? 400 :
+            err.code === 'IDEA_NOT_OPEN' ? 409 :
+            err.code === 'BOARD_HAS_NOT_PASSED' ? 409 :
+            err.code === 'NO_LIFECYCLE' ? 503 :
+            err.code === 'NO_BOARD' ? 503 :
+            500;
+          if (status !== 500) return res.fail(err.code, status, ratifyGoalDetail(err));
+        }
+        // The UNIQUE trips are the double-ratification guards: one on the audit
+        // row's idea_id, one on (version_id, criterion_id). Either means this
+        // idea has already become a goal.
+        if (err && err.code === '23505') {
+          return res.fail('IDEA_ALREADY_RATIFIED', 409, { detail: 'This idea has already been ratified into a goal.' });
+        }
+        log.error('[gds] POST /inbox/:id/ratify-goal', err);
+        res.fail('ratify_goal_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  return router;
+};

package/modules/ideas/templates.js

@@ -35,13 +35,25 @@
 // resolve its own registry and pass it through; nothing below cares where a
 // registry came from. No customization UI, no config plumbing — just the seam.
 //
-// Same-module import: DEFAULT_TEMPLATE_KEY and the payload cap live in inbox.js
-// (declared there for the route validators, mirroring the DB constraints) — one
-// source, so this file can never drift from what the store accepts.
+// Same-module import: DEFAULT_TEMPLATE_KEY and the payload cap live in
+// projection.js (declared there for the route validators, mirroring the DB
+// constraints) — one source, so this file can never drift from what the store
+// accepts.
+//
+// IT READS THEM FROM projection.js, NOT FROM inbox.js, and that is load-bearing
+// rather than tidy. Both names are the same constants either way — inbox.js only
+// re-exports what the 1004115 carve moved down to projection.js — but inbox.js
+// requires ./ratify, so importing them from there makes this file part of a
+// require CYCLE the moment anything in the ratify half wants a template
+// (BV2.R17 wants exactly that: a Full Idea's answers are ordered by the
+// declaration here). projection.js requires NOTHING, by design — its own header
+// calls that out as the property that keeps the module acyclic — so reading the
+// constants from the file that declares them is both shorter and the only
+// spelling that stays acyclic.
 
 'use strict';
 
-const { DEFAULT_TEMPLATE_KEY, FIELD_VALUES_MAX } = require('./inbox');
+const { DEFAULT_TEMPLATE_KEY, FIELD_VALUES_MAX } = require('./projection');
 
 // The five base fields, verbatim from the owner's brief. `key` is the stable
 // snake_case identity `field_values` is stored under (renaming a label is free;

package/modules/lifecycle/goal-from-idea.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// modules/lifecycle/goal-from-idea.js — creating the GOAL a ratified Full Idea
+// becomes, inside somebody else's transaction (task 1004096 / BV2.R17, spec R23,
+// goal 1000095, criterion `ideator-full-idea-shapes-the-space`).
+//
+// WHY THIS LIVES IN LIFECYCLE AND NOT IN modules/ideas. `goals`, `versions` and
+// `done_when_criteria` are this module's tables, and the ideas module may not
+// import lifecycle (the one-way module rule, ADR 0083). The alternative was to
+// widen the `lifecycle` port with four primitives — getVersion, createGoal,
+// createCriterion, authorizeGoalCreate — and let the ideas module compose them.
+// That is the shape to avoid: composing them IS the policy, and the policy is
+// "may a goal be created here, by this rank, with this scope", which is a
+// lifecycle judgement. Handing a caller the four pieces hands them four chances
+// to leave one out, and the one most easily left out is the gate.
+//
+// SO THIS IS ONE PORT CALL THAT EITHER CREATES BOTH ROWS OR NAMES ITS REFUSAL.
+// The ideas module supplies the DATA a ratification carries (title, the five
+// answers, the version and scope the board chose) and the actor's live rank; it
+// never gets to decide whether the create is allowed.
+//
+// IT RUNS IN THE CALLER'S TRANSACTION (`deps.client`, required — see below), for
+// the ensureMaintenanceGoal reason: a goal committed on its own connection would
+// survive a rolled-back ratification as an empty goal nobody asked for, pointing
+// at an idea still sitting `open` in the inbox.
+//
+// EVERY GATE POST /goals APPLIES IS APPLIED HERE, and that is the point of the
+// file rather than a courtesy. `idea.ratify`'s floor is METIC (ADR 0157 lowered
+// it from archon), while `POST /goals` refuses a protected-`scope_modules` goal
+// to anyone below Archon and refuses to grow a BUILDING version's goal set at
+// all without a named Archon admission. A ratification path that skipped either
+// would be a Metic-reachable way around both — the scope wall and the R03 gate
+// would still be in the code and no longer in the way of anything.
+
+const api = require('../../src/module-api');
+const db = require('./db.js');
+const { authorizeGoalCreate } = require('./routes/goal-route-authz.js');
+
+const { isModuleKey, scopeIncludesProtected, moduleKeys } = api.moduleScopeMap;
+
+// A typed refusal, never a throw: the caller is inside a transaction it has to
+// roll back itself, and an exception thrown across a port is the thing that
+// makes a rollback easy to forget. `status` travels with the refusal so the
+// route renders it without a second mapping table.
+function refuse(code, status, extra = {}) {
+  return { ok: false, code, status, ...extra };
+}
+
+// createRatifiedGoal — the goal + its first done-when criterion, in the caller's
+// transaction, or a named refusal.
+//
+// `criterionMd` is REQUIRED and is not a convenience. The criterion is what makes
+// the created row a goal in this project's sense rather than an empty container:
+// ADR 0263's close gate reads done-when criteria, so a goal born with none can
+// never be achieved and holds its version open forever. BV2.R17's whole claim is
+// that a Full Idea's "what does a successful implementation look like" answer IS
+// that criterion — so the two rows are one act, and this function will not make
+// the first without the second.
+//
+// `criterionRef` is the stable `criterion_id` text. The caller derives it from
+// the source idea (`idea-<n>`), which makes the UNIQUE (version_id,
+// criterion_id) constraint a second, database-level guard against ratifying the
+// same idea twice onto the same version — the `proposal-<idea_id>` trick
+// ratifyCriterionProposal already uses, for the same reason.
+async function createRatifiedGoal(
+  { versionId, title, description = null, subtitle = null, scopeModules = [], createdBy = null,
+    criterionMd, criterionRef, admitReason = null, actorRank = null },
+  deps = {}
+) {
+  if (!deps.client) {
+    // Not a policy refusal — a programming error, and one whose consequence is a
+    // half-committed ratification. It throws rather than returning, because no
+    // caller can sensibly handle it and none should try.
+    throw new Error('createRatifiedGoal requires deps.client — it must run in the ratification transaction');
+  }
+  if (typeof title !== 'string' || !title.trim()) return refuse('TITLE_REQUIRED', 400);
+  if (typeof criterionMd !== 'string' || !criterionMd.trim()) return refuse('CRITERION_REQUIRED', 400);
+  if (typeof criterionRef !== 'string' || !criterionRef.trim()) return refuse('CRITERION_REF_REQUIRED', 400);
+
+  const scope = Array.isArray(scopeModules) ? scopeModules : [];
+  // Fail closed on an unknown module key, POST /goals' first gate: a scope wall
+  // that can name a module which does not exist is not a wall.
+  const unknown = scope.filter((k) => !isModuleKey(k));
+  if (unknown.length) return refuse('UNKNOWN_MODULE', 400, { unknown, valid: moduleKeys() });
+  // The two RANK gates. `actorRank` is the caller's LIVE rank read (ADR 0016) —
+  // never a value a request body carried — and an absent rank denies, because a
+  // rank we were not told is not a rank we may assume.
+  if (scopeIncludesProtected(scope) && actorRank !== 'archon') {
+    return refuse('ARCHON_REQUIRED_FOR_PROTECTED_SCOPE', 403, { scope_modules: scope });
+  }
+  const reason = typeof admitReason === 'string' ? admitReason.trim() || null : null;
+  // Refused by RANK before the version is fetched, the POST /goals ordering: a
+  // Metic must not learn whether the override would have worked.
+  if (reason !== null && actorRank !== 'archon') {
+    return refuse('ARCHON_REQUIRED_FOR_ADMISSION', 403);
+  }
+
+  // FOR UPDATE, so a version freeze committing between this read and this
+  // transaction's COMMIT cannot leave the goal and its criterion on a version
+  // that closed underneath them (getVersion's own note explains why a plain read
+  // is not enough under READ COMMITTED).
+  const version = await db.getVersion(versionId, { client: deps.client, forUpdate: true });
+  const decision = authorizeGoalCreate({ version, override: reason !== null });
+  if (!decision.ok) {
+    return refuse(decision.body.error, decision.status, { message: decision.body.message, version_status: decision.body.status });
+  }
+
+  const goal = await db.createGoal({
+    versionId,
+    title: title.trim(),
+    subtitle,
+    description,
+    scopeModules: scope,
+    createdBy,
+    // The admission row is written ONLY when the override actually opened the
+    // gate — `overrideApplied`, not "a reason was supplied". A reason on a
+    // planning version changed nothing and must not be filed as a skipped gate.
+    admission: decision.overrideApplied ? { admittedBy: createdBy, reason } : null,
+  }, { client: deps.client });
+
+  const criterion = await db.createCriterion({
+    versionId,
+    criterionId: criterionRef.trim(),
+    criterionMd,
+    goalId: goal.id,
+  }, { client: deps.client });
+
+  return { ok: true, goal, criterion, admitted: decision.overrideApplied };
+}
+
+module.exports = { createRatifiedGoal };

package/modules/lifecycle/lifecycle.js

@@ -19,6 +19,7 @@
 const db = require('./db');
 const classifier = require('./task-classifier');
 const goalSuggest = require('./goal-suggest');
+const goalFromIdea = require('./goal-from-idea');
 const helpRequests = require('./help-requests');
 const taskRecommendations = require('./task-recommendations');
 const activity = require('./activity');
@@ -66,6 +67,19 @@ module.exports = {
   // lifecycle tables and the ideas module may not import lifecycle (ADR 0083).
   ensureMaintenanceGoal: (...a) => db.ensureMaintenanceGoal(...a),
   currentBuildingVersionId: (...a) => db.currentBuildingVersionId(...a),
+  // createRatifiedGoal (task 1004096 / BV2.R17): the GOAL a ratified Full Idea
+  // becomes, plus the done-when criterion its "what does a successful
+  // implementation look like" answer supplies — both rows, in the ideas module's
+  // ratification transaction, or one named refusal.
+  //
+  // ONE CALL RATHER THAN FOUR PRIMITIVES, deliberately. The ideas module could
+  // have been handed getVersion + createGoal + createCriterion +
+  // authorizeGoalCreate and left to compose them, but composing them IS the
+  // goal-creation policy — the scope wall, the rank gates, the R03 building-
+  // version gate — and that policy is a lifecycle judgement. `idea.ratify`'s
+  // floor is Metic, so a caller free to leave the gate out would be a
+  // Metic-reachable way around it. See modules/lifecycle/goal-from-idea.js.
+  createRatifiedGoal: (...a) => goalFromIdea.createRatifiedGoal(...a),
 
   // --- work-tracking READS the staying-core read routes resolve --------------
   // public.js (the status surface): version/ship feed + grade trend.

package/package-lock.json

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

package/package.json

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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.935'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.937'; // 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/government_board_view.mjs

@@ -69,7 +69,11 @@ test('the assembled view: enrichment, the open ballot, the snapshot, the databas
 
   const idea = view.open[0];
   assert.deepEqual(idea.subject,
-    { title: 'A big idea', author_id: '9', field_values: { purpose: 'p' }, template_key: 'base-v1', completeness_score: 82 },
+    // `recommendation: null` is the stored row's own answer, not a filler: this
+    // stub idea has no recommendation column set, and BV2.R13's whole posture is
+    // that "the author did not say" must reach the room as itself rather than
+    // being dropped or defaulted to one of the two values.
+    { title: 'A big idea', author_id: '9', field_values: { purpose: 'p' }, template_key: 'base-v1', completeness_score: 82, recommendation: null },
     'an idea shows its title, author, AND its five sections — the voter decides with the idea in front of them (R17)');
   assert.equal(idea.remaining_seconds, 540, 'the DATABASE clock, passed through — the client never does clock math');
   assert.deepEqual(idea.constitution, MONARCHY, 'the SNAPSHOT rides along — the room describes the rule the item runs under');

package/tests/government_seed.mjs

@@ -42,6 +42,7 @@ const NON_GRANT_MIGRATIONS = new Set([
   'government_007_amendments.sql',                 // R14 amendment proposals table (task 1003027)
   'government_008_closed_items_index.sql',         // R16 closed-history index (task 1003029)
   'government_017_board_section_keys_v2.sql',      // BV2.R06 board section_key CHECK widening (task 1004085)
+  'government_018_passed_items_index.sql',         // BV2.R17 passed-item lookup index (task 1004096)
 ]);
 
 // Permission keys RENAMED after the grant migrations that first granted them.

package/tests/idea_develop_spark.mjs

@@ -145,7 +145,12 @@ await test('a DISTINCT developer is recorded, and both parties are named in the
   assert.equal(r.payload.developer_id, '42');
   assert.equal(r.payload.author_id, '9');
   assert.equal(r.payload.self_developed, false);
-  assert.equal(updateQ().params.at(-1), '42', 'the developer is the AUTHENTICATED builder, not a body field');
+  // The developer is $5 in developSpark's UPDATE. Pinned by INDEX, not by
+  // `.at(-1)`: task 1004092 appended `recommendation` as $6, and a pin that
+  // meant "the developer" while reading "the last parameter" then failed for a
+  // reason that had nothing to do with what it was asserting.
+  assert.equal(updateQ().params[4], '42', 'the developer is the AUTHENTICATED builder, not a body field');
+  assert.equal(updateQ().params.length, 6, 'developSpark binds six parameters — a new one must be placed deliberately');
 });
 
 await test('self-development is legal and reported as such', async () => {