@bongos/core 1.19.936 → 1.19.937

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/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,
 };

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;