@bongos/core 1.19.418 → 1.19.420

package/modules/platform-identity/migrations/platform_identity_015_connections.sql

@@ -0,0 +1,78 @@
+-- platform_identity_015_connections.sql — the connection graph (task 1002295 /
+-- goal 1000045 criterion C6; ADR 0202 D1, whose migration sketch this is).
+--
+-- WHAT THIS IS. One directed row per relationship — the REQUEST, not the edge.
+-- requester/addressee are kept because the inbox, the cancel path and the
+-- 90-day decline cooldown all need to know who asked; the unordered pair is
+-- GENERATED from LEAST/GREATEST so A→B and B→A collide on one index instead of
+-- both being accepted. Reads are symmetric (the module unions both directions);
+-- no route writes a direction-aware WHERE of its own.
+--
+-- WHY GENERATED + A PARTIAL UNIQUE INDEX rather than a route check: a duplicate
+-- request and a simultaneous reciprocal request then become DATABASE errors, not
+-- a race two handlers have to remember to lose. The index covers only the OPEN
+-- statuses, so resolved rows stay as the audit trail and never block a later ask
+-- (the goal_membership_requests precedent, core_188).
+--
+-- WHY NO TOMBSTONE ON REMOVE (ADR 0202 D2): removing an accepted connection
+-- HARD-DELETES the row. "A removed B" is data neither party consented to keep
+-- and no read path uses. 'rejected' is kept because it still does work — it is
+-- the cooldown — which is exactly why the asymmetry is not an inconsistency.
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank check, admission gate
+-- or credit path reads this table; accepting a connection changes nobody's rank,
+-- credits, or access to any project. It is descriptive social data only.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Forward-safe: CREATE
+-- only, so the previous code release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_connections (
+  id                   bigserial PRIMARY KEY,
+  requester_github_id  bigint NOT NULL,
+  addressee_github_id  bigint NOT NULL,
+  -- The unordered pair, derived — never written by a caller, so A→B and B→A
+  -- collide on the index below instead of both being accepted.
+  pair_lo bigint GENERATED ALWAYS AS (LEAST(requester_github_id, addressee_github_id)) STORED,
+  pair_hi bigint GENERATED ALWAYS AS (GREATEST(requester_github_id, addressee_github_id)) STORED,
+  status  text NOT NULL DEFAULT 'pending'
+            CHECK (status IN ('pending', 'accepted', 'rejected', 'cancelled', 'expired')),
+  -- The note cap lives HERE as well as in the route: requestConnection is an
+  -- exported domain function, and every other invariant in this table is one the
+  -- engine refuses to break rather than one a caller must remember.
+  note        text CONSTRAINT platform_identity_connections_note_len
+                CHECK (note IS NULL OR length(note) <= 280),
+  seen_at     timestamptz,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  resolved_at timestamptz,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT platform_identity_connections_not_self
+    CHECK (requester_github_id <> addressee_github_id)
+);
+
+-- At most ONE open relationship per pair. Resolved rows stay as the audit trail
+-- and never block a later ask.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_connections_open
+  ON platform_identity_connections (pair_lo, pair_hi)
+  WHERE status IN ('pending', 'accepted');
+
+-- The three reads: my inbox, my outbox, and the 1-hop neighbourhood both the
+-- degree traversal and the suggester expand from.
+CREATE INDEX IF NOT EXISTS platform_identity_connections_addressee
+  ON platform_identity_connections (addressee_github_id, status);
+CREATE INDEX IF NOT EXISTS platform_identity_connections_requester
+  ON platform_identity_connections (requester_github_id, status);
+CREATE INDEX IF NOT EXISTS platform_identity_connections_pair_accepted
+  ON platform_identity_connections (pair_lo, pair_hi) WHERE status = 'accepted';
+
+COMMENT ON TABLE platform_identity_connections IS
+  'Account-to-account connections on the hub (ADR 0202). One DIRECTED request row per relationship; pair_lo/pair_hi are the generated unordered key a partial unique index over (pending, accepted) enforces. Lifecycle pending -> accepted | rejected | cancelled | expired; remove hard-deletes. Descriptive only — never authority (ADR 0016).';
+
+COMMENT ON COLUMN platform_identity_connections.status IS
+  'pending -> accepted (addressee accepted) | rejected (addressee declined — SILENT to the requester, and the 90-day cooldown that swallows a re-ask) | cancelled (requester withdrew) | expired (30 days unanswered, resolved at write time because now() cannot live in an index predicate).';
+
+COMMENT ON COLUMN platform_identity_connections.seen_at IS
+  'Stamped on first inbox render (ADR 0202 D2, the privacy-spec D4 parity item) so a delivered/seen affordance can land later without a schema change. Never exposed to the requester — a decline is silent, and so is a read.';
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections"],
     "migrations": true,
     "pollers": ["code-sweep"]
   },

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

@@ -201,7 +201,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 +218,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];

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

@@ -0,0 +1,236 @@
+// modules/platform-identity/routes/connections.js — the connection graph API
+// (R19, task 1002295 / goal 1000045 criterion C6; ADR 0202).
+//
+// EVERY ROUTE HERE IS OWN-SCOPED. The acting account is always
+// req.builder.github_id — the session — and no route reads its subject from a
+// query, body or path parameter. The counterparty is named by HANDLE (the
+// public address, ADR 0171 D8) or by the connection row's own id; neither is a
+// way to act AS someone else. tests/own_scope_guard.mjs holds that structurally.
+//
+//   POST   /connections               — ask. Body { handle, note? }. 201
+//                                       { status: 'pending' } whether the row
+//                                       was written or SWALLOWED by the 90-day
+//                                       decline cooldown: the two answers are
+//                                       identical on purpose (ADR 0202 D2 §2).
+//                                       404 — not 403 — for a private or absent
+//                                       target, because 403 confirms the handle.
+//   GET    /connections               — my accepted connections. count is the
+//                                       array's own length (no hidden remainder).
+//   GET    /connections/requests      — my inbox + outbox; stamps seen_at.
+//   GET    /connections/degree/:handle — the viewer-relative label 0|1|2|3|null
+//                                       plus the mutuals it is computed from.
+//                                       An OWN-SCOPE read (D4 §4): this is how a
+//                                       viewer-relative number coexists with the
+//                                       viewer-independent public profile read.
+//   POST   /connections/:id/accept    — addressee only. 404 for anyone else.
+//   POST   /connections/:id/decline   — addressee only, SILENT (204). 404 else.
+//   DELETE /connections/:id           — remove an accepted row (either side) or
+//                                       cancel a pending one (requester only).
+//
+// A CONNECTION IS NEVER AUTHORITY (ADR 0016 / ADR 0141). Nothing here reads or
+// writes rank, credits, admission or permission; the numbers are descriptive.
+//
+// no-store on every response: these payloads are privacy-filtered per viewer and
+// a hide or a visibility flip must beat any cache (ADR 0171 D5).
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+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 { pool, requireBuilder, validateOrRespond, parsePagination } = api;
+const log = api.logger('platform-identity');
+
+// A connection row id is a bigserial. Anything else is answered 404 rather than
+// 400, for the same reason a wrong-owner id is: the id space must not be probeable.
+// The length cap is load-bearing, not cosmetic: a 25-digit string is all digits
+// and would reach Postgres, where it raises 22003 (bigint out of range) and
+// surfaces as a 500 — a different answer for a different id, i.e. a probe.
+function connectionId(req) {
+  return /^\d{1,19}$/.test(String(req.params.id || '')) ? req.params.id : null;
+}
+
+// The caller's platform account, or a { fail } describing why they cannot take
+// part. profile_state = 'active' is the floor for the WHOLE feature (ADR 0202
+// D4 §1): a provisional account cannot send, cannot receive, and never appears
+// in a list or a frontier. This is about the CALLER, so it may say so plainly.
+async function actingAccount(builder) {
+  const githubId = builder && builder.github_id;
+  if (!pi.isNumericGithubId(githubId)) {
+    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') {
+    return { fail: ['profile_provisional', { status: 403, message: 'sign in to the platform once to activate your profile before connecting' }] };
+  }
+  return { githubId };
+}
+
+// Resolve a handle to a counterparty THIS VIEWER may address: publicly visible,
+// or a private account the viewer is already connected to (ADR 0202 D4 §2).
+// Everything else — unknown handle, provisional account, private stranger — is
+// the same null, and the caller answers 404 for all of them.
+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;
+  return (await conn.isConnectedTo(viewerGithubId, acct.github_id, { pool })) ? acct : null;
+}
+
+module.exports = function connectionRoutes() {
+  const router = express.Router();
+
+  // One prefix covers every route below (/connections and /connections/...).
+  router.use('/connections', (req, res, next) => {
+    res.set('Cache-Control', 'no-store');
+    next();
+  });
+
+  // rank: any-builder — MY accepted connections (own data, keyed on the session).
+  // Own scope, so the counterparty floors on profile_state alone: a private
+  // account you connected with appears here and in no public list (D4 §2).
+  router.get('/connections', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const { limit, offset } = parsePagination(req, { defaultLimit: conn.FANOUT_1, maxLimit: conn.FANOUT_1 });
+      const connections = await conn.listConnections({ githubId: me.githubId, limit, offset }, { pool });
+      // The count IS the array's length — never a raw total beside a filtered
+      // list, which is a leak by subtraction (ADR 0171 D4 / ADR 0202 D4).
+      res.json({ connections, count: connections.length });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections failed');
+      res.fail('connections_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — MY pending requests, both directions (own data).
+  router.get('/connections/requests', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const { incoming, outgoing } = await conn.listRequests({ githubId: me.githubId }, { pool });
+      res.json({ incoming, outgoing, incoming_count: incoming.length, outgoing_count: outgoing.length });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections/requests failed');
+      res.fail('connection_requests_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — the degree label between the CALLER and one handle, plus
+  // the mutuals it was computed from (own-scope read, D4 §4). Bounded by
+  // construction: degreeBetween caps every level and answers null past the caps.
+  router.get('/connections/degree/:handle', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const target = await visibleTarget(me.githubId, req.params.handle);
+      if (!target) return res.fail('connection_target_not_found', 404);
+      const out = await conn.degreeBetween(me.githubId, target.github_id, { pool });
+      res.json({
+        handle: target.handle,
+        degree: out.degree,
+        mutuals: out.mutuals,
+        mutual_count: out.mutuals.length,
+        truncated: out.truncated,
+      });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections/degree/:handle failed');
+      res.fail('connection_degree_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — ask to connect. The REQUESTER is always the session; the
+  // body names only who is being asked, and it names them by public handle.
+  router.post('/connections', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      handle: { required: true, type: 'string', minLength: 1, maxLength: 39 },
+      note: { type: 'string', maxLength: conn.NOTE_MAX_CHARS },
+    })) return;
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const target = await visibleTarget(me.githubId, req.body.handle);
+      // Absent, provisional and private-stranger are ONE answer. A 403 would
+      // confirm the handle exists, which is the whole thing private protects.
+      if (!target) return res.fail('connection_target_not_found', 404);
+      if (String(target.github_id) === String(me.githubId)) {
+        return res.fail('cannot_connect_to_self', { status: 400, message: 'that is your own account' });
+      }
+      const out = await conn.requestConnection({
+        requesterGithubId: me.githubId,
+        addresseeGithubId: target.github_id,
+        note: req.body.note || null,
+      }, { pool });
+      if (out.outcome === 'already_open') {
+        return res.fail('connection_already_open', { status: 409, message: 'there is already a request or a connection between you' });
+      }
+      // 'created' and 'swallowed' answer IDENTICALLY — no id, no timestamps,
+      // nothing a caller could difference to learn they were declined before.
+      res.status(201).json({ status: 'pending' });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections failed');
+      res.fail('connection_request_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — accept a request addressed to ME. The addressee is the
+  // session; a row belonging to anyone else simply does not match, and the 404
+  // that follows is what stops a builder acting on someone else's connection.
+  router.post('/connections/:id/accept', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_request_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const ok = await conn.acceptConnection({ id, githubId: me.githubId }, { pool });
+      if (!ok) return res.fail('connection_request_not_found', 404);
+      res.json({ status: 'accepted' });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections/:id/accept failed');
+      res.fail('connection_accept_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — decline a request addressed to ME. 204: the requester is
+  // never told, so there is nothing to return that they could ever observe.
+  router.post('/connections/:id/decline', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_request_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const ok = await conn.declineConnection({ id, githubId: me.githubId }, { pool });
+      if (!ok) return res.fail('connection_request_not_found', 404);
+      res.status(204).end();
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections/:id/decline failed');
+      res.fail('connection_decline_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — remove an accepted connection (either side may end it)
+  // or cancel a pending request I sent. An ADDRESSEE ending a pending row is a
+  // decline, not a delete, and is 404'd here so the cooldown cannot be dodged.
+  router.delete('/connections/:id', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const outcome = await conn.removeConnection({ id, githubId: me.githubId }, { pool });
+      if (!outcome) return res.fail('connection_not_found', 404);
+      res.json({ outcome });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'DELETE /connections/:id failed');
+      res.fail('connection_remove_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

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,