@iamu-dev/iamu 0.5.0-beta.0 → 0.6.0-beta.0

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

@@ -1,89 +1,83 @@
 ---
 name: iamu-design
-description: Use when setting up or updating a product's design rules, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design rules, or fixing a finding with a visual check.
+description: Use when recording where the project's design docs are, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design docs, pointing agents at the docs, or fixing a finding with a visual check.
 generatedBy: __IAMU_VERSION__
 ---
 
-Help the product's design: its interaction design at the level of one control and of a whole flow, and its look and feel. Design is led by intent and refined by evidence. The team decides what the product should be like; persona walks show where that works and where it hurts someone.
+Help the product's design: its interaction design at the level of one control and of a whole flow, and its look and feel.
 
-Personas experience; they do not design. Their walks are evidence. Design decisions come from the rules the team writes and from a designer's review of each surface.
+The design docs belong to the team. They can be in any format and at any path (a `DESIGN.md`, a section of `CLAUDE.md`, a brand guide). Iamu records which files they are, cites their rules by the names the docs give them (a heading, or the bold words that open a rule), and changes a doc only when a person accepts an exact Before → After proposal. Personas experience; they do not design. Their walks are evidence for those proposals.
+
+*The designer's review of a run looks at the screens one run's persona saw, after every run; a designer's review of a page looks at one page live, across all its visitors, when asked.*
 
 $ARGUMENTS
 
 ## 0. Where things stand
 
-Run `iamu design status --json`. It says whether `iamu/design.md` exists, where the project's own design material lives (`sources`), how many rules are `intent` (a decision not yet tested), `evidence` (persona walks back it) or `challenged` (evidence says it hurts someone), and which proposed edits are open.
+Run `iamu design status --json`. It lists the recorded design files (`files`, each with `kind`, `applies_to` and whether it `exists`), a legacy `iamu/design.md` not yet migrated (`legacy.doc` with no `legacy.migrated_at`), the open proposals (`proposals.open`, with the `stale` and `legacy` ones), and each rule anything cites, with how many runs cited it (`rules[].cited_by_runs`).
 
 Pick the mode from the user's words, or from the status when they asked generally:
 
-- no rules and no sources → **A. Set up the rules**;
+- no files recorded → **A. Record the design docs**;
+- a legacy `iamu/design.md` not yet migrated → **A3. Migrate the legacy doc** (offer it once);
 - "review this page / the request form / this finding's page / this direction" → **B. Review a surface**;
-- open proposals, or "what should change in our design rules" → **C. Decide proposed edits**;
+- open proposals, or "what should change in our design docs" → **C. Decide proposed edits**;
+- "point the agents at the design docs" → **A2. Point agents at the docs**;
 - "fix this finding" → **D. The fix loop**.
 
-## A. Set up the rules
-
-### A1. Record what the project already has
+## A. Record the design docs
 
-Run `iamu design detect --json`. It finds design docs (`DESIGN.md`, `PRODUCT.md`, design-language and interaction docs), tokens and component libraries.
+### A1. Detect, confirm once, record
 
-If it finds any, show them as a short list (kind, path, why) and ask which to record. Record the chosen ones with `iamu design sources <path…>` (it adds to what is recorded). These stay the team's documents.
+Run `iamu design detect --json`. It finds design docs in any format (`DESIGN.md`, design-system, brand, voice and interaction docs, also in a hidden folder at the top), `PRODUCT.md`, token sources and component libraries, each with a reason.
 
-When the sources already hold real rules (principles, a visual language, interaction rules), restate them as rules with ids so reviews and proposals can name them: run **A2** without the intent questions. The writer restates the team's rules faithfully, each with a `From: <path>#<section>` line, and adds nothing else. Without this step, a review's conflict with the team's own rules cannot be recorded.
+Show the candidates once as a short list (kind, path, why) and ask once which to record; the user may drop some or add others. Record the chosen ones with `iamu design sources <path…>` (it adds to what is recorded):
 
-### A2. Draft rules from intent
+- a section of a bigger file: `iamu design sources 'CLAUDE.md#Dashboard design'`;
+- a kind detection got wrong: `--kind design | product | tokens | components`;
+- in a monorepo, the part of the product a doc covers: `--applies-to /app` (URL path prefixes) or `--applies-to apps/dashboard` (an app's folder). Runs, reviews and fixes then use the right doc.
 
-When the project has no written rules (tokens and components alone are not rules), offer to draft them now. It takes a few minutes and needs no walks: design is led by intent.
+If nothing is found, say so in one line. Walks and reviews run without design docs; iamu does not write one for the team.
 
-1. Run `iamu design draft --json`, then read the file at `prompt_file_abs`: the bundle is in it (the product's context, its people, its situations, what the code already establishes). Read the `sources` it lists in full.
-2. Ask the five intent questions, one at a time, each with a suggested answer you derive from the bundle (the domain, who the people are, what the tokens and components already say). The user accepts, edits or skips each:
-   - What should using the product feel like, and for whom?
-   - Products whose look or way of working you want to be close to.
-   - Products, patterns or a look you never want.
-   - How dense and how plain-spoken, and does it differ by role?
-   - What must never happen to a person using it?
-3. Run `iamu design draft --answers '<json with keys feel, aim_for, avoid, density, never>' --json`. Dispatch a subagent (thorough tier) with the prompt file `prompt_file_abs` as its only context. It answers with the Markdown doc.
-4. Write the answer to `answer_file_abs` (from the draft result) and record it: `iamu design record --file <answer_file_abs>`. If it reports problems (a rule under an unknown heading, a missing `Source:` or `Test:`, wrong numbering), send the errors back to the writer once and record again.
-5. Show the result: the opening statement, then one line per rule (`P1 Nobody should feel stupid · intent`), grouped by layer. Every rule is `intent` until walks back or challenge it.
+### A2. Point agents at the docs
 
-### A3. Draft from evidence instead
+Offer `iamu design link-agents` (adds a short block to `CLAUDE.md` listing the recorded docs; `--file AGENTS.md` for other agents). Only with the user's yes. When the file already has an older design block, `iamu design link-agents --refresh` rewrites it, again only with a yes.
 
-When the project already has runs, the drafter can still start from intent; walks then refine it through proposals (C). Do not wait for many runs before writing rules.
+### A3. Migrate the legacy doc
 
-### A4. Point agents at the rules
+A project set up with an earlier version keeps its rules in `iamu/design.md`, with ids (`P4`) and field lines. It keeps working as it is. Offer the move once:
 
-Offer `iamu design link-agents` (adds a short block to `CLAUDE.md`; `--file AGENTS.md` for other agents). Only with the user's yes.
+1. Run `iamu design migrate --move-to DESIGN.md --json` (or the path the user prefers). It changes nothing and prints the plan: the files it would record, the old ids it keeps so older proposals still resolve, and the plain doc it would write (no iamu field lines or ids, the rules' checks gathered into a Review Checklist).
+2. Show the plan in a few lines and ask: **move it** to a plain doc the team owns, **keep** `iamu/design.md` as it is, or **later**.
+   - Move: `iamu design migrate --move-to <path> --apply`. It refuses a target that already exists.
+   - Keep: `iamu design migrate --apply`. It records the decision, so the offer is not repeated.
+   - Later: do nothing.
 
 ## B. Review a surface
 
 A surface is a page with its states and the flows through it. Review a surface, not a single finding: a page that collected eight separate fixes needs to be seen whole.
 
-1. Run `iamu design review <target> --json`. The target is a path (`/request`), a finding (its page), or a direction slug (the pages its findings are on). It writes a prompt with the surface's dossier: who passes through and what they said there, open problems with each person's need, strengths, fixes already tried and whether they held, what was dismissed, and the design rules.
-2. Dispatch a subagent (thorough tier) **with browser access** and the prompt file (`prompt_file_abs`) as its only context. It opens `target_url` + the path, signs in as the testability notes say, opens menus and states, compares with the walks' screenshots, and answers with JSON.
-3. Write the answer to `answer_file_abs` (from the review result) and record it: `iamu design review-record <target> --file <answer_file_abs>`. Show anything it reports as `rejected` or in `warnings` (a dropped proposal, an unknown rule): never let it disappear silently.
+1. Run `iamu design review <target> --json`. The target is a path (`/request`), a finding (its page), or a direction slug (the pages its findings are on). It writes a prompt with the surface's dossier: who passes through and what they said there, open problems with each person's need, strengths, fixes already tried and whether they held, what was dismissed, and the design docs that apply to the page. If it returns `warnings` (an installed prompt that differs from the shipped one), show them.
+2. Tell the user in a line or two what the reviewer looks at, from the result: the surface and its `paths`, how many visitors, open problems and strengths it weighs, and whether there are design docs to judge against. Then dispatch a subagent (thorough tier) **with browser access** and the prompt file (`prompt_file_abs`) as its only context. It opens `target_url` + the path, signs in as the testability notes say, opens menus and states, compares with the walks' screenshots, and answers with JSON. Run it in the foreground where your host allows, so its progress shows. If it runs in the background, say what it is doing while you wait, and do not end your turn with only a wait notice.
+3. Write the answer to `answer_file_abs` (from the review result) and record it: `iamu design review-record <target> --file <answer_file_abs>`. Show anything it reports as `rejected` or in `warnings` (a dropped proposal, a rule not found): never let it disappear silently.
 4. Present, in this order:
    - the summary (what the surface is for, for whom, how well it serves them);
-   - issues as a table: severity · title · evidence, observed or taste · where · rule. Taste is labelled as taste, never mixed with evidence;
+   - issues as a table: severity · title · evidence, seen or taste · where · rule it breaks. Taste is labelled as taste, never mixed with evidence;
    - **Keep** and **Change** from the brief, with whom each change serves;
-   - conflicts between a rule and a person's need, and proposed rule edits (they are now in `iamu design proposals`).
+   - conflicts between a rule and a person's need, and proposed doc edits (they are now in `iamu design proposals`; offer **C**).
 5. Offer the fix loop (D) for the changes, starting with the one that serves the most people.
 
 The review file is `iamu/design/reviews/<surface>.md`. Its issues do not count toward any scenario's verdict.
 
 ## C. Decide proposed edits
 
-Run `iamu design proposals --json`. For each open proposal, show: what it does (back rule P1, challenge L3, new behaviour rule), why (what the evidence shows), and the findings it rests on. Ask: accept, reject, or later.
-
-- `iamu design accept <slug>` applies it to `iamu/design.md`: a backed rule becomes `evidence`, a challenged rule is marked `challenged` with the reason and a proposed wording, a new rule is added as `evidence`.
-- `iamu design reject <slug>`: it is not proposed again.
-
-Accepting a **challenge** marks the rule `challenged`, with the reason and the proposed wording; the rule stays in force until a person rewrites it. Right after accepting one, show the proposed wording and offer to apply it now: edit the rule in `iamu/design.md` (new wording and test, `Source: intent`, remove the `Challenged:` and `Proposed:` lines), then record it with `iamu design record --file <project root>/iamu/design.md`.
+Run `iamu design proposals --json` and decide each open proposal exactly as the `iamu-findings` skill describes under "Then the proposed edits to the design docs": show its Why, the rule and file it changes, the findings it rests on, and Before → After, then ask accept, edit After then accept, reject, or later. It lists open proposals first, then stale ones (with why: the Before is gone, or occurs on several lines), then legacy ones; `--all` adds decided ones.
 
 ## D. The fix loop
 
 Fix by looking, not by hoping. For one finding:
 
-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 with their tests, 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.
+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.
@@ -91,7 +85,8 @@ Fix by looking, not by hoping. For one finding:
 ## Guidelines
 
 - **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
-- **The project's rules come first,** then platform conventions and accessibility, then general craft. Never invent a style the team has not chosen.
-- **Evidence and taste stay labelled.** Both are useful; only evidence moves a rule.
+- **The project's docs come first,** then platform conventions and accessibility, then general craft. Never invent a style the team has not chosen.
+- **The docs are the team's.** Change one only through an accepted proposal, never by hand on iamu's initiative.
+- **Evidence and taste stay labelled.** Both are useful; only evidence proposes a change to the docs.
 - **A rule that hurts someone is reported, not silently broken or silently followed.** A person decides.
 - **Prefer removing, merging and hiding by role to adding.**

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

@@ -1,6 +1,6 @@
 ---
 name: iamu-findings
-description: Use when triaging, reviewing, listing, or resolving findings, bugs, UX friction, or issues discovered during walkthroughs, or when the user asks "what broke?", "show findings", or "review issues".
+description: Use when triaging, reviewing, listing, or resolving findings (what personas experienced and what the designer saw), bugs, friction, or issues discovered during walkthroughs, or when the user asks "what broke?", "show findings", or "review issues".
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -61,21 +61,27 @@ 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`, `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. 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: 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.
 
 Filter to `triage_status: open`.
 
 **Fixed is not proven.** `triage_status: addressed` means a fix was applied. `iamu findings --json` adds `fix_state` to each addressed finding, derived from local runs:
 
-- `awaiting_rerun` — no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `awaiting_rerun` — a persona finding: no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `awaiting_review` — a designer finding: no designer's review of its page since the fix. A re-run's designer's review checks it, or a page check (below).
 - `verified` — a run that started after the fix saw it working (the since-last-run delta's "Resolved", backed by steps).
 - `recurred` — a run after the fix recorded it again: the fix did not hold. Reopen it (`iamu triage <slug> --status open`).
 
-A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
+A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. The eye that raised a finding confirms it: a re-run confirms the persona's findings, a designer's review the designer's; never the other way round.
+
+**Checking whether something is fixed, on request.** When the user asks in plain words ("is the pending colour fixed?", "check the approvals page"), find the findings meant and route by `source`:
+- **A designer finding:** check its page. Run `iamu design review <page> --blind` and have a fresh reviewer with a browser answer it (it is not told which findings were open: the check is blind), record it with `iamu design review-record <page> --file <answer>`, then `iamu design review-match <page> --json`; give its prompt to a fresh agent and record with `iamu design review-match-record <page> --file <answer>` (when it says `nothing_new`, record `--data '{"matches":[]}'`). Report what is still there and what was not seen again. While the result says `provisional: true`, say "not seen again (provisional)" and never "fixed": the check is not trusted yet.
+- **A persona finding:** a screenshot cannot say whether the person still gets stuck. Offer a re-run of the scenario that raised it (`iamu-run <scenario>`).
+- **A persona finding with design causes:** the re-run decides; a page check of its design cause is supporting evidence only. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
 
 **Directions before findings.** Run `iamu directions --json`. Directions are structural changes the advisor proposed after a walk, each absorbing several findings (sometimes across scenarios), with the people it could hurt and the scenarios to re-run. If any are `proposed` or `accepted`, show them above the tally, one line each: `◆ <title> (<size>, <status>) · absorbs <N> findings in <S> scenarios · could hurt: <scenarios or "none predicted">`. Offer them first: taking a direction fixes its findings together, which beats patching them one by one. For each the user can **take it** (`iamu directions set <slug> --status accepted`, then implement it, or hand it to planning when it is `large`), take **only the local fixes** (leave it `proposed`, triage its findings below), **defer**, or **reject** (`--status rejected`; it is never proposed again). When a taken direction is implemented, mark it `done` and offer `iamu-run` for every scenario in its `verify` list. Reach is a prediction: say "likely" and "could", never "will".
 
-**Design rule proposals.** Run `iamu design proposals --json`. Open ones are edits the advisor or a design review proposed to the design rules (back a rule, challenge one that hurts a persona, add one for a recurring problem). Show them after the directions, one line each, and offer to decide them (accept applies the edit, reject is final). When several open findings sit on one page, offer a design review of that page (`iamu-design`, review a surface) before fixing them one by one.
+**Design doc proposals.** Run `iamu design proposals --json` and note the open ones: edits the advisor, the designer (after a run, or reviewing a page) or a design review proposed to the project's design docs (a rule whose application hurt someone, or something the docs do not cover). They are decided after the findings (step 5), next to the evidence that raised them. When several open findings sit on one page, offer a design review of that page (`iamu-design`, review a surface) before fixing them one by one. *The designer's review of a run looks at the screens one run's persona saw, after every run; a designer's review of a page looks at one page live, across all its visitors, when asked.*
 
 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.
 
@@ -90,7 +96,7 @@ Render it as Markdown, not inside a code fence, so the tables render. Start with
 |---|---|---|---|---|
 | 1 | <title> | **Critical** | <where> | <first sentence of recommendation, or — > |
 
-Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → observation; 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).
+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).
 
 Ask the user how they would like to triage:
 
@@ -234,6 +240,8 @@ When all findings in the queue are triaged, present what was decided, one row pe
 | 3 | <title> | Defer | Revisit after the next run |
 | 4 | <title> | Dismissed | <reason>; guidance `<slug>` taught to future walks |
 
+**Then the proposed edits to the design docs.** For each open proposal from `iamu design proposals --json`, show its Why, the rule and file it changes, the findings it rests on, and the change as two short `text` blocks, Before then After. Ask: **accept** (`iamu design accept <slug>`: it replaces exactly the Before in the doc with the After), **edit After then accept** (change the After block in `iamu/design/proposals/<slug>.md` to the user's wording first), **reject** (`iamu design reject <slug>`), or **later**. A `stale` proposal, or an accept that stops with `before_not_found`, is offered only as edit (rewrite its Before to the doc's current text and its After to match, then accept) or reject. One marked as legacy (the earlier format) can only be rejected, or left for a later run to raise again. Never accept one on the user's behalf.
+
 If `<N> > 0` findings were queued for fix:
 - Prompt the user:
   - If interactive tool available:

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

@@ -12,6 +12,8 @@ This skill resolves what scenario to run following a clear **Target Scenario Res
 2. **Active conversational context:** When `$ARGUMENTS` is empty or generic (e.g. "it", "that", "this", "run it", "walk it", "go"), and a scenario was created, modified, staged, or discussed in the active session — immediately resolve to that active scenario without prompting or re-scanning.
 3. **No argument & No active session scenario:** Check unfinished runs, then present a prioritized pickable list (reruns needing proof first, then drafts and ready-to-run).
 
+**`--no-ux`:** when `$ARGUMENTS` contains `--no-ux`, take it out before resolving the scenario and skip the designer's review (step C3) for this run only: after A, record `iamu designer-record <run-id> --skipped "--no-ux"` so the report says it was skipped. There is no project setting for it: every other run gets a designer's review.
+
 $ARGUMENTS
 
 ## Prerequisites
@@ -264,7 +266,7 @@ The result's `walker_prompt` is the walker's entire prompt (also persisted at `w
 
 A fresh subagent is NOT blind by default. On most hosts it still loads the project's agent instructions and can read files in the repo, so it may know the domain model, the route table, and why a screen was built the way it was — none of which the persona knows. The methodology's "Stay outside the product" rule is what keeps it honest; it is part of `walker_prompt` — never remove or soften it.
 
-**Subagent Capability Fencing (Superpowers Pattern):**
+**Subagent capability fencing:**
 - **Tool Whitelist:** If the host allows tool restriction, grant the walker ONLY the browser driving tools (`iamu browse` or browser MCP) and read-only inspection.
 - **Tool Blacklist:** Strictly strip file write/edit tools (`write_to_file`, `replace_file_content`, patch/edit tools, and source git commits). The walker is an observer, never a developer.
 - **Child Session Suppression:** The walker must never execute parent workflow routines (`iamu init`, `iamu triage`, `iamu new`). All steps, findings, and summaries are recorded atomically via `iamu browse step`, `iamu new-finding`, and `iamu summary`.
@@ -338,7 +340,7 @@ iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type h
 This generates a valid UUID, derives the slug from the title, and writes the complete finding file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`. Never invoke host Edit or Write tools.
 
 Valid `--type` values: `helps`, `hinders`, `missing`, `irrelevant`, `incorrect`.
-Valid `--severity` values: `critical`, `major`, `minor`, `observation`.
+Valid `--severity` values: `critical`, `major`, `minor`, `nit`.
 Valid `--task-impact` values (effect on the persona's task): `blocks`, `impairs`, `slows`, `neutral`, `accelerates`, `enables`. A `helps` finding is never `blocks`/`impairs`/`slows`; a problem is never `accelerates`/`enables`.
 Valid `--confidence` values: `high`, `medium`, `low` (use `low` when it may be a tooling limitation).
 
@@ -354,7 +356,7 @@ iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --questi
 
 **Post-walk pipeline (MANDATORY — do NOT skip any step):**
 
-After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order.
+After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order; the designer's review (C3) starts right after A and runs beside them.
 
 > **CRITICAL EXECUTION RULE (Zero Host File Tools):**
 > Never invoke host edit or write tools (`write_to_file`, `create_file`, `replace_file_content`, etc.) on any files in `iamu/` (including run artifacts, steps, findings, outlines, personas, scenarios, or guidance). All files in `iamu/` must be generated and modified exclusively via `iamu` CLI commands (`iamu new`, `iamu set`, `iamu step`, `iamu new-finding`, `iamu evaluate-record`, `iamu match-record`, etc.). If an entity needs a field updated (e.g. adding a capability to an outline), run `iamu set <type> <slug> ...` instead of editing files by hand. Record subagent JSON outputs directly through the CLI using `--data '<json>'` (or pipe via stdin).
@@ -413,6 +415,22 @@ Each entry is checked on its own. Entries that come back rejected (an invented f
 
 The judge (C) and the advisor (C2) are independent, so their subagents may run in parallel, but run `evaluate-record` and `advise-record` one after the other: both rewrite finding files. On a host without subagents, run the advise prompt yourself inline and record it the same way.
 
+**C3. Designer's review.** For every run (unless `--no-ux` was given), start it as soon as A is done:
+
+```bash
+iamu designer <run-id> --json
+```
+
+If `needed` is `false` (`reason` is `blocked`, `no_screens` or `already_recorded`), skip it. Otherwise dispatch a fresh subagent that can look at images (the **thorough** model tier) with `iamu/.runs/<run-id>/designer_prompt.md` as its only context, alongside the matcher (B), the judge (C) and the advisor (C2) where the host allows. It reviews the screens the persona saw as the product's designer would: against the project's design docs when they apply to this run (`judged_against: design-docs`), else against general craft, across the whole screen. What it finds are designer findings: judgement, never the persona's experience, and never counted with the persona's findings or in the verdict.
+
+Nothing waits for it: the advisor never waits for the designer, and D and E go ahead without it. When its answer arrives, record it:
+
+```bash
+iamu designer-record <run-id> --data '<raw_designer_json>'
+```
+
+Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals` for step 5.
+
 **D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including the verification delta (if a prior run exists) and `analysis.directions` (if the advisor ran). Use this for step 5 presentation.
 
 **E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
@@ -431,7 +449,7 @@ It prints the URL only if the run is on the cloud; otherwise it exits 1 and says
 
 In linked-no-credentials or local-only mode, skip E.
 
-Only after A→E (with C2) are complete, proceed to step 5.
+Only after A→E (with C2) are complete, proceed to step 5. If the designer has returned by then, record it first; if not, present without it and add the designer's review when it lands. If it lands after E, run `iamu sync --json` once more so the cloud report carries it.
 
 ### 4a. Walk methodology summary
 
@@ -473,7 +491,7 @@ For a persisting finding, put its qualifiers in brackets: the `shift` ("less sev
 |---|---|---|---|---|
 | 1 | <title> | **Major** | <where> | <first sentence or two of recommendation, or — > |
 
-Mark a finding that persists from the last run with `(persists)` after its title. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
+Mark a finding that persists from the last run with `(persists)` after its title. When the designer gave a finding's design cause (a `summary.designer.issues` entry whose `design_cause_of` is that finding's `id`), add it under the row as `↳ Design cause (designer, <basis>): <what>`. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
 
 If `summary.directions` is non-empty:
 
@@ -485,9 +503,14 @@ If `summary.directions` is non-empty:
 
 Reach is a prediction until those scenarios run again.
 
-If `summary.observations` is non-empty, end with **Also worth knowing**: one bullet each, `Not walked: <title>` (coverage_gap) or `Risk: <title>` (feature_risk).
+If `summary.designer` is set, add the **Designer's review**: the designer's judgement of these screens, never the persona's experience. Give its count apart from the persona's ("2 designer findings"), never one total.
+- One line on what it was judged against: the design docs in `summary.designer.design_files`, or, when `judged_against` is `general-craft`, `Judged against general craft: recording the project's design docs makes this review sharper`, followed by the `hint` command `iamu designer` printed. Say so when `dispatch` is `inline` ("written by the orchestrator, less independent").
+- The rule breaks (`summary.designer.rules_broken`), one line each: `"<rule>" (<file>) on <screen>, step <n>`, then `<rules_held> rules held`.
+- The major and critical designer findings that are not a design cause (`summary.designer.issues` with no `design_cause_of`), one line each: `<id> · designer · <severity> · <basis> · <screen> · <title>`, with `breaks "<rule>"` when it breaks one; then the count of minor and nit ones in one line.
+
+If `summary.observations` is non-empty, end with **Also worth knowing** (the advisor's notes): one bullet each, `Not walked: <title>` (coverage_gap) or `Feature risk: <title>` (feature_risk).
 
-If the advise step proposed design rule edits (`design_proposals` in its result), add one line: `Design rules: <N> proposed edits (back / challenge / new) — iamu-design to decide`. They wait for a person; never apply them yourself.
+If the advise step or the designer proposed design doc edits (`design_proposals` in the advise result, `proposals` in the designer result), add one line: `Design docs: <N> proposed edits — decided after the findings`. They wait for a person; never apply them yourself.
 
 If `summary.setupNotes` is non-empty, add **Test setup** with one bullet each. These are doubts about the test, not the product (missing data, an account that cannot see enough, a date the scenario assumes). Offer the `iamu-stage` skill to fix the setup before the next run; a finding that rests on a setup doubt may not be real.
 
@@ -498,7 +521,7 @@ Do NOT prompt the user with a generic "How would you like to proceed?" multiple-
 
 - **If `summary.findings` is empty (no problems):**
   Output: "No problems found in this run." The verdict above still stands on its own: a run without findings can still answer NO.
-  Do not enter triage.
+  Do not enter finding triage for the persona; when the designer's review has major or critical designer findings, triage those (step 6 lists them the same way), then the proposed design doc edits.
 
 - **If `summary.findings` is not empty:**
   Output the Executive Scorecard above to chat FIRST, and advance IMMEDIATELY to triage on **Finding #1 of <total>** (Step 6 below) in the same turn. The user can choose to queue to fix, queue all remaining fixes (batch accept), dismiss, or discuss directly from Finding #1.
@@ -513,6 +536,8 @@ The conversation is the triage surface. Do NOT eject the user to manual CLI comm
 - **Defer** (leave `proposed`) or **reject** (`iamu directions set <slug> --status rejected`; it will not be proposed again).
 After a taken direction lands, mark it `done` and re-run the scenarios in its `verify` list, not only this one.
 
+**One list, worst first.** Triage goes through one list: every persona problem finding, and the designer findings at `major` or above that are not a design cause, ordered by severity (critical, major, minor, nit), persona before designer at equal severity. A persona finding and its design causes are one card and one decision. Number the cards across the whole list ("#3/7"). Every card opens with whose finding it is: "**Ana found:**" for a persona finding, "**The designer found (<basis>):**" for a designer finding. Severity means harm to the person for both.
+
 #### A. Guided One-by-One Review ("walk through them" / "review one by one")
 When the user asks to review findings one by one:
 1. **Present Finding #N in a scannable format (High Visual Hierarchy):**
@@ -532,6 +557,18 @@ When the user asks to review findings one by one:
    ```
    *(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
 
+   When the persona finding has design causes, add under the problem: `**↳ Design cause** (<id>, the designer, <basis>): <what> <why>` and `breaks "<rule>"` when it breaks one. It is decided with the finding.
+
+   A designer finding's card:
+   ```markdown
+   ### Finding #<N>/<total> [<SEVERITY>] — <title> · designer
+   > **The designer found (<basis>):** on `<screen>` (Step <N>) · <breaks "<rule>" (<file>) when set>
+   > **Evidence:** <run_dir>/screenshots/step-<N>.png
+
+   **What the designer saw:** <what> <why>
+   ```
+   Never write it in the persona's voice, never quote the persona for it, and say "taste" plainly when its basis is taste.
+
    If the project is cloud-linked, include the direct link to the walkthrough in Iamu Cloud (from `iamu open <run-id> --print`).
 
    Followed immediately by the decision prompt:
@@ -591,6 +628,9 @@ When the user asks to review findings one by one:
    ```text
    Triage Complete: <K> queued for fix, <D> dismissed, <O> kept open/deferred.
    ```
+   A designer finding is decided with the same choices: **queue to fix** (fixed from `iamu fix-brief <run-id>#D<n> --json` and its `loop`; the next designer's review of that screen shows whether it held), **dismiss** (`iamu designer-dismiss <run-id> D<n> --reason "<why>"`: later reviews do not raise it again unless it gets worse, and no rule is taught to the walker), or **later** (record nothing; it stays in the report). Minor and nit designer findings stay in the report and are not offered.
+
+   **Then the proposed edits to the design docs**, before any fixes: decide each open one exactly as the `iamu-findings` skill describes under "Then the proposed edits to the design docs" (Why, the rule and file, the findings, Before → After; accept, edit After then accept, reject, or later). Never accept one on the user's behalf.
    If `<K> > 0` (findings are queued for fix):
    - Prompt the user to execute the batch:
      - If interactive tool available:
@@ -604,7 +644,7 @@ When the user asks to review findings one by one:
        Proceeding with code fixes — say "re-run first" or "done for now" to adjust.
 
    - **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); findings on the same page go together as one change. 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, 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); findings on the same page go together as one change. Queued designer findings are fixed the same way from `iamu fix-brief <run-id>#D<n>`; mark each by the `finding.slug` its brief gives (a later designer's review of that screen confirms it, not the re-run). Verify once at the end (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
      Tell the user: "✓ Applied fixes for <K> findings. All marked addressed."
 
    - Run `iamu validate --all`.

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

@@ -14,7 +14,7 @@ What this skill does, end to end:
 - **Understand** — read the repo automatically to detect dev server, mock fixtures, external boundaries, domain stakes, and user roles.
 - **Step 1: Safety & Testability Fence** — agree on the sandbox boundaries (`iamu/testability.md`) so the autonomous browser agent never leaks data or hits real external services.
 - **Step 2: Project Domain & Description** — verify domain context and project description (`iamu/context.yml`) to ground UX evaluations.
-- **Design rules (skippable)** — record the design docs the project already has, or draft rules from intent (`iamu/design.md`).
+- **Design docs (skippable)** — record where the project's own design docs are (`iamu/design/sources.json`).
 - **Step 3: Co-Design First Journey** — co-create a high-friction scenario, verify auth preconditions (`personas/`, `outlines/`, `scenarios/`), and validate.
 - **Next Action** — copy-pasteable command to launch your first walkthrough.
 - **Cloud (optional)** — link to Iamu Cloud if you want to share findings with your team.
@@ -162,6 +162,10 @@ Explain the purpose of project context: traditional tests only assert button cli
 
 Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys.
 
+**Describe the product, not the environment you explored.** Persona drafting and the advisor read these fields and the description as the truth about the product. Write them as the product its people use in their real work. Leave out everything about how this copy runs, because Step 1 already recorded it in `testability.md`:
+- **Data and build:** seeded, mocked, fixture, sample or fake data; demo, prototype or staging status; where data is stored; frontend or backend architecture; dev servers.
+- **Seed numbers:** headcounts, named teams, stores or sites, and record counts taken from seed or fixture files describe the test data, not the customers. Say who the product is for in general terms ("small and mid-sized companies"). Rules and policies the code enforces (a notice period, an approval threshold) are product behaviour; keep them.
+
 **Dual-Surface Prompting (Sequencing Rule):**
 You MUST output the domain context and project description to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the complete substantive project description embedded in the `question` argument so the reviewer can read the full text directly within the dialog modal:
 
@@ -220,7 +224,7 @@ Persist the domain context using `iamu set context` (never invoke host file crea
 iamu set context \
   --domain "<domain>" \
   [--industry "<industry>"] \
-  --body "<The substantive 1–2 paragraph project description and core user workflows>" \
+  --body "<The 1-paragraph project description, as confirmed>" \
   --json
 ```
 
@@ -229,14 +233,15 @@ iamu set context \
 
 ---
 
-### 4b. Optional: design rules (quick, skippable)
+### 4b. Optional: design docs (quick, skippable)
 
-Design is led by intent: the product's design rules are part of its context, like the domain. Run `iamu design detect --json`.
+The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json`.
 
-- **Found design docs** (`DESIGN.md`, a design language, interaction principles): list them in one line each and ask whether to record them as the project's design rules. On yes, `iamu design sources <paths…>`. Iamu points at them; they stay the team's documents.
-- **Only tokens or components, or nothing:** say in one line that the project has no written design rules, and offer to draft them from intent now (five short questions, each with a suggested answer) or later. Now: follow **A2** of the `iamu-design` skill, then continue with Step 3/3 below. Later: mention `iamu-design` in the completion handoff.
+- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (tokens in a template, export or fixture folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
+- **A legacy `iamu/design.md`** (`iamu design status --json` shows `legacy.doc` and no `legacy.migrated_at`): fold it into the same single question. Run `iamu design migrate --json` first, and offer three answers next to the files: **move it** to a plain `DESIGN.md` the team owns (`iamu design migrate --move-to DESIGN.md --apply`), **keep** `iamu/design.md` as it is (`iamu design migrate --apply`, which records the choice so it is not offered again), or **not now** (run nothing; it is offered again next time). Only an explicit "keep" runs `--apply` without a move.
+- **Nothing found:** say so in one line and continue. Walks run without design docs.
 
-Never block setup on this. Skipping it is fine; walks still run, and the rules can come any time.
+Do not assess or draft design docs here. Never block setup on this step.
 
 ---
 
@@ -337,7 +342,7 @@ Render the output:
   iamu/
   ├── testability.md       [safety fence active: <target_url>]
   ├── context.yml          [domain: <domain>]
-  ├── design.md            [<N> design rules · <sources>]   (only when recorded)
+  ├── design/sources.json  [<N> design docs]   (only when recorded)
   ├── personas/
   │   └── <persona-slug>.md
   ├── outlines/
@@ -353,7 +358,7 @@ Next step:
 Other commands when you're ready:
 • iamu-new      Draft a scenario for a different product flow
 • iamu-propose  Brainstorm high-risk workflows and blind spots
-• iamu-design   Write or review the product's design rules (when none were recorded)
+• iamu-design   Record the project's design docs, review a page, decide proposed edits
 • iamu doctor   Diagnose test environment and target health
 <If cloud_linked: true>
 • iamu sync     Sync completed runs and findings to Iamu Cloud

package/dist/templates.d.ts

@@ -9,9 +9,15 @@ export declare function getTemplatesRoot(): string;
 export declare function getTemplateDir(subdir: "skills" | "prompts"): string;
 export declare function getTemplateFile(subdir: "skills" | "prompts", filename: string): string;
 /** Prompt templates `iamu init` installs and `iamu update` refreshes in `iamu/.prompts/`. */
-export declare const PROMPT_FILES: readonly ["walk.md", "persona.md", "outline.md", "combine.md", "complete.md", "evaluate.md", "advise.md", "design-draft.md", "design-review.md"];
+export declare const PROMPT_FILES: readonly ["walk.md", "persona.md", "outline.md", "combine.md", "complete.md", "evaluate.md", "advise.md", "design-draft.md", "design-review.md", "design-review-match.md", "designer.md"];
 /**
  * A prompt as the project has it: its `iamu/.prompts/<name>` copy (which
  * a team may tune), else the bundled template.
  */
 export declare function readInstalledPrompt(projectRoot: string, name: (typeof PROMPT_FILES)[number]): string;
+/**
+ * A warning when the project's `iamu/.prompts/<name>` differs from the
+ * bundled template: answers written from an older method may cite rules
+ * by id or propose in an old format. Null when it matches or is absent.
+ */
+export declare function installedPromptWarning(projectRoot: string, name: (typeof PROMPT_FILES)[number]): string | null;

package/dist/ui/html-report.d.ts

@@ -1,4 +1,4 @@
-import { type CheckOutcome, type RunChecks } from "@iamu-dev/local-store";
+import { type CheckOutcome, type RunChecks, type CanonicalAnalysis, type CanonicalDesigner } from "@iamu-dev/local-store";
 export interface HtmlReportHighlight {
     targetBox: {
         x: number;
@@ -38,6 +38,10 @@ export interface HtmlReportFinding {
     title: string;
     type: string;
     severity?: string | null;
+    /** What the walker filed, when the advisor's check changed the severity. */
+    filedSeverity?: string | null;
+    /** Why the advisor changed it. */
+    severityWhy?: string | null;
     uiFact?: string | null;
     consequence?: string | null;
     recommendation?: string | null;
@@ -102,6 +106,10 @@ export interface HtmlReportData {
         }>;
         directions: string[];
     } | null;
+    /** The designer's review; never counted with the persona's findings. */
+    designer?: CanonicalDesigner | null;
+    /** The advisor's directions and notes, when the run was advised. */
+    analysis?: CanonicalAnalysis | null;
 }
 export declare function generateHtmlReport(data: HtmlReportData): string;
 /**

package/dist/ui/report-view.d.ts

@@ -1,9 +1,12 @@
+import { type CanonicalDesigner } from "@iamu-dev/local-store";
 export type VerdictLabel = "YES" | "PARTIAL" | "NO" | "PENDING" | "BLOCKED";
 export interface RunFindingRow {
     id: string;
     /** Finding file slug, for `iamu triage <slug>`; null when the file is gone. */
     slug: string | null;
     severity: string | null;
+    /** What the walker filed, when the advisor's check changed the severity. */
+    filedSeverity?: string | null;
     type: string;
     title: string;
     where: string | null;
@@ -18,6 +21,8 @@ export interface RunView {
     situation: string;
     completedAt: string | null;
     steps: number;
+    /** How the walk ended (reached the goal, or stopped and why); null when blocked. */
+    ending?: string | null;
     targetUrl: string | null;
     /** Cloud link, or a note that the run is not synced; null when not linked. */
     cloud: string | null;
@@ -69,6 +74,8 @@ export interface RunView {
     } | null;
     /** The walker's doubts about the test setup. */
     setupNotes: string[];
+    /** The designer's review; null or absent without one. Never counted with findings. */
+    designer?: CanonicalDesigner | null;
 }
 export interface OverviewRun {
     completedAt: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.5.0-beta.0",
+  "version": "0.6.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -68,8 +68,18 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "eval:walkthroughs": "vitest run --config vitest.benchmark.config.ts",
-    "eval:gemini": "node .eval-dist/gemini-eval-cli.js",
+    "eval:walkthroughs": "node ../../scripts/paid-eval-guard.mjs && vitest run --config vitest.benchmark.config.ts",
+    "eval:gemini": "node ../../scripts/paid-eval-guard.mjs && node .eval-dist/gemini-eval-cli.js",
+    "eval:setup-context": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/setup-context.yaml --no-cache --repeat 3",
+    "eval:design-draft": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/design-draft.yaml --no-cache --repeat 2",
+    "eval:walker-severity": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/walker-severity.yaml --no-cache --repeat 3",
+    "eval:design-guide-apply": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/design-guide-apply.yaml --no-cache --repeat 3",
+    "eval:advisor-check": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/advisor-check.yaml --no-cache --repeat 2",
+    "eval:ux-judge": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge.yaml --no-cache --repeat 10",
+    "eval:ux-judge-heldout": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-heldout.yaml --no-cache --repeat 5",
+    "eval:ux-judge-counter": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-counter.yaml --no-cache --repeat 5",
+    "eval:ux-judge-ablations": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-ablations.yaml --no-cache --repeat 5",
+    "eval:designer-check": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/designer-check.yaml --no-cache --repeat 10",
     "pack:dry-run": "npm pack --dry-run"
   }
 }