@bongos/core 1.19.419 → 1.19.421

package/modules/platform-identity/account-visibility.js

@@ -14,10 +14,37 @@
 // already at the file-size ratchet. So the definition lands here, alone and
 // tiny, and 1002967 ADOPTS it rather than writing a second one.
 //
-// WHAT IT IS NOT. Not a rollup gate: hide_stats suppresses NUMBERS, not
-// existence, and is applied by the rollup readers (ADR 0171 D2), never here.
+// THREE AXES, THREE ANSWERS, ONE HOME (task 1002967 adopting this file). The
+// axes stay independent — conflating them is the trap the privacy spec D1/D2
+// exists to prevent — but every EFFECTIVE answer derived from them lives here,
+// because an answer that lives anywhere else is a second variant waiting to
+// drift:
+//
+//   accountVisibleSql / isAccountVisible   EXISTENCE  — may the world see that
+//       this account exists? Every PUBLIC read floors on this.
+//   accountActiveSql / isAccountActive     CONSENT    — active, without the
+//       existence axis. The OWN-SCOPE floor (ADR 0202 D4 §2): a private account
+//       is still a real participant in its own scope.
+//   rollupVisibleSql / isRollupVisible     NUMBERS    — visible AND NOT
+//       hide_stats. ADR 0171 D2's predicate EXTENDED with the existence axis,
+//       and COMPOSED from accountVisibleSql rather than restated.
+//   isRecruiterDiscoverable                REACH      — the COALESCE, privacy
+//       spec D1. A reach predicate only: it never buys addressability.
+//
+// The rollup pair was originally left to "the rollup readers" to apply. Task
+// 1002967 moved it here for the reason this file exists: there are two such
+// readers (listScoutingRollup and getPublicProfileExtras), so leaving them to
+// spell `AND NOT hide_stats` themselves is exactly the second-variant problem,
+// one level down. hide_stats still suppresses NUMBERS and never existence —
+// that is why it appears in rollupVisibleSql and in nothing above it.
+//
 // Not authority: an account being visible confers nothing (ADR 0016).
 //
+// tests/effective_visibility_predicate.mjs enforces that this file is the ONLY
+// first-party server file allowed to compare these columns to a literal, and
+// that every SELECT on platform_identity_accounts either joins one of these
+// predicates or is declared non-public with a reason.
+//
 // Fail-closed: a missing/absent account row is invisible, never visible
 // (ADR 0192 §6 / ADR 0194 §2).
 'use strict';
@@ -55,4 +82,68 @@ function accountActiveSql(alias) {
   return `(${alias ? `${alias}.` : ''}profile_state = 'active')`;
 }
 
-module.exports = { isAccountVisible, accountVisibleSql, accountActiveSql };
+// The JS twin of accountActiveSql, for an own-scope reader that already holds
+// the row (routes/connections.js). Fail-closed, same as isAccountVisible.
+function isAccountActive(account) {
+  return !!account && account.profile_state === 'active';
+}
+
+// -------------------------------------------------------------------------
+// The rollup axis: visible AND not hidden (task 1002967 — ADR 0171 D2 extended)
+// -------------------------------------------------------------------------
+
+// The predicate the two ROLLUP readers join — listScoutingRollup (/people,
+// /scouting) and getPublicProfileExtras (the platform-identity.hub port behind
+// core GET /builders/:id/profile). COMPOSED from accountVisibleSql, never
+// restated, so changing what "visible" means moves this with it.
+function rollupVisibleSql(alias) {
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('rollupVisibleSql: alias must be a bare SQL identifier');
+  }
+  return `(${accountVisibleSql(alias)} AND NOT ${alias ? `${alias}.` : ''}hide_stats)`;
+}
+
+// The JS twin of rollupVisibleSql, for a reader that already holds the row.
+function isRollupVisible(account) {
+  return isAccountVisible(account) && !account.hide_stats;
+}
+
+// -------------------------------------------------------------------------
+// The reach axis: recruiting discoverability (privacy spec D1)
+// -------------------------------------------------------------------------
+
+// The two stored values of account_visibility. Mirrors the CHECK in
+// migrations/platform_identity_012_account_privacy.sql.
+const ACCOUNT_VISIBILITY = ['public', 'private'];
+
+// isRecruiterDiscoverable(account) — THE effective-recruiter-reach predicate.
+// The JS twin of COALESCE(recruiter_discoverable, account_visibility='public');
+// nothing else may spell that COALESCE out. Moved here from platform-identity.js
+// by task 1002967 so all three effective answers share one home.
+//
+// The tri-state is the point: NULL = follow visibility (opt-OUT for a public
+// account, opt-IN for a private one), an explicit boolean overrides — an
+// explicit true on a PRIVATE account is exactly the privacy spec's D2
+// "private, discoverable" row, which the D3 recruiter sliver exists to serve.
+//
+// NOT a complete gate, and NEVER addressability: profile_state='active' still
+// floors every recruiter surface, hide_stats still empties the sliver to
+// name-only, and a discoverable private account is still absent from every
+// public read. Fail-closed on a missing account.
+function isRecruiterDiscoverable(account) {
+  if (!account) return false;
+  const explicit = account.recruiter_discoverable;
+  if (typeof explicit === 'boolean') return explicit;
+  return account.account_visibility === 'public';
+}
+
+module.exports = {
+  isAccountVisible,
+  accountVisibleSql,
+  accountActiveSql,
+  isAccountActive,
+  rollupVisibleSql,
+  isRollupVisible,
+  ACCOUNT_VISIBILITY,
+  isRecruiterDiscoverable,
+};

package/modules/platform-identity/platform-identity.js

@@ -14,8 +14,13 @@
 
 const crypto = require('node:crypto');
 const api = require('../../src/module-api');
+// THE effective-visibility predicate (task 1002967, adopting the file ADR 0202
+// D4 named). Every public read below joins it from here; nothing in this file
+// re-derives one (see account-visibility.js).
+const visibility = require('./account-visibility');
 
 const { pool: defaultPool } = api;
+const { ACCOUNT_VISIBILITY, accountVisibleSql, rollupVisibleSql, isRollupVisible } = visibility;
 
 // Default authorization-code lifetime — deliberately short (~60s). A code is a
 // bearer secret that travels through the browser; a tight TTL bounds the replay
@@ -201,7 +206,7 @@ async function getAccount(githubId, { pool = defaultPool } = {}) {
 // (task #1002109) calls this with a freshly generated secret; the plaintext is
 // hashed here and never stored. Upsert-on-client_id so re-provisioning rotates
 // the secret + redirect_uris without a duplicate row.
-async function registerClient({ clientId, secret, name, redirectUris, origin, ownerGithubId, type }, { pool = defaultPool } = {}) {
+async function registerClient({ clientId, secret, name, redirectUris, origin, ownerGithubId, type, description }, { pool = defaultPool } = {}) {
   const secretHash = sha256hex(secret);
   const uris = Array.isArray(redirectUris) ? redirectUris : [];
   const { rows } = await pool.query(
@@ -218,11 +223,11 @@ async function registerClient({ clientId, secret, name, redirectUris, origin, ow
      RETURNING id, client_id, name, redirect_uris, origin, owner_github_id, status`,
     [clientId, secretHash, name, uris, origin ?? null, ownerGithubId ?? null],
   );
-  // Auto-catalogue the project (unfeatured) so it appears in the Archon curation
-  // list the moment it federates (ADR 0141 §5). Best-effort — a catalog hiccup must
-  // never fail client registration. Only when an origin is known.
+  // Auto-catalogue the project (unfeatured) so it appears in the Archon curation list the
+  // moment it federates (ADR 0141 §5). Best-effort — a hiccup must never fail registration;
+  // only when an origin is known. `description` rides along like `type` (ADR 0182 D4, task 1002334).
   if (origin) {
-    try { await upsertProject({ origin, name, ownerGithubId, type }, { pool }); }
+    try { await upsertProject({ origin, name, description, ownerGithubId, type }, { pool }); }
     catch (err) { console.error('[platform-identity] auto-catalogue failed (non-fatal):', err.message); }
   }
   return rows[0];
@@ -717,11 +722,15 @@ async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped =
 // disciplines union is computed separately in `disc`. Proven against real SQL by
 // tests/scouting_rollup_fanout.mjs.
 //
-// Consent by construction (ADR 0171 D2/D3): only builders whose account is
-// profile_state='active' AND NOT hide_stats appear — /people and /scouting are
-// live cross-project surfaces, so the predicate lives IN the query, not in any
-// caller's memory. Provisional (no hub-session consent) and hidden builders drop
-// out entirely; the projection stays an explicit whitelist (no raw-row spread).
+// Consent by construction (ADR 0171 D2/D3, extended by task 1002967): only
+// builders whose account passes rollupVisibleSql — active, publicly visible, not
+// hidden — appear. /people and /scouting are live cross-project surfaces, so the
+// predicate lives IN the query, not in any caller's memory, and it is the SHARED
+// one so this list can never disagree with /profiles/:handle about who is
+// visible. Provisional, private and hidden builders drop out entirely; the
+// projection stays an explicit whitelist (no raw-row spread). A private account
+// that is recruiter-discoverable is absent here on purpose: the full rollup is
+// never its disclosure — the D3 sliver is (a separate authorization-scoped port).
 async function listScoutingRollup({ limit = 100, pool = defaultPool } = {}) {
   const { rows } = await pool.query(
     `WITH agg AS (
@@ -735,8 +744,7 @@ async function listScoutingRollup({ limit = 100, pool = defaultPool } = {}) {
         WHERE EXISTS (
                 SELECT 1 FROM platform_identity_accounts pa
                  WHERE pa.github_id = a.github_id
-                   AND pa.profile_state = 'active'
-                   AND NOT pa.hide_stats)
+                   AND ${rollupVisibleSql('pa')})
         GROUP BY a.github_id
      ), disc AS (
        SELECT x.github_id, array_agg(DISTINCT x.d) AS disciplines
@@ -840,20 +848,21 @@ async function getRollupForBuilder(githubId, { pool = defaultPool } = {}) {
   };
 }
 
-// The PUBLIC read behind the 'platform-identity.hub' port (ADR 0171 D1/D2):
-// null unless the account exists, consented (profile_state='active') and is not
-// hidden (hide_stats) — the fail-closed rule every public surface inherits by
-// construction. A null is deliberately indistinguishable between "no account",
-// "provisional" and "hidden" (no partial numbers; a count plus a hidden total is
-// a leak by subtraction).
+// The PUBLIC read behind the 'platform-identity.hub' port (ADR 0171 D1/D2,
+// extended by task 1002967): null unless the account passes the SHARED rollup
+// predicate — exists, consented (profile_state='active'), publicly visible
+// (account_visibility='public') and not hidden (hide_stats). The fail-closed
+// rule every public surface inherits by construction. A null is deliberately
+// indistinguishable between "no account", "provisional", "private" and "hidden"
+// (no partial numbers; a count plus a hidden total is a leak by subtraction).
 async function getPublicProfileExtras(githubId, { pool = defaultPool } = {}) {
   if (!isNumericGithubId(githubId)) return null;
   const { rows } = await pool.query(
-    `SELECT profile_state, hide_stats FROM platform_identity_accounts WHERE github_id = $1`,
+    `SELECT profile_state, account_visibility, hide_stats
+       FROM platform_identity_accounts WHERE github_id = $1`,
     [githubId],
   );
-  const acct = rows[0];
-  if (!acct || acct.profile_state !== 'active' || acct.hide_stats) return null;
+  if (!isRollupVisible(rows[0])) return null;
   return getRollupForBuilder(githubId, { pool });
 }
 
@@ -920,32 +929,10 @@ async function setAccountHideStats({ githubId, githubLogin, displayName, avatarU
 // Account privacy: visibility + recruiter reach (task 1002966 — privacy spec D1)
 // -------------------------------------------------------------------------
 
-// The two stored values of account_visibility (spec D1's EXISTENCE axis).
-// 'private' means the public profile read 404s to everyone — including the
-// owner, who reaches their own page through the own-scope side door instead.
-const ACCOUNT_VISIBILITY = ['public', 'private'];
-
-// isRecruiterDiscoverable(account) — THE effective-recruiter-reach predicate
-// (privacy spec D1). One definition, so every reader answers "may a recruiting
-// surface see this account at all?" the same way; task 1002967 adopts this
-// rather than re-deriving it, and nothing else should spell the COALESCE out.
-//
-// The JS twin of  COALESCE(recruiter_discoverable, account_visibility='public').
-// The tri-state is the point: NULL = follow visibility (opt-OUT for a public
-// account, opt-IN for a private one), an explicit boolean overrides — an
-// explicit true on a PRIVATE account is exactly the spec's D2 "private,
-// discoverable" row, which is what the recruiter sliver exists to serve.
-//
-// NOT a complete gate on its own. profile_state='active' still floors every
-// recruiter surface (a provisional account is never visible), and hide_stats
-// still empties the sliver down to name-only — both stay the caller's to apply.
-// Fail-closed on a missing/absent account.
-function isRecruiterDiscoverable(account) {
-  if (!account) return false;
-  const explicit = account.recruiter_discoverable;
-  if (typeof explicit === 'boolean') return explicit;
-  return account.account_visibility === 'public';
-}
+// ACCOUNT_VISIBILITY and isRecruiterDiscoverable moved to ./account-visibility.js
+// (task 1002967) — every effective-visibility answer now has ONE home, beside
+// the predicate the public reads join. They are re-exported below, so `pi.`
+// callers are unchanged.
 
 // The own-scoped privacy WRITE (task 1002966) — callers key this by the
 // AUTHENTICATED session's github_id, never a caller-named one. Validates here,
@@ -1123,10 +1110,18 @@ async function setAccountHandle({ githubId, handle }, { pool = defaultPool } = {
 // resolution). Case-insensitive. An exact current-handle match always wins;
 // otherwise the single-slot previous_handle matches and answers a move to the
 // current handle (the 301 window from P01). Only publicly addressable accounts
-// resolve (profile_state = 'active', ADR 0171 D3) — provisional and unknown are
-// the same null (the 404, indistinguishable by design). hide_stats deliberately
-// does NOT gate resolution: hiding removes the rollup, not the page (D2 —
-// addressability and hide are different invariants).
+// resolve — the SHARED accountVisibleSql predicate (task 1002967), so this is
+// the same "visible" every other public read uses. Provisional, PRIVATE and
+// unknown are all the same null: the 404 the privacy spec D2 requires, and it is
+// a 404 to EVERYONE INCLUDING THE OWNER, because this function takes no viewer
+// and therefore cannot vary by one (public responses stay viewer-independent,
+// ADR 0171 D4). An owner reaches their own private page through the own-scope
+// side door instead (GET /me/cross-project → getOwnProfileExtras) — the page
+// composition varies, the public response never does. A 403 is deliberately
+// never returned: it would confirm the handle exists.
+// hide_stats deliberately does NOT gate resolution: hiding removes the rollup,
+// not the page (D2 — addressability and hide are different invariants), which is
+// exactly why accountVisibleSql and rollupVisibleSql are two predicates.
 // Returns null | { moved_to } | { account: { github_id, github_login,
 // display_name, avatar_url, handle, created_at } }.
 async function resolveHandle(handle, { pool = defaultPool } = {}) {
@@ -1136,7 +1131,7 @@ async function resolveHandle(handle, { pool = defaultPool } = {}) {
     `SELECT github_id, github_login, display_name, avatar_url, handle, bio, links, created_at,
             (lower(handle) = $1) AS is_current
        FROM platform_identity_accounts
-      WHERE profile_state = 'active'
+      WHERE ${accountVisibleSql()}
         AND (lower(handle) = $1 OR lower(previous_handle) = $1)
       ORDER BY (lower(handle) = $1) DESC
       LIMIT 1`,
@@ -1467,9 +1462,9 @@ module.exports = {
   getPublicProfileExtras,
   getOwnProfileExtras,
   setAccountHideStats,
-  // account privacy: visibility + recruiter reach (privacy spec D1)
-  ACCOUNT_VISIBILITY,
-  isRecruiterDiscoverable,
+  // account privacy: the effective-visibility predicates (./account-visibility.js
+  // — one home for every effective answer; task 1002967 / ADR 0202 D4, 0207)
+  ...visibility,
   setAccountPrivacy,
   // builder handle (P01)
   RESERVED_HANDLES,

package/modules/platform-identity/routes/connections.js

@@ -40,7 +40,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const conn = require('../connections');
-const { isAccountVisible } = require('../account-visibility');
+const { isAccountVisible, isAccountActive } = require('../account-visibility');
 
 const { pool, requireBuilder, validateOrRespond, parsePagination } = api;
 const log = api.logger('platform-identity');
@@ -64,7 +64,7 @@ async function actingAccount(builder) {
     return { fail: ['no_platform_identity', { status: 400, message: 'this session has no platform account' }] };
   }
   const acct = await pi.getAccount(githubId, { pool });
-  if (!acct || acct.profile_state !== 'active') {
+  if (!isAccountActive(acct)) {
     return { fail: ['profile_provisional', { status: 403, message: 'sign in to the platform once to activate your profile before connecting' }] };
   }
   return { githubId };
@@ -78,7 +78,7 @@ async function visibleTarget(viewerGithubId, handle) {
   const acct = await conn.findAccountByHandle(handle, { pool });
   if (!acct) return null;
   if (isAccountVisible(acct)) return acct;
-  if (acct.profile_state !== 'active') return null;
+  if (!isAccountActive(acct)) return null;
   return (await conn.isConnectedTo(viewerGithubId, acct.github_id, { pool })) ? acct : null;
 }
 

package/modules/platform-identity/tests/platform-identity.mjs

@@ -406,6 +406,26 @@ await ta('registerClient auto-catalogues the project (2nd query) when an origin
   assert.match(pool.calls[1].text, /INSERT INTO platform_identity_projects/);
 });
 
+await ta('registerClient forwards the project-detail description into the catalog row (task 1002334)', async () => {
+  // Half the publish gate (ADR 0182 D4). It is given on the platform before this
+  // row exists, so if this hop drops it a project that DID describe itself sits
+  // in dark matter and the optional step is decorative.
+  const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
+  await P.registerClient(
+    { clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p', ownerGithubId: 7, description: 'A weather sim.' },
+    { pool },
+  );
+  assert.ok(pool.calls[1].params.includes('A weather sim.'), 'the description reaches the catalog upsert');
+});
+
+await ta('registerClient with a SKIPPED interview passes no description — and COALESCE nulls nothing', async () => {
+  const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
+  await P.registerClient({ clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p' }, { pool });
+  assert.equal(pool.calls[1].params[3], null, 'absent travels as null');
+  assert.match(pool.calls[1].text, /description     = COALESCE\(EXCLUDED\.description/,
+    'so a re-registration can never erase a description the owner added later');
+});
+
 console.log('\nproject memberships (§3 check-in directory):');
 
 await ta('recordFederatedSignin is the ONE path that creates a membership, and stamps the witness', async () => {

package/modules/provisioning/migrations/provisioning_013_project_detail.sql

@@ -0,0 +1,54 @@
+-- provisioning_013_project_detail.sql — the optional project-detail interview's
+-- storage (BV1.R15, task 1002334; goal 1000046 criterion `proj-detail-interview`).
+--
+-- The creation sequence gains ONE optional, skippable step — "tell us about your
+-- project" — and its answers have to live somewhere real the moment they are
+-- given. A standalone project never federates into the hub catalog at create
+-- time, so this mirrors exactly what provisioning_007 did for the declared
+-- `type`: the answer rides the provisioning request, and the control-plane
+-- runner carries it into platform_identity_projects whenever a catalog row
+-- materializes.
+--
+-- TWO columns, deliberately not one:
+--
+--   description  a REAL column, because it is half of the publish gate (ADR 0182
+--                D4: publishable iff name AND description are both present). It
+--                mirrors platform_identity_projects.description, which
+--                platform_identity_011 added for the same reason. NOT `tagline` —
+--                ADR 0182 refuses to collapse them, since a description is the
+--                publish bar and editing your card must never unpublish you.
+--
+--   detail       jsonb, because the interview grows one answer at a time as R17
+--                (rule-based recommendations), R19 (starter bundles) and R27
+--                (invites) land, and a new question must not cost a migration
+--                each time. Same contract as `settings` (provisioning_009): the
+--                column is a dumb store, the known keys + their vocabularies are
+--                enforced in code (provisioning.PROJECT_DETAIL_VOCAB +
+--                normalizeProjectDetail), and an unknown or off-vocabulary stored
+--                value is dropped at read time rather than leaking out.
+--
+-- SKIPPING IS THE DEFAULT, not a failure: both columns are nullable/empty, and an
+-- empty description is precisely what leaves a project dark-matter until its
+-- owner fills it in (ADR 0182 D4 — the bar exists to keep empty husks off the
+-- map, not to enforce completeness). Nothing here changes live behaviour; R16
+-- (task 1002335) is the surface that computes publishability and names what is
+-- missing.
+--
+-- Additive + provisioning_-namespaced (ADR 0083 §5): ADD COLUMN only, so the
+-- previous code release still runs against this schema. Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS description text;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS detail jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN provisioning_instances.description IS
+  'What the owner said they are building — the answer to the optional project-detail step (BV1.R15). Half of the publish gate (ADR 0182 D4: publishable iff name AND description are present), mirrored into platform_identity_projects.description when a catalog row materializes. NULL = the step was skipped, which is a supported default, not a failure: the project stays dark-matter until it is filled in.';
+
+COMMENT ON COLUMN provisioning_instances.detail IS
+  'The rest of the optional project-detail interview, as a dumb jsonb store (the `settings` contract from provisioning_009). Known keys + vocabularies live in provisioning.PROJECT_DETAIL_VOCAB and are enforced at the API layer; an unknown or off-vocabulary stored value is dropped at read time. jsonb so the interview can grow an answer at a time (R17 recommendations, R19 bundles, R27 invites) without a migration each time. {} = skipped.';
+
+COMMIT;

package/modules/provisioning/onboard-plan.js

@@ -9,6 +9,15 @@
 //
 // PURE — no I/O, no core imports. Safe to require from a script, a route, or a test.
 //
+// `optional: true` (task 1002334) marks a step every form must OFFER and every
+// owner may SKIP — today just `project-detail`, the "tell us about your project"
+// interview. It is a real step in the sequence rather than a wizard-only flourish
+// because all four forms have to ask it the same way; skipping is a supported
+// default that leaves the project dark-matter (off the map, un-joinable) until its
+// description is filled in later, never a dead end (ADR 0182 D4). A form that can
+// only render a linear checklist may treat an optional step as any other; one that
+// takes answers must let the owner past it without one.
+//
 // Each step: { key, kind: 'auto' | 'human', label }. `kind: 'human'` marks the
 // irreducibly-manual owner actions (create the GitHub repo, wire GitHub sign-in, first
 // sign-in, enter the hall) that every form renders UI-first; `kind: 'auto'` steps the
@@ -36,6 +45,10 @@ function onboardPlan(mode = 'greenfield', opts = {}) {
   const domain = typeof opts.domain === 'string' && opts.domain.trim() ? opts.domain.trim() : null;
   return [
     { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
+    // 'auto' like name-address above, and for the same reason: the form itself
+    // collects it, so it is not one of the irreducibly-manual legs a done panel
+    // lists. `optional` is what makes it skippable — see the header.
+    { key: 'project-detail', kind: 'auto', optional: true, label: 'Tell us about your project — optional, skip it and add it later' },
     { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
     { key: 'dns-preflight', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'DNS token preflight — before the address step (task 1980)' },
     { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },

package/modules/provisioning/provisioning.js

@@ -124,6 +124,34 @@ const SETTINGS_VOCAB = Object.freeze({
 });
 const DEFAULT_SETTINGS = Object.freeze({ platform_visibility: 'public', joinability: 'apply' });
 
+// The optional project-detail interview (BV1.R15, task 1002334) — the "tell us
+// about your project" step every creation form offers and every owner may skip.
+// The interview asks two things, and the vocabulary is the contract for the
+// closed-answer half:
+//
+//   team_shape   who is going to build it — the input R17 (task 1002336) maps to a
+//                recommended governance preset and to invite suggestions.
+//
+// (The module bundle R19 recommends comes off the separately-declared `type`, so
+// the interview deliberately does not ask it a second time.)
+//
+// The free-text half of the interview is NOT here: `description` is a real column
+// (migration provisioning_013) because it is half of the publish gate (ADR 0182
+// D4), while these are jsonb so a later question costs no migration — same dumb-
+// store contract as SETTINGS_VOCAB above.
+//
+// There is deliberately NO default. Settings describe a policy the instance must
+// obey, so an absent one has to resolve to today's behaviour; a detail answer is
+// something the owner SAID, and inventing one they never said would feed R17 a
+// recommendation nobody asked for. Absent stays absent, and skipped stays skipped.
+const PROJECT_DETAIL_VOCAB = Object.freeze({
+  team_shape: ['solo', 'small-team', 'community'],
+});
+// The publish-gate half of the interview is prose, so it needs a ceiling. Long
+// enough for a real paragraph, short enough that the column is never a document —
+// the Explore card renders `tagline`, not this.
+const DESCRIPTION_MAX = 600;
+
 // Monthly cost estimate (USD) for a dedicated droplet tier — VISIBILITY only
 // (ADR 0111 §6), never a bill. A small local table so this module needs no
 // sibling-module import; P2 (shared control-plane client extraction) is where a
@@ -257,6 +285,14 @@ function publicInstance(row) {
     // instances so a declaration shows before the catalog carries it. Nullable:
     // rows predating provisioning_007, or a declined answer, project null.
     type: row.type || null,
+    // The optional project-detail interview (task 1002334): what the owner said
+    // they are building, and the answers that feed R17's recommendations. Both
+    // are legitimately empty — the step is skippable by design — and `description`
+    // being null is exactly what keeps the project dark-matter until it is filled
+    // in (ADR 0182 D4). Surfaced so a form can render "here's what's still
+    // missing" from a plain instance read, without a second endpoint.
+    description: row.description || null,
+    detail: projectDetail(row),
     // The verification overlay (task 1002696, redesign direction §3): what the
     // heartbeat last OBSERVED, which is NOT what `status` claims. null = never
     // probed — a different claim from last_verified_up=false, and the UI renders
@@ -330,6 +366,40 @@ function effectiveSettings(row) {
   return out;
 }
 
+// A description as it may be STORED: trimmed, collapsed of runaway whitespace,
+// capped, and empty-means-absent. Returns null for anything that isn't real prose,
+// because null is what leaves the project dark-matter — an empty string stored in a
+// nullable column would look answered to `description IS NOT NULL` and publish an
+// husk, which is the one thing the gate exists to prevent (ADR 0182 D4). PURE.
+function normalizeDescription(input) {
+  if (typeof input !== 'string') return null;
+  const text = input.replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  return text.slice(0, DESCRIPTION_MAX);
+}
+
+// The detail answers as they may be STORED: on-vocabulary keys only, everything
+// else dropped. An off-vocabulary value is dropped rather than defaulted — a
+// recommendation built on an answer the owner never gave is worse than no
+// recommendation (see PROJECT_DETAIL_VOCAB). Always returns a plain object, so a
+// skipped interview stores `{}` rather than null. PURE.
+function normalizeProjectDetail(input) {
+  const given = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const out = {};
+  for (const [key, vocab] of Object.entries(PROJECT_DETAIL_VOCAB)) {
+    if (vocab.includes(given[key])) out[key] = given[key];
+  }
+  return out;
+}
+
+// What a row's detail answers READ as — the stored object filtered through the
+// same vocabulary, so a value that was valid when written and has since left the
+// vocabulary never leaks out of the read surface. Mirrors effectiveSettings, minus
+// the defaults it deliberately has none of. PURE.
+function projectDetail(row) {
+  return normalizeProjectDetail(row && row.detail);
+}
+
 // ---------------------------------------------------------------------------
 // GitHub App Manifest flow — PURE builders (task 2080, ADR 0133).
 // GitHub has no create-an-OAuth-App API, but the App *Manifest* flow lets the owner
@@ -479,6 +549,35 @@ async function updateInstanceSettings(db, id, patch) {
   return rows[0] || null;
 }
 
+// Fill in (or change) the project-detail answers AFTER creation — the other half
+// of "skippable" (task 1002334). Skipping the step at creation is a supported
+// default, but it is only a default and not a dead end if there is a way back; this
+// is that way back, and it is what turns a dark-matter project publishable once its
+// owner writes a description (ADR 0182 D4).
+//
+// `detail` MERGES (the settings `||` precedent — a form may send one answer without
+// resending the rest) while `description` REPLACES, because prose has no keys to
+// merge. Passing description: null clears it — and un-publishes the project, which
+// is the honest consequence of deleting half the identity gate, not a bug.
+// Undefined leaves the column alone.
+async function updateInstanceDetail(db, id, { description, detail } = {}) {
+  const sets = ['updated_at = now()'];
+  const params = [id];
+  if (description !== undefined) {
+    params.push(description);
+    sets.push(`description = $${params.length}`);
+  }
+  if (detail !== undefined) {
+    params.push(JSON.stringify(normalizeProjectDetail(detail)));
+    sets.push(`detail = detail || $${params.length}::jsonb`);
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
+    params
+  );
+  return rows[0] || null;
+}
+
 // Record an instance's domain — the ONLY columns this touches (task 1002692;
 // `releasing` added by task 1003237). Status changes stay setInstanceStatus's job;
 // keeping this narrow means the domain-attach route can never drift an instance's
@@ -630,7 +729,7 @@ async function listAllInstances(db, { status } = {}) {
 // re-fetches the existing row and returns { created:false } so the ROUTE can
 // decide (same owner → idempotent re-request; different owner → 409). Never
 // silently reassigns ownership.
-async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type }) {
+async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type, description, detail }) {
   const shape = HOSTING_SHAPES.includes(hostingShape) ? hostingShape : 'co-tenant';
   // Unknown/absent → 'greenfield', matching the column default. Falling back to the
   // SAFE mode matters: greenfield refuses to push over existing history (no --force
@@ -639,15 +738,22 @@ async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShap
   const mode = ONBOARD_MODES.includes(onboardMode) ? onboardMode : 'greenfield';
   // Type is a declaration — off-vocabulary or absent stores null, never a guess.
   const declaredType = PROJECT_TYPES.includes(type) ? type : null;
+  // The optional project-detail step (task 1002334). Skipping it is the SUPPORTED
+  // default, so both of these legitimately land empty — a null description is what
+  // leaves the project dark-matter until its owner fills it in (ADR 0182 D4), and
+  // updateInstanceDetail is the way back.
+  const told = normalizeDescription(description);
+  const answers = normalizeProjectDetail(detail);
   const cost = costEstimateUsd({ hostingShape: shape, tier });
   try {
     const { rows } = await db.query(
       `INSERT INTO provisioning_instances
-         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type, description, detail)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::jsonb)
        RETURNING *`,
       [ownerBuilderId, slug, targetRef ?? null, shape, domain ?? null,
-       dbName ?? null, port ?? null, tier ?? null, cost, mode, declaredType]
+       dbName ?? null, port ?? null, tier ?? null, cost, mode, declaredType,
+       told, JSON.stringify(answers)]
     );
     return { instance: rows[0], created: true };
   } catch (e) {
@@ -959,10 +1065,11 @@ module.exports = {
   SETTINGS_APPLY_FROM, SETTINGS_APPLY_SHAPES,
   RESTART_FROM, RESTART_SHAPES,
   TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
-  SETTINGS_VOCAB, DEFAULT_SETTINGS,
+  SETTINGS_VOCAB, DEFAULT_SETTINGS, PROJECT_DETAIL_VOCAB, DESCRIPTION_MAX,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
   defaultDomainForSlug, isReservedHostname, effectiveSettings,
+  normalizeDescription, normalizeProjectDetail, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
   // data access
@@ -970,6 +1077,7 @@ module.exports = {
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
+  createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings, updateInstanceDetail,
   createInstance, setInstanceStatus, updateInstanceDomain, clearReleasedDomains, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, enqueueSettingsApply, enqueueRestart, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,