@bongos/core 1.19.390 → 1.19.392

package/docs/design/projects-hub-direction-v2.md

@@ -0,0 +1,108 @@
+# The /projects hub, direction v2: the chrome and the card in the chrome world, three versions (task 1003299)
+
+**Date:** 2026-08-27 · **Goal:** 1000080 (Apex UI pass 2) · **Criterion:** `apex-hub-chrome-and-card` (this round is the composition half; the builds are task 1003300, the chrome, and task 1003301, the poster card) · **World:** chrome-blobs, composition A, recorded in `DESIGN.md` from the built landing (task 1003298, ADR 0196).
+
+This document records the hub composition round: what it had to do, how it was run, the three versions put in front of the owner, what each changes on the page beyond its skin, what the build will need that no feed carries yet, and the owner's decision. It supersedes `projects-hub-direction.md` (the 2026-08-13 marigold hub) for the LOOK of the bar, the menus, the search and the card; that document's structural decisions (map first, "only mine" in both browse views, "your projects" as a view, the `?view=` contract, the C1 to C9 build constraints) carry as givens. No build file was touched: `public-landing/projects.html`, `public-landing/assets/cosmos.css`, `DESIGN.md` and every test are as they were.
+
+## 0. Starting point: the hub on the new pack, measured
+
+Rendered on 2026-08-27 through a local stub running the real serving transforms (`docs/design/mocks/hub/` mocks were verified the same way):
+
+- **The bar** (`header.shell`, `cosmos.css:461-538`) is 69px at 1440: the self-typing wordmark at the left; the nav row `Home | Map · Your projects · New project` centred as a pill group; at the right the `Builders' hall` pill (an emoji glyph), a 34px mode toggle, the avatar + login chip and a `Sign out` pill (signed out: the hall pill, the toggle, `Sign in`). It has no ground of its own: the pills float over the sky and a scrim compensates. At 390 it **stacks to 161px** (the mark row, the right-group row, the nav row) and the toolbar adds three more rows (Sky | Table, Only mine, the search), so the sky starts about 300px down. That stack is what the givens retire.
+- **The toolbar** under the bar (`projects.html:413-428`): the `Sky | Table` segmented pill, the `Only mine` switch, the search pill (`#mapQ`, `Search projects by name or description…`, the count `4 projects` inside it).
+- **The sky** on the new pack: black ground (paper in light), the gravity grid, a starfield in dark only, four glossy orbs (`a.worldOrb`, 122px for the platform's own, smaller for the rest) with the name under each, `this platform` in mono under the self orb, the `yours` badge in the accent above an owned orb, the hint rail (`drag pan · scroll zoom · click a project open it`), the footer. The sky, the orbs and the hover card are task 1003258's rule and do not change: the orb is the door, the card is the room.
+- **The table**: a rounded panel with Project / Type / Builders / Runs / Status / Open, the disc at the row's left, `Open ->` pills.
+- **The card** (`projects.html:513-536`): the modal over the sky with the disc, the name at 21px, the tagline, the relationship pill, the facts (Builders / Type / Runs / Owner / Listed) and one `Open site` door. It is the floor of the poster card's degradation ladder: the state every rung degrades to.
+- Since A3 the controls are already Manrope on the pack's grey-paper / black grounds; the shapes and the composition are the marigold pass's.
+
+## 1. The givens (goal 1000080, owner, 2026-08-25 and 26; not re-opened here)
+
+1. One top bar, a real surface with its own ground and a bottom edge, not floating controls; not sticky.
+2. The logo top-left is the way home.
+3. `Projects` moves to the right group and becomes a dropdown holding `Map`, `Your projects`, `New project`; the nav row leaves the bar ("this way we dont clutter the bar").
+4. A profile dropdown on the identity chip: `My projects`, `Sign out`; a `Settings` slot deferred (a place, nothing rendered).
+5. The map search moves into the bar's left group and hides on the views it cannot filter; `#mineQ` untouched.
+6. `Home` is removed.
+7. The Builders'-hall pill leaves the bar and becomes a per-project, member-only affordance on the card (and a glyph on the table row), rendered only where the project's hall address differs from its site address (owner decision (a), 2026-08-26).
+8. The project card is overhauled into the poster card: a 5:2 art banner with the accent disc surviving, the name, the tagline, the relationship pill, up to five faces and an `+N` chip, two figures (builders, shipped in the last 30 days), the facts (Type / Runs / Owner / Listed), the actions (`Open site`, the hall entry), and a degradation ladder down to today's card with everything null.
+
+Not changing: the sky, the orbs, the hover card, the toolbar (Sky | Table, Only mine, the count), the table (except the glyph), the mine view, the new view, the footer.
+
+## 2. Method, as run
+
+1. Code-led (`.impeccable/config.json`: `buildPath: code`); the world is `DESIGN.md`, read and not rewritten; no comps, no images generated (the Higgsfield rule: hero plates only, and the hub has none). The only image in the round is the landing's own social card (`public-landing/assets/world/og-card.jpg`), used as the platform's art on the poster card because the feed carries no art for any project yet.
+2. Two mappers read the page and the tests first: the hub as it is (every id, class, copy string, feed and view-switch, with line refs) and the test contract (which assertion pins what, and which of the eight givens collides with which test when built). Both appendices went to every builder so the proposals could name their collisions instead of avoiding them.
+3. One shared brief: the givens, the two-voices rule from the goal (the bar and the triggers are chrome; the panels and the card are cards), the world's rules from `DESIGN.md`, the token mechanics for a mock (cosmos.css linked for the unchanged regions; the world's derived tier declared on `body` with the dark twins; no `:root`; `--line` and the status vocabulary left to cosmos), a **state contract** of twenty states (every bar state signed out and in, both menus open, keyboard focus, the search focused, the three views, the table, seven card rungs, and three boards: the bar states, the card ladder, the menu component), real data only, the poster card's content, the taste pre-flight, the exact copy strings, and one thesis paragraph per version.
+4. Three builders ran in parallel under `/impeccable` (setup on the surface, the craft floor, the bounded verify rule), each writing one file under `docs/design/mocks/hub/`, each verified through the stub in both modes at 1440 / 390 / 320 across every state (console clean, no overflow, controls at 24px, the bar under 80px, reduced motion dead) and a mechanical rule check (no `:root`, dark twins byte-identical, no literal colour, the state contract, the head comment, the card's vocabulary, the disclosure pattern).
+5. A review pass per version (a fidelity lens over the renders against `DESIGN.md` and the thesis; a measurement lens with a browser: glyph-pixel contrast, control boxes, the keyboard path through both menus, every state, the bar's height and non-stickiness; a code lens over the file), every must/should handed to a skeptic, the survivors fixed in one batch per version, the fixes confirmed.
+
+## 3. The three versions
+
+| # | File | The bar | The menu | The card | Light | 390 | Honest risk |
+|---|---|---|---|---|---|---|---|
+| v1 | `mocks/hub/v1.html` | **The shelf.** The landing's three pill groups set down on a `bg-frame` shelf with a hairline bottom edge, 72px: mark pill, a 46px glass search pill (260 to 340px focused, the count inside it), `Projects` pill + caret, the toggle, the sign-in door or the chip pill | A card: `bg-card`, 16px, hairline edge, 240px, hung 8px under its trigger; 44px lowercase rows; the current view marked by a 6px accent dot; rise + fade 220ms | **The poster as a stack.** The 5:2 banner, the 48px disc half over its lower-left edge, the name at 28px/300, the tagline, a glass relationship pill, five faces + `+N`, a centred two-up figure band, four hairline ledger rows, the landing's door bar (`open site` accent + `builders' hall`) | Paper on paper, told apart by the edge; near-opaque pill tints | One row; the search steps onto a second full-width lip of the shelf; menus drop full width | Closest to what shipped and to the landing, so the least new information; the shelf is one more grey band |
+| v2 | `mocks/hub/v2.html` | **The hairline.** No pill on the bar: the page ground closed by one `rule` hairline, 64px; the mark as plain type; a bare search field with only a bottom hairline (`ink` on focus), the count to its right; lowercase text triggers, the OPEN one underlined in the accent | A full-width **band** that unfolds under the bar and pushes the page down: `bg-card`, hairline bottom edge, three cells each a 24px/300 title over one clause (`the sky of every project`, `the ones you own or build on`, `five questions and a home`); the current cell carries a 2px accent hairline on its top edge; the profile band the same mechanism | **The specimen.** The 5:2 banner with the two figures as leader-line callouts ON the art (feathered grounds, measured 5.9 to 17.9:1), the 54px disc, the name at 32px/300, the relationship as a mono label, faces, a two-column mono ledger, one accent door + `builders' hall` as an underlined text link | Paper with hairlines; nothing inverts; the callout grounds show as soft patches on the art | One 60px row to 320; the search keeps a real narrower field; the bands stack; under 560 the callouts become the two-up band | The boldest reading of the world's structure rule; the band costs 121px of sky while open and the callout patches are visible in light |
+| v3 | `mocks/hub/v3.html` | **The glass strip.** One continuous glass surface over the sky (`void-glass` + blur in dark, a 5% ink tint on paper in light), 64px, a `glass-edge` bottom hairline; the mark, a hairline, the search fused into the plate (no chrome at rest, an inset field on focus), the right end cut into three **segments** by hairlines (`projects`, the toggle, the identity), the open segment filled `glass-strong` | A card-voice panel **welded to the strip's edge** (no top radius, 16px below), 252px, 44px items; the current view marked by a 2px accent bar at its left edge | **The room.** The name and tagline sit on the banner's lower third over a scrim that is a gradient of the card ground (measured 16.97:1 light, 19.01:1 dark); a shelf line across the banner's lower edge holds the disc (with the orb's gloss), the relationship pill and the faces; the figures and the facts are ONE hairline ledger (builders, shipped in 30 days at figure scale, then Runs / Owner / Listed); a full-width door bar | A tint over paper, hairlines only; the art itself stays a photograph (dark) above a paper card | One plate to 320; the search keeps a field taking the plate's slack; the segments keep 44px; panels drop to the strip's width | The most "one surface" and the most different from the landing's pills; the given's "its own ground" is satisfied by glass, which the owner may read as floating; a dark photograph on a paper card is the one ungraded image in light mode |
+
+All three: the sky, the orbs, the hover card, the toolbar (Sky | Table, Only mine), the table (plus the hall glyph in the existing Open cell), the mine and new views and the footer verbatim from today's page; the same real data (the platform's own project with the landing's social card as its art, nine builders holding credits, `30+` shipped in 30 days at the feed's cap; Example with no art, 13 builders and a real 0); the twenty states and the three boards; every render clean in both modes at 1440 / 390 / 320 with reduced motion dead; the mechanical rule set green.
+
+### 3.1 What the review found, and what was fixed before the owner saw the sheet
+
+Each version was reviewed by three independent lenses (a design director over the renders against `DESIGN.md` and the version's thesis; a verifier with a browser measuring glyph-pixel contrast, control boxes, the keyboard path through both menus, all twenty states, the bar's height and non-stickiness; a senior front-end reviewer over the file), 136 findings in all (37 must, 62 should, 37 nit); every must and should went to a skeptic (99; 15 refuted, 84 survived), the survivors were fixed in one batch per version and the batch confirmed by a fresh measurement. What changed:
+
+- **v1** (24 survived, 14 applied, confirm clean): the search pill carried two focus indicators and painted a ground-coloured slug on focus (now one two-tone ring on the pill's `:focus-within`, the whole 46px pill a `<label>` for the field); the `Type` fact never rendered on any rung (Example now shows `Type / Game`, the platform pair-hides it, which is the only rung that proves pair-hiding both ways); the banner crop cut the landing's headline in half and repeated a door pill above the card's own doors (re-framed on the chrome, identical 2.5:1 crop on every art rung); every fact row's hairline broke into two misaligned segments (one rule per row); signed-out states still claimed membership (two `you build here` badges and the self pill; now gated on auth); the current-view mark stayed on `Map` in the mine and new states; the card overflowed short viewports with no scroll (the scrim scrolls under 820px tall); `--label-face` never reached the facts (specificity); the boards restyled the components they exist to compare. Findings recorded, not fixed: `id="cardBuilders"` leaves the facts when Builders becomes a figure, which breaks `projects_hub.mjs:496-498, 586-602` (the build keeps a hidden dt/dd pair or moves the assertion); the LIGHT paragraph's "nothing black on a light page" is not true of dark art on a paper card (see v3's proposal).
+- **v2** (25 survived, 12 applied, confirm found two regressions, closed in a second batch): the hall glyph is now on the platform row only with seven cells on every row; one focus ring on the search; the dt/dd hairlines meet; the band's cells are real targets. **Closed 2026-08-28 (second batch, confirm clean):** the callout ground is one patch per callout, solid to 10px past every glyph edge and feathered by a token-only mask, not a shadow (the caption measures 7.04:1 light / 10.45:1 dark under every column, the figures 17.1 / 19.2; the first batch had thinned it to 1.61 / 3.11, and one patch per figure and one per caption had stacked into a stepped slab); under 480 the search folds into a 44px magnifier that drops one hairline row of the page ground under the bar with the full-width field and its count (a typed query at 320 sits in a 196px field, focus lands on it, Escape or an opening menu folds it; the bar had left 45px for the field, and no floor fits beside four controls); and `Runs` is the address on every rung (Example: example.com), the table keeps the module list.
+- **v3** (35 survived, 17 applied, confirm clean but two nits): the search pill takes the shared two-tone ring; the current-view mark follows the view across the six states; the seven board labels paint in both modes; the strip's light tint separates from the paper by its edge in the measured band; the signed-out states drop the membership claims; the card's scrim keeps the name at 16.97:1 light / 19.01:1 dark. Two nits, closed 2026-08-28: the close button is sticky inside the scrolling card (still in view at 320 × 568 with the door reached); the tray around a lone door goes, so the pill stands alone on the ladder's short rungs.
+
+Every version ends `ALL CLEAN` on the render (all states, both modes, 1440 / 390 / 320, reduced motion dead) and `ALL RULES PASS` on the mechanical check after its batch. The refuted findings (15) were either by-design behaviour the brief asks for, a given the reviewer re-opened, or a measurement the skeptic could not reproduce.
+
+## 4. Review
+
+Open `docs/design/mocks/hub/hub-sheet.html` in a browser from the checkout. Dark is the default; flip to light. The **state** picker shows the same state in every version's first tile (signed out, signed in, each menu open, keyboard focus, the search with a query, the mine and new views with the search gone, the table with the glyph); the **card** picker walks the ladder in the second tile. The two phone tiles show the menu open and the card at 390. Under each version the three **boards** put every bar state, every card rung and the menu component on one tall page, so a version can be read whole without clicking. `open full` walks any state at full size; the head comment of each version states its thesis, its bar, its menu, its card, its light answer, its 390 answer, what changes beyond the skin, its data and its tokens.
+
+## 5. Beyond the skin: what each version changes on the page, and what it proposes
+
+Every item is tagged as the builders tagged it: **given** (one of the eight), **consequence** (follows from a given), **proposal** (the version's own). Test collisions are named from the test map so the build can retarget rather than discover.
+
+**Shared by all three (consequences of the givens):**
+- The nav row's height returns to the sky; at 390 the bar goes from a 161px stack to one 56 to 60px row and the sky starts about 244px higher. `.field{height:calc(100vh - 232px)}` assumed the old bar and a three-control toolbar; retarget.
+- The toolbar keeps `Sky | Table` and `Only mine`; `#mapCount` travels with the search into the bar (`4 projects` at rest, `1 of 4` under a query). `projects_hub.mjs:389,393` pin the computation, not the wording; the copy registry regenerates.
+- The relationship pill loses the accent (it states a fact and is not pressable: the One Warm Thing Rule); the PAIRS rows for `.cardRel` / `.tbl .pill` retarget.
+- The hall glyph rides inside the existing `.colGo` cell beside `Open ->`, so the six-cell parity test (`projects_hub.mjs:531-535`) never fires.
+- The mark is the landing's static bongo-glyph + name pill/type. **This retires the self-typing wordmark** (`cloud|bongos`), which the 2026-08-13 pass kept on purpose as the carrier of the "type bongos in any AI" metaphor and which is frozen by `projects_hub.mjs:116-134, 400-434`. All three builders read given 2 ("the logo") as the landing's mark; the owner should say whether the typing stays. If it stays, it types inside the mark's slot in any version.
+- The table's "could not ask" mark is an em dash, banned by the taste rule the card already obeys; the mocks render a middot (`projects_hub.mjs:564-580` pins the dash).
+- One first-level heading per document (today's page carries ten `<h1>`s, one per view); the view headings become `<h2>`.
+- The contract's `in-table` wording ("glyph on every member row") contradicts given 7 ("only where the hall address differs"): Example is a member row whose hall is at its own site. v1 built the given (glyph on the platform row only), v2 and v3 built the wording and flagged it. **Recommendation: address-gated in both places**, one rule for the glyph and the card door.
+
+**v1 proposes:** `About` (goal 1000063) as a fourth Projects-menu item under a hairline; the card at 560px (cosmos's `min(420px,100%)` today) with `--shadow-card` dropped; `Runs` as the project's address on the poster while the table keeps the module list (`projects_hub.mjs:586-602` pins Runs = tags); the mine view's empty state as a hairline instead of a 2px dashed box; the status cell's `not checked` in place of `• —`.
+
+**v2 proposes:** the toolbar as a second hairline row under the bar; the mine view's empty state as a band of the same grammar; `About` as a fourth cell of the band; the card at 560px; `Runs` as the address on every rung (the table keeps the module list); under 480 the search folded into a 44px magnifier that drops one hairline row under the bar with the full-width field and its count (a 320 bar cannot hold a query beside four controls, and the row is this version's own grammar); the three carried controls under the 24px floor (footer links, the table's `all:unset` sort buttons, the `.search` inputs) floored (`projects_hub_pre_uat.mjs:430-433` pins the sort button rule verbatim).
+
+**v3 proposes:** the card at 640px on desktop ("the room earns it"); the hover card taking the panel's glass instead of `--bg-card` + `--shadow-card` (the world has no shadow vocabulary for UI); the search finding by tag as well as by name; the table view scrolling inside its own panel under 500px (today `body{overflow-x:hidden}` makes Status and Open unreachable on a phone); the wizard's bongo pair on the `--chrome-*` / `--skin-*` ramp instead of its marigold hex literals; a decision on dark project art over a paper card in light mode (accept photographs as exempt, or matte them).
+
+## 6. What the build needs that the page does not have yet (recorded so the pick is informed; not design questions)
+
+These were found by the test and page mappers and confirmed against the feeds; they belong to tasks 1003300 / 1003301, not to this round.
+
+- **No feed carries a per-project hall address.** `clientBranding()` deliberately withholds domains and `{{buildersOrigin}}` is one value per instance, so "hall entry only where the hall address differs from the site address" needs a new field on `/api/bongos/projects/featured` (or `/my-projects`), e.g. `hall_origin`, null where the hall is at `<site>/builders`. On the apex the hall is `builders.cloudbongos.com` (differs); on a child it is `<site>/builders` (same).
+- **No feed carries faces or a 30-day count.** The enrichment (`modules/platform-identity/project-stats.js`) returns `builders`, `tags`, `owner`, `owner_avatar`; the faces need the remote leaderboard's avatar rows kept (the count already comes from them), and `shipped_30d` needs the remote `/api/gds/public/recent-shipped` (row-capped at 30, hence the `N+` rule). `art_url` is already on the feed and is read by nothing.
+- **Tests that pin the retired chrome and must be retargeted in the build** (from `tests/projects_hub.mjs`, `tests/projects_hub_pre_uat.mjs`, `tests/landing_page.mjs`): the `Home` link (`projects_hub.mjs:40, 46, 48`), the hall pill's `data-link-hall href="{{buildersOrigin}}"` (`landing_page.mjs:214-220`, `projects_hub.mjs:105`), the `.shell .navrow` rule in cosmos (`projects_hub_pre_uat.mjs:203`), the card's slice rule (`projects_hub.mjs:487`: the first adjacent `</div></div>` ends the slice, so every new card region must be a direct child and the banner a bare `<img>`), the `<td>` count across the header, `#selfRow` and the row template if the glyph becomes a cell (`projects_hub.mjs:531-535`), and the singular `querySelector('[data-nav="mine"]')` at `projects.html:5307` (a `My projects` item with `data-nav="mine"` would be a second node; hide by `querySelectorAll` or hook it differently). The dropdown items keep `href="?view=map" data-nav="map"` (etc.) as adjacent attributes so `projects_hub.mjs:42-43` holds unchanged. A new bar-ground token goes into cosmos with both dark twins and a `PAIRS` row in `tests/cosmos_token_contrast.mjs`.
+- **Copy.** Every string that changes on the built page re-runs `node scripts/gds/copy-inventory.js` (CI checks the registry).
+
+## 7. The owner's decision
+
+**2026-08-28: v2, the hairline.** Move forward with v2's bar, menus, search and card ("in terms of template preference I would say the hairline is the best to move forward with"); v1 and v3 stay on disk as built. The raises and rulings made with the pick:
+
+- **The self-typing wordmark lives on the landing only** ("can probably only live on the landing page"). The hub carries the static mark, the bongo glyph and "Cloud Bongos" as plain type, as all three mocks did; `projects_hub.mjs:116-134, 400-434` retarget to the static mark, and the "fixed slot measured via `#markMeasure`" line in task 1003300 is void on the hub.
+- **Sky and Table become two views in the Projects menu**: Sky / Table / Your projects / New project (+ About under a hairline, §5). The `Sky | Table` pill leaves the toolbar. **Only mine moves beside the search in the bar as a filter**, member-gated as today. With `#mapCount` already in the bar, nothing is left in the toolbar row: it goes, and the sky starts under the bar's hairline. Retargets on top of §6: `.field{height:calc(100vh - 232px)}`, the `#sub-sky` / `#sub-table` `aria-pressed` pins, the `.switch` placement, and the menu-item pins (`Map</a>` becomes `Sky</a>` + `Table</a>`) in `tests/projects_hub.mjs`; the copy registry regenerates.
+- **The map's look improves beyond this round**: the planets as **templates** styled like the landing's hero blocks (the chrome-world objects, in different colours, shapes and styles), plus the field itself, filed as its own task, task 1003319, under this goal after 1003300.
+- **The §5 proposals travel with the version** unless the owner strikes one: the toolbar as a hairline row (moot: the toolbar goes), the mine view's empty state as a band of the same grammar, `About` as a cell of the band, the card at 560px, the three under-floor controls floored, `Runs` as the address on every rung (the table keeps the module list), the search folded into a magnifier under 480.
+- **Not ruled on, adopted by recommendation until the owner says otherwise**: the hall glyph and the card's hall door are address-gated in both the table and the card (given 7's reading, one rule); dark project art on the paper card in light mode is accepted as photographs are, no matte.
+
+The criterion `apex-hub-chrome-and-card` moves to the builds: task 1003300 (the chrome, now with the Sky / Table menu, the Only mine filter in the bar and no toolbar), task 1003301 (the card), and task 1003319 (the planets and the field). Both build tasks carry the pick as an amendment to their descriptions (written 2026-08-28).
+
+## 8. What carries forward
+
+- **Task 1003300** builds v2's bar, menus (Sky / Table / Your projects / New project) and search, with Only mine beside the search and the toolbar retired, into `public-landing/projects.html` + `cosmos.css` (the hub's sheet moves onto the world's derived tier the way `world.css` did, keeping `--line` and the status vocabulary), retargets the tests in §6, regenerates the copy registry.
+- **Task 1003301** builds the picked card and its ladder, adds the enrichment fields (§6) inside the same `Promise.allSettled` with the shared null object, gates the hall entry on the new hall-address field and membership, and keeps the orbs and the hover card untouched.
+- The unpicked versions stay on disk as built and verified; what they leave behind is listed per version in §3.

package/docs/file-map.md

@@ -152,7 +152,7 @@
 │       ├── discord-channels.js  ← Archon CLI: plan/apply the Discord channel layout via the API (ADR 0036, #727)
 │       ├── setup.js             ← one-time GitHub Device Flow → ~/.config/otb/gds-session.json
 │       ├── start.js             ← list claimable tasks + active claims (`/builder-start`)
-│       ├── claim.js             ← atomic POST /api/gds/claims (`/builder-claim`); prints the claim-time context pack incl. next-free ADR/migration numbers (V4.R26); printDisciplineMode() reads discipline-modes.json to route a claimed task to its playbook skill
+│       ├── claim.js             ← atomic POST /api/gds/claims (`/builder-claim`); runs the worktree-per-claim guard (worktree-claim-guard.js) BEFORE the session check and the POST; prints the claim-time context pack incl. next-free ADR/migration numbers (V4.R26); printDisciplineMode() reads discipline-modes.json to route a claimed task to its playbook skill
 │       ├── discipline-modes.json ← discipline→operating-playbook map read by claim.js: ideator→/ideate, artist→/paint, engineer→/dev; absence of an entry = the default build-and-ship loop, fail-open ([#1267](https://example.com/builders#/task/1267))
 │       ├── next-number.js       ← deterministic next-free ADR + migration number from origin/main ∪ local working tree; supersedes the drift-prone claim-time DB counter (V4.R26, [#964](https://example.com/builders#/task/964)). `node scripts/gds/next-number.js [--json]`
 │       ├── gen-repo-map.js      ← Path B (ADR 0063, [#1224](https://example.com/builders#/task/1224)): zero-dep, deterministic symbol-skeleton generator → docs/repo-map.md + the generated factual block in each nested CLAUDE.md; ranks exported symbols by reference frequency. `--check` = CI gate; regenerated on deploy by ship.js regenerateRepoMap()
@@ -181,6 +181,7 @@
 │       ├── recall.js            ← `/recall` CLI: two-call progressive-disclosure search (summary → `--expand <id>`) over Bongos retrieval layer (ADR 0060); `node scripts/gds/recall.js <query>`
 │       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills. Task 1002927 / R151 taught it the GRADES: `--full --fields-file f.json` files a Full Idea, `--spark` is capture-then-mark (two requests — the route refuses a pre-marked capture), and after a plain quick capture it OFFERS to develop further. That offer is TTY-gated (`--no-prompt` too): capture.js is run by agents with no terminal and reads its body from stdin, so an unguarded prompt would hang every non-interactive caller
 │       ├── spark.js            ← (tasks 1002920 / R144 + 1002921 / R145 + 1002922 / R146) the whole spark handoff from the terminal: mark one of your OWN quick ideas as a Big Idea Spark (`--undo` withdraws it), `--list` is the SPARK QUEUE, `--template` prints the five Full Idea fields, `--develop <id> --fields-file <json>` is the PICKUP (any builder; author + developer both recorded). Author-only server-side for the mark (it is the consent); its own command because sparking acts on an EXISTING idea, which is why capture.js refuses grade='spark'
+│       ├── worktree-claim-guard.js ← (task 1002579) the PURE decision behind worktree-per-claim, enforced at claim time: claiming in the MAIN CHECKOUT is refused (escape hatch `--here` → loud warning), a linked worktree passes, an unclassifiable tree fails open. Stops the ship-time "the main checkout is on <branch>, not main" strand at its cause
 │       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.390",
+  "version": "1.19.392",
   "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/claim.js

@@ -2,7 +2,7 @@
 // Builder claim — atomically claim a task.
 //
 // Usage:
-//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]
+//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]
 //
 // On success: prints the claim id, the task title, and the touches[] so the
 // builder knows the parallel-safety boundary they're working within.
@@ -13,8 +13,9 @@ const path = require('node:path');
 const { cliClient, requireSession, fmtTouches, printOnboardingNudge, rewardPolicy, costPlusOnlyNote } = require('./cli-lib');
 const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
-const { contextPack, formatContextPack } = require('./context-pack');
+const { contextPack, formatContextPack, resolveWorktreeRoot } = require('./context-pack');
 const { printClaimRecall } = require('./claim-recall');
+const { decideWorktreeClaim, ESCAPE_FLAG } = require('./worktree-claim-guard');
 // task 1003153 — the DEAD dependency edge, one definition shared with the route
 // and the detector. A lifecycle CLI may require the lifecycle module directly
 // (the documented exception in modules/lifecycle/CLAUDE.md).
@@ -81,6 +82,34 @@ function printDisciplineMode(task) {
   }
 }
 
+// task 1002579 — the I/O half of the worktree-per-claim guard. Probes the tree
+// with resolveWorktreeRoot (the same signal the context pack and skill-preflight
+// read, so there is one answer to "is this the main checkout") plus the current
+// branch, hands both to the pure decision, prints it, and exits 2 on a refusal.
+// Every probe failure degrades to isMainCheckout=null, which the decision treats
+// as allow — a guard that cannot see the tree must never block a real claim.
+function enforceWorktreeClaim(taskId, { allowMainCheckout }) {
+  let tree = { isMainCheckout: null };
+  let branch = null;
+  try {
+    const runGit = (a) => execSync(`git ${a.join(' ')}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    tree = resolveWorktreeRoot({ runGit, cwd: process.cwd() });
+    branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']).trim() || null;
+  } catch (_) {
+    /* fail-open: an unclassifiable tree is allowed through */
+  }
+  const d = decideWorktreeClaim({
+    isMainCheckout: tree.isMainCheckout,
+    branch,
+    allowMainCheckout,
+    taskId,
+  });
+  if (d.verdict === 'allow') return;
+  for (const line of d.lines) console.error(line);
+  if (d.verdict === 'refuse') process.exit(2);
+  console.error('');
+}
+
 function captureHeadSha() {
   try {
     return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
@@ -423,13 +452,17 @@ async function runGoalJoinFlow({ api, d, taskId, assumeYes }) {
 }
 
 async function main() {
-  await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]');
+    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join] [--here]');
     process.exit(2);
   }
+  // 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) });
+  await requireSession();
   const wIdx = args.indexOf('--worktree');
   // Explicit --worktree always wins; otherwise auto-detect a linked worktree so
   // parallel worktrees off one login each hold their own claim (the server guard

package/scripts/gds/worktree-claim-guard.js

@@ -0,0 +1,104 @@
+// scripts/gds/worktree-claim-guard.js — worktree-per-claim, enforced at CLAIM
+// time instead of discovered at ship time (task 1002579).
+//
+// THE FAILURE THIS KILLS. A builder with direct repo access runs
+// `git checkout -b task-N` in the PRIMARY worktree (the main checkout) rather
+// than in a dedicated `.claude/worktrees/<name>`. Everything looks fine for the
+// whole session — and then ship.js's local auto-merge finds the receiving tree
+// is the very tree holding the feature branch, so there is nowhere to merge
+// INTO. The ship bails with "the main checkout is on <branch>, not main"
+// (ship-merge.js) and the task strands at `confirmed` until the server
+// reconciler or /merge-mode catches it. The cause is at claim time; the symptom
+// was hours away at ship time.
+//
+// Worktree-per-claim has been the documented default since task 1642 and the
+// claim-time context pack has warned about it since task 1002573 — but both
+// speak AFTER the claim lands, and neither stops anything. Owner directive
+// (2026-08-05): make it the enforced project default for ALL builders.
+//
+// The whole decision is the pure function below so it can be unit-tested without
+// a git repo; claim.js supplies the two facts (which kind of tree, which branch)
+// from resolveWorktreeRoot() — the SAME probe the context pack and
+// skill-preflight already use, so there is one answer to "is this the main
+// checkout", not three that can disagree.
+
+'use strict';
+
+// The documented escape hatch. Named here so the refusal text and claim.js's
+// argv parse can never drift apart.
+const ESCAPE_FLAG = '--here';
+
+// Decide whether a claim may proceed in the tree it is being run from.
+//
+//   isMainCheckout  true | false | null   — null means "could not tell" (git
+//                                           unavailable / odd checkout)
+//   branch          the current branch name, or null when unknown
+//   defaultBranch   the branch the main checkout must stay parked on
+//   allowMainCheckout  the builder passed the escape hatch
+//   taskId          only used to spell the remedy commands concretely
+//
+// Returns { verdict: 'allow' | 'warn' | 'refuse', reason, lines }.
+// - 'allow'  — a linked worktree (the correct setup), or a tree we cannot
+//              classify. NEVER refuse on a guess: an unknown tree fails open,
+//              because a false refusal blocks real work and the ship-time bail
+//              still catches the real thing.
+// - 'refuse' — the main checkout, no escape hatch. Exit before the claim lands.
+// - 'warn'   — the main checkout WITH the escape hatch: the builder has said
+//              they mean it, so say loudly what it costs and continue.
+function decideWorktreeClaim({
+  isMainCheckout,
+  branch = null,
+  defaultBranch = 'main',
+  allowMainCheckout = false,
+  taskId = null,
+} = {}) {
+  if (isMainCheckout !== true) {
+    return { verdict: 'allow', reason: isMainCheckout === false ? 'linked worktree' : 'tree kind unknown', lines: [] };
+  }
+
+  // Two shapes of the same mistake, and the second is already broken: a main
+  // checkout parked OFF its default branch has ALREADY lost the merge target,
+  // so say that rather than warning about a future that has happened.
+  const parked = branch && branch !== defaultBranch && branch !== 'HEAD';
+  const headline = parked
+    ? `the main checkout is already parked on \`${branch}\`, not \`${defaultBranch}\``
+    : `you are in the main checkout (on \`${branch || defaultBranch}\`), not a per-claim worktree`;
+  const cost = parked
+    ? `The local auto-merge at ship time merges INTO this tree — while it holds \`${branch}\` there is nowhere to merge to, so the ship strands at \`confirmed\`.`
+    : `Branching here parks the main checkout off \`${defaultBranch}\`, and the local auto-merge at ship time then has nowhere to merge INTO: the ship strands at \`confirmed\` until the server reconciler (or /merge-mode) catches it.`;
+
+  const id = taskId == null ? '<task-id>' : String(taskId);
+  const remedy = [
+    '  Work this claim in its own worktree instead:',
+    `    node scripts/gds/worktree.js add ${id}`,
+    `    cd .claude/worktrees/task-${id}`,
+    `    node scripts/gds/claim.js ${id}`,
+  ];
+
+  if (allowMainCheckout) {
+    return {
+      verdict: 'warn',
+      reason: headline,
+      lines: [
+        `⚠ Claiming in the MAIN CHECKOUT (${ESCAPE_FLAG} given) — ${headline}.`,
+        `  ${cost}`,
+        '  Automation that resets this tree mid-session can also take your uncommitted work with it.',
+        ...remedy,
+      ],
+    };
+  }
+
+  return {
+    verdict: 'refuse',
+    reason: headline,
+    lines: [
+      `✗ Refusing to claim here — ${headline}.`,
+      `  ${cost}`,
+      '  Worktree-per-claim is the project default (task 1642); this is the check behind it.',
+      ...remedy,
+      `  If you genuinely mean to work in the main checkout, re-run with ${ESCAPE_FLAG} (you will land at \`confirmed\` and finish through /merge-mode).`,
+    ],
+  };
+}
+
+module.exports = { decideWorktreeClaim, ESCAPE_FLAG };

package/src/module-api.js

@@ -1220,8 +1220,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.388 with no explicit bump. run 33126279278. (task 1002620)
 //   1.19.390 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.389 with no explicit bump. run 33133575931. (task 1002620)
+//   1.19.391 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.390 with no explicit bump. run 33134514193. (task 1002620)
+//   1.19.392 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.391 with no explicit bump. run 33176032603. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.390'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.392'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/worktree_claim_guard.mjs

@@ -0,0 +1,105 @@
+// tests/worktree_claim_guard.mjs
+//
+// task 1002579 — worktree-per-claim, enforced at CLAIM time. The failure it
+// kills: branching in the PRIMARY worktree (the main checkout) instead of a
+// dedicated `.claude/worktrees/<name>` leaves the main checkout parked off
+// `main`, so ship.js's local auto-merge has nowhere to merge INTO and the task
+// strands at `confirmed` — a symptom hours away from its cause.
+//
+// decideWorktreeClaim() is the pure core; these tests pin every branch with
+// injected facts (no git, no repo, no claim).
+//
+// Run:  node tests/worktree_claim_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { decideWorktreeClaim, ESCAPE_FLAG } = require('../scripts/gds/worktree-claim-guard.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const text = (d) => d.lines.join('\n');
+
+// ---- the core case: the primary checkout, on main -------------------------
+t('REFUSE: the main checkout on `main` — the exact shape task 1642 documents', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  assert.equal(d.verdict, 'refuse');
+  assert.match(text(d), /main checkout/i);
+});
+
+t('REFUSE names the fix concretely, with the task id spelled into the commands', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  const s = text(d);
+  assert.match(s, /worktree\.js add 42/, 'names the worktree-create command');
+  assert.match(s, /cd \.claude\/worktrees\/task-42/, 'names where to go');
+  assert.match(s, /claim\.js 42/, 'names the re-run');
+});
+
+t('REFUSE names the escape hatch, so the refusal is never a dead end', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', taskId: 42 });
+  assert.match(text(d), new RegExp(ESCAPE_FLAG.replace(/-/g, '\-')));
+});
+
+t('a missing task id still yields runnable-shaped guidance, not "undefined"', () => {
+  const s = text(decideWorktreeClaim({ isMainCheckout: true, branch: 'main' }));
+  assert.match(s, /worktree\.js add <task-id>/);
+  assert.doesNotMatch(s, /undefined|null/);
+});
+
+// ---- the already-broken shape: primary checkout parked off main -----------
+t('REFUSE: the main checkout ALREADY parked on a task branch reads as already-broken', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'task-99', taskId: 42 });
+  assert.equal(d.verdict, 'refuse');
+  const s = text(d);
+  assert.match(s, /already parked on `task-99`/, 'names the branch it is stuck on');
+  assert.match(s, /nowhere to merge/, 'names the ship-time consequence');
+});
+
+t('a detached HEAD in the main checkout is not reported as "parked on HEAD"', () => {
+  const s = text(decideWorktreeClaim({ isMainCheckout: true, branch: 'HEAD', taskId: 42 }));
+  assert.doesNotMatch(s, /parked on `HEAD`/);
+});
+
+t('defaultBranch is honoured — a `master` instance is not told main', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'master', defaultBranch: 'master', taskId: 7 });
+  assert.equal(d.verdict, 'refuse');
+  assert.doesNotMatch(text(d), /already parked/, 'master IS the default branch here');
+});
+
+// ---- the escape hatch: loud, but it proceeds ------------------------------
+t('WARN, not refuse, when the escape hatch is given — and it still costs something out loud', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: true, branch: 'main', allowMainCheckout: true, taskId: 42 });
+  assert.equal(d.verdict, 'warn');
+  assert.match(text(d), /confirmed/, 'says what it will cost at ship time');
+  assert.match(text(d), /worktree\.js add 42/, 'still names the better path');
+});
+
+// ---- no false positives ---------------------------------------------------
+t('ALLOW: a real linked worktree is untouched — silently, no lines', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: false, branch: 'claude/task-42', taskId: 42 });
+  assert.equal(d.verdict, 'allow');
+  assert.deepEqual(d.lines, []);
+});
+
+t('ALLOW: a linked worktree that happens to be on `main` is still fine', () => {
+  assert.equal(decideWorktreeClaim({ isMainCheckout: false, branch: 'main' }).verdict, 'allow');
+});
+
+t('ALLOW: tree kind UNKNOWN fails open — a guard that cannot see must not block', () => {
+  const d = decideWorktreeClaim({ isMainCheckout: null, branch: null, taskId: 42 });
+  assert.equal(d.verdict, 'allow');
+  assert.deepEqual(d.lines, []);
+});
+
+t('ALLOW: called with no facts at all (every probe threw) still fails open', () => {
+  assert.equal(decideWorktreeClaim().verdict, 'allow');
+});
+
+console.log(`\nworktree_claim_guard: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);