@bongos/core 1.19.619 → 1.19.620

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.619",
-  "core_contract": "1.19.619",
-  "source_commit": "b3a494e84958a264492cf55b3525d70680f7bbda",
+  "core_version": "1.19.620",
+  "core_contract": "1.19.620",
+  "source_commit": "7e8c8d38a15a24575258eda58829e9120d9ed55f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-09T06:39:30.103Z",
+  "built_at": "2026-09-09T06:53:24.739Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 463,
+    "docs_redacted": 464,
     "agent_docs_stubbed": 24,
     "functional_verbatim": 2086,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2573,
-  "tree_sha256": "f0ad9c8d1e70405ab669163d2d2153cd7f6ae97a699036bb8e4278f1e3a435d5",
+  "file_count": 2574,
+  "tree_sha256": "8c5d0cef512909da1de5dd90510ca13a74737c8d3b80ec2d8e0a7fc5e1d9451d",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -397,7 +397,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "877ca14cd017c1392fcc5206c2f3603fb24becdc32670aa1e2ad0de9d930dfca"
+      "sha256": "07caf5c1db2cfd16c92713891055b477982aef4dd847af67042b742293e6a9ce"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1877,12 +1877,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "b430ecad01c7458dc893c11d976d3ae35f2dd5b8310e451a38af387908f64659"
+      "sha256": "8adebe11d51d4bbce7e5acacc003ce923e820f0d8532541d3f5a74ed07570ce8"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "81485c0440de636511dc9ee723e18af89f313b175ea626723d0beeeed31bba2f"
+      "sha256": "2059cb9b02d6a20e4b1297c866db9f717bb3514ec49ab2454c776c806775d3da"
     },
     {
       "path": "docs/architecture.md",
@@ -2757,7 +2757,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "1fe02fc79e2952efb61450bbd45e6b09e41e8cf73453c6e0a2fbbf2944c1cdab"
+      "sha256": "6b3c53cfb31b4bf6963f740bb386c24059ef370af8927b0ececde09e062fff33"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2954,6 +2954,11 @@
       "mode": "0000644",
       "sha256": "f6d2bb1da53f03f54080b8e0aec9f63390d3343c32917b64225ac47ae4ba7b42"
     },
+    {
+      "path": "docs/recipes/reranking-a-goals-board.md",
+      "mode": "0000644",
+      "sha256": "ecd8986c5e4831db53a803dae625e5f1b898b711911e8e6f1c4f1b79a98cbfe8"
+    },
     {
       "path": "docs/recipes/search-index-ingestion.md",
       "mode": "0000644",
@@ -5592,7 +5597,7 @@
     {
       "path": "modules/lifecycle/db-tasks.js",
       "mode": "0000644",
-      "sha256": "e978cadb879a57d8d7e3bb84657a787ac7e83125666fa2d31013ac64b37b0d7a"
+      "sha256": "15c9efea1fb5a8187fe5bae756777ebeb1a214e47e0434d7a8adeb156bd1e093"
     },
     {
       "path": "modules/lifecycle/db-versions.js",
@@ -5602,7 +5607,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "b4b2d6d7890ec67e52fc00718a814bf01a64f4432ed7380a175dca8bc794b0e4"
+      "sha256": "af6af95c05aa6cc76c0e49cb0a99bfb24685b3efb66df0f90883c3301baeede0"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5832,7 +5837,7 @@
     {
       "path": "modules/lifecycle/routes/task-write-routes.js",
       "mode": "0000644",
-      "sha256": "87843c62d8ce7af3d7d6aa5772791bd52823afe5f2c4b9b7427ca9f00dd14c11"
+      "sha256": "cc86b3c05885c733cc28ba6e41f1b08cb8f0fe652e3181c1c88be4caabf18d61"
     },
     {
       "path": "modules/lifecycle/routes/tasks.js",
@@ -7657,12 +7662,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "41aca5e97b1cb72e389656c14ddd1bb35a3d5fdce8145f05e294c3fa3f52dc15"
+      "sha256": "401ae455c8e67d7bf4d622ef7e93fce203948868ae3b07de9770e6d90607249f"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2084b4c59fd9b3857bb83b5a4198d43c308f0180edc0e21a698e4285809323fd"
+      "sha256": "f6c0e1047dcef4fe6e429e149606d521e0d196ff748bcdeb6de6e1c63d2a60ab"
     },
     {
       "path": "public-docs/index.html",
@@ -9392,7 +9397,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "983d456cff4042137990a5baacb002919c3d213a33f663d6e8fcc7e9f5945ae6"
+      "sha256": "d2b45162be47422810ab7a05c42c9926520df6c1c5ab7e7274386c5a25eb07a3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11432,7 +11437,7 @@
     {
       "path": "tests/migration_allocation.mjs",
       "mode": "0000644",
-      "sha256": "e2f03570b76b4d5af7af3c87a2a4989827eb71d1b50c92ab546a456e85c4024e"
+      "sha256": "0d1bc299555d98aa2ad8571e0a5a185776ca727f95577c3308a7e4b36efbfd97"
     },
     {
       "path": "tests/migration_namespace.mjs",
@@ -11672,7 +11677,7 @@
     {
       "path": "tests/patch_gate_ordering.mjs",
       "mode": "0000644",
-      "sha256": "b0690cf28c30bfa4ef1ecc4ceffa7d4be1666dbb09a6605ceb02cc057d2a9cc4"
+      "sha256": "27a3b5023b6857f3f53734966bc7685757383f2b8dadfa3c0bf1aca2e7db5517"
     },
     {
       "path": "tests/path_match.mjs",

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

@@ -182,7 +182,7 @@ export interface PatchProvisioningInstancesIdDetailResponse { ok: boolean; descr
 export interface PatchProvisioningInstancesIdSettingsResponse { ok: boolean; saved: unknown; planet: unknown; push: unknown }
 export interface PatchTaskRecommendationsIdRequest { status: "declined" | "withdrawn" }
 export interface PatchTaskRecommendationsIdResponse { ok: boolean; recommendation: unknown }
-export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; needs_migration?: boolean; description?: string; title?: string; status?: unknown }
+export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; needs_migration?: boolean; description?: string; title?: string; priority?: unknown; status?: unknown }
 export interface PostAccessRequestsInviteRequest { github_login: string }
 export interface PostAccessRequestsInviteResponse { ok: boolean; already_invited?: boolean; github_login?: unknown; request?: unknown }
 export interface PostAccessRequestsRequest { github_login: string; display_name?: string; note?: string }

package/docs/api/openapi.json

@@ -18880,6 +18880,7 @@
             "minLength": 1,
             "maxLength": 200
           },
+          "priority": {},
           "status": {}
         },
         "additionalProperties": false

package/docs/api-reference.md

@@ -591,7 +591,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/tasks` | `any-builder` | — |  |
 | POST | `/api/bongos/tasks` | `metic+archon` | `version_id`, `title`, `description`, `status`, `touches`, `est_minutes`, `est_cost_usd`, `manual_degree`, `priority`, `automation_tag`, `credits_reward`, `source`, `source_ref`, `value_summary`, `kind`, `discipline`, `parallel_safe`, `newcomer_friendly`, `security_sensitive`, `requires_rank`, `auto_detect_touches`, `criterion_ids`, `module_key`, `goal_id` | Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may … |
 | GET | `/api/bongos/tasks/:id` | `any-builder` | — | single-task read; preserved per CRITICAL §4 (supervisor hot path). |
-| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `needs_migration`, `description`, `title`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
+| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `needs_migration`, `description`, `title`, `priority`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
 | POST | `/api/bongos/tasks/:id/abandon` | `metic+archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
 | POST | `/api/bongos/tasks/:id/attest-gate` | `any-builder` | `head_sha` | POST /tasks/:id/attest-gate — body: { head_sha }. |
 | POST | `/api/bongos/tasks/:id/confirm` | `any-builder` | `verified` |  |

package/docs/module-api-changelog.md

@@ -1687,5 +1687,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.617 with no explicit bump. run 34318552090. (task 1002620)
   1.19.619 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.618 with no explicit bump. run 34320024204. (task 1002620)
+  1.19.620 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.619 with no explicit bump. run 34321089991. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/reranking-a-goals-board.md

@@ -0,0 +1,93 @@
+# Re-ranking a goal's board — the needed-vs-nice rubric
+
+> Written at task 1003750 (2026-09-09), the first whole-goal re-rank the project ran. Read this before re-ranking any board: the rubric is here so it is applied consistently rather than re-invented per session, and the mechanics section records the two traps that made the first pass cost more than the analysis did.
+
+`tasks.priority` is an integer **1–5, where 1 is most urgent**. Two surfaces read it and both take low-as-urgent:
+
+- version progress is weighted `6 - COALESCE(t.priority, 5)` (`migrations/003_pms.sql`), so an unset priority weighs the same as a P5;
+- the session optimizer orders claimable work `priority ASC NULLS LAST` (`src/bongos/optimizer.js`).
+
+So priority is not a label. It steers what every builder is offered first, and an unset one is not neutral — it sits at the bottom.
+
+## The rubric
+
+The axis is **needed vs nice-to-have**, which is deliberately *not* "is this still true" (that is a relevance audit — see [the goal 1000090 one](../audits/<redacted>.md)) and not "how big is it". A task can be tiny and P1, or large and P5.
+
+| Tier | Test | What earns it |
+|---|---|---|
+| **P1** | Bleeding now | A live path is broken, or **reports success falsely**, or finished paid work is being lost. Fix regardless of what else is queued. |
+| **P2** | Needed, not bleeding | A defect with a workaround that taxes every session; a keystone freezing other tasks; a cost window closing on its own. |
+| **P3** | Should do | Real reliability or legibility gain, no forcing function. |
+| **P4** | Nice to have | Consistency, doc nits, cleanups, and work blocked behind a decision nobody has made yet. |
+| **P5** | Nice to have / speculative | Large refactors and research with no forcing function. Also: tasks whose premise is contested and needs an owner call — park them here rather than guessing. |
+
+Three rules that did the most work in practice:
+
+1. **"Reports success falsely" outranks "is broken".** A broken thing gets noticed; a lying one does not. Three of the five P1s on goal 1000090 were only P1 because a tool printed a success it had not verified.
+2. **Read the body, not the title.** [Task 1001479](https://cloudbongos.com/builders#/task/1001479) sat at P1 from June while its own description read *"Trivial, low priority."* Titles drift from bodies; bodies drift from reality.
+3. **A blocked task is not urgent, but its keystone is.** Where five tasks waited on one unwritten ADR, the ADR moved up and the five moved down. Prioritizing the blocked five would have produced five claims that cannot start.
+
+**Sanity check before writing:** a tier list that is mostly P1 has ranked nothing. Aim for a distribution that narrows sharply at the top — goal 1000090's 63 open rows came out 5 / 8 / 27 / 17 / 6.
+
+## Mechanics
+
+**Now:** `PATCH /api/bongos/tasks/:id` accepts `priority` (integer 1–5, or `null` to clear). It did not before task 1003750 — priority was write-once at create and immutable at every rank, which is why the first re-rank had to be SQL.
+
+```bash
+echo '{"priority":2}' > /tmp/p.json
+node scripts/gds/api.js PATCH /api/gds/tasks/1002884 --body-file /tmp/p.json
+```
+
+Two things to know before you batch this:
+
+- **Bulk PATCH is rate-limited to roughly 30 per minute.** A 63-row pass needs pacing, not a tight loop.
+- **`priority` is not settable at the same time as `status`.** Status moves only through its own transition routes (`/promote`, `/confirm`, …); a body carrying `status` is refused outright with `status_not_patchable`.
+
+**The trap that outlives this recipe: a P1 in `backlog` is inert.** Priority orders the *claimable* feed, and `backlog` rows are not in it. On goal 1000090, four of the five P1s were in `backlog`, so the re-rank changed nothing about what builders saw until they were promoted. **Always re-check status after re-ranking** — `/promote` the ones that should be live, and use [`/backlog-review`](../../.claude/skills/backlog-review/SKILL.md) to walk what is waiting on a person.
+
+And before promoting anything into the claimable pool, **check `requires_rank`.** New tasks floor at `xenos` and the auto-derivation has been inert since ADR 0049, so a task about the deploy or authority surface is newcomer-claimable unless someone raised it by hand. Promoting a P1 without checking that is how a deploy-authority design lands in the newcomer queue.
+
+### When the API cannot reach the live board
+
+Core reaches a live instance only through a release plus a pin move (gate 3, [`core-release-pipeline.md`](core-release-pipeline.md)) — so a *newly shipped* route is not callable against production for as long as the pin lags. In that window the board is only reachable by SQL on the control-plane box, and an agent cannot run it (the permission classifier blocks a mutating `sudo -u lars` over ssh, by design — see [task 1003159](https://cloudbongos.com/builders#/task/1003159), which exists to close exactly this gap).
+
+Generate the statements from a checked map rather than typing ids, keep it in one transaction, and **write the revert first** — the prior values are only recoverable if you captured them before the write:
+
+```bash
+node scripts/gds/api.js GET '/api/gds/tasks?goal_id=<goal>&limit=200' --quiet > before.json
+```
+
+Then group the ids by target tier and emit one `UPDATE` per tier, guarded to the goal and to open statuses so a concurrent ship cannot be clobbered:
+
+```sql
+BEGIN;
+UPDATE tasks SET priority=1, updated_at=now()
+ WHERE goal_id=<goal> AND status IN ('ready','backlog') AND id IN (<ids>);
+-- one statement per tier
+COMMIT;
+```
+
+Build the revert from `before.json` the same way, grouping by each row's *original* priority (including a `NULL` group — unset is a real prior value and restoring it as 5 is not the same thing). Verify every id in the map appears in the emitted SQL before running anything; a silently dropped id leaves a row at a priority nobody chose.
+
+## The goal 1000090 pass, as a worked example
+
+All 63 open rows of [goal 1000090](https://cloudbongos.com/builders#/goal/1000090) (working area 4 — Bongos Core distribution), 2026-09-09. 48 of 63 changed; 24 had no priority at all.
+
+| Tier | Tasks |
+|---|---|
+| **P1** | 1002708, 1002714, 1002884, 1003159, 1003200 |
+| **P2** | 1001431, 1002204, 1002205, 1002863, 1002869, 1003526, 1003537, 1003742 |
+| **P3** | 1000380, 1000861, 1000862, 1001219, 1001429, 1001433, 1001436, 1001930, 1002206, 1002531, 1002532, 1002583, 1002617, 1002622, 1002669, 1002707, 1002854, 1002880, 1002900, 1002903, 1003499, 1003502, 1003564, 1003625, 1003647, 1003648, 1003658 |
+| **P4** | 1001311, 1001441, 1001479, 1001641, 1001927, 1001929, 1002049, 1002208, 1002209, 1002842, 1002844, 1002879, 1002882, 1003563, 1003573, 1003651, 1003657 |
+| **P5** | 1002406, 1002413, 1002839, 1002840, 1002841, 1002843 |
+
+The five P1s all said the same thing, which is the finding the exercise produced: **shipped work does not reliably reach users, and the tooling misreports it.** Task 1002884 health-checked the old still-running process and printed "✓ upgrade complete" while live served the previous version; 1002708 and 1002714 leave the pin uncommitted so the next commit silently downgrades live; 1003159 is the owner having no deploy control at all; 1003200 is that nothing checks whether a claimed artifact ever reached a remote, found after three paid tasks turned out to exist only on laptops.
+
+1002406 and 1002413 sit at P5 as *contested*, not as unimportant — ADR 0062 §7 and task 1003740 now point against their premise, so they need an owner's kill-or-re-argue rather than a builder's guess.
+
+## Related
+
+- [`docs/audits/<redacted>.md`](../audits/<redacted>.md) — the relevance pass on the same board. Run relevance first: there is no point ranking a task whose premise is gone.
+- `/backlog-review` — walks `status='backlog'`, which is where a re-rank's P1s often turn out to be hiding.
+- `/priority-session` — reweights the **idea inbox**, not tasks, and writes no priorities. It ends in a recommendation; this recipe is the write.
+- [`core-release-pipeline.md`](core-release-pipeline.md) — why a shipped route is not a live route.

package/modules/lifecycle/db-tasks.js

@@ -272,7 +272,7 @@ async function findTaskBySourceRef({ source, sourceRef } = {}, deps = {}) {
 
 const TASK_SETTER_COLUMNS = new Set([
   'kind', 'discipline', 'newcomer_friendly', 'security_sensitive', 'parallel_safe', 'automation_tag',
-  'needs_migration', 'module_key', 'description', 'title',
+  'needs_migration', 'module_key', 'description', 'title', 'priority',
 ]);
 
 async function updateTaskColumn(id, column, value) {
@@ -339,6 +339,14 @@ async function updateTaskDescription(id, description) { return updateTaskColumn(
 // 1002791) was permanent. Same permission, same audit trail as the body.
 async function updateTaskTitle(id, title) { return updateTaskColumn(id, 'title', title); }
 
+// task 1003750: the third write-once planning field, and the one that steers
+// what gets claimed — version progress is weighted `6 - COALESCE(priority, 5)`
+// and the session optimizer orders claimable work by `priority ASC NULLS LAST`.
+// Set at create and then immutable at every rank, so re-ranking a goal's board
+// (needed vs nice-to-have) had no route at all and had to be done as raw SQL.
+// 1 = most urgent, 5 = least; null clears it back to unset (weighted as 5).
+async function updateTaskPriority(id, priority) { return updateTaskColumn(id, 'priority', priority); }
+
 
 async function updateTaskDiscipline(id, discipline) { return updateTaskColumn(id, 'discipline', discipline); }
 
@@ -936,6 +944,7 @@ module.exports = {
   updateTaskNeedsMigration,
   updateTaskNewcomerFriendly,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskRequiresRank,
   updateTaskSecuritySensitive,
   updateTaskStatus,

package/modules/lifecycle/db.js

@@ -127,6 +127,7 @@ const {
   updateTaskNeedsMigration,
   updateTaskNewcomerFriendly,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskRequiresRank,
   updateTaskSecuritySensitive,
   updateTaskStatus,
@@ -301,6 +302,7 @@ module.exports = {
   disambiguateWorktreeName,
   foldWorktreeName,
   updateTaskParallelSafe,
+  updateTaskPriority,
   updateTaskSecuritySensitive,
   updateTaskAutomationTag,
   updateTaskNeedsMigration,

package/modules/lifecycle/routes/task-write-routes.js

@@ -318,6 +318,14 @@ module.exports = function registerTaskWriteRoutes(router) {
       // briefs naming tables that hard-fail CI). Same shape as create, same
       // task.edit permission, same audit_log trail as a description edit.
       title: { type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
+      // task 1003750: priority was accepted at create and then immutable at every
+      // rank — the same write-once defect title/description carried above. It is
+      // not cosmetic: the DB weights version progress as `6 - COALESCE(priority, 5)`
+      // and the session optimizer orders claimable work by `priority ASC NULLS LAST`,
+      // so a wrong value at create time steers what every builder claims, forever.
+      // A whole-goal re-rank (needed-vs-nice) had no route and had to run as SQL.
+      // null clears it back to unset; the 1..5 bounds mirror tasks_priority_check.
+      priority: {},                                      // 1..5 or null — checked inline
       // task 1002614 (map D-18): DECLARED so strict-mode admits the request far
       // enough to reach the deliberate status_not_patchable hint below (#514) —
       // the hint had been unreachable dead code behind unknown_field since the
@@ -345,6 +353,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasGoalId = Object.prototype.hasOwnProperty.call(body, 'goal_id');
     const hasDescription = Object.prototype.hasOwnProperty.call(body, 'description');
     const hasTitle = Object.prototype.hasOwnProperty.call(body, 'title');
+    const hasPriority = Object.prototype.hasOwnProperty.call(body, 'priority');
     // #514: status is a lifecycle field, not a PATCH-able column — it moves only
     // through the dedicated transition routes. The #506 session tried
     // `PATCH status=ready`, got the generic no_supported_fields error, and had
@@ -356,8 +365,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, priority, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -374,6 +383,16 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (hasParallelSafe && body.parallel_safe !== null && typeof body.parallel_safe !== 'boolean') {
       return res.fail('bad_parallel_safe', { status: 400, message: 'parallel_safe must be true, false, or null' });
     }
+    // task 1003750: bounds mirror the tasks_priority_check DB constraint via the
+    // shared TASK_FIELD_BOUNDS the create schema uses, so the route and the
+    // column can't drift. Integer or null only — a float or "3" would pass a
+    // bare range test and then fail at the column.
+    if (hasPriority && body.priority !== null) {
+      const p = body.priority;
+      if (!Number.isInteger(p) || p < TASK_FIELD_BOUNDS.priority.min || p > TASK_FIELD_BOUNDS.priority.max) {
+        return res.fail('bad_priority', { status: 400, message: `priority must be an integer ${TASK_FIELD_BOUNDS.priority.min}-${TASK_FIELD_BOUNDS.priority.max} (1 = most urgent), or null to clear` });
+      }
+    }
     if (hasSecuritySensitive) {
       // task 990: explicit Archon-only-broadcast flag. Boolean only (no null) —
       // it gates whether ship.js routes the broadcast to the Archon-only
@@ -528,6 +547,15 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasPriority) {
+      try {
+        updated = await db.updateTaskPriority(id, body.priority ?? null);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id priority', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasGoalId) {
       try {
         updated = await db.updateTaskGoal(id, body.goal_id);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.619",
+  "version": "1.19.620",
   "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.619'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.620'; // 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/migration_allocation.mjs

@@ -204,6 +204,7 @@ function shouldReserveMigrationNumber(task) {
         [() => db.updateTaskModuleKey(1, null), 'module_key'],
         [() => db.updateTaskDescription(1, 'edited body'), 'description'], // task 1002647
         [() => db.updateTaskTitle(1, 'corrected title'), 'title'], // task 1002792
+        [() => db.updateTaskPriority(1, 2), 'priority'], // task 1003750
       ];
       for (const [call, column] of setters) {
         const before = seen.length;
@@ -225,10 +226,35 @@ function shouldReserveMigrationNumber(task) {
       'the PATCH schema must declare title with the create-time limits — a title can be rewritten, never blanked'
     );
     assert.ok(/const hasTitle = Object\.prototype\.hasOwnProperty\.call\(body, 'title'\)/.test(routesSrc), 'title is gated like every other field');
-    assert.ok(/&& !hasTitle\) \{/.test(routesSrc), 'a title-only PATCH is a supported request, not no_supported_fields');
+    // Assert !hasTitle is a TERM of the no_supported_fields guard, not that it is
+    // the LAST term: pinning the final position made this red the moment task
+    // 1003750 appended !hasPriority, for a change that kept the stated intent
+    // (a title-only PATCH is supported) perfectly intact.
+    assert.ok(/if \(!hasParent &&[^)]*!hasTitle\b/.test(routesSrc), 'a title-only PATCH is a supported request, not no_supported_fields');
     assert.ok(/db\.updateTaskTitle\(id, body\.title\.trim\(\)\)/.test(routesSrc), 'the write goes through the allowlisted setter');
   });
 
+  // task 1003750: priority was the third write-once planning field (after title
+  // and description above) — accepted at create, then immutable at every rank.
+  // It is the one that steers what gets claimed: version progress is weighted
+  // `6 - COALESCE(priority, 5)` and the optimizer orders by `priority ASC NULLS
+  // LAST`, so re-ranking a goal's board had to be done as raw SQL against prod.
+  await test('PATCH /tasks/:id accepts priority so a board can be re-ranked (task 1003750)', () => {
+    assert.ok(/priority: \{\},\s*\/\/ 1\.\.5 or null/.test(routesSrc), 'the PATCH schema must declare priority so strict-mode admits it');
+    assert.ok(/const hasPriority = Object\.prototype\.hasOwnProperty\.call\(body, 'priority'\)/.test(routesSrc), 'priority is gated like every other field');
+    assert.ok(/if \(!hasParent &&[^)]*!hasPriority\b/.test(routesSrc), 'a priority-only PATCH is a supported request');
+    assert.ok(/db\.updateTaskPriority\(id, body\.priority \?\? null\)/.test(routesSrc), 'the write goes through the allowlisted setter, and null clears');
+    // The bounds must come from the shared TASK_FIELD_BOUNDS the create schema
+    // reads, never a literal 1..5 here — that is how a route and its column drift.
+    assert.ok(/TASK_FIELD_BOUNDS\.priority\.min.*TASK_FIELD_BOUNDS\.priority\.max/s.test(routesSrc), 'priority bounds are shared with the create schema, not re-typed');
+    // Validation must sit ABOVE the first write (the task 1002609 rule this
+    // handler documents): a body mixing a valid field with a bad priority must
+    // commit nothing.
+    const guardAt = routesSrc.indexOf("res.fail('bad_priority'");
+    const firstWriteAt = routesSrc.indexOf('await db.updateTaskKind(');
+    assert.ok(guardAt > 0 && firstWriteAt > 0 && guardAt < firstWriteAt, 'the priority bounds check must run before the first write, not after');
+  });
+
   await test('PATCH /tasks/:id accepts needs_migration so a wrong flag is correctable', () => {
     assert.ok(
       /needs_migration: \{ type: 'boolean' \}/.test(routesSrc),

package/tests/patch_gate_ordering.mjs

@@ -46,6 +46,9 @@ const REFUSALS = [
   // rendered from goalNotOpenRefusal, so the pin looks for the call.
   'goalNotOpenRefusal(goal)',
   "'bad_requires_rank'",
+  // task 1003750: priority joined the PATCH surface; its bounds check is a
+  // validation refusal like the rest, so it must settle before the first write.
+  "'bad_priority'",
   'badKind(res)',
   "'bad_discipline'",
 ];