@boopkit/cap-workflows 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-workflows",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Reusable end-to-end code development and audit workflows for AI agents",
   "files": [
     "skills/",

package/skills/boop-architecture-audit-workflow/SKILL.md

@@ -137,16 +137,16 @@ For the work that is genuinely new:
 - **One child per structural change, not one per call site.** Enumerate-and-patch is the failure that [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) exists to prevent, and it starts at decomposition time.
 - **Carry the method on every child.** Each child must state the go-red discipline explicitly: delete the old shape first, commit the red build, follow the compiler. An agent picking up "split this interface" without that instruction will keep the build green by leaving a fallback, which is the exact failure this is meant to prevent.
 - **Carry the named change too**, so the executor can tell a finished refactor from a rearranged one.
-- **Name the skills on every child, and name only their names.** Step 8 says each child runs under [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) — but the executing session never reads this workflow, only the issue body, so that pointer reaches it exactly when the child says so and never otherwise. Put `boop-refactor-dev-workflow` on every child, plus the skill for the layer the structural change touches (services, controllers, data model, view) and `boop-testing-testing` for the real-path proof. Names, not extracts: the go-red method in the bullet above is copied deliberately, because a fallback that survives into the branch cannot be corrected afterwards, and that is the one exception. Everything else stays in its skill so there is a single copy to keep current.
+- **Name the skills on every child, and name only their names.** Step 8 says each child runs under [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) — but the executing session never reads this workflow, only the issue body, so that pointer reaches it exactly when the child says so and never otherwise. Put `boop-refactor-dev-workflow` on every child, plus the skill for the layer the structural change touches (services, controllers, data model, view) and `boop-testing-testing` for the real-path proof. Write them 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`, because a session opens a skill named only in a bare list of names about one time in seven. Names, not extracts: the go-red method in the bullet above is copied deliberately, because a fallback that survives into the branch cannot be corrected afterwards, and that is the one exception. Everything else stays in its skill so there is a single copy to keep current.
 - **Settle open decisions before the work starts, not during.** A choice like which validation library, or where a declaration lives, belongs in the issue body marked as decided, with the reasoning. An executor who has to pick one mid-implementation will pick silently.
 - **Include a review child** that checks each change against its named change, not merely that the issue closed.
 - **Put the test run scope on every child.**
-  The review child above is the one that runs the full suite; every other child runs focused tests plus the project's whole-program static check.
-  Left unstated, a child that has just changed a widely called function runs the whole suite on its own reasoning, and every sibling pays it again.
-  The rule and the wording to use are in `boop-project-mgmt-beads-planning`.
+  Each child 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 child above.
+  Left unstated, a child that has just changed a widely called function 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`.
 - **Do not create the feature branch.** The loop creates the worktree and its `work/<epic-id>` branch when it takes the first child.
 
-- **Audit the issue bodies before the session ends, 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 child issue exists, re-read them all as the agent who will claim them cold, using the audit pass in `boop-project-mgmt-beads-planning` and the anti-patterns in `boop-writing-technical-prose`, then rewrite whatever the audit finds. Read the tree side by side rather than one issue at a time: a child that says "a sibling issue handles this" without naming it, or a term the container defines and a child then uses bare, is only visible that way.
+- **Audit the issue bodies before the session ends, 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 child 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 child that says "a sibling issue handles this" without naming it, or a term the container defines and a child then uses bare.
 
 ### 8. Execute, verify, close out
 

package/skills/boop-feature-dev-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boop-feature-dev-workflow
-description: "When you are tasked with building a feature end-to-end, follow this guidance."
+description: "When you are tasked with building a feature end-to-end, follow this beads-issue-per-step workflow: epic root → understand → plan → decompose → implement → review → punch-list → closeout → reconcile-and-finalize."
 metadata:
   category: workflow
 ---
@@ -20,7 +20,7 @@ When you are tasked with building a feature end-to-end, follow this guidance.
 > fails. Refactors done to make a feature buildable run first, as their own unit; the feature then
 > follows on this workflow.
 
-## Relvant skills
+## Relevant skills
 
 ### Step zero — before claiming any task
 - `boop-skills-discovery` — when you pick up a non-trivial task, before claiming it: the discovery backstop. An issue's breadcrumbs are the primary way the right skills reach you, but an issue can miss one. Before claiming any task in this workflow, run the discovery sweep so a forgotten breadcrumb does not cost you the discipline that skill carries.
@@ -37,7 +37,7 @@ When you are tasked with building a feature end-to-end, follow this guidance.
 - `boop-database-data-model` — when you need to design data models.
 - `boop-web-web-ui-design` — when you need to design web UIs.
 - `boop-ux-purpose-judgement` — when the feature includes new or substantially modified UI surface: the structural lens. Does each affordance belong, in the right shape, for the right job? Run during Plan against the spec; run during Review against a screenshot of the built page.
-- `boop-ux-visual-judgement` — when the feature includes new or substantially modified UI surface: the taste lens (eye-path, register, anatomy, scan-line). Run during Review against a screenshot of the built page; optional during Plan against a nearby existing surface for register calibration only.
+- `boop-ux-visual-judgement` — when the feature includes new or substantially modified UI surface: the taste lens (eye-path, loudness, anatomy, scan-line). Run during Review against a screenshot of the built page; optional during Plan against a nearby existing surface for loudness calibration only.
 
 
 ### Coding
@@ -71,6 +71,15 @@ Documents are organized into
 
 The loop runs without a live operator. The patterns below follow from that and apply to every task in the workflow.
 
+### Keep working until the Done-when is true
+
+A task is finished when every one of its Done-when conditions holds, checked against the artifact the condition names: the call site in the code, the archived spec, the rendered page.
+"I performed the listed steps" and "the tests are green" are the two weaker stopping points an agent drifts to, and neither is the bar.
+If a condition cannot be met, register the wait as the "Waiting protocol" below says, with a blocking edge or a human gate, rather than closing on partial work.
+
+This is the same discipline Review applies afterwards, when it verifies each closed slice against its Done-when by name (step 4).
+Review is the second net, not the only one.
+
 ### Respect safety mechanisms; do not override them
 
 Tools sometimes expose safety mechanisms for destructive operations. Examples include consent environment variables like `PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION`, a required `--force` flag, an interactive "are you sure?" prompt, or a warning that the command emits before it runs. These mechanisms exist because the action behind them was deemed to require explicit human approval before it could be considered safe to run.
@@ -113,7 +122,7 @@ You leave `bd ready` because of the edge, and you return to it automatically whe
 Two constraints, both easy to get wrong:
 
 - **The edge must point at a sibling or an unrelated issue — never at your own ancestor or your own descendant.** An unresolved edge on a parent holds *every* descendant out of `bd ready` at every depth, so gating a container on its own children deadlocks those children. (bd rejects ancestor/descendant gating edges outright.)
-- **Use `blocks`, not `waits-for`.** In bd 1.1.2 `waits-for` is not even a valid `bd dep add -t` type (valid types are `blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes`); and where `waits-for` does exist it releases when the *first* child of its target closes, not all of them — unsafe against any container with more than one child. Use `blocks`, one edge per thing waited on.
+- **Use `blocks`, not `waits-for`.** In bd 1.1.2 a `waits-for` edge added with `bd dep add -t waits-for` releases when the *first* child of its target closes, not all of them — unsafe against any container with more than one child. (`bd dep add --help` does not list `waits-for`, but bd accepts it, as it accepts any string after `-t`; see `boop-project-mgmt-beads-planning` for the measured types.) Use `blocks`, one edge per thing waited on.
 
 **Waiting on a human decision** — a build-or-defer call, a safety mechanism that needs operator consent, a spec ambiguity only the operator can resolve. Create a **human gate** and stay `open`:
 
@@ -164,7 +173,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 2. **Plan the work**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading `specs/{feature-name}-plan-findings.md`** from the "understand" task (path is in this task's breadcrumbs; also check `bd show <predecessor-id>` notes). The findings contain gap analysis and open questions that must inform the plan. Then find the feature implementation plan document, or create one in `specs/`. Follow the engineering planning skill. Ensure the plan covers the spec; create follow-up tasks for any gaps.
 
    **UX paired-lens pass (when the feature includes new or substantially modified UI surface):** If the spec touches the app's UI surface, run a paired-lens pass during planning so the plan and downstream punch-list carry explicit UI work and acceptance criteria. The two cases are not symmetric:
-   - **Brand-new surface (the page does not exist yet):** run `boop-ux-purpose-judgement` against the spec, reference docs, and any existing nearby templates that anchor the register. **Do not try to screenshot a not-yet-built surface** — the purpose lens has an explicit fallback for missing inputs; use it and label each finding by which inputs supported it. The output validates the spec's interaction-shapes table: each affordance traced to a job, mechanism matched against frequency × consequence, anything underspecified flagged as a plan or punch-list candidate. Optionally run `boop-ux-visual-judgement` against a nearby existing surface for **register calibration only** (output is "the calm/loud target the new surface should match," not findings about the unbuilt page); skip it if no nearby surface is a useful anchor.
+   - **Brand-new surface (the page does not exist yet):** run `boop-ux-purpose-judgement` against the spec, reference docs, and any existing nearby templates that anchor how loud the surface should be. **Do not try to screenshot a not-yet-built surface** — the purpose lens has an explicit fallback for missing inputs; use it and label each finding by which inputs supported it. The output validates the spec's interaction-shapes table: each affordance traced to a job, mechanism matched against frequency × consequence, anything underspecified flagged as a plan or punch-list candidate. Optionally run `boop-ux-visual-judgement` against a nearby existing surface for **loudness calibration only** (output is "the calm/loud target the new surface should match," not findings about the unbuilt page); skip it if no nearby surface is a useful anchor.
    - **Modified existing surface (the page exists and is being changed):** capture a screenshot of the current surface with `npm run ux:capture -- <path> <label>`, then run both lenses in order — purpose first, visual second.
    Write the lens findings into the same `specs/{feature-name}-plan-findings.md`, labelling each with the lens that produced it (`[purpose]` or `[visual]`) and noting which inputs were loaded.
 
@@ -173,11 +182,24 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    **Every code-touching sub-task carries a `Tests` section and testing breadcrumbs.** This is how the workflow produces tasks that get tested correctly — author it when you write the sub-task, not later. Each sub-task that creates or changes code must include in its description:
    - A **`Tests`** section naming: (a) the contracts the task creates or modifies — if it writes a function other code calls, or is itself a new caller of an existing function, name that producer/consumer boundary explicitly (e.g. *"this task calls `buildXyz`; exercise the caller's actual argument shape pairwise, not just the function's contract in isolation"*); (b) the test shapes required at this scope — unit for pure helpers, pairwise component where two pieces of code share a boundary, integration where data crosses a real boundary (DB, HTTP, serialization), route/render for surfaces; (c) any test scope deliberately deferred, with why. A `Tests` section that only says "tests pass" gives the implementing agent no signal about which shape the work needs, and the easy default (a unit test on whatever was written) misses contract bugs.
    - **Breadcrumbs to the design/layer skill** for the code being written (controller, service, data-access, view) **and to all three testing skills** (general principles, Light TDD, the domain testing skill — see the Testing section above). The general-principles skill is the one most often dropped because a task "feels like just unit-testing" — which is exactly when pairwise contract tests get missed. List all three by default; drop one only if it is genuinely irrelevant.
+     A child's session starts cold and sees only its issue; it does not read this workflow.
+     Write them 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`.
+     Names, not extracts: a command or checklist copied out of a skill into an issue is a second copy of the method, and it drifts out of step with the skill.
    - **The test run scope.**
-     Name what the sub-task runs before it calls itself done: the focused tests for the files it touches, plus the project's whole-program static check, and an explicit instruction not to run the full suite.
-     The full suite runs once per branch, on the Review task in step 4 — give Review that scope when you create it below.
-     Left off, every sub-task runs the whole suite on its own reasoning and the branch pays for it once per slice.
-     The wording to put on each is in the `boop-project-mgmt-beads-planning` skill.
+     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, so give Review that scope when you create it below.
+     Left unstated, a sub-task that has just changed a widely called function 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`.
+   - **The live checks, scoped the way the tests are.**
+     A live check starts a running system and watches its real behaviour, such as an end-to-end run or a browser pass over a changed page, and each run costs minutes.
+     Beside its run scope, each slice names the live checks that exercise what it changed, and runs only those.
+     The complete set runs once, at Review, against the complete branch.
+     A spec that asks for each stage to be verified before the next starts is satisfied by each slice's own checks plus that one complete run.
+     Rerun the whole set at a stage boundary only when the spec gives a reason that stage needs it, such as a stage that ships on its own.
+
+   **Audit the child issue bodies, then revise them, before this task closes.**
+   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 child 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 child that says "a sibling issue handles this" without naming it, or a term the container defines and a child then uses bare.
 
    **THE TREE RECIPE — verified on bd 1.1.2.** Wire it exactly this way. The whole lifecycle was driven through a simulated loop against this shape, including a slice that decomposed itself mid-flight, and at every step the loop claimed exactly one correct issue: no leak, no deadlock, no stall.
 
@@ -225,7 +247,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    bd dep add <reconcile-id> <closeout-id>
    ```
 
-   **Every edge is plain `blocks`. Never `waits-for`** — in bd 1.1.2 `waits-for` is not a valid `bd dep add -t` type, and where it does exist it releases when the *first* child of its target closes, not all of them, contradicting its own documentation. See the Waiting protocol.
+   **Every edge is plain `blocks`. Never `waits-for`** — in bd 1.1.2 a `waits-for` edge added with `bd dep add` releases when the *first* child of its target closes, not all of them. See the Waiting protocol.
 
    > **There is no rollup-gate leaf any more, and adding one back is a regression.** Earlier versions of this recipe created a childless "all slices complete" marker task for Review to depend on. It existed only because bd refuses gating edges to or from an **epic**, so an epic container could not be depended on directly. That restriction applies to **epics alone** — `task blocks-on feature` and `feature blocks-on task` are both **accepted**. Review can simply block on the slices. The gate was an extra node, an extra agent turn, and an extra thing to forget to close.
 
@@ -262,15 +284,15 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    - **It is the last link in one chain, so it cannot fire early.** Every lifecycle task is blocked-by the previous one, and Review is blocked-by every slice, so nothing downstream can run against partial work.
    - **It is a sibling of the work, so it can wait on it without holding it.** Reconcile is a childless leaf child of the *root*, never a parent of any slice — an unresolved edge on a parent holds every descendant, so a gate placed above the work would deadlock it.
 
-4. **Review the work done**: This task issue must be gated on **slice completion**, not on the Decompose task — Decompose only plans. Step 3 wires this: it removes any stale Review→Decompose dep and makes each slice block Review with a plain `blocks` edge (so Review fires only when *every* slice closes), and deliberately does **not** wire Review `waits-for` the do-the-work container, because `waits-for` releases on the first slice closing and hands Review a partial branch. (If this Review issue was pre-created with a dep on Decompose, step 3 is responsible for rewiring it to slice completion.) This task reviews 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 on what was implemented.
+4. **Review the work done**: This task issue must be gated on **slice completion**, not on the Decompose task — Decompose only plans. Step 3 wires this: it removes any stale Review→Decompose dep and makes each slice block Review with a plain `blocks` edge (so Review fires only when *every* slice closes), and deliberately does **not** wire Review `waits-for` the do-the-work container, because `waits-for` releases on the first slice closing and hands Review a partial branch. (If this Review issue was pre-created with a dep on Decompose, step 3 is responsible for rewiring it to slice completion.) This task reviews all changes **in the feature branch** `work/<feature-issue-id>` (confirm with `git branch` or breadcrumbs).
+   The slices are the children of the do-the-work container, so list them with `bd children <do-the-work-container-id>`; in the small shape, which has no container, they are the root's children.
+   In the epic shape, `bd children <root-id>` returns the container and the lifecycle tasks, not the slices.
 
-   **Precondition check before reviewing anything (forbid reviewing a partial branch, recurs):** Review must cover the *whole* feature, not whatever happens to be built. The slice-completion wiring in step 3 is meant to hold Review until every slice closes, but a slice further decomposed at implementation time — or a mis-wired dep — can still let Review go ready against a partial branch. Before reading any code, run both checks:
+   **Precondition check before reviewing anything (forbid reviewing a partial branch, recurs):** Review must cover the *whole* feature, not whatever happens to be built. The slice-completion wiring in step 3 is meant to hold Review until every slice closes, but a slice further decomposed at implementation time — or a mis-wired dep — can still let Review go ready against a partial branch. Before reading any code, check the slices: list them as above, and `bd show <id>` on each, including any sub-slice a slice decomposed into during implementation (`bd children <slice-id>` shows them). Confirm **every** slice and sub-slice is `closed`. Any that is `open`, `in_progress`, or itself `blocked` means the branch is partial.
 
-   **Check 1 — slices:** `bd children <feature-issue-id>`, and `bd show <id>` on each slice (and on any sub-slice a slice was further decomposed into during implementation). Confirm **every** slice/sub-task is `closed`. Any slice that is `open`, `in_progress`, or itself `blocked` means the branch is partial.
+   **Do not check the do-the-work container's own status.** It is an organising issue that nobody claims, and only Reconcile (step 7) closes it, long after Review has run. So on a finished branch the container is still `open`, and that is the healthy state; requiring it to be closed, or adding an edge onto it, would hold Review forever.
 
-   **Check 2 — container:** `bd show <do-the-work-container-id>`. If it is `blocked`, the work stopped at a partial state.
-
-   **If either check fails, stop and add a blocking edge for each still-open slice — do NOT scope the review down to the built slices and close, and do NOT set `status=blocked`.** Scoping down is precisely the failure this guard exists to prevent: it lets the largest slice ship with zero review pass. Review is waiting on the remaining slices to close, which happens on its own with no human input, so an edge is the right primitive — it holds Review out of `bd ready` and returns it automatically when the last slice closes (see "Waiting protocol" above). One edge per still-open slice ID from the failing check(s):
+   **If any slice is still open, stop and add a blocking edge for each one — do NOT scope the review down to the built slices and close, and do NOT set `status=blocked`.** Scoping down is precisely the failure this guard exists to prevent: it lets the largest slice ship with zero review pass. Review is waiting on the remaining slices to close, which happens on its own with no human input, so an edge is the right primitive — it holds Review out of `bd ready` and returns it automatically when the last slice closes (see "Waiting protocol" above). One edge per still-open slice ID:
    ```
    bd dep add <this-review-task-id> <every-open-slice-id> -t blocks
    bd update <this-review-task-id> --notes "Review cannot run against a partial branch; <which slices are still open, with specific IDs and statuses>. Blocking edges added; this returns to bd ready on its own once they close."
@@ -278,22 +300,39 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    Review is a **sibling** of the slices, never their parent, so these edges gate Review without holding the slices themselves. Do not review, do not write the review summary, do not file a punch-list, do not close this task. Only once every slice is closed does Review return to `bd ready` and the review below run — against the complete branch.
 
    This task will:
+  - **Run the full test suite first, before reviewing anything.**
+    Every slice ran only its focused tests, so this is the first run that sees the complete branch.
+    Run it as one blocking call, as "Run long verification steps BLOCKING" above says, and read the summary rather than the exit code.
+    A red suite stops the review and becomes the first punch-list item; do not review code whose tests fail.
+    For a test that passes alone and fails in the full run, follow the `boop-testing-testing` skill's section "A suite that passes alone and fails in a full run is a suspect, not a verdict".
+  - **Then run each live check the spec's success criteria name, once.** This is the one place they all run together. A failing check becomes a punch-list item.
   - perform a code review and test review of all changes in the feature branch (use available skills for code review, test review, and any other relevant review skills).
-  - **Verify each closed slice against its Done-when, by name.** For every closed sub-task (`bd children <feature-issue-id>`, then `bd show <id>` on each), read its Done-when / acceptance conditions and confirm **each condition is actually met on the branch** — not merely that the task is closed. A closed task only means an agent decided it was done; it does not mean the goal was reached. Check the real artifact each condition names: if a condition says a function is wired into a code path, confirm the call site exists in `src/` — not just that a test exercises the function. List any unmet Done-when condition as a punch-list item, citing the slice ID and the specific condition.
+  - **Verify each closed slice against its Done-when, by name.** For every closed slice and sub-slice (listed as in the precondition check, then `bd show <id>` on each), read its Done-when / acceptance conditions and confirm **each condition is actually met on the branch** — not merely that the task is closed. A closed task only means an agent decided it was done; it does not mean the goal was reached. Check the real artifact each condition names: if a condition says a function is wired into a code path, confirm the call site exists in `src/` — not just that a test exercises the function. List any unmet Done-when condition as a punch-list item, citing the slice ID and the specific condition.
   - write the review to `labs/claude-runs/{feature-issue-id}-review-summary.md`.
   - append a punch-list of issues that must be addressed before merge.
 
    **UX paired-lens pass (when the change touched UI files):** if `git diff main...HEAD -- views/ styles/ src/controllers/` shows changes, the surface needs a post-build UX review. The page now exists, so both lenses run normally against it:
 
-   1. Pick a port and confirm it is free before you start anything: `lsof -ti tcp:<port>` prints nothing when the port is free. Then start the dev server in the feature worktree: `PORT=<port> npm --prefix <absolute-worktree-path> run dev` — the `--prefix` form is required; `cd <worktree> && npm run dev` silently falls back to the project root and screenshots the wrong build. If the port is already held, do not kill what is there and do not assume it serves your code — several worktrees and loops can run at once. Identify the holder with `lsof -a -d cwd -p <pid> -Fn` and reuse the server only when that directory is this feature's worktree; otherwise move to the next free port.
+   1. Pick a port and confirm it is free before you start anything: `lsof -ti tcp:<port> -sTCP:LISTEN` prints nothing when the port is free. Then start the dev server in the feature worktree: `PORT=<port> npm --prefix <absolute-worktree-path> run dev` — the `--prefix` form is required; `cd <worktree> && npm run dev` silently falls back to the project root and screenshots the wrong build. If the port is already held, do not kill what is there and do not assume it serves your code — several worktrees and loops can run at once. Identify the holder with `lsof -a -d cwd -p <pid> -Fn` and reuse the server only when that directory is this feature's worktree; otherwise move to the next free port.
    2. Capture each changed surface with `npm run ux:capture -- <path> <label>`, passing `BASE_URL=http://localhost:<port>`.
    3. Run `boop-ux-purpose-judgement` first against the screenshot plus the rendered HTML, template, controller, and route. Run `boop-ux-visual-judgement` second against the screenshot.
-   4. Label findings by lens (`[purpose]`, `[visual]`) in `labs/claude-runs/{feature-issue-id}-review-summary.md`, alongside the code-review findings, and feed them into the punch-list the same way code-review findings do.
-   5. **Stop the dev server before this task closes**, unless you reused one you found already running. Stop it by port: `lsof -ti tcp:<port> | xargs kill`. Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like) — a pattern matches every other worktree's server and the operator's own, and this project routinely has several alive at once. Never stop a server you did not start, including any port a concurrently running loop owns.
+   4. Drive each changed surface against its slices' Done-when, as the section "Verifying a change someone will look at" in `boop-web-testing` describes when the project has the web capability: the lenses judge how the page reads, and that pass confirms a person gets what each issue promised.
+   5. Label findings by lens (`[purpose]`, `[visual]`) in `labs/claude-runs/{feature-issue-id}-review-summary.md`, alongside the code-review findings, and feed them into the punch-list the same way code-review findings do.
+   6. **Stop the dev server before this task closes**, unless you reused one you found already running.
+      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.
 
    **Why the stop belongs in this step, not at Closeout.** This pass runs once per surface-touching task, so a server left behind is not one stray process but one per surface. Deferring teardown to a distant Closeout is how orphaned watchers accumulate — each holding memory, none listening, none visible unless someone goes looking. The phase that starts a process is the phase that has to stop it.
 
 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.
+  **Those sub-tasks are built in the same run, before Closeout.**
+  Filing them is this task's job; the loop then picks each one up as ready work, and the edges below hold Closeout until every one has closed.
+  A run that files a punch list and stops has not finished the feature: it leaves the review's findings unaddressed on the branch the operator is asked to merge.
 
   **Hierarchy rule:** Create punch-list items with `--parent <punch-list-task-id>` so they are true hierarchical children: `bd create "..." --parent <punch-list-task-id> ...`. `bd dep add` creates sequencing only — it is not a substitute for `--parent`. Sequencing deps between siblings are fine to add after creation.
 
@@ -301,7 +340,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
   **Wire Closeout's dependency carefully (critical, recurs):** Closeout (step 6) must not run until the punch-list task *and all its children* are closed. The default `blocks` dep releases as soon as the punch-list task itself closes — which can happen while the just-filed punch-list fix children are still open, so Closeout would archive the spec and integrate reference docs against the *pre-fix* state.
 
-  **Use one plain `blocks` edge per thing you are waiting on. Never `waits-for`.** `waits-for` releases as soon as the *first* child of its target closes, not all of them — so with several fix children open, the first one closing would release Closeout against pre-fix state, the exact failure this step exists to prevent (and in bd 1.1.2 `waits-for` is not even a valid `bd dep add -t` type). `blocks` is unambiguous — it resolves only when *that* issue closes — so gating on N issues means N edges. There is no cascade to rely on and none is needed.
+  **Use one plain `blocks` edge per thing you are waiting on. Never `waits-for`.** `waits-for` releases as soon as the *first* child of its target closes, not all of them — so with several fix children open, the first one closing would release Closeout against pre-fix state, the exact failure this step exists to prevent (that is how a `waits-for` edge added with `bd dep add` behaves in bd 1.1.2). `blocks` is unambiguous — it resolves only when *that* issue closes — so gating on N issues means N edges. There is no cascade to rely on and none is needed.
 
   **Critical order — do these steps IN ORDER, do not close Punch-list until step 4 has been verified:**
 
@@ -326,17 +365,18 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
    **Precondition check before any closeout activity (defensive layer, recurs):** the activities below — archive the spec, integrate reference docs, close the issues — are procedural, and an agent will walk through them cleanly even when the actual work is not done. The dep-wiring race (see the callout at the end of step 5) can let this task become ready before implementation has run, or before the punch-list fix children have closed. Before taking any closeout activity, run both checks:
 
-   **Check 1 — implementation:** `bd show <do-the-work-container-id>` and confirm status is `closed`.
+   **Check 1 — implementation:** list the slices as in step 4's precondition check, and confirm every slice and sub-slice is `closed`.
+   Check the slices, not the container: only Reconcile closes the container, and Reconcile is blocked by Closeout, so requiring the container to be closed here, or adding an edge onto it, leaves the two tasks waiting on each other.
 
    **Check 2 — punch-list children:** `bd children <punch-list-task-id>` and confirm every child is `closed`. (Even if the punch-list task itself is closed, individual children can still be open — that means the Closeout dep wiring in step 5 was skipped or arrived too late, and the original `blocks` dep released prematurely.)
 
-   **If either check fails, stop and add a blocking edge for each still-open issue — do NOT set `status=blocked`.** Closeout is almost always waiting on the implementation container and/or the punch-list children to close, which happens on its own with no human input, so an edge holds it and returns it automatically (see "Waiting protocol" above). Setting the status instead freezes the task even after the cause clears. One edge per still-open issue ID from the failing check(s):
+   **If either check fails, stop and add a blocking edge for each still-open issue — do NOT set `status=blocked`.** Closeout is almost always waiting on the remaining slices and/or the punch-list children to close, which happens on its own with no human input, so an edge holds it and returns it automatically (see "Waiting protocol" above). Setting the status instead freezes the task even after the cause clears. One edge per still-open issue ID from the failing check(s), pointed at the open slices and fix children themselves, never at the do-the-work container:
    ```
-   bd dep add <this-closeout-task-id> <do-the-work-container-id-if-open> -t blocks
+   bd dep add <this-closeout-task-id> <every-open-slice-id> -t blocks
    bd dep add <this-closeout-task-id> <every-open-punch-list-child-id> -t blocks
    bd update <this-closeout-task-id> --notes "Closeout cannot run; <check failure summary, including specific issue IDs and statuses>. Blocking edges added; this returns to bd ready on its own once they close."
    ```
-   Closeout is a **sibling** of the implementation container and of the punch-list, so these edges gate Closeout without holding any of that work. Never point such an edge at your own ancestor or descendant. (If the wait is instead a genuine operator decision — e.g. the feature cannot proceed without a human call — raise a **human gate** on this Closeout task instead, per the Waiting protocol; it will not auto-release.) Do not archive the spec, do not integrate reference docs, do not commit, do not close bd issues. Closeout returns to `bd ready` on its own once the edges resolve, or when the operator resolves the gate. Do not interpret a subsequent boop resume prompt as authorization to override this — the wait stands until its edges resolve or the operator confirms.
+   The slices sit under the container and the fix children under the punch-list, both siblings of Closeout, so these edges gate Closeout without holding any of that work. Never point such an edge at your own ancestor or descendant. (If the wait is instead a genuine operator decision — e.g. the feature cannot proceed without a human call — raise a **human gate** on this Closeout task instead, per the Waiting protocol; it will not auto-release.) Do not archive the spec, do not integrate reference docs, do not commit, do not close bd issues. Closeout returns to `bd ready` on its own once the edges resolve, or when the operator resolves the gate. Do not interpret a subsequent boop resume prompt as authorization to override this — the wait stands until its edges resolve or the operator confirms.
 
    When (and only when) the checks pass, the closeout task performs two activities:
 
@@ -347,10 +387,14 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    - The archived spec and planning artifacts should be the full originals — do not edit or trim them.
 
    **b. Integrate into reference:**
-   - Follow the `boop-product-design-reference-integration` skill to blend the new feature's knowledge into existing `reference/` pages.
-   - This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages (and creating new concept pages only when a genuinely new concept has no home).
+   - Follow the `boop-product-design-reference-integration` skill. Its goal is that a reader with a question about one subject finds one page whose title names that subject; name the subjects from what actually shipped, and let the skill decide where each one goes.
+     Pages named in this task's description are where to start, not the limit.
+   - **Write this task's description as what was learned, not as pages to edit.** When you create the Closeout task, list the knowledge the feature produced: what now exists, what changed, and what was decided. Do not list the reference pages to update. 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, which is how a subject the feature created ends up buried in a page about something else.
    - Update cross-links between affected reference pages.
    - Remove or update any reference content that is now outdated.
+   - **Then decide, explicitly, whether the feature changed what a customer could truthfully be told.**
+     If the project keeps a capability catalog and the answer is yes, update it against the rule in the reference-integration skill's section "A capability catalog, if the project keeps one".
+     Otherwise record "no product-facing change" in the closing comment.
 
    **c. Hand off — the loop ends at the feature branch:**
 
@@ -372,21 +416,23 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
    **Step 1 — sweep the tree and branch.** Enumerate every descendant of the root (`bd children <root-id>`, recursing into containers) and read each one's status. Branch on what you find:
 
+   **An open container is not work in flight.** An open `epic` or `feature` that has children is an organising container, and only Step 2 below closes it, so judge it by its children, never by its own status. An unfinished slice still means a wait, pointed at the slice; an edge onto the container would wait for this task to close it, which never happens.
+
    - **A descendant genuinely needs a human** (an operator decision, a safety mechanism awaiting consent). The feature is **not** done. Raise a **human gate** on *this* Reconcile task naming the held IDs, and stop:
      ```
      bd gate create --type=human --blocks <reconcile-task-id> \
        --reason="Cannot finalize; descendants <held issue IDs> need an operator decision. <summary>."
      ```
 
-   - **Real work is still in flight** (any descendant `open` or `in_progress`). Add a blocking edge onto each in-flight ID, and stop. Reconcile returns to `bd ready` on its own once they close — no monitoring pass required:
+   - **Real work is still in flight** (any descendant other than an organising container is `open` or `in_progress`). Add a blocking edge onto each in-flight ID, and stop. Reconcile returns to `bd ready` on its own once they close — no monitoring pass required:
      ```
      bd dep add <reconcile-task-id> <each-in-flight-id> -t blocks
      ```
      Reconcile is a childless leaf **child of the root**, and the in-flight work sits under the do-the-work container, so these edges point at issues that are neither its ancestors nor its descendants — which is what keeps them from deadlocking the work they wait on.
 
-   - **Every descendant is closed.** Proceed to Step 2.
+   - **Every descendant is closed, apart from the organising containers.** Proceed to Step 2, which closes them.
 
-   **Step 2 — finalize (only when every descendant is closed).** In order:
+   **Step 2 — finalize (only when every descendant but the containers is closed).** In order:
 
    1. **Run any un-run Closeout activity.** Confirm Closeout's two knowledge-integration activities actually landed — the spec (and its `-plan.md` / `-plan-findings.md` siblings) moved to `specs/history/`, and the feature's knowledge folded into `reference/`. If Closeout never ran or left either undone, do that work here now per step 6a/6b and the `boop-product-design-reference-integration` skill, then `bd close <closeout-task-id>` if it is still open.
 
@@ -401,11 +447,13 @@ Create tasks as child issues of the feature issue. The descriptions below are th
       ```
       bd close <container-id>          # the do-the-work container: a feature, closes freely
       bd close <reconcile-task-id>     # close yourself — you are the last open child of the root
-      bd epic close-eligible           # now every root child is closed, so the epic root closes
+      bd close <root-id>               # now every root child is closed, so the epic root closes
       ```
       For the **small** shape there is no container and the root is a `feature`, so it is just `bd close <reconcile-or-last-task-id>` then `bd close $ROOT`.
 
-      **Why this order.** bd **refuses to close an epic that still has an open child** — Reconcile is that open child, so closing the root before yourself simply fails, and if the failure is swallowed the root is left open with every other issue closed. (A `feature`-typed root does allow it, which is why the order looks optional until the root is an epic.) Closing your own bd issue does not end your turn, so running `bd epic close-eligible` afterwards is fine — and it is better than `bd close <root> --force`, which closes the root while leaving Reconcile open.
+      **Why this order.** bd **refuses to close an epic that still has an open child** — Reconcile is that open child, so closing the root before yourself simply fails, and if the failure is swallowed the root is left open with every other issue closed. (A `feature`-typed root does allow it, which is why the order looks optional until the root is an epic.) Closing your own bd issue does not end your turn, so closing the root afterwards is fine — and it is better than `bd close <root> --force`, which closes the root while leaving Reconcile open.
+
+      **Close the root by its id, not with `bd epic close-eligible`.** That command takes no issue id: it closes every epic in the database whose children are all closed, including unrelated ones another effort left eligible.
 
       **Do this even though boop has a safety net, because the net does not cover every run.** `closeCompletedFeatureRoot` in `src/commands/loop.ts` closes a root whose children have all closed, and it accepts a `feature` *or* `epic` root — but its call site is guarded by `work && resolvedFlow && prefix`, so it fires **only in spec-driven runs (`--work --flow`)**. An issue-driven `--prefix` run never reaches it. In spec-driven mode your explicit close just makes the net a no-op, which costs nothing.
 

package/skills/boop-light-dev-workflow/SKILL.md

@@ -56,21 +56,37 @@ If the design fails, redesign now — it is far cheaper here than after an epic'
 Now swap the "implement" tail of a one-pass flow for a decomposition. In the **same session**, while grounded, emit **one bd epic** (an epic container is claim-safe) with child issues scoped to the actual wiring:
 
 - **Ground each child in the real code** — name the files, call sites, conditions, and events from *investigate*. A child issue written by the agent that read the real system is a far less lossy input to its execution session than a spec would be.
+- **Name the skills each child needs, and name only their names.**
+  A child issue is the whole briefing its session gets: that session never reads this workflow, and it will not read every skill hunting for the few that matter.
+  Put on each child the skills its kind of work uses: the skill for the layer it touches, and all three testing skills — `boop-testing-testing` for which shape of test the change needs, `boop-testing-tdd-light` for the cycle, and the stack's testing skill.
+  Write them 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`.
+  Names, not extracts: a command or checklist copied out of a skill into an issue is a second copy of the method, and it drifts out of step with the skill.
+- **Put the test run scope on every child.**
+  Each child 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 child that completes it.
+  Left unstated, a child that has just changed a widely called function 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`.
 - **Keep it proportional.** The epic is the real work plus its safety tasks — not a regrown four-session front half or a reflexive 13-issue tree. But it does need to *be* an epic: this workflow's floor is a change that genuinely decomposes into several grounded children. If the work is a one-line edit that needs no decomposition, you are in the wrong workflow — file a plain bd issue or just make the change; do not spin up this flow for it.
 - **Size children to a session, not to a step.** A child issue is the unit a session picks up, and every session boundary is a cold start: the next agent re-reads the surface, re-derives the pattern, and re-runs the gates before it changes a character. So never split work that one session could carry. Group related small changes — a set of copy fixes on one template, several style corrections in one stylesheet — into a single child, and keep grouping until that child would take a session past roughly **50%** context. A one-line text change must never be its own child issue; that is a full session spent on a cold start to earn one line of diff.
 - **Include a review task and a punch-list** as children — the relocated safety net. For engine/back-end extensions especially, the review must verify the new wiring is in the **live path** (not tests-only) and handles **every** existing case it touches.
 - Use `boop-project-mgmt-beads-planning` and `boop-project-mgmt-engineering-planning` to shape the epic.
+- **Audit the child issue bodies before the session ends, 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 child 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 child that says "a sibling issue handles this" without naming it, or a term the epic defines and a child then uses bare.
 - **Do not create the feature branch yourself.** This decompose step runs in the *launch directory* (the planning phase runs before any worktree exists), so a `git checkout -b work/<epic-id>` here parks the launch dir on the feature branch — which then collides with the executor's `git worktree add` ("already checked out") and, worse, strands a concurrent session's next commit on your feature branch. The executor owns the branch: `boop loop` creates the worktree and its `work/<epic-id>` branch when it picks up the first child. Just create the bd tree and stop.
 
-The loop then picks up each child as its own execution session. That boundary is the context-budget seam, and it is fine *when the child is large enough to need one* — the children are grounded, so a fresh session can execute them. It is pure waste when the child is smaller than the cold start that precedes it, which is what the sizing rule above exists to prevent. It creates the worktree and feature branch itself; the decompose session above must not.
+The loop then picks up each child as its own execution session. That boundary is the context-budget seam, and it is fine *when the child is large enough to need one* — the children are grounded, so a fresh session can execute them. It is pure waste when the child is smaller than the cold start that precedes it, which is what the sizing rule above exists to prevent. The loop creates the worktree and feature branch itself; the decompose session above must not.
 
 ### 6. Run the epic — implement, review, punch-list
 The loop implements each child (`boop-coding-development`, `boop-testing-tdd-light`), then the review and punch-list run against the whole branch (`boop-coding-review-changes`). Do not treat these as leftover process — they are where the independent perspective the single front session lacked actually happens. Verify each child against its goal, not merely that it closed.
 
 ### 7. Verify and close out
 - **Run the real path, not just the suite.** For UI, capture the render and re-critique against it. For back-end, drive the real end-to-end flow against a throwaway environment — a green suite proves structure compiles, not that the goal is served.
-- Run the targeted tests for what you touched, and the full suite before closeout.
+- The full suite runs once, on the review child that completes the branch; every other child ran its focused tests and the whole-program static check.
 - Integrate knowledge into `reference/` (`boop-product-design-reference-integration`) and archive anything the change completed.
+- **Decide whether the change altered what a customer could truthfully be told, and say so in the handoff.**
+  If the project keeps a capability catalog and the answer is yes, update it against the catalog rule in `boop-product-design-reference-integration`.
+  Otherwise record "no product-facing change", which is the expected answer for most changes rather than a skipped step.
 - Leave the branch for review. **Do not merge to main** — the human owns the merge.
 
 ## Front-end, back-end, full-stack: what "investigate" means

package/skills/boop-refactor-dev-workflow/SKILL.md

@@ -24,10 +24,14 @@ This is the opposite instinct from feature work, and the difference is worth sta
 | The work is | capability that does not exist yet | every existing caller of a contract you are changing |
 | Progress looks like | vertical slices, each demonstrable | concept groups, none user-visible |
 | A green build means | the slice works | **possibly that you have not deleted enough** |
-| Completeness comes from | the Done-when and a demo | the compiler, a mechanical scan, and the suite |
+| Completeness comes from | the Done-when and a demo | the compiler, a search for the deleted name, and the suite |
 
 The central failure mode: **keeping the build green throughout a refactor is only possible by leaving a fallback** — a scalar, an optional-handle-with-default, a first-of-set pick — that silently absorbs the callers you have not converted yet. Every "additive, expand-contract, drop the old thing last" plan re-commits that sin, which is why it keeps producing refactors that look finished and leave an undetected tail.
 
+A scope boundary that leaves the old path callable is the same fallback under another name.
+"Runtime only; the pages keep showing the first item" and "defer the deletion to a later phase" both keep it alive.
+So whoever briefs, reviews or reports on a refactor checks that it began by deleting the old path and committed the red build, and calls a surviving optional parameter with a default unfinished.
+
 ## When this workflow applies
 
 - Changing a relationship's cardinality (one-to-one becoming one-to-many).
@@ -37,6 +41,9 @@ The central failure mode: **keeping the build green throughout a refactor is onl
 
 **When it does not apply:** adding new capability (use the feature workflow), or a change contained to one file with a handful of callers you can see at once. This workflow's overhead only pays when the call sites are too many to hold in your head — which is exactly when diligence-based approaches fail.
 
+It is also the wrong workflow for a change to a database that already holds rows, when the readers of those rows cannot all be updated at the same moment.
+Old and new code then have to run against the same data for a while, and that is the one case where expand-contract — add the new shape, move every reader, drop the old shape last — is the right method.
+
 ## The workflow
 
 ### 1. Establish the target vocabulary first, grounded in the code
@@ -54,6 +61,30 @@ Ground the vocabulary in the domain, not in the code's current names. If the cod
 ### 2. Decompose by concept group, not by call site
 
 One task per concept, ordered so that later concepts build on earlier ones. Enumerate-and-patch — a task per call site, each threading a handle through — always leaves a tail, because the list of sites is exactly the thing you cannot trust yourself to have enumerated.
+Add one more task beside the concept groups, for the verify stage in step 7, blocked by all of them.
+
+**Split a wide concept group at the compiler's checkpoints.**
+A concept group is as wide as its callers, and the widest can be more than one session's work.
+A session should not be run up to the model's context limit, because it slows down there and its judgement drops.
+How wide a group will turn out is hard to predict, but where to cut it is not, because the work falls into three stages and each ends on a state a command can check:
+
+1. Delete the old names and convert until the product code compiles, checked by compiling the product code alone, without the tests.
+2. Convert the tests until they type-check, checked by the whole-program static check over the product code and the tests together.
+3. Walk the test suites, as step 6 describes, until they pass.
+
+Make each stage its own issue, blocked by the one before it, so that each starts in a fresh session.
+Each stage issue carries the method like any other task, and its run scope says which check must be clean when it closes.
+The red the first two stages leave behind is intended: green is the end state of the group, not of each stage.
+Decide which groups are wide from the concept map — a deleted name that appears across dozens of files, or fixtures that reach most of the test tree — and leave a narrow group as one issue, since splitting it only adds cold starts.
+
+**Audit the issue bodies, then revise them, before the work starts.**
+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 issue 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.
+The go-red instruction in step 3 is the one most often lost to compressed wording, and an executor who misreads it keeps the build green with a fallback.
+
+**Put the test run scope on every issue.**
+Each issue runs the focused tests for what its group touches, plus the project's whole-program static check; the full suite runs once per branch, in the verify stage that completes it.
+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`.
 
 ### 3. Delete the escape hatch first, and commit the red build
 
@@ -64,30 +95,65 @@ If the build is still green after the deletion, a surviving hatch is absorbing t
 ### 4. Follow the compiler to green
 
 Fix each site by giving it the handle it needs, reading the set, or — only at a genuine display boundary — an explicit **commented reduction** (`set[0]` with a comment saying it is a render choice). Never inside a reusable resolver, where a write path can reach it.
+More generally, a site that keeps part of the old shape is legitimate only when a comment on that line says why; without one it is an unconverted call site.
 
 **A fallback is never correct.** Not a defaulted handle, not `?? oldThing`, not a first-of-set inside a resolver. If a call site genuinely cannot supply the handle, that is a **finding to surface**, not a fallback to invent. Green is the *end state*, never a state maintained throughout.
 
-### 5. Scan for what the types cannot see
+### 5. Loop on the compiler and a search, not on the test suite
+
+The compiler cannot see code that reaches the changed thing without a type.
+A read behind an inline cast (`as { field?: ... }`) re-declares the deleted field locally and compiles fine.
+So do a raw query naming a dropped column, a value read out of an `any`-typed blob, and a field name inside a template or a data fixture.
+The only tool that finds these is a search for the deleted name — the column, the field, the identifier — and for the inline-cast pattern, across the code, the templates and the data fixtures.
 
-A read hidden behind an inline cast (`as { field?: ... }`) re-declares the deleted field locally and compiles fine. After reaching green, grep for the cast pattern and for the deleted name in strings and comments. Also check loosely-typed call sites (`any`-typed blobs, raw queries, string-built SQL) — the compiler has no opinion there.
+**The conversion loop is: delete, let the compiler list the callers, fix them, search for the deleted name, fix what the search finds, and repeat until the static checks are clean and the search finds nothing.**
+Before the first deletion, confirm that both checks are clean on the unchanged tree, so every error they report afterwards is the refactor's own.
+If the project's static check does not cover the tests, widen it to cover them, because a fixture that still builds the old shape is a caller too.
 
-### 6. Run the full suite — it finds more than the compiler can
+The test suite is not part of this loop, and the reason is how directly each tool names the cause.
+The compiler names a file and a line, and the search names every occurrence; both are complete over what they cover.
+The suite reports one broken query as a cascade of failures in tests that never mention it, so it names symptoms where the compiler names the cause.
+A green static check is still a checkpoint, not the finish line: the compiler cannot see a writer that fails to fill the new field, or a value that now lands where no reader looks, and only running code finds those.
+That is the next step's job.
 
-Two whole classes of breakage are invisible to a type-check of the source:
+### 6. Walk the suites one at a time
 
-- **Fixtures** using the deleted shape, when tests are not in the source's type-check scope. Enumerate them with a widened check and migrate them forward.
-- **Writer-side and runtime gaps.** The compiler cannot see a *writer* that fails to populate the new field, or a value that now lands somewhere a reader does not look. Only the running suite does.
+Take the list of every suite from the test runner — all of them, not a list of failures — and walk it.
+Run one suite on its own; if it fails, read the failure, fix the cause, run it again, and move on.
 
-So the loop is always: **go red → follow the compiler → scan for casts → run the full suite → fix the writer gaps → repeat until green.** A green type-check is a checkpoint, not the finish line.
+**Do not collect the failures first.**
+A full run up front looks like it produces the work-list, and it actually manufactures one.
+Failures share causes: one missing method or one query naming a dropped column fails many suites at once, so a full run records one cause as many separate work items.
+A walk meets each cause once, in the first suite that reaches it, and by the time you arrive at the rest they pass.
 
-### 7. Prove it structurally, then hand off
+Nothing is filed during the walk; the suites you have not reached yet are the work-list.
+The only thing that becomes an issue is what cannot be resolved in the walk: a call site that genuinely cannot supply what the new contract requires, or a design question a person has to answer.
 
-Finish with evidence that does not depend on anyone's care:
+### 7. Verify — a stage, and an issue, of its own, ending in a punch list
 
-- The **mechanical scan** for every deleted pattern returns zero outside explicitly-commented display reductions.
-- A **real-path test at N greater than one** drives the actual surface to distinct outcomes — not a unit test of the new primitive, but the whole path, because concurrency and wiring defects only appear there.
-- The **full suite** is green.
-- Fold what changed into the reference docs, and leave the merge decision to the operator.
+Finish with evidence a reader can check without repeating the work:
+
+- **The search for every deleted name finds nothing**, except occurrences whose line comment says why they are deliberate.
+- **One test drives the real path end to end** — not a unit test of the new primitive, but the whole path, because concurrency and wiring defects only appear there. Where the change made something plural, drive it with three items and assert on the middle one.
+- **Every suite passes.** This is the one place in the workflow that runs them all.
+
+These checks are their own issue, a sibling of the concept groups and blocked by all of them, and a session that did not do the converting works it.
+The agent that converted the call sites is the worst-placed reader of its own work: it knows what it meant the code to do, so it reads that intention into the code.
+
+**Anything unresolved becomes an issue** under the same container, blocking the hand-off.
+A check that was never run counts as failed, since both leave the claim unproved.
+File one issue per cause, not per symptom.
+**A long punch list means the walk in step 6 was skipped.**
+Go back to the walk rather than filing every failure.
+
+**How to run and report the tests here.**
+Go through the project's test script, as "Go through the project's test script" in `boop-testing-testing` says.
+Write a run's output to a file and read the file, rather than piping it into a filter, so a wrong pattern does not force another run.
+A claim that the work is verified names the command, the counts and the commit, so a reviewer can check it without running the suite again.
+
+### 8. Hand off
+
+Fold what changed into the reference docs, and leave the merge decision to the operator.
 
 ## Principles that carry across the whole workflow
 
@@ -95,13 +161,25 @@ Finish with evidence that does not depend on anyone's care:
 
 **Verify the guarantee mechanism itself works.** "The compiler enforces this" is a claim worth testing. A type-check config that does not actually compile the files you think it does has been silently enforcing nothing.
 
-**Prefer three over two when proving a set.** Two is the weakest multi case: a first-of-set bug survives it whenever the arbitrary pick happens to match what the assertion reads. Use three, and assert against the middle one.
+**When the change made something plural, prefer three over two when proving it.** Two is the weakest multi case: a first-of-set bug survives it whenever the arbitrary pick happens to match what the assertion reads. Use three, and assert against the middle one.
 
-**Assert by name and by count.** Naming catches something missing; counting catches something doubled. A set-equality assertion reads identically whether an item was written once or twice.
+**When asserting over a collection, assert by name and by count.** Naming catches something missing; counting catches something doubled. A set-equality assertion reads identically whether an item was written once or twice.
+
+**When the new model gives a different answer from the shipped code, that is a design question, not a regression.**
+Do not patch a consumer back to the old output: that hides the question the refactor existed to raise.
+Record what the old code says, what the new model says, and which surface shows the difference, and leave the choice to whoever owns the design; an unattended session hands it back rather than choosing.
+If the new answer is right, update the copy, the tests and every surface that read the old behaviour; if the old one is right, narrow the new model.
 
 ## Running this unattended
 
-If the work is executed by autonomous agents, put **the method itself into each task's notes** — not just the task's scope. An agent picking up "make this field required" without the go-red discipline will keep the build green, which is the failure this workflow exists to prevent. Carrying the method on every task is what makes an unattended run trustworthy, and it is cheap: the same block on each issue, with a task-specific section.
+If the work is executed by autonomous agents, put **the method itself into each task's description** — not just the task's scope.
+The description is the copy that counts, because `boop loop` sends a session the issue's description and nothing else; the notes can repeat it.
+An agent picking up "make this field required" without the go-red discipline will keep the build green, which is the failure this workflow exists to prevent. Carrying the method on every task is what makes an unattended run trustworthy, and it is cheap: the same block on each issue, with a task-specific section.
+
+**Name the skills each task needs, too:** `boop-testing-testing` on every task, plus the skill for the layer the concept group changes.
+Write them 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 method is the one thing worth copying into an issue, because a fallback left in place cannot be corrected afterwards.
+Copy nothing else out of a skill: the copy in the issue is the one that goes stale without looking stale.
 
 ## Relationship to the feature workflow
 
@@ -110,6 +188,7 @@ A refactor of this kind usually exists to **make a feature buildable**. It ships
 ## Related
 
 - [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) — the peer workflow, for building capability.
+- [boop-architecture-audit-workflow](../boop-architecture-audit-workflow/SKILL.md) — when the structural change has not been chosen yet; it audits an area, grades its findings, and hands the survivors to this workflow.
 - `boop-product-design-engineering-design` — the concept map in step 1 is a design artifact; the current-state audit guidance applies.
-- `boop-testing-testing` — for the real-path proof in step 7.
-- `boop-coding-review-changes` — the scan in step 5 belongs in review too.
+- `boop-testing-testing` — for the real-path proof in step 7, and how to run the suites.
+- `boop-coding-review-changes` — the search for the deleted name in step 5 belongs in review too.

package/skills/boop-test-audit-workflow/SKILL.md

@@ -110,7 +110,21 @@ In the same session, while the classification is fresh, create one bd epic (an e
 
 **Keep the child count low, and group coarsely — at the suite level or higher.** Every child issue is a session for whoever runs it, and a fresh session reloads its context from scratch. Many small children multiply that cost and lose context between them. Prefer a few coarse issues, split by area or by suite rather than by file or by kind of change. Keep a removal together with the rewrite that covers its invariant, so one session cannot delete an old test before its replacement exists. Add one issue that confirms coverage and one that reviews the result. Ground each issue in the real test files it touches, and use `boop-project-mgmt-beads-planning` to shape the tree.
 
-Then create the bd tree and stop. Do not run the work yourself, and do not create the feature branch: the loop creates the worktree and its `work/<epic-id>` branch when it takes the first child. Creating the branch here collides with that and can strand commits.
+**Name the testing skills on every child.**
+A child's session sees the issue body and little else: not this workflow, and not the trim list unless the body points at it.
+Every child that rewrites or promotes a test carries `boop-testing-testing`, because the decision about a test's level (unit, pairwise, integration, seam) lives there, and the level is exactly what a rewrite gets wrong.
+Add the testing skill that matches the suite: the stack's (`boop-typescript-testing` in a TypeScript project) and, for routes, controllers and middleware, `boop-web-testing`.
+The children are all of one kind, so one named set covers the tree; write it once and put it on each child.
+Write them 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`.
+Names, not extracts: copy no method or checklist out of a skill into an issue, so that there is a single copy to keep current.
+The run-scope line is not an extract, and each child still carries it with the project's actual commands, as that skill asks.
+
+**Audit the issue bodies before the session ends, 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 child 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 child that says "a sibling issue handles this" without naming it, or a term the epic defines and a child then uses bare.
+
+Once the audited tree is in place, stop. Do not run the work yourself, and do not create the feature branch: the loop creates the worktree and its `work/<epic-id>` branch when it takes the first child. Creating the branch here collides with that and can strand commits.
 
 ### 6. How the children are executed (the loop runs them; these are the rules each one carries)
 Hand the finished tree to `boop loop --prefix <epic-id> --run`. Prefer `--reuse-session` for this workflow: every child has to re-read the invariant list and the trim list to make a correct keep-or-cut call, and carrying one session across the cluster is exactly the context a fresh-session-per-issue run would reload each time.
@@ -118,7 +132,7 @@ Hand the finished tree to `boop loop --prefix <epic-id> --run`. Prefer `--reuse-
 Write these rules into the child issues so each executing session follows them:
 
 - **The suite passes before and after.** This is a change to the tests, not to behaviour, so the tests in scope stay green throughout, and the only tests that stop existing are the ones the trim list marked for removal.
-- **Run tests per file or per small group, not the whole suite on each pass.** Re-running a large suite on every attempt is the biggest avoidable cost of this kind of work.
+- **Run tests per file or per small group, not the whole suite on each pass.** The file you just rewrote is the test that can tell you whether the rewrite holds, and a whole-suite run answers that question far less directly; this workflow makes hundreds of such passes, so the difference compounds.
 - **Change only tests.** Fixtures, factories, and test harness code count as tests and may change, which is what makes a promotion to a real-collaborator test possible. Production behaviour does not. If a rewrite uncovers a real bug — and a promotion often will, since it exercises a seam nothing exercised before — write a separate issue for it rather than fixing it in place.
 
 The review child then reads the whole branch and checks each change against the invariant it was meant to protect, not merely that the issue closed.
@@ -139,6 +153,7 @@ This is the work of the coverage and review children, and the loop's own closeou
 | Extend an existing system toward a goal, wiring new behaviour from parts that already exist | [boop-light-dev-workflow](../boop-light-dev-workflow/SKILL.md) |
 | Build a genuinely new subsystem, data model, or API from a spec | [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) |
 | Clear a noisy backlog of small lingering items in a themed sweep | `boop-project-mgmt-issue-sweep-workflow` |
+| Audit a surface's production code for structural debt rather than its tests | [boop-architecture-audit-workflow](../boop-architecture-audit-workflow/SKILL.md), which depends on this workflow's verdict that the suite can catch a behaviour change |
 
 If the set of tests is small enough that the audit is a handful of edits with no real decomposition, skip the epic and do the rewrite under a plain bd issue. This workflow is for a surface big enough that classifying first, then executing, earns its keep.