@bongos/core 1.19.586 → 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.586",
-  "core_contract": "1.19.586",
-  "source_commit": "ac6f287b895b1259c7b9fcc6b3a13e4fe178fbc0",
+  "core_version": "1.19.588",
+  "core_contract": "1.19.588",
+  "source_commit": "1833a4d18085bddf05b12c89aea4381e5ac5207e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T22:34:04.491Z",
+  "built_at": "2026-09-08T02:03:26.993Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 454,
+    "docs_redacted": 456,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2058,
+    "functional_verbatim": 2060,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2536,
-  "tree_sha256": "7986b516ffada3b257352c5ecedda7fbc33f7e216f58f11fd2cd8edf23920cae",
+  "file_count": 2540,
+  "tree_sha256": "c1fc62840116ec8d78c3841c8a17e3172d902aadea6e084717199ab6bf5af95c",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -182,7 +182,7 @@
     {
       "path": ".claude/skills/idea-triage/SKILL.md",
       "mode": "0000644",
-      "sha256": "2519755269ff2d55e3c060569f7d16c440428ba005d206a3bf12fe2275830285"
+      "sha256": "348bb6e8d27610848fb5f31b672c2c762f56cfb17141f7abe1a8dee0b5030bdd"
     },
     {
       "path": ".claude/skills/ideate/SKILL.md",
@@ -1824,10 +1824,20 @@
       "mode": "0000644",
       "sha256": "04382d76f04c9317b565fb72951b36503e67acc95981a388d5c45efc80faaa26"
     },
+    {
+      "path": "docs/adr/0262-a-bug-never-lands-in-the-inbox.md",
+      "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": "6d2df0c7c0e6cfd3381935d14a703f8cfa7854d107a6add03bc743e631823ada"
+      "sha256": "fce8c6fab919a332b83cd467b2c0548499c58a2e032ca8e8d4da4b06d35bb715"
     },
     {
       "path": "docs/api-reference.md",
@@ -2712,7 +2722,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "3474ae19a143b381a4da0091daa41c301338dac6ffd97e7ef396079803589160"
+      "sha256": "44d532bc6f634ef0730d4f5d3a778c67516143ea202f126c48aed43ffc8e8664"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4197,7 +4207,7 @@
     {
       "path": "modules/discord/discord-bugs.js",
       "mode": "0000644",
-      "sha256": "083569e4fe2a621dc6c8663fafc5ec1d6f5e1e1893a3b4a9bdb74ecf4854cd24"
+      "sha256": "52b463955cd7e57f8d194c161a76e2ade83481f3ee0a16759019a5b1f873b374"
     },
     {
       "path": "modules/discord/discord-channels.js",
@@ -4207,7 +4217,7 @@
     {
       "path": "modules/discord/discord-inbound.js",
       "mode": "0000644",
-      "sha256": "06937afc2ac299c8b6572cf296bbaed4e1e078802f9d3fc7a81e5851a639d5f3"
+      "sha256": "86099070386ff606ec14330375ac8c3145365307ae2ac354539731aebcc16563"
     },
     {
       "path": "modules/discord/discord-message-buffer.js",
@@ -5364,10 +5374,15 @@
       "mode": "0000644",
       "sha256": "07e5666362c91f92d34388b4f6f4507cc5387866d317970478e6cae417c19975"
     },
+    {
+      "path": "modules/ideas/homeless-home.js",
+      "mode": "0000644",
+      "sha256": "363598b5905c850967b407f20110a1d9e9d5b1090a958700cb6a4ed5cea70d80"
+    },
     {
       "path": "modules/ideas/inbox.js",
       "mode": "0000644",
-      "sha256": "5ebd1524a5593b70f74a83bdaa3a6d772eb820ea3d962f48dedace970efcc119"
+      "sha256": "8c0792629df6d9587bce828a0f3743b8c86bdb31ba226d31211b9c6623574395"
     },
     {
       "path": "modules/ideas/migrations/ideas_001_grades.sql",
@@ -5412,12 +5427,12 @@
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "a092eea43d9030eb55a23b60bd1ad5673132b83a3a2649961413cd505fd685ef"
+      "sha256": "8dec7682099d131ca050487dafe259bf4c9b511103c472cd0cbce54b4b9a898f"
     },
     {
       "path": "modules/ideas/routing.js",
       "mode": "0000644",
-      "sha256": "2ca0adb68b0fd44a65b9637c177848648ecd20ecd8ef67e65527c17b7a46414d"
+      "sha256": "ddedb76f43edbe3e7c918578fda94b97cb3822d97074af33393791fb1ec1cbef"
     },
     {
       "path": "modules/ideas/templates.js",
@@ -5492,7 +5507,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "31f39ea088b03feb217af4ce2fbf0b4dba0d8dad3e8eec625cf11e0dd4cb4228"
+      "sha256": "f50a54a0e0f0cdeac5a2321b14757e52d9d9507417b1d1962aa09cdc6a222832"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5527,12 +5542,12 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "9f777643c44ebeef8b668a8120bf74d369564f904b2cb1aff54711bd5825c9c5"
+      "sha256": "8214d4a7c2e97b12e8cd9ba866b6560ac6e67446af5dcf28a0055838e32897f5"
     },
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "61ed58e2d0dbe9aa0b889d27b6a9c38df024a40bc797f22b0ff766fedf85a9de"
+      "sha256": "6d69634ad12510f81727eeed0a8fdde4eac618fedc23e43e2c1aa5835aaf0388"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5557,7 +5572,7 @@
     {
       "path": "modules/lifecycle/goal-advisory.js",
       "mode": "0000644",
-      "sha256": "b9138fa63ef324b9353354e4c5398150d576dd7e3547bb6889f2f83ebd7b995f"
+      "sha256": "d17e49302bde2677927467c01acc40060f0abfcb7d8361354f9b092dd9859b55"
     },
     {
       "path": "modules/lifecycle/goal-authz.js",
@@ -5612,7 +5627,7 @@
     {
       "path": "modules/lifecycle/lifecycle.js",
       "mode": "0000644",
-      "sha256": "6d94121968be4164151a913971f7a5e248104511ebc41ff5a95f5a1ee05af5a6"
+      "sha256": "db5e823ab382d44d4ae41266cec8ff76a98d6e636fd175cea0f1a04135eec7c9"
     },
     {
       "path": "modules/lifecycle/merge-lock.js",
@@ -7582,12 +7597,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d60a7d4e330cfd6154a5dea888aa9062d7571dee2d62aafc73cadb19b4afa604"
+      "sha256": "93ff5dd9e6965597f8af514e41a02d0c5149e31e6a456576f6dc9b1bd1a773fc"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "14e7286fe47165dabdc74cb24b6bb5afdc1e7b949ae612b2f72c7a56107a246b"
+      "sha256": "ed02b11ea51fdadd43ceb8fcaa9c3613ca172bf8c06caeeb0a351b8c65405900"
     },
     {
       "path": "public-docs/index.html",
@@ -9297,7 +9312,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b3b115c1a4652247daebb85a6c393400361c2269cb047e691121193c45a63648"
+      "sha256": "d1b45d7bf6ca9667e8ef78fbb8dc255eda9bb60a27a74e48f59fb067e882d8d4"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10287,7 +10302,7 @@
     {
       "path": "tests/filing_abuse_matrix.mjs",
       "mode": "0000644",
-      "sha256": "dd63216406ff8d76a6250944c03fb8e0f2028c599d01ee4720ba3dd79d547a63"
+      "sha256": "2a6de0e7411bb4796fe4f301af77c33f08a99307f2298ed83cd32c38cf059dc5"
     },
     {
       "path": "tests/first_admin_bootstrap.mjs",
@@ -11012,7 +11027,7 @@
     {
       "path": "tests/idea_routing.mjs",
       "mode": "0000644",
-      "sha256": "39bdd91984e584f7f81f6dc096093a7a273c483e845b7c821a389472684114a3"
+      "sha256": "d4d4e6ce60f1524e821e0c6c9f2844c7ba791b5502072dc00496224404afa990"
     },
     {
       "path": "tests/idea_spark_hall.mjs",
@@ -11234,6 +11249,11 @@
       "mode": "0000644",
       "sha256": "9a1813d6036886ea07d1563e71a466e66c28554b75b22605464c795fd9fa2ebb"
     },
+    {
+      "path": "tests/maintenance_goal.mjs",
+      "mode": "0000644",
+      "sha256": "645fe3e9093abcb1425a59602d6a92a6d90669775aa3503ae435a54c79eca5c1"
+    },
     {
       "path": "tests/manage_manifest_shared_read.mjs",
       "mode": "0000644",
@@ -12477,7 +12497,7 @@
     {
       "path": "tests/task_goal_required.mjs",
       "mode": "0000644",
-      "sha256": "915711866bc194d977225326511c55ac5084b52d10a45a855bc9d6da815f4b8b"
+      "sha256": "2e311d02f87c562c2e8ed7cec24100efe3d1c750cb145e9e9e6bb1dac8043228"
     },
     {
       "path": "tests/task_lib.mjs",

package/.claude/skills/idea-triage/SKILL.md

@@ -1,18 +1,38 @@
 ---
 name: idea-triage
-description: Daily walk through the Bongos idea_inbox, which since task 1003071 holds only HOMELESS work — bugs and goal-bound captures now route to a task at filing time and never reach the inbox. For each open idea, prompt to promote (→ task, naming a goal), discard, or merge with another idea. Triggers when the user says "/idea-triage", "triage ideas", "review the inbox", "walk the idea inbox", or runs as a scheduled daily task. Metic+ rank only (Metic and Archon; not Xenos).
+description: >-
+  Daily walk of the Bongos idea_inbox, which holds only HOMELESS work: a capture
+  naming a goal, and since ADR 0262 a bug from a trusted vector, become a task at
+  filing time and never reach it. Promote, discard or merge each open idea.
+  Triggers on "/idea-triage", "triage ideas", "review the inbox", "walk the idea
+  inbox", or a scheduled daily run. Metic+ only.
 ---
 
 You are running the daily idea-triage session for Example. Open ideas in the Bongos `idea_inbox` table get walked one-at-a-time and verdicted, so the inbox doesn't accumulate stale entries.
 
-## The inbox is HOMELESS-ONLY now (task 1003071 / R13, goal 1000071)
+## The inbox is HOMELESS-ONLY now (task 1003065 / R01 + task 1003691, goal 1000071)
 
-**What changed.** Since R01 (task 1003065) a bug or goal-bound capture ROUTES at
-filing time — it becomes a task in its goal, in one transaction, and never appears
+**What changed.** Since R01 (task 1003065) a capture that NAMES A GOAL routes at
+filing time — it becomes a task in that goal, in one transaction, and never appears
 here. The inbox is therefore no longer "everything anyone filed"; it holds only
 **work with no home yet**. Expect it to be smaller, and read what IS in it as
 work that genuinely needs a decision rather than a queue to clear.
 
+**Bugs (task 1003691, [ADR 0262](../../../docs/adr/<redacted>.md)).**
+A `kind='bug'` now routes even with NO goal named: the system files it into the
+version's maintenance goal rather than making the reporter know the goal map. So a
+bug should not appear in this queue — with **one deliberate exception**. Routing is
+gated on the VECTOR, and Discord `#ideas` is not on the allowlist: it passes no
+kind, so the classifier GUESSES one from keywords ("we should fix the copy" reads
+as a bug), and a guess must not mint work (ADR 0234's owner-interview decision).
+Bug reports from Discord have their own channel, `#bugs`, which does route.
+
+> An earlier version of this section claimed bugs "never appear here" and credited
+> task 1003071. That was false when written — 1003071 only touched the
+> triage/promote path (commit `dab7e314`), while capture-time routing was 1003065,
+> whose no-goal early return made the bug branch unreachable. If you are triaging a
+> bug today, it arrived from `#ideas` or from a vector predating ADR 0262.
+
 **Two consequences for how you run this skill:**
 
 1. **Every promote names a goal.** The promote step now asks for one, defaulted

package/docs/adr/0262-a-bug-never-lands-in-the-inbox.md

@@ -0,0 +1,96 @@
+# ADR 0262 — A bug never lands in the inbox: the system names the home the reporter didn't
+
+**Status:** Accepted · 2026-09-07 · task 1003691
+**Supersedes nothing. Amends nothing.** It makes the explicit decision [ADR 0235](<redacted>.md) §6 said would be needed, and it keeps [ADR 0234](<redacted>.md)'s `#ideas` interview decision and [ADR 0250](<redacted>.md) D4's invariant both intact.
+
+## Context
+
+A reported defect could still end up parked in `idea_inbox`, waiting for a human triage pass — the exact tax criterion C1 of goal 1000071 was opened to remove.
+
+The cause is one line. `modules/ideas/routing.js` `decideLanding()` opened with:
+
+```js
+if (goalId == null || goalId === '') return { route: false, reason: 'no_goal' };
+```
+
+The `kind === 'bug'` hard-land branch sat **nine lines below** it and was therefore **unreachable without a goal**. `kind` only ever chose the routed task's *status* (`ready` for a trusted filer, `backlog` otherwise); it never chose whether the filing routed at all. So "bugs are urgent-true" was true only for a reporter who already knew which goal the defect belonged to — which is precisely the knowledge criterion C5 promises a filer never needs.
+
+### The conflict this task was filed over does not exist
+
+The task was opened on the premise that two accepted ADRs contradict each other, and that one had to lose:
+
+- **ADR 0250 D4** — "Every task belongs to a real, open goal. `goal_id` becomes required at creation." Enforced: `modules/lifecycle/db-tasks.js` throws, `POST /tasks` 400s `goal_id_required`.
+- **ADR 0235** — read as exempting `kind='bug'` from needing a goal at all, on the strength of the phrase *"a fix needs no home to be filed correctly."*
+
+**That reading of 0235 is wrong, and checking it was the first thing this task did.** ADR 0235's headline decision is the opposite:
+
+> **A fix category is `kind='bug'` on a task that carries a real `goal_id`** — no schema change, no new column, no new goal type.
+
+The quoted phrase describes `adviseGoal()` in `modules/lifecycle/goal-advisory.js:64`, which returns `null` — stays silent — for a `kind='bug'` task on its `no_goal`, `catch_all` and `no_criterion_link` branches. It is an **advisory suppression**: it stops the system nagging a bug about its goal. It grants nothing, and it changes no schema.
+
+So both ADRs already require a real goal, nothing loses, and no amendment is owed. What ADR 0235 *did* anticipate is this task — §6 Consequences:
+
+> giving `kind='bug'` more weight than an advisory exemption "is a new, explicit decision needing its own ADR."
+
+This is that ADR.
+
+## Decision
+
+**A `kind='bug'` filed from a trusted vector with no goal becomes a task in the version's maintenance goal, at the status the existing rank split already assigns.** Two halves, and both are load-bearing.
+
+### D1 — The home is the per-version MAINTENANCE goal, find-or-created
+
+The reporter does not name a home; the system does. `modules/ideas/homeless-home.js` resolves the current building version (`lifecycle.currentBuildingVersionId`), then find-or-creates `"<version> — maintenance"` (`lifecycle.ensureMaintenanceGoal`).
+
+**Not the `"<version> — general"` catch-all**, which is the obvious-looking choice and the wrong one. BV1.R11 (task 1003598) began *deleting* that fallback after 53 open tasks accumulated unread in two of them, and `db-tasks.js` warns against adding a third caller to the `allowCatchAll` opt-out it left behind. The maintenance goal is the home task 1003605 (BV1.R18) already designs for exactly this — *"where a defect against already-shipped work lands"* — so routing points at the destination the roadmap was already heading for rather than repopulating the bucket being drained. **This vector adds no `allowCatchAll` caller**, pinned by `tests/task_goal_required.mjs`.
+
+ADR 0250 D4's invariant therefore holds exactly: the task carries a real, open `goal_id`. What changes is only *who names it*.
+
+Three mechanics that are decisions, not implementation detail:
+
+- **The version tiebreak is not new.** More than one version may sit at `building` — ADR 0250 D5 closes the *planning* slot only, and refusing a second building version is still unshipped (task 1003606, BV1.R19). The rule reused is `pickDefaultVersion` from `scripts/gds/version-select.js`, expressed in SQL: building only, `started_at DESC`, nulls last, `id` breaking a remaining tie.
+- **Find-or-create takes a `pg_advisory_xact_lock`.** `goals` has no unique constraint on `(version_id, title)` — migration 160 used a `NOT EXISTS` guard, safe for a one-shot backfill and unsafe for a concurrent path, where two bugs reported in the same second would both insert and leave the title lookup permanently ambiguous.
+- **It runs inside the caller's transaction.** A goal created on its own connection would outlive a rolled-back route as an empty goal nobody asked for.
+
+**It fails closed.** No building version (`NO_BUILDING_VERSION`), or a version whose maintenance goal cannot be made (`NO_MAINTENANCE_GOAL`), refuses the filing and rolls back. Inventing a version is idea 1000771's exact failure — every Discord report entombed in a shipped version's catch-all — and this path exists to end that, not to repeat it.
+
+### D2 — The gate is the VECTOR, not the kind alone
+
+Routing keys on an allowlist, `routing.HOMELESS_ROUTING_VECTORS = {'api', 'discord-bugs'}`, and **absent or unrecognised is untrusted**.
+
+This is the half that keeps ADR 0234 whole. Its owner-interview decision — *"Discord `#ideas` files with HINTS only, never routes"* — is not an incidental detail: `#ideas` passes **no kind at all**, so `inbox.classify()` guesses one from keywords, and its bug pattern fires on `fix|broken|bug|regression|crash|error` anywhere in the text. *"We should fix the copy on the landing page"* classifies as a bug. Gating on kind alone would let a keyword guess mint work and would have killed an explicit owner decision as a side effect.
+
+The two trusted members each carry a human or a channel that means *this is broken*:
+
+| Vector | Why it is trusted |
+|---|---|
+| `api` | `POST /inbox`, authenticated builder, explicit `kind`. `scripts/gds/capture.js` posts to this route, so the CLI inherits it and needs no member of its own. |
+| `discord-bugs` | The **channel is the classification** (`discord-bugs.js` forces `kind='bug'`), and it already carries an unlinked-author guard, a per-builder hourly rate cap, and a body screen. |
+
+`discord-ideas` is named explicitly at its call site so its exclusion is a written fact rather than an absence someone has to notice. The vector is **server-set at every call site and never read from a request body**, which is what makes forging it a non-move.
+
+#### A vector is claimed by a call site, so the call site must still check identity
+
+`#bugs` sets `vector: builder ? 'discord-bugs' : null` — **conditional, not the bare string.** The first cut of this ADR set it unconditionally and that was a trust-boundary regression caught as a grader blocker, worth recording because the shape will recur.
+
+The channel earns its place on the allowlist through two guards that are both **identity-bound**: the rank-aware landing needs a rank, and the rolling rate cap is counted per builder id. An unlinked Discord author has neither — `filerRank` is null and the goal is only sought `if (builder)` — so an unconditional vector meant they took the homeless-bug branch and minted a real `backlog` task, with the per-builder rate limiter not running at all for them. That is unattributed task creation at no cost, and it contradicts the promise at the top of `discord-bugs.js` that ADR 0047 bought: *"an unlinked author cannot inject claimable work… it no longer mints anything."*
+
+The general rule: **being on the allowlist is a property of the DOOR, not of everyone who walks through it.** A vector attests "filings from here carry a human who means *this is broken*"; where a door admits both identified and anonymous traffic, it may only claim the vector for the identified half. With no vector the filing falls back to the inbox exactly as before — the report is kept, its images re-hosted, a human still sees it in triage. Pinned as F16, mutation-verified against the unconditional form.
+
+Everything else the matrix already decided is unchanged and still applies to this path: the Metic+ rank split (`ready` vs `backlog`), the Full Idea refusal, and the judgment kinds. **Only bugs get a free home** — a homeless feature or cleanup is exactly the work the inbox is *for*, and fabricating homes for it would empty the inbox by lying.
+
+## Consequences
+
+- **The inbox's stated identity becomes true.** `.claude/skills/idea-triage/SKILL.md` claimed bugs "never appear here" and credited task 1003071 — which only touched the triage/promote path (commit `dab7e314`); capture-time routing was task 1003065. The claim was false when written and is corrected alongside this ADR; it is now true for the `api` and `discord-bugs` vectors.
+- **A bug reported in Discord `#ideas` still lands in the inbox.** That is deliberate, and it is not a gap: bug reports from Discord have their own channel, `#bugs`, which routes.
+- **`#bugs`' bad-guess fallback got better.** It re-files with `goalId: null` when a suggested goal refuses the landing; that path now reaches the maintenance goal instead of the inbox, so dropping a wrong guess costs a triage pass rather than the whole report.
+- **Task 1003605 (BV1.R18) is partly delivered and still owed.** This ships the maintenance goal's title, find-or-create and routing. R18 still owns auto-creating it with every version, the close-exempt flag R16 reads, and carrying open bugs forward to the successor version on close.
+- **A new file on the create path** — `modules/ideas/homeless-home.js`, added to the `tests/task_goal_required.mjs` roster so the anti-drift pin covers it.
+
+## Alternatives rejected
+
+- **Let a goal-less bug create a goal-less task** (an `allowCatchAll`-style escape hatch for bugs). Breaks ADR 0250 D4 one day after it was accepted, and every consumer assuming `goal_id` is non-null would need auditing. The invariant is worth more than the shortcut.
+- **Reject a bug with no goal, listing open goals to pick from.** One rule, no exceptions — but a rejected report does not land *at all*, and Discord's bot fires and forgets, so every inbound bug from a channel that cannot retry would be silently lost. It also directly contradicts the thing being asked for.
+- **Route into the `"<version> — general"` catch-all.** Smallest diff, reuses shipped machinery, and repopulates the exact buckets BV1.R11 was filed to drain. R18 would then have to undo it.
+- **Build R18 whole first, then route.** The cleanest end state, and substantially more scope than the defect being fixed; the close-exempt flag and version-close carry-forward are independent of whether a reported bug finds a home today.
+- **Gate on `kind` alone.** Cheapest fix, and it silently overturns ADR 0234's owner-interview decision by letting a keyword classifier mint tasks from an ideation channel.

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) |