@boopkit/cap-web 0.5.7 → 0.5.8

package/capability.json

@@ -26,9 +26,11 @@
   ],
   "skills": [
     "boop-web-web-ui-design",
+    "boop-web-css",
     "boop-web-testing",
     "boop-web-website-dev-workflow",
-    "boop-web-design-handoff-workflow"
+    "boop-web-design-handoff-workflow",
+    "boop-web-design-handoff-bundle"
   ],
   "scripts": {
     "tailwind:build": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-web",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Express view engine configuration, Handlebars helpers, and static asset middleware",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scaffold/reference/web-ui.ref.md

@@ -2,7 +2,7 @@
 
 How this project renders pages: Handlebars templates, Tailwind CSS, static assets, and the request pipeline.
 
-**Related skills**: [design.web-ui-design.skill.md](../skills/design.web-ui-design.skill.md)
+**Related skills**: [boop-web-web-ui-design](../skills/boop-web-web-ui-design/SKILL.md) for pages, templates and markup; [boop-web-css](../skills/boop-web-css/SKILL.md) for class names and stylesheet rules
 
 ---
 
@@ -29,18 +29,31 @@ Handlebars via `express-handlebars`. Templates in `views/`, layouts in `views/la
 
 ### Helpers
 
-~130 helpers registered from `handlebars-helpers` (comparison, string, math, array). Custom helpers from `@boopkit/cap-web`:
+About 130 helpers are registered from [`handlebars-helpers`](https://github.com/helpers/handlebars-helpers).
+The most useful:
+
+| Kind | Helpers |
+|------|---------|
+| Comparison | `gt`, `lt`, `gte`, `lte`, `eq`, `is`, `not`, `compare` |
+| Logical | `and`, `or`, `not` |
+| String | `capitalize`, `trim`, `replace`, `startsWith`, `contains` |
+| Array | `first`, `last`, `sort`, `forEach`, `join` |
+| Math | `add`, `subtract`, `multiply`, `divide`, `ceil`, `floor`, `round` |
+
+Custom helpers from `@boopkit/cap-web`:
 
 | Helper | Purpose |
 |--------|---------|
-| `json` | JSON stringify with formatting |
-| `truncate` | Truncate string with ellipsis |
-| `urlencode` | Percent-encode a value for a query parameter: `href="/signup?next={{urlencode next}}"`. Handlebars escapes for HTML, not for a URL, so a value interpolated straight into a query string is truncated at its first `&`. |
-| `fmt_dollars` | Currency formatting |
-| `fmt_percent` | Percentage formatting |
-| `fmt_date` | Human-readable date (e.g., "March 28, 2026") |
-| `markdown` | Render markdown to HTML |
-| `icon` | Inline SVG from heroicons: `{{icon "user" "24/outline"}}` with optional `class=` |
+| `fmt_dollars` | Currency: `{{fmt_dollars 1234}}` → `$1,234`. An optional `sigfigs` rounds for data visualisation: `{{fmt_dollars 12345 sigfigs=4}}` → `$12,350`. |
+| `fmt_percent` | Percentage: `{{fmt_percent 45}}` → `45%` |
+| `fmt_date` | Human-readable date: `{{fmt_date createdAt}}` → `March 28, 2026` |
+| `markdown` | Render markdown to HTML: `{{markdown text}}` or `{{#markdown}}...{{/markdown}}` |
+| `icon` | Inline SVG from heroicons: `{{icon "user" "24/outline"}}`, with an optional class: `{{icon "check" "24/solid" class="icon done"}}`. Styles are `24/outline`, `24/solid`, `20/solid` and `16/solid`. Icons are read from `node_modules/heroicons/` and cached. |
+| `json` | JSON stringify with formatting: `{{json obj}}` |
+| `truncate` | Truncate a string with an ellipsis: `{{truncate text 100}}` |
+| `urlencode` | Percent-encode a value for a query parameter: `href="/signup?next={{urlencode next}}"`. Handlebars escapes an interpolated value for HTML, not for a URL, so `?next={{next}}` renders a return path of `/a&b=c` as `next=/a&b=c` and the browser reads `next=/a`. Use it for every value that lands in a query string. It encodes rather than validates, so whatever checks the value keeps doing that job. |
+| `upper` / `lower` | Case conversion |
+| `eq` | Strict equality (also available from `handlebars-helpers`) |
 
 ---
 
@@ -62,6 +75,12 @@ npm run tailwind:watch   # Development (watch mode)
 
 Use semantic class names in templates, define them in `styles/styles.css` with `@apply` for Tailwind utilities. Avoid inline Tailwind classes in templates except for one-off spacing.
 
+Class names nest.
+A block has one class, its children are nested inside it in the stylesheet with short names (`.quote-card .price`), and a variant or state is a second class on the element (`class="quote-card booked"`), selected with `&.booked`.
+BEM's `__element` and `--modifier` separators are not used, nor are flat prefixed names such as `.quote-card-price`.
+Colors, sizes and spacing come from the theme tokens in `@boopkit/cap-web/styles/theme.css`, through `var()` or `@apply`.
+The rules, with an example, are in the [boop-web-css](../skills/boop-web-css/SKILL.md) skill.
+
 ---
 
 ## Static Assets

package/skills/boop-web-css/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: boop-web-css
+description: "When you need to write or change CSS — adding or renaming a class, writing a selector or a stylesheet rule, or editing a class attribute in a template — name classes for what their elements are for, nest each block's children and variants inside it, and never use BEM's __element or --modifier separators."
+metadata:
+  category: web
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Writing CSS
+
+## Goal
+
+**A stylesheet's nesting is its structure, so a class name never repeats it.**
+
+A block gets one class that names what it is.
+Its children are nested inside it in the stylesheet and take short names for what they are.
+A variant or a state is a second class on the same element, selected with `&.name`.
+The stylesheet then reads as the shape of the page, and a template's class attributes stay short.
+
+This skill applies every time you touch a class, not only when you design a page.
+It is separate from `boop-web-web-ui-design` for that reason: a one-line change to a class attribute is CSS work, and it is where the naming goes wrong.
+
+## Name classes for what an element is for
+
+A class name says what the element is for, not how it looks.
+`.page-title`, `.price` and `.booked` survive a redesign; `.big-bold`, `.text-green` and `.mt-4` do not, and they tell a reader nothing about the page.
+
+Use lowercase words joined by hyphens.
+Keep Tailwind utility classes out of templates, except for a one-off spacing tweak; apply them inside a semantic class with `@apply` instead.
+
+## The nested shape
+
+```css
+/** === Quote card === **/
+.quote-card {
+    border-color: var(--color-on-surface-muted);
+    border-radius: var(--radius-lg);
+    @apply border p-4;
+
+    .vendor {
+        @apply font-medium;
+    }
+
+    .price {
+        color: var(--color-brand-700);
+        @apply font-semibold;
+    }
+
+    &.booked {
+        border-color: var(--color-brand-500);
+    }
+}
+```
+
+```handlebars
+<article class="quote-card{{#if booked}} booked{{/if}}">
+    <h3 class="vendor">{{vendorName}}</h3>
+    <span class="price">{{fmt_dollars total}}</span>
+</article>
+```
+
+- The block, `.quote-card`, is the only class that has to be unique across the stylesheets.
+- Each child takes a short name for what it is: `.price`, not `.quote-card-price`.
+- A variant or a state is a second class on the block or child element (`class="quote-card booked"`, `class="filter-tab active"`), styled with `&.booked` inside the block.
+- Group a page's styles under the page's class, and mark each major section with a comment such as `/** === Settings page === **/`.
+- Nest only as deep as the markup needs. Each level raises the selector's specificity, and a rule three levels down is hard to override.
+
+## No BEM
+
+Never write BEM's `__element` or `--modifier` separators, in a stylesheet or in a template.
+`.quote-card__price` and `.quote-card--booked` are not allowed, and neither are flat prefixed names such as `.quote-card-price`, which are one step from BEM.
+
+Nesting already ties a child to its block.
+Repeating the block's name in every child's class attribute adds nothing, and a flat list of `.quote-card__vendor`, `.quote-card__price` and `.quote-card--booked` hides the hierarchy that the stylesheet should show.
+
+## When a short name matches more than you meant
+
+A nested selector such as `.quote-card .price` matches every element with the class `price` anywhere inside the block.
+That includes an element inside another component nested in the block, such as a line-item list that has its own `.price`.
+A short name also picks up any rule that styles that name on its own, at the top level of any stylesheet.
+
+Before you add a short child name, check both:
+
+1. Search the stylesheets for a top-level rule of that name.
+2. Look at what components the block's template renders inside it.
+
+If either applies, use a child combinator (`> .price`) so the rule reaches only the block's own children, or pick a more specific name for what the element is (`.total` instead of `.price`).
+
+## When the stylesheet around you uses old names
+
+A stylesheet you are editing may still hold BEM or prefixed names.
+Write your new classes in the nested shape anyway, rather than copying the names around them.
+The convention to match is this skill's, not the file's.
+
+Do not rename the existing classes as part of an unrelated change, because their templates change with them.
+If the old names are worth replacing, file an issue for it.
+
+## Colors, sizes and spacing come from the theme
+
+Take every color, radius, font and spacing value from the theme's tokens, through `var()` (`var(--color-brand-600)`, `var(--radius-lg)`) or through `@apply` of a Tailwind utility the theme backs.
+Do not write a literal value such as `#10b981` or `13px` in a rule.
+A literal does not change when the project's theme does, so the page drifts from the rest of the site.
+
+If no token fits, add one to the project's `@theme` block and use it.
+The web capability's default tokens are in `@boopkit/cap-web/styles/theme.css`, and [`reference/boop-guide.ref.md`](../../reference/boop-guide.ref.md) describes how a project overrides them.
+
+## Reuse a class by job
+
+Reuse a class when an element does the same job as the elements the class already styles.
+Elements that do the same job should look the same everywhere, so one class serves them all, and a later change reaches every one.
+
+Matching declarations are not a reason to share a class.
+Two classes for different jobs stay separate even when their rules are identical today, because they will change for different reasons.
+
+Never create a class named for its layout or its look, such as `.stack-sm` or `.card-shadow`.
+It is a utility class under another name.
+
+Before adding a class:
+
+1. Look for an existing class that already does the job, starting with the shared classes the web capability ships (`.btn-primary`, `.btn-secondary` and the others in its `base.css`).
+2. If one fits, use it. Do not create a near-duplicate with a slightly different name.
+3. If one is close but not right, decide whether the job is really the same. If it is, change that class; if it is not, write a new simple class. Two simple classes are better than one class with variants for every case.
+
+## Related
+
+- [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — when the change is a new page, partial or component, for the markup patterns and the visual check before done.

package/skills/boop-web-design-handoff-bundle/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: boop-web-design-handoff-bundle
+description: "When the operator points at a design canvas (an artifact of artboards) and asks for it to be bundled, turned into a handoff, or made ready for the coding agent, turn it into a design handoff bundle under specs/design-handoffs/: a README, drop-in templates and CSS in the project's conventions, the decisions, and an eval checklist. The producing side of boop-web-design-handoff-workflow; the system wins over the prototype, and every departure is written down."
+metadata:
+  category: workflow
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Design canvas → design handoff bundle
+
+## Goal
+
+**A bundle is a translation of the design into the project's system, not a copy of the prototype.**
+
+A canvas is drawn with the designer's own sizes, colours and one-off markup.
+The bundle restates it in the project's tokens, shared classes and partials, and records every place it departs from the drawing, so the coding agent builds the design without re-deciding it.
+The output is a folder under `specs/design-handoffs/<name>/` that [`boop-web-design-handoff-workflow`](../boop-web-design-handoff-workflow/SKILL.md) consumes.
+This skill produces the bundle; that one verifies and builds it.
+
+Never commit; the operator commits the bundle.
+
+## 1. Find and read the canvas, all of it
+
+- Find the canvas with the Artifact tool.
+  A canvas shared from another organization does not appear in `list`, even under "shared", so ask for its link straight away.
+- **List the canvas's files (`scope: "files"`) every time before bundling.**
+  Boards get added while you work.
+  Read `project/canvas.json` for the board titles, then read every `project/*.dc.html`; do not trust a board count from an earlier read.
+- People edit the canvas live.
+  Re-read the boards right before writing the bundle, and diff them against your earlier copy to pick up the edits.
+
+## 2. Check the canvas's design system against the project
+
+The canvas's design system is under `project/ds/<namespace>/tokens.json`.
+Compare its `meta.source` and its values with the project's theme: the `@theme` block in `styles/styles.css`, `@boopkit/cap-web/styles/theme.css`, and Tailwind's own `theme.css`.
+If the tokens were generated from this project and the values match, say so in the decisions file: there is nothing to reconcile, and the build uses the tokens by name.
+If they differ, list every difference and ask the operator which wins before writing any CSS.
+
+## 3. Read the project's conventions before mapping anything
+
+- [`boop-web-css`](../boop-web-css/SKILL.md) for class names and nesting, and [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) for templates and partials. The bundle's CSS and templates follow them; do not restate them in the bundle.
+- The project's web-UI and brand reference pages, including any rules on copy and on claims about the product.
+- The shared stylesheets and `views/partials/`, for the classes and partials a section can be built from.
+- The routes, controllers and forms the pages touch.
+- `git log` on `views/` and `styles/`, and `specs/history/`: handoffs get built and archived quickly, so the code the bundle replaces may have changed today.
+
+## 4. Map every section
+
+For each section of each board, decide which existing class or partial it is, or which new class it needs.
+A pattern used on more than one page goes into a shared additions file; a pattern used on one page goes into that page's stylesheet.
+Markup used on more than one page becomes a partial with documented parameters.
+
+**The system wins over the prototype.** Record each departure in `00-decisions.md`:
+
+- Type sizes, radii and spacing are the theme's tokens, not the prototype's own values.
+- Each inline colour maps to a token; keep a table of prototype value, where it is used, and what the build uses. Never introduce a new colour.
+- A fixed width or height a designer set on a heading to stop a line wrapping is not shipped. Widen the heading's container instead, so it still wraps on a phone.
+- A picture of the product is a real screenshot, not drawn markup, because a mockup can look right and not match what the product does. Specify the capture instead of building it: seeded demo data in a throwaway database, never the shared development one, then `npm run ux:capture` against the bundle's dev server, with the `<img>` width and height left for the coding agent to fill.
+
+## 5. Copy
+
+- Copy is the board's, word for word, with the project's copy rules applied.
+- Remove canvas debris, such as placeholder text, absolutely positioned leftovers and forced line breaks. Fix obvious missing punctuation, and list every fix.
+- Flag, do not silently change, anything that breaks the copy rules, such as a claim beyond what the product does. The operator decides; once they have, record the result as kept on purpose in both `00-decisions.md` and the template's comment, so a later review does not "fix" it.
+
+## 6. Write the bundle
+
+At `specs/design-handoffs/<name>/`:
+
+| File | Contents |
+|---|---|
+| `README.md` | The authoritative spec the workflow reads first: what is being built and which views and rules it replaces, a read-in-this-order table, the **Data to surface** list (view-model fields the controller does not pass yet), what was dropped and why, follow-ons out of scope, and the canvas link. |
+| `00-decisions.md` | The design-system check, the departures table, the copy fixes, a dated list of what was settled with the operator, and open questions. The bundle is not finished while any question is open. |
+| `<slug>.hbs` + `<slug>.css` per page | A drop-in template, with every new field guarded so it renders against today's view-model, and its CSS, whose header comment names the rules it supersedes. A short `NN-page-<slug>.md` beside them gives each section's layout and how it reflows. |
+| `shared-additions.css`, `partials/` | Shared classes and new partials, with where each goes and which pages use it. For a change to an existing partial, show only what changes. |
+| `NN-eval.md` | A pass/fail checklist at desktop, tablet and phone widths, which the workflow's visual check runs against. |
+| `prototypes/` | Each board exported, with cross-board links renamed to the exported filenames. |
+
+Add a routes document only when pages, redirects or forms are new or retired; shape any form endpoint like the project's existing ones.
+Each template opens with a comment naming the bundle and board, what the page is for, what the controller passes, and where its CSS lives.
+Each section gets a short comment saying why it is built the way it is.
+
+## 7. Check before handing over
+
+Run a script over the bundle and fix everything it finds:
+
+- Every `var(--…)` in the new CSS exists in the project's stylesheets, including cap-web's and Tailwind's theme files.
+- Every class in the new templates is defined in the project's CSS or the bundle's.
+- Every visible string on each board appears in its template; expect only shared navigation, footers and the strings you fixed to differ.
+
+## 8. Working with the operator
+
+Ask decisions as short, separate questions.
+Record each answer with its date in `00-decisions.md`, and update every file it touches: templates, routes document and checklist.
+Finish with where the bundle is, that nothing is committed, and what the coding agent still has to produce, such as the screenshots.
+
+## Related
+
+- [`boop-web-design-handoff-workflow`](../boop-web-design-handoff-workflow/SKILL.md) — when the bundle is done and the operator hands it to a coding agent; its README claims are verified there before anything is built.

package/skills/boop-web-design-handoff-workflow/SKILL.md

@@ -15,12 +15,16 @@ A design handoff package is a high-leverage input: someone has already done the
 
 ## What a handoff package looks like
 
-Three files, typically grouped under a per-handoff directory in the project's design/eval reference area:
+A folder under `specs/design-handoffs/<name>/`, which [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) writes from a design canvas.
+Three kinds of file carry the build:
 
 - **`README.md`** — the authoritative spec. Names what is being built, which files it replaces, a "Data to surface" list (the view-model fields the redesign needs that the controller does not pass yet), what was deliberately dropped, and any follow-ons that are explicitly out of scope.
 - **A drop-in view template** — replaces an existing view. Every new field is guarded (rendered only when the field is present) with a live fallback, so the template renders *today* against the current view-model and "lights up" as each data field lands. Ship the template first, work the data list independently.
 - **A CSS file** — appended into an existing style block; its header comment names the rules it supersedes.
 
+Beside them, `00-decisions.md` records where the build departs from the prototype and what the operator has already settled, and an eval checklist gives the pass/fail checks for the visual check in step 6.
+A decision recorded there is settled; do not raise it again in step 4.
+
 ## The process
 
 ### 1. Read the README in full
@@ -47,7 +51,12 @@ Report: feasible or not, the scope, and the one question that is genuinely their
 
 ### 5. File a bd issue (goal/approach/context shape)
 
-Per `boop-project-mgmt-beads-planning`. Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise. Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up). Name the visual-check as the done-gate.
+Per `boop-project-mgmt-beads-planning`.
+Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise.
+Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up).
+Name the visual-check as the done-gate.
+Name the skills the sub-agent needs, such as `boop-light-dev-workflow` for the per-issue steps and the project's web design skill, in the skills list that `boop-project-mgmt-beads-planning` sets out under "Breadcrumb the skills that carry the discipline".
+The sub-agent reads the issue, not this workflow, so a skill the issue does not name is one it never opens.
 
 ### 6. Run it as a sub-agent
 
@@ -55,8 +64,19 @@ Per `boop-project-mgmt-beads-planning`. Breadcrumb the handoff README as the aut
 - **Apply template + CSS**, removing the rules the CSS header names as superseded.
 - **Make the view-model edits** per the (corrected) data list.
 - **Trim brittle tests rather than lovingly rework them.** A redesigned surface is in flux; the operator's visual UAT is the safety net. Keep the full suite green; do not invest in expanding coverage on a surface that is still moving.
-- **The visual-check is the gate.** Build the CSS bundle, capture the affected states at desktop (1280) and mobile (390), and *read* the captures — the render is the proof, not the diff. (Auth caveat: the default capture tool may log in as a demo account and not reach the populated data you need; use a capture path that authenticates as the fully-populated account so the render shows real content.)
-- **Never `pkill` or pattern-kill a process** — an over-broad `pkill -f "<server command>"` can kill the operator's main-checkout server. Stop only your own server, by precise PID via `lsof -i:<port>`.
+- **The visual-check is the gate.** Build the CSS bundle, capture each affected state, and *read* the captures — the render is the proof, not the diff.
+  Capture with `npm run ux:capture -- <path> <label>`, which writes `tmp/ux-eval/<label>.png` at a desktop width of 1280.
+  It has no narrow viewport, so check the mobile layout another way, such as a browser's responsive view at 390.
+
+  - **`BASE_URL`** — the capture defaults to `http://localhost:3000`, the operator's server, not your worktree's. Pass `BASE_URL=http://localhost:<port>` with every capture, or you will screenshot someone else's build and review it as your own.
+  - **Auth** — the capture logs in only with the session cookie in `UX_EVAL_AUTH_COOKIE_NAME` and `UX_EVAL_AUTH_COOKIE_VALUE`. Use one for an account that has the data the surface shows: an empty account renders an empty page, which reads as a broken redesign but is an artefact of who is logged in.
+- **Stop the dev server you started, all of it, not only the process on the port.**
+  A dev script that watches files runs a supervisor above the server, and only the server holds the port: boop's web-app profile runs `nodemon --exec tsx src/server.ts`, so killing the port holder leaves `nodemon` running while the port reads free, and `nodemon` starts the server again on the next file change.
+  Find the supervisor by the worktree's absolute path in its command line, `ps -eo pid=,args= | grep "<absolute-worktree-path>/node_modules/.bin/[n]odemon"`, with the dev script's own watcher in place of `nodemon` if it runs another, and kill that pid; the server under it stops too.
+  Then run that search again and `lsof -ti tcp:<port> -sTCP:LISTEN`, and confirm both print nothing, because a free port does not show that the supervisor is gone.
+  If the dev script runs no supervisor, the process on the port is the whole server, and `lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill` stops it.
+  Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like): a pattern reaches every other worktree's server and the operator's own.
+  Never stop a server you did not start, or one a running loop owns.
 - **Disposition:**
   - **Branch for UAT** when the change is a substantial visual redesign the operator will want to see — leave the branch, the worktree, and the captures; do not merge, do not close.
   - **Merge on a clean visual-check** when the change is quick, clear, and additive — merge to main only if the capture clearly confirms the result and tests are green; if verification is blocked or ambiguous, fall back to branch-for-UAT rather than merging blind.
@@ -68,13 +88,14 @@ Often itself a sub-agent. Per `boop-product-design-knowledge-backfill`:
 - **Merge** the branch to main; run the full suite green first.
 - **Integrate the knowledge** — update the relevant reference page (e.g. the web-UI reference for a redesigned surface) to describe the new shape, and fix any reference line the redesign made stale. Commit docs direct to main.
 - **Archive the handoff package** (unedited) to `specs/history/<name>-handoff/`.
-- **Clean up** — close the issue, remove the worktree, delete the branch, stop the server by precise PID. Do not push to origin unless asked.
+- **Clean up** — stop the server and its supervisor as step 6 describes, then close the issue, remove the worktree and delete the branch. Do not push to origin unless asked.
 
 ## When to use this vs the other workflows
 
 | Situation | Workflow |
 |---|---|
 | A design handoff package (README + drop-in template + CSS) for a surface | **this** |
+| A design canvas the operator wants made ready for the coding agent | `boop-web-design-handoff-bundle`, then **this** |
 | A goal-framed improvement to an existing surface, no package | `boop-light-dev-workflow` |
 | A backlog cleanup sweep of lingering P1/P2 items | `boop-project-mgmt-issue-sweep-workflow` |
 | A feature with backend work driven by a spec | `boop-feature-dev-workflow` |
@@ -91,7 +112,7 @@ Often itself a sub-agent. Per `boop-product-design-knowledge-backfill`:
 
 ## Related
 
+- [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) — when the operator points at a design canvas rather than a finished package; bundle it first.
 - `boop-product-design-knowledge-backfill` — the archive + reference-integration discipline for the closeout.
 - [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — the visual-check-before-done rule the run leans on.
-- `boop-light-dev-workflow` — the per-issue beats that run inside the sub-agent.
 - `boop-product-design-thought-partnership` — surfacing the buried decision at the operator's altitude.

package/skills/boop-web-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boop-web-testing
-description: "When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes."
+description: "When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes — or to confirm in a browser that a change to something a person looks at does what its issue said, since a green suite proves behaviour but not what renders."
 metadata:
   category: test
 ---
@@ -86,6 +86,92 @@ Boop scaffolds one — `npm run db:query` (database capability) — for reading
 
 These are exploratory aids. They are not part of the automated suite, and none of them substitutes for a Jest test that can go red on its own.
 
+## Verifying a change someone will look at
+
+When a change alters something a person looks at, such as a page, a form, a list, an empty state or a message, finish by driving it in a browser against seeded data.
+**A passing suite proves the behaviour. Only the rendered page proves that a person can reach it.**
+
+A change can be correct and still fail the person it was built for.
+A confirmation renders six screens below the fold; an error appears at the bottom of a form while the reader looks at the top; a button's label does not say what it does; a control lands on the wrong one of two pages.
+In each, the code does what it should and its test passes, because a test asserts that the confirmation renders and none asserts where on the page it lands.
+In one downstream project a change shipped with over eight thousand passing tests and a clean typecheck, and twenty minutes of driving it found a P1: the confirmation that was the only defence against a repeated submit rendered more than four thousand pixels down the page, so the reader saw a form redisplay unchanged and pressed submit again.
+
+So the question here is not whether it works, which the suite answered, but **whether the person this is for would get what the issue promised.**
+Get the suite green first, or you will spend the session diagnosing a failure a test would have named in seconds.
+This is no substitute for tests, and it does not re-prove logic a unit test already covers.
+
+### The rendered page is the authority for what a page shows
+
+Before you say a surface works or is broken, sign in as the person it is for and render it.
+A database query and a code trace each describe something next to the page, not the page.
+In the same project, a query found the value a fix had written and the fix was called done, while the view read a different, empty field and still showed the old text; a later fix was then called broken from a code trace, and the render showed it worked.
+
+- Verify the broad claim the change makes across the whole surface, not only the row you changed.
+- Before handing to the operator, ask what they would catch on it, and go and find that first.
+- A sub-agent's "verified on real data" is a lead to check, not a verdict.
+
+A surface you are making no claim about needs no render.
+
+### Stand up an environment with the states the surface will meet
+
+- **Never the shared development database or a deployed environment.**
+  Use a throwaway database and a server started from the worktree whose code you are verifying.
+  A server running another checkout's code produces a page that looks plausible and is wrong, so confirm the server process's working directory is your worktree.
+- **Rebuild the compiled stylesheet first.**
+  It is usually gitignored, so a fresh worktree lacks it or holds a build from before the branch's CSS, and nothing warns you: the page still renders, and you judge a layout you did not ship.
+- **Seed the variety of states.**
+  A fault that shows only in an empty, single, partial, finished or failed state is invisible while the database holds one well-formed example.
+  Reuse a seed the project already has that writes those states.
+  When a feature brings a new kind of list, roster, directory or inbox, scope a seed-data spec beside the feature spec, naming the permutations it must write; the two can run as parallel loops, neither gating the other, so the feature develops against the seed and exposes shapes the seed missed.
+- **Run the background workers the pages depend on.**
+  A web process alone leaves the jobs a page waits on sitting in their queue, and the page eventually reports a failure that nothing logs as an error.
+
+### Drive it
+
+Use the browser tools against the real pages: read the page, fill the real inputs, press the real buttons.
+A bare HTTP request to the route is not a check of the surface, because what renders is the thing under test.
+Walk the issue's Done-when one line at a time, and for each ask what a person would see, not whether the write happened.
+
+These traps each cost a downstream session time:
+
+- **Page-text extraction reports screen-reader-only text as if it were visible.**
+  Confirm anything you rely on with a screenshot or by measuring the element.
+- **Presence is not position.**
+  When something must catch the reader's attention, such as a confirmation, an error or a warning, measure where it lands rather than confirming it exists:
+  ```js
+  const r = el.getBoundingClientRect();
+  ({ top: Math.round(r.top), aboveFold: r.top < window.innerHeight })
+  ```
+- **A Chromium capture can miss a mobile overflow caused by a native form control.**
+  Chromium shrinks a `<select>` with long options; Safari sizes it to its longest option, so a picker that fitted 390px and 320px captures overflowed on an iPhone.
+  Where `<select>`, date or file inputs sit in a narrow layout, reason about the layout's structure, prefer fixes that hold in any browser (`min-width: 0` on flex children, a column layout, `max-width: 100%`), and have the change confirmed on a real device.
+- **`:focus` did not match under a headless Playwright probe**, measured once: a focused input read back its unfocused border colour, including one whose focus rule had worked for months.
+  Read focus and hover rules from the compiled stylesheet instead, and compare any probe with a sibling known to work, so that a false result shows itself.
+- **The seed may not hold the case you need.**
+  Rather than hunting for a record that happens to match, change one you control so that it does; that tests your change and the path beneath it in one move.
+
+### Judge what you see
+
+Once a flow works, whether it reads well is a separate judgement.
+When the project has the ux capability, run `boop-ux-purpose-judgement` for whether each thing on the page belongs there, then `boop-ux-visual-judgement` for how it looks and scans.
+
+- **Read each page, message or notification as its recipient would:** addressed to its reader, warm and professional, free of internal identifiers and jargon, and carrying nothing that reader should not see, such as the operator's budget.
+  Wording that confuses you will confuse the person it is for.
+- **When a count or a set appears on more than one surface**, such as a badge in the navigation, a summary on a hub and the rows of a list, put the surfaces side by side.
+  A difference between them is the defect, and comparing them finds what a test of one surface cannot.
+- **When the page and the data could disagree, look at the data** with the project's query tool (`npm run db:query` above).
+  A row that repeats one value five times is either a rendering fault or a storage fault, and the two have different owners, so establish which before you file it.
+
+### Record and tear down
+
+**Findings are observations, not commits.**
+Capture what you saw and file it; do not start fixing mid-run, because editing the code restarts the server and destroys the state you are standing in.
+
+File each finding as its own issue, saying what the person sees, why it matters, and what good looks like.
+Put a finding caused by the work under test beneath that work's epic, and file a pre-existing one standalone, saying in its body how you established it was not this branch: a seed fault blamed on the branch sends the next person to the wrong code.
+
+Then stop the server you started and drop the throwaway database, and confirm that the port is free and the database is gone rather than assuming the teardown worked.
+
 ## References
 
 - `boop-testing-testing` — testing philosophy and the generic approach

package/skills/boop-web-web-ui-design/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 # Web UI Design Principles
 
-For controller design (the code that handles requests and renders views), apply the core principles in `design.controllers.skill.md` from the `services` capability: thin dispatch, no business logic in controllers, services handle the work. This skill adds web-specific guidance on top: view rendering, template structure, CSS patterns.
+For controller design (the code that handles requests and renders views), apply the core principles in `design.controllers.skill.md` from the `services` capability: thin dispatch, no business logic in controllers, services handle the work. This skill adds web-specific guidance on top: view rendering, template structure and markup patterns.
 
 ## Core Philosophy
 When building UI components, align with the **Spartan Code Philosophy** (see `boop-coding-development`):
@@ -20,44 +20,15 @@ When building UI components, align with the **Spartan Code Philosophy** (see `bo
 - Resist adding extra styling, animations, or features beyond what's requested
 - If additional UI enhancements seem beneficial, discuss with the team first
 
-## Semantic CSS Approach
-We use **semantic CSS classes** that describe the purpose of elements rather than their appearance:
+## CSS
+Before you add or change a class, a selector or a stylesheet rule, read [`boop-web-css`](../boop-web-css/SKILL.md).
+It states how classes are named and nested, rules out BEM, and says when to reuse a class.
+The class names in the markup patterns below follow it.
 
-**Good (semantic):**
-```html
-<h1 class="page-title">Dashboard</h1>
-<p class="page-subtitle">Welcome back</p>
-<button class="btn-primary">Save Changes</button>
-<div class="policy-item">...</div>
-```
-
-**Avoid (presentational):**
-```html
-<h1 class="text-2xl font-bold text-gray-900">Dashboard</h1>
-<p class="text-sm text-gray-600 mt-2">Welcome back</p>
-<button class="bg-blue-500 text-white px-4 py-2 rounded">Save Changes</button>
-```
-
-### Implementation
-- Define semantic class names in `styles.css` using nested structure
-- Apply Tailwind utility classes with `@apply` directive inside semantic classes
-- Use semantic classes in HTML/Handlebars templates
-- Group related styles together with CSS nesting
-
-**Example:**
-```css
-.settings-page {
-    @apply px-6 py-4;
-
-    .settings-block {
-        @apply mb-8 bg-white border border-gray-200 rounded-lg p-6;
-    }
-
-    .block-heading {
-        @apply text-lg font-semibold text-gray-900 mb-4;
-    }
-}
-```
+## State labels and action verbs
+Before you name a state, choose its tone or signal, or write the label of a button or link, read the "Status communication" and "Affordance signaling" sections of `boop-ux-visual-judgement`, if the project has the `ux` capability.
+They say to take each state's label, tone and signal from one shared table, and to use one verb for an action on every surface.
+Whether or not it does, keep the project's state table and chosen verbs in its reference pages, and check them before adding a new state word or action label.
 
 ## Modular Templates and Partials
 Structure templates for reusability while maintaining simplicity:
@@ -83,28 +54,8 @@ When considering whether to reuse existing components:
 - **DON'T make** components overly configurable to handle every edge case
 - **DO create** a second simpler component if the existing one requires too many parameters or conditions
 
-### Handlebars Helpers
-`@boopkit/cap-web` includes the [`handlebars-helpers`](https://github.com/helpers/handlebars-helpers) library (~130 helpers) plus custom formatting helpers.
-
-**Standard helpers (from handlebars-helpers) — most useful:**
-- Comparison: `gt`, `lt`, `gte`, `lte`, `eq`, `is`, `not`, `compare`
-- Logical: `and`, `or`, `not`
-- String: `capitalize`, `trim`, `replace`, `startsWith`, `contains`
-- Array: `first`, `last`, `sort`, `forEach`, `join`
-- Math: `add`, `subtract`, `multiply`, `divide`, `ceil`, `floor`, `round`
-
-**Custom helpers (from @boopkit/cap-web):**
-- `fmt_dollars` — format number as currency: `{{fmt_dollars 1234}}` → `$1,234` (optional `sigfigs` for data viz: `{{fmt_dollars 12345 sigfigs=4}}` → `$12,350`)
-- `fmt_percent` — format as percentage: `{{fmt_percent 45}}` → `45%`
-- `fmt_date` — human-readable date: `{{fmt_date createdAt}}` → `March 28, 2026`
-- `markdown` — render markdown to HTML: `{{markdown text}}` or `{{#markdown}}...{{/markdown}}`
-- `icon` — inline SVG icon from heroicons: `{{icon "user" "24/outline"}}` or with CSS class: `{{icon "check" "24/solid" class="w-5 h-5 text-green-600"}}`. Styles: `24/outline`, `24/solid`, `20/solid`, `16/solid`. Icons are read from `node_modules/heroicons/` and cached.
-- `json` — JSON stringify: `{{json obj}}`
-- `truncate` — truncate string: `{{truncate text 100}}`
-- `urlencode` — percent-encode a value for a query parameter: `<a href="/signup?next={{urlencode next}}">`. Handlebars escapes an interpolated value for HTML, not for a URL, so `?next={{next}}` renders a return path of `/a&b=c` as `next=/a&amp;b&#x3D;c` and the browser reads `next=/a`. Use this helper for **every** value that lands in a query string; it encodes rather than validates, so whatever gates the value keeps doing that job.
-- `upper` / `lower` — case conversion
-- `eq` — strict equality check (also available from handlebars-helpers)
-
+### Template logic
+The Handlebars helpers the web capability registers are listed in [`reference/web-ui.ref.md`](../../reference/web-ui.ref.md#helpers).
 Keep template logic minimal—complex logic belongs in the controller/service layer.
 
 ## UI Structure Patterns
@@ -113,10 +64,10 @@ Keep template logic minimal—complex logic belongs in the controller/service la
 Follow consistent page patterns:
 ```html
 <div class="[page-type]-page">
-  <div class="page-header mb-6">
-    <h1 class="page-title">Page Title</h1>
-    <p class="page-subtitle">Brief description of the page</p>
-  </div>
+  <header class="header">
+    <h1 class="title">Page Title</h1>
+    <p class="subtitle">Brief description of the page</p>
+  </header>
 
   <section class="[content-section-class]">
     <!-- Page content -->
@@ -128,60 +79,37 @@ Follow consistent page patterns:
 Use consistent form patterns:
 ```html
 <form method="POST" action="/path" class="form">
-  <div class="form-group horizontal">
-    <label for="field-id" class="form-label">Field Name</label>
-    <input id="field-id" name="fieldName" type="text" class="form-input">
+  <div class="field horizontal">
+    <label for="field-id">Field Name</label>
+    <input id="field-id" name="fieldName" type="text">
   </div>
-  
-  <div class="form-actions">
+
+  <div class="actions">
     <button type="submit" class="btn-primary">Save</button>
-    <button type="button" class="btn-cancel">Cancel</button>
+    <button type="button" class="btn-secondary">Cancel</button>
   </div>
 </form>
 ```
 
 ### Component Structure
-Group related elements with semantic containers:
+Group related elements with semantic containers, a block class on the outside and short child names inside it:
 ```html
 <div class="policy-list">
-  <div class="policy-item">
-    <div class="policy-header">
-      <h2 class="policy-name">Policy Name</h2>
+  <div class="policy{{#if archived}} archived{{/if}}">
+    <div class="header">
+      <h2 class="name">Policy Name</h2>
       <!-- controls -->
     </div>
-    <p class="policy-description">Description text</p>
+    <p class="description">Description text</p>
   </div>
 </div>
 ```
 
-## Best Practices
-
-### Naming Conventions
-- Use lowercase with hyphens: `page-title`, `btn-primary`, `policy-item`
-- Be descriptive of purpose, not appearance: `block-heading` not `large-bold-text`
-- Group related classes with common prefixes: `policy-item`, `policy-header`, `policy-name`
-
-### CSS Organization
-- Group page-specific styles under page class selector
-- Use nesting to show hierarchy and relationships
-- Add comments to mark major sections: `/** === Settings Page === **/`
-- Keep specificity low—avoid deep nesting unless necessary
-
-### Reuse Strategy
-1. **First**, check if an existing semantic class fits your needs
-2. **If close**, use the existing class—don't create near-duplicates
-3. **If not quite right**, evaluate:
-   - Is it worth making the existing class more flexible?
-   - Or is a new simple class clearer?
-4. **Remember**: Two simple classes are better than one complex parameterized system
-
 ## Anti-Patterns to Avoid
-- ❌ Using Tailwind utility classes directly in templates (except for one-off spacing tweaks)
 - ❌ Creating overly abstract/configurable components for simple use cases
 - ❌ Deep partial nesting that makes template flow hard to follow
 - ❌ Adding UI elements or styles "just in case" they're needed later
 - ❌ Creating partials for markup that only appears once
-- ❌ Duplicating semantic classes with slightly different names
 
 ## "Paper-Style" Reports (Analytics & Insights)
 When designing report/analytics UIs, prefer a **paper-like** presentation:
@@ -198,7 +126,6 @@ When designing report/analytics UIs, prefer a **paper-like** presentation:
 See also:
 - `boop-coding-development` for Spartan Code Philosophy
 - [`reference/web-ui.ref.md`](../../reference/web-ui.ref.md) for the current implementation: the view engine, the CSS pipeline and the page pattern
-- [`reference/boop-guide.ref.md`](../../reference/boop-guide.ref.md) for the CSS extension model (`@theme` tokens, package styles, cascade overrides)
 
 ## Visually verify before declaring done
 

package/skills/boop-web-website-dev-workflow/SKILL.md

@@ -74,18 +74,22 @@ If a content situation cannot be resolved by 1–5 (the refs don't cover it; the
 This protects the ref docs as durable guardrails and keeps the next page's implementer from re-deriving the same decision.
 
 ## Workflow
-Prime directive: **Use beads issues for everything**. Beads has hierarchical issues (epics, features, tasks, sub-tasks, bugs). All steps of this website development workflow should be an issue, with appropriate dependencies and reference material (breadcrumbs, etc). We will use feature → task → sub-task for most work. If you find yourself doing work that is not in an issue, stop and create an issue for it.
+Prime directive: **Use beads issues for everything**. Beads has hierarchical issues (epics, features, tasks, sub-tasks, bugs). All steps of this website development workflow should be an issue, with appropriate dependencies and reference material (breadcrumbs, etc). We will use an epic root with `task` children for most work, and a `feature` container for the implementation tasks. If you find yourself doing work that is not in an issue, stop and create an issue for it.
 
 **Flow overview.** The website work ships as a chain of issues, each one a separate task whose output is written somewhere the next task can find it:
 
-> feature (parent) → understand → plan → decompose → implement → review → punch-list → closeout
+> epic (root) → understand → plan → decompose → implement → review → punch-list → closeout
 
-The first issue is the feature parent; working it produces the next issue(s), and so on. `bd-loop` picks up each newly-ready issue and runs it until the chain is complete.
+The first issue is the epic root; working it produces the next issue(s), and so on. `bd-loop` picks up each newly-ready issue and runs it until the chain is complete.
 
 **The loop ends with the feature branch pushed for human review.** Merging, main-branch coordination, and branch deletion are out of scope for the loop. See step 6 (Closeout).
 
 ### First step:
-1. **Create the feature issue**: Create a new feature issue in beads for the requested website work. This is the parent issue for all work tasks. Write a clear title and description that names the page(s) or IA change and links the driving spec (these are the 'breadcrumbs'). Ref-doc and marketing-skill identification happens in the Understand task (step 1 below); the feature issue does not need to enumerate them up front.
+1. **Create the root issue as an `epic`**: `bd create "<page or IA change>" -t epic`. This is the parent issue for all work tasks, and the rest of this workflow calls it the feature issue. Write a clear title and description that names the page(s) or IA change and links the driving spec (these are the 'breadcrumbs'). Ref-doc and marketing-skill identification happens in the Understand task (step 1 below); the feature issue does not need to enumerate them up front.
+
+   **Only `task` issues are claimed as work.**
+   `epic` and `feature` organise the tree and anchor dependencies, and a loop never picks either up, as "Hierarchy with `--parent`" in `boop-project-mgmt-beads-planning` explains.
+   The one consequence to plan for is the closing order in step 6: bd refuses to close an epic that still has an open child.
 
 ### Task construction:
 Create tasks as child issues of the feature issue. The descriptions below are the content of the created issue — so don't *do* the work described in the issue description, this is just the content of the issue.
@@ -133,32 +137,56 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
    When you decompose the plan into implementation sub-tasks (step 3), **include the guardrail registry as breadcrumbs in each sub-task**: the brand ref doc(s), the realization / tone-mode doc, the audience-type marketing skill, the web design skill, and the per-page tone / persona selections from the plan. Review the plan to ensure it fully covers the spec; create follow-up tasks for any gaps it can't resolve.
 
-3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the website implementation plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" task issue plus smaller sub-tasks following the `boop-project-mgmt-beads-planning` skill.
+3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the website implementation plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" container, a `feature`-typed organiser rather than a task, holding one `task` child per unit of work, following the `boop-project-mgmt-beads-planning` skill.
 
    Sub-task granularity for website work is typically **page-level or surface-level**: one sub-task per new page, one per page rewrite, one per retired-route deletion, one for global-nav structure, etc. Shared concerns like semantic CSS extensions or new partials get their own sub-tasks and become blockers for the pages that depend on them.
 
    **Propagate the guardrail registry into every sub-task as breadcrumbs** — brand ref doc(s), realization / tone-mode doc, audience-type marketing skill, web design skill — so the implementation agent does not have to re-discover them.
+   Write the skills among them, and any other skill the sub-task's work needs, as the skills list that `boop-project-mgmt-beads-planning` sets out in its section "Breadcrumb the skills that carry the discipline": a `## Skills` heading, the line "Before making changes, read each of these in full.", and a path to each skill's `SKILL.md`.
+   The session that claims a sub-task reads its issue, not this workflow, so a skill the issue only names in passing is one it rarely opens.
+
+   **Put the test run scope on every implementation sub-task.**
+   Each sub-task runs the focused tests for what it touches, plus the project's whole-program static check; the full suite runs once per branch, on the Review task in step 4.
+   Left unstated, a sub-task that has just changed a shared partial or a widely used helper runs the whole suite on its own reasoning.
+   The rule and the wording to put on each are in the section "Test run scope: what each task runs, and what runs once" in `boop-project-mgmt-beads-planning`.
+
+   **Audit the sub-task bodies before this task closes, then revise them.**
+   Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time.
+   Once every sub-task exists, re-read them all side by side as the agent who will claim each one cold, following the section "Write, audit and revise in three separate turns" in `boop-project-mgmt-beads-planning`, then rewrite whatever the audit finds.
+   Some faults show only side by side: a sub-task that says "a sibling issue handles this" without naming it, or a term the container defines and a sub-task then uses bare.
 
    Create the feature branch `work/<feature-issue-id>` (e.g. `work/boop-arc.14`) — branch names MUST use the `work/` prefix + issue ID, never feature names like `home-page-refresh`. All sub-tasks work within this branch.
 
-   **Re-wire the Review dependency (critical):** Decompose only plans the work, it does not perform it. So Review (step 4) must depend on the "do the work" task, not on this Decompose task. If Review already exists with a Review→Decompose dep, fix it:
+   **Wire Review to each sub-task (critical):** Decompose only plans the work, so Review (step 4) must not depend on this task.
+   It must not depend on the container either: bd never closes a container on its own, so an edge on it holds Review until someone closes the container by hand, which is not the same event as the work being done.
+   Give Review one plain `blocks` edge on each sub-task instead, so it becomes ready only when every sub-task has closed:
    ```
-   bd dep remove <review-task-id> <this-decompose-task-id>
-   bd dep add    <review-task-id> <do-the-work-task-id>
+   bd dep remove <review-task-id> <this-decompose-task-id>   # only if Review was wired to Decompose
+   bd dep add    <review-task-id> <sub-task-id>              # once per sub-task
    ```
-   If Review doesn't exist yet, create it now with the correct dep on the do-the-work task.
+   If Review doesn't exist yet, create it now with those edges.
+   Every edge in this tree is plain `blocks`.
+   Step 3 of `boop-feature-dev-workflow` gives the whole tree recipe, why each piece is shaped as it is, and how to verify the wiring.
 
-4. **Review the work done**: Next task (don't *do* this work, this is the content of the task issue). Depends on the "do the work" task from step 3 (step 3 is responsible for rewiring this if pre-created with the wrong dep). Review all changes **in the feature branch** `work/<feature-issue-id>` (confirm with `git branch` or breadcrumbs). Run `bd children <feature-issue-id>` to see what sub-tasks were created and closed for context. Pull the **guardrail registry** from the findings file (`specs/{feature-name}-plan-findings.md`) before reviewing — every review below is anchored against those project-specific guardrails. This task will:
-   - Perform a **code review and content review** of all changes in the feature branch. The content review checks that each affected page (1) implements the driving spec's stated intent for every page-level goal, (2) where the spec specifies exact copy, uses that copy verbatim, and (3) where the spec leaves a content slot to implementation judgment, the copy aligns with the project's brand-voice ref and the audience-type marketing skill (no audience-register drift, no forbidden patterns, no superlatives without evidence, no invented positioning that contradicts settled ref-doc content).
+4. **Review the work done**: Next task (don't *do* this work, this is the content of the task issue). Blocked by each sub-task of the "do the work" container from step 3, so it runs only once all of them have closed (step 3 wires this, and rewires it if Review was created with an edge on Decompose). Review all changes **in the feature branch** `work/<feature-issue-id>` (confirm with `git branch` or breadcrumbs). Run `bd children <feature-issue-id>` to see what sub-tasks were created and closed for context. Pull the **guardrail registry** from the findings file (`specs/{feature-name}-plan-findings.md`) before reviewing — every review below is anchored against those project-specific guardrails. This task will:
+   - Perform a **code review and content review** of all changes in the feature branch. The content review checks that each affected page (1) implements the driving spec's stated intent for every page-level goal, (2) where the spec specifies exact copy, uses that copy verbatim, and (3) where the spec leaves a content slot to implementation judgment, the copy aligns with the project's brand-voice ref and the audience-type marketing skill (no copy pitched at a different audience, no forbidden patterns, no superlatives without evidence, no invented positioning that contradicts settled ref-doc content).
    - Perform a **brand-voice review** against the project's brand ref doc — its voice / language constraints / do-don't / exclusions sections. Flag any drift from the project-specific rules.
-   - Perform a **marketing-copy review** against the audience-type marketing skill (if the project ships one) — its universal forbidden patterns (hype cadence, vague universals, unearned superlatives, wrong-audience register) and its quick self-check.
+   - Perform a **marketing-copy review** against the audience-type marketing skill (if the project ships one) — its universal forbidden patterns (hype cadence, vague universals, unearned superlatives, copy pitched at the wrong audience) and its quick self-check.
    - Perform a **tone-mode review** — each page uses the tone mode named in the plan (per the project's realization doc's tone-mode assignments).
    - Perform a **machine-readability / semantic-HTML review** — headings describe sections; meaningful prose is in the HTML rather than JS-injected; code samples are `<pre><code>`, not background images; copy-paste-safe snippets; plain URLs for the things that matter; OG / meta descriptions truthful (and ideally lifted from the hero lede).
-   - Perform a **browser validation** — start the dev server on a port confirmed free (`lsof -ti tcp:<port>` prints nothing when free), load each affected page, and confirm the golden path (page renders, primary CTA is wired correctly, internal links work, no console errors, no broken images, the project's theme is intact, no contrast regressions). Test the page narrow (mobile-ish) as well as wide. **If browser validation isn't possible in this environment, say so explicitly — do not claim success.** (Per project `CLAUDE.md` / `AGENTS.md` conventions where present — *for UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete.*)
-   - **Stop the dev server this task started** before it closes (`lsof -ti tcp:<port> | xargs kill`), by port only. Never pattern-kill (`pkill -f <runner>` reaches every other worktree's server and the operator's own — this project runs several worktrees and loops at once). Never stop a server you did not start: if the port you wanted is already held, identify the holder's cwd via `lsof -a -d cwd -p <pid> -Fn` and reuse it only when the directory is this feature's worktree, else take the next free port.
+   - Perform a **browser validation** — start the dev server on a port confirmed free (`lsof -ti tcp:<port> -sTCP:LISTEN` prints nothing when free), load each affected page, and confirm the golden path (page renders, primary CTA is wired correctly, internal links work, no console errors, no broken images, the project's theme is intact, no contrast regressions). Test the page narrow (mobile-ish) as well as wide. Drive it as the section "Verifying a change someone will look at" in `boop-web-testing` describes, which names the traps a browser pass falls into. **If browser validation isn't possible in this environment, say so explicitly — do not claim success.** (Per project `CLAUDE.md` / `AGENTS.md` conventions where present — *for UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete.*)
+   - **Stop the dev server this task started** before it closes.
+     Stop all of it, not only the process on the port.
+     A dev script that watches files runs a supervisor above the server, and only the server holds the port: boop's web-app profile runs `nodemon --exec tsx src/server.ts`, so killing the port holder leaves `nodemon` running while the port reads free, and `nodemon` starts the server again on the next file change.
+     Find the supervisor by the worktree's absolute path in its command line, `ps -eo pid=,args= | grep "<absolute-worktree-path>/node_modules/.bin/[n]odemon"`, with the dev script's own watcher in place of `nodemon` if it runs another, and kill that pid; the server under it stops too.
+     Then run that search again and `lsof -ti tcp:<port> -sTCP:LISTEN`, and confirm both print nothing, because a free port does not show that the supervisor is gone.
+     If the dev script runs no supervisor, the process on the port is the whole server, and `lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill` stops it.
+     Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like): a pattern reaches every other worktree's server and the operator's own.
+     Never stop a server you did not start, or one a running loop owns: if the port you wanted is already held, identify the holder's cwd via `lsof -a -d cwd -p <pid> -Fn` and reuse it only when the directory is this feature's worktree, else take the next free port.
+   - Run the **full test suite** once, plus the project's whole-program static check. This is the branch's only full-suite run; every implementation sub-task ran focused tests.
    - Perform an **IA review** — the top-nav structure matches the driving spec; retired routes return the spec's prescribed behavior (404, redirect, or other); any home-page cross-links the spec prescribes are present; the primary CTA destination exists and is reachable from every surface that the spec routes traffic from.
    - Write the review to `labs/claude-runs/{feature-issue-id}-review-summary.md`, structured as: code findings, content findings, brand-voice findings, marketing-copy findings, tone-mode findings, semantic-HTML findings, browser findings, IA findings, and an overall punch-list.
-   - Append a **punch-list** of issues that must be addressed before merge. Punch-list items typically span categories: code (refactor, naming, controller cleanliness), content (drift from spec intent or from brand-grounded copy judgment), brand-voice (project-specific forbidden phrasing, wrong register), marketing-copy (universal forbidden patterns — hype cadence, vague universals, unearned proof), tone (wrong mode applied), semantic HTML (heading order, missing alt text, JS-injected content), browser (visual bugs, broken links, console errors, mobile breaks, contrast issues), and IA (wrong nav, missing cross-links, retired routes still live).
+   - Append a **punch-list** of issues that must be addressed before merge. Punch-list items typically span categories: code (refactor, naming, controller cleanliness), content (drift from spec intent or from brand-grounded copy judgment), brand-voice (project-specific forbidden phrasing, wording more formal, casual or salesy than the brand ref allows), marketing-copy (universal forbidden patterns — hype cadence, vague universals, unearned proof), tone (wrong mode applied), semantic HTML (heading order, missing alt text, JS-injected content), browser (visual bugs, broken links, console errors, mobile breaks, contrast issues), and IA (wrong nav, missing cross-links, retired routes still live).
 
 5. **Add a punch-list work task**: Create a 'punch list' task issue as a child of the feature issue. Its goal: turn each item in the punch-list from the review document into a sub-task issue under this punch-list task. **Propagate the guardrail registry into the punch-list task and its children** so the fixers operate against the same brand ref / marketing skill the implementation did.
 
@@ -166,9 +194,15 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
   **Verify before closing the punch-list task:** Run `bd children <punch-list-task-id>` and confirm every item appears in the tree. Fix any missing item with `bd update <id> --parent <punch-list-task-id>` (remove conflicting deps first if needed). Only close once the tree is correct.
 
+  **Hold Closeout until every fix is done (critical):** a `blocks` edge on the punch-list task alone releases Closeout when that task closes, which can happen while its fix sub-tasks are still open, and Closeout would then archive the spec and update reference against the pre-fix site.
+  Once `bd children` lists every fix sub-task, create Closeout (step 6) if it does not exist yet, with a `blocks` edge on the punch-list task, and add a `blocks` edge from Closeout onto each fix sub-task: `bd dep add <closeout-task-id> <fix-sub-task-id>`.
+  Confirm with `bd dep list <closeout-task-id>` that the punch-list task and every fix sub-task are there, and only then close the punch-list task.
+  If Review found nothing to fix, the edge on the punch-list task is enough.
+  Step 5 of `boop-feature-dev-workflow` gives the full order.
+
   Punch-list sub-tasks of category "browser" or "content" should re-validate in the dev server after the fix, and each such sub-task stops the server it started before it closes, on the same terms as the browser validation in step 4. There is one sub-task per punch-list item, so deferring the stop to closeout leaves one stray watcher process per item. Sub-tasks of category "brand-voice" or "tone" should re-check against the project's brand ref doc. Sub-tasks of category "marketing-copy" should re-check against the audience-type marketing skill.
 
-6. **Close out the website work**: After the punch-list is resolved and the website work is complete, create a closeout task as a child of the feature issue. The closeout task performs two activities:
+6. **Close out the website work**: After the punch-list is resolved and the website work is complete, create a closeout task as a child of the feature issue, if step 5 has not already created it, blocked by the punch-list task and by each of its fix sub-tasks. The closeout task performs two activities:
 
    **a. Archive the spec:**
    - Move the completed driving spec from `specs/` to `specs/history/` (create the directory if it doesn't exist).
@@ -178,7 +212,9 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
    **b. Integrate into reference:**
    - Follow the `boop-product-design-reference-integration` skill to blend the new website knowledge into existing `reference/` pages.
-   - This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages. The integration targets are the **guardrail registry** captured in the findings file:
+   - This is NOT "create a new page for the feature". Name the subjects the work created or changed, the way a reader would look them up; merge each into the page whose title names it, and give a subject its own page when it has none or has outgrown the page it sits in.
+   - **Write this task's description as what was learned, not as pages to edit.** When you create the closeout task, list the knowledge the work produced: what the site now says and where, what was retired, and what voice or audience rules the work surfaced. A page list written before the work can only name pages that already existed, and the session that runs closeout tends to treat it as the whole job.
+   - The **guardrail registry** captured in the findings file names the pages most likely to change. Check each of them, as a starting point rather than the scope:
      - The project's brand realization / site doc — IA, page roster, retired-surfaces list, tone-mode assignments, any messaging tables (if rows changed).
      - The project's brand ref doc — any voice / language drift discovered during implementation that warrants a new *Do/Don't* row, a new entry in *Language we avoid*, a new persona, etc.
      - Any other project ref docs that surfaced gaps during the work.
@@ -195,12 +231,18 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    1. Commit the closeout edits (spec archive + reference updates) on the feature branch.
    2. `git push` the feature branch to its own remote ref.
    3. `bd dolt push` so beads state is synced.
-   4. `bd close <closeout-task-id>`.
-   5. `bd close <feature-issue-id>` (all child work is now done).
-   6. Stop. The loop will go idle on "No ready issues for prefix"; the next action belongs to the human reviewer.
+   4. Close the tree from the bottom up, because bd refuses to close an epic that still has an open child:
+      ```
+      bd close <do-the-work-container-id>   # a feature; its sub-tasks closed before Review ran
+      bd close <closeout-task-id>           # this task, the last open child of the root
+      bd close <feature-issue-id>           # the epic root, now that every child is closed
+      ```
+      If the last close fails, bd reports how many children are still open: find them with `bd children <feature-issue-id>` and find out why each is open before trying again, rather than forcing the close.
+   5. Stop. The loop will go idle on "No ready issues for prefix"; the next action belongs to the human reviewer.
 
 ## Related
 
 - [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — the primary design skill for this workflow; read it at the design step, before deciding what a page is made of.
 - `boop-ux-purpose-judgement` — when reviewing the rendered page, to ask whether each thing on it belongs there at all, which the visual pass does not ask.
+- [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) — when the pages' design arrives as a design canvas rather than a spec; bundle it before building.
 - `boop-writing-technical-prose` — when writing the driving spec and the child issues; each is picked up cold by an agent who was not in this session.