@iamu-dev/iamu 0.7.0-beta.0 → 0.8.0-beta.1

package/dist/templates/prompts/advise.md

@@ -66,6 +66,7 @@ Work in this order. Do not skip ahead to writing fixes.
 - Recommendations, quick fixes and direction texts are prose for a product person and a developer reading together. Plain, specific, in the product's own words.
 - **No file paths or code symbols in the prose.** They go in `builds_on` only. The prose is shown to a later walker who must stay outside the code.
 - A recommendation says what the person would see and why it meets their need, then how it fits this product.
+- **Titles** of directions and observations: A title is a headline someone scans in a list: what changes for the person (a direction) or what is missing or risky (an observation), in a few words. Aim for about 60 characters; the detail belongs in the fields below it. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
 
 ## Answer
 

package/dist/templates/prompts/complete.md

@@ -31,7 +31,7 @@ Write `iamu/.runs/<run-id>/canonical.json`:
     "browser": "chrome-devtools"
   },
   "provenance": {
-    "walker_prompt": { "id": "walkthroughPhilosophy", "version": "2.0.0" },
+    "walker_prompt": { "id": "walkthroughPhilosophy", "version": "<the walker prompt version; iamu complete records the current one>" },
     "model": "unspecified",
     "started_at": "<created_at from manifest>",
     "completed_at": "<current ISO timestamp>"

package/dist/templates/prompts/design-review.md

@@ -16,17 +16,26 @@ You review one surface of the product: a page, its states, and the flows that pa
 - **Name the rule.** When an issue breaks a rule in the design docs, give the rule's name exactly as the doc writes it (its heading, or the bold words that open it) as `rule`, and the entry it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
 - **When a rule hurts a need, say so.** If following a rule is what fails a visitor (the rule keeps a caveat small and grey, and the person missed it), report a `conflict`: the rule and its file, the rule's text copied exactly from the doc as `before`, better wording as `after`, the evidence, and why. Do not silently break the rule or silently follow it. A person decides.
 - **Prefer removing, merging and hiding by role to adding.** Every element must earn its place.
+- **Confirm resolved problems.** When a problem in `problems` or an unverified fix in `fix_history` (`state: "awaiting_rerun"`, carrying a `ref` like `F1`, `F2`, ...) is now visibly fixed on the live surface, list it in `resolved` with its `ref` (`"F1"`) and one sentence (`how`) describing what on the live screen resolves the visitor's need. Never list the same ref in both `issues[].evidence` and `resolved`.
 - **Be specific.** "The approve button and the reject link share one grey; the reject reads as disabled", not "improve hierarchy". Do not manufacture issues: a clean surface is a valid answer.
 
 Severity: `critical` (broken, unreachable, unreadable), `major` (a visitor's need is not met, or the surface is clearly inconsistent), `minor` (polish), `nit` (preference).
 
 ## Answer
 
+**Titles.** A title is a headline someone scans in a list: what is wrong and where, in a few words. Aim for about 60 characters; the detail belongs in `what` and `why`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
+
 Reply with one JSON object and nothing else:
 
 ```json
 {
   "summary": "What this surface is for, for whom, and how well it serves them (two to four sentences).",
+  "resolved": [
+    {
+      "ref": "F1",
+      "how": "What on the live screen now resolves this visitor's need"
+    }
+  ],
   "issues": [
     {
       "title": "Short title",

package/dist/templates/prompts/designer.md

@@ -50,6 +50,8 @@ A correct refusal whose reason is on the screen is not `critical`: the product i
 
 ## Answer
 
+**Titles.** A title is a headline someone scans in a list: what is wrong and where, in a few words. Aim for about 60 characters; the detail belongs in `what` and `why`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
+
 Reply with one JSON object and nothing else:
 
 ```json

package/dist/templates/prompts/walk.md

@@ -172,10 +172,12 @@ Your walking prompt has an `## Access` section saying how to become this persona
 
 - For `iamu browse`:
   ```bash
-  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...]
+  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...] [--then '<command> [args...]']
   ```
   Commands: `click <role> "<name>"`, `click-text "<text>"`, `click-index <N>`, `fill <role> "<name>" "<text>"`, `fill-index <N> "<text>"`, `select <role> "<name>" "<val>"`, `upload <role> "<name>" "<file-path>"`, `upload-index <N> "<file-path>"`, `press <key>`, `scroll [px]`, `back`, `shot`, `wait [ms]`.
-  When accessibility names are ambiguous, missing, or broken, inspect indexed interactive elements and drive via `click-index <N>`, `fill-index <N> "<text>"`, or `upload-index <N> "<file-path>"`.
+  `iamu browse step` automatically saves the screenshot and prints the updated `[#N]` interactive elements and accessibility snapshot — do not run a separate `snapshot` command after `browse step`.
+  Chain consecutive form fills on the same screen into a single step using `--then '<command> [args...]'`.
+  Prefer driving via `click-index <N>`, `fill-index <N> "<text>"`, or `upload-index <N> "<file-path>"` using the `[#N]` numbers from the previous step's output.
   When a link or button opens a new window/tab (`target="_blank"`), manage tabs via `tabs`, `switch-tab <index>`, and `close-tab [index]`.
 - For other surfaces:
   ```bash
@@ -186,12 +188,13 @@ Your walking prompt has an `## Access` section saying how to become this persona
 `note` is your internal first-person persona reaction in character.
 The CLI automatically handles sequential numbering, timestamps, screenshot capture/linking, and live event streaming.
 
-**Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools:
+**Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools. When recording multiple findings, execute them together in a single shell command chained with `&&` rather than one turn per finding:
 
 ```bash
 iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
+- `--title`: A title is a headline someone scans in a list: what goes wrong (or works) and where, in a few words. Aim for about 60 characters; the detail belongs in `--ui-fact`, `--consequence` and `--description`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
 - `--type`: `helps | hinders | missing | irrelevant | incorrect`
 - `--severity`: `critical | major | minor | nit`
 - `--task-impact`: `blocks | impairs | slows | neutral | accelerates | enables`
@@ -203,7 +206,7 @@ iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type h
 
 Leave `triage_status` alone; triage is not the walker's job.
 
-**Screenshots:** Screenshots are captured automatically by `iamu browse step`. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
+**Screenshots:** Screenshots are captured automatically by `iamu browse step`. Do not read step screenshot PNGs with your file-reading tool after routine steps — use the returned accessibility snapshot unless checking a visual layout discrepancy. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
 
 **Execution rule:** Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.
 
@@ -221,4 +224,4 @@ iamu summary <run-id> --reached "Sent the request; it shows Pending with my mana
 - `--question` — Questions for the product team: decisions the walk raised that the product does not settle and that you could not settle as the persona ("Should a reporter see the investigator's checklist at all?", "Is the 14-day notice rule enforced or only advised?"). Not doubts about the test itself.
 - `--setup-note` — Doubts about the test setup, not the product: data that seemed missing or unrealistic, an account that could not see what the situation needs, a date the scenario assumes ("No absences are recorded for summer 2027, so 'nobody is away' may only mean no data"). These go to whoever stages the scenario.
 
-Then return your final summary to the orchestrating agent so it can run `iamu complete` and the evaluation stage.
+Then reply to the orchestrating agent with a concise one-line status (`Walk complete: <N> steps, <M> findings`) so it can run `iamu complete` and the evaluation stage — do not re-type your findings or synthesis into chat.

package/dist/templates/skills/iamu-design.md

@@ -76,31 +76,41 @@ Run `iamu design proposals --json` and decide each open proposal exactly as the
 
 ## D. The fix loop
 
-Fix by looking, not by hoping. For one finding:
+Fix by looking, not by hoping:
 
-1. `iamu fix-brief <finding> --json` (a slug, id, or id prefix). It gives the **before** (page, step and screenshot where the persona hit it), what they **needed**, the full recommendation, the design rules tied to this finding by name with the file and line where each is now (`found: false` when the docs no longer have it), the design docs that apply (`design_files`), what the last design review said about it, the strengths on the same page that must keep working, other open problems there, fixes already tried there, the direction it belongs to, where to save screenshots (`shots_dir`), and the **loop** itself.
-2. Follow `loop` step by step. Save before and after screenshots in `shots_dir` and show their absolute paths when you report.
-3. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
-4. If fix-brief says the finding has no known page, take the page from the finding's step and still screenshot it before you edit.
+- **One finding:** `iamu fix-brief <finding> --json` (a slug, id, or `<run-id>#D<n>`).
+- **One surface (all open findings on a page):** `iamu fix-brief /path --json` (e.g. `iamu fix-brief /approvals`).
+- **A multi-scenario wave (all open surfaces in order):** `iamu fix-brief --wave --json`.
 
-## E. Start a design doc from the template
-
-Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything a person decides is a `<placeholder>`. You and the user fill those in together, and the result becomes the team's doc.
+1. Run the matching `iamu fix-brief` command. It gives the **before** screenshots, what each visitor **needed**, the design rules tied to the findings with the file and line where each is now (`found: false` when the docs no longer have it), the design docs that apply (`design_files`), what the last design review said, the strengths on the page that must keep working (`protect`), fixes already tried there (`fix_history`, with `verified` patterns that held and `recurred` approaches that failed alongside what the post-fix walk still saw), where to save screenshots (`shots_dir`), and the **loop** itself.
+2. Check `fix_history` before editing: never repeat a `recurred` approach, and keep the patterns from `verified` fixes intact.
+3. Follow `loop` step by step. Save before and after screenshots in `shots_dir` and show their absolute paths when you report. When fixing a surface or a wave, use `iamu design review <path> --blind` as the fast designer inner check on the page, and batch persona walkthrough re-runs (`rerun` / `scenarios_to_rerun`) once at the end of the wave.
+4. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
+5. If fix-brief says a finding has no known page, take the page from the finding's step and still screenshot it before you edit.
 
-1. **Template.** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
-2. **Fill it in with the user, one placeholder at a time.** Go through the `placeholders` in this order, one question per message, and edit the draft after each answer. Each question carries a suggested answer drawn from what is known: `iamu/context.yml`, the roles and situations, what runs and findings showed of the screens, the components and tokens. The user accepts it, changes it, or skips it (the placeholder stays; a decision still open also goes under Open Questions).
-   1. **Who it is for:** by role, and what they come to do. Suggest it from the roles and situations the Overview lists, then replace that list with the agreed words. Roles only, never a persona's name.
-   2. **How it should feel:** a few words (calm and plain, dense and fast). Suggest from the domain and the roles' dispositions.
-   3. **Accessibility target:** suggest WCAG 2.2 AA, or more when the domain asks for it (a public service, long reading).
-   4. **Look:** what each token group is for, and for each contrast clash, how to keep the two apart or where one may not be used.
-   5. **States:** how forms report errors, loading, failure, empty. Suggest from what the runs saw and the components that exist (an empty-state component, a field with an error prop). Only the states the product has.
-   6. **Content and voice:** the product's words for its things, tone by role, and date and number formats (suggest from the locale and what the screens show).
-   7. **Checks:** yes/no questions a reviewer answers by looking at one screen, where yes is a pass. Suggest them from the answers so far.
-   8. **Not in the library yet**, then **Open Questions:** components screens need that do not exist, and policy decisions still open.
+## E. Start a design doc from the template
 
-   Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a placeholder and an open question. Name tokens, never raw colours or lengths.
+Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything else starts as a `<placeholder>`. Auto-extract what the code and `iamu/context.yml` already answer, ask the user only for the qualitative intent and clash decisions that code cannot answer, and the result becomes the team's doc.
+
+1. **Template & Auto-Extraction (0 questions to the user).** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
+   Before asking the user anything, read the actual token files (`sources.tokens`), UI components (`sources.components`), page code, and `iamu/context.yml` (plus live rendered screens or recent runs if available), and pre-fill the code-evidenced placeholders in `iamu/.analysis/design-draft.md`:
+   - **Overview — Who it is for:** Synthesize who uses the product and what they come to do from `iamu/context.yml` and the roles and situations the Overview lists, then replace that list with the synthesized role-based words (roles only, never a persona's name or a single-scenario situation number).
+   - **Look — Token roles:** Fill in `<what each is for>` for each extracted token group from how stylesheets and components actually apply those tokens (always name tokens in backticks, never raw hex or px values in prose).
+   - **Interaction and States:** Extract how `Forms` (error reporting), `Loading`, `Failure`, and `Empty` states are actually implemented in `sources.components` and screens. Describe only the states the product has; missing state patterns go under `Not in the library yet` / `Open Questions`.
+   - **Content and Voice — Words & Formats:** Fill in the product's domain `Words` from product copy/`iamu/context.yml` and date/number `Formats` from formatters (`Intl`, `date-fns`, locale helpers) in the code.
+2. **Interview for Qualitative Intent & Clashes (2–3 focused questions, one question per message).** Never ask the user an open-ended blank question or make them describe their own code: each question MUST carry 2–3 concrete options (with `[Recommended]` first) drawn from `iamu/context.yml` and the codebase. Ask at most 2–3 questions, one question per message, using `ask_question` when available, and update the draft after each answer:
+   1. **Creative North Star, Feel & Accessibility Target (`Overview` & `Tone`):**
+      Propose 2–3 options for the system's visual personality and feel—each pairing a named **Creative North Star** metaphor with mood/density adjectives (`How it should feel`, e.g., *"The Quiet Workbench — calm, dense, and keyboard-first"*), `Tone` by role, and `Accessibility target` (recommend `WCAG 2.2 AA`, or stricter when the domain requires it, such as a public service or clinical tool)—and ask if there is any visual anti-reference (what the UI must *never* feel like).
+   2. **Palette Character, Contrast Clashes & Component Feel (`Look` & `Components`):**
+      Briefly show the auto-extracted token roles and component/elevation feel (flat vs. tonal layering vs. lifted, button/input character), and ask for the decision code alone cannot make:
+      - **When `clashes` is non-empty:** for each measured contrast clash in `Look`, propose a concrete `[Recommended]` rule (how to keep the pair apart or where one may not be used, e.g., restricting a low-contrast token to borders/decorators or pairing it with a darker text token) and ask the user to confirm or adjust.
+      - **When `clashes` is empty:** confirm the primary/accent usage doctrine (e.g., a Named Rule like *"The One Accent Rule — primary accent reserved for the single primary action per view"*) and any missing primitives for `Not in the library yet`.
+   3. **Unresolved States or Policy Gaps (only if needed):**
+      Skip this question when the codebase already covers states and formats cleanly. Ask a 3rd question only if key state patterns (`Forms`, `Loading`, `Failure`, `Empty`) are missing or contradictory in code, or if an open domain policy question needs a decision (establish a rule now vs. leave under `## Open Questions`).
+
+   After the user's answers, synthesize `## Review Checklist` (concrete yes/no questions a reviewer answers by looking at one screen, where yes is a pass, derived from the confirmed rules and extracted states) and `## Open Questions` (components screens need that do not exist yet, and policy decisions still open). Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a `<placeholder>` and an open question. Name tokens, never raw colours or lengths.
 3. **Check.** Run `iamu design draft-check --file iamu/.analysis/design-draft.md --json`. Fix each of its `errors` in the draft (a value or path the code does not have, a prop a component lacks, a persona's name) and check again; ask the user only when the fix is a choice.
-4. **Show it once.** Show the whole draft, then the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
+4. **Show it once.** Show the whole draft, briefly highlight the non-obvious creative choices (North Star/feel, clash rules, review checks), and list the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
 5. **Adopt.** Run `iamu design adopt --file iamu/.analysis/design-draft.md --json` (`--to <path>` when the user wants it elsewhere). It refuses only when the target already exists: then ask for another path. It writes the doc and records it, with `applies_to` for its app. From then on it is the team's doc: iamu changes it only through proposals a person accepts.
 6. Offer **A2** (point agents at the doc).
 

package/dist/templates/skills/iamu-findings.md

@@ -39,7 +39,7 @@ Follow this precedence cascade:
 
 When `iamu/config.json` has `cloud_linked: true` and the `iamu_requests` tool is available, call it once before listing. If it returns `ok: false` (not linked, not authenticated, or `cloud_too_old`), skip this section silently.
 
-If `count > 0`, show the requests first, before the findings tables:
+If `count > 0`, show the requests first, before the findings list:
 
 ```
 Requests from the team (2)
@@ -53,7 +53,7 @@ Ask whether to pick one up. When the user picks a request:
 
 1. Call `iamu_requests_claim` with its `id`. If it fails with `lease_held`, say who holds it and when the lease expires, and return to the list.
 2. Follow `next` from the result:
-   - `fix` → go to step 4's **Fix now** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
+   - `fix` → go to step 4's **Fix immediately** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
    - `verify` or `run` → run `iamu-run <scenario.id>`; offer `scenario.targetUrl` as the target when present.
 3. Tell the user the request closes itself on the next `iamu sync` — step 6 runs it.
 
@@ -61,7 +61,7 @@ Ask whether to pick one up. When the user picks a request:
 
 ### 2. List mode: present open findings grouped by scenario
 
-Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. One list, worst first, with both sources: say on every row who found it ("Ana found" / "the designer found (seen)"), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
+Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. One list, worst first, with both sources: every line says who found it (the persona through its block, the designer on the line itself), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
 
 Filter to `triage_status: open`.
 
@@ -85,39 +85,33 @@ A run that simply did not come across a finding proves nothing — never call a
 
 When open findings span three or more scenarios and there are no open directions, or the user asks what to change first, offer a project synthesis: `iamu advise --project --json`, dispatch a thorough-tier subagent with `iamu/.analysis/advise_prompt.md` as its only context, and record its answer with `iamu advise-record --project --data '<json>'`. It proposes directions across every scenario.
 
-Render it as Markdown, not inside a code fence, so the tables render. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
+Render it as Markdown, not inside a code fence. It is read in a terminal: no tables, one line per finding, so the list can be taken in at a glance. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
 
-**<N> open problems** (<C> critical · <M> major · <m> minor) across <S> scenarios · <K> fixes awaiting a re-run
+**<N> open problems** · <counts by severity, only the ones above zero, e.g. "1 critical · 4 major · 4 minor"> · <S> scenarios · <K> fixes awaiting a re-run
 
 ### <persona> · <situation> — **<NO / PARTIAL / YES>**
-<the scenario's latest `summary.verdict.answer`, first sentence or two>
+> <the scenario's latest `summary.verdict.answer`, its first sentence>
 
-| # | Finding | Severity | Where | What to do |
-|---|---|---|---|---|
-| 1 | <title> | **Critical** | <where> | <first sentence of recommendation, or — > |
+1. **Critical** · <title> · <where>
+2. **Major** · designer (seen) · <title> · <where>
 
-Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → nit; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out of the tables. Keep the "What to do" cell to one sentence: the full recommendation belongs in the finding card (step 3).
+A persona finding's line needs no name: the block's heading names the persona who found it. A designer finding's line says `designer (<basis>)` after the severity, and `designer (taste)` plainly when its basis is taste. Add ` ↳ design cause` to a persona finding the designer explained (`design_causes` above zero). A page-review designer finding with no `scenario` goes in a block headed `### <page> — page review`.
 
-Ask the user how they would like to triage:
+Number findings continuously across scenarios, so "fix 3" means one finding. Sort each block worst first (critical → major → minor → nit; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out. No recommendation on the line: it belongs in the finding card (step 3). With more than 7 in a block, show the worst 7 and end it with `+<n> more (<counts by severity>)`.
 
-- **"walk through them"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
-- **"all critical"** → iterate through all critical findings in order.
-- **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
+End with the choices on one line, the recommended one first, and **stop**. Do not use a question tool here, since it covers the list:
+
+`Next: **walk through** (one by one from #1) · **critical only** · **<persona> · <situation>** (one scenario) · **fix 3** · **dismiss 3**`
+
+Recommend **walk through**; recommend a direction first when one is open (see "Directions before findings"). Then, on the user's word:
+
+- **"walk through"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
+- **"critical only"** → iterate through all critical findings in order.
+- **A scenario** (its heading, or "group 1") → iterate through that scenario's findings.
 - **Single number or slug** → single finding (skip to step 3).
-- **"fix 1 and 2"** → make code fixes and mark addressed immediately.
+- **"fix 1 and 2"** → the list shows no recommendations, so never fix from a number alone: show each named finding's card (step 3, without the decision prompt), then one line: `Fix <these N> as shown? Say "yes", or name the ones to leave out.` Only on a yes, fix each as step 4's **Fix immediately** branch does.
 - **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
 
-**Interactive Triage Strategy:**
-- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
-  - Question: "How would you like to review these <N> open findings?"
-  - Options:
-    1. "[Recommended] Walk through findings one by one"
-    2. "Focus only on Critical findings (<C> items)"
-    3. "Review by scenario group: <Top Scenario>"
-- Otherwise (in CLI or text-only environments):
-  How would you like to triage these <N> open findings? I recommend walking through findings one by one.
-  Proceeding with one-by-one triage. (Say "critical only", specify a scenario group, or enter a finding number/slug).
-
 ### 3. Direct triage: review one finding
 
 Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter (`severity`, `type`, `title`, `ui_fact`, `consequence`, `persona`, `walkthrough_step_id`, `screen_title`, `page_url`, `run`) and markdown body (description and recommendation).
@@ -204,6 +198,9 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
   Once the user provides their rationale:
   - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>" --rule "<rule string>"`.
   - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>" --rule "<rule string>"`.
+  - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
+    `iamu triage [slug] --status dismissed --note "<why>" --rule "Don't report: <X>" --sweep "<keyword>"`.
+    This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, matcher, judge, designer, and `fix-brief` all respect.
   - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
 
   Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."** One-word notes ("nope") degrade future runs — capture the user's specific rationale.
@@ -254,7 +251,7 @@ If `<N> > 0` findings were queued for fix:
     Proceeding with code edits — say "done" to keep fixes open in iamu/findings/.
 
 - **Executing the queued fixes:**
-  When Option 1 is chosen, fix each queued finding in turn with the fix loop (`iamu fix-brief <slug>`, before and after screenshots of its page, helped / hurt / no visible change) — the fix shown on its card or agreed in Discuss, not the walker's original text. Findings on the same page go together: fix them as one change to that surface. Verify once at the end (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+  When Option 1 is chosen, findings on the same page go together as one coherent change to that surface (`iamu fix-brief /path --json` for one page, or `iamu fix-brief --wave --json` across multiple pages/scenarios; `iamu fix-brief <slug>` for a single isolated finding). Check `fix_history` first so you never repeat a `recurred` approach, and keep every strength in `protect` intact. Save before and after screenshots in `shots_dir`, use `iamu design review <path> --blind` as a fast inner check when a surface has multiple or structural edits, and do not re-run persona walkthroughs between individual findings. Verify once at the end (run test/typecheck suite). Update each fixed finding with `iamu triage <slug...> --status addressed --note "<summary of fix>"`.
   Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Closed-Loop Regression Verification (1-Click):**