@bongos/core 1.19.477 → 1.19.479

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

@@ -0,0 +1,103 @@
+---
+name: minimalist-ui
+description: Quiet editorial product interfaces built out of type and white space, inside the instance's world. Macro whitespace first, a capped measure, one display job and one body job, exactly one hairline weight for every border in the sheet, washed accents measured against their own ink, flat tile cards with no shadow, box-less accordions, keycap shortcuts, one depth treatment per band, entry motion inside the Kill Switch. Triggers on "make it minimal", "clean and editorial", "quiet", "document-like", "this feels busy". Declines dense surfaces like dashboards and ledgers. Rebuilt in-house from the taste-skill rebuild spec (task 1003327, ADR 0198); the palette is the pack and the nearest library look is expedition.
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `minimalist-skill` entry), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325) — the `[minimalist-ui]` requirement group — and this file is its port under [task 1003327](https://cloudbongos.com/builders#/task/1003327); it implements those requirements from scratch, **no upstream bytes consulted or copied**. The landing shape is [ADR 0220](../../../../docs/adr/<redacted>.md); what a *look* skill is allowed to be is [ADR 0230](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose: the upstream shipped a **palette** (white or warm bone canvas, near-white cards, washed-out pastel accents each with its own darker text tone). Here that palette is a **look in the library** — `modules/ui-design/styles/expedition` is the warm-paper entry this skill was tuned against — and the canvas is whatever `bg` / `bg-card` the instance's pack carries. The upstream's editorial serif for hero headings becomes the pack's `display` stack; a face this skill wants and the pack does not have is a pack change, not a page's `@font-face`. Its pastels become `color-mix()` of the pack's `accent`, `sea` and `terracotta` against `bg-card`, each paired with the contract's own ink for that field, so a badge is measured rather than guessed. Its imagery clause is gone: **seeded placeholder photography does not exist here**, and the only rasters this skill may ask for are text-free hero plates under the owner's rule. Its ban on pill shapes for primary buttons is a default an instance's `DESIGN.md` overrules — Cloud Bongos's own door pill is that world's signature and wins. Its entry motion survives only inside the Kill Switch.
+
+## Where this look lives
+
+The **grammar** below is this skill's. The **palette** is not: it comes from the instance's pack, and a variant comes from the style library at `modules/ui-design/styles/`. The nearest library entry to this look is `expedition` (warm paper, hairline frames, one lamp yellow as a fill); `grove` reads the same grammar cooler; `chrome-world` is where the grammar has to fight the void and usually loses. Render under one with `--style <name>` before you commit to it. Adopting one is the owner's `config/branding.json`; a page never picks its own.
+
+## Fires on
+
+Clean, document-like product interfaces built out of type and white space: a reading surface, a settings sheet, a changelog, a pricing page, a documentation shell, an editorial marketing page whose argument is the words. It does **not** fire on a surface whose job is density (a dashboard, a data table, a ledger) — the quiet grammar makes a dense surface harder to read, not calmer. Say so and route to `impeccable layout` or `design-taste-frontend-v1` instead.
+
+## Execution order
+
+Do these in order; each one constrains the next, and doing them out of order produces a busy page with generous padding rather than a quiet one.
+
+1. **Macro whitespace first.** Set the band rhythm before any component exists: the world's band clamp between chapters, and inside a chapter one step of `spacing`. A section that needs a divider to be legible has too little air, not too few rules.
+2. **Constrain the measure.** Body text sits at 60 to 70 characters. The container is the world's `spacing.container`; a reading column inside it is narrower still, and it is centred only if the page has no rail.
+3. **The type scale and the tokens.** Every size from the world's scale, every colour a `var()` or a `color-mix()` of the fifteen. This is where the look is decided; nothing below adds a colour.
+4. **The hairline rule on every border.** See below. Do this as one pass over the whole sheet, not per component.
+5. **Depth, then entry motion.** Both last, both optional, both removable without the page changing meaning.
+
+## Typography
+
+- **One display job, one body job.** The pack carries two stacks; a minimalist surface uses `display` for the h1 and h2 only and `body` for everything else. Where the pack's two stacks are the same family (the chrome world's are), the contrast is **weight and tracking**, not family: display at 300 with tight tracking, body at 400 at the world's default tracking.
+- **Tight display, generous body.** Display headings take negative tracking (about -0.02em) and a line height near 1.05; body takes 1.6 to 1.7. The contrast between the two is the whole look.
+- **Mono for metadata and code**, from the pack's `links` (the chrome world loads JetBrains Mono). Numerals in a table or a stat are tabular; a number that changes in place never reflows its neighbours.
+- **Off-black body ink**, which is what `ink` already is; the softer tiers (`ink-soft`, `ink-faint`) carry captions and labels. Pure black as body ink is a different look.
+- **No orphan.** A headline's last word never sits alone on its own line; fix it by widening the container or reducing the clamped size, never by rewriting the sentence for the layout's convenience.
+
+## Colour and the hairline rule
+
+- **The canvas is the pack's `bg`; a card is `bg-card`;** a recessed well is `bg-deep`. Three grounds, no more, and the step between them is small enough that the page reads as one sheet of paper.
+- **Every border is a hairline**: 1px, `rule-soft` at rest, `rule` where it separates two live regions. There is no second border weight anywhere on the surface. A border that needs to be heavier is a background change.
+- **Accents are washed, and each carries its own ink.** A badge, a tag or a quiet highlight is `color-mix(in srgb, var(--accent) 22%, var(--bg-card))` with `accent-ink` on it; the same shape in the `sea` or the `terracotta` field uses that field's ink. Measure the pair with `node modules/ui-design/kit/contrast.js` — a washed pastel is exactly where AA gets lost.
+- **One solid call to action**, the accent as the fill with `accent-on` as the ink, and **no shadow on it**. The rest of the page's buttons are hairline-bordered and transparent.
+- **Banned by default** (an instance's `DESIGN.md` may overrule any of these): gradients as a surface treatment, neon, a heavy or untinted drop shadow, 3D glass, a hero band painted in the accent, and a fully rounded pill on a large container. Where the instance's world has a signature that breaks one of these, the world wins and the sheet says so in a comment.
+
+## Components
+
+- **Tile cards**: a hairline border, the world's small radius (never the panel radius), padding at `spacing.md` or more, and no shadow. Cards sit in a flat grid with a real gutter; nothing lifts at rest.
+- **Badges**: uppercase, the world's label size, tracked out, the washed field with its own ink, a small radius. Never a full pill, never the accent at full strength.
+- **Accordions**: no box. Two rows are separated by one hairline and nothing else; the open row is marked by its own weight, not by a container appearing around it.
+- **Keycaps**: mono, the world's smallest size, a hairline border, a 3px radius, `bg-deep` as the fill. A shortcut is written as keys, not as prose.
+- **Tables**: hairlines between rows, none between columns; the header row is `ink-soft` at label size, tracked out, uppercase.
+
+## Copy
+
+Realistic and specific, always. Banned: emoji, placeholder person and company names, lorem, invented round numbers, and the marketing verbs that mean nothing (`unleash`, `supercharge`, `revolutionize`, `elevate`). If the real content is not known yet, write the shortest true sentence and mark the gap in a comment — a page full of plausible fiction is harder to fix than a page with a hole in it.
+
+## Quiet depth
+
+A band must not read as a flat empty strip. Give it one of these, and only one:
+
+- a faint radial of the pack's own warm token, `radial-gradient(circle at 30% 0%, color-mix(in srgb, var(--accent) 8%, transparent), transparent 60%)`, sitting behind the content;
+- a minimal line pattern from a `repeating-linear-gradient` of `rule-soft` at low alpha, on a pointer-inert pseudo-element;
+- a **text-free hero plate** from the instance's world, as a background token on `body` with a provenance sidecar beside it, never an `<img>` and never on more than one band per page.
+
+That is the whole list. Depth is a background job; it never touches the content layer, and it is invisible in a screenshot taken at 320.
+
+## Motion, inside the Kill Switch
+
+Felt, not noticed. All CSS, on the world's curves, nothing authored in JavaScript.
+
+- **Entry**: a fade with a 12 to 16px rise on the entrance curve, about 500ms. Prefer `animation-timeline: view()` behind `@supports`; where that is unsupported, one `IntersectionObserver` may add a single class and the motion stays in CSS. The rest frame is the finished page, so a browser with no script shows a complete composition.
+- **Cascade**: across a list or a grid, `animation-delay` stepped from an `--i` in the markup, capped at about 6 steps so the last card is never noticeably late.
+- **Hover**: an ultra-subtle lift on a card, `translateY(-2px)` and a hairline that goes from `rule-soft` to `rule`. No shadow appears on hover that was not there at rest.
+- **Press**: `scale(.98)` on `transform` only.
+- **`@media (prefers-reduced-motion: reduce)` at the foot of the token layer kills all of it**, and the page is complete without it.
+
+## Pre-flight, measured by the kit
+
+Render the real surface — `node modules/ui-design/kit/render.js --page <path>` (add `--style expedition` to see it under the library's warm paper) — and read the shots, not the source.
+
+- [ ] One display job, one body job; the contrast is weight and tracking where the pack has one family.
+- [ ] Measure between 60 and 70 characters on the reading column at 1440.
+- [ ] **One** border weight in the whole sheet, and it is a hairline.
+- [ ] Every washed accent pair measured with `contrast.js`, AA in both modes.
+- [ ] Exactly one depth treatment per band, none on the content layer.
+- [ ] Every band that looked empty at 1440 still reads at 390 and 320.
+- [ ] Reduced-motion pass identical to the rest frame.
+- [ ] `node modules/ui-design/kit/check-mock.js` clean, including the craft tells; a tell you mean to keep is waived in the file with its reason.

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

@@ -0,0 +1,91 @@
+---
+name: stitch-design-taste
+description: Writes a design contract document for an external screen-generating tool such as Google Stitch, in the platform's own frontmatter shape. Four dials (creativity, density, variance, motion intent) with named bands and stated defaults, then eight fixed sections (atmosphere, colour roles, typography, components, layout, responsive rules, motion intent, banned patterns) written as descriptive language paired with exact values. The thirteen colours are transcribed from the instance's pack and diffed, never invented; motion is an intent brief inside the Kill Switch; the screens that come back are a reference, not a source of truth. Triggers on "write a design brief for Stitch", "a design contract document", "a prompt-to-screen tool". Rebuilt in-house from the taste-skill rebuild spec (task 1003327, ADR 0198).
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `stitch-skill` entry and its `DESIGN.md`), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325) — the `[stitch-design-taste]` requirement group — and this file is its port under [task 1003327](https://cloudbongos.com/builders#/task/1003327); it implements those requirements from scratch, **no upstream bytes consulted or copied**. The landing shape is [ADR 0220](../../../../docs/adr/<redacted>.md); what a *look* skill is allowed to be is [ADR 0230](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose: the upstream **authored a palette** for the downstream tool — a descriptive name, a hex and a role per token, invented to taste. Here the colour contract is **transcribed, not invented**: it is the instance's thirteen with their real hex values and the roles the instance's `DESIGN.md` already gives them, so the external tool and the built surface cannot diverge. The document it writes uses the platform's own frontmatter shape — the one every look in `modules/ui-design/styles/` carries — rather than a shape of its own, so a document produced here can be read back as a style. Its universal bans (no pure black, no serif in a dashboard, the default UI sans banned) become **defaults the instance's `DESIGN.md` overrules**: Cloud Bongos's own world is a black void, and a document that told the tool otherwise would describe a different product. Its "signature move" of small contextual images set inline between headline words survives as a **hero object** under the owner's rule: a text-free cutout with its provenance sidecar, never a photograph of a screen. Its motion section stays what it always was, an intent brief for whoever writes the code afterwards, and every parameter in it is written to live inside the Kill Switch.
+
+## Where this look lives
+
+This skill writes a **document**, not code. The palette it transcribes is the instance's pack; the recipes it transcribes are the instance's `DESIGN.md`; a variant is a look from the style library at `modules/ui-design/styles/`, named by its directory so the reader can render it (`chrome-world`, `expedition` and `grove` today). It never invents a fifteen-token world and it never edits the instance's.
+
+## Fires on
+
+The deliverable is a **design contract document for an external screen-generating tool** — Google Stitch, a comparable prompt-to-screen product, or any collaborator who will produce screens from prose rather than from a repository. It does not fire when the deliverable is code (that is `design-taste-frontend` or `impeccable shape`), and it does not fire when the deliverable is a new look for the library (that is the `/style` session).
+
+## Step 1 — the dials
+
+Open the document with four dials, each with named bands and a stated default, set from the owner's description of the vibe and written as one line each.
+
+| Dial | Bands | Default | What it moves |
+|---|---|---|---|
+| **Creativity** | conventional · considered · expressive | considered | how far a screen may depart from the archetype the surface implies |
+| **Density** | airy · balanced · dense | balanced | information per screen; `dense` switches numerals to mono and tightens the scale |
+| **Variance** | uniform · varied · asymmetric | varied | how much two sibling screens may differ in structure |
+| **Motion intent** | still · restrained · alive | restrained | what the downstream coder is asked to build, all of it inside the Kill Switch |
+
+State the default and the chosen value. A dial the owner did not speak to keeps its default and says so.
+
+## Step 2 — the document, in this order
+
+The section order is fixed. The reader is a tool that interprets **visual description**, so every rule is written as descriptive natural language **paired with an exact value** — "a warm salmon, the pack's `accent` hex verbatim, used only on what is pressable or live", never `bg-accent-500`. Utility class names mean nothing to it.
+
+1. **Atmosphere** — three or four sentences on what the surface feels like and what it is not. This is the only prose section; everything below is rules with values.
+2. **Colour roles** — the instance's thirteen, transcribed: descriptive name, hex, functional role, one row each. One palette for the whole output. One accent. Where the instance's world uses a colour the upstream would have banned (a pure black ground, a saturated accent), transcribe it and note that it is the instance's decision, not a default.
+3. **Typography** — the pack's two stacks by name with their real fallbacks, the scale as values, tracking and measure specified per role, and which roles use mono numerals (always, above `density: dense`).
+4. **Components** — the vocabulary the instance already has, described: tactile press feedback with no outer glow; cards only where elevation carries hierarchy; label-above-input forms with the error below the field; skeleton loaders shaped like the content, never a spinner; composed empty states with an action in them; errors inline rather than in a toast.
+5. **Layout** — grid over flexbox arithmetic; no overlapping content layers; no three-equal-card feature row; a max-width container with its value; dynamic viewport height (`100dvh`) for any full-height section.
+6. **Responsive rules**, a hard requirement, not advice — single-column collapse below the tablet breakpoint; zero horizontal overflow; headline sizes clamped with a stated body-size floor; 44px minimum touch targets (the platform floor is 24px of clearance on both sides of every control, and this is the tighter of the two); and the named test viewports, 1440, 390 and 320.
+7. **Motion intent** — written for the coding agent, because the generating tool emits static screens: the curve and duration per interaction, perpetual micro-loops only where the world has one, staggered mounts with their step, `transform` and `opacity` only, and the statement that every rule here sits inside `@media (prefers-reduced-motion: reduce)` at the foot of the token layer with a complete rest frame.
+8. **Banned patterns** — the closing list, below.
+
+## The hero contract
+
+- **One primary call to action.** A second competing action on the same screen is a defect.
+- **Small contextual images set inline between headline words** are this contract's signature move, and under the owner's rule they are **hero objects**: text-free cutouts with a provenance sidecar, sized to the cap height, never a photograph of an interface.
+- **No overlapping layers** in the hero, no scroll-cue filler text, and above `variance: varied` the structure is asymmetric.
+- Full-page **hero plates** are text-free by definition; the document says so explicitly so the downstream tool does not letter one.
+
+## Banned patterns (the closing list)
+
+Emoji · the default UI sans as a display face where the pack has a real one · pure black as a *ground the instance did not choose* · neon glows · custom cursors · placeholder person and company names · fake round numbers · cliché marketing verbs · unstyled component-library defaults · arbitrary `z-index` values · circular spinners · a three-equal-card feature row · gradient text · a screenshot of an interface built out of divs.
+
+Each line is a default. The document states plainly that the instance's `DESIGN.md` is the authority and that where it disagrees with this list, it wins — otherwise the external tool is being told a different product exists.
+
+## Step 3 — prove it before it is sent
+
+A document that cannot be built is a wish list.
+
+- **Transcription check**: the thirteen hexes in the document equal the instance's pack, value for value. Diff them; do not retype them.
+- **Contrast**: `node modules/ui-design/kit/contrast.js` over the pack, and every pair the document names as a component's colour must be in the clean list.
+- **Reference render**: render the nearest existing surface — `node modules/ui-design/kit/render.js --page <path>` (add `--style <name>` for a look from the library) — and attach the 1440, 390 and 320 shots to the document. The tool composes better against a real specimen than against prose alone, and a rule the specimen contradicts is a rule that was wrong.
+- **Round trip**: when the screens come back, they are a reference, not a source of truth. `image-to-code` reads them, the instance's world overrides them, and what ships goes through the kit like anything else.
+
+## Pre-flight
+
+- [ ] Four dials, each with its bands, its default and its chosen value.
+- [ ] The eight sections, in order, every rule paired with an exact value.
+- [ ] The thirteen transcribed from the pack and diffed, not retyped.
+- [ ] Every colour pair the document names cleared by `contrast.js`.
+- [ ] The responsive section names 1440, 390 and 320 and states the overflow rule.
+- [ ] The motion section states the Kill Switch and a complete rest frame.
+- [ ] The banned list closes with the instance-wins clause.
+- [ ] The reference shots are attached, and the document names the look they were rendered under.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.477",
+  "version": "1.19.479",
   "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

@@ -34,7 +34,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.477'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.479'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/closeness.mjs

@@ -9,9 +9,10 @@
 //   3. a hidden builder appears in no graph.
 //
 // The scorer is pure, so 1 and 2 are driven with real inputs rather than asserted
-// over source. 3 is a consent property of the read, and is driven through the
-// real applyConsent gate with stub readers — including the failure modes, which
-// are the ones that actually matter.
+// over source. 3 is a consent property of the read, and since task 1003175 (C05)
+// it is driven through the REAL graph read against a stub pool — the leak tests
+// need a graph that was actually assembled, not a gate called in isolation —
+// including the failure modes, which are the ones that actually matter.
 import { strict as assert } from 'node:assert';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
@@ -152,55 +153,174 @@ test('effective weights always sum to 1 over the available subset', () => {
   assert.ok(Math.abs(summed - 1) < 1e-3, `effective weights sum to ${summed}`);
 });
 
-// ── 3. CONSENT: a hidden builder appears in NO graph ────────────────────────
-
-const entries = () => [
-  { builder_id: '10', score: 0.9 },
-  { builder_id: '20', score: 0.5 },
-  { builder_id: '30', score: 0.1 },
-];
-
-test('THE CONSENT RULE: a hidden builder is removed from the graph', () => {
-  return closeness.applyConsent(entries(), async () => new Set(['20']))
-    .then((out) => assert.deepEqual(out.map((e) => e.builder_id), ['10', '30']));
+// ── 3. CONSENT IS THE READ PATH (task 1003175 / C05) ────────────────────────
+//
+// C04 gated the graph by filtering assembled rows. C05's criterion says that is
+// not enough: "the hide cannot be a post-filter over an already-assembled graph —
+// an assembled-then-filtered graph leaks through counts, ranks and 'you have 4
+// close collaborators' totals even when the node itself is hidden. Test the leak,
+// not just the absence of the row."
+//
+// So these drive the REAL closenessFor against a stub pool and assert on the four
+// things a post-filter gets wrong — the total, the identity read, the ranking and
+// the page — rather than only on the missing row. Every one of them fails if the
+// gate is moved back downstream of assembly.
+
+// A pool that answers the three signal queries and the hydrate, keyed off the SQL
+// each read actually sends. It also RECORDS which ids were hydrated, which is how
+// "a hidden builder's identity is never read" becomes an observation rather than a
+// claim about source order.
+function fakePool({ coClaim = {}, coSession = {}, shipped = {} } = {}) {
+  const seen = { hydrated: null };
+  const toRows = (obj) => Object.entries(obj).map(([other_id, n]) => ({ other_id, n }));
+  return {
+    seen,
+    async query(sql, params) {
+      if (/FROM claims mine/.test(sql)) return { rows: toRows(coClaim) };
+      if (/FROM session_logs mine/.test(sql)) return { rows: toRows(coSession) };
+      if (/FROM tasks t_mine/.test(sql)) return { rows: toRows(shipped) };
+      if (/FROM builders WHERE id/.test(sql)) {
+        seen.hydrated = (params[0] || []).map(String);
+        return {
+          rows: seen.hydrated.map((id) => ({
+            id, github_login: `u${id}`, display_name: `B${id}`, avatar_url: null,
+          })),
+        };
+      }
+      throw new Error(`unexpected query: ${sql.slice(0, 70)}`);
+    },
+  };
+}
+
+// Four collaborators of clearly separated strength. '40' is the STRONGEST, so
+// hiding them is the case that moves the top of the ranking.
+const GRAPH = { coClaim: { 10: 1, 20: 2, 30: 3, 40: 9 } };
+const hides = (...ids) => async () => new Set(ids.map(String));
+
+test('THE CONSENT RULE: a hidden builder is no node in anyone else\'s graph', async () => {
+  const pool = fakePool(GRAPH);
+  const { entries } = await closeness.closenessFor(1, { hiddenIdsFor: hides(40) }, { pool });
+  assert.deepEqual(entries.map((e) => e.builder_id).sort(), ['10', '20', '30']);
+});
+
+test('THE COUNTS LEAK: the total counts the CONSENTED graph, not the assembled one', async () => {
+  // This is the criterion's own example. Four candidates, one hidden — a surface
+  // that says "you have 4 close collaborators" over a list of 3 has leaked the
+  // hidden builder by subtraction, without ever showing their row.
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, { hiddenIdsFor: hides(40) }, { pool });
+  assert.equal(total, 3, 'the total is counted after the gate, not before it');
+  assert.equal(entries.length, 3);
+});
+
+test('THE IDENTITY LEAK: a hidden builder\'s name is never even fetched', async () => {
+  // Not fetched and then dropped — never asked for. A post-filter that ran after
+  // hydrate would still have read the row.
+  const pool = fakePool(GRAPH);
+  await closeness.closenessFor(1, { hiddenIdsFor: hides(40) }, { pool });
+  assert.ok(pool.seen.hydrated, 'the graph was hydrated');
+  assert.ok(!pool.seen.hydrated.includes('40'), 'the hidden builder was never looked up');
+});
+
+test('THE RANK LEAK: hiding the top scorer leaves no gap at the top', async () => {
+  // Ranking runs over the consented set, so the #1 slot is the strongest VISIBLE
+  // collaborator. Ranked before the gate, the top slot belongs to the hidden
+  // builder and is then removed — so "who am I closest to" comes back EMPTY for a
+  // builder who has three collaborators, which tells them precisely that someone
+  // was taken out from above them. Asked for one, you get the real one.
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, { limit: 1, hiddenIdsFor: hides(40) }, { pool });
+  assert.equal(entries.length, 1, 'the #1 slot is filled, not vacated by the hidden builder');
+  assert.equal(entries[0].builder_id, '30', 'and it is the top VISIBLE builder');
+  assert.equal(total, 3);
+
+  // Ordering over the whole consented graph is dense and monotonic — no rank a
+  // reader could subtract from.
+  const all = await closeness.closenessFor(1, { hiddenIdsFor: hides(40) }, { pool });
+  const scores = all.entries.map((e) => e.score);
+  assert.deepEqual(scores, [...scores].sort((a, b) => b - a));
+});
+
+test('THE PAGE LEAK: a page is refilled from the rest, never returned short', async () => {
+  // Gating after the slice would hand back one row for a limit of two, and a page
+  // that comes back short announces a removal as loudly as the row would have.
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, { limit: 2, hiddenIdsFor: hides(40) }, { pool });
+  assert.equal(entries.length, 2, 'the page is full');
+  assert.deepEqual(entries.map((e) => e.builder_id), ['30', '20']);
+  assert.equal(total, 3, 'and the total still describes the whole consented graph, not the page');
 });
 
 test('FAIL CLOSED: a consent read that THROWS empties the graph', async () => {
   // An unreadable consent state is not permission. This is the direction that
   // matters: the opposite default would serve a hidden builder on any hiccup.
-  const out = await closeness.applyConsent(entries(), async () => { throw new Error('hub down'); });
-  assert.deepEqual(out, []);
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, {
+    hiddenIdsFor: async () => { throw new Error('hub down'); },
+  }, { pool });
+  assert.deepEqual(entries, []);
+  assert.equal(total, 0);
+  assert.equal(pool.seen.hydrated, null, 'and nobody was looked up on the way out');
 });
 
 test('FAIL CLOSED: a consent read returning null empties the graph too', async () => {
   // null is not "nobody is hidden".
-  const out = await closeness.applyConsent(entries(), async () => null);
-  assert.deepEqual(out, []);
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, { hiddenIdsFor: async () => null }, { pool });
+  assert.deepEqual(entries, []);
+  assert.equal(total, 0);
 });
 
 test('no consent reader at all leaves the graph intact — that is not a hole', async () => {
   // Where the hub module is off there is no hub-level hide flag to honour,
   // because nobody on that instance has been offered the switch. Suppressing
   // everyone would not be consent, it would be an outage.
-  const out = await closeness.applyConsent(entries(), null);
-  assert.equal(out.length, 3);
+  const pool = fakePool(GRAPH);
+  const { entries, total } = await closeness.closenessFor(1, {}, { pool });
+  assert.equal(entries.length, 4);
+  assert.equal(total, 4);
 });
 
-test('consent is ONE gate the reads pass through, not a filter at each call site', () => {
-  // C05 (task 1003175) is "consent is the read path, not a filter bolted on
-  // after" — it needs a single structural place, and this is it.
-  assert.equal((SRC.match(/await applyConsent\(/g) || []).length, 1,
-    'exactly one call site applies consent');
-  assert.match(SRC, /entries = await applyConsent\(entries, hiddenIdsFor\);/);
+// ── the gate's own shape ────────────────────────────────────────────────────
+
+test('THE GATE TAKES IDS, NEVER ASSEMBLED ROWS — that is what makes it the read path', () => {
+  // The whole of C05 is this signature. A gate over ids can only be applied before
+  // there is anything to derive; a gate over rows invites being applied after.
+  const fn = SRC.slice(SRC.indexOf('async function consentedIds'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.ok(!/\.score|\.builder_id|entries/.test(body),
+    'the gate never touches a scored row');
 });
 
-test('a suppressed builder\'s identity is never even read', () => {
-  // hydrate() runs AFTER applyConsent, so a hidden builder\'s name and avatar are
-  // not fetched at all — not fetched and then dropped.
+test('consent is applied to the SIGNALS, so the graph is built from consented data', async () => {
+  // readConsentedSignals is the single structural place. The maps it returns do
+  // not contain a hidden builder, so nothing assembled from them can.
+  const pool = fakePool(GRAPH);
+  const signals = await closeness.readConsentedSignals(1, { hiddenIdsFor: hides(40) }, { pool });
+  assert.deepEqual([...signals.ids].sort(), ['10', '20', '30']);
+  assert.ok(!signals.co_claim.has('40'), 'the hidden builder is not a key in the signal map');
+});
+
+test('consent is ONE gate, and the graph read never re-implements it', () => {
+  assert.equal((SRC.match(/await consentedIds\(/g) || []).length, 1,
+    'exactly one call site applies the gate');
+  const fn = SRC.slice(SRC.indexOf('async function closenessFor'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.ok(!/consentedIds|\.filter\([^)]*hidden/i.test(body),
+    'closenessFor does not filter on consent itself — it reads already-consented data');
+  assert.match(body, /await readConsentedSignals\(/);
+});
+
+test('everything derived comes AFTER the gate', () => {
+  // Source order is the backstop for the behavioural tests above: the read, then
+  // the scoring, then the total. A future aggregate added below this line inherits
+  // the guarantee; one added above it would not.
   const fn = SRC.slice(SRC.indexOf('async function closenessFor'));
   const body = fn.slice(0, fn.indexOf('\n}'));
-  assert.ok(body.indexOf('applyConsent') < body.indexOf('return hydrate'),
-    'consent is applied before hydration');
+  const gate = body.indexOf('readConsentedSignals');
+  for (const derived of ['scoreCloseness(', 'entries.sort(', 'const total', 'hydrate(']) {
+    assert.ok(gate < body.indexOf(derived), `${derived} is computed after the gate`);
+  }
 });
 
 test('the pair read cannot be used to detect that someone hid themselves', () => {