@bongos/core 1.19.935 → 1.19.937

package/modules/government/board.js

@@ -861,6 +861,10 @@ async function boardRoomView({ closedLimit = 20 } = {}) {
             field_values: r.field_values || null,
             template_key: r.template_key || null,
             completeness_score: r.completeness_score ?? null,
+            // BV2.R13: the author's recommendation, in front of the voter with
+            // the sections. A RECOMMENDATION, NOT A DECISION — the board is
+            // deciding it, and nothing on this path may treat it as settled.
+            recommendation: r.recommendation ?? null,
           } : null;
         })()
       : (() => { const r = amendmentById.get(String(item.subject_id)); return r ? { proposed: r.proposed, rationale_md: r.rationale_md, author_id: r.proposed_by == null ? null : String(r.proposed_by) } : null; })();
@@ -1037,6 +1041,36 @@ async function latestRejectionForIdea(ideaId) {
   });
 }
 
+// ── BV2.R17's read: did the board CARRY this idea? (task 1004096) ───────────
+//
+// The ratification half of the ideator surface turns a Full Idea into a goal,
+// and spec decision 9 is that the ideator RECOMMENDS while the board DECIDES.
+// The ideas module holds the author's recommendation on its own grade row, so
+// without this read "the board decides" would be a sentence in a comment: the
+// only fact stopping a ratification from being one person's opinion is that a
+// sitting actually closed `passed`.
+//
+// Null means "no passing decision on record", which the caller must treat as a
+// refusal and never as an absence it may work around. A returned item, an item
+// still open, and an idea that never reached the board all read the same here,
+// on purpose — none of them is a mandate, and distinguishing them would invite a
+// caller to accept one of them.
+//
+// Frozen, like latestRejectionForIdea, so a caller cannot decorate the record of
+// a decision and pass it on as though the board had said more than it did.
+async function boardPassForIdea(ideaId) {
+  const id = Number(ideaId);
+  if (!Number.isFinite(id) || id <= 0) return null;
+  const row = await db.getLatestPassedItem('full_idea', id);
+  if (!row) return null;
+  return Object.freeze({
+    item_id: row.item_id,
+    outcome: 'passed',
+    opened_at: row.opened_at,
+    closed_at: row.closed_at,
+  });
+}
+
 // ── the summons: what is waiting on THIS member's vote (task 1003271) ───────
 //
 // THE PROBLEM THIS EXISTS TO FIX. Nine items sat open for two days with zero
@@ -1123,6 +1157,7 @@ module.exports = {
   closeItem,
   maybeCloseAfterVote,
   latestRejectionForIdea,
+  boardPassForIdea,
   validateProposedConstitution,
   proposeAmendment,
   boardRoomView,

package/modules/government/db.js

@@ -509,7 +509,14 @@ async function getIdeaSubjects(ideaIds) {
   // in the hall rather than on a reaction. LEFT JOIN: an idea whose grade row
   // is somehow gone still shows its title.
   const { rows } = await pool.query(
-    `SELECT i.id, i.title, i.captured_by, g.field_values, g.template_key, g.completeness_score
+    // `g.recommendation` (task 1004092 / BV2.R13, spec R22): what the author
+    // thinks their idea turned out to be — a goal, or a criterion inside one.
+    // It rides with the sections for exactly the same reason they do: the board
+    // is being asked to decide that question, and deciding it without seeing
+    // what was proposed is the gap this closes. NULL for every Full Idea filed
+    // before the question existed, which the room renders honestly.
+    `SELECT i.id, i.title, i.captured_by, g.field_values, g.template_key, g.completeness_score,
+            g.recommendation
        FROM idea_inbox i
        LEFT JOIN ideas_grades g ON g.idea_id = i.id
       WHERE i.id = ANY($1::bigint[])`,
@@ -603,6 +610,38 @@ async function getLatestReturnedItemWithObjection(subjectType, subjectId) {
   return rows[0] || null;
 }
 
+// BV2.R17's read (task 1004096): the most recent PASSED item for a subject.
+//
+// The mirror of getLatestReturnedItemWithObjection above, and the reason it
+// exists separately rather than as a `outcome` parameter on that one: the
+// returned read exists to carry an OBJECTION back to an author and joins the
+// votes table to find it, while this one exists to answer a single yes/no —
+// "did the board carry this?" — and must not depend on any vote row existing.
+// A passed item commonly has NO votes at all (a zero-vote sitting passes under
+// the absence rules, ADR 0175 §3), so the LEFT JOIN that is merely defensive
+// there would be load-bearing here, which is a good sign the two are different
+// questions.
+//
+// Ordering is closed_at DESC, id DESC: an idea returned once and resubmitted can
+// have several closed items, and it is the latest decision that stands.
+//
+// Served by the partial index `government_board_items_passed_by_subject`
+// (government_018), the mirror of government_006's index for the returned read.
+// It needs its own: the table only grows, government_003's two indexes both key
+// on OPEN items and government_008's keys on closed_at alone for the whole-board
+// history feed, so none of them helps a lookup filtered by subject.
+async function getLatestPassedItem(subjectType, subjectId) {
+  const { rows } = await pool.query(
+    `SELECT id AS item_id, closed_at, opened_at, constitution AS decided_under
+       FROM government_board_items
+      WHERE subject_type = $1 AND subject_id = $2 AND outcome = 'passed'
+      ORDER BY closed_at DESC, id DESC
+      LIMIT 1`,
+    [subjectType, subjectId],
+  );
+  return rows[0] || null;
+}
+
 // The expiry sweep's read (R11): every OPEN item whose deadline has passed, on
 // the database clock, oldest deadline first. Served by the partial index
 // government_board_items_open_by_deadline (government_003 built it for exactly
@@ -721,6 +760,7 @@ module.exports = {
   getIdeaCompleteness,
   getExpiredOpenBoardItems,
   getLatestReturnedItemWithObjection,
+  getLatestPassedItem,
   createAmendment,
   getAmendment,
   listOpenBoardItems,

package/modules/government/migrations/government_018_passed_items_index.sql

@@ -0,0 +1,31 @@
+-- government_018_passed_items_index.sql — index the passed-item lookup
+-- (task 1004096 / BV2.R17; a grader efficiency finding, and right — exactly as
+-- government_006 was for the sibling read one outcome over).
+--
+-- `getLatestPassedItem` answers "did the board CARRY this subject?" and runs on
+-- every Full-Idea→goal ratification. It is the mirror of
+-- `getLatestReturnedItemWithObjection`, and it inherits that read's problem in
+-- full: `government_board_items` only grows — one row per window, and a
+-- returned idea can be resubmitted without bound — while the table's two
+-- OPEN-item indexes (`government_003`) both key on `closed_at IS NULL` and the
+-- one closed-item index (`government_008`) keys on `closed_at` alone, for the
+-- whole-board history feed. None of them helps a lookup that filters by
+-- subject. Without this, a ratification scans historical volume that scales
+-- with every sitting the project has ever held.
+--
+-- Partial on outcome='passed' — the only outcome this read asks for — and keyed
+-- (subject_type, subject_id, closed_at DESC) to match the query's WHERE and
+-- ORDER BY exactly, the government_006 shape. Two narrow partial indexes rather
+-- than one wider index over `outcome`: each read asks for exactly one outcome
+-- and never ranges across them, so a shared index would be larger and no more
+-- useful to either.
+--
+-- Additive, idempotent, no rows touched — safe on any database state.
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS government_board_items_passed_by_subject
+  ON government_board_items (subject_type, subject_id, closed_at DESC)
+  WHERE outcome = 'passed';
+
+COMMIT;

package/modules/government/routes/government.js

@@ -103,6 +103,13 @@ const governmentPort = {
   // resubmit path in modules/ideas resolves this to show what was objected to
   // and to check whether the flagged section actually changed.
   latestRejectionForIdea: board.latestRejectionForIdea,
+  // BV2.R17 (task 1004096): the record of the board having CARRIED an idea, or
+  // null. The ideas module's ratification path resolves this to check the one
+  // fact that makes turning a Full Idea into a goal a board decision rather
+  // than a ratifier's preference. Read-only, like every other entry here — there
+  // is no counterpart that records an outcome, and there must never be one: an
+  // outcome is written by a close, never by the module reading it.
+  boardPassForIdea: board.boardPassForIdea,
 };
 
 function registerSeams() {

package/modules/hall-ui/public/board-room.css

@@ -40,6 +40,12 @@
 .gov-item__title .fact-pill { vertical-align: middle; margin-left: 10px; text-shadow: none; }
 .gov-item__state { display: inline-flex; align-items: center; gap: 10px; font-size: 12.5px; color: var(--ink-faint); font-variant-numeric: tabular-nums; }
 .gov-item__amend { margin: 0 0 12px; font-size: 13.5px; line-height: 1.5; color: var(--ink-soft); max-width: var(--measure); overflow-wrap: anywhere; }
+/* The author's scope recommendation (BV2.R13). Sits between the ballot and the
+   idea's own words, at the weight of a stated fact rather than a badge — it is
+   what the board is deciding, not something already decided. */
+.gov-item__rec { margin: 12px 0 0; font-size: 13.5px; line-height: 1.5; color: var(--ink-soft); max-width: var(--measure); }
+.gov-item__rec strong { font-weight: 500; color: var(--ink); }
+.gov-item__rec--none { color: var(--ink-faint); }
 .gov-item__act { margin: 8px 0 4px; }
 .gov-item__cast { margin: 0; font-size: 13.5px; color: var(--ink-soft); }
 .gov-item__meta { margin: var(--sp-sm) 0 0; border-top: var(--line) solid var(--rule-soft); }

package/modules/hall-ui/public/board-room.js

@@ -265,6 +265,36 @@
       : emptyStateHtml('This idea has no written sections.');
   }
 
+  // The author's scope recommendation, in front of the voter WITH the sections
+  // (task 1004092 / BV2.R13, spec R22).
+  //
+  // THE WORDING CARRIES THE WHOLE POINT, so it is not shortened to a pill. The
+  // ideator recommends and the board decides (spec decision 9) — a bare badge
+  // reading "goal" next to a ballot reads as a fact already settled, which is
+  // the one thing this value is not. The line says who said it and who decides.
+  //
+  // AN ABSENT RECOMMENDATION IS STATED, NOT HIDDEN. Every Full Idea filed before
+  // this question existed carries NULL, and so does a terse CLI filing; there is
+  // no backfill and no default, because inventing a scope opinion is putting
+  // words in an author's mouth. Rendering nothing would leave a voter unable to
+  // tell "recommended as a criterion" from "never asked".
+  const RECOMMENDATION_WORDS = {
+    goal: 'a goal of its own',
+    criterion: 'a criterion inside an existing goal',
+  };
+
+  function recommendationHtml(item) {
+    if (item.subject_type !== 'full_idea' || !item.subject) return '';
+    const rec = item.subject.recommendation;
+    // An unknown value can only mean the vocabulary widened after this page
+    // shipped. Print it rather than dropping it — the same honesty rule the
+    // unlabelled-section tail follows.
+    const words = rec ? (RECOMMENDATION_WORDS[rec] || rec) : null;
+    return words
+      ? `<p class="gov-item__rec">Its author recommends this becomes <strong>${escapeHtml(words)}</strong>. The board decides.</p>`
+      : '<p class="gov-item__rec gov-item__rec--none">Its author gave no scope recommendation.</p>';
+  }
+
   // ---- the sitting's rules, in plain words (task 1003270) --------------------
 
   // The card used to carry `tally: 0 yes · 0 no — sitting under <first_ratifier>,
@@ -412,6 +442,7 @@
       </div>
       ${amendmentDetail}
       ${action ? `<div class="gov-item__act">${action}</div>` : ''}
+      ${isOpen ? recommendationHtml(item) : ''}
       ${isOpen ? ideaSectionsHtml(item) : ''}
       <details class="gov-item__meta">
         <summary class="gov-item__summary">${tally} · who votes, and how it ${isOpen ? 'passes' : 'passed'}</summary>

package/modules/hall-ui/public/ideas.css

@@ -71,6 +71,33 @@
 
 .fi-note { font-size: 13.5px; color: var(--ink-faint); }
 
+/* ---- the scope recommendation (BV2.R13) ----------------------------------
+   A pick, so it is radios — the settings family's `.prow--pick` grammar, not a
+   toggle: a toggle says on/off and this says which of two. The fieldset draws
+   no box (a bordered group inside a composer panel is the card-in-a-card the
+   world removed) and the legend takes the label voice the five questions wear,
+   so the sixth question does not read as a different kind of thing.
+
+   The 24px floor is on the LABEL, not the 13px input: the whole option row is
+   the target, so the box stays the size it is drawn while the thing a finger
+   lands on is the sentence beside it. */
+.fi-rec__set { margin: 0; padding: 0; border: 0; max-width: var(--measure); }
+.fi-rec__set > .fi-label { margin-bottom: 0; padding: 0; }
+.fi-rec__hint { margin-bottom: 6px; }
+.fi-rec__opt {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 24px;
+  padding: 3px 0;
+  font-size: 14px;
+  line-height: 1.4;
+  color: var(--ink);
+  cursor: pointer;
+}
+.fi-rec__opt input { flex: none; margin: 0; }
+.fi-rec__opt input:focus-visible { outline: 2px solid var(--focus); outline-offset: 3px; }
+
 /* GRAVITY (task 1004083 / spec R02) — the consequence of the picker above it,
    so it sits tight under the select rather than at the form's own rhythm, and
    reads a step louder than .fi-hint: a hint describes a control, this states

package/modules/hall-ui/public/ideas.html

@@ -158,6 +158,13 @@
               <p class="fi-note">Loading the five questions…</p>
             </div>
 
+            <!-- The scope recommendation (BV2.R13). Rendered from the same
+                 GET /inbox/template read as the fields above, and for the same
+                 reason: the two values are a closed vocabulary the database
+                 enforces, so a hand-written pair of radios here would be a
+                 second copy of it, free to drift. -->
+            <div id="fi-rec" class="fi-rec"></div>
+
             <p class="fi-err" id="fi-err" role="alert"></p>
 
             <div class="fi-actions">

package/modules/hall-ui/public/ideas.js

@@ -119,6 +119,10 @@
         template_key: template.key,
         title: titleEl().value,
         field_values: collect(),
+        // BV2.R13: a half-written thought includes the scope its author has in
+        // mind for it; losing that on navigation is the same loss as losing a
+        // paragraph.
+        recommendation: collectRecommendation(),
         at: new Date().toISOString(),
       }));
       note('Draft saved in this browser.');
@@ -258,6 +262,8 @@
     }
     titleEl().addEventListener('input', onEdit);
 
+    renderRecommendation(draft);
+
     $('#fi-meter').hidden = false;
     renderMeterSkeleton();
   }
@@ -268,6 +274,83 @@
     return out;
   }
 
+  // ---------------------------------------------------------------------------
+  // the scope recommendation (task 1004092 / BV2.R13, spec R22)
+  // ---------------------------------------------------------------------------
+  //
+  // NOT A SIXTH TEXTAREA, and deliberately not collected into `field_values`:
+  // the five answers are prose the scorer measures, and this is a two-value
+  // choice nothing scores. It travels as its own body field, so the meter
+  // above never moves when it is picked.
+  //
+  // THE OPTIONS COME FROM THE SERVER, like the fields. The vocabulary is a
+  // database CHECK constraint; hard-coding the pair here would be the "second
+  // copy of the rules" defect this whole file is organised against, and would
+  // silently omit any value a later migration admits.
+  //
+  // REQUIRED HERE, OPTIONAL AT THE API — which is not a contradiction. The
+  // hall is where the question is actually put to a person, so filing from it
+  // without answering would be filing an unanswered question. The route stays
+  // permissive because hundreds of already-filed Full Ideas carry no
+  // recommendation and a terse CLI filing may carry none either; every reader
+  // therefore has to render the absence honestly regardless, and a required
+  // body field would 400 every already-shipped client.
+
+  function recSpec() {
+    return (template && template.recommendation) || null;
+  }
+
+  function renderRecommendation(draft) {
+    const host = $('#fi-rec');
+    if (!host) return;
+    const spec = recSpec();
+    // An instance whose template read predates this question simply has no
+    // control — the composer keeps working and files without one.
+    if (!spec || !Array.isArray(spec.options) || !spec.options.length) {
+      host.innerHTML = '';
+      return;
+    }
+    const picked = draft && typeof draft.recommendation === 'string' ? draft.recommendation : '';
+    host.innerHTML = `
+      <fieldset class="fi-rec__set">
+        <legend class="fi-label">${escapeHtml(spec.label || 'What do you think this is')}</legend>
+        ${spec.hint ? `<p class="fi-hint fi-rec__hint">${escapeHtml(spec.hint)}</p>` : ''}
+        ${spec.options.map((o) => `
+          <label class="fi-rec__opt">
+            <input type="radio" name="fi-rec-choice" value="${escapeHtml(o.value)}"${o.value === picked ? ' checked' : ''}>
+            <span>${escapeHtml(o.label || o.value)}</span>
+          </label>`).join('')}
+      </fieldset>`;
+    // onEdit, not a bespoke handler: picking an option has to save the draft
+    // and re-evaluate the file button exactly as typing does. It cannot change
+    // the score, and scoreNow is a no-op for it beyond one wasted call — which
+    // the debounce already collapses.
+    for (const el of host.querySelectorAll('input[name="fi-rec-choice"]')) {
+      el.addEventListener('change', onEdit);
+    }
+  }
+
+  function collectRecommendation() {
+    const host = $('#fi-rec');
+    const picked = host && host.querySelector('input[name="fi-rec-choice"]:checked');
+    return picked ? picked.value : '';
+  }
+
+  function clearRecommendation() {
+    const host = $('#fi-rec');
+    if (!host) return;
+    for (const el of host.querySelectorAll('input[name="fi-rec-choice"]')) el.checked = false;
+  }
+
+  // Whether the composer may file. Only true when the server actually offered
+  // the choice — an instance that serves no `recommendation` spec must not have
+  // its file button held hostage by a control that was never rendered.
+  function recommendationMissing() {
+    const spec = recSpec();
+    if (!spec || !Array.isArray(spec.options) || !spec.options.length) return false;
+    return !collectRecommendation();
+  }
+
   // ---------------------------------------------------------------------------
   // the meter — every number in it came from the server
   // ---------------------------------------------------------------------------
@@ -316,7 +399,13 @@
     // does NOT enforce the substance floor, because a thin answer is a scoring
     // problem, not a capture error). Matching that exactly means the button never
     // promises an outcome the server will refuse, and never blocks one it accepts.
-    const missingRequired = template.fields.some((f) => f.required && !fieldEl(f.key).value.trim());
+    //
+    // THE SCOPE RECOMMENDATION IS THE ONE PLACE THIS BUTTON IS STRICTER THAN
+    // THE ROUTE (BV2.R13). The route accepts a Full Idea without one, because
+    // the historical rows have none; the hall does not, because the hall is
+    // where the question was actually asked. See renderRecommendation.
+    const missingRequired = template.fields.some((f) => f.required && !fieldEl(f.key).value.trim())
+      || recommendationMissing();
     // In develop mode the title is the existing idea's and is not editable, so it
     // cannot be a reason to keep the button off.
     $('#fi-submit').disabled = filing || missingRequired || (!DEVELOP_ID && !titleEl().value.trim());
@@ -342,7 +431,8 @@
     if (lastScore) renderScore(lastScore);
     else $('#fi-submit').disabled = filing
       || (!DEVELOP_ID && !titleEl().value.trim())
-      || template.fields.some((f) => f.required && !fieldEl(f.key).value.trim());
+      || template.fields.some((f) => f.required && !fieldEl(f.key).value.trim())
+      || recommendationMissing();
   }
 
   // ---------------------------------------------------------------------------
@@ -386,10 +476,13 @@
     // The one behavioural fork between the two modes. Developing is an act on an
     // EXISTING idea, so it carries no title and no grade: the row already has
     // both, and R146 preserves them along with its author.
+    // BV2.R13: the recommendation travels on BOTH paths, and only when one was
+    // actually picked — sending '' would be asserting an opinion nobody gave.
+    const rec = collectRecommendation();
     const r = DEVELOP_ID
       ? await api.inbox.postInboxIdDevelop({
         id: DEVELOP_ID,
-        body: { field_values: collect(), template_key: template.key },
+        body: { field_values: collect(), template_key: template.key, ...(rec ? { recommendation: rec } : {}) },
       })
       : await api.inbox.postInbox({
         body: {
@@ -397,6 +490,7 @@
           grade: 'full',
           template_key: template.key,
           field_values: collect(),
+          ...(rec ? { recommendation: rec } : {}),
         },
       });
 
@@ -429,6 +523,7 @@
 
     if (!DEVELOP_ID) titleEl().value = '';
     for (const f of template.fields) fieldEl(f.key).value = '';
+    clearRecommendation();
     lastScore = null;
     renderScore(null);
     note('');
@@ -445,6 +540,7 @@
     clearDraft();
     titleEl().value = '';
     for (const f of template.fields) fieldEl(f.key).value = '';
+    clearRecommendation();
     lastScore = null;
     renderScore(null);
     showErr('');

package/modules/ideas/grades.js

@@ -18,6 +18,7 @@ const { pool } = api;
 const {
   IDEA_COLS_Q, GRADE_COLS_Q,
   VALID_GRADES, DEFAULT_TEMPLATE_KEY, TEMPLATE_KEY_RE, TEMPLATE_KEY_MAX, FIELD_VALUES_MAX,
+  VALID_RECOMMENDATIONS, isValidRecommendation,
 } = require('./projection');
 const { skillFrictionHiddenClause } = require('./skill-friction');
 // developSpark reads the whole idea back to build the idea.graded.full payload.
@@ -121,7 +122,7 @@ async function countSparkQueue({ viewerRank = null } = {}, deps = {}) {
 // Structured throws (not raw constraint violations) so the routes that land on
 // top of this — R143's Full Idea capture, R144's mark-as-spark — return a clean
 // 400/404 rather than a 500 with a Postgres message in it.
-function assertGradePayload({ grade, templateKey, fieldValues, completenessScore }) {
+function assertGradePayload({ grade, templateKey, fieldValues, completenessScore, recommendation = null }) {
   if (!VALID_GRADES.includes(grade)) {
     throw { code: 'BAD_GRADE', grade, valid: VALID_GRADES };
   }
@@ -141,27 +142,45 @@ function assertGradePayload({ grade, templateKey, fieldValues, completenessScore
       throw { code: 'BAD_COMPLETENESS', completeness_score: completenessScore };
     }
   }
+  // task 1004092 / BV2.R13. NULL is legal and permanent ("the author did not
+  // say"); anything outside the closed vocabulary is a structured throw here so
+  // the route returns a named 400 rather than letting
+  // ideas_grades_recommendation_chk surface as a 500.
+  if (!isValidRecommendation(recommendation)) {
+    throw { code: 'BAD_RECOMMENDATION', recommendation, valid: VALID_RECOMMENDATIONS };
+  }
 }
 
+// THE RECOMMENDATION IS INSIDE THE WHOLE-ROW CONTRACT, NOT BESIDE IT (task
+// 1004092 / BV2.R13). It defaults to null, so a caller that omits it CLEARS it
+// — deliberately the same rule as field_values, and for the same reason: it is
+// current content the author states, not a historical fact about who acted
+// (which is why developed_by/developed_at sit outside the contract instead).
+// The consequence the callers must honour: POST /inbox/:id/resubmit re-states
+// the whole Full Idea, so it passes the STORED recommendation forward unless
+// the body names a new one — otherwise answering a board objection would
+// silently withdraw the scope the board was shown.
 async function setIdeaGrade(ideaId, {
   grade,
   templateKey = DEFAULT_TEMPLATE_KEY,
   fieldValues = {},
   completenessScore = null,
+  recommendation = null,
 } = {}) {
-  assertGradePayload({ grade, templateKey, fieldValues, completenessScore });
+  assertGradePayload({ grade, templateKey, fieldValues, completenessScore, recommendation });
   try {
     const { rows } = await pool.query(
-      `INSERT INTO ideas_grades (idea_id, grade, template_key, field_values, completeness_score)
-       VALUES ($1, $2, $3, $4::jsonb, $5)
+      `INSERT INTO ideas_grades (idea_id, grade, template_key, field_values, completeness_score, recommendation)
+       VALUES ($1, $2, $3, $4::jsonb, $5, $6)
        ON CONFLICT (idea_id) DO UPDATE
           SET grade              = EXCLUDED.grade,
               template_key       = EXCLUDED.template_key,
               field_values       = EXCLUDED.field_values,
-              completeness_score = EXCLUDED.completeness_score
+              completeness_score = EXCLUDED.completeness_score,
+              recommendation     = EXCLUDED.recommendation
        RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                 created_at, updated_at`,
-      [ideaId, grade, templateKey, JSON.stringify(fieldValues), completenessScore]
+                 recommendation, created_at, updated_at`,
+      [ideaId, grade, templateKey, JSON.stringify(fieldValues), completenessScore, recommendation]
     );
     return rows[0];
   } catch (err) {
@@ -185,7 +204,7 @@ async function setIdeaCompleteness(ideaId, completenessScore) {
         SET completeness_score = $2
       WHERE idea_id = $1
       RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                created_at, updated_at`,
+                recommendation, created_at, updated_at`,
     [ideaId, completenessScore]
   );
   return rows[0] ?? null;
@@ -237,11 +256,11 @@ async function setIdeaCompleteness(ideaId, completenessScore) {
 // work, not current content, and setIdeaGrade's ON CONFLICT SET list omits both
 // columns — so a later re-score or an author's R13 resubmission preserves the
 // developer's attribution instead of silently erasing it.
-async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLATE_KEY, fieldValues = {}, completenessScore = null } = {}) {
+async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLATE_KEY, fieldValues = {}, completenessScore = null, recommendation = null } = {}) {
   // Reuse the R140 payload validator so a bad template key or an oversize
   // field_values map is a structured throw here rather than a constraint
   // violation surfacing as a 500 (the assertGradePayload contract).
-  assertGradePayload({ grade: 'full', templateKey, fieldValues, completenessScore });
+  assertGradePayload({ grade: 'full', templateKey, fieldValues, completenessScore, recommendation });
   if (developedBy == null) throw { code: 'MISSING_DEVELOPER' };
   const { rows } = await pool.query(
     `UPDATE ideas_grades
@@ -250,15 +269,21 @@ async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLAT
             field_values       = $3::jsonb,
             completeness_score = $4,
             developed_by       = $5,
-            developed_at       = now()
+            developed_at       = now(),
+            -- task 1004092 / BV2.R13: developing a spark IS filing the Full
+            -- Idea, so the developer states its scope recommendation here. A
+            -- spark has none to inherit (the question belongs to the full
+            -- grade), so an omitted value writing NULL is the honest outcome,
+            -- not a loss.
+            recommendation     = $6
       WHERE idea_id = $1
         AND grade = 'spark'
         AND EXISTS (
           SELECT 1 FROM idea_inbox i WHERE i.id = $1 AND i.status = 'open'
         )
       RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                developed_by, developed_at, created_at, updated_at`,
-    [ideaId, templateKey, JSON.stringify(fieldValues), completenessScore, developedBy]
+                developed_by, developed_at, recommendation, created_at, updated_at`,
+    [ideaId, templateKey, JSON.stringify(fieldValues), completenessScore, developedBy, recommendation]
   );
   // null = "this row was not a developable spark when we looked". THREE ways to
   // get here, and the caller re-reads to say which: it was never a spark,
@@ -288,6 +313,10 @@ async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLAT
         grade: 'full',
         completeness_score: graded.completeness_score,
         developed_by: graded.developed_by,
+        // Stated from the write's own RETURNING rather than left to the re-read
+        // above, for the same reason completeness_score is: the listener acts on
+        // what this transition actually wrote.
+        recommendation: graded.recommendation ?? null,
       });
     } catch { /* a listener, or the read that feeds it, must never cost the ideator their grade */ }
   }
@@ -299,7 +328,7 @@ async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLAT
 async function getIdeaGrade(ideaId) {
   const { rows } = await pool.query(
     `SELECT idea_id, grade, template_key, field_values, completeness_score,
-            created_at, updated_at
+            recommendation, created_at, updated_at
        FROM ideas_grades
       WHERE idea_id = $1`,
     [ideaId]

package/modules/ideas/inbox.js

@@ -31,6 +31,7 @@ const ideasConfig = require('./config');
 const {
   IDEA_COLS, IDEA_COLS_Q, GRADE_COLS_Q, IDEA_JOIN_GRADE, ungradedProjection,
   DEFAULT_GRADE, VALID_GRADES, DEFAULT_TEMPLATE_KEY, TEMPLATE_KEY_MAX, FIELD_VALUES_MAX,
+  VALID_RECOMMENDATIONS, isValidRecommendation, normalizeRecommendation,
 } = require('./projection');
 // The carved domains. Each is re-exported at the bottom of this file, so every
 // existing caller of `require('./inbox')` keeps working unchanged — the same
@@ -796,6 +797,12 @@ module.exports = {
   DEFAULT_TEMPLATE_KEY,
   TEMPLATE_KEY_MAX,
   FIELD_VALUES_MAX,
+  // the recommendation vocabulary (task 1004092 / BV2.R13) — goal | criterion,
+  // re-exported so the routes and the composer's template read declare it from
+  // the same place the SQL CHECK mirrors
+  VALID_RECOMMENDATIONS,
+  isValidRecommendation,
+  normalizeRecommendation,
   // skill-friction marker + rank visibility gate (V3.R70 / #289; the kind
   // itself landed in task 1003105 — both markers are live, see above)
   SKILL_FRICTION_TAG,
@@ -841,4 +848,15 @@ module.exports = {
   parseProposalBody: ratify.parseProposalBody,
   KARMA_RATIFY_DELTA: ratify.KARMA_RATIFY_DELTA,
   KARMA_RATIFY_REASON: ratify.KARMA_RATIFY_REASON,
+  // Full-Idea → GOAL ratification, the goal half beside it (task 1004096 /
+  // BV2.R17); see ratify.js on why the two halves are not symmetrical.
+  //
+  // ONLY THE TRANSACTION IS RE-EXPORTED. `composeGoalFromFullIdea` and
+  // `GOAL_SHAPE_BY_TEMPLATE` are deliberately NOT on the facade: nothing outside
+  // ratify.js calls either, and a re-export no caller needs is an unused export
+  // the dead-code ratchet counts. The facade's job is to keep the ~20 callers of
+  // the pre-carve surface working, not to publish everything a new file declares
+  // — anything that wants the pure composer requires ./ratify directly, as the
+  // test does.
+  ratifyFullIdeaAsGoal: ratify.ratifyFullIdeaAsGoal,
 };