@bongos/core 1.19.658 → 1.19.660

package/.bongos-core.json

@@ -2,23 +2,28 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.658",
-  "core_contract": "1.19.658",
-  "source_commit": "116ba7cf659c5768b1e7ce2196e38becb98d2654",
+  "core_version": "1.19.660",
+  "core_contract": "1.19.660",
+  "source_commit": "5d0f5acbd9c33a29dfff28dfc344af42a4bf53f3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T00:39:52.368Z",
+  "built_at": "2026-09-11T01:39:06.499Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 472,
+    "docs_redacted": 473,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2112,
+    "functional_verbatim": 2113,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2608,
-  "tree_sha256": "c480f8fa183ff4de3cbfefdfe804fe219ab875a0c873e4d9dc8ed1322652e3ae",
+  "file_count": 2610,
+  "tree_sha256": "02c8e791b05c6718bd28b1e66840239f3f3b6ef1cd6d7fff3e6f22598468f4db",
   "files": [
+    {
+      "path": ".claude/skills/ask-for-help/SKILL.md",
+      "mode": "0000644",
+      "sha256": "53dd3df0bc38a8d75de44dfb54f68df4a4f7c288f4f4bf74c84cfc3ae7b23d04"
+    },
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
       "mode": "0000644",
@@ -2772,7 +2777,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "cb99e968645b768fe425af7c6be53f38b5f52e6185f179cee471da9c2f818c45"
+      "sha256": "fb772f5b797986dcfc60120d5bcb3c1097436d0434160028fe0f48f9f450e84e"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2782,7 +2787,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "08320e0ddfd04ab34b258eb3c6e2c4700c5cc209d76efb8becf7c9f65149678b"
+      "sha256": "4ed79e71c0f7543d8189f2c4d0ee3c83c34429b6785beb7ddeaa529b7f5f7576"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4482,7 +4487,7 @@
     {
       "path": "modules/government/catalog.js",
       "mode": "0000644",
-      "sha256": "3d6d6ced85b69bd6086533a0d118e4032037de66a10931cb3fc4a75bd8b6dbdc"
+      "sha256": "ce3dd2f87b0c6fbb1e2c62028bf50679fa8be316546efb6bf398a2afe22a791d"
     },
     {
       "path": "modules/government/config.js",
@@ -7747,12 +7752,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b64a9a59bb6257652b417c5a8c52b901d02915ae5d565b728e29b01f73ee5b01"
+      "sha256": "65abd9c62cd7f323dcc6478d9203b11fcd364e6c86e43e0e11763dfa8812311f"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0c28879af088fa3615bb534b1d545e909d712b2c5676e5f4a6140410c43b21e2"
+      "sha256": "a71aea9196614109127b129b57630118e53dabf98c168c6e7ec291673d27eb86"
     },
     {
       "path": "public-docs/index.html",
@@ -9507,7 +9512,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "25384d0eebd630303512971574f4bbdfa1aebc9680705bff64a34c6dc6e1b4d5"
+      "sha256": "5e1cee6085965844a656e2b5791db19d9cad43770691f4ebb07100787bdbf448"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10842,7 +10847,7 @@
     {
       "path": "tests/government_catalog.mjs",
       "mode": "0000644",
-      "sha256": "74cfbd482b689df40348af3bdaf050f056e216ff18fdd6add4136d4589b7cd92"
+      "sha256": "1058c2c691a05b4db0365fed68794de8cffa2c4af2c97f4e8c91ba197f67cb6d"
     },
     {
       "path": "tests/government_charter_library.mjs",
@@ -10907,7 +10912,7 @@
     {
       "path": "tests/government_parity.mjs",
       "mode": "0000644",
-      "sha256": "7e1cc047dc75b9574bd64329974f8d1ae59b474d8719fbaae00314c7b2cc88e5"
+      "sha256": "0c619508691d41f41b0fbbb1d6939ba9ac7fde2ef4ec08ae7622bfa70bfbf624"
     },
     {
       "path": "tests/government_principals.mjs",
@@ -12634,6 +12639,11 @@
       "mode": "0000644",
       "sha256": "7e4f4270188771f1fc1fa7d68e9730b4562fb772ee9ecbd04b65fd1738ee9795"
     },
+    {
+      "path": "tests/skill_ask_for_help.mjs",
+      "mode": "0000644",
+      "sha256": "02424dd3b9f084d30802d0fde441ad7d6c20edcfbc8172683dc5d94d7d19725b"
+    },
     {
       "path": "tests/skill_docs_unavailable_regrade.mjs",
       "mode": "0000644",

package/.claude/skills/ask-for-help/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ask-for-help
+description: >-
+  Ask a named builder or a craft for help on a task, as a filed collab help request. Triggers: "ask <builder> to help with task N", "get <name> on this", "who can help with N", "I'm stuck on task N", "/ask-for-help".
+---
+
+**Route skill (authoritative).** The core action is `POST /api/gds/help-requests`. Once the addressee and the context are settled, file it and report the id — do not narrate the API.
+
+You are asking a *person* for help on behalf of the current builder. Being asked assigns them nothing: the collab surfaces recommend, they never transfer a claim (ADR 0187 §3). Declining costs them nothing.
+
+## Recognise the ask
+
+"Ask <builder> to help with task N", "can someone artist-side look at this", "I'm stuck on N" — all of these are help requests. **File one before reaching for any other surface.** The failure this skill exists to stop: a session hears "ask X to help" and files a BLOCKER instead, which is the owner's review queue and is not read at `/#/collab` by anyone. Both were needed once (2026-09-10, task 1002068) and only the blocker got written.
+
+## Pick the right surface
+
+| The ask | Surface | Route |
+|---|---|---|
+| "Ask X to help with N" / "I'm stuck" | **help request** — this skill | `POST /help-requests` |
+| "X should pick this up" / "pass N to X" | task recommendation — "you might want to claim this" | `POST /task-recommendations` (`task_id`, `recommended_to`, `reason`) |
+| Work stuck on the owner's decision, credential, or a hand on the box | blocker — see `/blocker-review` | `POST /blockers` |
+
+They are **complementary, not alternatives.** An owner-only task (a credential rotation, a purchase) deserves a blocker *and* a help request addressed to the owner: the blocker parks the task and holds the detail, the help request is what actually reaches them.
+
+## How to use
+
+1. **Resolve the addressee to an id — never guess one.**
+   ```bash
+   node scripts/gds/api.js GET /api/gds/builders/directory
+   ```
+   Match the `github_login` or `display_name` the user named. A name with no match is a question for the user, not a guess — a wrong `needs_builder_id` sends the ask to a stranger.
+
+   Addressing a **craft** instead of a person is the alternative: `needs_craft` is one of `artist`, `builder`, `ideator`, `ui`. It reaches only builders who declared that discipline in their profile, so a craft nobody has declared reaches nobody.
+
+   **Exactly one addressee.** Both fields is a 400 `two_addressees`; neither is `no_addressee`. The refusal body carries the valid `crafts`.
+
+2. **Attach at most one context.** `task_id` **or** `goal_id`, never both (400 `two_contexts`). Neither is allowed — a general "who knows about X" has no context row.
+
+3. **Write `what_is_stuck` so it is answerable without this session** (≤ 4000 chars). The recipient has none of your context. Cover:
+   - what is stuck, in plain words;
+   - why it needs *this* person (rank, access, a call only they can make) — being asked without a reason reads as work being dumped;
+   - the concrete steps, so the ask is actionable rather than a summons;
+   - how to verify it worked;
+   - what has already been tried or ruled out.
+
+   Never put a secret in it — a password, token, or key. If the work involves one, describe the rotation and let them handle the value on the box.
+
+4. **File it.** Write the body to a file first — `api.js` silently drops a positional JSON body:
+   ```bash
+   node scripts/gds/api.js POST /api/gds/help-requests --body-file <path>.json
+   ```
+   ```json
+   { "needs_builder_id": 3, "task_id": 1002068, "what_is_stuck": "..." }
+   ```
+   A 201 returns the row. `no_such_builder` on `needs_builder_id` means step 1 was skipped.
+
+5. **Report it honestly, including the limit.** Give the request id and say where it lands: the recipient sees it at `/#/collab`, which reads `GET /help-requests/for-me`. That is a **pull, not a push** — help requests have no builder-needs notification (task recommendations do). If it is urgent, say so and tell the user the ask waits until that person opens Collab.
+
+6. **Settle it when it resolves** — only the asker can, and an unsettled pile is noise:
+   ```bash
+   node scripts/gds/api.js PATCH /api/gds/help-requests/<id> --body-file <path>.json
+   ```
+   `{"status": "answered"}` when someone helped, `{"status": "withdrawn"}` when it is no longer needed. Check yours with `GET /api/gds/help-requests/mine`.
+
+## Constraints
+
+- **Never claim the task on the recipient's behalf**, and never say they are "assigned" or "on it". They still claim it themselves.
+- **One request per ask.** Re-asking the same person about the same task makes a second open row, not a nudge.
+- **Asking is not privileged** — any builder may file one, and gating it would exclude exactly the newcomers most likely to be stuck.
+
+## Files this skill touches
+
+- Calls: `GET /api/gds/builders/directory`, `POST /api/gds/help-requests`, `GET /api/gds/help-requests/{for-me,mine}`, `PATCH /api/gds/help-requests/:id`
+- Reads: `modules/lifecycle/routes/help-requests.js` (the four routes), `modules/lifecycle/help-requests.js` (the validation rules), ADR 0187 §3 (recommend, never transfer)

package/docs/file-map.md

@@ -383,6 +383,7 @@ tests/
 <!-- BEGIN GENERATED FILE-MAP .claude/skills/ (scripts/gds/gen-file-map.js — do not hand-edit; notes live in docs/file-map.notes.json) -->
 ```
 .claude/skills/
+├── ask-for-help/SKILL.md          ← /ask-for-help — turn 'ask <builder> to help with task N' into a filed collab help request (POST /help-requests): resolve the name to a builder id, one addressee (person XOR craft) and one context (task XOR goal), a what_is_stuck answerable without this session, then settle it; routes the near-neighbours (recommendation vs blocker) and states that the addressed read is a pull, not a push (task 1003826)
 ├── backlog-review/SKILL.md        ← /backlog-review — daily walk of status=backlog, the pre-workable state a human must say go on: splits rows waiting on a PERSON (promote / kill / water) from rows waiting on a live dep TRIGGER (counted, never walked, migration 163) and surfaces rows stranded behind an abandoned dep; runs scripts/gds/backlog-review.js (task 1003746); Metic+
 ├── blocker-review/SKILL.md        ← /blocker-review — daily review of open Bongos blockers (resolve / escalate / note); Metic+
 ├── blocker-solve/SKILL.md         ← /blocker-solve N — drive ONE blocker to done: do the doable parts, hand back owner-only steps, verify, auto-resolve (auto-promotes waiters); Metic+

package/docs/module-api-changelog.md

@@ -1765,5 +1765,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.656 with no explicit bump. run 34546894776. (task 1002620)
   1.19.658 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.657 with no explicit bump. run 34547406494. (task 1002620)
+  1.19.659 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.658 with no explicit bump. run 34550130772. (task 1002620)
+  1.19.660 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.659 with no explicit bump. run 34551485764. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/government/catalog.js

@@ -221,7 +221,7 @@ const PERMISSIONS = [
   // route reads is INERT; a route reading a key with no grant rows 403s everyone.
   // ADR 0174's Consequences record that failure landing on the Government tab
   // itself. So grants lead, routes follow — inside this goal, not across releases.
-  { key: 'board.item.open', system: false, floor: 'metic', guards: 'POST /board/items — put a subject to the board (ADR 0175; a Full Idea window opens automatically on grade pass, so in practice this guards an amendment)' },
+  { key: 'board.item.open', system: false, floor: 'metic', guards: 'POST /government/board/items — put a subject to the board (ADR 0175; a Full Idea window opens automatically on grade pass, so in practice this guards an amendment)' },
   // floor 'xenos' is NOT a mistake and must not be "tightened". Who may vote is
   // the CONSTITUTION's membership predicate, resolved per request from config
   // (ADR 0175 §6) — today `rank:archon`. Encoding that rank here too would fork
@@ -230,7 +230,7 @@ const PERMISSIONS = [
   // is. So the atom says only "this route exists for authenticated builders" and
   // the predicate does the real gating — the `criterion.create` pattern above,
   // where the floor is real but explicitly not the whole gate.
-  { key: 'board.vote.cast', system: false, floor: 'xenos', guards: 'POST /board/items/:id/vote — floor is the coarse gate; board membership is the configured predicate (ADR 0175 §6), checked in-handler' },
+  { key: 'board.vote.cast', system: false, floor: 'xenos', guards: 'POST /government/board/items/:itemId/votes — floor is the coarse gate; board membership is the configured predicate (ADR 0175 §6), checked in-handler' },
   { key: 'task.newcomer_restock', system: false, floor: 'metic', guards: 'POST /tasks/newcomer-restock (ADR 0157, was archon)' },
   { key: 'task.peer_votes.tally', system: false, floor: 'metic', guards: 'POST /tasks/peer-votes/tally (ADR 0157, was archon)' },
   { key: 'goal.reorder', system: false, floor: 'metic', guards: 'POST /goals/reorder (ADR 0157, was archon)' },
@@ -247,7 +247,25 @@ const PERMISSIONS = [
   // ── ownership-scoped + baseline own-work (floor thetes / xenos) ───────────────
   { key: 'task.claim.any', system: false, floor: 'thetes', guards: 'claim the general queue (per-task requires_rank floor still applies)' },
   { key: 'page.view.builder', system: false, floor: 'thetes', guards: 'authenticated hall pages (requireNonXenosPage / requireBuilderPage)' },
-  { key: 'goal.manage.own', system: false, floor: 'metic', scope: 'own', resource: 'goal', guards: 'PATCH /goals/:id/members/:b, POST /goals/:id/transfer — owner/manager, in-handler (ADR 0106)' },
+  // floor 'metic' is real but NOT the whole gate — the `criterion.create` pattern
+  // above, and here the floor is the LOOSER half. Both routes carry requireBuilder
+  // and decide in-handler (authorizeMembershipKindChange / authorizeOwnershipTransfer,
+  // modules/lifecycle/routes/goal-route-authz.js): rank is consulted ONLY as an
+  // Archon bypass, so `actorIsOwner || actorIsManager` admits at ANY rank.
+  //
+  // THE LIVE POPULATION, recorded because a migration must not silently evict it:
+  // a goal's owner is its `created_by` (goal-authz.js isGoalOwner), so a builder
+  // DEMOTED below metic keeps owner authority over goals they created; and a
+  // sub-metic member can be promoted to manager ('lead') on any unprotected goal,
+  // reaching this permission without ever holding metic.
+  //
+  // So when R104-R107 migrates these routes, the gate stays requireBuilder +
+  // resolver.authorizeOwned(key, owner) — a bare permission gate on this key would
+  // 403 exactly the owners and managers the routes admit today. The floor is
+  // deliberately NOT lowered to xenos here (the board.vote.cast option): a floor
+  // feeds RANK_SEED and the live reset route, so widening it is an authority change
+  // that wants its own decision, not a note in a hardening batch.
+  { key: 'goal.manage.own', system: false, floor: 'metic', scope: 'own', resource: 'goal', guards: 'PATCH /goals/:id/members/:b, POST /goals/:id/transfer — requireBuilder + in-handler owner|manager|Archon (ADR 0106); floor is not the whole gate, and sub-metic owners/managers hold it today' },
   { key: 'task.claim.newcomer', system: false, floor: 'xenos', guards: 'claim a newcomer_friendly task (xenosClaimAllowed; xenos = one active claim)' },
   { key: 'task.ship', system: false, floor: 'xenos', guards: '/builder-ship own claim' },
   { key: 'task.act.own', system: false, floor: 'xenos', scope: 'own', resource: 'claim', guards: 'act on OWN active claim (release, cost, notes) — ownership-scoped' },
@@ -261,7 +279,7 @@ const PERMISSIONS = [
   // marker here. Exactly why scope is declared data: the suffix rule only runs the
   // safe direction ('.own' ⇒ scope 'own'), never the converse.
   { key: 'me.wandering.set', system: false, floor: 'xenos', scope: 'own', resource: 'builder_prefs', guards: 'PATCH /me/wandering (clamped by maxLevelForRank) — ownership-scoped' },
-  { key: 'cost.log', system: false, floor: 'xenos', guards: 'POST /costs' },
+  { key: 'cost.log', system: false, floor: 'xenos', guards: 'POST /cost' },
   { key: 'learning.create', system: false, floor: 'xenos', guards: 'POST /learnings' },
   { key: 'blocker.file', system: false, floor: 'xenos', guards: 'POST /blockers' },
   { key: 'idea.file', system: false, floor: 'xenos', guards: 'POST /inbox (own idea capture)' },
@@ -281,7 +299,8 @@ const OWNERSHIP_SCOPES = Object.freeze(['own', 'any']);
 const _byKey = new Map();
 const _byPrincipal = new Map();
 const _byResource = new Map();
-for (const p of PERMISSIONS) {
+for (let i = 0; i < PERMISSIONS.length; i++) {
+  const p = PERMISSIONS[i];
   if (typeof p.key !== 'string' || !p.key) throw new Error(`government catalog: permission missing a key`);
   if (typeof p.system !== 'boolean') throw new Error(`government catalog: ${p.key} missing boolean 'system'`);
   if (p.floor !== null && !RANK_ORDER.includes(p.floor)) throw new Error(`government catalog: ${p.key} has invalid floor "${p.floor}"`);
@@ -320,6 +339,16 @@ for (const p of PERMISSIONS) {
     // floor would seed the key into a rank that the substrate then still denies.
     if (p.floor !== 'archon') throw new Error(`government catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
   }
+  // A system:true key is trust-boundary authority (ADR 0016): it is never grantable
+  // to a custom rank, so the ONLY way a builder holds it is by sitting on a seeded
+  // rank at or above its floor. That makes the floor the whole wall, and the wall
+  // belongs at the top of the ladder. Without this, {system:true, floor:'metic'}
+  // loads clean and governance_002's reset route seeds Archon-only power to Metic.
+  // The two floor:null shapes are the exception and are already partitioned above:
+  // a machine principal is held by NO rank at all.
+  if (p.system && principal === null && p.floor !== 'archon') {
+    throw new Error(`government catalog: ${p.key} is system:true and must floor at 'archon' (a system key is not grantable, so its floor is the whole wall) — got "${p.floor}"`);
+  }
   // ── the OWNERSHIP axis (R100) ─────────────────────────────────────────────
   const scope = p.scope ?? null;
   const resource = p.resource ?? null;
@@ -347,7 +376,15 @@ for (const p of PERMISSIONS) {
   if (scope !== null && p.floor === null) {
     throw new Error(`government catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a RANK permission, never an identity one`);
   }
+  // ONE object per permission, shared by every reader. The frozen copy goes back
+  // into PERMISSIONS[i] as well as the lookup maps, because the alternative —
+  // freezing a COPY and leaving the original mutable in the array — splits the
+  // catalog into two views that can disagree: `Object.freeze(PERMISSIONS)` below
+  // seals the array's SHAPE but not its entries, so a runtime mutation of
+  // PERMISSIONS[i] would change the floor seedForRank() reads (and with it the
+  // live POST /government/ranks/:rankKey/reset) while byKey() kept the old value.
   const frozen = Object.freeze({ ...p, principal, scope, resource, substrate });
+  PERMISSIONS[i] = frozen;
   _byKey.set(p.key, frozen);
   if (principal !== null) _byPrincipal.set(principal, frozen);
   if (resource !== null) {

package/package-lock.json

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

package/package.json

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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.658'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.660'; // 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/government_catalog.mjs

@@ -178,3 +178,16 @@ test('byKey returns a frozen record or null', () => {
   assert.throws(() => { p.system = false; }, /Cannot assign|read only|frozen/i);
   assert.equal(byKey('nope'), null);
 });
+
+// Freezing the ARRAY only seals its shape. Before task 1003194 the entries inside it
+// stayed mutable and byKey() handed out a frozen COPY, so the catalog had two views
+// that could disagree: mutating PERMISSIONS[i].floor moved what seedForRank() reads —
+// and with it the live POST /government/ranks/:rankKey/reset — while byKey() kept the
+// old value. Identity is the assertion that actually forbids that, not depth.
+test('the catalog is ONE immutable object per permission — array, entries, and byKey identity', () => {
+  assert.equal(Object.isFrozen(PERMISSIONS), true, 'the PERMISSIONS array must be frozen');
+  for (const p of PERMISSIONS) {
+    assert.equal(Object.isFrozen(p), true, `PERMISSIONS entry ${p.key} must be frozen, not just the array`);
+    assert.equal(p, byKey(p.key), `${p.key}: PERMISSIONS[i] and byKey() must be the SAME object, not equal copies`);
+  }
+});

package/tests/government_parity.mjs

@@ -163,6 +163,13 @@ const normRoute = (key) => key.replace(/:[A-Za-z0-9_]+/g, ':p'); // :id vs :crit
 // Leading `METHOD /path` of a guards note. Deliberately conservative: a note that
 // lists several routes or wraps them in prose/braces simply doesn't participate.
 const GUARD_ROUTE_RE = /^(GET|POST|PATCH|PUT|DELETE)\s+(\/[^\s,(]+)/;
+// The conservative intent above is enforced HERE, not by the character class: a
+// path carrying `{a,b}` (a brace set), `[/x]` (an optional segment) or `*` (a
+// wildcard) is a PATTERN standing for several routes, not one concrete route, so
+// it cannot be looked up and does not participate. Without this the regex happily
+// captured `/blockers/:id/{resolve` and seven siblings, which then dangled in B0
+// and drowned the three real typos it exists to catch (task 1003194).
+const ROUTE_PATTERN_RE = /[{[*]/;
 // A route's middleware rank → the LOOSEST floor still consistent with it. Only the
 // two rank-gated classifications constrain a floor; 'any-builder' / 'public' /
 // 'unknown' / 'bfg-principal' carry no rank middleware to compare against.
@@ -190,12 +197,17 @@ function crossReference() {
   const live = liveRoutes();
   const floorPinned = [];
   const atomPinned = [];
+  const dangling = [];
   for (const p of FLOORED) {
     const m = GUARD_ROUTE_RE.exec(p.guards);
     if (!m) continue;
+    if (ROUTE_PATTERN_RE.test(m[2])) continue;
     const routeKey = `${m[1]} ${m[2]}`;
     const r = live.get(normRoute(routeKey));
-    if (!r) continue;
+    // A note that names ONE concrete route which does not exist is a typo, and a
+    // silent `continue` here is how it stayed invisible: the entry simply dropped
+    // out of B1 and B3 while all 27 tests stayed green. B0 asserts this is empty.
+    if (!r) { dangling.push(`${p.key} → ${routeKey}`); continue; }
     if (r.perms) {
       atomPinned.push({ permission: p.key, floor: p.floor, routeKey, perms: r.perms });
       continue;
@@ -204,9 +216,27 @@ function crossReference() {
     if (!minFloor) continue;
     floorPinned.push({ permission: p.key, floor: p.floor, routeKey, routeRank: r.rank, minFloor });
   }
-  return { floorPinned, atomPinned };
+  return { floorPinned, atomPinned, dangling };
 }
 
+// The oracles B1 and B3 can only judge a permission whose guards note RESOLVES to a
+// live route. A note naming a route that does not exist therefore fails open — it is
+// dropped, not reported, and the permission silently leaves both oracles while the
+// suite stays green. That is not hypothetical: `cost.log` said 'POST /costs' against
+// a real 'POST /cost', and both Board Room keys omitted the '/government' prefix, so
+// the two newest requirePermission routes sat outside B3 — the very oracle written
+// for them. This test is the fail-loud half (task 1003194).
+//
+// There is deliberately NO allowlist. A note that genuinely cannot name one concrete
+// route does not reach here at all: it either fails GUARD_ROUTE_RE (prose, a surface
+// name like 'planning-session surface') or is a pattern caught by ROUTE_PATTERN_RE.
+// An allowlist would be a place to park the next typo.
+test('B0: every guards note that names a concrete route names one that EXISTS', () => {
+  const { dangling } = crossReference();
+  assert.deepEqual(dangling, [],
+    `guards notes point at routes that do not exist — fix the note (or the route), never ignore it:\n  ${dangling.join('\n  ')}`);
+});
+
 // ONE-DIRECTIONAL, and deliberately so. A floor STRICTER than the route middleware
 // is legitimate and common: the wall lives in the handler (task.confirm.grade_bypass
 // on an any-builder POST /tasks/:id/confirm; goal.manage.own's owner|manager check;

package/tests/skill_ask_for_help.mjs

@@ -0,0 +1,72 @@
+// tests/skill_ask_for_help.mjs — the /ask-for-help skill exists and routes the
+// plain-language ask ("ask <builder> to help with task N") to the collab help
+// request rather than to a blocker (task 1003826).
+//
+// The failure it guards: a session hears "ask X to help with N" and files a
+// BLOCKER — the owner's review queue — while the surface the recipient actually
+// reads (/#/collab → GET /help-requests/for-me) stays empty. So the assertions
+// below are about ROUTING and the constraints the table's CHECKs restate, not
+// about prose.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILL = path.join(ROOT, '.claude', 'skills', 'ask-for-help', 'SKILL.md');
+const NOTES = path.join(ROOT, 'docs', 'file-map.notes.json');
+
+// .claude/skills is INSTANCE-materialized; a neutral core checkout carries none
+// (task 1002470) — skip there, with the same guard shape as skill_grade_recover.mjs.
+const skillsDirExists = existsSync(path.join(ROOT, '.claude', 'skills'));
+
+test('/ask-for-help files a help request and routes its near-neighbours', (t) => {
+  if (!skillsDirExists) return t.skip('.claude/skills not materialized in this checkout');
+  assert.ok(existsSync(SKILL), '.claude/skills/ask-for-help/SKILL.md must exist (task 1003826)');
+  const md = readFileSync(SKILL, 'utf8');
+
+  // The write path, named literally — this is the whole point of the skill.
+  assert.match(md, /POST \/(?:api\/gds\/)?help-requests/, 'names the help-request write route');
+  assert.match(md, /--body-file/, 'files via --body-file (api.js drops a positional body)');
+
+  // Resolve the addressee — never guess a builder id.
+  assert.match(md, /GET \/api\/gds\/builders\/directory/, 'resolves a named builder through the directory');
+  assert.match(md, /never guess/i, 'forbids guessing a builder id');
+
+  // The two XOR rules the table's CHECK constraints enforce.
+  assert.match(md, /needs_craft/, 'names the craft addressee field');
+  assert.match(md, /needs_builder_id/, 'names the person addressee field');
+  assert.match(md, /two_addressees/, 'names the both-addressees refusal');
+  assert.match(md, /two_contexts/, 'names the both-contexts refusal');
+  assert.match(md, /task_id/, 'names the task context field');
+  assert.match(md, /goal_id/, 'names the goal context field');
+
+  // The near-neighbours are routed, not collapsed: a recommendation and a blocker
+  // are different acts, and the blocker is complementary rather than an alternative.
+  assert.match(md, /POST \/task-recommendations/, 'routes the recommendation surface');
+  assert.match(md, /POST \/blockers/, 'routes the blocker surface');
+  assert.match(md, /complementary, not alternatives/i, 'says a blocker and a help request can both be right');
+
+  // ADR 0187 §3 — being asked assigns nobody anything.
+  assert.match(md, /never transfer/i, 'states that the collab surfaces never transfer a claim');
+
+  // The honest limitation: the addressed read is a pull, and help requests have
+  // no builder-needs push (task recommendations do).
+  assert.match(md, /pull,? not a push/i, 'states the pull-not-push caveat');
+  assert.match(md, /help-requests\/for-me/, 'names the addressed read the recipient sees');
+
+  // Settling is the asker's job — an unsettled pile is noise.
+  assert.match(md, /PATCH \/api\/gds\/help-requests\/<id>/, 'names the settle route');
+  assert.match(md, /answered/, 'names the answered status');
+  assert.match(md, /withdrawn/, 'names the withdrawn status');
+
+  // No secret ever goes in the ask.
+  assert.match(md, /Never put a secret/i, 'forbids putting a secret in what_is_stuck');
+});
+
+test('/ask-for-help is described in the generated file map', (t) => {
+  if (!skillsDirExists) return t.skip('.claude/skills not materialized in this checkout');
+  const notes = JSON.parse(readFileSync(NOTES, 'utf8'));
+  assert.ok(notes.skills['ask-for-help'], 'docs/file-map.notes.json must carry a note for ask-for-help');
+});