@bongos/core 1.19.527 → 1.19.529

package/docs/module-api-changelog.md

@@ -1491,5 +1491,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.525 with no explicit bump. run 33824700579. (task 1002620)
   1.19.527 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.526 with no explicit bump. run 33827382028. (task 1002620)
+  1.19.528 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.527 with no explicit bump. run 33829339717. (task 1002620)
+  1.19.529 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.528 with no explicit bump. run 33877197857. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/grading/grader-subagent.js

@@ -23,6 +23,25 @@ function runSubagent({ prompt, opts = {} }) {
     // isn't named `claude` on PATH — covers any OS, not just Windows.
     const bin = opts.claudeBin ?? process.env.OTB_CLAUDE_BIN ?? process.env.CLAUDE_BIN ?? 'claude';
 
+    // THE PERMISSION MODE IS ROOT-DEPENDENT (task 1003574). `bypassPermissions` maps
+    // to --dangerously-skip-permissions, and the CLI REFUSES that when euid is 0:
+    //   "--dangerously-skip-permissions cannot be used with root/sudo privileges"
+    // It exits non-zero before doing any work, so under root EVERY worker returns
+    // SUBAGENT_NONZERO_EXIT and the whole panel dies. A root container is an ordinary
+    // CI/sandbox shape, not an exotic one — this was hit on a real ship (task 1003280).
+    //
+    // `acceptEdits` is the fallback because it is the closest mode the CLI accepts as
+    // root, and it grants this worker NOTHING extra: the tool list is `Read` alone, so
+    // there are no edits to accept. Verified as root that a worker under acceptEdits
+    // still reads files inside its cwd (which is all a grader worker ever does) while
+    // a path outside the project is refused without hanging — in -p there is no prompt
+    // to answer, so a denial returns rather than blocking.
+    //
+    // Non-root keeps bypassPermissions exactly as before: this narrows the mode only
+    // where the wider one cannot run at all.
+    const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+    const permissionMode = isRoot ? 'acceptEdits' : 'bypassPermissions';
+
     const args = [
       '-p',
       '--print',
@@ -30,7 +49,7 @@ function runSubagent({ prompt, opts = {} }) {
       '--output-format', 'json',
       '--tools', 'Read',
       '--disable-slash-commands',
-      '--permission-mode', 'bypassPermissions',
+      '--permission-mode', permissionMode,
     ];
 
     const startedAt = Date.now();

package/modules/grading/grader.js

@@ -183,6 +183,11 @@ function aggregatePanel(workerResults, meta = {}) {
   // If the panel were somehow advisory-only, fall back to gating on everyone so
   // a lone Narc still counts (defensive — the default panel always has 3+
   // gating workers).
+  // A pseudo-worker produced by a deterministic check rather than an LLM subagent
+  // (route-rank, permission-path — both stamp model:'deterministic'). It cannot be
+  // taken out by a grader outage, so it is not evidence either way about whether the
+  // panel ran. Task 1003574.
+  const isDeterministic = (w) => w && w.model === 'deterministic';
   const nonAdvisory = workerResults.filter((w) => !isAdvisory(w));
   const gating = nonAdvisory.length ? nonAdvisory : workerResults;
   const gatingFail = gating.filter((w) => w.verdict === 'fail' && !isMissingSignal(w)).length;
@@ -202,7 +207,25 @@ function aggregatePanel(workerResults, meta = {}) {
   // is an infra/outage condition, NOT a 0/10 quality rejection. Distinguished
   // from the partial-error case (some gating workers errored, others reported)
   // so callers (ship.js) can present "grader unavailable" instead of a FAIL.
-  const gatingErrorAll = gating.length > 0 && gating.every((w) => isMissingSignal(w));
+  //
+  // TASK 1003574 — WHY THIS COUNTS ONLY THE SUBAGENT WORKERS. When #943 was written
+  // every gating worker was an LLM subagent, so "all of them are missing signal" and
+  // "the grader could not run" were the same sentence. They stopped being the same
+  // the moment the DETERMINISTIC pseudo-workers (route-rank, permission-path) were
+  // appended to workerResults: those never spawn a subprocess, so an outage cannot
+  // touch them, and a passing route-rank made `gating.every(isMissingSignal)`
+  // permanently false. The effect was that a TOTAL subagent outage could no longer
+  // reach this branch at all — it fell through to securityLensErrored and was
+  // reported as `FAIL · 0/10` with zero issues and every rubric axis null, which is
+  // indistinguishable from a real rejection and routes the builder to a re-grade
+  // that cannot clear it. Observed end-to-end on task 1003280.
+  //
+  // Excluding the deterministic checks here does NOT weaken the gate: a
+  // deterministic worker that FAILS is a real finding and is caught by `gatingFail`,
+  // which is the first branch and takes precedence over this one. All this says is
+  // that a deterministic check PASSING is not evidence the grader ran.
+  const subagentGating = gating.filter((w) => !isDeterministic(w));
+  const gatingErrorAll = subagentGating.length > 0 && subagentGating.every((w) => isMissingSignal(w));
   // Advisory-worker outcomes — never a hard block. Uses isAdvisory so a Narc
   // that DID raise a blocker is treated as gating (in `nonAdvisory`), not here.
   const advisoryFail = workerResults.some((w) => isAdvisory(w) && w.verdict === 'fail' && !isMissingSignal(w));

package/modules/lifecycle/cascade.js

@@ -77,10 +77,85 @@
 //               a throw is caught and treated as "no match", because a broken
 //               predicate must not stop the other rules.
 //   title(task) / body(task)  the generated task's title and description.
-//   kind        optional task kind; defaults to 'chore'.
+//   kind        optional task kind; must be one the classifier knows
+//               (task-classifier.VALID_KINDS). Defaults to 'unclassified' —
+//               which is right for generated work anyway, because a request the
+//               board has not triaged has, precisely, no classification yet.
 //
-// Production rules live here. It is empty by design — see the header.
-const CASCADES = Object.freeze([]);
+// ---------------------------------------------------------------------------
+// The first production rule (R04 of goal 1000074, task 1003115).
+// ---------------------------------------------------------------------------
+//
+// THE ARTIST REVIEW. "Every shipped work with copy or visuals becomes a Review
+// task for an artist, in two steps" (the criterion artist-review-task-on-ship).
+// This is the rule that makes that true, and it is the whole of R04's build: the
+// mechanism (ADR 0242) and its four safety properties already exist and are
+// tested; R04 writes the one declaration.
+//
+// TWO GUARDS THAT KEEP IT FROM MISFIRING, both pinned in the tests:
+//   • It excludes `source === CASCADE_SOURCE`. Without that, the artist review
+//     task it generates — discipline 'artist', so it matches its own predicate —
+//     would on ship generate a review OF the review, and so on. The exclusion
+//     makes the generation a single hop, never a chain.
+//   • "Copy or visuals" is a NARROW, explicit predicate (hasCopyOrVisualWork),
+//     not "every ship". A cascade that fired on everything would bury the artist,
+//     and the criterion's "dismissable rather than nagging" would be a lie.
+//
+// It does NOT block anything (ADR 0241 draws the line: an artist may hold a
+// DEPLOY, decided per project, never a builder's ship; that gate is a separate
+// build). The generated task is a `backlog` request that triage may dismiss.
+
+// The modules whose shipped work puts user-facing copy or visuals in front of a
+// person. Kept as an explicit set rather than inferred, because "is this
+// copy/visual work" is a judgement the rule should state out loud and a test
+// should be able to pin — an inferred predicate is the kind that quietly widens.
+const COPY_VISUAL_MODULES = Object.freeze([
+  'copy-desk',    // the copy registry + proposals (goal 1000074's own spine)
+  'hall-ui',      // the builders' hall — the most-seen surface
+  'art-pipeline', // generated visual assets
+  'status-ui',    // the public status dashboard
+  'ui-design',    // the design-system surfaces (ADR 0081)
+]);
+
+// Does this shipped task's work put copy or visuals in front of a person? Pure
+// and total — the runner treats a throw as "no match", but this must not throw.
+function hasCopyOrVisualWork(task) {
+  if (!task) return false;
+  if (task.source === 'copy-proposal') return true;        // a copy change that landed via the copy desk (ADR 0233)
+  if (task.discipline === 'artist') return true;           // work an artist did is, by definition, on their surface
+  if (task.module_key && COPY_VISUAL_MODULES.includes(task.module_key)) return true;
+  return false;
+}
+
+// The two-step artist review body. STEP 1 coaches the grader (the artist trains
+// the grading system, not only the artefact); STEP 2 remakes the copy/visuals
+// with both routes explicitly offered — R04's brief, verbatim in intent.
+function artistReviewBody(task) {
+  return [
+    `This is an ARTIST REVIEW, generated automatically because task ${task.id} put copy or visuals in front of a person. It is a REQUEST, not a gate — it blocks nothing that shipped, and triage may dismiss it.`,
+    '',
+    `STEP 1 — REVIEW THE GRADER, not only the work. Read how the grader judged task ${task.id}'s copy and visuals, and coach it: where was it right, and where did it miss what an artist would catch — slop, an off-voice line, a claim that does not land, a visual that reads as generated? The artist trains the grading system, not just the artefact, so this step is the one that compounds.`,
+    '',
+    'STEP 2 — REMAKE OR TWEAK the copy/visuals if they need it. Your choice of route, both offered on purpose: OUTSIDE the AI chat (edit the surface directly and land it through the copy desk or the normal pipeline), or WITH it (draft in chat, then land). Either way it lands as a claimed, graded, shipped task like everything else — there is no live CMS (goal 1000074\'s hard rule).',
+    '',
+    'If the copy and visuals are fine and the grader judged them well, DISMISS this in triage. That is a real, expected outcome — not a failure.',
+  ].join('\n');
+}
+
+// Production rules. The artist review is the first (R04); add another by
+// appending an entry, never by touching the runner (ADR 0242).
+const CASCADES = Object.freeze([
+  Object.freeze({
+    key: 'artist-review-on-ship',
+    discipline: 'artist',
+    kind: 'unclassified',
+    // The anti-recursion guard (source !== CASCADE_SOURCE) is FIRST so a
+    // cascade-generated task is rejected before any other test runs.
+    when: (t) => t.source !== CASCADE_SOURCE && hasCopyOrVisualWork(t),
+    title: (t) => `Artist review: the copy and visuals that shipped in task ${t.id}`,
+    body: artistReviewBody,
+  }),
+]);
 
 // The (source, source_ref) pair the generated task is keyed on. `source` is a
 // constant so every cascade-generated row is findable as a class; the ref pins
@@ -171,7 +246,11 @@ function cascadeTaskSpec(rule, task) {
     title: String(rule.title(task) || '').trim(),
     description: `${preamble}\n\n${body}`,
     discipline: rule.discipline,
-    kind: rule.kind || 'chore',
+    // 'unclassified', not 'chore' (task 1003115): the cascade calls db.createTask
+    // directly, bypassing the route's kind validation, and 'chore' is not in
+    // task-classifier.VALID_KINDS — it would have written an invalid kind. A
+    // generated request the board has not triaged is genuinely unclassified.
+    kind: rule.kind || 'unclassified',
     status: 'backlog',
     source: CASCADE_SOURCE,
     sourceRef: cascadeSourceRef(rule.key, task.id),
@@ -229,6 +308,9 @@ async function runCascadesForShip(shipped, deps = {}) {
 module.exports = {
   CASCADES,
   CASCADE_SOURCE,
+  COPY_VISUAL_MODULES,
+  hasCopyOrVisualWork,
+  artistReviewBody,
   cascadeSourceRef,
   assertRuleShape,
   validateCascades,

package/modules/lifecycle/tests/cascade.mjs

@@ -185,12 +185,69 @@ await test('the production table is valid, and a duplicate key is refused', () =
   assert.ok(shape.some((p) => /body/.test(p)));
 });
 
-await test('the production table ships EMPTY, deliberately — R04 writes the first rule', () => {
-  // If this fails because a rule was added, that is fine: replace the assertion
-  // with one that pins the new rule's key and discipline. It exists so the
-  // emptiness is a DECISION on the record (see cascade.js's header) rather than
-  // something nobody noticed.
-  assert.equal(cascade.CASCADES.length, 0);
+// --- the first production rule: the artist review (R04, task 1003115) --------
+
+const shippedCopy = (over = {}) => ({
+  id: '7001', version_id: 'BONGOS-V1', goal_id: '1000074',
+  title: 'Reword the hall empty states', discipline: 'engineer',
+  kind: 'feature', status: 'shipped', module_key: 'hall-ui', source: 'manual',
+  ...over,
+});
+
+await test('the artist review is the one production rule, keyed and disciplined', () => {
+  assert.equal(cascade.CASCADES.length, 1);
+  const r = cascade.CASCADES[0];
+  assert.equal(r.key, 'artist-review-on-ship');
+  assert.equal(r.discipline, 'artist', 'the review is FOR the artist, whatever role shipped the work');
+  assert.equal(r.kind, 'unclassified', 'a valid kind — not the invalid "chore" the spec used to default to');
+  assert.deepEqual(cascade.validateCascades(), [], 'and the shipped table is well-formed');
+});
+
+await test('a copy/visual ship generates the two-step artist review', () => {
+  const { matched } = cascade.cascadesFor(shippedCopy());
+  assert.equal(matched.length, 1);
+  const spec = matched[0].spec;
+  assert.equal(spec.discipline, 'artist');
+  assert.equal(spec.kind, 'unclassified');
+  assert.equal(spec.status, 'backlog', 'a request that triage may dismiss — not claimable, not nagging');
+  assert.match(spec.title, /7001/);
+  // Both steps, and both routes of step 2, are in the body.
+  assert.match(spec.description, /STEP 1 — REVIEW THE GRADER/);
+  assert.match(spec.description, /STEP 2 — REMAKE OR TWEAK/);
+  assert.match(spec.description, /OUTSIDE the AI chat/);
+  assert.match(spec.description, /WITH it/);
+  assert.match(spec.description, /DISMISS this in triage/);
+  assert.match(spec.description, /blocks nothing that shipped/, 'it says out loud that it is not a gate');
+});
+
+await test('"copy or visuals" is a NARROW predicate — three ways in, and a default of no', () => {
+  const H = cascade.hasCopyOrVisualWork;
+  assert.equal(H(shippedCopy({ module_key: 'copy-desk' })), true);
+  assert.equal(H(shippedCopy({ module_key: 'art-pipeline' })), true);
+  assert.equal(H(shippedCopy({ module_key: null, source: 'copy-proposal' })), true, 'a landed copy proposal');
+  assert.equal(H(shippedCopy({ module_key: null, source: 'manual', discipline: 'artist' })), true, 'work an artist did');
+  // The default is NO — a backend/infra ship is not an artist review.
+  assert.equal(H(shippedCopy({ module_key: 'lifecycle', discipline: 'engineer', source: 'manual' })), false);
+  assert.equal(H(shippedCopy({ module_key: null, discipline: 'engineer', source: 'manual' })), false);
+  assert.equal(H(null), false);
+});
+
+await test('THE ANTI-RECURSION GUARD: an artist review shipping does NOT generate a review of itself', () => {
+  // The generated review is discipline:'artist' + source:'cascade'. Its own
+  // predicate (discipline artist) would match — so without the source guard it
+  // would cascade forever. This is the test that proves it is a single hop.
+  const reviewTaskThatShipped = shippedCopy({
+    discipline: 'artist', source: cascade.CASCADE_SOURCE, module_key: null, id: '7100',
+  });
+  const { matched } = cascade.cascadesFor(reviewTaskThatShipped);
+  assert.equal(matched.length, 0, 'a cascade-generated task never triggers another cascade');
+});
+
+await test('the review inherits the shipped task goal and version, not goal 1000074 by fiat', () => {
+  // A copy ship in some other goal gets its review filed next to that work.
+  const { matched } = cascade.cascadesFor(shippedCopy({ goal_id: '1000046', version_id: 'BONGOS-V1' }));
+  assert.equal(matched[0].spec.goalId, 1000046);
+  assert.equal(matched[0].spec.versionId, 'BONGOS-V1');
 });
 
 console.log(`\n${passed} passed, ${failed} failed`);

package/modules/provisioning/recommendations.js

@@ -39,42 +39,20 @@
 
 'use strict';
 
-const { bundleForProjectType, ALWAYS_ON_CORE } = require('./starter-bundles');
+const { bundleForAnswers, TEAM_SHAPE_RULES, ALWAYS_ON_CORE } = require('./starter-bundles');
 const { PROJECT_DETAIL_VOCAB } = require('./provisioning');
 
-// How the team shape adjusts the type's starter bundle, in application order.
-// Each entry is one condition (`teamShape`) and one effect on ONE opt-in module,
-// carrying the sentence a picker shows when it fires. Deliberately tiny: ADR 0237
-// already made the per-type preset the opinion, and today's opt-in catalog is
-// three modules wide (`agents`, `dev-box`, `discord`) — so this table's job is to
-// correct a preset the owner's answer contradicts, not to re-derive it.
+// `TEAM_SHAPE_RULES` MOVED to starter-bundles.js (BV1.R22, task 1002341; ADR 0243)
+// and is re-exported here so this file's public surface is unchanged. It went to
+// the bundle layer because a bundle adjustment is not advice about the bundle —
+// it IS the bundle once the owner has answered, and `effectiveModules` is the
+// function ADR 0240 §2 hangs the whole skip contract on. A rule the creation
+// picker applies but that fallback does not is two lists kept in agreement by
+// hand, which is the failure ADR 0240 §2 was written to make impossible.
 //
-// A rule may only ever name an OPT-IN module. Adding or removing an always-on one
-// would be a toggle that toggles nothing (ADR 0237 §3's argument, and
-// `tests/provisioning_recommendations.mjs` fails the build over it).
-const TEAM_SHAPE_RULES = Object.freeze([
-  Object.freeze({
-    id: 'a-community-needs-somewhere-to-gather',
-    teamShape: 'community',
-    effect: 'add',
-    module: 'discord',
-    reason: 'You said an open community is building this, so somewhere for it to gather is switched on.',
-  }),
-  Object.freeze({
-    id: 'a-team-shares-one-environment',
-    teamShape: 'small-team',
-    effect: 'add',
-    module: 'dev-box',
-    reason: 'A small team gets one shared environment to build in, so nobody is debugging their own laptop.',
-  }),
-  Object.freeze({
-    id: 'building-alone-needs-no-shared-environment',
-    teamShape: 'solo',
-    effect: 'remove',
-    module: 'dev-box',
-    reason: 'You are building this alone, so the shared cloud environment is off — your own machine is the setup.',
-  }),
-]);
+// What stays HERE is the advice: a governance preset that is only ever previewed,
+// and an invite SEEK nothing in this module may run. Neither is a thing a project
+// silently ends up with, so neither belongs in the read-time resolution.
 
 // The governance presets, by key. A preset is a NAME plus the one sentence that
 // says what living under it feels like — never a set of roles or permissions,
@@ -167,25 +145,6 @@ function normalizeTeamShape(value) {
   return PROJECT_DETAIL_VOCAB.team_shape.includes(value) ? value : null;
 }
 
-// Apply the team-shape rules to one type's opt-in bundle. Returns the adjusted
-// list plus the adjustments that ACTUALLY changed it — a rule whose module the
-// bundle already carries (or already lacks) records nothing, because a stated
-// reason for a change that did not happen is a lie the owner cannot check.
-// Never touches the always-on core. PURE.
-function adjustBundle(bundle, teamShape) {
-  const modules = [...bundle];
-  const adjustments = [];
-  for (const rule of TEAM_SHAPE_RULES) {
-    if (rule.teamShape !== teamShape) continue;
-    const at = modules.indexOf(rule.module);
-    if (rule.effect === 'add' && at === -1) modules.push(rule.module);
-    else if (rule.effect === 'remove' && at !== -1) modules.splice(at, 1);
-    else continue;
-    adjustments.push({ rule: rule.id, effect: rule.effect, module: rule.module, reason: rule.reason });
-  }
-  return { modules, adjustments };
-}
-
 // The whole recommendation for one set of creation answers:
 //
 //   {
@@ -211,8 +170,10 @@ function adjustBundle(bundle, teamShape) {
 function recommendationsForDetails(answers) {
   const given = answers && typeof answers === 'object' && !Array.isArray(answers) ? answers : {};
   const teamShape = normalizeTeamShape(given.team_shape);
-  const preset = bundleForProjectType(given.type);
-  const { modules, adjustments } = adjustBundle(preset.bundle, teamShape);
+  // The SAME resolver the picker preselects from and effectiveModules falls back
+  // to (ADR 0243) — so the recommendation, the panel and the project a skipped
+  // picker ends up with are one function's answer, not three that agree.
+  const preset = bundleForAnswers(given.type, teamShape);
 
   const gov = GOVERNANCE_RULES.find((r) => r.teamShape === teamShape) || GOVERNANCE_DEFAULT;
   const invite = INVITE_RULES.find((r) => r.teamShape === teamShape) || INVITE_DEFAULT;
@@ -226,9 +187,9 @@ function recommendationsForDetails(answers) {
       label: preset.label,
       summary: preset.summary,
       core: [...ALWAYS_ON_CORE],
-      bundle: modules,
-      modules: [...ALWAYS_ON_CORE, ...modules],
-      adjustments,
+      bundle: preset.bundle,
+      modules: preset.modules,
+      adjustments: preset.adjustments,
     },
     governance: {
       preset: gov.preset,

package/modules/provisioning/routes/provisioning.js

@@ -36,7 +36,7 @@ const auth = api;
 const { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { onboardPlan, stepsForShape } = require('../onboard-plan');
-const { ALWAYS_ON_CORE, OPTIONAL_MODULES, allStarterBundles, optionalModules } = require('../starter-bundles');
+const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModules, effectiveModules } = require('../starter-bundles');
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -840,6 +840,8 @@ module.exports = function provisioningRoutes() {
         // project is now on the map, and one who cleared it learns it just left.
         // Re-deriving it from a follow-up GET would let the two answers disagree.
         publish: publishVerdict(updated),
+        // `team_shape` MOVES a bundle-sourced project's modules — effect with cause (ADR 0243 §5).
+        modules: effectiveModules(updated),
       });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/detail', err);
@@ -1337,8 +1339,10 @@ module.exports = function provisioningRoutes() {
   // row for. The alternatives were both worse: `GET /modules` needs a session
   // (this wizard is read signed-out) and `GET /public/modules` serves booleans,
   // not copy. Additive — `core` and `bundles` keep their shape.
+  // `byTeamShape` re-resolves each bundle for every answer the About step can give,
+  // riding THIS payload rather than a second read (task 1002341; ADR 0243 §4).
   router.get('/provisioning/starter-bundles', (req, res) => {
-    res.json({ core: [...ALWAYS_ON_CORE], bundles: allStarterBundles(), optional: optionalModules() });
+    res.json({ core: [...ALWAYS_ON_CORE], bundles: starterBundleAnswerTable(), optional: optionalModules() });
   });
 
   // GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer>

package/modules/provisioning/starter-bundles.js

@@ -106,6 +106,60 @@ const OPTIONAL_MODULES = Object.freeze([
 // so the declaration above stays the single place a choice is written down.
 const OPTIONAL_MODULE_KEYS = Object.freeze(OPTIONAL_MODULES.map((m) => m.key));
 
+// How the interview's team-shape answer ADJUSTS the type's starter bundle, in
+// application order. Each entry is one condition (`teamShape`) and one effect on
+// ONE opt-in module, carrying the sentence the picker shows when it fires.
+//
+// WHY THE TABLE LIVES HERE and not in recommendations.js beside the governance
+// and invite tables it shipped with (task 1002336, ADR 0239). A bundle adjustment
+// is not advice about the bundle — it IS the bundle, once the owner has answered.
+// `effectiveModules` below is the function ADR 0240 §2 leans the whole skip
+// contract on ("the preselect and the fallback are the same declaration — one
+// function, called twice"), and a rule the picker applies but that function does
+// not is exactly two lists kept in agreement by hand. So the rules sit at the
+// bundle layer, `effectiveModules` applies them, and recommendations.js re-exports
+// them unchanged — its governance preview and invite seam are genuinely advice and
+// stay there. Decision: ADR 0243 (BV1.R22, task 1002341).
+//
+// Deliberately tiny: ADR 0237 already made the per-type preset the opinion, and
+// today's opt-in catalog is three modules wide — so this table's job is to correct
+// a preset the owner's answer contradicts, not to re-derive it.
+//
+// A rule may only ever name an OPT-IN module. Adding or removing an always-on one
+// would be a toggle that toggles nothing (ADR 0237 §3's argument, and
+// `tests/provisioning_recommendations.mjs` fails the build over it).
+const TEAM_SHAPE_RULES = Object.freeze([
+  Object.freeze({
+    id: 'a-community-needs-somewhere-to-gather',
+    teamShape: 'community',
+    effect: 'add',
+    module: 'discord',
+    reason: 'You said an open community is building this, so somewhere for it to gather is switched on.',
+  }),
+  Object.freeze({
+    id: 'a-team-shares-one-environment',
+    teamShape: 'small-team',
+    effect: 'add',
+    module: 'dev-box',
+    reason: 'A small team gets one shared environment to build in, so nobody is debugging their own laptop.',
+  }),
+  Object.freeze({
+    id: 'building-alone-needs-no-shared-environment',
+    teamShape: 'solo',
+    effect: 'remove',
+    module: 'dev-box',
+    reason: 'You are building this alone, so the shared cloud environment is off — your own machine is the setup.',
+  }),
+]);
+
+// The team shapes the rules above can fire on. Derived from the table rather than
+// imported from provisioning.js's PROJECT_DETAIL_VOCAB, because importing it would
+// point this file UP at the module that requires it. It costs nothing to derive:
+// an off-vocabulary shape matches no rule and adjusts nothing, which is already
+// the right answer — `tests/provisioning_recommendations.mjs` pins the two lists
+// against each other so a fourth interview answer cannot arrive unhandled.
+const RULED_TEAM_SHAPES = Object.freeze([...new Set(TEAM_SHAPE_RULES.map((r) => r.teamShape))]);
+
 // The curated presets, keyed by the declared project type (the closed vocabulary
 // owner-decided 2026-08-13 and mirrored in provisioning.PROJECT_TYPES + the
 // provisioning_007 CHECK). `label` and `summary` are the owner-facing copy the
@@ -192,6 +246,69 @@ function optionalModules() {
   return OPTIONAL_MODULES.map((m) => ({ ...m }));
 }
 
+// Apply the team-shape rules to one type's opt-in bundle. Returns the adjusted
+// list plus the adjustments that ACTUALLY changed it — a rule whose module the
+// bundle already carries (or already lacks) records nothing, because a stated
+// reason for a change that did not happen is a lie the owner cannot check.
+// A null/unknown/off-vocabulary shape fires no rule and adjusts nothing, which is
+// the same answer `normalizeProjectDetail` gives such a value on the way in.
+// Never touches the always-on core. PURE.
+function adjustBundle(bundle, teamShape) {
+  const held = new Set(bundle);
+  const adjustments = [];
+  for (const rule of TEAM_SHAPE_RULES) {
+    if (rule.teamShape !== teamShape) continue;
+    if (rule.effect === 'add' && !held.has(rule.module)) held.add(rule.module);
+    else if (rule.effect === 'remove' && held.has(rule.module)) held.delete(rule.module);
+    else continue;
+    adjustments.push({ rule: rule.id, effect: rule.effect, module: rule.module, reason: rule.reason });
+  }
+  // CATALOG order, not append order — `normalizeModuleSelection` stores a chosen
+  // set this way and the picker re-derives its toggles this way, so an adjusted
+  // bundle that appended would make the same set of modules read as a different
+  // list depending on whether the owner answered the picker or skipped it.
+  return { modules: OPTIONAL_MODULE_KEYS.filter((k) => held.has(k)), adjustments };
+}
+
+// What the creation flow preselects for one set of ANSWERS — `bundleForProjectType`
+// with the team-shape rules applied, in the same `{ type, label, summary, core,
+// bundle, modules }` shape plus the `adjustments` delta that got it there.
+//
+// This is the single resolver the picker paints from and `effectiveModules` falls
+// back to, so an owner who answers the interview and then skips the picker gets
+// the set the panel was showing them (ADR 0240 §2's property, extended to the
+// interview's answer — BV1.R22, ADR 0243). PURE; arrays are fresh.
+function bundleForAnswers(type, teamShape) {
+  const preset = bundleForProjectType(type);
+  const { modules, adjustments } = adjustBundle(preset.bundle, teamShape);
+  return {
+    ...preset,
+    bundle: modules,
+    modules: [...ALWAYS_ON_CORE, ...modules],
+    adjustments,
+  };
+}
+
+// Every curated bundle resolved for every team shape the rules can fire on, plus
+// the no-answer resolution — the whole preselect table in ONE read.
+//
+// The picker needs this shape rather than a per-answer query because ADR 0240 §4's
+// rule is that what may be chosen and what is preselected have to arrive together
+// or the panel can preselect a key it has no row for. The owner flips the type
+// question and the team-shape question freely on two earlier panels; re-preselecting
+// must not cost a round trip, and a round trip it did pay could land after they had
+// moved on. PURE — five types by four answers is twenty small rows.
+function starterBundleAnswerTable() {
+  return allStarterBundles().map((preset) => {
+    const byTeamShape = {};
+    for (const shape of RULED_TEAM_SHAPES) {
+      const { modules, adjustments } = adjustBundle(preset.bundle, shape);
+      byTeamShape[shape] = { bundle: modules, adjustments };
+    }
+    return { ...preset, byTeamShape };
+  });
+}
+
 // A MODULE SELECTION as it may be STORED (BV1.R20, task 1002339): opt-in keys
 // only, deduped, in catalog order. Everything else is dropped — an always-on
 // module (it was never a choice), a hub-only one (the control plane's own), and
@@ -218,22 +335,39 @@ function normalizeModuleSelection(input) {
 
 // What a row's modules READ as: the always-on floor, plus whatever the owner
 // chose — or, when they never answered, the starter bundle for their declared
-// type. `source` says which of the two it is, so a surface can tell a chosen
-// empty set from an unanswered one without re-deriving the rule.
+// type ADJUSTED by what they told the interview. `source` says which of the two
+// it is, so a surface can tell a chosen empty set from an unanswered one without
+// re-deriving the rule.
 //
 // This is what makes skipping the picker a supported default rather than a
 // project with nothing on it: the flow's preselect and the server's fallback are
 // the SAME declaration, so the owner gets exactly the set the panel showed them.
-// PURE — takes a row-shaped `{ type, modules }`, touches no database.
+// The team-shape adjustment is INSIDE that fallback (BV1.R22, ADR 0243) for
+// exactly that reason — the picker paints the adjusted set, so a picker skipped
+// after an answered interview has to resolve to the adjusted set too, or the
+// panel's promise stops being true the moment the interview is answered.
+//
+// Reads `detail.team_shape` straight off the row rather than through
+// provisioning.js's `normalizeProjectDetail` — importing it would point this file
+// up at the module that requires it, and it would buy nothing: an off-vocabulary
+// shape fires no rule and adjusts nothing, which is the answer the normalizer
+// would have produced anyway.
+//
+// PURE — takes a row-shaped `{ type, modules, detail }`, touches no database.
 function effectiveModules(row) {
   const chosen = normalizeModuleSelection(row && row.modules);
-  const preset = bundleForProjectType(row && row.type);
+  const detail = row && row.detail && typeof row.detail === 'object' ? row.detail : null;
+  const preset = bundleForAnswers(row && row.type, detail ? detail.team_shape : null);
   const selected = chosen === null ? preset.bundle : chosen;
   return {
     core: [...ALWAYS_ON_CORE],
     selected,
     modules: [...ALWAYS_ON_CORE, ...selected],
     source: chosen === null ? 'bundle' : 'chosen',
+    // Why the unanswered set is what it is, in the owner's own words — empty when
+    // nothing adjusted it, and never populated for a `chosen` set, because an
+    // owner's own toggle needs no reason given back to them.
+    adjustments: chosen === null ? preset.adjustments : [],
   };
 }
 
@@ -242,9 +376,14 @@ module.exports = {
   HUB_ONLY_MODULES,
   OPTIONAL_MODULES,
   STARTER_BUNDLES,
+  TEAM_SHAPE_RULES,
+  RULED_TEAM_SHAPES,
   bundleForProjectType,
   allStarterBundles,
   optionalModules,
+  adjustBundle,
+  bundleForAnswers,
+  starterBundleAnswerTable,
   normalizeModuleSelection,
   effectiveModules,
 };