@bongos/core 1.19.276 → 1.19.278

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.276",
-  "core_contract": "1.19.276",
-  "source_commit": "de2f0fb76790e78b4b2c1bb4878fa88233a36c46",
+  "core_version": "1.19.278",
+  "core_contract": "1.19.278",
+  "source_commit": "d2c8b889323c64a1734fa1e622fe168b46b1116f",
   "source_ref": "HEAD",
-  "built_at": "2026-08-21T15:45:27.022Z",
+  "built_at": "2026-08-21T17:28:18.709Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 318,
+    "docs_redacted": 319,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1375,
+    "functional_verbatim": 1376,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1715,
-  "tree_sha256": "abe78982ee6e0304610e16ce97f65fc75baf045c6d210c2ab7ee65ced93b4ee7",
+  "file_count": 1717,
+  "tree_sha256": "f8955f572f4ca37464ee436a7b53e1b27efcc4d7f142af25ea001a4f42ca390b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -87,7 +87,7 @@
     {
       "path": ".claude/skills/builder-sequence/SKILL.md",
       "mode": "0000644",
-      "sha256": "4284bc0184dd27752202ce02974fa8909fc462f546ee3cae38fa26b4ca071f81"
+      "sha256": "838648912f0f058c58c42d943282346e2c35a90aea507b0ec136e9b0fbda50b0"
     },
     {
       "path": ".claude/skills/builder-setup/SKILL.md",
@@ -1389,10 +1389,15 @@
       "mode": "0000644",
       "sha256": "26f39ae01ea1768dfbd61789752356ae30364b465117b1e7ddee94fabc7d6bbf"
     },
+    {
+      "path": "docs/adr/0182-project-visibility-two-axes.md",
+      "mode": "0000644",
+      "sha256": "119637165d2d6b89f8c00afccd07d9f073629f1502f4b2f2cdc673001b2f8d2a"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "01396708c202d9c266bc2a3cf3ab4052fd2f3823e6957e7669370fdad2fdb7a9"
+      "sha256": "56d478e1b5285c1c133225240c65ec23c6b3b4f280cdda853c50b33564cc2910"
     },
     {
       "path": "docs/api-reference.md",
@@ -3872,7 +3877,7 @@
     {
       "path": "modules/lifecycle/ship-card.js",
       "mode": "0000644",
-      "sha256": "c2c4f75c6fec8a51befbe9e08f9fdb15b47a637654791a98d5eac6ed4a319ece"
+      "sha256": "c08ee0e89f67a2db7ea049353a12bdd6e5d97c6a7ec9039d19bdd797f66c112e"
     },
     {
       "path": "modules/lifecycle/ship-preflight.js",
@@ -4487,12 +4492,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "db42d8af206914a247ba771e7d711b22137bea42d6b4464eaa60a02bf8947c74"
+      "sha256": "6c3c704f2de78db933bd38831feaae364a1d1d608a01b7c14d147854950a6cef"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "8918824ec6d64703f4976a6f7863aa7ac0f240af95711972715967dfe973f944"
+      "sha256": "61504099e0e7e063f76862dfb805405f2743eaa0a3cb389a6b80fad771f35775"
     },
     {
       "path": "public-docs/index.html",
@@ -6137,7 +6142,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8eb348b653371b264e5c6b6efecddbdf18412e419e7dbd517b87322bdc806aae"
+      "sha256": "e0b73ea48b0a4c19e931162761dc58e0f97859e35bd92d93335cf610fc2036b0"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8194,6 +8199,11 @@
       "mode": "0000644",
       "sha256": "e76a3baf5fb2cdee08ffe8d80c55630b5ab4f708046f3c63c07c480926ccda31"
     },
+    {
+      "path": "tests/session_boundary_handoff.mjs",
+      "mode": "0000644",
+      "sha256": "8789eb59b2c3984500b4b2eb24d1e812e0ce6c970fc6fc940c06a6daf2613ec2"
+    },
     {
       "path": "tests/session_caps.mjs",
       "mode": "0000644",

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

@@ -35,7 +35,20 @@ This skill owns the **loop and the halt discipline**. It does not re-derive how
 
 5. **Ship it** — `/builder-ship`. The task must reach `shipped`, not stall at `completed` or `confirmed`. A ship that does not land has not unblocked anything, so the chain cannot advance; treat it as a halt (see `ship_failed` below).
 
-6. **Go back to step 2.** The ship you just landed is what promotes the next task to `ready`.
+6. **Hand the chain off before the next link — the chain gets slower otherwise.** This is the step that makes a long run stay fast, and it is easy to skip because nothing breaks without it.
+
+   Every turn re-reads the whole conversation, so a chain worked in one window pays more per turn the further down it goes. Measured on a three-task run (2026-08-21): 11.3M cached tokens on the first task, 36.1M on the second, 78.1M on the third. The third task was not twice the work of the second — it re-processed twice the context.
+
+   A shipped task is the moment almost all of that context turns into dead weight: superseded diffs, resolved test failures, closed grade rounds. **The chain's state is already durable** — dependencies and claims live in the GDS, and `--next` re-derives the plan from them — so a fresh window loses nothing that matters.
+
+   So, when the ship card shows a **heavy session** (it says so itself: `⚠ heavy session (NNM cached) — run /session-handoff…`), or when you have landed **three or more links** in one window:
+
+   - Run `/session-handoff`, scoped to the REMAINDER of the chain — the next task id, the chain's tail, and any decision from the links already landed that the rest depends on. Do not summarise the finished work in detail; it is shipped, and the GDS is its record.
+   - Hand the user that prompt and say plainly that the chain continues in a fresh session. Then **stop.** Do not claim the next task in this window.
+
+   `/session-handoff` composes text and changes nothing, so this is safe at any point — and it cannot be automated away: a hook cannot clear a conversation, which is exactly why this step is the runner's job.
+
+7. **Otherwise, go back to step 2.** The ship you just landed is what promotes the next task to `ready`.
 
 Between passes, report progress in one line — which task landed, what is next, how much of the chain remains. The user is following a long run; they should never have to ask where it is.
 
@@ -73,6 +86,8 @@ node scripts/gds/sequence.js --check <task-id>
 
 ## What NOT to do
 
+- **Do not run a long chain to exhaustion in one window** to avoid the handoff in step 6. It feels like progress and it is the single biggest reason a long run drags: the last link can cost several times the first for identical work. Handing off is not an interruption of the chain; it is how the chain stays cheap.
+
 - **Do not skip a halted task and continue down the chain.** The owner chose stop-and-report precisely so a blocked predecessor does not silently strand its dependents.
 - **Do not batch-claim.** See "The one rule".
 - **Do not widen a task's `touches[]`** to make the chain flow. File a new task instead (`node scripts/gds/capture.js`).

package/docs/adr/0182-project-visibility-two-axes.md

@@ -0,0 +1,168 @@
+# ADR 0182 — Project visibility is TWO axes: a derived publish gate and a stored join door
+
+- **Status:** Accepted
+- **Date:** 2026-08-21
+- **Task:** [task 1002320](https://cloudbongos.com/builders#/task/1002320) (BONGOS-V1, goal 1000046 — *Project creation — visibility & customization*)
+- **Deciders:** IAMMASTERQUA (Archon), Claude
+- **Confirms R04–R18** — the full accounting is in *Scope* below, including the two that this ADR deliberately does **not** govern.
+- **Bounds — deliberately NOT decided here:** the self-hosted→hub *reporting and trust* mechanics ([task 1002321](https://cloudbongos.com/builders#/task/1002321), R02) · the applications/invite *model* (`docs/specs/<redacted>.md` D2, already decided) · project *authority* (same spec, D1)
+- **Related:** [ADR 0141](<redacted>.md) (hub = identity + relay, authority stays local) · [ADR 0112](<redacted>.md) (`goals.visibility`, the precedent this copies) · [ADR 0108](<redacted>.md) (the instance IS the project) · [ADR 0174](<redacted>.md) (one word, one meaning)
+
+---
+
+## Scope — what "confirms R04–R18" means, task by task
+
+The task description says this ADR *"confirms R04–R18"*. That is 15 tasks and they do not
+all relate to it the same way, so they are enumerated rather than gestured at. **Its
+criteria** are `proj-visibility-states`, `proj-join-policy` and `proj-detail-interview`
+(the goal's C1–C3); task 1002320 is linked to all three.
+
+**Shape set by this ADR** — these build what it decides, and each should be read against it:
+
+| | Task | Gets from this ADR |
+|---|---|---|
+| R04 | [1002323](https://cloudbongos.com/builders#/task/1002323) | the 3-value enum + the derived gate + the missing `description` column (D1, D4) |
+| R05 | [1002324](https://cloudbongos.com/builders#/task/1002324) | **moves host** — an instance surface, not a hub one (D5) |
+| R06 | [1002325](https://cloudbongos.com/builders#/task/1002325) | the feed predicate change + **server-side** stealth redaction (D2a, D3) |
+| R07 | [1002326](https://cloudbongos.com/builders#/task/1002326) | which three states render, and that `featured` no longer gates presence (D3) |
+| R08 | [1002327](https://cloudbongos.com/builders#/task/1002327) | the hub row is a cache; **unreported ⇒ fail-closed** (D5) |
+| R09 | [1002328](https://cloudbongos.com/builders#/task/1002328) | the render mapping, and that it may not be trusted to redact (D2a) |
+| R11 | [1002330](https://cloudbongos.com/builders#/task/1002330) | per-state application rules on the already-decided model (D6) |
+| R12 | [1002331](https://cloudbongos.com/builders#/task/1002331) | **visibility is the ceiling; join policy may only narrow** (D6) |
+| R15 | [1002334](https://cloudbongos.com/builders#/task/1002334) | why skipping the interview is a supported default, not a dead end (D4) |
+| R16 | [1002335](https://cloudbongos.com/builders#/task/1002335) | the bar is identity only, and it must name what is missing (D4) |
+
+**Proofs of those shapes** — no new decisions, but their assertions are set here:
+R10 ([1002329](https://cloudbongos.com/builders#/task/1002329)) must assert stealth's
+**absent fields, not absent pixels** (D2a);
+R14 ([1002333](https://cloudbongos.com/builders#/task/1002333)) must cover the
+ceiling-vs-narrowing rule (D6);
+R18 ([1002337](https://cloudbongos.com/builders#/task/1002337)) must cover
+skip ⇒ dark-matter-until-published (D4).
+
+**NOT governed by this ADR**, stated so the omission is a decision rather than a gap:
+
+- **R13** ([1002332](https://cloudbongos.com/builders#/task/1002332)), the owner
+  applications review queue — belongs to `docs/specs/<redacted>.md`
+  (D1/D2), which already decided the queue, its authority and its storage. This ADR sets
+  only which states *accept* an application (D6), never what happens to it afterwards.
+- **R17** ([1002336](https://cloudbongos.com/builders#/task/1002336)), rule-based
+  recommendations from the project detail — orthogonal. Recommendations concern module and
+  governance presets; nothing about them depends on visibility or publishability.
+
+## Context
+
+Goal 1000046 seeded 31 tasks, and R04–R18 each say *"per R01"* — this ADR. Nothing in the goal could start until it landed: at claim time it gated **29 open tasks**, the largest single chokepoint in the repo, and it was itself parked at `backlog` with no dependencies of its own.
+
+The spec its planning task cites — `docs/specs/<redacted>.md` — **was never written**. This ADR is therefore the design of record, not a summary of one.
+
+**What exists today.** `platform_identity_projects` (hub-side, keyed by `origin`) carries `status ('active'|'hidden')`, an Archon-curated `featured` boolean, and `owner_github_id` — explicitly commented *"advisory attribution (not an authority)"*. The public feed reads `featured = true AND status = 'active'`. So today a project's presence on the map is **Archon editorial curation**, and the owner has no control at all. The goal's premise is the inverse: the owner shapes it.
+
+**The apparent contradiction that motivated this ADR.** The goal's own criterion `proj-visibility-states` says *"one of **four** states"* (Public/Private/Stealth/Unlisted). R04's description says *"3-state visibility enum … dark-matter is derived … not a stored 4th state"*. Read as one enum these disagree. They do not disagree; they describe different layers, and conflating those layers is the trap this ADR exists to prevent.
+
+## Decision 1 — Two independent axes, not one four-valued enum
+
+| Axis | Stored? | Set by | Governs |
+|---|---|---|---|
+| **Publishability** | **Derived** | the identity gate (R16) | whether the project is on the map *at all* |
+| **The join door** | Stored: `visibility ∈ (public, private, stealth)` | the project's owner | how it renders, and who may get in |
+
+The four user-facing states are **3 × publishable, plus one derived state that collapses all three**:
+
+```
+publishable = false  →  DARK MATTER   (off the map, un-joinable) — whatever the enum says
+publishable = true   →  public   → planet      (identified,  anyone may join)
+                        private  → star        (identified,  no self-join, applications accepted)
+                        stealth  → black hole  (ANONYMOUS,   no self-join, applications refused)
+```
+
+**The name `visibility` is kept, and it is a mild lie.** The column does not decide visibility — publishability does. We keep the name because `goals.visibility` (ADR 0112) already established it and one word across both planes beats an accurate name used in one place. This paragraph is the mitigation: **anyone reading `visibility = 'public'` and expecting the orb on the map is reading it wrong**, and the publish gate is the thing to check. R04 must carry that sentence to the column comment.
+
+## Decision 2 — All three stored states are VISIBLE; only the derived state is invisible
+
+This is what makes the 3+1 split honest rather than a workaround: the enum is a *door* policy, and every value of it is on the map. Consequences worth stating because R06/R07/R09 all depend on them:
+
+- **`private` means visible-but-closed, exactly as it already does for goals.** ADR 0112: *"a private goal stays VISIBLE in the goal list but non-members can't self-join."* The project plane inherits that meaning unchanged. A private project is a star you can see and ask to join.
+- **`stealth` exposes EXISTENCE but not IDENTITY.** The black hole is the metaphor and it is precise: you see the gravitational effect, not the object. R06/R09 say "stealth is anonymous", and that is a real privacy primitive, not a rendering note.
+- **Dark matter is not a state an owner picks.** It is the absence of a met bar. There is deliberately no way to *choose* it, because "unlisted" as a selectable option would compete with `private` and nobody could say which to pick.
+
+### Decision 2a — stealth redaction is SERVER-SIDE, in the feed
+
+A stealth project's `name`, `tagline`, `art_url`, and `origin` **must not leave the server** in the public feed. The feed emits the orb (existence, render type, and whatever aggregate the map needs) and nothing identifying.
+
+This is called out because the naive implementation is to send the row and let the orbs page hide it — which leaks the whole thing to anyone who opens the network tab, and the orbs page is a **static site outside this repo** (R09), so we cannot enforce it there even in principle. Redaction at the boundary is the only version of this that is true. R06 owns it; R10's proof must assert the absence of the fields, not the absence of pixels.
+
+## Decision 3 — Three mechanisms, three owners, one composition rule
+
+`status`, `visibility` and `featured` all touch "does this appear", and they are not the same thing:
+
+| Field | Owner | Meaning |
+|---|---|---|
+| `status` | system / Archon | operational lifecycle — a deprovisioned project is `hidden` |
+| `visibility` | the **project owner** | the join door (Decision 1) |
+| `featured` | Archon | editorial promotion |
+
+**Composition:** a project is on the map iff `status = 'active' AND publishable`. `featured` may only **rank or promote among projects already on the map** — it can never put an unpublishable or `hidden` project there.
+
+That is a behaviour change: today's feed predicate is `featured = true AND status = 'active'`, so **featuring is currently load-bearing for visibility at all**, and an owner setting `public` on an unfeatured project would see nothing happen. R06 replaces the predicate; R07 dogfoods it. Without this decision the owner-control premise of the whole goal silently does not work.
+
+## Decision 4 — The publish gate is identity only: `name` + `description`
+
+Per the owner interview (recorded on R16): the bar is a name and a description. **Not** tagline, art, modules, governance, or a completed interview.
+
+The bar exists to keep empty husks off the map — not to enforce completeness. A higher bar would make "skip the optional detail step" a dead end rather than the supported default the goal explicitly wants (`proj-detail-interview`: *"skipping it produces sensible defaults"*).
+
+**The gate must name what is missing, never merely refuse.** A project that cannot be published and is not told why is indistinguishable from a broken one.
+
+*Note for R04:* `platform_identity_projects` has `name NOT NULL` but **no `description` column** (only `tagline`). R04 adds it. Do not repurpose `tagline` — it is the card one-liner and a description is the publish bar; collapsing them means editing your card can unpublish your project.
+
+## Decision 5 — Visibility is owned by the INSTANCE and mirrored to the hub
+
+The hub's `platform_identity_projects` row is a **cache, never the source of truth.**
+
+This follows from ADR 0141 §3 and the admin-console spike's D1 (*the instance IS the project; authority lives on the project instance*), and it resolves what otherwise looks like a gap: `owner_github_id` being "advisory, not an authority" is **correct**, not a hole to be filled. The hub never authorizes a visibility change; it accepts a report from the authenticated `sso_client` and stores it.
+
+Two consequences that redirect seeded work:
+
+1. **R05 (owner set/change visibility) is an INSTANCE surface**, not a hub one. The setting lives in the project's own hall settings, gated by the project's own ranks.
+2. **R08 is the sync, not an afterthought.** A hub row whose visibility was never reported is stale, and stale here means *wrong on the public map*. R08's absent-report default must be **fail-closed: unreported ⇒ treated as not publishable (dark matter)**, so a project that has never spoken is off the map rather than exposed by omission.
+
+The *trust* mechanics of that report — how the hub authenticates it, replay, rate — are **R02's** ([task 1002321](https://cloudbongos.com/builders#/task/1002321)), not this ADR's.
+
+## Decision 6 — Per-state join rules, and how they compose with the join-policy setting
+
+The applications *model* is already decided (`docs/specs/<redacted>.md` D2: extend `access_requests` with `kind ∈ ('application','invite')`, no new table). This ADR adds only the per-state rules on top:
+
+| State | Self-join | Applications |
+|---|---|---|
+| public / planet | permitted | not needed |
+| private / star | refused | accepted, owner reviews |
+| stealth / black hole | refused | **refused at the door** (the public POST 403s) |
+| dark matter | refused | refused — there is no door to knock on |
+
+Stealth's distinction from private is **at the door, not in the queue**: a refused application is never stored, so a stealth project accumulates no queue to leak.
+
+**Two knobs could contradict.** [task 1002817](https://cloudbongos.com/builders#/task/1002817) adds a per-project join policy (`open|closed`) at the same door. Rule: **visibility sets the ceiling; join policy may only narrow it.** A `closed` public project accepts no self-joins; an `open` stealth project still refuses everything. The stricter of the two always wins, and neither can widen the other. Without this, the two settings are a coin-flip decided by evaluation order.
+
+## Decision 7 — The word `stealth` already means something else; product surfaces win, and the collision is tracked
+
+`src/bongos/stealth-gate.js` + `STEALTH_PASSWORD` already mean *an instance-wide pre-launch password wall* — an entire instance made **unreadable**. Project `visibility = 'stealth'` means a project that is **on the public map, anonymously, refusing applications**. These are close to opposites, and ADR 0174 is the standing lesson that one word carrying two meanings costs more than a rename.
+
+**Decision:** the *product* meaning (the owner-facing state, whose orb metaphor is locked by the criterion) keeps the word. The infra gate is the one that should be renamed — to `prelaunch` — but that touches a protected path, an env var, and a live instance's configuration, so it is **not** decided here by an ADR about visibility. It is filed as its own task with the owner's call attached.
+
+Until then: `stealth` unqualified in product code and copy means the project state. The infra gate is referred to as the **pre-launch gate** in prose even while its identifier still says stealth.
+
+## Consequences
+
+- R04 lands `visibility` (3-value CHECK, default `public`, precedent `goals.visibility`) **and** the missing `description` column, plus the backfill. Existing rows keep today's behaviour: `visibility='public'`, publishable iff they already have a name and description.
+- R06's feed predicate changes from `featured`-gated to `publishable + active`, with stealth rows redacted server-side. This is the single riskiest change in the goal — it is what actually moves control from Archon curation to the owner — and R10 is its proof.
+- R05 moves host: instance-side settings, not a hub page.
+- R08 defaults fail-closed on an unreported project.
+- Anything reading `featured = true AND status = 'active'` as "is this public" is now wrong and must be found. `modules/platform-identity/routes/projects.js` is the known site.
+
+## Alternatives rejected
+
+- **A stored four-valued enum including `unlisted`.** Rejected: it makes "unlisted" a choice competing with `private`, and it lets a project be simultaneously "publishable" and "unlisted" — two sources of truth for one question, which is the bug the derived gate prevents by construction.
+- **A separate `published` boolean.** Rejected for the same reason: a boolean can disagree with the identity it is supposed to summarise. Derived cannot drift.
+- **Letting `featured` keep gating visibility, with owner visibility layered on top.** Rejected: an owner who sets `public` and appears nowhere until an Archon blesses them has not been given control, and the goal's premise is that they have.
+- **Client-side stealth redaction.** Rejected: the orbs page is a static site outside this repo, so the guarantee would be unenforceable by construction.

package/docs/adr/README.md

@@ -255,5 +255,6 @@ This keeps the decision history honest and traceable.
 | 0179 | [**`rank:metic+` means metic and above; a bare `rank:metic` still means exactly metic** ([task 1003094](https://cloudbongos.com/builders#/task/1003094), goal 1000069). [ADR 0175](<redacted>.md) gave the constitution ONE membership form, `rank:<key>`, resolved by an EXACT SQL match — so `rank:metic` seated metics ONLY (excluding Archons), `rank:xenos` seated NEWCOMERS ONLY rather than "everyone", and "Metic and above" was inexpressible. Everywhere else a rank is a LADDER and authority is cumulative (ADR 0034 inheritance, requireRank('metic','archon'), the floor-derived seed); board membership was the one place it meant "exactly", and nothing said so. Rehearsing R25 on a real Postgres, an Archon ratified `rank:metic` under monarchy — the apply worked perfectly — and the next vote came back 403 not_board_member: **the owner flipped the switch and fell off their own board**, with the board deadlocked at one member because an Archon can still PROPOSE but no longer VOTE. Owner decision: EXPLICIT GRAMMAR. `rank:metic+` (that rank and above), `rank:metic,archon` (union), and **a bare key still means EXACTLY that key** — rejecting the smaller diff (silently redefining the bare form) precisely because it would have changed the meaning of every already-ratified constitution, the monarchy default included, on upgrade: nothing in a government should change meaning without a vote. `+` is defined only on the STANDARD ladder — "and above" about a custom rank with no ladder position is a parse REFUSAL, not a guess, and a refusal seats nobody. The grammar had been written TWICE (a shape regex in the config sanitizer, a parse regex in the resolver, pinned by a property test) — sound for one literal form, unsound the moment a rule needs a LOOKUP, which is the same class of drift that produced the bug; both now call one pure `membership-predicate.js`. Adds the DISENFRANCHISEMENT GUARD: a proposal that would unseat its own proposer is refused before any write, naming the one-character fix, overridable with an explicit `acknowledge_self_removal` (a separate parameter, never a proposal field) because stepping back is a legitimate act. The two DB reads take a set via `= ANY($1)` + DISTINCT (a double-counted member silently raises the consent bar), the structural filters are re-proven against real Postgres (a deactivated builder and a machine principal still never govern), and the hall panel now describes every form in plain language — rendering `rank:metic+` as "the metic+ rank" would be the same bug one layer up. Unblocks task 1003095, which can now write each charter's TRUE predicate rather than wording around a limitation.](<redacted>.md) | government / the board |
 | 0180 | [**Dependency intake & drift policy: baseline-ratchet audit gate, install scripts off, cooldown via patrol, OIDC publish** ([task 1003127](https://cloudbongos.com/builders#/task/1003127), goal 1000076). The red-team baseline audit found 18 advisories (2 high) sitting unwatched in 9 production deps, the `undici ^6.27.0` override pinned INSIDE a vulnerable range while also breaking Node 26 CLIs, and nothing gated what an agent may install — against a 2025 npm threat wave (chalk/debug, Shai-Hulud, Nx) that ran on postinstall scripts and long-lived publish tokens. Four decisions. (1) `scripts/gds/audit-gate.js` runs in the required `unit` check: a high/critical advisory NOT in the committed `config/audit-baseline.json` fails the merge gate; the baseline is **shrink-only pre-gate debt** (10 findings at adoption) — adding an entry to silence a NEW advisory is out of policy. Fail-OPEN on registry/infra errors, fail-CLOSED on findings: the gate catches new advisories, it does not prove registry uptime. Notably a blanket `npm audit fix` cannot even run here (`workspace:` protocol, EUNSUPPORTEDPROTOCOL) — fixes are explicit tasks. (2) `.npmrc ignore-scripts=true`: the tree needs no install-lifecycle scripts — sharp installs prebuilds via optionalDependencies, proven by a script-less `npm ci` + full 430-test suite; a future dep needing one is an ADR-level exception. (3) Update cooldown is PATROL-enforced (task 1003128 flags versions younger than 7 days + stale overrides + action-pin drift) rather than `.npmrc`-enforced, because CI's npm 10 warns on the npm-11 `minimum-release-age` key for every builder; move it into `.npmrc` when the toolchain floor reaches npm ≥ 11.10. (4) Publish auth moves to npm **trusted publishing (OIDC)** — needs a one-time owner registration on npmjs.com (blocker filed); until then the granular 90-day `NPM_TOKEN` is a documented exception.](<redacted>.md) | devsecops / supply chain |
 | 0181 | [**Teardown accepts every state but `torn_down`, and deliberately keeps the address** ([task 1003042](https://cloudbongos.com/builders#/task/1003042), goal 1000058). Walk finding N5: an instance at `status='error'` could never be removed — the owner's teardown answered 409 `not_teardownable` and the archon `force-teardown`, which exists as the escape hatch, answered the SAME refusal, because both read one hand-kept whitelist `['provisioning','active','tearing_down']` that omitted `requested` and `error`. No role had a path out, so errored rows accumulated permanently (instance 15 `swag` from 2026-08-07). The whitelist justified itself as "nothing running to tear down", which is FALSE for `error`: a provision failing mid-run lands there AFTER it may have created the database, taken a port, and written the systemd unit, Caddy block and DNS record — a partial standup is the thing most in need of reclaiming. `TEARDOWN_FROM` is now DERIVED from `INSTANCE_STATES` minus `torn_down`, so a future state is teardownable by DEFAULT — the bug was an allow-list that silently omitted states, and for a failure mode whose signature is "a row with no exit", the safe default is that an exit exists. The runner needed no change (its steps are each `allowFail`); only the web guard refused. The one surviving refusal is now ONE shared helper: the copies had drifted, and force-teardown's positional `res.fail` form put the bare code `not_teardownable` on the wire as the human text. **The `port` and `domain` are deliberately NOT released** — releasing the port alone would be WORSE than the status quo, because the `<slug>.caddy` block survives teardown and proxies the hostname to a PORT NUMBER, so a later instance given that port would answer at the torn-down project's still-live address (verified live: two projects torn down 2026-08-13 still resolved on 2026-08-19). Holding the port is what keeps the address inert at a harmless 502; releasing both is [task 1002897](https://cloudbongos.com/builders#/task/1002897). Retention is also correct for revive, which re-uses the same hostname. Copy was corrected to match: it had promised "the address stops answering", which was never true.](0181-teardown-state-gate-and-address-retention.md) | provisioning / lifecycle |
+| 0182 | [**Project visibility is TWO axes: a derived publish gate and a stored join door** ([task 1002320](https://cloudbongos.com/builders#/task/1002320), goal 1000046). Goal 1000046 seeded 31 tasks each citing "per R01" — this ADR — so nothing in the goal could start until it landed: it gated **29 open tasks**, the largest single chokepoint in the repo, while itself parked at `backlog` with no dependencies. The spec its planning task cites was never written, so this is the design of record. The goal's criterion says **four** states (Public/Private/Stealth/Unlisted) and R04 says **three** stored plus a derived dark-matter; both are right and conflating them is the trap. There are two INDEPENDENT axes: **publishability** (DERIVED from the identity gate — name + description, per the owner interview) decides whether a project is on the map at all, and **the join door** (STORED `visibility ∈ public|private|stealth`, owner-set) decides how it renders and who gets in. Four user-facing states = 3 × publishable + one derived state that collapses all three. The column name `visibility` is a mild lie kept for consistency with `goals.visibility` (ADR 0112) — it does NOT decide visibility, publishability does — and the ADR is the mitigation. All three stored states are VISIBLE; only the derived state is invisible, which is what makes the 3+1 split honest rather than a workaround. `private` inherits ADR 0112's exact meaning (visible-but-closed); `stealth` exposes EXISTENCE but not IDENTITY, and its redaction is **server-side in the feed** — the naive client-side version leaks to anyone opening the network tab, and the orbs page is a static site OUTSIDE this repo (R09) so it could never be enforced there. Three mechanisms touch "does this appear" and are separated: `status` (operational), `visibility` (owner), `featured` (Archon editorial) — on the map iff `status='active' AND publishable`, with `featured` only ranking among those. That is a real behaviour change: today's predicate is `featured=true AND status='active'`, so **featuring is currently load-bearing for visibility at all** and the goal's owner-control premise silently does not work without it. Visibility is owned by the INSTANCE and the hub row is a CACHE (ADR 0141 §3 + the admin-console spike's D1) — so `owner_github_id` being "advisory, not an authority" is CORRECT rather than a gap, R05 moves to an instance surface, and R08's absent-report default is fail-closed (unreported ⇒ dark matter, off the map rather than exposed by omission). Per-state join rules compose with the separate `open|closed` join policy ([task 1002817](https://cloudbongos.com/builders#/task/1002817)) by one rule: **visibility sets the ceiling, join policy may only narrow** — otherwise the two settings are a coin-flip decided by evaluation order. Finally, `stealth` COLLIDES with the existing instance-wide pre-launch password gate (`STEALTH_PASSWORD`, `src/bongos/stealth-gate.js`), which means nearly the opposite (a whole instance made unreadable vs a project publicly on the map, anonymously); per ADR 0174 the product meaning keeps the word and the infra rename is filed separately rather than decided by an ADR about visibility. Rejected: a stored 4-valued enum (makes `unlisted` compete with `private`, and lets publishable+unlisted disagree), a separate `published` boolean (can drift from the identity it summarises; derived cannot), and keeping `featured` as the visibility gate (an owner who sets public and appears nowhere has not been given control).](<redacted>.md) | platform-identity / project visibility |
 
 > ⚠️ **Numbering collision (known):** two ADRs share `0008`. The numbers were assigned in parallel sessions before the lock could be enforced. The files are kept under their existing filenames to preserve git history, but the table disambiguates them as `0008-a` / `0008-b`. New ADRs should resume at `0040` to avoid further collisions. (`0024` is also a real on-disk duplicate: the cloneable-repo/local-first-memory ADR and the multi-agent-system-architecture ADR were both numbered `0024` in parallel; both keep their filenames, disambiguated as `0024-a` / `0024-b` like `0008`. Likewise `0025` ended up with two on-disk files — the offsite-backup ADR and the structured-criterion↔task-link ADR — both kept under their existing filenames and disambiguated as `0025-a` / `0025-b`; separately, the BFG ADR had also claimed `0025` on 2026-05-30 and yielded to `0026`. A third happened 2026-06-06: `0036` was claimed in parallel by the builders-subdomain ADR ([#726](https://example.com/builders#/task/726)) and this Discord-channels ADR ([#727](https://example.com/builders#/task/727)); the Discord-channels ADR yielded to `0037`. A fourth landed 2026-06-10: `0044` was claimed in parallel by the palette-replacement ADR and the per-box game-preview ADR ([#897](https://example.com/builders#/task/897)); both keep their filenames, disambiguated as `0044-a` / `0044-b` like `0008`. A fifth was caught pre-land 2026-06-13: `0050` was claimed in parallel by the device-flow-admission ADR ([#1000](https://example.com/builders#/task/1000)) and the sandbox-for-everyone ADR ([#1001](https://example.com/builders#/task/1001)); the latter yielded to `0052` before merging, so there is no `0050` duplicate. A sixth was caught pre-land 2026-06-21: the tool-agnostic-design-layer ADR ([#1375](https://example.com/builders#/task/1375)) first collided at `0079` with the value-gated-autonomous-engagement ADR, then at `0080` with the llm-cache-api-transport ADR (both part of the 0075–0080 LLM-cost-reduction series, landed on `main` in parallel); it yielded to `0081` before merging, so there is no `0079`/`0080` design-layer duplicate. A seventh landed 2026-06-23: `0084` was claimed in parallel by the auto-derived-per-task-rank-floor ADR and the remove-default-spend-cap ADR (task 1499); the rank-floor ADR landed on `main` first, so the spend-cap ADR yielded to `0085`, leaving no `0084` duplicate. An eighth landed 2026-06-27: `0095` was claimed in parallel by the borrowed-memory-and-retrieval-concepts ADR (PR #459, landed first) and the cross-agent-context-management ADR ([#1651](https://example.com/builders#/task/1651), PR #460); both keep their filenames, disambiguated as `0095-a` / `0095-b` like `0008`. These two are companions — `0095-a` adopts the memory/retrieval concepts and explicitly defers the grep-vs-semantic question to `0095-b`.)

package/modules/lifecycle/ship-card.js

@@ -174,6 +174,59 @@ function nextActionFor(stage, { taskId, discipline, sandboxUrl } = {}) {
   return { kind: 'prompt', label: 'Continue', cmd: '/builder-start' };
 }
 
+// ---- the session boundary (task 1003150) -----------------------------------
+//
+// A shipped task is the one moment the system KNOWS a session's work is finished,
+// and it is the only moment when almost everything in that session's context
+// becomes dead weight: superseded diffs, resolved test failures, closed grade
+// rounds. Carrying it into the next task costs real time, because every turn
+// re-reads the whole conversation.
+//
+// MEASURED, session of 2026-08-21 — three tasks shipped in one window:
+//   task 1003148   262K new + 11.3M cached
+//   task 1003065   582K new + 36.1M cached
+//   task 1003066   891K new + 78.1M cached
+// The third was not twice the work of the second; it re-processed twice the
+// context. The builder's own report was that everything felt slow, and this was
+// the largest single contributor.
+//
+// WHY THIS LIVES ON THE CARD AND NOT IN A HOOK. A hook cannot clear a
+// conversation, and /session-handoff is read-only by its own spec ("composes text
+// and changes no state") — it has to be invoked. The harness does auto-compact on
+// context PRESSURE, but that fires on size rather than meaning: as likely to
+// compact mid-task, where the detail is load-bearing, as after a ship, where it is
+// not. The ship card is the only component that is already running, already at the
+// boundary, and already printing to the builder — so the nudge costs one line and
+// no new machinery.
+//
+// THE THRESHOLD is deliberately generous. The advice is only useful if it is rare:
+// a line that prints on every ship is wallpaper (the deploy-divergence footer is
+// the cautionary tale — 21 core versions of identical warning that nobody acted
+// on). 25M cached sits between the 11.3M session that felt fine and the 36.1M one
+// that had begun to drag, so a short session never sees it.
+const HEAVY_SESSION_CACHED_TOKENS = 25_000_000;
+
+// handoffAdvice — PURE. null when there is nothing to say (the overwhelming
+// majority of ships), else the one-line nudge. Exported so every branch is pinned
+// by a DB-free unit test.
+//
+// Gated on a TERMINAL stage, not merely a big number: mid-task the context is what
+// the work is standing on, and telling someone to reset in the middle of a claim is
+// actively wrong. 'shipped' and 'confirmed' are the two stages where the task is
+// out of the builder's hands.
+function handoffAdvice(input) {
+  // Normalise BEFORE destructuring. A default parameter only fires on `undefined`,
+  // so an explicit `null` — what a caller spreading an absent object hands over —
+  // would throw. This runs at the very end of a successful ship, so a crash here
+  // would turn a landed task into a traceback. (Same trap as decideLanding in
+  // modules/ideas/routing.js, task 1003065 — it caught me twice in one session.)
+  const { stage, cachedTokens } = input || {};
+  if (stage !== 'shipped' && stage !== 'confirmed') return null;
+  const cached = Number(cachedTokens);
+  if (!Number.isFinite(cached) || cached < HEAVY_SESSION_CACHED_TOKENS) return null;
+  return `heavy session (${fmtTokens(cached)} cached) — run /session-handoff, then start the next task in a fresh session`;
+}
+
 function safeBrand() {
   try {
     const b = branding();
@@ -219,6 +272,7 @@ function buildCardModel(input = {}) {
 
   const rows = [];
   const facts = [];
+  let handoff = null; // task 1003150 — the session-boundary nudge; null on all but a heavy ship
   const addRow = (k, v) => { if (v != null && v !== '') rows.push({ k, v }); };
   const addFact = (label, value, opts = {}) => { if (value != null && value !== '') facts.push({ label, value, ...opts }); };
 
@@ -319,6 +373,10 @@ function buildCardModel(input = {}) {
 
     addRow('Value', value); addRow('Changed', changed); addRow('Grade', gradeText);
     addRow('Credits', creditsText); addRow('Usage', usageText); addRow('Deploy', deployText);
+    // task 1003150: the session-boundary nudge. Not a row — it qualifies the
+    // Next-> action rather than reporting a fact about the task, so both renderers
+    // hang it off the action. Usually null.
+    handoff = handoffAdvice({ stage, cachedTokens: usage.cachedTokens });
 
     addFact('', changed);
     if (gradeText) addFact('grade', gradeText, { cls: gradeCls });
@@ -345,7 +403,7 @@ function buildCardModel(input = {}) {
     notes: input.notes || '',
     description: input.description || '',
     issues,
-    rows, facts, action,
+    rows, facts, action, handoff,
   };
 }
 
@@ -403,6 +461,9 @@ function renderMonospaceCard(model) {
   for (const r of m.rows) kv(r.k, r.v);
   out.push(bar);
   kv('Next →', m.action.kind === 'link' ? (m.action.url || '(sandbox)') : m.action.cmd);
+  // task 1003150: aligned under the Next action it qualifies, not as a row — this
+  // is guidance about the SESSION, not a fact about the task.
+  if (m.handoff) for (const l of wrap(`⚠ ${m.handoff}`, MONO_W - 9)) out.push('  ' + ' '.repeat(9) + l);
   return out.join('\n');
 }
 
@@ -459,6 +520,12 @@ function renderCardHtml(model) {
     actionHtml = `<button class="cc-link cc-next" onclick="sendPrompt('${cmd}')">${esc(m.action.label)} ↗</button>`;
   }
 
+  // task 1003150: the boundary nudge rides beside the action, muted — it is
+  // advice, not an alarm, and it must not outshout the Next button.
+  const handoffHtml = m.handoff
+    ? `<span class="cc-sep">·</span><span style="color:var(--color-text-tertiary);">${esc(m.handoff)}</span>`
+    : '';
+
   const factsSr = m.facts.map((f) => `${f.label ? f.label + ' ' : ''}${f.value}`).join('. ');
   const srText = `${m.cfg.headline(m.taskId)}. ${factsSr}. A collapsible summary expands on click.`;
 
@@ -490,7 +557,7 @@ function renderCardHtml(model) {
     ${actionHtml}
   </div>
   <div style="display:flex;align-items:baseline;gap:10px;">
-    <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.7;flex:1;min-width:0;">${facts}</div>
+    <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.7;flex:1;min-width:0;">${facts}${handoffHtml}</div>
     <button class="cc-link cc-sum" aria-label="Toggle task summary" onclick="var s=this.parentElement.nextElementSibling;var o=getComputedStyle(s).display==='none';s.style.display=o?'block':'none';this.querySelector('i').style.transform=o?'rotate(90deg)':'';">Summary <span class="cc-chev"><i class="ti ti-chevron-right" aria-hidden="true"></i></span></button>
   </div>
   <div style="display:none;margin-top:0.6rem;padding-top:0.55rem;border-top:0.5px solid var(--color-border-tertiary);font-size:13px;line-height:1.6;">${summaryBody}</div>
@@ -538,5 +605,7 @@ module.exports = {
   STAGES, TONE, stageFor, buildCardModel, renderMonospaceCard, renderCardHtml, emitCard,
   // exported for unit tests:
   fmtTokens, fmtUsd, fmtInt, fmtMins, nextActionFor, esc, wrap, changedText,
+  // task 1003150 — the session-boundary nudge, pure so every branch is pinned.
+  handoffAdvice, HEAVY_SESSION_CACHED_TOKENS,
   PIPELINE, FORMS, trailSteps,
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.276",
+  "version": "1.19.278",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -979,8 +979,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.274 with no explicit bump. run 32492414871. (task 1002620)
 //   1.19.276 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.275 with no explicit bump. run 32499257959. (task 1002620)
+//   1.19.277 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.276 with no explicit bump. run 32503053532. (task 1002620)
+//   1.19.278 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.277 with no explicit bump. run 32508270995. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.276'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.278'; // 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/session_boundary_handoff.mjs

@@ -0,0 +1,184 @@
+// tests/session_boundary_handoff.mjs
+//
+// THE SESSION BOUNDARY — task 1003150 (goal 1000053 "Session efficiency").
+//
+// The mirror of that goal's session-START series (1002435-1002438): those
+// front-load what a session can know at open; this stops a session dragging what
+// it no longer needs at close. A shipped task is the one moment the system KNOWS
+// the work is finished, and the moment almost all of that context becomes dead
+// weight.
+//
+// TWO HALVES, both pinned here:
+//   1. ship-card.js handoffAdvice — PURE, so every branch is a real assertion with
+//      no card, no DB, no session.
+//   2. .claude/skills/builder-sequence/SKILL.md — a DOC-CONTRACT check. The skill
+//      is the only place the between-links handoff can live (a hook cannot clear a
+//      conversation), and a prose step with nothing asserting it is exactly the
+//      kind of instruction that gets tidied away in a later edit. This is the same
+//      posture as the fitness doc checks: assert the RULE is stated, not its wording.
+//
+// WHY A THRESHOLD TEST AT ALL. The failure mode here is not a crash, it is
+// wallpaper: advice that prints on every ship stops being read (the
+// deploy-divergence footer is the in-repo cautionary tale — 21 core versions of
+// identical warning that nobody acted on). So "stays silent on a normal ship" is
+// the assertion that matters most, and it is first.
+//
+// Run:  node tests/session_boundary_handoff.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const card = require('../modules/lifecycle/ship-card.js');
+const { handoffAdvice, HEAVY_SESSION_CACHED_TOKENS, buildCardModel, renderMonospaceCard, renderCardHtml } = card;
+
+const { test, summary } = makeRunner();
+
+// The three real sessions the threshold was calibrated against (2026-08-21).
+const MEASURED = { light: 11.3e6, dragging: 36.1e6, heavy: 78.1e6 };
+
+// =========================================================================
+// 1. handoffAdvice — the decision
+// =========================================================================
+
+await test('SILENT on an ordinary ship — the whole design rests on this', () => {
+  // Advice that fires every time is wallpaper. A short session must never see it.
+  for (const cached of [0, 1, 1e6, MEASURED.light, HEAVY_SESSION_CACHED_TOKENS - 1]) {
+    assert.equal(handoffAdvice({ stage: 'shipped', cachedTokens: cached }), null,
+      `${cached} cached must stay silent`);
+  }
+});
+
+await test('SPEAKS once the session is genuinely heavy', () => {
+  for (const cached of [HEAVY_SESSION_CACHED_TOKENS, MEASURED.dragging, MEASURED.heavy]) {
+    const advice = handoffAdvice({ stage: 'shipped', cachedTokens: cached });
+    assert.ok(advice, `${cached} cached should advise`);
+    assert.match(advice, /session-handoff/, 'and names the command that does something about it');
+    assert.match(advice, /fresh session/, 'and says what to do with it');
+  }
+});
+
+await test('the advice quotes the ACTUAL figure, so it is arguable', () => {
+  // A builder who disagrees can check the number rather than take it on faith.
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }), /78\.1M cached/);
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.dragging }), /36\.1M cached/);
+});
+
+await test('NEVER mid-task — resetting inside a claim is actively wrong', () => {
+  // Mid-task the context is what the work is standing on. Only a stage where the
+  // task has left the builder's hands may advise a reset.
+  for (const stage of ['claimed', 'review', 'built', 'completed', 'failed']) {
+    assert.equal(handoffAdvice({ stage, cachedTokens: MEASURED.heavy }), null,
+      `stage '${stage}' must not advise a reset`);
+  }
+  // ...and the two that may.
+  assert.ok(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }));
+  assert.ok(handoffAdvice({ stage: 'confirmed', cachedTokens: MEASURED.heavy }),
+    'confirmed counts: the task is out of the builder\'s hands even though it has not landed');
+});
+
+await test('hostile or absent input is silence, never a throw', () => {
+  // This runs inside the ship card. A card that CRASHES at the end of a
+  // successful ship would turn a landed task into a scary traceback.
+  for (const args of [undefined, {}, null, { stage: 'shipped' }, { stage: 'shipped', cachedTokens: null },
+    { stage: 'shipped', cachedTokens: 'lots' }, { stage: 'shipped', cachedTokens: NaN },
+    { stage: 'shipped', cachedTokens: -1 }, { stage: null, cachedTokens: 1e9 }]) {
+    assert.doesNotThrow(() => handoffAdvice(args), `${JSON.stringify(args)} must not throw`);
+    assert.equal(handoffAdvice(args), null, `${JSON.stringify(args)} ⇒ silence`);
+  }
+  assert.equal(handoffAdvice(null), null, 'explicit null ⇒ silence, not a crash');
+});
+
+await test('the threshold sits between the session that felt fine and the one that dragged', () => {
+  // Documents the calibration as an assertion: if someone retunes the constant,
+  // this says what the number was chosen to separate.
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS > MEASURED.light,
+    'the 11.3M session was fine and must stay quiet');
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS < MEASURED.dragging,
+    'the 36.1M session had begun to drag and should be caught');
+});
+
+// =========================================================================
+// 2. The card — the advice has to actually reach the builder
+// =========================================================================
+
+await test('a heavy ship card carries the nudge, in BOTH renderers', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1003150, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy, newTokens: 891e3, costUsd: 49.81 },
+  });
+  assert.ok(model.handoff, 'it is on the model');
+  const mono = renderMonospaceCard(model);
+  assert.match(mono, /heavy session/, 'terminal card shows it');
+  assert.match(mono, /Next →/, 'and it sits with the Next action it qualifies');
+  // Position matters: the nudge must come AFTER Next, as a qualifier, not above it.
+  assert.ok(mono.indexOf('Next →') < mono.indexOf('heavy session'), 'below the action, not shouting over it');
+  assert.match(renderCardHtml(model), /heavy session/, 'in-feed card shows it too');
+});
+
+await test('a normal ship card is BYTE-IDENTICAL to before the nudge existed', () => {
+  // The regression that matters: every ordinary ship must look exactly as it did.
+  const usage = { cachedTokens: MEASURED.light, newTokens: 262e3, costUsd: 8.06 };
+  const model = buildCardModel({ stage: 'shipped', taskId: 1003148, title: 'A task', usage });
+  assert.equal(model.handoff, null);
+  const mono = renderMonospaceCard(model);
+  assert.doesNotMatch(mono, /heavy session/);
+  assert.doesNotMatch(mono, /session-handoff/);
+  assert.doesNotMatch(renderCardHtml(model), /heavy session/);
+  // A card with no usage data at all (old breadcrumbs) must also stay clean.
+  const bare = buildCardModel({ stage: 'shipped', taskId: 1, title: 'A task' });
+  assert.equal(bare.handoff, null);
+  assert.doesNotMatch(renderMonospaceCard(bare), /heavy session/);
+});
+
+await test('the nudge is not a Usage/Deploy ROW — it is guidance, not a task fact', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy },
+  });
+  assert.equal(model.rows.some((r) => /heavy session/.test(String(r.v))), false,
+    'rows report facts about the TASK; this is advice about the SESSION');
+  assert.equal(model.facts.some((f) => /heavy session/.test(String(f.value))), false);
+});
+
+// =========================================================================
+// 3. /builder-sequence — the doc contract
+//
+// A hook cannot clear a conversation and /session-handoff is read-only, so the
+// runner skill is the ONLY place the between-links handoff can live. That makes
+// its prose load-bearing, and load-bearing prose needs a test.
+// =========================================================================
+
+const SEQ = fs.readFileSync(path.join(ROOT, '.claude/skills/builder-sequence/SKILL.md'), 'utf8');
+
+await test('the sequence runner states the between-links handoff step', () => {
+  assert.match(SEQ, /\/session-handoff/, 'it names the command');
+  assert.match(SEQ, /fresh session/i, 'and that the chain continues in a fresh one');
+  assert.match(SEQ, /heavy session/i, 'and the ship-card signal it keys off');
+});
+
+await test('...and tells the runner to STOP rather than claim the next link', () => {
+  // The failure mode: a runner that emits the prompt and then helpfully carries on
+  // in the same window has done the paperwork and none of the work.
+  assert.match(SEQ, /do not claim the next task in this window/i,
+    'the halt must be explicit — emitting a prompt and continuing anyway is the trap');
+});
+
+await test('...and says WHY, with the measurement, not just what', () => {
+  // An unexplained instruction is the first thing dropped in a later edit.
+  assert.match(SEQ, /re-?read/i, 'names the mechanism (context re-read per turn)');
+  assert.match(SEQ, /11\.3M|36\.1M|78\.1M/, 'carries the measured figures');
+  assert.match(SEQ, /durable|GDS/, 'and why a fresh window is safe: the chain state is durable');
+});
+
+await test('the runner is warned against running a chain to exhaustion', () => {
+  assert.match(SEQ, /What NOT to do/, 'the section exists');
+  assert.match(SEQ, /exhaustion|one window/i, 'and names the anti-pattern this step prevents');
+});
+
+summary('session_boundary_handoff');