@bongos/core 1.19.587 → 1.19.588

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.587",
-  "core_contract": "1.19.587",
-  "source_commit": "cd407ba54d0bdbe3638949084ba731c21179c811",
+  "core_version": "1.19.588",
+  "core_contract": "1.19.588",
+  "source_commit": "1833a4d18085bddf05b12c89aea4381e5ac5207e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T00:16:55.401Z",
+  "built_at": "2026-09-08T02:03:26.993Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 455,
+    "docs_redacted": 456,
     "agent_docs_stubbed": 24,
     "functional_verbatim": 2060,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2539,
-  "tree_sha256": "20c7a1a223a182078ca9a6e5dc0b6ca8d715a6e8b0a47b08a9c4dcb8dac2c74a",
+  "file_count": 2540,
+  "tree_sha256": "c1fc62840116ec8d78c3841c8a17e3172d902aadea6e084717199ab6bf5af95c",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1829,10 +1829,15 @@
       "mode": "0000644",
       "sha256": "cc30ad9de02409b6e3db26517bef2966133b3362903a984b65d94ea289fd0d88"
     },
+    {
+      "path": "docs/adr/0263-how-a-version-closes.md",
+      "mode": "0000644",
+      "sha256": "07a3561c7bc7f55bb2077925df4df6a24b68a1f0c8d4052ac50278edd9d4eba1"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "9d58f1a823a763141df272149e58b2182aa2289dd94d69ba0b3999789d8fc743"
+      "sha256": "fce8c6fab919a332b83cd467b2c0548499c58a2e032ca8e8d4da4b06d35bb715"
     },
     {
       "path": "docs/api-reference.md",
@@ -2717,7 +2722,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "3e6075bb21834fc14b6201155cac3f4b51e262d86d6ccbed2505f593831f59f9"
+      "sha256": "44d532bc6f634ef0730d4f5d3a778c67516143ea202f126c48aed43ffc8e8664"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7592,12 +7597,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "2b1a6ffdd207887a187f1574571de67e3f8ba851e80e433d463e932316b36e16"
+      "sha256": "93ff5dd9e6965597f8af514e41a02d0c5149e31e6a456576f6dc9b1bd1a773fc"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0caa3d71c5b02c8a41cebc7e59a6af2d68b50eb419311c7d444b0daa30df8430"
+      "sha256": "ed02b11ea51fdadd43ceb8fcaa9c3613ca172bf8c06caeeb0a351b8c65405900"
     },
     {
       "path": "public-docs/index.html",
@@ -9307,7 +9312,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6a4b0d97d9bc67728886e879359cf1f657dd81f865d141d8a1c6cd6e41877012"
+      "sha256": "d1b45d7bf6ca9667e8ef78fbb8dc255eda9bb60a27a74e48f59fb067e882d8d4"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/adr/0263-how-a-version-closes.md

@@ -0,0 +1,275 @@
+# 0263 — How a version closes: auto, early, roll-forward, and the maintenance exemption
+
+- **Status:** Accepted
+- **Date:** 2026-09-07
+- **Tasks:** [#1003593](https://cloudbongos.com/builders#/task/1003593) (this design pass, BV1.R06). Implemented by BV1.R12 ([#1003599](https://cloudbongos.com/builders#/task/1003599)), R16 ([#1003603](https://cloudbongos.com/builders#/task/1003603)), R17 ([#1003604](https://cloudbongos.com/builders#/task/1003604)), R18 ([#1003605](https://cloudbongos.com/builders#/task/1003605)), R20 ([#1003607](https://cloudbongos.com/builders#/task/1003607)) and R23 ([#1003610](https://cloudbongos.com/builders#/task/1003610)).
+- **Goal:** [#1000086](https://cloudbongos.com/builders#/goal/1000086) — Strict versioning.
+- **Implements:** [ADR 0250](<redacted>.md) D5. That decision says a version *can* close; this one says *how*, so the five build tasks under it are mechanical.
+
+## 1. Why a second ADR
+
+[ADR 0250](<redacted>.md) is the
+decision: the version boundary is the scope gate, and a version must be able to
+reach done. It deliberately stops at the rule. Closing a version is the widest
+write in the system — it flips a version, dispositions every goal still standing,
+promotes the next version into `building`, and carries a bug queue across the
+boundary — and *four* separate tasks build pieces of it. Left undesigned, each
+would pick its own refusal codes, its own payload shape, and its own answer to
+"what happens to the maintenance goal", and the seams would only meet in
+production.
+
+So this ADR pins the mechanics. It adds no rule ADR 0250 did not already decide.
+
+## 2. The state machine
+
+`versions.status` has four values (migration 003): `planning`, `building`,
+`shipped`, `frozen`. Only two transitions are in scope here:
+
+```
+planning ──promote──> building ──close──> shipped
+```
+
+`frozen` is archival bookkeeping and no business of this design. Nothing
+un-closes a version: reopening is not a move, and a version closed in error is
+corrected the way any other bad row is.
+
+**Only a `building` version may close.** Closing a `planning` version is
+meaningless (nothing was built), and closing an already-`shipped` one is a
+double-close. Both are `version_not_building` (409).
+
+## 3. Two doors, and the asymmetry that makes the design simple
+
+The single most useful thing to notice about D5 is that **auto-close, by
+construction, has nothing to disposition.**
+
+Auto-close fires when the last non-maintenance goal achieves. If that goal was
+the last one, then every non-maintenance goal on the version is already
+`achieved` or `archived` — so the set of open goals needing a decision is *empty
+by definition*. The disposition machinery is not merely unnecessary on that path;
+it can never have input.
+
+That splits the feature cleanly in two:
+
+| | **Auto-close** (R16) | **Early close** (R12) |
+|---|---|---|
+| Trigger | the last non-maintenance goal achieves | an Archon calls `POST /versions/:id/close` |
+| Open goals at close | zero, by construction | any number |
+| Disposition required | none — there is nothing to disposition | one per open non-maintenance goal |
+| Actor | the system, on a ship or a satisfy | an Archon, deliberately |
+| Roll-forward | the maintenance goal only | the maintenance goal, plus every goal dispositioned `roll_forward` |
+
+Every complication in this feature — the disposition map, the refusal that
+returns the open goals, the successor lineage — belongs to **early close only**.
+R16 is a much smaller task than the ADR 0250 sentence makes it sound, and R12 is
+where the weight is.
+
+## 4. Auto-close: where it fires, and why it cannot fail a ship
+
+Goal achievement has **two writers**, and [ADR 0250](<redacted>.md) D2 already made them a deliberate,
+documented duplicate rather than one helper, because collapsing them creates a
+require cycle (`db-goals` → `done-when` → `db-goals`):
+
+- [`db-goals.js` `achieveGoalIfComplete`](../../modules/lifecycle/db-goals.js) — the manual `POST /done-when/:id/satisfy` path.
+- [`done-when.js` `autoSatisfyShippedCriteria`](../../modules/lifecycle/done-when.js) — the cascade that fires on **every ship** and every reconciler tick, on the ship transaction's own `exec`.
+
+**Auto-close hangs off both, on the same exec, exactly as R08/R09's closure check
+did.** The rule is written twice on purpose, and the two copies move together or
+a version closes correctly through one door and wrongly through the other. That
+sentence is already load-bearing in both files; this feature adds a second clause
+governed by it, so it is repeated here rather than left to be rediscovered.
+
+**Auto-close must never fail a ship.** This is not a preference — it is the
+established posture of the surrounding code:
+[`closeCompletedWorkForShip`](../../modules/lifecycle/done-when.js) already
+swallows its own failure and reports it in a summary line, on the argument that a
+criterion close must never fail a ship and the reconciler's unscoped sweep
+retries every tick. Version close is a strictly wider write than a criterion
+close, so it inherits the posture *a fortiori*:
+
+- it runs inside the ship transaction so it sees the uncommitted `shipped` flip (the same reason R09's clause needs `exec`);
+- it is wrapped so a throw is caught, logged, and reported — never propagated into the ship;
+- it is **idempotent** (`WHERE status = 'building'` guards the flip), so the reconciler sweep retrying it is a no-op once it has run.
+
+The consequence, stated plainly: **a version can be left un-closed by a failure,
+and never half-closed.** Un-closed self-heals on the next sweep. That is the
+correct trade — the opposite choice makes a bug in version-close able to block
+every builder's ship.
+
+### The archive doc is not part of the transaction
+
+`limitations/<version>-shipped.md` is a **repo file**, and a route cannot write
+one. Auto-close therefore flips the database and nothing else; the scope archive
+stays a human/agent follow-up driven by
+[`scripts/gds/version-close.js`](../../scripts/gds/version-close.js) (R23). This is
+worth saying because ADR 0250 §7 speaks of a version "reaching done", and a
+reader could reasonably assume the archive rides along. It does not, and pretending
+otherwise would put file I/O inside a ship transaction.
+
+## 5. Early close: the two-step, mirroring the archive refusal
+
+`POST /versions/:id/close` is Archon-only, behind the **already-defined**
+`version.close` permission ([`government/catalog.js`](../../modules/government/catalog.js)) that nothing has referenced until now.
+
+The shape is **the R10 archive two-step, verbatim in spirit** — that precedent is
+shipped, agents already know it, and inventing a second idiom for the same
+interaction is how two surfaces drift:
+
+**Step 1 — refuse, and return the work.** Called with open non-maintenance goals
+and no disposition, the route refuses with `version_holds_open_goals` (409) and
+**returns the goals**, not merely a count. R10's reasoning applies unchanged: the
+caller's next move is to decide what happens to each, and an agent that has to go
+fetch the list first will guess instead.
+
+```
+409 { error: "version_holds_open_goals",
+      message: "Version 'BONGOS-V1' still holds 12 open goal(s). …",
+      details: { total: 12, shown: 12,
+                 goals: [ { id, title, open_tasks } … ] } }
+```
+
+**Step 2 — proceed with a disposition map.** One entry per open non-maintenance
+goal, keyed by goal id:
+
+```json
+{ "reason": "V1 is done; the rest is V2 scope.",
+  "dispositions": {
+    "1000044": { "verb": "roll_forward" },
+    "1000065": { "verb": "abandon" }
+  } }
+```
+
+Two verbs, and only two:
+
+- **`roll_forward`** — a successor goal is created in the planning version (§6).
+- **`abandon`** — the goal is archived, and its open tasks are abandoned with the close's `reason`, through the same path R14 gives the archive flow. It is deliberately **not** possible to abandon a goal without a reason: `reason` is required on the close call, and it is what lands in each abandoned task's record.
+
+**A version holding zero open goals stays a single call**, exactly as a goal
+holding zero open tasks does. That is the auto-close path's shape too, so both
+doors agree.
+
+### Refusal codes
+
+Every one is **named**, per ADR 0250 §7 — the callers are agents, and an unnamed
+409 is an agent stopping to ask a human.
+
+| Code | Status | When |
+|---|---|---|
+| `version_not_found` | 404 | no such version |
+| `version_not_building` | 409 | the version is `planning`, `shipped` or `frozen` |
+| `version_holds_open_goals` | 409 | open non-maintenance goals and no/partial disposition map; returns the goals |
+| `bad_disposition` | 400 | a disposition names an unknown goal, a goal not on this version, or a verb outside `roll_forward`/`abandon` |
+| `no_planning_version` | 409 | a `roll_forward` was asked for and no `planning` version exists to receive it |
+| `close_reason_required` | 400 | `reason` missing on a close that dispositions anything |
+
+`no_planning_version` is the one that will actually be hit in practice, and it is
+a **refusal rather than an auto-create on purpose**: cutting the successor version
+is a scope decision with its own criteria, and doing it implicitly inside a close
+is precisely the "fake hotfix version" failure ADR 0250 §3 built the override
+counter to prevent.
+
+## 6. Roll-forward: the lineage column already exists, pointing the other way
+
+Migration 160 gave `goals` a **`succeeded_by_goal_id`** column — on the *old*
+goal, pointing at the *new* one. Both ADR 0250 and task 1003604's brief say
+`succeeds_goal_id`, which does **not** exist. The column that exists wins; there
+is no migration here, and R17 must write:
+
+```sql
+UPDATE goals SET succeeded_by_goal_id = <new.id> WHERE id = <old.id>
+```
+
+Naming this explicitly is the whole reason this section exists — R17's brief would
+otherwise send a builder to reserve a migration number for a column that has been
+in the schema since the goal tier landed.
+
+A rolled-forward goal is created on the planning version carrying the original's
+`title`, `description`, `scope_modules`, `category_id` and **membership**; its
+open tasks are re-pointed at it. The predecessor is then `archived` with zero
+open tasks — so it passes R10's own check on the way out, rather than being
+special-cased around it.
+
+## 7. The maintenance goal: the flag R18 owes, and the exemption
+
+The maintenance goal is currently **matched by title** —
+`ensureMaintenanceGoal` (task 1003691) looks up `"<version> — maintenance"`, and
+its own comment flags this as R18's debt:
+
+> MATCHED BY TITLE, because there is no column that says "this is the maintenance goal" … task 1003605 (BV1.R18) is where a real flag belongs when the feature gets its own column.
+
+**R18 adds the column**: `goals.is_maintenance boolean NOT NULL DEFAULT false`,
+backfilled by title for the rows that already exist, after which the title lookup
+becomes a flag read. This is not cosmetic. The close count asks "are there any
+open non-maintenance goals?", and answering it with a `title NOT LIKE` would make
+a hand-titled goal silently exempt from the gate that decides when a **version**
+closes — a much worse blast radius than the provenance wrinkle the title match
+carries today.
+
+The exemption is then one predicate, used identically by auto-close and early
+close:
+
+```sql
+WHERE version_id = $1 AND status = 'open' AND NOT is_maintenance
+```
+
+**The maintenance goal always rolls forward, and never needs a disposition.** It
+is exempt from the close count, so it cannot hold a version open; and its open
+bugs move to the successor version's maintenance goal (`ensureMaintenanceGoal` on
+the newly-promoted version — the find-or-create already exists and is
+advisory-locked). Bugs arrive on their own schedule and must not need an override
+to be filed; that is the pressure valve ADR 0250 §3 describes, and it only works
+if the queue survives the boundary.
+
+## 8. Promotion: the close's last act
+
+On a successful close, the single `planning` version is promoted to `building`
+(R20), so the project is never without a live train.
+
+- It runs **in the close's transaction** — a project with zero building versions is a broken state, not an intermediate one, and `currentBuildingVersionId` returns `null` there, which fails every routing path closed over it.
+- **Zero planning versions is not an error.** The close succeeds and the project sits with no building version until someone cuts one. Refusing the close would trap a finished version open because nobody had scoped the next one yet.
+- Exactly one can be promoted, because R04 already refuses a second `planning` version.
+- The promoted version gets its maintenance goal via `ensureMaintenanceGoal`, which is what receives the carried-forward bugs in §7.
+
+**Ordering inside the transaction is load-bearing:** promote *before* roll-forward
+and before the bug carry-over, because both need a destination version that is
+already `building` — `ensureMaintenanceGoal` returns `null` for a version whose
+status is not `building`, so a carry-over run before the promotion silently
+carries nothing.
+
+## 9. The race, and where the index belongs
+
+[`versions.js`](../../modules/lifecycle/routes/versions.js) already documents R04's
+unmitigated check-then-insert race and names R19 as the place to fix both halves
+with one partial unique index. That still stands, and this design adds the close
+side of the same exposure: two concurrent closes could both promote.
+
+The single migration R19 reserves should therefore carry **both** guards:
+
+```sql
+CREATE UNIQUE INDEX ON versions ((status)) WHERE status = 'planning';
+CREATE UNIQUE INDEX ON versions ((status)) WHERE status = 'building';
+```
+
+With those in place the promotion race resolves the way the version-id collision
+already does — the loser gets a `23505` and the route translates it into the same
+clean refusal, rather than the check-then-act prayer both rules rely on today.
+
+## 10. What this design does not do
+
+- **It does not gate shipping.** Consistent with ADR 0250 §4. Auto-close rides the ship transaction and is swallowed on failure; nothing here can refuse a ship, a claim, or a grade.
+- **It does not write the scope archive.** §4. The route closes the version; the doc is R23's CLI work.
+- **It does not auto-create the successor version.** §5. That is a scope decision with criteria, and doing it implicitly is the escape hatch ADR 0250 exists to close.
+- **It does not add a reopen.** A version does not un-close.
+
+## 11. The sub-tasks this implies
+
+All five were already filed by the planning session; this ADR is what makes them
+mechanical. Two briefs are **corrected** by it:
+
+| Task | What this ADR pins |
+|---|---|
+| R12 [#1003599](https://cloudbongos.com/builders#/task/1003599) | the route, the six refusal codes, the two-step + disposition payload (§5) |
+| R16 [#1003603](https://cloudbongos.com/builders#/task/1003603) | **corrected** — auto-close needs no disposition machinery (§3); it hangs off *both* achievement writers on the caller exec and may never fail a ship (§4) |
+| R17 [#1003604](https://cloudbongos.com/builders#/task/1003604) | **corrected** — the column is `succeeded_by_goal_id` and already exists; no migration (§6) |
+| R18 [#1003605](https://cloudbongos.com/builders#/task/1003605) | the `is_maintenance` flag, the backfill, the exemption predicate, the bug carry-over (§7) |
+| R20 [#1003607](https://cloudbongos.com/builders#/task/1003607) | promotion runs in the close txn, before roll-forward; zero planning versions is not an error (§8) |
+| R19 [#1003606](https://cloudbongos.com/builders#/task/1003606) | its migration carries the `building` partial index **and** R04's `planning` one (§9) |

package/docs/adr/README.md

@@ -354,3 +354,4 @@ This keeps the decision history honest and traceable.
 | 0260 | [**An application IS the consent, and the hub’s own echo is the gate** ([task 1002972](https://cloudbongos.com/builders#/task/1002972) · goal 1000045, criterion C4). Privacy spec **D7** asks that a reviewer see what the applicant’s OWN profile rules would already show, evaluated LIVE at review time. The rule is ONE port composing the two EXISTING views — `getPublicProfileExtras` for a public account, `recruiter-sliver`’s own `sliverShapeFor` for a private one — because a third five-key lookalike **is** the new disclosure class D7 forbids. **The one deliberate difference from the D3 sliver:** `getRecruiterSliver` floors on recruiting REACH, and reusing it verbatim would be wrong in the direction that looks safe — `recruiter_discoverable` defaults to FALSE for a private account, so a private builder who deliberately applied would show their reviewer NOTHING and C4 would be satisfied by an empty box. D7 settles it: *“applying is an explicit act”*. The swap relaxes REACH only; `accountActiveSql` (active **and** terms accepted) and `hide_stats` still floor it, and the proof asserts both directions on the same account so the tempting refactor cannot pass quietly. **The federated route’s gate is the whole security story** ([ADR 0205](<redacted>.md) / security report 1000027): client credentials name a PROJECT and never a person, so `POST /sso/applicant-profile` authenticated alone is a bulk disclosure oracle over every account on the platform, private ones included. `applicationBacksProfileRead` demands a HUB-WRITTEN echo for exactly (this account, this client) inside the same 30-day window — a row only the hub’s own join relay creates — refusing **404, never 403**, and BEFORE any account is read (asserted on the statement log, because a gate that refuses after reading has already done the disclosure work). LIVE means nothing is stored at either end; the queue keys on the VOUCH and never on `github_login` (the one PUBLIC unauthenticated write makes an unvouched login an impersonation surface); and the hub client secret stays in core behind a narrow doorway port. **The path is complete but DORMANT until R09 ([task 1002285](https://cloudbongos.com/builders#/task/1002285)) ships the vouch writer** — nothing writes `applicant_github_id` today, and that dependency was missing from 1002972’s graph. Rejected: routing the port through `getRecruiterSliver`, a snapshot at apply time, resolving by `github_login`, and putting `loadIdpConfig` on the doorway.](<redacted>.md) | platform identity / privacy |
 | 0261 | [**A preselect always carries a reason; the bundle’s summary is the floor** ([task 1003684](https://cloudbongos.com/builders#/task/1003684) · goal 1000046 — *Project creation*). Resolves a collision between two rules that were each right alone. [ADR 0243](<redacted>.md) made `adjustments` a **delta** — a team-shape rule that fires without moving anything claims nothing, because a sentence explaining a change that did not happen is a claim the owner cannot check. [ADR 0237](<redacted>.md) says a preselect the owner cannot see a reason for is one they must audit, which is worse than no preselect at all. The two collide whenever a type’s bundle **already contains** what a rule would add: `game` is `[dev-box, discord]` and the `small-team` rule adds `dev-box`, so the rule fires, moves nothing, and correctly reports `adjustments: []`. Confirmed on live core 1.19.580 — `byTeamShape[small-team]` = `{"bundle":["dev-box","discord"],"adjustments":[]}`. The owner then reached step 4 and saw **two extras switched on with no reason beside them**, `#modWhy` an empty hidden div: exactly what 0237 exists to prevent, produced by 0243 behaving correctly. Filed as a dropped adjustment; it was not — the engine is right, and the panel simply had ONE voice and fell silent when the rule had nothing to say. **Decision: the why-line has two voices and the type’s is the floor.** A real adjustment still speaks for itself and is never displaced; when none moved, the type’s own curated `summary` explains the preselect; when the owner has answered the picker themselves the panel stays silent (unchanged — a reason handed back for a toggle they just flipped reads as the panel arguing with them); a bundle with no summary still says nothing, because a floor is not an invention. **No new copy, endpoint or field** — the summary was authored for this job in `starter-bundles.js`, served on every row of `GET /provisioning/starter-bundles`, and rendered NOWHERE in the product until now. 0243 is not weakened: the delta stays a delta and no rule is credited with a change it did not make. The pin `tests/projects_hub_module_picker.mjs` carried a fixture with **no `summary` field**, which made four “no adjustment, no sentence” cases pass for the wrong reason; the fixture now carries the real summaries and those cases assert the new contract, including explicitly that no RULE sentence is invented for a change that did not happen. Rejected: making the rule claim a no-op change (re-introduces the unverifiable claim 0243 removed); widening the bundles so no rule is ever redundant (contorts curated presets for a rendering concern, and the redundancy returns on the next edit); and leaving it silent, declined by the owner once the trade-off was put to them directly.](<redacted>.md) | provisioning / starter bundles / owner-facing copy |
 | 0262 | [**A bug never lands in the inbox: the system names the home the reporter didn't** ([task 1003691](https://cloudbongos.com/builders#/task/1003691) · goal 1000086 — *Strict versioning*). `routing.js` returned early on a goal-less filing, so its own `kind='bug'` hard-land branch was UNREACHABLE without a goal — `kind` only ever chose a routed task's STATUS, never whether it routed — and a reported defect sat in `idea_inbox` awaiting the triage pass criterion C1 exists to remove. The premise that [ADR 0250](<redacted>.md) D4 and [ADR 0235](<redacted>.md) contradict each other is FALSE: 0235's exemption is an advisory silence in `goal-advisory.adviseGoal`, and its actual decision already requires a real `goal_id`. So nothing is amended; this is the explicit decision 0235 §6 said would be needed. **D1** a homeless bug gets the version's MAINTENANCE goal (R18's design), find-or-created under an advisory lock inside the route's own transaction — not the catch-all R11 is deleting, and adding no `allowCatchAll` caller. **D2** the gate is the VECTOR (`api`, `discord-bugs`), not the kind: `#ideas` passes no kind, so the classifier guesses one from keywords, and gating on kind alone would silently overturn [ADR 0234](<redacted>.md)'s owner-interview decision. Rejected: goal-less bug tasks (breaks D4 a day after it landed); rejecting the filing (Discord cannot retry, so the report is lost); the catch-all (repopulates the bucket being drained); building R18 whole first.](<redacted>.md) | work intake / idea routing / the version-goal invariant |
+| 0263 | [**How a version closes: auto, early, roll-forward, and the maintenance exemption** ([task 1003593](https://cloudbongos.com/builders#/task/1003593) · goal 1000086 — *Strict versioning*). [ADR 0250](<redacted>.md) D5 decided a version *can* close; this is the design pass that makes its five build tasks mechanical, so they do not each invent their own refusal codes and payload shapes and meet only in production. **The asymmetry that shrinks the feature:** auto-close fires when the last non-maintenance goal achieves — so by construction every non-maintenance goal is already closed and the set needing a disposition is EMPTY. All the machinery (the disposition map, the refusal that returns the goals, successor lineage) belongs to EARLY close alone; R16 is small and R12 carries the weight. **Auto-close hangs off BOTH achievement writers** (`db-goals.achieveGoalIfComplete` and the `done-when` cascade — the deliberate duplicate D2 already governs, a require cycle being the reason they are not one helper), on the caller `exec` so it sees the ship's uncommitted flip, and **may never fail a ship**: wrapped and swallowed like `closeCompletedWorkForShip`, idempotent under `WHERE status='building'`, so a failure leaves a version un-closed (self-healing on the next reconciler sweep) and never half-closed. **Early close** is the R10 archive two-step verbatim in spirit — refuse with `version_holds_open_goals` **returning the goals**, then proceed with a per-goal `roll_forward`/`abandon` map and a required `reason`; six named codes, because the callers are agents. **Two briefs are corrected by measurement:** the lineage column is `succeeded_by_goal_id` (migration 160, on the OLD row pointing forward) — not the `succeeds_goal_id` both 0250 and R17's brief name, so R17 needs NO migration; and R18's `is_maintenance` flag is load-bearing rather than cosmetic, because answering the close count with a `title NOT LIKE` would let a hand-titled goal silently exempt itself from the gate that decides when a VERSION closes. Promotion runs inside the close txn and BEFORE roll-forward (`ensureMaintenanceGoal` returns null for a non-`building` version, so a carry-over run first silently carries nothing); zero planning versions is not an error; R19's one migration should carry the `building` AND `planning` partial unique indexes so the promotion race resolves like a 23505 rather than a prayer. Rejected: auto-creating the successor version inside a close (the "fake hotfix version" escape hatch 0250 built the override counter to prevent), writing `limitations/<version>-shipped.md` from the route (file I/O in a ship transaction — it stays R23's CLI work), and a version reopen.](<redacted>.md) | version lifecycle / scope closure |

package/docs/module-api-changelog.md

@@ -1623,5 +1623,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.585 with no explicit bump. run 34167072966. (task 1002620)
   1.19.587 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.586 with no explicit bump. run 34172785860. (task 1002620)
+  1.19.588 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.587 with no explicit bump. run 34178696372. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.587",
+  "version": "1.19.588",
   "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

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.587'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.588'; // 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');