@bongos/core 1.19.677 → 1.19.678

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.677",
-  "core_contract": "1.19.677",
-  "source_commit": "edcffc22cdab15c1f61e5cd2cb2b9d6a13872150",
+  "core_version": "1.19.678",
+  "core_contract": "1.19.678",
+  "source_commit": "f16c9e626ff2c55f717a95aee3d34d77b8d1d7cc",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T21:42:20.049Z",
+  "built_at": "2026-09-11T22:19:41.718Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 474,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2123,
+    "functional_verbatim": 2124,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2621,
-  "tree_sha256": "2afeb3b9fd9e3cf3de8feb833f7710642830cc081102cfd1a58d9e7ea6057332",
+  "file_count": 2622,
+  "tree_sha256": "f74a39b4cffb6701304f05814582718e8b1580ab01d97d6c6be2be8e2ff4e18f",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -387,7 +387,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "22523f2527d8849445122c5a03332d777a63d849a5806e33d387cbd83c54fb2f"
+      "sha256": "ba2f6ea9be911785f06761110363357fc1257fb53dadcb51def6194d1f60c9e7"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1912,12 +1912,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "6b681ad5de20a67efa1d6d024d5cb5dbe5313add4ec51d94a30a0025fa567ba2"
+      "sha256": "f4f639df647605d86971b62b81921c77c465ded0782eb29d7fc5254ba2f16d0d"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "45efd65847e2b9e5ade3d21eef0bc3ec3562184b109927f93425887ca99b02ba"
+      "sha256": "dbe27d28100bdbf007baefc90bfc93692b04fc8772019976292260617af175ac"
     },
     {
       "path": "docs/architecture.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "2fbf6cfad023d90c93ffcc7cadce65e73e578cead78069011d2b47b23a0de8e5"
+      "sha256": "ec91ef553908baf5180767c401d6b91afc48d938740258e63a48fb88106f7177"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5662,7 +5662,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "dde23a909ea56f7102d42af9bd5a832449940b00b4bfac7ed779e7938d95885c"
+      "sha256": "23df3da3437c14aa3dd1d276d501a9fd42c9937ffdfcec8d7b893d5edfd69469"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5697,7 +5697,7 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "8d8f8a16443e9f193829d8ac127b522e92984bcafc9a48a27c7deea5da2900b7"
+      "sha256": "7eaaafc9414bf77c12c57eefde02ddf1c67601f4b6b15ded3692bc3765ac036b"
     },
     {
       "path": "modules/lifecycle/db.js",
@@ -5947,7 +5947,7 @@
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "a8cdb97b220c2de738396986e8cd326218f688a0277b4c75784420cfbdd0d369"
+      "sha256": "d69b98e63306141aa01d064b82a249a05b96aa010404cebd00edbc887107e52d"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -7767,12 +7767,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f9c8562e66253cdfd8487dfb052d7a3443c477d4bb1abfef8b53946cd5104691"
+      "sha256": "0edc0468c32498fd329ba23692832935f7524f2b4d24065d9a53cf583728af49"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7be7c3c8b5ca557dbbf7f5a38453fedb85bd004e53b170e1746a03a02ab75ae9"
+      "sha256": "32048e9ab629a14af9beee43dba2b8620a0e29db73a806dc66f21d08061a3c8b"
     },
     {
       "path": "public-docs/index.html",
@@ -8362,7 +8362,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "390df0043001a825bbd4709df767e8ef21089743b799fc9c638a5509e8222ae8"
+      "sha256": "1d63c1485820ad2e81e97979402eabd3829e86503f4c06318a251dc3a6874047"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9532,7 +9532,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "025ba17e4ac4f614e81bde6009db0ed9ba04ccfb3d226abcc92e9e51d24b97b9"
+      "sha256": "538fc4afaf5a3f0da5eb4bcc3d99533cdf03cc5898163e6b8bcf8ca1584d14ec"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11382,7 +11382,7 @@
     {
       "path": "tests/init.mjs",
       "mode": "0000644",
-      "sha256": "21e5093a3b151e378a69249dab9b82845cec4d6c172d1a729cdc28512615a00b"
+      "sha256": "4a79313db6d6393415ace3e24f985be397156c10845b6543fdfbda3944ddeec0"
     },
     {
       "path": "tests/instance_config.mjs",
@@ -13014,6 +13014,11 @@
       "mode": "0000644",
       "sha256": "f972971a1f668a085c5f5b4c5ccba616e4b77a3f3308f9a48af33e43ecd62a8c"
     },
+    {
+      "path": "tests/version_first_goal.mjs",
+      "mode": "0000644",
+      "sha256": "52e6115ac6af363db16358c1264b01d3295d013db1a986a9c21fdb8ba58f4119"
+    },
     {
       "path": "tests/version_literals.mjs",
       "mode": "0000644",
@@ -13037,7 +13042,7 @@
     {
       "path": "tests/versions_route.mjs",
       "mode": "0000644",
-      "sha256": "2a381bab380342e4fc556211d4821c85fdde1f676a6c5c6aa2421a89a573cd27"
+      "sha256": "1e439ad083cb9a345fafc952d9527979c59d9ef9ca875e4aa1eb602b5227dc22"
     },
     {
       "path": "tests/visibility_pull.mjs",

package/clients/bongos-client/index.d.ts

@@ -397,8 +397,8 @@ export interface PostVersionsIdCloseRequest { reason?: string; dispositions?: Re
 export interface PostVersionsIdCloseResponse { ok: boolean; version: unknown; applied: unknown; promoted: unknown; carried: unknown }
 export interface PostVersionsIdDoneWhenRequest { criterion_id: string; criterion_md: string; goal_id?: number; sort_order?: number }
 export interface PostVersionsIdDoneWhenResponse { ok: boolean; criterion: unknown }
-export interface PostVersionsRequest { id: string; name: string; status?: string; track?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[] }
-export interface PostVersionsResponse { version: unknown; criteria: unknown }
+export interface PostVersionsRequest { id: string; name: string; status?: string; track?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[]; first_goal?: Record<string, unknown> }
+export interface PostVersionsResponse { version: unknown; goal: unknown; criteria: unknown }
 export interface PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse { ok: boolean; rank_key: unknown; permission_key: unknown; granted: unknown }
 export interface PutMingleOptInRequest { opted_in: boolean }
 export interface PutMingleOptInResponse { opted_in: unknown; updated_at: unknown }

package/docs/api/openapi.json

@@ -22791,6 +22791,9 @@
           "criteria": {
             "type": "array",
             "maxItems": 100
+          },
+          "first_goal": {
+            "type": "object"
           }
         },
         "required": [
@@ -22803,10 +22806,12 @@
         "type": "object",
         "properties": {
           "version": {},
+          "goal": {},
           "criteria": {}
         },
         "required": [
           "version",
+          "goal",
           "criteria"
         ]
       },

package/docs/api-reference.md

@@ -629,7 +629,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/versions` | `public` | — | read-only version list; mirrors /public/versions. |
-| POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `track`, `done_when`, `scope_doc_path`, `criteria` | POST /versions — create a version + its done-when criteria in one call. |
+| POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `track`, `done_when`, `scope_doc_path`, `criteria`, `first_goal` | POST /versions — create a version + its done-when criteria in one call. |
 | POST | `/api/bongos/versions/:id/close` | `archon` | `reason`, `dispositions` | POST /versions/:id/close — the move a version has never had (BV1.R12, task 1003599, goal 1000086, ADR 0250 D5, ADR 0263 §5). |
 | GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: the status dashboard (status.<apex>) fetches this every 60s alongside other public/* surfaces. |
 | POST | `/api/bongos/versions/:id/done-when` | `metic+archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. |

package/docs/module-api-changelog.md

@@ -1813,5 +1813,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.675 with no explicit bump. run 34645751352. (task 1002620)
   1.19.677 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.676 with no explicit bump. run 34650610723. (task 1002620)
+  1.19.678 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.677 with no explicit bump. run 34653458123. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-goals.js

@@ -65,11 +65,17 @@ const MEMBERSHIP_REQUEST_COLS =
 // state R03 exists to prevent, and a second round-trip can fail after the goal
 // lands. Pass null (the normal path) and no admission row is written at all, so
 // the presence of a row always means the gate was actually overridden.
+//
+// IT CAN RUN INSIDE THE CALLER'S TRANSACTION (deps.client), the same seam
+// ensureMaintenanceGoal below already takes and for the same reason: a version's
+// FIRST goal is created by db.createVersion in the transaction that creates the
+// version (task 1003701), and a goal committed on its own connection would
+// survive a rolled-back version create as a goal pointing at nothing.
 async function createGoal(
   { versionId, title, subtitle = null, description = null, scopeModules = [], status = 'open', createdBy = null, categoryId = null, admission = null },
   deps = {}
 ) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const activePool = deps.client || ((deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool);
   const { rows } = await activePool.query(
     `WITH next_order AS (
        SELECT COALESCE(MAX(sort_order) + 1, 0) AS n FROM goals WHERE version_id = $1

package/modules/lifecycle/db-versions.js

@@ -15,6 +15,10 @@ const { pool, withTx } = api;
 const doneWhen = require('./done-when.js');
 const { nonTerminalSql } = require('./task-status');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+// db-goals.js does NOT require this file, so this direction adds no require cycle
+// (fitness pins the count). createVersion needs it to seed a version's FIRST goal
+// in the same transaction — task 1003701.
+const { createGoal } = require('./db-goals.js');
 
 async function listVersions() {
   const { rows } = await pool.query(
@@ -130,10 +134,35 @@ async function versionsWithStatus(status, deps = {}) {
   return rows;
 }
 
-async function createVersion({ id, name, status = 'planning', track = 'product', scopeDocPath = null, doneWhen = null, criteria = [] }) {
+// createVersion — a version, its FIRST GOAL, and its done-when criteria, in one
+// transaction (task 1003701).
+//
+// THE GOAL IS NOT OPTIONAL DECORATION; it closes a chicken-and-egg that made a
+// fresh instance unseedable. `bongos init` creates its version at 'building', and
+// two rules then met in the middle: BV1.R11 refuses a task with no goal_id, and
+// R03 refuses a new goal on a version that is no longer 'planning'. So init could
+// file no task, and could create no goal to file them under — proved against live
+// on 2026-09-07. Creating the version's own first goal WITH the version is the
+// way out that spends no escape hatch: this is not scope GROWTH on a closed
+// version (what R03 guards), it is the version's initial scope, and it exists
+// before the version is visible to anyone.
+//
+// It also fixes the quieter defect underneath. Since ADR 0086 criteria live under
+// goals, and since migration 160 the catch-all goals were created by a one-shot
+// backfill with no trigger behind it — so every version created afterwards got
+// goal-less criteria, and ADR 0183 criteria satisfy themselves off LINKED tasks.
+// Criteria nobody can link a task to can never close. Stamping goal_id here is
+// what gives them something to hang from.
+async function createVersion({ id, name, status = 'planning', track = 'product', scopeDocPath = null, doneWhen = null, criteria = [], firstGoal = null, createdBy = null }, deps = {}) {
   // versions.track is NOT NULL with no DB default (migration 003) — omitting it
   // here made every create 500. An instance's first version is its product
   // track, so that's the default; 'internal' is the platform's own track.
+  //
+  // deps.pool is the module's existing test seam (listVersions, versionProgress):
+  // honoured ONLY under NODE_ENV=test, so production can never be pointed at an
+  // injected pool. It is threaded into withTx so the whole transaction — version,
+  // goal and criteria — runs on it.
+  const txPool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   return withTx(async (client) => {
     const { rows } = await client.query(
       `INSERT INTO versions (id, name, status, track, scope_doc_path, done_when)
@@ -142,21 +171,32 @@ async function createVersion({ id, name, status = 'planning', track = 'product',
       [id, name, status, track, scopeDocPath, doneWhen]
     );
     const version = rows[0];
+    // The first goal. Titled for the version it opens unless the caller names one —
+    // a version's opening scope is the version, until someone splits it. Rides the
+    // SAME client, so a failure anywhere below rolls the goal back with everything
+    // else and never leaves a goal pointing at a version that does not exist.
+    const goal = await createGoal({
+      versionId: id,
+      title: (firstGoal && String(firstGoal.title || '').trim()) || name || id,
+      description: (firstGoal && firstGoal.description) || doneWhen || null,
+      createdBy,
+    }, { client });
     const createdCriteria = [];
     let i = 0;
     for (const c of (criteria || [])) {
       const { rows: cr } = await client.query(
-        `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order)
-              VALUES ($1, $2, $3, $4)
+        `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order, goal_id)
+              VALUES ($1, $2, $3, $4, $5)
          ON CONFLICT (version_id, criterion_id) DO NOTHING
-         RETURNING id, version_id, criterion_id, criterion_md, sort_order, satisfied`,
-        [id, c.criterion_id, c.criterion_md, Number.isFinite(c.sort_order) ? c.sort_order : (i + 1) * 10]
+         RETURNING id, version_id, criterion_id, criterion_md, sort_order, satisfied, goal_id`,
+        [id, c.criterion_id, c.criterion_md, Number.isFinite(c.sort_order) ? c.sort_order : (i + 1) * 10,
+         goal ? goal.id : null]
       );
       if (cr[0]) createdCriteria.push(cr[0]);
       i++;
     }
-    return { version, criteria: createdCriteria };
-  });
+    return { version, goal: goal || null, criteria: createdCriteria };
+  }, { pool: txPool });
 }
 
 // currentBuildingVersionId — the version new work defaults into, or null when

package/modules/lifecycle/routes/versions.js

@@ -103,6 +103,8 @@ module.exports = function buildVersionsRouter() {
       done_when: { type: 'string', maxLength: 8000 },
       scope_doc_path: { type: 'string', maxLength: 256 },
       criteria: { type: 'array', maxItems: 100 },
+      // The version's first goal (task 1003701) — { title?, description? }, both optional.
+      first_goal: { type: 'object' },
     })) return;
     const body = req.body || {};
     const id = String(body.id).trim();
@@ -177,13 +179,23 @@ module.exports = function buildVersionsRouter() {
       });
     }
 
-    let version, created;
+    // The version's FIRST GOAL (task 1003701). Optional and free-form: name it and
+    // the version opens with that goal, omit it and the goal carries the version's
+    // own name. It is created in createVersion's transaction, not here, because a
+    // goal that outlived a rolled-back version create would point at nothing.
+    const fg = body.first_goal && typeof body.first_goal === 'object' ? body.first_goal : null;
+    let version, goal, created;
     try {
-      ({ version, criteria: created } = await db.createVersion({
+      ({ version, goal, criteria: created } = await db.createVersion({
         id, name, status, track,
         doneWhen: body.done_when ?? null,
         scopeDocPath: body.scope_doc_path ?? null,
         criteria,
+        firstGoal: fg,
+        // The creator OWNS the goal (createGoal's rule — created_by plus a 'lead'
+        // member row). Null for an unauthenticated/system create, which is the
+        // migration-160 posture: no owner, Archons act as one.
+        createdBy: (req.builder && req.builder.id) || null,
       }));
     } catch (err) {
       // TOCTOU: the getVersion() pre-check above runs outside the insert
@@ -222,7 +234,11 @@ module.exports = function buildVersionsRouter() {
       }
       throw err;
     }
-    res.status(201).json({ version, criteria: created });
+    // `goal` is returned because a caller that just made a version CANNOT file a
+    // task without one (BV1.R11) and cannot create one afterwards (R03) — so the
+    // id has to come back with the version or the caller is stuck. This is the
+    // half `bongos init` was missing (task 1003701).
+    res.status(201).json({ version, goal: goal || null, criteria: created });
   }, { errorCode: 'create_version_failed' }));
 
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.677",
+  "version": "1.19.678",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.677",
+      "version": "1.19.678",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.677",
+  "version": "1.19.678",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/init.js

@@ -668,8 +668,30 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   if (!vres.ok && vres.status !== 409) {
     throw new Error(`POST /versions failed (${vres.status}): ${JSON.stringify(vres.data)}`);
   }
-  if (vres.status === 409) log(`  • version ${vp.id} already exists — continuing.`);
-  else log(`  ✓ created version ${vp.id} + 1 done-when goal`);
+  // The version's first goal — every task below needs its id (BV1.R11 refuses a
+  // goal-less task, and R03 refuses creating a goal on a version that is already
+  // 'building', which is what versionPayload makes). POST /versions now returns it
+  // alongside the version (task 1003701); on the 409 re-run path the version is
+  // already there, so read its goals back instead.
+  let goalId = vres.ok && vres.data && vres.data.goal ? vres.data.goal.id : null;
+  if (vres.status === 409) {
+    log(`  • version ${vp.id} already exists — continuing.`);
+    const gres = await api('GET', `/api/gds/goals?version=${encodeURIComponent(vp.id)}`);
+    const goals = gres.ok ? (Array.isArray(gres.data) ? gres.data : (gres.data && gres.data.goals) || []) : [];
+    const open = goals.find((g) => g && g.status === 'open' && !g.is_maintenance) || goals.find((g) => g && g.status === 'open');
+    goalId = open ? open.id : null;
+  } else {
+    log(`  ✓ created version ${vp.id} + its first goal`);
+  }
+  // Fail LOUD rather than filing a wave of tasks the server will refuse one by one:
+  // with no goal every POST below returns 400 goal_id_required, and the run would
+  // report a pile of identical failures instead of the single reason behind them.
+  if (goalId == null) {
+    throw new Error(
+      `could not determine a goal for version ${vp.id} — every task needs one (goal_id_required). ` +
+      `The version exists but has no open goal to file under; create one and re-run.`
+    );
+  }
   const criterionId = vp.criteria[0].criterion_id;
 
   // A tracked kickoff/starter task (status ready). Returns true on success.
@@ -681,7 +703,7 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
   const postTask = async (t, extra = {}) => {
     attempted++;
     const res = await api('POST', '/api/gds/tasks', {
-      version_id: vp.id, title: t.title, description: t.description || '', status: 'ready',
+      version_id: vp.id, goal_id: goalId, title: t.title, description: t.description || '', status: 'ready',
       kind: t.kind || 'infra', discipline: t.discipline || 'engineer', source: 'bongos-init', ...extra,
     });
     if (!res.ok) failures.push({ title: t.title, status: res.status, detail: JSON.stringify(res.data) });

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.677'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.678'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/init.mjs

@@ -558,11 +558,21 @@ test('writeConfigs (greenfield, dry-run): mints no README', () => {
 // A fake apiCall that records calls and returns a configured response per path
 // substring (default: 200 ok). Lets us exercise the live seedViaApi branching
 // (POST the request; 404/error → fall back to the manual task) with no server.
+// POST /versions answers with the version's FIRST GOAL since task 1003701, and
+// seedViaApi cannot file a single task without its id (BV1.R11 refuses a task with
+// no goal_id, and R03 refuses creating one on a version that is already
+// 'building'). So the default version response carries one — a stub that omitted
+// it would not be a simpler fixture, it would be a server that cannot be seeded,
+// which is the bug this all fixes. FAKE_GOAL_ID is asserted on the task POSTs.
+const FAKE_GOAL_ID = 4242;
 function fakeApi(responses = []) {
   const calls = [];
   const api = async (method, path, body) => {
     calls.push({ method, path, body });
     for (const [match, res] of responses) if (path.includes(match)) return res;
+    if (path.endsWith('/versions')) {
+      return { ok: true, status: 201, data: { version: { id: (body && body.id) || 'V1' }, goal: { id: FAKE_GOAL_ID, status: 'open' }, criteria: [] } };
+    }
     return { ok: true, status: 200, data: {} };
   };
   api.calls = calls;
@@ -623,6 +633,9 @@ async function runSeedTests() {
     const calls = [];
     const api = async (method, path, body) => {
       calls.push({ method, path, body });
+      if (path.endsWith('/versions')) {
+        return { ok: true, status: 201, data: { version: { id: body.id }, goal: { id: FAKE_GOAL_ID, status: 'open' }, criteria: [] } };
+      }
       if (path.endsWith('/tasks') && /instance look/i.test((body && body.title) || '')) {
         return { ok: false, status: 400, data: { error: 'validation_failed' } };
       }
@@ -639,6 +652,61 @@ async function runSeedTests() {
     assert.match(text, new RegExp(`⚠ filed ${out.created} of ${out.attempted}`), 'summary is a warning with actual-vs-expected counts, not a green check');
   });
 
+  // ── the version's first goal (task 1003701) ──────────────────────────────
+  // `bongos init` could not seed a new instance at all: versionPayload creates the
+  // version at 'building', BV1.R11 refuses a task with no goal_id, and R03 refuses
+  // creating a goal on a version that is no longer 'planning'. Both halves were
+  // proved against live on 2026-09-07 — every starter and kickoff task 400'd.
+
+  await at('seedViaApi: EVERY task POST carries the goal_id the version create returned', async () => {
+    const api = fakeApi();
+    const out = await init.seedViaApi(provSpec({}), { log: () => {}, api });
+    const taskPosts = api.calls.filter((c) => c.path.endsWith('/tasks'));
+    assert.ok(taskPosts.length > 0, 'there are tasks to check');
+    for (const c of taskPosts) {
+      assert.equal(c.body.goal_id, FAKE_GOAL_ID, `${c.body.title} filed under the version's first goal`);
+    }
+    assert.equal(out.failures.length, 0, 'and none of them is refused');
+  });
+
+  await at('seedViaApi: a version create that answers with NO goal fails loudly, before filing anything', async () => {
+    // Fail closed and say the real reason ONCE. Without this every task POST comes
+    // back 400 goal_id_required and the run reports a pile of identical failures
+    // instead of the single cause behind them.
+    const api = fakeApi([['/versions', { ok: true, status: 201, data: { version: { id: 'V1' }, criteria: [] } }]]);
+    await assert.rejects(
+      () => init.seedViaApi(provSpec({}), { log: () => {}, api }),
+      /goal/i,
+      'the failure names the goal, not a task'
+    );
+    assert.equal(api.calls.filter((c) => c.path.endsWith('/tasks')).length, 0, 'nothing was filed');
+  });
+
+  await at('seedViaApi: on a 409 re-run it reads the goal back, preferring an ordinary open goal over the maintenance one', async () => {
+    const api = fakeApi([
+      ['/versions', { ok: false, status: 409, data: { error: 'version_exists' } }],
+      ['/goals', { ok: true, status: 200, data: { goals: [
+        { id: 900, status: 'open', is_maintenance: true },
+        { id: 901, status: 'achieved', is_maintenance: false },
+        { id: 902, status: 'open', is_maintenance: false },
+      ] } }],
+    ]);
+    const out = await init.seedViaApi(provSpec({}), { log: () => {}, api });
+    const taskPosts = api.calls.filter((c) => c.path.endsWith('/tasks'));
+    assert.ok(taskPosts.length > 0);
+    for (const c of taskPosts) assert.equal(c.body.goal_id, 902, 'the ordinary open goal, not the maintenance bucket and not the achieved one');
+    assert.equal(out.failures.length, 0);
+  });
+
+  await at('seedViaApi: a 409 re-run on a version with no open goal fails loudly too', async () => {
+    const api = fakeApi([
+      ['/versions', { ok: false, status: 409, data: { error: 'version_exists' } }],
+      ['/goals', { ok: true, status: 200, data: { goals: [{ id: 900, status: 'archived', is_maintenance: false }] } }],
+    ]);
+    await assert.rejects(() => init.seedViaApi(provSpec({}), { log: () => {}, api }), /goal/i);
+    assert.equal(api.calls.filter((c) => c.path.endsWith('/tasks')).length, 0, 'nothing was filed');
+  });
+
   await at('seedViaApi: no provisioning block → no provisioning POST, topo stays a normal kickoff task', async () => {
     const spec = init.normalizeSpec({ identity: { productName: 'X Co' }, repo: { owner: 'o', name: 'n' },
       firstAdmin: 'x', version: { id: 'V1', name: 'V1', done_when: 'ship' } });

package/tests/version_first_goal.mjs

@@ -0,0 +1,165 @@
+// tests/version_first_goal.mjs
+//
+// A version is created WITH its first goal, and its done-when criteria hang off
+// that goal (task 1003701, goal 1000106).
+//
+// THE BUG. `bongos init` could not seed a new instance at all. Two rules met in
+// the middle, both proved against live cloudbongos.com on 2026-09-07:
+//   • BV1.R11 (task 1003598) — POST /tasks refuses a task with no goal_id, so
+//     every starter and kickoff task 400'd `goal_id_required`.
+//   • R03 (task 1003591) — POST /goals refuses a new goal on a version that is
+//     not 'planning', and versionPayload creates the version at 'building', so
+//     init could not create a goal to file them under either.
+// There is no version-status transition route yet, so init could not create at
+// 'planning', seed, and promote. The way out is the version's OWN first goal,
+// created in the same transaction: that is not scope GROWTH on a closed version
+// (what R03 guards) but the version's initial scope, and it spends none of the
+// R07 Archon admission override that ADR 0250 §3 keeps counted.
+//
+// THE QUIETER DEFECT UNDERNEATH. Since ADR 0086 criteria live under goals, but
+// createVersion inserted done_when_criteria with no goal_id — the catch-all goals
+// came from migration 160's one-shot backfill with no trigger behind it, so every
+// version created after it got goal-less criteria. Since ADR 0183 criteria satisfy
+// themselves off LINKED tasks, a criterion nobody can link a task to can never
+// close. Stamping goal_id here is what gives them something to hang from.
+//
+// DB-FREE, through the module's OWN test seam: createVersion takes deps.pool and
+// honours it only under NODE_ENV=test (the listVersions / versionProgress idiom),
+// threading it into withTx so version, goal and criteria all run on the fake. The
+// fake client answers by statement shape and records every one, which is what lets
+// this pin the SQL's shape AND its order without a Postgres — and the goal INSERT
+// appearing inside the same BEGIN/COMMIT is the proof that createGoal rode the
+// caller's transaction rather than opening its own connection. (The live SQL is
+// exercised against a real database the same way the other write paths are — see
+// the versions_route.mjs note.)
+//
+// Run:  node tests/version_first_goal.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// ── the fake connection ─────────────────────────────────────────────────────
+// Answers each statement by shape and records it. Returning a row for the goal
+// insert matters: createVersion stamps the criteria with `goal.id`, so a stub
+// that answered {rows: []} would silently reproduce the goal-less-criteria bug
+// it is here to catch.
+function fakeDb({ goalRow = { id: 77, title: 'Foundations' } } = {}) {
+  const log = [];
+  const client = {
+    query: async (sql, params) => {
+      log.push({ sql, params });
+      if (/^\s*(BEGIN|COMMIT|ROLLBACK)/i.test(sql)) return { rows: [] };
+      if (/INSERT INTO versions/i.test(sql)) return { rows: [{ id: params[0], name: params[1], status: params[2], track: params[3] }] };
+      if (/INSERT INTO goals/i.test(sql)) return { rows: [goalRow] };
+      if (/INSERT INTO done_when_criteria/i.test(sql)) {
+        return { rows: [{ id: log.length, version_id: params[0], criterion_id: params[1], criterion_md: params[2], sort_order: params[3], goal_id: params[4], satisfied: false }] };
+      }
+      return { rows: [] };
+    },
+    release() {},
+  };
+  return { log, pool: { connect: async () => client } };
+}
+
+// deps.pool is the module's own test seam and is honoured ONLY under NODE_ENV=test,
+// so this line is load-bearing: without it createVersion reaches for the real pool.
+process.env.NODE_ENV = 'test';
+const db = fakeDb();
+const { createVersion } = require('../modules/lifecycle/db-versions.js');
+
+const CRITERIA = [
+  { criterion_id: 'first-loop', criterion_md: 'A task reaches shipped with credits.' },
+  { criterion_id: 'second', criterion_md: 'And a second one does too.' },
+];
+
+console.log('createVersion — the version, its first goal, and its criteria:');
+
+const out = await createVersion({
+  id: 'V1', name: 'Foundations', status: 'building', track: 'product',
+  doneWhen: 'The loop closes.', criteria: CRITERIA, createdBy: 7,
+}, { pool: db.pool });
+
+await t('the version, a goal, and every criterion land in ONE transaction', async () => {
+  const kinds = db.log.map((c) => c.sql.trim().split(/\s+/).slice(0, 3).join(' ').toUpperCase());
+  assert.equal(kinds[0], 'BEGIN', 'opens a transaction');
+  assert.equal(kinds[kinds.length - 1], 'COMMIT', 'and commits it');
+  assert.ok(!db.log.some((c) => /ROLLBACK/i.test(c.sql)), 'nothing rolled back');
+  // A goal committed on its own connection would survive a rolled-back version
+  // create as a goal pointing at a version that does not exist.
+  assert.ok(db.log.some((c) => /INSERT INTO goals/i.test(c.sql)), 'the goal is created here, not by a second round-trip');
+});
+
+await t('the goal is created AFTER the version and BEFORE the criteria', async () => {
+  const at = (re) => db.log.findIndex((c) => re.test(c.sql));
+  const v = at(/INSERT INTO versions/i);
+  const g = at(/INSERT INTO goals/i);
+  const c = at(/INSERT INTO done_when_criteria/i);
+  assert.ok(v >= 0 && g >= 0 && c >= 0, 'all three statements ran');
+  assert.ok(v < g, 'the goal references the version, so the version exists first');
+  assert.ok(g < c, 'the criteria reference the goal, so the goal exists first');
+});
+
+await t('EVERY criterion carries the goal_id — the defect that made criteria uncloseable', async () => {
+  const crits = db.log.filter((c) => /INSERT INTO done_when_criteria/i.test(c.sql));
+  assert.equal(crits.length, CRITERIA.length, 'one insert per criterion');
+  for (const c of crits) {
+    // Assert the STATEMENT, not only the params. goal_id can sit in the insert
+    // list while VALUES still binds a literal NULL — which is this defect exactly,
+    // and a fixture that rebuilds the row out of params cannot see it happen.
+    assert.match(c.sql, /INSERT INTO done_when_criteria \(version_id, criterion_id, criterion_md, sort_order, goal_id\)/,
+      'goal_id is in the insert list');
+    assert.match(c.sql, /VALUES \(\$1, \$2, \$3, \$4, \$5\)/, 'and VALUES BINDS it, rather than a literal NULL');
+    assert.match(c.sql, /RETURNING[\s\S]*goal_id/, 'and the row comes back carrying it');
+    assert.equal(c.params[4], 77, "and it is THIS version's first goal");
+  }
+  for (const c of out.criteria) assert.equal(c.goal_id, 77, 'the returned rows say so too');
+});
+
+await t('the goal is returned, because the caller cannot file a task without its id', async () => {
+  assert.ok(out.goal, 'createVersion returns it');
+  assert.equal(out.goal.id, 77);
+  assert.equal(out.version.id, 'V1');
+});
+
+await t('the goal is titled for the version, and owned by its creator', async () => {
+  const g = db.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[0], 'V1', 'scoped to the version');
+  assert.equal(g.params[1], 'Foundations', 'named after the version by default');
+  assert.equal(g.params[5], 7, 'created_by is the caller — createGoal also makes them a lead');
+  assert.equal(g.params[2], 'The loop closes.', 'described by the version\'s done_when');
+});
+
+await t('an explicit firstGoal overrides the default title and description', async () => {
+  const d2 = fakeDb();
+  await createVersion({ id: 'V2', name: 'Ignored', doneWhen: 'also ignored', criteria: [],
+    firstGoal: { title: 'Project creation', description: 'The picker and the wizard.' } }, { pool: d2.pool });
+  const g = d2.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[1], 'Project creation');
+  assert.equal(g.params[2], 'The picker and the wizard.');
+});
+
+await t('a blank firstGoal title falls back to the version rather than creating an unnamed goal', async () => {
+  const d3 = fakeDb();
+  await createVersion({ id: 'V3', name: 'Third', criteria: [], firstGoal: { title: '   ' } }, { pool: d3.pool });
+  const g = d3.log.find((c) => /INSERT INTO goals/i.test(c.sql));
+  assert.equal(g.params[1], 'Third', 'goals.title is NOT NULL — a blank title must never reach it');
+});
+
+await t('a version with NO criteria still gets its goal (the goal is the point, not the criteria)', async () => {
+  const d4 = fakeDb();
+  const r = await createVersion({ id: 'V4', name: 'Fourth', criteria: [] }, { pool: d4.pool });
+  assert.ok(d4.log.some((c) => /INSERT INTO goals/i.test(c.sql)), 'still created');
+  assert.equal(r.goal.id, 77);
+  assert.equal(r.criteria.length, 0);
+});
+
+console.log(`\nversion_first_goal: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/versions_route.mjs

@@ -32,6 +32,7 @@ const VERSIONS_POST_SCHEMA = {
   done_when: { type: 'string', maxLength: 8000 },
   scope_doc_path: { type: 'string', maxLength: 256 },
   criteria: { type: 'array', maxItems: 100 },
+  first_goal: { type: 'object' },
 };
 
 // ---- the router builds (smoke: imports auth/db/branding/_helpers cleanly) ----
@@ -46,6 +47,17 @@ test('INIT: minimal create (id + name only) passes', () => {
   assert.equal(validate({ id: 'V1', name: 'Prove the loop' }, VERSIONS_POST_SCHEMA), null);
 });
 
+// The version's first goal (task 1003701). init does NOT send one — it takes the
+// default, which names the goal after the version — so the minimal create above
+// staying valid is half the contract, and this is the other half.
+test('INIT: an explicit first_goal object passes', () => {
+  assert.equal(validate({ id: 'V1', name: 'Prove the loop', first_goal: { title: 'Foundations' } }, VERSIONS_POST_SCHEMA), null);
+});
+
+test('BAD: first_goal as a string is refused (it is an object or nothing)', () => {
+  assert.notEqual(validate({ id: 'V1', name: 'n', first_goal: 'Foundations' }, VERSIONS_POST_SCHEMA), null);
+});
+
 test('INIT: full create with criteria array passes', () => {
   const body = {
     id: 'V1',