@bongos/core 1.19.306 → 1.19.308

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.306",
-  "core_contract": "1.19.306",
-  "source_commit": "bfb69ddea49ebcce6d1d0608dd8e1fc50cc755e2",
+  "core_version": "1.19.308",
+  "core_contract": "1.19.308",
+  "source_commit": "73400ffdb3672b797a1dda57f589d9cc43da2ed1",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T19:41:29.546Z",
+  "built_at": "2026-08-23T20:30:08.216Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1416,
+    "functional_verbatim": 1420,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1760,
-  "tree_sha256": "a2c3f65e69e891c0076d0b10268d3549cfddf8d76d1f320274e86fd833d56013",
+  "file_count": 1764,
+  "tree_sha256": "bfea309c25b9ba974096b8f0572e268ea80238aaf00e23d700adeb9e58458d49",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -97,7 +97,7 @@
     {
       "path": ".claude/skills/builder-ship/SKILL.md",
       "mode": "0000644",
-      "sha256": "bb9075e768b4cbc6142e2b4b24a57f92e9a4ae75d76f6849566082e0c5495d13"
+      "sha256": "78fcb68ce3ff4b1028904acb9d4d0a37dadd8377108fefef248feef010e4c8b1"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -142,7 +142,7 @@
     {
       "path": ".claude/skills/fix-task/SKILL.md",
       "mode": "0000644",
-      "sha256": "2ccc2a59ce44ba21c18db999c86768252b2fa6c8be6fa81f2b00a71eb727e664"
+      "sha256": "59b29fcdf54fe51e85191d1a66be237ef35432b76b26a10ec67e46bf08b4d1d3"
     },
     {
       "path": ".claude/skills/goal-create/SKILL.md",
@@ -1662,12 +1662,12 @@
     {
       "path": "docs/recipes/claude-design-loop.md",
       "mode": "0000644",
-      "sha256": "4f2e7cc445ae05968ba65fcb0c995cb358f144344dcb498047ec753a5a229a39"
+      "sha256": "389dbbbfb7c941315731d533e300b5d43f40a8aac866c5a1c74c32d5be212a22"
     },
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "100a1bd6bde327c60f37727ce85f75cf5539b007473359692de7ab87876c936b"
+      "sha256": "b42d8b4620355bef0e27480b2ddfaa07140e322de988839f0e102f1a1545ac47"
     },
     {
       "path": "docs/recipes/devbox-app-release.md",
@@ -1687,7 +1687,7 @@
     {
       "path": "docs/recipes/figma-design-loop.md",
       "mode": "0000644",
-      "sha256": "0c2c462d59634b9ec0e777d713cbc0bdc5af06408aa8b3717d2afac09c0070f0"
+      "sha256": "6bfee82bddc07a5743316e310dda1e6cb7266fa7805fc1eed67bc8cc17980b46"
     },
     {
       "path": "docs/recipes/gds-db-backup.md",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ab53e6d02f437a24895dd3d04b3e8ef39ddf4257b8c4b2e784a84dd10820adc4"
+      "sha256": "4293f77940579b7c64fa5bc09f5a132c27efb5e4d21ee37a29ee3cf08d60ad88"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c98acd264e43f570b82f0c7c72efb952d6e68758794f4c49a78db06cf44a867f"
+      "sha256": "254eba7acbbc7ba707abfe41dd50f8e83880cf8f93cbe5daff2c88cf02dd46f1"
     },
     {
       "path": "public-docs/index.html",
@@ -5082,7 +5082,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "95574e210b1fd215b10c7664da109b0698b18aa7724daa736bade6d752318f63"
+      "sha256": "5aa658b099b2acda06cdb3aecfe905da7de79f2b12c844faca091ff061454017"
     },
     {
       "path": "scripts/gds/code.js",
@@ -5309,6 +5309,11 @@
       "mode": "0000644",
       "sha256": "75130de4a880fc7d76f5a8d79ed65750238df94847c1ccfdc974188f9300a1e6"
     },
+    {
+      "path": "scripts/gds/go-live.js",
+      "mode": "0000644",
+      "sha256": "05734e21763cc0b0614275efa76b7b68afabee8be93f3f2d797400d6a97e86c1"
+    },
     {
       "path": "scripts/gds/goal.js",
       "mode": "0000644",
@@ -5784,10 +5789,15 @@
       "mode": "0000644",
       "sha256": "087def1396283b19cb8a6deea4cc7f362d7a2f164d496a587220f0a48568aae6"
     },
+    {
+      "path": "scripts/gds/ship-honesty.js",
+      "mode": "0000644",
+      "sha256": "32827178a46cc01c36c422e1adef433be99492e8444a8affbe51e5e8c1e8ce9f"
+    },
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "73c2e91340171d6a9112e869552be17e0f82aeb80a5c680205ac452d34c3ddc4"
+      "sha256": "f3005175abc0ba20e958381df6aee02402267e9956da466386656dd4e86ad8cf"
     },
     {
       "path": "scripts/gds/smoke-batch-claim.sh",
@@ -6242,7 +6252,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "31f8e9579aa3e015fc2c1f819d5d84076db27e831bfb3419ca48141cbcd84038"
+      "sha256": "87cec9eba20525297a298914c20d89882db138f0cdbc5c1ae4a5ce3d285147db"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7159,6 +7169,11 @@
       "mode": "0000644",
       "sha256": "d0d10628a17717fdef505dcf501915ecfcc31a0c99d9e5d4cf6dc06b47d8c883"
     },
+    {
+      "path": "tests/go_live.mjs",
+      "mode": "0000644",
+      "sha256": "90c8cbfd8bf0b446261f9fd837b9b08b1035210f1cbf1f7ff81998ec535c32f1"
+    },
     {
       "path": "tests/goal_abuse_matrix.mjs",
       "mode": "0000644",
@@ -8282,7 +8297,7 @@
     {
       "path": "tests/route_rank_check.mjs",
       "mode": "0000644",
-      "sha256": "1cb0af04d3f0f837ab19c5c821e91ca7a183f2744608d7ee3b79b4886fbbd4ed"
+      "sha256": "bdc58224050392ece492ae8e8f12f62a8934d86e3993e0df5b8cb0aac80602e8"
     },
     {
       "path": "tests/route_validation.mjs",
@@ -8504,6 +8519,11 @@
       "mode": "0000644",
       "sha256": "afdb09a3ee072fea82390a187c12c42d8249fce0ce84644a4b8dff6a643dd009"
     },
+    {
+      "path": "tests/ship_cannot_lie.mjs",
+      "mode": "0000644",
+      "sha256": "82f6f951cc50c34860545be0f309e18a796ebb5baa712ccb341e1fd0dd72a233"
+    },
     {
       "path": "tests/ship_card.mjs",
       "mode": "0000644",
@@ -8552,7 +8572,7 @@
     {
       "path": "tests/ship_smoke_gate.mjs",
       "mode": "0000644",
-      "sha256": "43e2f109ce85e99e71daa4573a6ec4fc591b167fe81ee02f2f73ea1ce84d465c"
+      "sha256": "6ce7bd5d2a8910e201a9869c8a3f22ef210fd4400fbd14777d8d15d13252a97e"
     },
     {
       "path": "tests/ship_upload_skip.mjs",

package/.claude/skills/builder-ship/SKILL.md

@@ -7,7 +7,7 @@ You are shipping a task on behalf of the current builder. Shipping is the moment
 
 ## What this skill does
 
-Runs `node scripts/gds/ship.js <task-id> --notes "..." --summary "..."`.
+Runs `node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt`.
 
 The CLI drives a **three-state lifecycle** with a subagent grader between states (Phase 5, 2026-05-10):
 
@@ -34,7 +34,7 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
 
    **When you see that block, position the sandbox link prominently for the builder.** `ship.js` also emits the deterministic lifecycle card for the `review` stage (an `[otb-card-html] <path>` marker) — if an in-feed visualization tool is available, render that card (its primary action is **Open in sandbox ↗**, the URL); it's the cleanest way to make the link impossible to miss. Either way, surface the URL as its own standalone, clickable line in chat — a clear callout, NOT buried inside a paragraph of command output — and say in one line what to look at. This is the moment the change is ready to review; the link must be impossible to miss. Let the builder open it, review, and suggest changes; iterate if needed. **Only once the builder explicitly approves, re-run with `node scripts/gds/ship.js <id> --approved`** — that records their sign-off as a durable `sandbox_review` fact on the task (who, when, and the content stamp of exactly what was reviewed). Never pass `--approved` yourself without a real human go; the pause + sign-off IS the feature. `--skip-stage` is the escape hatch (use sparingly — the gate exists so unreviewed game changes don't ride straight to prod). Laptop sessions and non-game diffs are unaffected.
 
-2. **Compose the handoff notes (`--notes`)** following the structure in `docs/handoff-template.md`:
+2. **Compose the handoff notes (`--notes-file`)** following the structure in `docs/handoff-template.md`:
    - What shipped (with confidence tags: verified-prod | verified-smoke | implemented-not-verified)
    - What's broken or unverified
    - Manual checks the next session should run first
@@ -52,16 +52,28 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
    - "Sessions can claim work atomically; merge conflicts can't happen across worktrees."
    No jargon, no file paths, no commit hashes.
 
-4. **Run**:
+4. **Run** — write the prose to files and pass the file (task 1003168):
    ```bash
-   node scripts/gds/ship.js <task-id> \
-     --notes "$(cat <<'EOF'
-   ...handoff markdown...
-   EOF
-   )" \
-     --summary "the one-liner"
+   # write notes.md and summary.txt with your editor/Write tool first
+   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
    ```
 
+   **Use the `-file` forms.** Handoff notes are technical prose, so they contain
+   backticks — and a backtick in an inline `--notes "..."` is command-substituted
+   by the shell *before* node runs: the span executes, its output replaces it, and
+   the rest of the argument list is truncated. That is not hypothetical; it shipped
+   a task with **empty notes and no summary**, so the ledger held nothing about a
+   session that had happened (learning 1000197). A file argument is the one form
+   the shell cannot rewrite. `-` reads stdin if you'd rather pipe.
+
+   Inline `--notes "..."` / `--summary "..."` still work for short prose with no
+   backticks, `$`, or newlines. The older documented form —
+   `--notes "$(cat <<'EOF' … EOF)"` — is *also* shell-safe, because the quoted
+   heredoc delimiter suppresses expansion; it is simply easy to get subtly wrong,
+   and when you do the failure is silent. Passing both `--notes` and
+   `--notes-file` is refused rather than resolved by precedence, so nothing you
+   wrote is dropped without a word.
+
    **Never merge a task branch to main before running `ship.js`.** `ship.js` diffs the claim branch against `main`; an already-merged branch yields an empty diff, and the only exits are `--allow-empty` (dead-ends the task at `completed`, requiring an Archon-only confirm) or reverting the merge. Ship from the branch, then let `ship.js` land it. (This trap was hit on tasks 1002417 and 1002419, producing blockers 1000081/1000082 and an ~8.5-hour stall.)
 
 5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**

package/.claude/skills/fix-task/SKILL.md

@@ -39,7 +39,7 @@ Runs the recurring "claim, fix, and ship task NNNN" macro end to end. Its own va
 
 6. **Ship from the claim branch** — see `/builder-ship` for handoff notes, the value summary, and the completion-card rendering contract. In short:
    ```
-   node scripts/gds/ship.js <id> --notes "..." --summary "..."
+   node scripts/gds/ship.js <id> --notes-file notes.md --summary-file summary.txt
    ```
    **Never merge the claim branch into `main` before running `ship.js`.** `ship.js` diffs the branch against `main`; a pre-merged branch yields an empty diff, and the only way out is `--allow-empty` (dead-ends the task at `completed`, needing an Archon-only confirm) or reverting the merge. Ship from the branch and let `ship.js` land it — the same trap `/builder-ship` calls out.
 

package/docs/recipes/claude-design-loop.md

@@ -113,7 +113,7 @@ The adapter writes files to `src/ui/<surfaceId>/` and updates `config/design-sou
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Claude Design export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/docs/recipes/core-release-pipeline.md

@@ -136,6 +136,38 @@ The generic mechanics are [upgrading-the-core](upgrading-the-core.md); this is t
 
 **Cadence: bump once, at session end.** One upgrade covers every release the session landed (publish-on-merge cuts one per merge — you don't chase each). Don't bump per-ship.
 
+### Step 0 — try the one command first (task 1003189)
+
+The whole sequence below is deterministic, so it is also a script. `go-live.js` composes the
+same parts this runbook narrates — `deploy-divergence.js` for the gap, the registry for proof a
+release exists, and `bongos upgrade --registry --commit-pin` for the bump itself — and reports
+once instead of forty times:
+
+```bash
+node scripts/gds/go-live.js
+```
+
+That is **plan-only and read-only**: it prints live-vs-target, checks the registry actually
+carries the target, and names every halt condition it found. Add `--apply` to move the pin.
+
+It **halts rather than guessing** on exactly the things that need judgement — unreleased commits
+on `main`, a registry missing the target, a dirty tree on either end, a failed health check, an
+uncommitted pin. When it halts, fall through to the manual steps below and use your own head;
+that is what the rest of this section is for.
+
+Two flags worth knowing:
+
+- `--verify-marker <path>=<needle>` refuses a target that does not actually contain your change.
+  This is the guard for the trap in Step 1: the carrier sitting on `main` when your fix merged
+  was usually cut *before* it, so deploying "the version main was on" is a textbook-clean go-live
+  that changes nothing — and every downstream check agrees it worked.
+- `--allow-unreleased` downgrades the UNRELEASED halt to a warning. Reach for it only when you
+  have already confirmed *why* main is ahead of its last release.
+
+Host topology (ssh alias, box paths, service names, health URL) lives in a host-owned
+`config/go-live.json`, never in the core — run `node scripts/gds/go-live.js --help` for the
+schema. A core that named one instance's box would not be a core.
+
 ### Step 1 — pick the version (your machine, main checkout)
 
 ```bash

package/docs/recipes/figma-design-loop.md

@@ -98,7 +98,7 @@ The adapter translates frames/text/solid-fill rectangles into `.js` + `.css` fil
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Figma export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.306",
+  "version": "1.19.308",
   "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/scripts/gds/cli-lib.js

@@ -266,6 +266,58 @@ function stripBom(s) {
   return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
 }
 
+// argText(name, args, io) — resolve prose passed EITHER inline (`--notes "..."`)
+// or from a file (`--notes-file path`, or `-` for stdin). Returns
+// { value, source, error }: `value` is a string ('' when neither flag is
+// present), `source` is 'inline' | 'file' | 'stdin' | 'none', and `error` is a
+// caller-printable string when the request was refused or unreadable.
+//
+// WHY THIS EXISTS (learning 1000197). Prose handed to a CLI inline goes through
+// the SHELL first. A handoff note containing backticks — which technical prose
+// constantly does — is command-substituted by bash before node ever runs: the
+// backticked span executes, its output replaces it, and the rest of the argument
+// list is truncated. That is not a theoretical hazard; it silently shipped a task
+// with EMPTY notes and no summary, so the ledger recorded nothing about a session
+// that had happened. A file argument is the only form the shell cannot rewrite.
+//
+// BOTH-GIVEN IS AN ERROR, never a silent precedence. Picking one would mean the
+// caller's other input vanished without a word — the same class of quiet loss
+// this helper exists to end (the capture.js --spark/--full refusal precedent).
+function argText(name, args = process.argv.slice(2), io = {}) {
+  const readFile = io.readFile || ((f) => require('fs').readFileSync(f, 'utf8'));
+  const readStdin = io.readStdin || (() => require('fs').readFileSync(0, 'utf8'));
+  const fileFlag = `${name}-file`;
+  const inline = arg(name, args);
+  // arg() returns undefined (not null) for a flag present as the LAST token, so
+  // presence must be tested separately — otherwise `--notes-file` with no path
+  // slips past the null check and resolves to an empty string, which is the very
+  // silent-empty outcome this helper exists to prevent.
+  const filePresent = args.includes(fileFlag) || args.some((a) => a.startsWith(`${fileFlag}=`));
+  const file = filePresent ? arg(fileFlag, args) : null;
+
+  if (inline != null && filePresent) {
+    return {
+      value: '', source: 'none',
+      error: `${name} and ${fileFlag} were both given. Pass one — ${fileFlag} is the safe form for prose `
+        + '(a shell rewrites backticks in an inline value before node sees it). Refusing rather than '
+        + 'silently picking one, so nothing you wrote is dropped without a word.',
+    };
+  }
+  if (filePresent) {
+    if (file == null || file === '' || file.startsWith('--')) {
+      return { value: '', source: 'none', error: `${fileFlag} needs a path (or - for stdin).` };
+    }
+    try {
+      const raw = file === '-' ? readStdin() : readFile(file);
+      return { value: stripBom(String(raw)), source: file === '-' ? 'stdin' : 'file', error: null };
+    } catch (err) {
+      return { value: '', source: 'none', error: `could not read ${fileFlag} ${file}: ${err.message}` };
+    }
+  }
+  if (inline != null) return { value: inline, source: 'inline', error: null };
+  return { value: '', source: 'none', error: null };
+}
+
 // resolveQuiet(args, env) — true when api.js's stderr status banner should be
 // suppressed: the --quiet flag or the GDS_QUIET env var. Both default to the
 // live process, matching hasFlag()'s own default-args contract. Default OFF —
@@ -853,6 +905,7 @@ module.exports = {
   loadSessionSync,
   saveSession,
   arg,
+  argText,
   hasFlag,
   stripBom,
   repairMsysMangledPath,