@bongos/core 1.19.935 → 1.19.937

package/modules/ideas/migrations/ideas_009_recommendation.sql

@@ -0,0 +1,62 @@
+-- ideas_009_recommendation.sql — a Full Idea carries a RECOMMENDATION: goal or
+-- criterion (task 1004092 / BV2.R13, spec R22 in
+-- docs/specs/bongos-v2-ideator-surface.md; spec decision 9).
+--
+-- WHAT THIS IS, AND WHAT IT IS NOT. It is the ideator's answer to "how big did
+-- this turn out to be" — a goal (a gravity well of its own) or a criterion (a
+-- ring inside an existing one). It is NOT a decision. The owner's recorded
+-- reasoning: scope is the thing you learn last, so the person who had the
+-- thought writes down what they think it is and the board, reading it, decides.
+-- Nothing in the system may branch on this column as if it were an outcome —
+-- the ratification half (BV2.R17) reads what the BOARD chose, and this column
+-- only travels alongside it so voters can see what was proposed.
+--
+-- WHY A COLUMN AND NOT A SIXTH TEMPLATE FIELD. The five questions are prose an
+-- author writes and the completeness scorer measures; this is a closed
+-- two-value vocabulary that nothing scores. Putting it in `field_values` would
+-- make it a scored field (`completeness.js` walks every declared field), would
+-- change what a Full Idea costs to file, and would have to be declared once per
+-- vintage — while the recommendation is the same question under any template.
+-- It is a property OF the grade row, beside `completeness_score`, not one of
+-- the answers inside it.
+--
+-- NULLABLE, AND THAT IS PERMANENT. Every Full Idea filed before today has no
+-- recommendation, and inventing one for them would put words in an author's
+-- mouth — the never-invent-a-field rule (the Ideator pack) is exactly about
+-- this. So NULL means "the author did not say", every reader must render that
+-- honestly, and there is no backfill. The hall composer requires a choice
+-- going forward (that is where the question is actually asked); the API keeps
+-- it optional, because a reader that can handle NULL for the historical rows
+-- can handle NULL for a terse CLI filing too, and a required body field would
+-- 400 every already-shipped client against an upgraded instance.
+--
+-- Text + CHECK rather than a Postgres enum TYPE, matching
+-- `ideas_grades_grade_chk` one column over: the vocabulary is pinned closed
+-- today (an unknown recommendation is refused, never silently stored) and
+-- widening it later is a one-line constraint change in a subsequent ideas_*
+-- migration rather than an enum-type migration.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): this
+-- touches only `ideas_grades`, a table this module owns. There is no
+-- down-migration. Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE ideas_grades
+  ADD COLUMN IF NOT EXISTS recommendation text;
+
+-- Added separately and guarded, because ADD COLUMN IF NOT EXISTS skips the
+-- whole clause on a re-run — an inline CONSTRAINT would then never be created
+-- on an instance where the column already landed without it.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'ideas_grades_recommendation_chk'
+  ) THEN
+    ALTER TABLE ideas_grades
+      ADD CONSTRAINT ideas_grades_recommendation_chk
+      CHECK (recommendation IS NULL OR recommendation IN ('goal', 'criterion'));
+  END IF;
+END $$;
+
+COMMIT;

package/modules/ideas/migrations/ideas_010_goal_ratification.sql

@@ -0,0 +1,103 @@
+-- ideas_010_goal_ratification.sql — the durable record of a Full Idea having
+-- been ratified INTO A GOAL (task 1004096 / BV2.R17, spec R23 in
+-- docs/specs/bongos-v2-ideator-surface.md; spec decision 9).
+--
+-- WHAT THIS TABLE IS FOR. The ratification writes a goal and a done-when
+-- criterion into the LIFECYCLE tables and flips the idea to `promoted`. Those
+-- rows are the outcome; none of them records the ACT. Afterwards the goal looks
+-- exactly like a goal someone scoped in a planning session, and the idea looks
+-- exactly like an idea that became a task. Nothing left says who ratified it,
+-- under which board decision, with what scope, or what the author had
+-- recommended — and "a thought is never lost between having it and learning what
+-- it caused" (criterion `ideator-nothing-is-lost`) is not met by an outcome with
+-- no provenance. This is the `criterion_proposal_audit` argument (migration 042)
+-- applied to the goal half.
+--
+-- `idea_id` IS UNIQUE, AND THAT IS THE IDEMPOTENCY. The transaction also refuses
+-- an idea whose status is no longer `open`, which catches the ordinary second
+-- attempt; this constraint is what catches the two-concurrent-ratifications race
+-- the status check cannot, because both would read `open` before either wrote.
+-- The second INSERT trips 23505 and its whole transaction rolls back, so the
+-- outcome is one goal, never two.
+--
+-- `recommendation_at_filing` IS PROVENANCE, NOT AN INPUT. It stores what the
+-- AUTHOR recommended (ideas_009) beside what the BOARD chose, so the two can be
+-- compared after the fact — how often does the board agree with the ideator? —
+-- without that ever having influenced the ratification. NULL is first-class and
+-- permanent here for the same reason it is on ideas_grades: every Full Idea
+-- filed before BV2.R13 shipped carries no recommendation, there is no backfill,
+-- and inventing one would put a scope opinion in an author's mouth. Nothing may
+-- branch on this column.
+--
+-- FOREIGN KEYS POINT AT CORE TABLES, which is allowed and is what the module's
+-- own precedent does: ideas_002 references `tasks(id)`, ideas_005 references
+-- `builders(id)`. The namespacing rule (ADR 0083 §Decision #5) is about which
+-- tables a module may CREATE and ALTER, not about what its own rows may point
+-- at.
+--
+-- NONE OF THE FOUR FKs CASCADES, and that is the deliberate part. An audit row
+-- exists to say what happened; a cascade would delete the record of a
+-- ratification along with the goal it produced, which is precisely when someone
+-- wants to read it. `criterion_proposal_audit` (migration 042) takes the same
+-- posture on the same reasoning. The consequence is accepted: a hard DELETE of a
+-- ratified goal is refused while its audit row stands, and that refusal is
+-- correct — goals are archived, not deleted.
+--
+-- `scope_modules` is stored as text[] matching `goals.scope_modules`, because
+-- WHICH WALL the goal was given is part of what was decided — a ratification
+-- that admitted a protected module is an Archon act and the row has to say so
+-- even after someone later widens or narrows the live goal.
+--
+-- Module migrations are ADDITIVE and NAMESPACED. There is no down-migration.
+-- Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS ideas_goal_ratifications (
+  id                      bigserial PRIMARY KEY,
+  idea_id                 bigint NOT NULL REFERENCES idea_inbox(id),
+  goal_id                 bigint NOT NULL REFERENCES goals(id),
+  criterion_id            bigint NOT NULL REFERENCES done_when_criteria(id),
+  board_item_id           bigint,
+  target_version          text   NOT NULL,
+  scope_modules           text[] NOT NULL DEFAULT '{}',
+  recommendation_at_filing text,
+  proposed_by             bigint REFERENCES builders(id),
+  ratified_by             bigint NOT NULL REFERENCES builders(id),
+  notes_md                text   NOT NULL DEFAULT '',
+  ratified_at             timestamptz NOT NULL DEFAULT now()
+);
+
+-- One ratification per idea — see the header. Added separately and guarded so it
+-- still lands on an instance where the table was created before this clause
+-- existed.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'ideas_goal_ratifications_idea_uniq'
+  ) THEN
+    ALTER TABLE ideas_goal_ratifications
+      ADD CONSTRAINT ideas_goal_ratifications_idea_uniq UNIQUE (idea_id);
+  END IF;
+END $$;
+
+-- Mirrors ideas_grades_recommendation_chk one table over: the vocabulary is
+-- closed, and NULL means "the author did not say".
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'ideas_goal_ratifications_recommendation_chk'
+  ) THEN
+    ALTER TABLE ideas_goal_ratifications
+      ADD CONSTRAINT ideas_goal_ratifications_recommendation_chk
+      CHECK (recommendation_at_filing IS NULL OR recommendation_at_filing IN ('goal', 'criterion'));
+  END IF;
+END $$;
+
+-- "What did this goal come from" — the read the goal surface will want when it
+-- shows a goal's origin. The idea direction is already served by the unique
+-- constraint's index.
+CREATE INDEX IF NOT EXISTS ideas_goal_ratifications_goal_idx
+  ON ideas_goal_ratifications (goal_id);
+
+COMMIT;

package/modules/ideas/module.json

@@ -10,6 +10,7 @@
   "contributes": {
     "routes": [
       "inbox",
+      "ratify-goal",
       "blockers"
     ],
     "pollers": [

package/modules/ideas/projection.js

@@ -80,6 +80,40 @@ const TEMPLATE_KEY_MAX = 64;
 // payload gets a structured 400 instead of a constraint-violation 500.
 const FIELD_VALUES_MAX = 32768;
 
+// -------------------------------------------------------------------------
+// The recommendation (task 1004092 / BV2.R13, spec R22)
+//
+// What the author thinks their Full Idea turned out to be: a goal (a gravity
+// well of its own) or a criterion (a ring inside an existing one). A CLOSED
+// vocabulary, mirroring ideas_grades_recommendation_chk so an unknown value is
+// a named 400 at the route rather than a constraint-violation 500 in the
+// driver.
+//
+// NULL IS A FIRST-CLASS VALUE AND ALWAYS WILL BE — "the author did not say".
+// Every Full Idea filed before this shipped has no recommendation, and there is
+// no backfill, because inventing one would put a scope opinion in someone's
+// mouth. Every reader must render the absence honestly; nothing may substitute
+// a default.
+//
+// IT IS A RECOMMENDATION, NEVER A DECISION (spec decision 9). The ideator
+// recommends; the board decides. Nothing may branch on this column as if it
+// were the outcome — BV2.R17's ratification reads what the board chose.
+const VALID_RECOMMENDATIONS = ['goal', 'criterion'];
+
+// The one predicate. `undefined` and `null` both mean "not given" and are
+// legal; anything else must be a declared member. Pure, so a route can refuse
+// before any write and a test can exercise it with no harness.
+function isValidRecommendation(v) {
+  return v === null || v === undefined || VALID_RECOMMENDATIONS.includes(v);
+}
+
+// Normalise a request-supplied value to what the column stores. Written once
+// because three routes (capture, develop, resubmit) all take the same field and
+// all have to turn "absent" into NULL rather than into the string 'undefined'.
+function normalizeRecommendation(v) {
+  return v === undefined || v === '' ? null : v;
+}
+
 // The grade half of an idea read: the COALESCE above, plus the template-shaped
 // store and the score. `g.*` columns are NULL for an ungraded idea, which is
 // exactly right — it has no template and no score, it just has a default grade.
@@ -89,16 +123,22 @@ const FIELD_VALUES_MAX = 32768;
 // hall detail view (R153) and the R147 credit split all want it. NULL for the
 // overwhelming majority of rows — a quick idea and a self-authored Full Idea were
 // never developed by anyone — which is the honest answer, not a missing one.
+//
+// `recommendation` (ideas_009, task 1004092 / BV2.R13) rides along for the same
+// reason developed_by does: it is part of a Full Idea's identity from filing
+// onwards, and the board item, the detail read and the author's own trail all
+// want it without a second query. NULL for every quick idea and for every Full
+// Idea filed before the question existed — the honest answer, not a missing one.
 const GRADE_COLS_Q = `COALESCE(g.grade, '${DEFAULT_GRADE}') AS grade,
             g.template_key, g.field_values, g.completeness_score,
-            g.developed_by, g.developed_at`;
+            g.developed_by, g.developed_at, g.recommendation`;
 const IDEA_JOIN_GRADE = `LEFT JOIN ideas_grades g ON g.idea_id = i.id`;
 
 // The same projection for a row that provably has no grade row yet (a just-
 // INSERTed idea), so INSERT…RETURNING does not need a second round trip to
 // return the same shape every other read returns.
 function ungradedProjection() {
-  return { grade: DEFAULT_GRADE, template_key: null, field_values: null, completeness_score: null, developed_by: null, developed_at: null };
+  return { grade: DEFAULT_GRADE, template_key: null, field_values: null, completeness_score: null, developed_by: null, developed_at: null, recommendation: null };
 }
 
 module.exports = {
@@ -110,6 +150,9 @@ module.exports = {
   TEMPLATE_KEY_RE,
   TEMPLATE_KEY_MAX,
   FIELD_VALUES_MAX,
+  VALID_RECOMMENDATIONS,
+  isValidRecommendation,
+  normalizeRecommendation,
   GRADE_COLS_Q,
   IDEA_JOIN_GRADE,
   ungradedProjection,

package/modules/ideas/ratify.js

@@ -13,7 +13,9 @@
 // Archon ratifies it into a version's scope. Keeping it beside the triage
 // writes made the two look like the same kind of act. They are not.
 
-const { pool } = require('../../src/module-api');
+const api = require('../../src/module-api');
+const { pool } = api;
+const { templateFor, fieldOrder } = require('./templates');
 
 // -------------------------------------------------------------------------
 // Criterion-proposal ratification (V3.R31 / #252)
@@ -203,9 +205,294 @@ async function ratifyCriterionProposal(ideaId, ratifierId, { notesMd = '' } = {}
   }
 }
 
+// -------------------------------------------------------------------------
+// THE GOAL HALF (task 1004096 / BV2.R17, spec R23, criterion
+// `ideator-full-idea-shapes-the-space`)
+//
+// The criterion half above turns a `criterion-proposal` — an idea filed as JSON,
+// explicitly to become a ring inside an existing well — into a
+// `done_when_criteria` row. This half turns a FULL IDEA, filed as five prose
+// answers by someone who was thinking rather than scoping, into a GOAL: a
+// gravity well of its own, with the "what does a successful implementation look
+// like" answer as its first done-when criterion.
+//
+// THE TWO HALVES ARE NOT SYMMETRICAL, and reading them as if they were is the
+// mistake to avoid:
+//
+//   • THE SUBJECT DIFFERS. The criterion half parses `body_md` as JSON the
+//     proposer wrote FOR ratification. This half reads a graded Full Idea's
+//     `field_values` — prose written to express a thought, which nobody wrote
+//     with a goal row in mind. So the shape has to be DERIVED, and which answer
+//     becomes which part of the goal is a decision recorded below.
+//
+//   • THE AUTHORITY DIFFERS. A criterion proposal is one Metic's suggestion and
+//     one ratifier's judgement; there is no board in it. A Full Idea has already
+//     been through the Board Room (`government.openBoardWindowForIdea` fires when
+//     its grade lands), and spec decision 9 is that the ideator RECOMMENDS while
+//     the BOARD DECIDES. So this half is GATED on a passed sitting, and the
+//     author's own `recommendation` is read for the audit row only.
+//
+//   • NOBODY IS PAID HERE. The criterion half awards KARMA_RATIFY_DELTA to the
+//     proposer, because nothing else ever will. A Full Idea's author was already
+//     paid at the board CLOSE — karma by `awardAuthorRatifyKarma` and credit by
+//     `awardIdeaGovernancePassCredit`, both inside the close transaction. Paying
+//     again on the ratification would pay twice for one thought, and the second
+//     payment would be invisible beside the first. This is why there is no karma
+//     INSERT below, and it is a decision rather than an omission.
+
+// WHICH ANSWER BECOMES WHICH PART OF THE GOAL, per template vintage.
+//
+// THIS IS RATIFICATION POLICY, NOT TEMPLATE SHAPE, which is why it lives here
+// and not as two more keys inside the declarations in templates.js. Those
+// declarations are FROZEN — a vintage is never edited, because `substanceMin`
+// feeds `completeness_score` and that feeds credits — and "this field supplies a
+// goal's done-when" is a statement about what ratification does with an answer,
+// not about what the question is or what it costs to answer it.
+//
+// `base-v1` IS DELIBERATELY ABSENT, and that is the honest answer rather than a
+// gap. Its five questions are Purpose / Big Picture / Why did you have it / Why
+// does it matter / How does it fit — an argument for a thought, with no answer
+// anywhere in it describing a finished implementation. A goal needs a done-when
+// criterion to be achievable at all (ADR 0263's close gate reads them, so a goal
+// born without one holds its version open forever), and there is nothing in a
+// base-v1 filing to write one FROM. Picking its closest-sounding field would be
+// inventing a success criterion on the author's behalf — the never-invent-a-field
+// rule, and the one place in this file where it bites. A base-v1 Full Idea is
+// refused with TEMPLATE_HAS_NO_GOAL_SHAPE, naming the vintage; its author can
+// resubmit against the current questions, which is what the resubmit path is for.
+//
+// ADDING A VINTAGE MEANS ADDING AN ENTRY HERE. Nothing falls back — an unmapped
+// template refuses, rather than guessing at a key that happens to exist.
+const GOAL_SHAPE_BY_TEMPLATE = Object.freeze({
+  // The five questions a Full Idea is asked today (BASE_V2_TEMPLATE). The
+  // mapping is the one the proof task (BV2.R25) states: scope from "scope it as
+  // best as you can here", done-when from "what does a successful
+  // implementation of the idea look like".
+  'base-v2': Object.freeze({ doneWhenField: 'success' }),
+});
+
+// composeGoalFromFullIdea — the five answers → the goal's prose + its first
+// criterion. PURE: no DB, no clock, no doorway, so the route can refuse before
+// opening a transaction and a test can exercise every branch with no harness.
+//
+// EVERY ANSWER LANDS IN THE DESCRIPTION, including the one that also becomes the
+// criterion. The done-when is a one-line gate a version-close reads; the
+// description is what a builder opening the goal actually reads, and dropping
+// the success answer from it to avoid "duplication" would take the clearest
+// statement of the goal's purpose out of the one place someone looks for it.
+//
+// ORDER COMES FROM `fieldOrder`, never from Object.keys(field_values) — jsonb
+// does not preserve key order, so iterating the stored row shows the five
+// answers in whatever order Postgres chose (templates.js' own header says so).
+// LABELS come from the declaration too, so a v1 row would render under v1
+// labels if a v1 shape were ever declared.
+function composeGoalFromFullIdea({ ideaId, templateKey, fieldValues } = {}) {
+  const template = templateFor(templateKey);
+  if (!template) return { ok: false, reason: 'unknown_template', template_key: templateKey ?? null };
+  const shape = Object.hasOwn(GOAL_SHAPE_BY_TEMPLATE, templateKey) ? GOAL_SHAPE_BY_TEMPLATE[templateKey] : null;
+  if (!shape) return { ok: false, reason: 'template_has_no_goal_shape', template_key: templateKey };
+  if (!fieldValues || typeof fieldValues !== 'object' || Array.isArray(fieldValues)) {
+    return { ok: false, reason: 'field_values_missing' };
+  }
+
+  const doneWhen = fieldValues[shape.doneWhenField];
+  if (typeof doneWhen !== 'string' || doneWhen.trim() === '') {
+    // A Full Idea cannot normally reach here with a blank required field —
+    // validateFieldValues refuses that at capture. It is checked anyway because
+    // the alternative is a goal whose only criterion is an empty string, which
+    // the close gate would read as satisfiable by nothing.
+    return { ok: false, reason: 'done_when_answer_missing', field: shape.doneWhenField };
+  }
+
+  const sections = [];
+  for (const key of fieldOrder(template)) {
+    const field = template.fields.find((f) => f.key === key);
+    const value = fieldValues[key];
+    // A field the stored row simply does not carry is SKIPPED, not rendered as an
+    // empty heading. Only required fields are guaranteed present, and a heading
+    // with nothing under it reads as a question the author declined to answer
+    // rather than one the template added later.
+    if (typeof value !== 'string' || value.trim() === '') continue;
+    sections.push(`### ${field.label}\n\n${value.trim()}`);
+  }
+  if (sections.length === 0) return { ok: false, reason: 'field_values_empty' };
+
+  // The provenance line is FIRST and is prose, not a machine key: the durable
+  // machine record is the ideas_goal_ratifications row. This is so a builder
+  // opening the goal learns, without asking anyone, that its scope is somebody's
+  // thought and where to go and read it whole.
+  const origin = `> Ratified from Full Idea [#${ideaId}](/idea/${ideaId}) — its five answers, as written.`;
+  return {
+    ok: true,
+    description: [origin, ...sections].join('\n\n'),
+    criterionMd: doneWhen.trim(),
+    doneWhenField: shape.doneWhenField,
+  };
+}
+
+// ratifyFullIdeaAsGoal — the whole act, in one transaction.
+//
+// a. lock the idea + its grade row      e. write the ideas_goal_ratifications row
+// b. check the board carried it         f. COMMIT
+// c. compose the goal's prose
+// d. create the goal + its criterion (through the `lifecycle` port)
+//
+// WHAT THE CALLER DECIDES AND WHAT IT DOES NOT. `targetVersion`, `scopeModules`
+// and `admitReason` are the BOARD'S choices, stated by the ratifier: no prose
+// answer can supply which version a goal belongs to or which modules it may
+// touch, and guessing either would be the system deciding scope — the exact
+// thing spec decision 9 puts in the board's hands. What the caller may NOT do is
+// decide whether the create is allowed: `actorRank` is passed through to the
+// lifecycle port, which applies every gate POST /goals applies.
+//
+// THE AUTHOR'S `recommendation` IS READ AND NEVER BRANCHED ON. It is copied into
+// the audit row beside what the board chose, so "how often does the board agree
+// with the ideator" is answerable later. A ratification of an idea whose author
+// recommended 'criterion' is NOT refused here — the board may well have decided
+// the thought was bigger than its author thought, and refusing would make the
+// recommendation a decision, which is the one thing it is not.
+async function ratifyFullIdeaAsGoal(
+  ideaId, ratifierId,
+  { targetVersion, scopeModules = [], admitReason = null, actorRank = null, notesMd = '' } = {}
+) {
+  const id = Number(ideaId);
+  if (!Number.isFinite(id)) throw { code: 'BAD_ID' };
+  const rid = Number(ratifierId);
+  if (!Number.isFinite(rid)) throw { code: 'BAD_RATIFIER' };
+  if (!targetVersion || typeof targetVersion !== 'string') throw { code: 'TARGET_VERSION_REQUIRED' };
+
+  // BOTH PORTS RESOLVE BEFORE THE TRANSACTION OPENS, and both FAIL CLOSED. An
+  // instance without the lifecycle module cannot hold goals at all; an instance
+  // without government has no board, and "the board decided" cannot be true
+  // where there is no board. A missing authority system is a denial, never an
+  // admission (the requirePermission posture).
+  const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+  if (!lifecycle || typeof lifecycle.createRatifiedGoal !== 'function') {
+    throw { code: 'NO_LIFECYCLE', detail: 'This instance cannot create goals — the lifecycle module is not mounted.' };
+  }
+  const government = api.resolveOptional && api.resolveOptional('government');
+  if (!government || typeof government.boardPassForIdea !== 'function') {
+    throw { code: 'NO_BOARD', detail: 'This instance has no Board Room, so a Full Idea cannot be ratified.' };
+  }
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // a. Read + lock the idea and its grade row together. LEFT JOIN, the module's
+    //    standing rule: an idea with no grade row reads as 'quick', and that is a
+    //    refusal below rather than a missing row here. FOR UPDATE names the idea
+    //    table explicitly — a bare FOR UPDATE over an outer join is not lockable
+    //    in Postgres, and locking the idea is what serialises two ratifiers.
+    const { rows: ideaRows } = await client.query(
+      `SELECT i.id, i.title, i.kind, i.status, i.captured_by,
+              COALESCE(g.grade, 'quick') AS grade,
+              g.template_key, g.field_values, g.recommendation
+         FROM idea_inbox i
+         LEFT JOIN ideas_grades g ON g.idea_id = i.id
+        WHERE i.id = $1
+        FOR UPDATE OF i`,
+      [id]
+    );
+    if (ideaRows.length === 0) throw { code: 'IDEA_NOT_FOUND' };
+    const idea = ideaRows[0];
+    if (idea.grade !== 'full') throw { code: 'NOT_A_FULL_IDEA', grade: idea.grade };
+    if (idea.status !== 'open') throw { code: 'IDEA_NOT_OPEN', status: idea.status };
+
+    // b. The board gate. Spec decision 9 in one statement: without a sitting that
+    //    closed `passed`, this is a ratifier's preference and not a decision.
+    //    Read through the port, outside its own transaction (a closed item is
+    //    terminal, so there is nothing here for a lock to protect).
+    const pass = await government.boardPassForIdea(id);
+    if (!pass) throw { code: 'BOARD_HAS_NOT_PASSED' };
+
+    // c. Compose. Pure, and its refusals are the caller's 400s.
+    const composed = composeGoalFromFullIdea({
+      ideaId: idea.id, templateKey: idea.template_key, fieldValues: idea.field_values,
+    });
+    if (!composed.ok) throw { code: 'CANNOT_COMPOSE_GOAL', reason: composed.reason, ...composed };
+
+    // d. The goal + its first criterion, through the port, on THIS client.
+    //    `criterionRef` is derived from the idea, so UNIQUE (version_id,
+    //    criterion_id) is a second guard against a double ratification onto the
+    //    same version — the `proposal-<idea_id>` trick, one half over.
+    //
+    //    created_by IS THE RATIFIER, NOT THE AUTHOR, and that is a security
+    //    decision rather than a credit one. createGoal makes created_by the
+    //    goal's owner AND inserts a 'lead' membership row, and goal leads author
+    //    tasks inside the scope wall. Filing an idea is open to every rank, so
+    //    owning the goal your idea became would turn "have a thought that the
+    //    board likes" into a grant of authority nobody reviewed. The author's
+    //    claim on the thought is preserved where claims belong — the audit row
+    //    below, and the origin line in the description.
+    const made = await lifecycle.createRatifiedGoal({
+      versionId: targetVersion,
+      title: idea.title,
+      description: composed.description,
+      scopeModules,
+      createdBy: rid,
+      criterionMd: composed.criterionMd,
+      criterionRef: `idea-${idea.id}`,
+      admitReason,
+      actorRank,
+    }, { client });
+    if (!made.ok) throw { code: made.code, status: made.status, ...made };
+
+    // e. Mark the idea promoted. promoted_to_task_id stays NULL — a goal is not
+    //    a task, the same reading the criterion half takes.
+    await client.query(
+      `UPDATE idea_inbox
+          SET status              = 'promoted',
+              promoted_to_task_id = NULL,
+              reviewed_at         = now()
+        WHERE id = $1`,
+      [idea.id]
+    );
+
+    // f. The audit row — who ratified what, under which decision, with what the
+    //    author had recommended beside it.
+    const { rows: auditRows } = await client.query(
+      `INSERT INTO ideas_goal_ratifications
+         (idea_id, goal_id, criterion_id, board_item_id, target_version,
+          scope_modules, recommendation_at_filing, proposed_by, ratified_by, notes_md)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id, ratified_at`,
+      [
+        idea.id, made.goal.id, made.criterion.id, pass.item_id, targetVersion,
+        Array.isArray(scopeModules) ? scopeModules : [],
+        idea.recommendation ?? null,
+        idea.captured_by, rid, notesMd || '',
+      ]
+    );
+
+    await client.query('COMMIT');
+    return {
+      goal: made.goal,
+      criterion: made.criterion,
+      admitted: made.admitted,
+      audit_id: auditRows[0].id,
+      ratified_at: auditRows[0].ratified_at,
+      board_item_id: pass.item_id,
+      // Reported back so a caller can see what the author had recommended and
+      // what the board did with it, without a second read. NULL stays NULL.
+      recommendation_at_filing: idea.recommendation ?? null,
+      done_when_from: composed.doneWhenField,
+      proposer_id: idea.captured_by,
+    };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 module.exports = {
   KARMA_RATIFY_DELTA,
   KARMA_RATIFY_REASON,
   parseProposalBody,
   ratifyCriterionProposal,
+  GOAL_SHAPE_BY_TEMPLATE,
+  composeGoalFromFullIdea,
+  ratifyFullIdeaAsGoal,
 };