@bongos/core 1.19.571 → 1.19.572

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.571",
-  "core_contract": "1.19.571",
-  "source_commit": "342ef455a76142077c47deaa4ef6db7b76139f1e",
+  "core_version": "1.19.572",
+  "core_contract": "1.19.572",
+  "source_commit": "31894c826b1cb16600f02046b2e17a09f78f3712",
   "source_ref": "HEAD",
-  "built_at": "2026-09-06T23:07:09.000Z",
+  "built_at": "2026-09-07T00:51:07.099Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 450,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2040,
+    "functional_verbatim": 2042,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2514,
-  "tree_sha256": "c508f7935f6abe6b6bdf02bab8820c895a17b9c1d3c689fab2c0e78ad6ce985b",
+  "file_count": 2516,
+  "tree_sha256": "dc4746621684478bdfcc20dba9ccc094ed1722956378f38939e11ff3f83e35d5",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -392,7 +392,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "2b37686507b5ea701c19a1086352a2f0c84eae46510ef12b3a601c18812610c6"
+      "sha256": "adaa20c8ce6bee76dc289f10929014382aa89d7373f94ddafc84f4c87eeb0ed4"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1812,12 +1812,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "33d4d9b7530ebeebffc8c7200a137f5624b8319ff9a26e8b7b1e3209acb413ae"
+      "sha256": "0a622847ab68980279beba2e1a54813b2393107144f88dd31228fe4dfd248b90"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "9148616a367b2f7486a8f14c0f7ecf9ed367bd552075b15c4f2b0f3dd40712db"
+      "sha256": "60ca0b131c661df16fb993182d2085d0b04ea15a4d91bec4318c3413fb8dc311"
     },
     {
       "path": "docs/architecture.md",
@@ -2692,7 +2692,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "64941aa45c872838ad9b962b98fd750eea92110cfdb9b40bb16b0c57748f09c3"
+      "sha256": "d7acc0617ab16007150c0f733248576e5c285286f22b32ec722fa061748994f9"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5467,7 +5467,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "16c5f2ed9ae4b70a30eb47a4864c4ad6273afbe19e925edcac5f9d965e670f24"
+      "sha256": "31f39ea088b03feb217af4ce2fbf0b4dba0d8dad3e8eec625cf11e0dd4cb4228"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5507,7 +5507,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "c6ab8ace534687d1989e4b192809a373294e539f7fb8624f512fda4ceea884ba"
+      "sha256": "61ed58e2d0dbe9aa0b889d27b6a9c38df024a40bc797f22b0ff766fedf85a9de"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5624,6 +5624,11 @@
       "mode": "0000644",
       "sha256": "0d17971d88c2f75a61a5646325ebab121fd4406cdd39324a1128a5e610ce6d7d"
     },
+    {
+      "path": "modules/lifecycle/migrations/lifecycle_008_goal_version_admissions.sql",
+      "mode": "0000644",
+      "sha256": "4e4099764712b6ac8ad322cb846eb1e4b1118e936d03628e01a6a04adb4d4ebf"
+    },
     {
       "path": "modules/lifecycle/mingle.js",
       "mode": "0000644",
@@ -5682,12 +5687,12 @@
     {
       "path": "modules/lifecycle/routes/goal-route-authz.js",
       "mode": "0000644",
-      "sha256": "c380ad664c18beff53dd50e9bd5ad9ba78c05c18fae182cc0b0cc8ea41ee1a75"
+      "sha256": "5022ec9cdd2ba5087bc0b4607691c21d361f4a4edbf029ff3dea37ade373e890"
     },
     {
       "path": "modules/lifecycle/routes/goals.js",
       "mode": "0000644",
-      "sha256": "9d3079d7f3f610aa5893f02fb4858f73ec98718d6096c423cd52c15d2b30d1ec"
+      "sha256": "d408d89cf736a7d4cdf45ccff44c2038bbc64b13be42dd1b460198dfc8112535"
     },
     {
       "path": "modules/lifecycle/routes/help-requests.js",
@@ -5747,7 +5752,7 @@
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "a825191c1ef406ec4c0eb9455df5b65c5ecf25e23d2b9a9f78eeeae424fa2bf6"
+      "sha256": "5efe819220f9128844793a0c068babcd402860b434aab322fd9a99f8d2d26167"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -7542,12 +7547,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6e8b9fee606ca0b7f97205d2cd7eace56e341a525232e39e3da81e05390da456"
+      "sha256": "439507cc695f5ef93f4fe1aa9a48556b4b9e11a023fa4e60912de1ed8befc5ee"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5a2e1030453e82c8b52575c904e816e833343788d90e07c5d1946f15207fe8a4"
+      "sha256": "bf5fe42d980095754ea4b13501ede3a559376dae4127a99915767ba4be0c27d2"
     },
     {
       "path": "public-docs/index.html",
@@ -9247,7 +9252,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a92eeea78188a9a1658c5d6dc928062720189bf23511e2ca50d9a4eac5ef91ef"
+      "sha256": "be71a580784409ac5e4507201fbbf9915e16f0682098e3b9e98ec49a0af98216"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10329,6 +10334,11 @@
       "mode": "0000644",
       "sha256": "3e157d5bf44370e4935b70203fe59e40cf9120d12c472f24ed7bd85cb33cbe91"
     },
+    {
+      "path": "tests/goal_admission_override.mjs",
+      "mode": "0000644",
+      "sha256": "94b378fb96bbbb6285b61c4d00827f57e0b29d64d9036576670ffaf8ca233239"
+    },
     {
       "path": "tests/goal_advisory.mjs",
       "mode": "0000644",
@@ -10342,7 +10352,7 @@
     {
       "path": "tests/goal_category.mjs",
       "mode": "0000644",
-      "sha256": "05d46d4dcfd3a3b21ef0fc258263081cf4e624bdef4348daf84a90da589387c3"
+      "sha256": "dbdfd351d5edc3ac6adcb1a34e072fab0a8db9669030d7476bbf18aa1e81540d"
     },
     {
       "path": "tests/goal_category_ui.mjs",
@@ -10367,7 +10377,7 @@
     {
       "path": "tests/goal_create_version_gate.mjs",
       "mode": "0000644",
-      "sha256": "addd9fe7179236d24c316923fd47a60947c1a34f9e01eb1a4d47faa49b4fa18f"
+      "sha256": "28da055ccad13b327135dce6292df9c6bc53e2589648e0a4361ada0ddd21b863"
     },
     {
       "path": "tests/goal_criterion_confirm_ui.mjs",
@@ -10422,7 +10432,7 @@
     {
       "path": "tests/goal_tier.mjs",
       "mode": "0000644",
-      "sha256": "7d8c1b8300c99be22b42ff25e8ce25e25b5af28cd29c314f9aee7ddee11fc0d5"
+      "sha256": "3c420d28341a6e5aaeb5d4af978e72acefec3c9bd7d97f66fd11a72517118606"
     },
     {
       "path": "tests/goal_wall_proof.mjs",

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

@@ -49,7 +49,7 @@ export interface GetGithubRepoResponse { ok: boolean; repo: unknown; private_dep
 export interface GetGithubReposResponse { repos: unknown }
 export interface GetGoalsIdConflictsResponse { ok: boolean; goal_id: unknown; conflicts: unknown; cross_goals_considered: unknown }
 export interface GetGoalsIdRequestsResponse { requests: unknown }
-export interface GetGoalsIdResponse { goal: unknown; members: unknown; criteria: unknown; dependencies: unknown; criterionless_task_count: unknown }
+export interface GetGoalsIdResponse { goal: unknown; members: unknown; criteria: unknown; dependencies: unknown; criterionless_task_count: unknown; admitted: unknown }
 export interface GetGoalsResponse { goals: unknown }
 export interface GetGoalsRollupsResponse { rollups: unknown }
 export interface GetGovernmentAssignmentsResponse { assignments: unknown }
@@ -278,8 +278,8 @@ export interface PostGoalsIdTransferRequest { builder_id?: StringifiableId }
 export interface PostGoalsIdTransferResponse { ok: boolean; goal: unknown; changed: boolean }
 export interface PostGoalsReorderRequest { version_id: string; ordered_ids: number[] }
 export interface PostGoalsReorderResponse { ok: boolean; goals: unknown }
-export interface PostGoalsRequest { version_id: string; title: string; subtitle?: string; description?: string; scope_modules?: string[]; succeeds_goal_id?: number; category_id?: number }
-export interface PostGoalsResponse { ok: boolean; goal: unknown; succeeds_goal_id: unknown; category_advisory: unknown }
+export interface PostGoalsRequest { version_id: string; title: string; subtitle?: string; description?: string; scope_modules?: string[]; succeeds_goal_id?: number; category_id?: number; admit_reason?: string }
+export interface PostGoalsResponse { ok: boolean; goal: unknown; succeeds_goal_id: unknown; category_advisory: unknown; admitted: unknown }
 export interface PostGovernmentAssignmentsRequest { builder_id: number; rank_key: string }
 export interface PostGovernmentBoardItemsItemIdVotesRequest { direction: string; reason_md?: string; section_key?: string }
 export interface PostGovernmentBoardItemsRequest { subject_type: string; proposal: Record<string, unknown>; rationale_md?: string; acknowledge_self_removal?: boolean }

package/docs/api/openapi.json

@@ -16955,14 +16955,16 @@
           "members": {},
           "criteria": {},
           "dependencies": {},
-          "criterionless_task_count": {}
+          "criterionless_task_count": {},
+          "admitted": {}
         },
         "required": [
           "goal",
           "members",
           "criteria",
           "dependencies",
-          "criterionless_task_count"
+          "criterionless_task_count",
+          "admitted"
         ]
       },
       "GetGoalsResponse": {
@@ -20325,6 +20327,11 @@
           "category_id": {
             "type": "integer",
             "minimum": 1
+          },
+          "admit_reason": {
+            "type": "string",
+            "minLength": 8,
+            "maxLength": 500
           }
         },
         "required": [
@@ -20341,13 +20348,15 @@
           },
           "goal": {},
           "succeeds_goal_id": {},
-          "category_advisory": {}
+          "category_advisory": {},
+          "admitted": {}
         },
         "required": [
           "ok",
           "goal",
           "succeeds_goal_id",
-          "category_advisory"
+          "category_advisory",
+          "admitted"
         ]
       },
       "PostGovernmentAssignmentsRequest": {

package/docs/api-reference.md

@@ -226,7 +226,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/goals` | `any-builder` | — | GET /goals?version=&status= — list goals (read). |
-| POST | `/api/bongos/goals` | `metic+archon` | `version_id`, `title`, `subtitle`, `description`, `scope_modules`, `succeeds_goal_id`, `category_id` | POST /goals — create a goal. |
+| POST | `/api/bongos/goals` | `metic+archon` | `version_id`, `title`, `subtitle`, `description`, `scope_modules`, `succeeds_goal_id`, `category_id`, `admit_reason` | POST /goals — create a goal. |
 | GET | `/api/bongos/goals/:id` | `any-builder` | — | GET /goals/:id — one goal with its members + linked criteria (read). |
 | PATCH | `/api/bongos/goals/:id` | `any-builder` | — | PATCH /goals/:id — correct a goal's own title/subtitle/description (tasks 1003102, 1003224). |
 | PATCH | `/api/bongos/goals/:id/accepting-requests` | `any-builder` | — | PATCH /goals/:id/accepting-requests { accepting_requests } — a private goal's lead closes or re-opens it to join-requests (task 1002971, … |

package/docs/module-api-changelog.md

@@ -1591,5 +1591,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.569 with no explicit bump. run 34060442118. (task 1002620)
   1.19.571 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.570 with no explicit bump. run 34065943703. (task 1002620)
+  1.19.572 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.571 with no explicit bump. run 34071078624. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-goals.js

@@ -49,8 +49,15 @@ const MEMBERSHIP_REQUEST_COLS =
 // atomically. createdBy NULL (system-attributed, e.g. the migration-160 default
 // goals) inserts no member — those goals have no owner; Archons act as one.
 
+// `admission` (BV1.R07, task 1003594) is the R03 escape valve's record: when an
+// Archon admits this goal into a BUILDING version, the who/why row rides in the
+// SAME statement as the goal insert. Atomic on purpose — a goal that skipped the
+// scope gate with no surviving record of who waved it through is precisely the
+// 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.
 async function createGoal(
-  { versionId, title, subtitle = null, description = null, scopeModules = [], status = 'open', createdBy = null, categoryId = null },
+  { 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;
@@ -64,13 +71,49 @@ async function createGoal(
      ), first_lead AS (
        INSERT INTO goal_members (goal_id, builder_id, membership_kind)
        SELECT g.id, $6::bigint, 'lead' FROM g WHERE $6::bigint IS NOT NULL
+     ), admitted AS (
+       INSERT INTO lifecycle_goal_version_admissions (goal_id, version_id, admitted_by, reason)
+       SELECT g.id, g.version_id, $9::bigint, $10::text FROM g WHERE $9::bigint IS NOT NULL
      )
      SELECT * FROM g`,
-    [versionId, title, description, scopeModules, status, createdBy, subtitle, categoryId]
+    [versionId, title, description, scopeModules, status, createdBy, subtitle, categoryId,
+     admission ? admission.admittedBy : null, admission ? admission.reason : null]
   );
   return rows[0];
 }
 
+// listVersionAdmissions (BV1.R07, task 1003594) — every goal admitted into ONE
+// version, newest first. ADR 0250 §3: "the overrides are counted and shown on the
+// version" — a visible counter is what keeps the exception honest, because an
+// override nobody can see is just a slower version of having no rule. Returns []
+// for the overwhelmingly common case of a version whose scope nobody widened.
+async function listVersionAdmissions(versionId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT a.goal_id, a.version_id, a.admitted_by, a.reason, a.created_at, g.title AS goal_title
+       FROM lifecycle_goal_version_admissions a
+       JOIN goals g ON g.id = a.goal_id
+      WHERE a.version_id = $1
+      ORDER BY a.created_at DESC`,
+    [versionId]
+  );
+  return rows;
+}
+
+// getGoalAdmission (BV1.R07, task 1003594) — the override record for ONE goal, or
+// null when the goal was created normally. Null is the overwhelmingly common
+// answer and is not an absence of data: it is the positive fact "this goal did
+// not skip the scope gate".
+async function getGoalAdmission(goalId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT goal_id, version_id, admitted_by, reason, created_at
+       FROM lifecycle_goal_version_admissions WHERE goal_id = $1`,
+    [goalId]
+  );
+  return rows[0] ?? null;
+}
+
 
 async function getGoal(id, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
@@ -807,6 +850,7 @@ module.exports = {
   createGoal,
   createMembershipRequest,
   getGoal,
+  getGoalAdmission,
   getGoalDependencies,
   getGoalMember,
   getMembershipRequest,
@@ -818,6 +862,7 @@ module.exports = {
   listGoals,
   listInboxFor,
   listPendingRequestsForGoal,
+  listVersionAdmissions,
   removeGoalMember,
   reorderGoals,
   requestClaimRelease,

package/modules/lifecycle/db.js

@@ -72,6 +72,8 @@ const {
   createGoal,
   createMembershipRequest,
   getGoal,
+  getGoalAdmission,
+  listVersionAdmissions,
   getGoalDependencies,
   getGoalMember,
   getMembershipRequest,
@@ -217,6 +219,8 @@ module.exports = {
   createVersion,
   createGoal,
   getGoal,
+  getGoalAdmission,
+  listVersionAdmissions,
   getGoalDependencies,
   listGoals,
   reorderGoals,

package/modules/lifecycle/migrations/lifecycle_008_goal_version_admissions.sql

@@ -0,0 +1,51 @@
+-- lifecycle_008_goal_version_admissions.sql — the R07 escape valve for R03
+-- (task 1003594, goal 1000086, ADR 0250 D1).
+--
+-- WHY THIS TABLE EXISTS. BV1.R03 (task 1003591) closed a version's goal set the
+-- moment the version starts building: new goals belong on the `planning` version.
+-- That rule is right and it is also absolute, which is a problem — an instance
+-- with no planning version cannot create a goal at all, and a genuinely urgent
+-- goal has nowhere to go. R07 is the valve: an Archon may admit ONE named goal
+-- into a building version and must say why.
+--
+-- PER-GOAL, NEVER A BLANKET UNLOCK. `goal_id` is the PRIMARY KEY, so an admission
+-- is a fact about one goal and cannot be widened into "this version is open
+-- again". There is deliberately no version-level switch here — a row per decision
+-- is what makes the scope growth auditable after the fact, which is the whole
+-- reason R03 exists (BONGOS-V1 reached 64 goals with nobody deciding to widen it).
+--
+-- THE ROW IS THE RECORD. reason is NOT NULL because an override with no stated
+-- cause is indistinguishable from the rule not existing; six weeks later the only
+-- question anyone asks is "why is this goal here", and the answer has to be in
+-- the row. admitted_by is the actor (an Archon — enforced at the route, since
+-- rank is a live DB read and pinning it here would freeze it at write time), and
+-- created_at is when. Together: the goal, the actor, the reason, the timestamp.
+--
+-- WRITTEN ONLY WHEN THE OVERRIDE ACTUALLY DID WORK — i.e. the version was
+-- `building`. A goal created normally on a planning version has no row, so the
+-- presence of a row always means "this goal skipped the scope gate", never
+-- "someone passed a flag that changed nothing".
+--
+-- ON DELETE CASCADE: the admission is a fact ABOUT the goal and is meaningless
+-- without it. A deleted goal's override record is not history worth orphaning.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed so fitness check 11 permits it (ADR 0083
+-- §Decision #5) — the lifecycle_004..007 convention. It only REFERENCES the core
+-- `goals` / `builders` tables; a module migration may not ALTER them.
+
+CREATE TABLE IF NOT EXISTS lifecycle_goal_version_admissions (
+  goal_id      bigint PRIMARY KEY REFERENCES goals(id) ON DELETE CASCADE,
+
+  -- Denormalised from goals.version_id ON PURPOSE: the question this table
+  -- answers is "which versions had their scope widened, and why", and a goal can
+  -- be carried forward to another version later. The admission belongs to the
+  -- version that was building AT THE TIME.
+  version_id   text NOT NULL REFERENCES versions(id),
+
+  admitted_by  bigint NOT NULL REFERENCES builders(id),
+  reason       text NOT NULL,
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_lifecycle_goal_admissions_version
+  ON lifecycle_goal_version_admissions (version_id);

package/modules/lifecycle/routes/goal-route-authz.js

@@ -120,7 +120,13 @@ function authorizeGoalCreate({ version, override = false }) {
       message: `Version '${version.id}' is already building — its goal set is closed. Scope this goal onto the planning version instead, or ask an Archon to admit it with a reason.`,
     } };
   }
-  return { ok: true };
+  // `overrideApplied` says whether the override DID WORK, not whether one was
+  // offered (BV1.R07, task 1003594). An admit_reason on a planning version is a
+  // no-op — the create was always going to succeed — and recording it would file
+  // a "this goal skipped the scope gate" row against a goal that skipped nothing.
+  // It is returned from here rather than recomputed at the route because this is
+  // the ONE place allowed to reason about version.status; the route renders.
+  return { ok: true, overrideApplied: override === true && version.status !== 'planning' };
 }
 function authorizeGoalTaskCreate({ goal, version, isMember, builderRank, touches }) {
   if (!goal) {

package/modules/lifecycle/routes/goals.js

@@ -82,6 +82,11 @@ module.exports = function buildGoalsRouter() {
       // task 1003275 — the human category. ADVISORY: absent is legal (it becomes a
       // prompt, never a refusal), and no gate below reads it.
       category_id: { type: 'integer', min: 1 },
+      // BV1.R07 (task 1003594) — the Archon admission. Its PRESENCE is the
+      // override; there is no boolean beside it, so an override cannot be
+      // requested without stating a cause. minLength 8 because 'ok' / '.' is not
+      // a reason, and the row is the only place the why survives.
+      admit_reason: { type: 'string', minLength: 8, maxLength: 500 },
     })) return;
 
     const scopeModules = req.body.scope_modules || [];
@@ -96,6 +101,16 @@ module.exports = function buildGoalsRouter() {
     if (scopeIncludesProtected(scopeModules) && req.builder.rank !== 'archon') {
       return res.fail('archon_required_for_protected_scope', { status: 403, message: 'A goal scoped to a protected module can only be created by an Archon.' });
     }
+    // BV1.R07 (task 1003594, goal 1000086): admitting a goal into a building
+    // version is an Archon decision, so the field is refused by RANK before the
+    // version is even fetched — a Metic must not learn whether the override
+    // would have worked. Checked here rather than folded into the pure gate
+    // because rank is a live DB read on req.builder (ADR 0016), never a value
+    // the caller supplies.
+    const admitReason = (req.body.admit_reason || '').trim() || null;
+    if (admitReason !== null && req.builder.rank !== 'archon') {
+      return res.fail('archon_required_for_admission', { status: 403, message: 'Only an Archon may admit a goal into a version that is already building.' });
+    }
 
     try {
       const version = await db.getVersion(req.body.version_id);
@@ -103,7 +118,7 @@ module.exports = function buildGoalsRouter() {
       // fetched and then discarded after the null check — its status was never
       // read, so a goal could be added to a version that had been building for
       // months. The ordered, DB-free gate answers all of it, including the 404.
-      const versionDecision = authorizeGoalCreate({ version });
+      const versionDecision = authorizeGoalCreate({ version, override: admitReason !== null });
       if (!versionDecision.ok) {
         return res.status(versionDecision.status).json(versionDecision.body);
       }
@@ -123,6 +138,14 @@ module.exports = function buildGoalsRouter() {
       if (categoryId !== null && !(await goalCategory.getCategory(categoryId))) {
         return res.fail('category_not_found', 404, { message: 'No such category. List them at GET /work-categories, or create one with POST /work-categories.' });
       }
+      // The admission row is written ONLY when the gate says the override
+      // actually opened it (see authorizeGoalCreate) — an admit_reason on a
+      // planning version changed nothing and must not be recorded as a skipped
+      // gate. It rides inside createGoal's statement so the goal and its
+      // justification land together or not at all.
+      const admission = versionDecision.overrideApplied
+        ? { admittedBy: req.builder.id, reason: admitReason }
+        : null;
       const goal = await db.createGoal({
         versionId: req.body.version_id,
         title: req.body.title,
@@ -130,6 +153,7 @@ module.exports = function buildGoalsRouter() {
         scopeModules,
         createdBy: req.builder.id,
         categoryId,
+        admission,
       });
       // Stamp the predecessor's succeeded_by pointer at the new goal (the lineage).
       if (succeedsId != null) {
@@ -144,7 +168,11 @@ module.exports = function buildGoalsRouter() {
           category_advisory = goalCategory.adviseCategory({ categoryId, categories: await goalCategory.listCategories() });
         } catch (_) { /* fail-open — advice only */ }
       }
-      return res.status(201).json({ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory });
+      // `admitted` is null on every normal create. Non-null says the goal was
+      // waved into a building version, by whom and why — the caller should not
+      // have to re-read the goal to find out whether their override took effect.
+      const admitted = admission ? await db.getGoalAdmission(goal.id) : null;
+      return res.status(201).json({ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted });
     } catch (err) {
       log.error('[gds] POST /goals', err);
       return res.fail('goal_create_failed', { status: 500, message: 'internal error' });
@@ -257,7 +285,7 @@ module.exports = function buildGoalsRouter() {
     try {
       const goal = await db.getGoal(id);
       if (!goal) return res.fail('goal_not_found', 404);
-      const [members, criteria, dependencies, criterionless_task_count] = await Promise.all([
+      const [members, criteria, dependencies, criterionless_task_count, admitted] = await Promise.all([
         db.listGoalMembers(id),
         db.listCriteriaForGoal(id),
         db.getGoalDependencies(id),  // task 1761 — prerequisite goals + satisfied state
@@ -265,11 +293,16 @@ module.exports = function buildGoalsRouter() {
         // page already renders, so a builder sees the gap without waiting for
         // the create-time advisory to catch the next task.
         db.countTasksWithoutCriterionLink(id),
+        // BV1.R07 (task 1003594): null on every normal goal. Non-null is the
+        // record that this goal was admitted into a building version — the
+        // override is worthless as an audit trail if reading the goal never
+        // shows it.
+        db.getGoalAdmission(id),
       ]);
       const byId = await goalCategory.categoryIndex();
       return res.json({
         goal: goalCategory.decorateGoalCategory(decorateGoalScope(goal), byId),
-        members, criteria, dependencies, criterionless_task_count,
+        members, criteria, dependencies, criterionless_task_count, admitted,
       });
     } catch (err) {
       log.error('[gds] GET /goals/:id', err);

package/modules/lifecycle/routes/versions.js

@@ -76,9 +76,17 @@ module.exports = function buildVersionsRouter() {
   router.get('/versions/:id/progress', asyncHandler('GET /versions/:id/progress', async (req, res) => {
     const versionId = String(req.params.id || '').trim();
     if (!versionId) return res.fail('version_id_required', 400);
-    const progress = await doneWhen.criterionProgress(versionId);
+    // BV1.R07 (task 1003594) — ADR 0250 §3: "the overrides are counted and shown
+    // on the version". The scope gate's exceptions ride the aggregate the status
+    // dashboard already reads, rather than a route nobody would think to call.
+    // `admissions` is [] for a version whose scope nobody widened, which is the
+    // answer for every version that has never needed the valve.
+    const [progress, admissions] = await Promise.all([
+      doneWhen.criterionProgress(versionId),
+      db.listVersionAdmissions(versionId),
+    ]);
     res.set('Cache-Control', 'public, max-age=60');
-    res.json(progress);
+    res.json({ ...progress, admissions, admission_count: admissions.length });
   }, { message: false, errorCode: 'progress_failed' }));
 
   // POST /versions — create a version + its done-when criteria in one call. The

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.571",
+  "version": "1.19.572",
   "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/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // 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.571'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.572'; // 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/goal_admission_override.mjs

@@ -0,0 +1,179 @@
+// tests/goal_admission_override.mjs — the R03 escape valve: an Archon admits ONE
+// named goal into a building version, and must say why (BV1.R07, task 1003594,
+// goal 1000086, ADR 0250 D1).
+//
+// WHAT R03 LEFT BEHIND. BV1.R03 closed a version's goal set the moment the
+// version starts building. Correct, and absolute: an instance whose only versions
+// are `building` cannot create a goal at all — which is exactly the state
+// cloudbongos.com was in when this task was claimed. R07 is the valve, and the
+// thing that makes it a valve rather than a hole is that every use leaves a row
+// naming the goal, the actor, the reason and the time.
+//
+// The gate stays pure and DB-free (the authorizeGoalTaskCreate precedent), so the
+// decision half is exercised here without a database. The route half is pinned by
+// reading the source — the same technique goal_create_version_gate.mjs uses — so
+// the wiring cannot silently come undone.
+//
+// Run:  node --test tests/goal_admission_override.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { authorizeGoalCreate } = require('../modules/lifecycle/routes/goal-route-authz.js');
+
+const V = (status) => ({ id: 'BONGOS-V1', status });
+const decide = (version, override) => authorizeGoalCreate({ version, override });
+
+const routeSrc = () => readFileSync(new URL('../modules/lifecycle/routes/goals.js', import.meta.url), 'utf8');
+const postGoals = () => {
+  const src = routeSrc();
+  const start = src.indexOf("router.post('/goals'");
+  assert.notEqual(start, -1, 'POST /goals must exist');
+  return src.slice(start, src.indexOf('router.', start + 20));
+};
+
+// ---- the valve opens, and says that it opened ------------------------------
+
+test('an override admits a building version', () => {
+  assert.equal(decide(V('building'), true).ok, true);
+});
+
+test('overrideApplied distinguishes "it worked" from "it was offered"', () => {
+  // The row must mean "this goal skipped the scope gate". On a planning version
+  // the create was always going to succeed, so the override did nothing and
+  // recording it would libel a perfectly normal goal.
+  assert.equal(decide(V('building'), true).overrideApplied, true, 'building: the override did the work');
+  assert.equal(decide(V('planning'), true).overrideApplied, false, 'planning: nothing to override');
+  assert.equal(decide(V('planning')).overrideApplied, false, 'no override offered at all');
+});
+
+test('a refusal carries no overrideApplied claim', () => {
+  // ok:false has no admission story; asserting the field is absent stops a caller
+  // reading `.overrideApplied` off a rejection and getting a useful-looking false.
+  const d = decide(V('building'));
+  assert.equal(d.ok, false);
+  assert.equal('overrideApplied' in d, false);
+});
+
+// ---- and it stays a valve, not a hole --------------------------------------
+
+test('the override never reopens closed history', () => {
+  for (const status of ['shipped', 'paused', '', null, undefined]) {
+    assert.equal(decide(V(status), true).ok, false, `'${String(status)}' must stay closed`);
+    assert.equal(decide(V(status), true).body.error, 'version_closed');
+  }
+});
+
+test('only a literal true overrides — a JSON body cannot coerce its way in', () => {
+  for (const v of ['yes', 1, {}, [], 'true']) {
+    assert.equal(decide(V('building'), v).ok, false);
+  }
+});
+
+// ---- the route: rank, reason, and the record -------------------------------
+
+test('admit_reason is Archon-only, refused by rank before the version is read', () => {
+  const body = postGoals();
+  assert.match(body, /archon_required_for_admission/);
+  assert.match(body, /req\.builder\.rank !== 'archon'/);
+  // Ordering matters: the rank refusal sits above the getVersion call, so a Metic
+  // never learns whether the override would have worked on this version.
+  assert.ok(
+    body.indexOf('archon_required_for_admission') < body.indexOf('db.getVersion'),
+    'the rank check must precede the version fetch'
+  );
+});
+
+test('the override cannot be requested without a reason', () => {
+  const body = postGoals();
+  // There is no boolean flag beside admit_reason — its presence IS the request,
+  // so "override with no cause" is unrepresentable rather than merely refused.
+  assert.equal(/admit(_reason)?\s*:\s*\{\s*type:\s*'boolean'/.test(body), false);
+  assert.match(body, /admit_reason:\s*\{\s*type:\s*'string',\s*minLength:\s*[1-9]/,
+    'a non-empty minimum — "." is not a reason');
+  assert.match(body, /override:\s*admitReason !== null/,
+    'the reason is what opens the gate');
+});
+
+test('whitespace is not a reason', () => {
+  assert.match(postGoals(), /req\.body\.admit_reason \|\| ''\)\.trim\(\) \|\| null/);
+});
+
+test('the record is written from the gate\'s verdict, not a second status read', () => {
+  const body = postGoals();
+  assert.match(body, /versionDecision\.overrideApplied/);
+  assert.equal(/version\.status\s*[=!]==/.test(body), false,
+    'one place reasons about version status, and it is the gate');
+});
+
+test('goal and justification land in ONE statement — no goal without its reason', () => {
+  const db = readFileSync(new URL('../modules/lifecycle/db-goals.js', import.meta.url), 'utf8');
+  const fn = db.slice(db.indexOf('async function createGoal'), db.indexOf('async function getGoalAdmission'));
+  assert.match(fn, /INSERT INTO lifecycle_goal_version_admissions/,
+    'the admission insert rides inside createGoal');
+  assert.ok(
+    fn.indexOf('INSERT INTO lifecycle_goal_version_admissions') < fn.indexOf('SELECT * FROM g`'),
+    'as a CTE in the same query, so it cannot fail after the goal has landed'
+  );
+  assert.match(fn, /WHERE \$9::bigint IS NOT NULL/,
+    'and writes nothing on the normal path');
+});
+
+test('the row carries the goal, the actor, the reason and the time', () => {
+  const sql = readFileSync(
+    new URL('../modules/lifecycle/migrations/lifecycle_008_goal_version_admissions.sql', import.meta.url), 'utf8');
+  for (const col of ['goal_id', 'admitted_by', 'reason', 'created_at']) {
+    assert.match(sql, new RegExp(`\\b${col}\\b`), `the done-when names ${col}`);
+  }
+  assert.match(sql, /reason\s+text NOT NULL/, 'an override with no stated cause is not an override');
+  assert.match(sql, /goal_id\s+bigint PRIMARY KEY/,
+    'per-goal, never a blanket unlock — one row per goal, and no version-level switch');
+  const tables = [...sql.matchAll(/CREATE TABLE IF NOT EXISTS (\w+)/g)].map((m) => m[1]);
+  assert.deepEqual(tables, ['lifecycle_goal_version_admissions'],
+    'exactly one table, keyed by goal — no second, version-level unlock switch beside it');
+});
+
+test('a module migration may reference core tables but never alter them', () => {
+  const sql = readFileSync(
+    new URL('../modules/lifecycle/migrations/lifecycle_008_goal_version_admissions.sql', import.meta.url), 'utf8');
+  assert.equal(/ALTER TABLE/i.test(sql), false, 'ADR 0083 §Decision #5');
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS lifecycle_/, 'module-owned tables carry the module prefix');
+});
+
+// ---- the record is legible afterwards --------------------------------------
+
+test('reading a goal shows whether it was admitted', () => {
+  const src = routeSrc();
+  const start = src.indexOf("router.get('/goals/:id'");
+  assert.notEqual(start, -1);
+  const body = src.slice(start, src.indexOf('router.', start + 20));
+  assert.match(body, /db\.getGoalAdmission\(id\)/);
+  assert.match(body, /admitted/, 'and returns it — an audit trail nobody can read is not one');
+});
+
+test('the create response says whether the override took effect', () => {
+  assert.match(postGoals(), /admitted \}\);/);
+});
+
+// ---- ADR 0250 §3: the exception is counted, or it is not an exception --------
+
+test('the version aggregate carries the override count', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/routes/versions.js', import.meta.url), 'utf8');
+  const start = src.indexOf("router.get('/versions/:id/progress'");
+  assert.notEqual(start, -1);
+  const body = src.slice(start, src.indexOf('router.', start + 20));
+  assert.match(body, /db\.listVersionAdmissions\(versionId\)/);
+  assert.match(body, /admission_count: admissions\.length/,
+    'ADR 0250: an override that leaves no visible trace is a slower version of no rule');
+});
+
+test('the admissions query is scoped to one version and names the goal', () => {
+  const db = readFileSync(new URL('../modules/lifecycle/db-goals.js', import.meta.url), 'utf8');
+  const fn = db.slice(db.indexOf('async function listVersionAdmissions'), db.indexOf('// getGoalAdmission'));
+  assert.match(fn, /WHERE a\.version_id = \$1/, 'one version, not the whole ledger');
+  assert.match(fn, /g\.title AS goal_title/, 'a count with no goal names is not reviewable');
+});

package/tests/goal_category.mjs

@@ -169,7 +169,7 @@ test('the advisory is advice on a 201, never a refusal', () => {
   // and never fails the create over it (best-effort, wrapped in try).
   const routes = read('modules', 'lifecycle', 'routes', 'goals.js');
   assert.match(routes, /category_advisory = goalCategory\.adviseCategory/);
-  assert.match(routes, /res\.status\(201\)\.json\(\{ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory \}\)/,
+  assert.match(routes, /res\.status\(201\)\.json\(\{ ok: true, goal, succeeds_goal_id: succeedsId, category_advisory, admitted \}\)/,
     'it rides the 201 — advice appended to a request that already succeeded');
 });
 

package/tests/goal_create_version_gate.mjs

@@ -30,7 +30,8 @@ const decide = (version, override) => authorizeGoalCreate({ version, override })
 // ---- the truth table --------------------------------------------------------
 
 test('planning accepts — that is what a planning version is for', () => {
-  assert.deepEqual(decide(V('planning')), { ok: true });
+  // overrideApplied false: nothing was overridden, the version was simply open.
+  assert.deepEqual(decide(V('planning')), { ok: true, overrideApplied: false });
 });
 
 test('building refuses with a named 409 an agent can act on', () => {
@@ -77,8 +78,8 @@ test('an unrecognised status is NOT described as shipped', () => {
 
 // ---- the override seam (R07 is not built yet) -------------------------------
 
-test('override admits a building version — the R07 seam, already shaped', () => {
-  assert.deepEqual(decide(V('building'), true), { ok: true });
+test('override admits a building version — the R07 seam, now wired (task 1003594)', () => {
+  assert.deepEqual(decide(V('building'), true), { ok: true, overrideApplied: true });
 });
 
 test('override does NOT reopen a shipped version', () => {
@@ -120,7 +121,9 @@ test('POST /goals consults the gate and returns its exact status + body', () =>
   const start = src.indexOf("router.post('/goals'");
   assert.notEqual(start, -1);
   const body = src.slice(start, src.indexOf('router.', start + 20));
-  assert.match(body, /const versionDecision = authorizeGoalCreate\(\{ version \}\);/);
+  // BV1.R07 (task 1003594) wired the override argument in; the route still only
+  // renders whatever the gate decides.
+  assert.match(body, /const versionDecision = authorizeGoalCreate\(\{ version, override: [^)]*\}\);/);
   assert.match(body, /return res\.status\(versionDecision\.status\)\.json\(versionDecision\.body\);/,
     'the route renders the decision, it does not re-derive one');
   assert.equal(/version\.status\s*[=!]==/.test(body), false,

package/tests/goal_tier.mjs

@@ -69,7 +69,9 @@ await test('createGoal: INSERT binds all six fields in order and returns the row
   // title, and task 1003275 appended `category_id` as $8 the same way, so $1–$6
   // keep the positions this test has always pinned. New goal fields go on the
   // END of the bind list for exactly this reason.
-  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42, null, null],
+  // $9/$10 are the BV1.R07 admission (task 1003594) — null on the normal path,
+  // where nothing overrode the version scope gate.
+  assert.deepEqual(ins.params, ['BONGOS-V1', 'Goal hierarchy', 'desc', ['gds-core'], 'open', 42, null, null, null, null],
     'version_id, title, description, scope_modules, status, created_by, then subtitle, then category_id — in that order');
   assert.match(ins.sql, /RETURNING/, 'returns the row, not just inserts');
 });
@@ -91,7 +93,7 @@ await test('createGoal: defaults — null description/createdBy, empty scope, op
   const pool = fakePool((s) => (/INSERT INTO goals/.test(s) ? { rows: [GOAL_ROW] } : null));
   await createGoal({ versionId: 'V1', title: 'general' }, { pool });
   const ins = find(pool.queries, /INSERT INTO goals/);
-  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null, null, null],
+  assert.deepEqual(ins.params, ['V1', 'general', null, [], 'open', null, null, null, null, null],
     'unspecified fields fall back to null / [] / open — subtitle ($7) and category_id ($8) default to null too');
 });