@bongos/core 1.19.658 → 1.19.659

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.659",
+  "core_contract": "1.19.659",
+  "source_commit": "feb248ee00547956060970a0a2b26b7923f1ef47",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T00:39:52.368Z",
+  "built_at": "2026-09-11T01:18:53.775Z",
   "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": "d533f43caabc05ab3636390cbbe8f63a140b0c0d84321a438dd2f243041f2301",
   "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": "b92613f789d9a907511c2b1490773a86e1c8c2793f90560bfbb8ede7c3b24652"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7747,12 +7752,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b64a9a59bb6257652b417c5a8c52b901d02915ae5d565b728e29b01f73ee5b01"
+      "sha256": "d8f97007999a707d1f1b5cce57a4933594b9abe96061396ac0cf09bb5a22fa5d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0c28879af088fa3615bb534b1d545e909d712b2c5676e5f4a6140410c43b21e2"
+      "sha256": "6498ec4a5891c341fa302772fd0ca40de911494cfee16009186a43208a27c18f"
     },
     {
       "path": "public-docs/index.html",
@@ -9507,7 +9512,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "25384d0eebd630303512971574f4bbdfa1aebc9680705bff64a34c6dc6e1b4d5"
+      "sha256": "b44e546023213b0bedaf19d6685ea25dd9d3da8f61b33296a7d311bb4f459390"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -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,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.658",
+  "version": "1.19.659",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.658",
+      "version": "1.19.659",
       "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.659",
   "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.659'; // 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/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');
+});