@bongos/core 1.19.715 → 1.19.725

package/modules/ui-design/skills/stitch-design-taste/SKILL.md

@@ -23,7 +23,7 @@ description: >-
 
 ## Rebuilt from
 
-This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `stitch-skill` entry and its `DESIGN.md`), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325) — the `[stitch-design-taste]` requirement group — and this file is its port under [task 1003327](https://cloudbongos.com/builders#/task/1003327); it implements those requirements from scratch, **no upstream bytes consulted or copied**. The landing shape is [ADR 0220](../../../../docs/adr/<redacted>.md); what a *look* skill is allowed to be is [ADR 0230](../../../../docs/adr/<redacted>.md).
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `stitch-skill` entry and its `DESIGN.md`), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/0198-third-party-skill-vendoring-policy.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325) — the `[stitch-design-taste]` requirement group — and this file is its port under [task 1003327](https://cloudbongos.com/builders#/task/1003327); it implements those requirements from scratch, **no upstream bytes consulted or copied**. The landing shape is [ADR 0220](../../../../docs/adr/0220-an-in-house-rebuilt-skill-is-a-first-party-skill.md); what a *look* skill is allowed to be is [ADR 0230](../../../../docs/adr/0230-a-look-skill-is-a-composition-grammar-the-palette-is-the-pack.md).
 
 What changed in translation, on purpose: the upstream **authored a palette** for the downstream tool — a descriptive name, a hex and a role per token, invented to taste. Here the colour contract is **transcribed, not invented**: it is the instance's thirteen with their real hex values and the roles the instance's `DESIGN.md` already gives them, so the external tool and the built surface cannot diverge. The document it writes uses the platform's own frontmatter shape — the one every look in `modules/ui-design/styles/` carries — rather than a shape of its own, so a document produced here can be read back as a style. Its universal bans (no pure black, no serif in a dashboard, the default UI sans banned) become **defaults the instance's `DESIGN.md` overrules**: Cloud Bongos's own world is a black void, and a document that told the tool otherwise would describe a different product. Its "signature move" of small contextual images set inline between headline words survives as a **hero object** under the owner's rule: a text-free cutout with its provenance sidecar, never a photograph of a screen. Its motion section stays what it always was, an intent brief for whoever writes the code afterwards, and every parameter in it is written to live inside the Kill Switch.
 

package/modules/ui-design/skills/style/SKILL.md

@@ -23,9 +23,9 @@ description: >-
 
 ## First party
 
-This skill has **no upstream**. It was authored for the platform by [task 1003475](https://cloudbongos.com/builders#/task/1003475) from the owner's idea on the style-library sheet: the library ships looks an instance can adopt, and the next step is letting an owner *make* one with Claude beside them. It is not a rebuild, carries no vendored bytes and claims no origin; the two-origin rule for the module's skills is [ADR 0231](../../../../docs/adr/<redacted>.md).
+This skill has **no upstream**. It was authored for the platform by [task 1003475](https://cloudbongos.com/builders#/task/1003475) from the owner's idea on the style-library sheet: the library ships looks an instance can adopt, and the next step is letting an owner *make* one with Claude beside them. It is not a rebuild, carries no vendored bytes and claims no origin; the two-origin rule for the module's skills is [ADR 0231](../../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md).
 
-Why it exists: a look in this library is a **branding pack** ([ADR 0219](../../../../docs/adr/<redacted>.md)) — thirteen colours, two font stacks, a `DESIGN.md` of derived recipes and one specimen. That is a small enough object for an owner to have opinions about and a strict enough one that a wrong guess fails a measurement rather than shipping. What was missing was the loop between the two: the search that shows what already exists, the draft that stays inside the contract, the retune that is arithmetic rather than taste, and the one-line adoption at the end. This skill is that loop, bounded.
+Why it exists: a look in this library is a **branding pack** ([ADR 0219](../../../../docs/adr/0219-a-look-is-a-branding-pack-the-style-library.md)) — thirteen colours, two font stacks, a `DESIGN.md` of derived recipes and one specimen. That is a small enough object for an owner to have opinions about and a strict enough one that a wrong guess fails a measurement rather than shipping. What was missing was the loop between the two: the search that shows what already exists, the draft that stays inside the contract, the retune that is arithmetic rather than taste, and the one-line adoption at the end. This skill is that loop, bounded.
 
 ## What this session is, and is not
 

package/modules/ui-design/styles/README.md

@@ -1,6 +1,6 @@
 # `modules/ui-design/styles/` — the style library: looks as branding packs
 
-A **look** is something a builder or an instance owner picks for a new surface or a whole instance. The library ships looks as **branding packs** ([task 1003323](https://cloudbongos.com/builders#/task/1003323), [ADR 0219](../../../docs/adr/<redacted>.md)): the thirteen colours and the two font stacks of `theme.ui` (the fifteen host-overridable tokens, [ADR 0062 §3](../../../docs/adr/<redacted>.md) / [ADR 0196](../../../docs/adr/<redacted>.md)), a `DESIGN.md` of the look's derived recipes in the frontmatter shape the chrome world uses, and one specimen mock. **Never a fork of a sheet.** The drift tests already prove every served sheet reads only the contract, so a look that needs a sixteenth token is a contract change and an ADR, not a style.
+A **look** is something a builder or an instance owner picks for a new surface or a whole instance. The library ships looks as **branding packs** ([task 1003323](https://cloudbongos.com/builders#/task/1003323), [ADR 0219](../../../docs/adr/0219-a-look-is-a-branding-pack-the-style-library.md)): the thirteen colours and the two font stacks of `theme.ui` (the fifteen host-overridable tokens, [ADR 0062 §3](../../../docs/adr/0062-medusa-instance-model-decoupling.md) / [ADR 0196](../../../docs/adr/0196-chrome-world-token-contract-and-the-landing-sheets.md)), a `DESIGN.md` of the look's derived recipes in the frontmatter shape the chrome world uses, and one specimen mock. **Never a fork of a sheet.** The drift tests already prove every served sheet reads only the contract, so a look that needs a sixteenth token is a contract change and an ADR, not a style.
 
 ## The catalogue
 
@@ -8,7 +8,7 @@ A **look** is something a builder or an instance owner picks for a new surface o
 |---|---|---|---|
 | `chrome-world` | the neutral pack, byte for byte | The canonical entry: one iridescent chrome sculpture in a black void, pale grey paper in light, one warm salmon that lights only the pressable and the live. Its recipes are the repo-root [`DESIGN.md`](../../../DESIGN.md); [`chrome-world/DESIGN.md`](chrome-world/DESIGN.md) points there. | the world round's pick (task 1003296 → 1003298) |
 | `expedition` | warm paper, lamp yellow, Archivo | A printed field journal: a halftone screen over the paper, hairline frames instead of a grid, big heavy uppercase headlines, the yellow as a fill only. [`expedition/DESIGN.md`](expedition/DESIGN.md) | `docs/design/mocks/world/natgeo-editorial` (kept in round 1) |
-| `blueprint` | cool grey-blue paper, cyanotype blue, slate green, IBM Plex Sans | A drafting table under north light: a faint graph lattice on the ground, compartments registered to the board with a crosshair tick at a 2px cut edge, the display voice in sentence case, every figure mono and tabular, one cyanotype blue on what is pressable, a slate green for what was measured and a rust pencil for what went wrong. The library's first cool look. [`blueprint/DESIGN.md`](blueprint/DESIGN.md) | authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/<redacted>.md)) |
+| `blueprint` | cool grey-blue paper, cyanotype blue, slate green, IBM Plex Sans | A drafting table under north light: a faint graph lattice on the ground, compartments registered to the board with a crosshair tick at a 2px cut edge, the display voice in sentence case, every figure mono and tabular, one cyanotype blue on what is pressable, a slate green for what was measured and a rust pencil for what went wrong. The library's first cool look. [`blueprint/DESIGN.md`](blueprint/DESIGN.md) | authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) |
 | `grove` | pale sage, tan, sea green, Nunito | A sculpted paper garden: soft corners on everything that holds content, tinted shadows, the sea as a slab a whole band sits on, the tan as the one lit thing. [`grove/DESIGN.md`](grove/DESIGN.md) | `docs/design/mocks/world/organic-cards` (kept in round 1) |
 
 The owner looked at both alternates on the sheet on 2026-09-01 and kept them ("styles look good for a start"). Both alternates were **retuned against the contract**, which is a measurement and not a taste: a pack's thirteen are laid through three sheets that already exist (the landing's `world.css`, the hub's `cosmos.css`, the hall's `style.css`) and every pair those sheets paint must clear AA under it. The grove's sage ground lifted and its inks deepened until the hub's fixed status vocabulary and the hall's chips cleared; the expedition's `ink-faint` deepened one step. What a pack cannot carry is **dark**: the contract is light values only, and every sheet's dark tier is its own black, which a look reaches through its accent and its faces. So the grove's green dark ground stays in the world round's mock and does not travel.
@@ -51,7 +51,7 @@ SURFACE=modules/ui-design/styles/expedition STYLE=expedition node modules/ui-des
 
 ## Adding a look
 
-The steps below are the manual path. The **`/style` session** ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/<redacted>.md)) walks them with an owner instead: it renders the nearest entries before it asks anything, drafts inside the contract, retunes against the same measurements below with a failure-to-fix table, and hands over the one-step adoption without taking it. `blueprint` was authored that way.
+The steps below are the manual path. The **`/style` session** ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) walks them with an owner instead: it renders the nearest entries before it asks anything, drafts inside the contract, retunes against the same measurements below with a failure-to-fix table, and hands over the one-step adoption without taking it. `blueprint` was authored that way.
 
 1. Make the dir with the three files; start from the alternate nearest to it.
 2. `node modules/ui-design/kit/contrast.js --pack <name>` until the floor is clean; then `node --test tests/ui_design_styles.mjs`, which runs the world / cosmos / hall suites under the pack and tells you the exact pair that fails. Tune the thirteen, never the sheets.

package/modules/ui-design/styles/blueprint/DESIGN.md

@@ -75,7 +75,7 @@ components:
 
 # Style: The Blueprint
 
-**Origin.** Authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../../docs/adr/<redacted>.md)) from a two-line brief: *"a drafting table under north light, cool paper and graphite; one cyanotype blue on what is pressable, a rust pencil for what went wrong."* The library's three existing looks are all warm and all carry a warm accent (salmon, lamp yellow, tan), so the search step found no near neighbour and the session drafted rather than adapted. The retune against the contract took one pass: the pack floor and all three token suites cleared on the first measurement, which is what a cool ground and a deep graphite ink buy you. The candidate's own dark ground does not travel, as with every look: a pack carries light values only.
+**Origin.** Authored through the `/style` session ([task 1003475](https://cloudbongos.com/builders#/task/1003475), [ADR 0231](../../../../docs/adr/0231-the-style-session-an-owner-authors-a-look-inside-the-contract.md)) from a two-line brief: *"a drafting table under north light, cool paper and graphite; one cyanotype blue on what is pressable, a rust pencil for what went wrong."* The library's three existing looks are all warm and all carry a warm accent (salmon, lamp yellow, tan), so the search step found no near neighbour and the session drafted rather than adapted. The retune against the contract took one pass: the pack floor and all three token suites cleared on the first measurement, which is what a cool ground and a deep graphite ink buy you. The candidate's own dark ground does not travel, as with every look: a pack carries light values only.
 
 ## Overview
 

package/modules/ui-design/styles/chrome-world/DESIGN.md

@@ -30,7 +30,7 @@ rounded:
 
 # Style: The Chrome World (the canonical look)
 
-This is the look Cloud Bongos itself runs on and the **first entry** of the style library ([task 1003323](https://cloudbongos.com/builders#/task/1003323)). It is the canonical one in a precise sense: its `pack.json` is byte-for-byte the `theme.ui` block of [`config/branding.neutral.json`](../../../../config/branding.neutral.json), the neutral pack every instance resolves over, and its recipes are **not restated here**. The world's derived tiers, faces, materials, motion grammar, components, Do's and Don'ts and accessibility floors are the repo-root [`DESIGN.md`](../../../../DESIGN.md), recorded from the built landing ([ADR 0196](../../../../docs/adr/<redacted>.md)). Read that file; this one only holds the thirteen so the catalogue's lockstep test has something to hold.
+This is the look Cloud Bongos itself runs on and the **first entry** of the style library ([task 1003323](https://cloudbongos.com/builders#/task/1003323)). It is the canonical one in a precise sense: its `pack.json` is byte-for-byte the `theme.ui` block of [`config/branding.neutral.json`](../../../../config/branding.neutral.json), the neutral pack every instance resolves over, and its recipes are **not restated here**. The world's derived tiers, faces, materials, motion grammar, components, Do's and Don'ts and accessibility floors are the repo-root [`DESIGN.md`](../../../../DESIGN.md), recorded from the built landing ([ADR 0196](../../../../docs/adr/0196-chrome-world-token-contract-and-the-landing-sheets.md)). Read that file; this one only holds the thirteen so the catalogue's lockstep test has something to hold.
 
 ## What this entry is for
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.715",
+  "version": "1.19.725",
   "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/adopt-preflight.js

@@ -11,11 +11,20 @@
 //     floor (ADR 0043, via gate-review.js's canonical matchesHardFloor).
 //   • CI collisions — the repo's workflows vs core's expected unit/secret-scan/
 //     gate-review checks.
+//   • IGNORED incoming files — a pre-existing .gitignore rule that would swallow what
+//     adopt is about to commit (task 1003400). This is the check that was missing when
+//     Cloud Bongos was adopted onto a repo whose .gitignore already carried `.claude/`:
+//     the skills, hooks and settings.json were materialized onto disk and then dropped
+//     by `git add`, so the adopt commit landed 8 files with no methodology surface at
+//     all. Nothing failed, nothing was logged, and every clone of that repo has been
+//     missing its /builder-* commands since. BLOCKING, because the result is a
+//     non-functional instance that looks fine.
 // READ-ONLY: it computes findings; the accept-gate that decides whether to proceed
 // lives in init.js runAdopt. Pure check functions + a thin fs-reading orchestrator.
 
 const nodeFs = require('node:fs');
 const nodePath = require('node:path');
+const { execFileSync: nodeExecFileSync } = require('node:child_process');
 const { filenameViolation, INSTANCE_NS } = require('./migration-namespace');
 const { matchesHardFloor } = require('./gate-review');
 
@@ -79,10 +88,66 @@ function checkCiCollisions(workflows = []) {
   return [{ category: 'ci', severity: SEV.INFO, message: `${workflows.length} existing CI workflow(s); core will ADD its own unit/secret-scan/gate-review checks alongside them — confirm no required-check conflict.` }];
 }
 
+// PURE — [{ path, rule }] of incoming files a .gitignore rule would swallow → findings.
+// BLOCKING: an ignored incoming file is not a style problem, it is silent data loss at
+// `git add` time, and the instance that results is broken in a way nothing reports.
+function checkIgnoredIncoming(ignored = [], { checked = true } = {}) {
+  if (!checked) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'could not run `git check-ignore` here (no git, or not a repo yet) — cannot confirm the incoming files are committable. Re-check after `git init` if adopt lands nothing under .claude/.' }];
+  }
+  if (!ignored.length) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'no existing ignore rule swallows the files adopt writes — they will all reach the commit.' }];
+  }
+  const lines = ignored.map((i) => (i.rule ? `${i.path} (ignored by ${i.rule})` : i.path));
+  return [{
+    category: 'ignored-incoming',
+    severity: SEV.BLOCK,
+    message: `${ignored.length} file(s) adopt writes are IGNORED by this repo and would be silently dropped from the commit: ${lines.join('; ')}. `
+      + 'Adopt would appear to succeed and produce an instance missing that surface — a repo ignoring `.claude/` gets no /builder-* commands on any clone. '
+      + 'Fix the rule (delete it, or add a negation such as `!.claude/` after it), then re-run.',
+  }];
+}
+
+// Which of `incoming` does this repo's ignore rules match? Uses `git check-ignore -v`,
+// which reports the SOURCE RULE for each match, so the finding can name the exact line
+// the owner has to change rather than leaving them to hunt for it.
+//
+// Returns { ignored:[{path, rule}], checked:boolean }. `checked:false` means the probe
+// could not run at all (no git, not a repo) — deliberately distinct from "nothing is
+// ignored", because the two warrant different advice. execFileSync is injectable for
+// tests; git exits 1 when nothing matches, which is a normal answer and not an error.
+function probeIgnoredIncoming({ dir, incoming = INCOMING_PATHS, execFileSync = nodeExecFileSync } = {}) {
+  // Trailing slashes are ours (they mark dirs in the list); git wants plain pathnames.
+  const paths = incoming.map((p) => String(p).replace(/\/+$/, ''));
+  let out = '';
+  try {
+    out = execFileSync('git', ['check-ignore', '-v', '--stdin'], {
+      cwd: dir, input: paths.join('\n'), encoding: 'utf8', timeout: 5000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }) || '';
+  } catch (err) {
+    // Exit 1 = "no path is ignored" (a real answer, stdout empty). Anything else means
+    // the probe itself could not run.
+    if (err && err.status === 1) return { ignored: [], checked: true };
+    return { ignored: [], checked: false };
+  }
+  const ignored = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    // `<source>:<line>:<pattern>\t<pathname>`
+    const tab = line.lastIndexOf('\t');
+    if (tab === -1) continue;
+    const rule = line.slice(0, tab).trim();
+    const pathname = line.slice(tab + 1).trim();
+    ignored.push({ path: pathname, rule });
+  }
+  return { ignored, checked: true };
+}
+
 // Read the repo (migrations, src/bongos, workflows) and run every check. `stack` is the
 // adopt-detect summary (task 2043); we re-read only what the checks need. Returns
 // { findings, counts:{blocking,warning,info}, hasBlocking }.
-function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {}) {
+function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath, execFileSync = nodeExecFileSync } = {}) {
   const listFiles = (rel) => { try { return fs.readdirSync(path.join(dir, rel)).filter((f) => { try { return fs.statSync(path.join(dir, rel, f)).isFile(); } catch { return false; } }); } catch { return []; } };
   const exists = (rel) => { try { return fs.existsSync(path.join(dir, rel)); } catch { return false; } };
 
@@ -105,6 +170,7 @@ function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath } = {})
     ...checkFitnessBoundary({ topLevelDirs: stack.topLevelDirs || [], hasSrcBongos: exists('src/bongos') }),
     ...checkProtectedPaths(INCOMING_PATHS),
     ...checkCiCollisions(workflows),
+    ...(() => { const { ignored, checked } = probeIgnoredIncoming({ dir, execFileSync }); return checkIgnoredIncoming(ignored, { checked }); })(),
   ];
   const counts = { blocking: 0, warning: 0, info: 0 };
   for (const f of findings) counts[f.severity === SEV.BLOCK ? 'blocking' : f.severity === SEV.WARN ? 'warning' : 'info']++;
@@ -118,4 +184,4 @@ function formatPreflight(report) {
   return report.findings.map((f) => `  ${mark[f.severity] || '·'}  [${f.category}] ${f.message}`);
 }
 
-module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };
+module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, checkIgnoredIncoming, probeIgnoredIncoming, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };

package/scripts/gds/audit-rank-roles.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// scripts/gds/audit-rank-roles.js — does the live builder roster hold ONLY the
+// four live ranks? (task 1002873)
+//
+// WHY. `migrations/023`'s CHECK on `builders.rank` still admits twelve legacy
+// values beyond the four live ranks. `governance_002_seed_and_backfill.sql`
+// backfills roles with an INNER JOIN from `builders.rank` to the four seeded
+// `governance_roles`, so a builder sitting on a legacy rank gets NO role row and
+// resolves to ZERO permissions: admitted by threshold under `requireRank`, locked
+// out of everything under the resolver. They are not told why, and nothing about
+// their account looks wrong.
+//
+// That divergence is deliberate — ADR 0151 chose fail-closed, and
+// `tests/governance_parity.mjs` asserts it is strictly a tightening. What was
+// missing is the VERIFICATION. governance_002's comment says "none exist today —
+// verified", a point-in-time manual check that nothing re-runs; the parity test
+// is DB-free by necessity (the unit gate has no Postgres) and says so in the
+// repo; and R114's live proof ran on a scratch DB holding only the four seeded
+// rank-roles, so the production roster was never queried.
+//
+// THIS IS THE RE-RUNNABLE HALF, and it is deliberately NOT fatal at boot. Idea
+// 1000622 records that trap: an assertion that throws on startup turns a data
+// problem on one instance into an outage. This is a standalone read-only script
+// for a nightly/deploy-time caller — it exits 1 so a caller can act, and nothing
+// in the server's boot path requires it.
+//
+// It reports rather than repairs, and that is a decision, not an omission:
+// rewriting somebody's rank is an authority change, and it belongs to an operator
+// who can see who the account is — not to a sweep.
+//
+//   node scripts/gds/audit-rank-roles.js [--json] [--file-idea]
+//
+// Exit codes:
+//   0  every builder holds a live rank
+//   1  at least one builder holds a rank the governance backfill cannot match
+//   2  could not read the roster (no session / network / route absent)
+//
+// `--file-idea` is what makes this a SURFACE rather than another thing nobody
+// runs — the same shape diagram-drift/check.js uses, spawning capture.js so idea
+// filing has one implementation. Without it a nightly deterministic run that exits
+// 1 reports into a log nobody reads, which is the exact criticism this task makes
+// of the status quo.
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const { cliClient, requireSession, cliExit } = require('./cli-lib');
+const { LIVE_RANK_LADDER } = require('../../src/bongos/db-kernel.js');
+
+// findRanksWithoutRoles — the PURE half. Given roster rows and the live ladder,
+// which builders hold a rank that `governance_002`'s INNER JOIN cannot match?
+//
+// Pure + exported because this is the only altitude the repo can test: the unit
+// gate has no Postgres, which is exactly why the gap this script closes went
+// unverified for so long. A DB-free test of the decision is not a consolation
+// prize here — it is the thing that can actually run in CI.
+//
+// A row with NO rank at all counts: NULL fails the INNER JOIN the same way a
+// legacy value does, and reads as "fine" in every UI that renders a blank.
+function findRanksWithoutRoles(rows, liveRanks = LIVE_RANK_LADDER) {
+  const live = new Set(liveRanks);
+  return (Array.isArray(rows) ? rows : [])
+    .filter((b) => b && !live.has(b.rank))
+    .map((b) => ({
+      id: b.id != null ? String(b.id) : null,
+      // The login is what an operator needs to act; it is already visible to any
+      // caller authorised to read the roster, so this adds no exposure.
+      github_login: b.github_login || null,
+      rank: b.rank === undefined ? null : b.rank,
+      status: b.status || null,
+    }));
+}
+
+// summarize — the rank histogram, so a CLEAN run still says what it looked at.
+// A green check that prints nothing is indistinguishable from one that read
+// nothing, which is the failure mode this whole task is about.
+function summarize(rows) {
+  const counts = new Map();
+  for (const b of Array.isArray(rows) ? rows : []) {
+    const key = b && b.rank ? b.rank : '(none)';
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+// Spawn capture.js rather than POSTing here, so idea filing keeps one
+// implementation (the diagram-drift/check.js precedent). Best-effort: a failure to
+// file must not turn a successful audit into a crash — the exit code and stdout
+// still carry the finding.
+function fileIdea(offenders) {
+  const body = [
+    `${offenders.length} builder(s) hold a rank with no matching governance_roles row.`,
+    '',
+    'They resolve to ZERO permissions — admitted by rank threshold under requireRank,',
+    'refused by the permission resolver, and given no reason (ADR 0151 fail-closed).',
+    '',
+    ...offenders.map((o) => `- builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`),
+    '',
+    'Fix: move each to a live rank through the normal rank-change path, which rotates',
+    'the governance role in the same transaction. Not auto-repaired: changing a rank is',
+    'an authority decision, and a sweep is the wrong actor for it.',
+    '',
+    'Filed by scripts/gds/audit-rank-roles.js (task 1002873).',
+  ].join('\n');
+  const tmp = path.join(os.tmpdir(), `rank-roles-audit-${process.pid}.md`);
+  try {
+    fs.writeFileSync(tmp, body, 'utf8');
+    const r = spawnSync(
+      process.execPath,
+      [path.join(__dirname, 'capture.js'),
+        `[rank-roles] ${offenders.length} builder(s) on a rank with no governance role`,
+        '--kind', 'bug', '--body-file', tmp],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }
+    );
+    if (r.status !== 0) console.error('audit-rank-roles: capture.js failed to file the idea — the exit code above still carries the finding.');
+  } catch (e) {
+    console.error(`audit-rank-roles: could not file the idea (${(e && e.message) || e}) — the exit code above still carries the finding.`);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* best-effort */ }
+  }
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  await requireSession();
+  const api = await cliClient();
+  const r = await api.request('GET', '/builders/roster');
+  if (!r.ok) {
+    console.error(`audit-rank-roles: could not read the roster (HTTP ${r.status}).`);
+    console.error('  Needs a session with builder.roster.read. Nothing was checked — do NOT read this as a pass.');
+    return cliExit(2);
+  }
+  // The roster query has no WHERE on `builders`, so this covers every row,
+  // INACTIVE ONES INCLUDED. That matters: a deactivated builder on a legacy rank
+  // is exactly the row a future CHECK-narrowing migration would fail to apply over.
+  const rows = (r.data && (r.data.builders || r.data.roster || r.data)) || [];
+  const offenders = findRanksWithoutRoles(rows);
+  const histogram = summarize(rows);
+
+  if (json) {
+    console.log(JSON.stringify({ checked: rows.length, live_ranks: LIVE_RANK_LADDER, histogram, offenders }, null, 2));
+    return cliExit(offenders.length ? 1 : 0);
+  }
+
+  console.log(`audit-rank-roles: ${rows.length} builder row(s) checked against the live ladder [${LIVE_RANK_LADDER.join(', ')}]`);
+  for (const [rank, n] of histogram) console.log(`  ${String(rank).padEnd(12)} ${n}`);
+  if (!offenders.length) {
+    console.log('\n✓ every builder holds a live rank — the governance backfill can match all of them.');
+    return cliExit(0);
+  }
+  console.log(`\n✗ ${offenders.length} builder(s) hold a rank with no matching governance role.`);
+  console.log('  They resolve to ZERO permissions: admitted by rank threshold, refused by the resolver,');
+  console.log('  and nothing tells them why (ADR 0151 fail-closed).');
+  for (const o of offenders) {
+    console.log(`  - builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`);
+  }
+  console.log('\n  This is a BUILDER NEED, not an outage: move each to a live rank with the normal');
+  console.log('  rank-change path so the governance role rotates in the same transaction.');
+  console.log('  Deliberately not repaired here — changing a rank is an authority decision.');
+  if (process.argv.includes('--file-idea')) fileIdea(offenders);
+  return cliExit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('audit-rank-roles:', (err && err.message) || err);
+    cliExit(2);
+  });
+}
+
+module.exports = { findRanksWithoutRoles, summarize };

package/scripts/gds/build-cli-package.js

@@ -51,6 +51,7 @@ const FILES = [
   'scripts/gds/login.js',
   'scripts/gds/reauth.js',
   'scripts/gds/setup.js',
+  'scripts/gds/device-flow-help.js', // shared leaf: login.js + setup.js both require it (task 1003881)
   'scripts/gds/onboarding-config.js', // lazy dep of setup.js
   'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
   'scripts/gds/preflight.js',
@@ -64,6 +65,7 @@ const FILES = [
   'scripts/gds/recall.js',
   'scripts/gds/cost.js',
   'scripts/gds/release.js',
+  'scripts/gds/worktree-claim-guard.js', // release.js warns through it; pure, zero requires
 
   // Get onto a real environment without installing one: the cloud dev box.
   'scripts/gds/shell.js',

package/scripts/gds/claim.js

@@ -10,7 +10,7 @@
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
-const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName } = require('./cli-lib');
+const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote, detectWorktreeName, cliExit } = require('./cli-lib');
 const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
 const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
@@ -147,10 +147,44 @@ function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
     allowMainCheckout,
     taskId,
   });
-  if (d.verdict === 'allow') return;
+  if (d.verdict === 'allow') return tree;
   for (const line of d.lines) console.error(line);
   if (d.verdict === 'refuse') process.exit(2);
   console.error('');
+  return tree;
+}
+
+// task 1002592 — a failed worktree DETECTION reaches the builder disguised as a
+// claim CONFLICT, and that disguise is the whole of the original bug report.
+// When detectWorktreeName() yields nothing the claim goes up with
+// worktree_name: null; the server's one-active-claim guard keys on the WORKING
+// TREE, so an unnamed claim falls back to the per-session compare and a
+// genuinely-parallel worktree is refused as a duplicate. The builder then hunts
+// for a claim conflict that does not exist.
+//
+// Only speak when null is WRONG. In the main checkout null is the documented
+// correct answer and the refusal is genuine, so a note there would send the next
+// reader down precisely the wrong path — that distinction is the fix, not a
+// detail of it.
+function worktreeDetectionNote(ctx, taskId) {
+  // The caller must have actually PROBED the tree. Without that this cannot tell
+  // "detection failed" from "nobody looked", and guessing would hang a worktree
+  // warning on every refusal rendered by a caller that never had tree info —
+  // including every pre-existing one. Absence of knowledge is not evidence.
+  if (!ctx || !('worktree' in ctx)) return [];
+  const { worktree, isMainCheckout } = ctx;
+  if (worktree) return [];                // named fine — the refusal is genuine
+  if (isMainCheckout === true) return [];  // null is correct here
+  const why = isMainCheckout === false
+    ? 'this IS a linked worktree, so a name was expected'
+    : 'this tree is not recognisable as the main checkout either';
+  return [
+    `  ⚠ This session could not name its worktree — auto-detect returned nothing, and ${why}.`,
+    '     An unnamed claim is compared per-SESSION instead of per-worktree, so a real parallel',
+    '     worktree is refused as a duplicate. That is very likely what you are looking at, and',
+    '     it is a path-detection problem, not a claim conflict. Name it explicitly to rule it out:',
+    `       node scripts/gds/claim.js ${taskId} --worktree <name>`,
+  ];
 }
 
 function captureHeadSha() {
@@ -247,7 +281,25 @@ function claimErrorInfo(r) {
 // string), so every branch below silently missed and the refusal printed as
 // `[object Object]`. Pure (no console / no process.exit) + exported so it can be
 // unit-tested against the real envelope shapes. Returns { lines, exit }.
-function formatClaimFailure(r, taskId) {
+//
+// task 1002592: server-supplied prose (a task title, a flag reason, a hint) is
+// echoed to the operator's terminal by the branches below. It is our own API, so
+// this is hygiene rather than a live threat — but an unbounded string can carry
+// control characters that repaint a terminal, and a runaway one can bury the
+// guidance it was meant to add. Clip to one line, strip C0/C1 controls, cap length.
+const MAX_LISTED_TASKS = 20;
+function clip(s, max = 160) {
+  if (s == null) return '';
+  // eslint-disable-next-line no-control-regex
+  const flat = String(s).replace(/[--Ÿ]+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+// task 1002592: `ctx` carries what the CALLER knows about the tree
+// ({ worktree, isMainCheckout }) so the session-claim branch can tell a real
+// conflict apart from a failed worktree detection. Optional and defaulted — the
+// function stays pure and every existing caller/test keeps working.
+function formatClaimFailure(r, taskId, ctx) {
   const lines = [];
   const { code, message, d } = claimErrorInfo(r);
 
@@ -271,6 +323,7 @@ function formatClaimFailure(r, taskId) {
       ? `Run /builder-ship ${n} (or /builder-release ${n}) first, or open a fresh worktree/session for this task.`
       : 'Ship or release the in-flight claim, or start a fresh worktree/session.')}`);
     lines.push('  One claim per session keeps each ship isolated (task 1642). To work tasks in PARALLEL, open a separate worktree/session per task — each holds its own single claim — or use the hall work board’s multi-select bulk-claim.');
+    lines.push(...worktreeDetectionNote(ctx, taskId));
     return { lines, exit: 1 };
   }
   if (code === 'newcomer_must_ship_first') {
@@ -294,6 +347,26 @@ function formatClaimFailure(r, taskId) {
     lines.push(`  ${d.what_to_do || `Run /builder-ship ${n || '<task>'} (or /builder-release ${n || '<task>'}) first, claim from a separate worktree, or claim with {"bind_session":false} (an unbound claim always coexists).`}`);
     return { lines, exit: 1 };
   }
+  // task 1002592: ADR 0120 part 3's owed-rebase gate refuses EVERY new claim, so
+  // it is the refusal a builder is most stuck behind — and it was the only one
+  // with no branch here, printing as a bare `[REBASE_REQUIRED]: REBASE_REQUIRED`
+  // code echo. The server builds a full way-forward menu for it
+  // (rebaseRequiredHint, task 1003768 — /strand-fix leads because it is the one
+  // exit that works with no GitHub push credential, the DOCUMENTED default
+  // posture) and this surface dropped it on the floor. Name the owed tasks, then
+  // print the server's menu.
+  if (code === 'REBASE_REQUIRED') {
+    const owed = (d.rebaseTasks || d.rebase_tasks || []).slice(0, MAX_LISTED_TASKS);
+    lines.push(owed.length
+      ? `Your queue is gated — ${owed.length} confirmed task(s) are waiting on your rebase:`
+      : 'Your queue is gated — a confirmed task is waiting on your rebase.');
+    for (const t of owed) {
+      lines.push(`  - task ${t.id}${t.title ? `  ${clip(t.title)}` : ''}`);
+      if (t.reason) lines.push(`      flagged: ${clip(t.reason)}`);
+    }
+    lines.push(`  ${clip(d.hint, 600) || 'Clear it with /strand-fix N, or rebase the branch and re-ship — or /builder-release it to give up on one.'}`);
+    return { lines, exit: 1 };
+  }
   if (code === 'ALREADY_CLAIMED') {
     lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
     return { lines, exit: 1 };
@@ -356,6 +429,11 @@ function formatClaimFailure(r, taskId) {
   }
   // Fallback — still readable: the message + code, never a raw [object Object].
   lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
+  // task 1002592: whatever the code, if the server sent a way forward, PRINT it.
+  // REBASE_REQUIRED sat in this fallback with a fully-formed hint in its body and
+  // nothing rendered it. The branches above stay the curated wording; this is the
+  // floor, so the next unmapped code can never be mute the same way.
+  if (d && d.hint) lines.push(`  ${clip(d.hint, 600)}`);
   return { lines, exit: 1 };
 }
 
@@ -488,7 +566,7 @@ async function main() {
   // task 1002579: worktree-per-claim, enforced BEFORE anything happens — before
   // the session check, before the POST. The whole point is that the builder
   // learns at claim time, not from a stranded ship hours later.
-  enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
+  const tree = enforceWorktreeClaim(taskId, { allowMainCheckout: args.includes(ESCAPE_FLAG) });
   await requireSession();
   const wIdx = args.indexOf('--worktree');
   // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
@@ -527,7 +605,7 @@ async function main() {
     if (outcome === 'retry') {
       r = await postClaim();
     } else if (outcome === 'stop') {
-      process.exit(1); // everything already printed; no claim landed
+      return cliExit(1); // everything already printed; no claim landed
     }
   }
   if (r.status === 201) {
@@ -651,9 +729,16 @@ async function main() {
   }
   // Any non-201 comes here. formatClaimFailure normalizes the R01 error envelope
   // and renders the refusal as guidance (task 1476) — one place, unit-tested.
-  const failure = formatClaimFailure(r, taskId);
+  const failure = formatClaimFailure(r, taskId, {
+    worktree,
+    isMainCheckout: tree ? tree.isMainCheckout : null,
+  });
   for (const line of failure.lines) console.error(line);
-  process.exit(failure.exit);
+  // task 1002592: this exit runs immediately after the claim request, which is
+  // exactly where Windows aborts teardown — "Assertion failed: !(handle->flags &
+  // UV_HANDLE_CLOSING)" — turning a refusal's intended exit 1 into 127. Measured
+  // 3/3 aborting before this change. Set the code, let the loop drain (1002734).
+  cliExit(failure.exit);
 }
 
 // Only auto-run when invoked directly (`node claim.js …`); a `require()` (the
@@ -661,8 +746,8 @@ async function main() {
 if (require.main === module) {
   main().catch((err) => {
     console.error('fatal:', err);
-    process.exit(1);
+    cliExit(1);
   });
 }
 
-module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills };
+module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, materializeModeSkills, worktreeDetectionNote };

package/scripts/gds/claude-md-template.js

@@ -12,6 +12,14 @@
 // of a mature instance's CLAUDE.md — the instance grows its own. Coordinates with
 // task 1963 (neutralizing the core's own CLAUDE.md into the portable template).
 //
+// FIRST-RUN SECTION. The template used to open by instructing the agent to run
+// `bongos start` without ever saying the CLI ships inside an uninstalled dependency,
+// so an agent opening a fresh clone followed its first instruction straight into
+// `command not found`. The root README carries the same signpost for humans — but only
+// when the repo had no README to begin with, which an ADOPTED repo always does. This
+// file lands on BOTH paths and loads in full every session, so it is the one place the
+// bootstrap is guaranteed to be read.
+//
 // PURE (branding in → markdown out), so it unit-tests standalone and carries no
 // hardcoded host identity (everything comes from the branding object — R76-safe).
 
@@ -48,6 +56,16 @@ function renderInstanceClaudeMd(branding = {}) {
 
 Read this at the start of every session. Keep it lean — it loads in full every time.
 
+## First run — before any \`bongos\` command
+
+**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency, so until the install completes there is no \`bongos\` command and every instruction below fails with \`command not found\`:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If a \`bongos\` command then still misbehaves, \`bongos doctor\` checks the toolchain and session and prints the fix.
+
 ## What this is
 
 ${ident}