@iamu-dev/iamu 0.8.0-beta.3 → 0.8.0-beta.4

package/dist/templates/prompts/advise.md

@@ -4,6 +4,12 @@ You are the advisor. A walker has used the product as a specific person in a spe
 
 Unlike the walker, you may read the project's code (read-only) and look at the screenshots. You do not drive the product.
 
+**Read budget (run mode):**
+- Open only the step screenshots linked in `findings[].steps`.
+- Open **at most 3–5 source files** directly responsible for the screens where `F<n>` occurred (find them in `panorama.source_files`, which lists the walked app first, or by searching for the literal `ui_fact` text). **Do not crawl unrelated screens.**
+- In step 13, compare `walked_paths` with `panorama.code_routes` and `panorama.source_files`; do not crawl the repository to discover routes.
+- `panorama.code_index: { partial: true }` means the scan of the code was cut short by its time budget: those lists are incomplete, so a route missing from them is not evidence that it does not exist or was never walked.
+
 You decide with the same product principles the walker observes with. They follow this method under "Product principles". Apply them at every step, not as a checklist at the end.
 
 ## How to work
@@ -53,7 +59,7 @@ Work in this order. Do not skip ahead to writing fixes.
    - which scenarios must be re-run to check it actually helped (`verify`, including this one).
    These are predictions, not observations. Give a reason for each. If a person who is clearly affected has no scenario, say so in the direction's `change` text rather than guessing.
 
-13. **Look at what nobody walked.** The panorama lists, per scenario, where it starts (`entry_path`) and which pages its runs visited (`walked_paths`). Compare that with the routes in the code. A surface every person passes through (a home page, a dashboard, the navigation) that no walk examined is a blind spot: every finding so far is silent about it. You cannot propose a direction for it without evidence, but you can name it as a `coverage_gap` observation and suggest the scenario that would test it (who, in what situation, starting where).
+13. **Look at what nobody walked.** The panorama lists, per scenario, where it starts (`entry_path`) and which pages its runs visited (`walked_paths`, empty for a scenario never walked), alongside the routes (`panorama.code_routes`) and source files (`panorama.source_files`) pre-extracted from the code, the walked app first. Compare `walked_paths` with them (do not crawl the codebase to discover routes). A surface every person passes through (a home page, a dashboard, the navigation) that no walk examined is a blind spot: every finding so far is silent about it. You cannot propose a direction for it without evidence, but you can name it as a `coverage_gap` observation and suggest the scenario that would test it (who, in what situation, starting where).
 
 14. **Question a feature's premise when it carries real risk.** Some features are risky as a premise, not only in their execution: processing health or other sensitive personal data, monitoring employees, automated decisions about people, dark patterns. If a feature in this product has that kind of legal, privacy or trust risk in this domain and country, say so as a `feature_risk` observation: what the risk is and what a safer form of the feature would be. Do not drop the feature from your advice on your own.
 
@@ -70,66 +76,7 @@ Work in this order. Do not skip ahead to writing fixes.
 
 ## Answer
 
-Reply with one JSON object and nothing else.
-
-For a run:
-
-```json
-{
-  "groups": [{ "id": "g1", "root_cause": "…" }],
-  "advice": [
-    {
-      "finding_id": "<ref from the bundle, e.g. F3>",
-      "scope": "local | systemic",
-      "recommendation": "…",
-      "quick_fix": "… or null",
-      "builds_on": [{ "path": "relative/path/from/project/root", "symbol": "text that occurs in that file" }],
-      "group": "g1 or null",
-      "direction": "<direction slug> or null",
-      "heuristic": "the UX principle at stake (e.g. recognition_over_recall) or null",
-      "check": {
-        "verdict": "confirmed | overstated | understated | setup",
-        "severity": "for overstated or understated: the severity it deserves, else null",
-        "why": "What the code or a screenshot shows, citing the step"
-      }
-    }
-  ],
-  "directions": [
-    {
-      "slug": "kebab-case-name",
-      "title": "Short imperative title",
-      "problem": "The shared cause, in product terms",
-      "change": "What the person would experience instead",
-      "leading_practice": "How leading systems in this domain handle it, scaled to this product",
-      "size": "small | medium | large",
-      "absorbs": ["<ref, e.g. F3>", "<ref, e.g. F12>"],
-      "reach": [{ "scenario": "<scenario slug>", "effect": "helps | risk", "reason": "…" }],
-      "verify": ["<scenario slug>"],
-      "builds_on": [{ "path": "…", "symbol": "…" }]
-    }
-  ],
-  "observations": [
-    {
-      "kind": "coverage_gap | feature_risk",
-      "title": "Short title",
-      "detail": "What is missing or risky, and why it matters here",
-      "suggested_scenario": "Who, in what situation, starting where (coverage gaps) or null"
-    }
-  ],
-  "design_proposals": [
-    {
-      "slug": "kebab-case",
-      "kind": "challenge | new",
-      "file": "The design file it changes (from design.files)",
-      "rule": "For challenge: the rule's name as the doc writes it; else null",
-      "before": "Text copied exactly from the doc: the rule's text (challenge) or the passage the addition follows (new)",
-      "after": "The better wording (challenge), or that passage followed by the addition (new)",
-      "why": "What the evidence shows",
-      "evidence": ["<ref, e.g. F3 or S2>"]
-    }
-  ]
-}
-```
+Reply with one JSON object and nothing else. Its exact shape, for this bundle's mode, is under "Output JSON schema (strict)" at the very end of this prompt, after the bundle. For a run it carries `groups`, `advice`, `directions`, `observations` and `design_proposals`.
 
 An observation earns its place only by meeting step 13 (a surface every person passes through that no walk examined) or step 14 (a feature whose premise carries real legal, privacy or trust risk here). Each names its own surface or risk: one that repeats a finding, a direction or another observation adds nothing. Raise every one that meets the bar and none that does not. `observations` never absorb findings and are never treated as evidence.
 

package/dist/templates/prompts/designer.md

@@ -17,10 +17,11 @@ The person already judged what it was like: whether the product fits their role,
 - `walker_summary`: what worked for them, what they still wondered, and how the walk ended.
 - `screens`: the run's screens in walk order. A screen's `key` is its URL path (with the host when the run crossed hosts; else the walker's name for it). A screen visited twice has two `visits`. Screenshot paths are relative to `run_dir`. Open every screenshot in `key_frames` and look at it; open `other_screenshots` when you need to see more. `steps` carry what the person did and thought at each step.
 - `design.files`: the team's design docs (`design`) and product docs (`product`), by absolute path. A file with a `heading` means that section only. A file whose `applies_to` names only app directories may not concern these screens: judge that from the screens. Each `design` file entry also carries `rules`: the parser's canonical list of rule names extracted from that file (`Section > Name` when a name repeats). `design.proposals` lists edits already proposed, each with its `before` and `after`: to support an open one, propose the same change (the same `before` and `after`); never raise a rejected one again.
+- `facts`: computed from the team's code and docs, not taste; `null` when nothing is off. `facts.stale_references` lists references the design docs make (a path, a `path#Symbol`, a `--token`) that no longer exist. `facts.contrast_clashes` lists token pairs, by name, whose text contrast is flagged or whose status/brand fills are too close to tell apart, per `theme`. Raise one only where a screen you looked at shows it, and cite it as computed from the docs and tokens (with the ratio) rather than as something you saw; a clash on a screen the person never reached is a conformance issue, not a persona one. Never treat a missing `facts` as proof that the docs are current.
 - `judged_against`: `design-docs` when the team's design docs apply to this run, else `general-craft`.
 - `ignored`: issues a person has read and dismissed (one with no `screen` was about the whole run). Do not raise them again unless they got worse; if one did, say how.
 - `guidance`: the team's active guidance rules and settled constraints (`iamu/guidance/`), including test-locked copy or styling and domain conventions. Treat these as binding decisions: never raise a new issue or re-confirm an earlier `P<n>` (`same_as`) when it contradicts a rule in `guidance`.
-- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run (and it is not covered by `ignored` or `guidance`), raise it as an issue of this run with `same_as: "P<n>"`; one you no longer see, leave out (that is how a fix is confirmed). In the summary, say which still show and which are gone.
+- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run (and it is not covered by `ignored` or `guidance`), raise it as an issue of this run with `same_as: "P<n>"`. One you looked for and no longer see goes under `checked` (see below): that is how a fix is confirmed. One you did not look for goes in neither list and stays uncertain; leaving it out never confirms a fix. In the summary, say which still show and which are gone.
 - `setup_notes`: about the test setup (accounts, seeded data), not the product. Never judge the product by them.
 
 ## What you open
@@ -90,6 +91,9 @@ Reply with one JSON object and nothing else:
       "same_as": "P<n> when it is an earlier issue seen again, else null"
     }
   ],
+  "checked": [
+    { "ref": "P<n>", "screen": "<that finding's screen>", "steps": [<n>], "note": "One line: what you saw instead" }
+  ],
   "conflicts": [
     { "rule": "The rule's name", "file": "The entry it is in", "before": "The rule's text, copied exactly", "after": "Better wording", "why": "How following it failed the person", "evidence": ["F<n>"] }
   ],
@@ -99,4 +103,6 @@ Reply with one JSON object and nothing else:
 }
 ```
 
-`screen` is a screen's `key` from the bundle, and `steps` are step numbers from it. With `general-craft`, leave `rules`, `conflicts` and `design_proposals` empty and every `breaks` null.
+`screen` is a screen's `key` from the bundle, and `steps` are step numbers from it.
+
+**checked** (optional): for an earlier designer finding listed under `P<n>` whose screen you actually judged in this run, and which you looked for and no longer see, add `{ "ref": "P<n>", "screen": "<that finding's screen>", "steps": [<the step numbers where you looked>], "note": "<one line: what you saw instead>" }`. List a `P<n>` only when its screen is one of the screens in this bundle and you looked at it at the steps you name. A finding you see again is answered with `same_as` on your issue instead. One you did not look for goes in neither list: it stays uncertain. Never list a check for a screen you did not judge, or without steps. With `general-craft`, leave `rules`, `conflicts` and `design_proposals` empty and every `breaks` null.

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

@@ -59,7 +59,7 @@ A project set up with an earlier version keeps its rules in `iamu/design.md`, wi
 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 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.
+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 the product's target URL (named in the prompt's dossier) + 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);

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

@@ -42,9 +42,14 @@ Determine the mode based on `$ARGUMENTS` and user intent:
   1. Ground in `iamu/context.yml` actors, domain, and jurisdiction.
   2. Define role, disposition, key biases, friction triggers, and domain vocabulary.
   3. Propose the persona candidate to the user (name, role, disposition, expectations).
-   4. Once confirmed, scaffold the persona into `iamu/personas/` with its background narrative and `## Today` section passed via `--body` (or update later with `iamu set persona <slug> --body "..."`):
+   4. Once confirmed, scaffold the persona into `iamu/personas/` with its background narrative and `## Today` section passed via `--body-file` (or update later with `iamu set persona <slug> --body-file <path>`; `-` reads stdin). Never put `\n` inside `--body`, it is stored literally:
       ```bash
-      iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<Background narrative and test expectations>\n\n## Today\n<How this person does the job today without the product>" --json
+      iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body-file - --json <<'EOF'
+<Background narrative and test expectations>
+
+## Today
+<How this person does the job today without the product>
+EOF
       ```
    5. Ensure the persona's markdown body includes their background narrative and test expectations, ending with a `## Today` section: how this person does the job the product is for today, without it (a paper sheet, a spreadsheet, phone calls, a colleague, another tool), and what that costs or gives them. The walker holds the product against it and the judge weighs voluntary use against it.
    6. Run `iamu validate --all`.
@@ -239,9 +244,14 @@ The `--capability`, `--additional-capabilities`, `--tension`, `--narrative`, and
 
 **3. Persona** (if user picked a new persona to scaffold):
 ```bash
-iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --body "<Persona background narrative and test expectations>\n\n## Today\n<How this person does the job today without the product>" --json
+iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --body-file - --json <<'EOF'
+<Persona background narrative and test expectations>
+
+## Today
+<How this person does the job today without the product>
+EOF
 ```
-The `--role`, `--disposition`, and `--body` flags populate frontmatter and the markdown body directly (or you can update the body via `iamu set persona <slug> --body "..."`). Leave `access` out — which product account the persona uses is decided when the scenario is staged in `iamu-run`. End the `--body` with a `## Today` section: how this person does the job the product is for today, without it (a paper sheet, a spreadsheet, phone calls, a colleague, another tool), and what that costs or gives them. The walker holds the product against it and the judge weighs voluntary use against it.
+The `--role`, `--disposition`, and `--body-file` flags populate frontmatter and the markdown body directly (or you can update the body via `iamu set persona <slug> --body-file <path>`; `-` reads stdin). Never put `\n` inside `--body`: it is stored literally. Leave `access` out — which product account the persona uses is decided when the scenario is staged in `iamu-run`. End the body with a `## Today` section: how this person does the job the product is for today, without it (a paper sheet, a spreadsheet, phone calls, a colleague, another tool), and what that costs or gives them. The walker holds the product against it and the judge weighs voluntary use against it.
 
 **4. Scenario** (the binding):
 ```bash

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

@@ -14,9 +14,9 @@ This skill resolves what scenario to run following a clear **Target Scenario Res
 
 **`--target <url>` (or a bare `http(s)://...` URL in `$ARGUMENTS`):** when `$ARGUMENTS` contains `--target <url>` or a URL, take it out before resolving the scenario and persist it immediately with `iamu set testability --target <url>` (and if the resolved scenario had its own `target_url` override that was shadowing the project target, clear it with `iamu set scenario <slug> --no-target` unless the user asked for a scenario-only URL).
 
-**`--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.
+**`--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. Pass `--no-ux` to `iamu post-walk`, which records the skip itself (reason `--no-ux`). Only on the manual path (no `post-walk`), run `iamu designer-record <run-id> --skipped "--no-ux"` after A. Never both: a second record is refused. Either way the report says it was skipped. There is no project setting for it: every other run gets a designer's review.
 
-**`--critic`:** when `$ARGUMENTS` contains `--critic`, take it out before resolving the scenario. This run is one critic pass in a builder ↔ critic loop (a gauntlet loop) the user orchestrates: the builder needs the verdict and the findings fast, not fixes or a design review. Skip the advisor (C2) entirely and skip the designer's review (C3): after A, record `iamu designer-record <run-id> --skipped "critic mode"`. Run A, B, C, D (and E in linked mode) as usual. In step 5, present the glance without the Advisor and Designer lines, and do not offer **directions** or **designer**. Per invocation only, like `--no-ux`. When the loop looks converged (every human test passes, or no open major or critical findings), add one line: `Loop looks converged: run once without --critic for the advisor's and designer's review.`
+**`--critic`:** when `$ARGUMENTS` contains `--critic`, take it out before resolving the scenario. This run is one critic pass in a builder ↔ critic loop (a gauntlet loop) the user orchestrates: the builder needs the verdict and the findings fast, not fixes or a design review. Skip the advisor (C2) entirely and skip the designer's review (C3): pass `--critic` to `iamu post-walk`, which records the skip itself (reason `--critic`); only on the manual path, run `iamu designer-record <run-id> --skipped "--critic"` after A. Never both. Run A, B, C, D (and E in linked mode) as usual. In step 5, present the glance without the Advisor and Designer lines, and do not offer **directions** or **designer**. Per invocation only, like `--no-ux`. When the loop looks converged (every human test passes, or no open major or critical findings), add one line: `Loop looks converged: run once without --critic for the advisor's and designer's review.`
 
 **`--fresh`:** when `$ARGUMENTS` contains `--fresh`, take it out before resolving the scenario. Clear the app's storage after `iamu browse start` (step 4) so the walk starts from clean storage, not from what an earlier walk left behind. `iamu browse` only; per invocation, like `--no-ux`.
 
@@ -236,7 +236,7 @@ Never silently guess login credentials or auth strategy without confirming with
 
 **Interactive Auth Handshake (for `interactive`, enterprise auth, SSO, 2FA, BankID):**
 If `auth_strategy` is `interactive` or the product is behind enterprise login where automated dev persona switching is not configured:
-1. Open the browser to the target URL (`iamu browse start --run <run-id>` or browser tool).
+1. Open the browser to the target URL (`iamu browse start` or browser tool). There is no run id yet; step 4 creates the run, and `iamu browse start --run <run-id>` there sizes the already open browser for the persona.
 2. Prompt the human user:
    > 👉 **Please log in as `<persona.role>` (`<persona.name>`) in the opened browser window.** Tell me once you reach the dashboard (e.g. "I'm logged in") to hand control to the walker...
 3. Wait for the user to confirm, then let the walker drive the authenticated session.
@@ -269,7 +269,7 @@ Use the returned `run_id` and `path` for all subsequent operations.
 iamu browse start --run <run-id>
 ```
 
-It sizes the page as the device the persona's tags name (`mobile`/`phone`, `tablet`/`ipad`, `desktop`/`laptop`; `start-run` prints it as `device`) and resizes a browser left at another persona's size.
+It sizes the page as the device the persona's tags name (`mobile`/`phone`, `tablet`/`ipad`, `desktop`/`laptop`; `start-run --json` returns it as `viewport.device`) and resizes a browser left at another persona's size.
 
 **Fresh walk (`--fresh`, `iamu browse` only).** When `--fresh` was given, or when running iterative passes against a browser left open (e.g. with `--critic`), clear the origin's storage after `browse start` so each walk starts from clean app storage:
 
@@ -287,10 +287,10 @@ iamu instructions walk --scenario <scenario-slug> --run <run-id> --surface brows
 
 The result's `walker_prompt` is the walker's entire prompt (also persisted at `walker_prompt_path`). Pass it verbatim — do not rewrite, summarize or trim it. The prompt already carries the dismissed findings, the active tester guidance rules (`iamu/guidance/`) for this scenario, and — when fixes await a re-run — the places they were seen (places only, never what was wrong; the list is in `revisit`). The rest of the bundle (`persona`, `outline`, `access`, `dismissed_findings`, `tester_guidance`, …) is there for you, not the walker. If `access` is missing a half, fill it in first (step 3) and re-run this command.
 
-**Preflight: Unattended execution check.** A walkthrough executes 15–30 terminal commands sequentially (`iamu browse step`, `iamu new-finding`). If your agent host requires manual confirmation for terminal/shell commands (standard interactive mode in Claude Code, Cursor, Antigravity, Cline, Windsurf, etc.), the walker subagent will stall waiting for approval on every step. Before dispatching, verify that command auto-approval / unattended execution is enabled in your environment, or warn the user once:
+**Preflight: Unattended execution check.** A walkthrough executes 15–30 terminal commands sequentially (`iamu browse step`, `iamu new-finding`). If your agent host requires manual confirmation for terminal/shell commands (the standard interactive mode of most agent hosts), the walker subagent will stall waiting for approval on every step. Before dispatching, verify that command auto-approval / unattended execution is enabled in your environment, or warn the user once:
 "Autonomous walkthroughs require auto-approving terminal commands so the walker can drive the product unattended. If command approvals are prompted, please enable auto-approval or expect to approve steps manually."
 
-**CRITICAL: Dispatch the walker as an isolated subagent.** Spawn a fresh subagent using your host editor's subagent mechanism (e.g. `Agent(...)` in Claude Code, `invoke_subagent` in Antigravity, or host-native subagent launcher). The subagent gets ONLY the walking prompt (`walker_prompt`) — no prior conversation history.
+**CRITICAL: Dispatch the walker as an isolated subagent.** Spawn a fresh subagent using your host's own subagent mechanism. The subagent gets ONLY the walking prompt (`walker_prompt`) — no prior conversation history.
 
 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.
 
@@ -300,17 +300,18 @@ A fresh subagent is NOT blind by default. On most hosts it still loads the proje
 - **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`.
 
 **Model tiering & subagent dispatch:**
-- **Walker (Browser Navigation):** High turn count, and a judgement at every screen about what fits the persona's role. Use the **mid** tier (`sonnet` in Claude Code, `flash` in Antigravity) by default: on the role-fit benchmark in Claude Code it found the same problems as `haiku` about 1.7× faster, at a higher price per token. In `--critic` loops, where cost per walk matters more than the time of one walk, the **fastest** tier (`haiku` in Claude Code) is an option.
-- **Matcher:** Short-text classification (same problem or not) into strict JSON that `match-record` validates. Use the **fastest** tier (`haiku` in Claude Code, `flash_lite` in Antigravity, else the mid tier).
-- **Judge:** Evaluates the human tests from the walk's recorded steps and findings (`judge_prompt.md`, text-only reading comprehension). Use the **mid** tier (`sonnet` in Claude Code, `flash` in Antigravity).
+- **Walker (Browser Navigation):** High turn count, and a judgement at every screen about what fits the persona's role. Use the **mid** tier by default: on the role-fit benchmark it found the same problems as the fastest tier about 1.7× faster, at a higher price per token. In `--critic` loops, where cost per walk matters more than the time of one walk, the **fastest** tier is an option.
+- **Matcher:** Short-text classification (same problem or not) into strict JSON that `match-record` validates. Use the **fastest** tier (else the mid tier).
+- **Judge:** Evaluates the human tests from the walk's recorded steps and findings (`judge_prompt.md`, text-only reading comprehension). Use the **mid** tier.
+- **Advisor and designer:** the **thorough** tier.
 
-```
-# In Claude Code:
-Agent({ description: "Walk <scenario-slug> as <persona.name>", model: "sonnet", prompt: "<walker_prompt, verbatim>" })
+Dispatch each with your host's subagent launcher, giving it the model for the tier, the walker prompt verbatim (or, for the other stages, the path to the prompt file). Example model names per host, which change over time; use what your host offers at that tier:
 
-# In Antigravity / generic subagent hosts:
-invoke_subagent(Role="Persona Walker", Model="flash", Prompt="<walker_prompt, verbatim>")
-```
+| Tier | Claude Code | Antigravity |
+|------|-------------|-------------|
+| fastest | `haiku` | `flash_lite` |
+| mid | `sonnet` | `flash` |
+| thorough | `opus` | the host's strongest model |
 
 The subagent inherits the driving-surface tools and drives the product independently. It does not see this conversation.
 
@@ -385,19 +386,23 @@ 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 A, then B and C in parallel, then C2; the designer's review (C3) starts right after A and runs beside B, C and C2. D and E wait until every record (B, C, C2, C3) is in, so the report you read and the run you publish are complete.
+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 A, then B and C in parallel, then C2 once the judge's verdict is recorded (the advisor reads it); the designer's review (C3) starts right after A and runs beside B, C and C2. D and E wait until every record (B, C, C2, C3) is in, so the report you read and the run you publish are complete.
 
 > **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`, `iamu post-walk`, 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 via stdin heredoc (`--file - <<'EOF' ... EOF`), `--file <path>`, or `--data '<json>'`.
 
 **Fast path — prepare all post-walk prompts in one hop:**
-You can complete the run locally AND generate `match_prompt.md`, `judge_prompt.md`, `advise_prompt.md`, and `designer_prompt.md` in a single command:
+You can complete the run locally AND generate `match_prompt.md`, `judge_prompt.md` and `designer_prompt.md` in a single command; the advisor's prompt waits for the judge:
 
 ```bash
 iamu post-walk <run-id> --json
 ```
 
-`iamu post-walk <run-id> --json` returns the `needed` status, `prompt_file_abs`, and `answer_file_abs` for `match`, `evaluate`, `advise`, and `designer` in one JSON object (pass `--critic` or `--no-ux` when applicable). If subagent JSON outputs are later written to their `answer_file_abs` paths in `<run-dir>/`, running `iamu post-walk <run-id> --json` again records all of them in lock-safe order automatically.
+`iamu post-walk <run-id> --json` returns the `needed` status, `prompt_file_abs`, and `answer_file_abs` for `match`, `evaluate`, `advise`, and `designer` in one JSON object (pass `--critic` or `--no-ux` when applicable; it records those skips itself). The advisor reads the judge's verdict, so until `verdicts.json` exists `advise` comes back as `needed: false` with `reason: "awaiting judge"` and no prompt.
+
+Call `post-walk` twice:
+1. After the walk: dispatch the matcher, the judge and the designer from the prompts it wrote, and write each answer to its `answer_file_abs` (or record it with the `*-record` command).
+2. After `evaluate-record` has recorded the verdict: run `iamu post-walk <run-id> --json` again. It records every answer file that has arrived, in lock-safe order, and now builds `advise_prompt.md`. Dispatch the advisor from it (C2) and record its answer the same way.
 
 **A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous (already done if you ran `iamu post-walk <run-id> --json`):
 
@@ -421,7 +426,7 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 iamu match <run-id> --json
 ```
 
-If `needed` is `false` (no earlier findings for this scenario, or none this run), there is no matcher subagent. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **fastest** model tier: `haiku` in Claude Code, `Model="flash_lite"` in Antigravity). Record its JSON answer via `--file - <<'EOF'` (or `--data`):
+If `needed` is `false` (no earlier findings for this scenario, or none this run), there is no matcher subagent. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **fastest** model tier). Record its JSON answer via `--file - <<'EOF'` (or `--data`):
 
 ```bash
 iamu match-record <run-id> --file - <<'EOF'
@@ -438,7 +443,7 @@ This links recurrences to their earlier canonical finding, marks earlier finding
 iamu evaluate <run-id> --json
 ```
 
-Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt, at the same time as the matcher (use the **mid** model tier: `sonnet` in Claude Code, `Model="flash"` in Antigravity). After the evaluator returns verdicts, record them via `--file - <<'EOF'` (or `--data`). Like every record command it stays local and never prompts; E publishes:
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt, at the same time as the matcher (use the **mid** model tier). After the evaluator returns verdicts, record them via `--file - <<'EOF'` (or `--data`). Like every record command it stays local and never prompts; E publishes:
 
 ```bash
 iamu evaluate-record <run-id> --file - <<'EOF'
@@ -449,13 +454,13 @@ EOF
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
-**C2. Advise: fixes and directions.** Skip in `--critic` mode. Otherwise get the advisor prompt (if not already prepared via `iamu post-walk`):
+**C2. Advise: fixes and directions.** Skip in `--critic` mode. The advisor starts from the judge's verdict, so it runs only after `evaluate-record` has recorded it, never beside the judge. Get the advisor prompt (a second `iamu post-walk <run-id> --json` after `evaluate-record` builds it; before that `advise` says `needed: false`, `reason: "awaiting judge"`):
 
 ```bash
 iamu advise <run-id> --json
 ```
 
-If `needed` is `false` (blocked run, nothing open to advise, or already advised), skip to D. Otherwise read the prompt from `iamu/.runs/<run-id>/advise_prompt.md` and dispatch an advisor subagent with it as its only context (use the **thorough** model tier). Unlike the walker, the advisor reads the project's code (read-only) and the screenshots: it classifies each finding local or systemic, writes the fix from the persona's need, looks at how leading systems in the domain handle the moment, and proposes directions for the flow with their predicted reach on other personas. Record its JSON answer via `--file - <<'EOF'` (or `--data`):
+If `needed` is `false` (blocked run, nothing open to advise, or already advised), skip to D. Otherwise read the prompt from `iamu/.runs/<run-id>/advise_prompt.md` and dispatch an advisor subagent with it as its only context (use the **thorough** model tier). Unlike the walker, the advisor reads the project's code (read-only) and the screenshots: it classifies each finding local or systemic, writes the fix from the persona's need, looks at how leading systems in the domain handle the moment, and proposes directions for the flow with their predicted reach on other personas. Tell the advisor to read the whole prompt (its answer schema is at the end) and to open at most 3–5 source files behind the screens where its findings occurred, found through `panorama.source_files` and `panorama.code_routes` in the bundle, rather than crawling unrelated screens. Record its JSON answer via `--file - <<'EOF'` (or `--data`):
 
 ```bash
 iamu advise-record <run-id> --file - <<'EOF'
@@ -466,7 +471,7 @@ EOF
 
 Each entry is checked on its own. Entries that come back rejected (an invented file or symbol, a path in the prose, a direction with too little evidence) stay unadvised and the rest is kept; a run is advised once, so do not record again. Mention rejected entries in step 5. Keep the result's `directions` and `rerun` for step 5.
 
-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.
+Dispatch the advisor (C2) after `evaluate-record`, never in parallel with the judge: it reads the verdict. Run `evaluate-record` and `advise-record` one after the other too: 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` or `--critic` was given), start it as soon as A is done:
 
@@ -474,7 +479,7 @@ The judge (C) and the advisor (C2) are independent, so their subagents may run i
 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. The subagent MUST open and look at the key screenshots the prompt lists (their paths are `key_screenshots` in the result) with its own file-viewing tool, judging visual hierarchy, layout, contrast and typography against the design docs the prompt names, else general craft. What it finds are designer findings: judgement, never the persona's experience, and never counted with the persona's findings or in the verdict.
+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, once the verdict is in, the advisor (C2) where the host allows. The subagent MUST open and look at the key screenshots the prompt lists (their paths are `key_screenshots` in the result) with its own file-viewing tool, judging visual hierarchy, layout, contrast and typography against the design docs the prompt names, else general craft. What it finds are designer findings: judgement, never the persona's experience, and never counted with the persona's findings or in the verdict.
 
 The advisor (C2) does not wait for the designer, but D and E do: when its answer arrives, record it:
 
@@ -648,8 +653,15 @@ When the user asks to review findings one by one:
      > • **By design / intended behavior:** (Why this pattern is expected)
      > • **Walker error:** (What the walker misread or did wrong)
      > • **Out of scope:** (Non-issue for this product/flow)
+     > • **Duplicate:** (Same problem as another finding)
      > What specific rule should future walkers follow?"
-     
+
+     Map the user's choice to the `--reason` value; no other value is accepted (`invalid_reason`):
+     - By design / intended behavior → `not_relevant`
+     - Walker error → `walker_error`
+     - Out of scope → `out_of_scope`
+     - Duplicate → `duplicate` (add `--duplicate-of <slug>`; it writes no guidance rule)
+
      Once the user provides their reasoning (or if already clear from discussion):
      Derive a concise, actionable guidance rule string.
      Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<user rationale>" --rule "<rule string>"`.

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

@@ -390,8 +390,14 @@ Step 3b: Walk Surface & Persona Login
    ```
 3. **Scaffold Persona**:
    ```bash
-   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>\n\n## Today\n<how they do this job today without the product, and what that costs or gives them>" [--access "<confirmed-account-or-role>"] --json
+   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" [--access "<confirmed-account-or-role>"] --body-file - --json <<'EOF'
+<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>
+
+## Today
+<how they do this job today without the product, and what that costs or gives them>
+EOF
    ```
+   Pass a multi-line body with `--body-file` (a path, or `-` for stdin as above), never with `\n` inside `--body`: the shell does not turn `\n` into a newline, so the file would store a literal backslash-n.
 4. **Scaffold Bound Scenario**:
    ```bash
    iamu new scenario --name "<persona-slug>--<outline-slug>" --outline "<outline-slug>" --persona "<persona-slug>" --entry "<confirmed_entry_path>" --body "<Persona's first-person test brief describing what they intend to achieve>" --json

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

@@ -45,10 +45,10 @@ Run `iamu instructions stage [slug] --json` to inspect the scenario's paired per
 iamu instructions stage <slug> --json
 ```
 This loads:
-- **Who:** Persona role, technical disposition, and required account access.
-- **Where:** What screen/page does the persona start on? (The landing URL / route prefix).
-- **What:** What world state must exist for the situation to make sense? (e.g. "Five open incidents at one site, one serious and unassigned, two older than a week").
-- **Human Tests:** What specific questions will be evaluated? (e.g. "Can Maria see which incident is unassigned without clicking each row?").
+- **Who:** `persona.role`, `persona.disposition`, and `persona.access` (the persona's own account or role key; null when unset).
+- **Where:** `scenario.entry_path` (the landing route; null when unset) and `scenario.target_url`.
+- **What:** `scenario.state` and `outline.narrative`: what world state must exist for the situation to make sense? (e.g. "Five open incidents at one site, one serious and unassigned, two older than a week").
+- **Human Tests:** `outline.human_tests`, the questions that will be evaluated (e.g. "Can Maria see which incident is unassigned without clicking each row?").
 
 ### 2. Scout the Codebase & Environment (The "How")
 

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

@@ -59,12 +59,17 @@ export interface HtmlReportSinceItem {
     title: string;
     note?: string;
     step_ids?: string[];
+    visited?: boolean;
     fixed_before?: boolean;
     severity_before?: string;
     severity_now?: string;
+    /** `resolvedUntriaged` only: the finding file to triage. */
+    slug?: string;
 }
 export interface HtmlReportVerification {
     resolved: HtmlReportSinceItem[];
+    /** Gone this run per the matcher, but never marked addressed. */
+    resolvedUntriaged?: HtmlReportSinceItem[];
     persists: HtmlReportSinceItem[];
     notObserved?: HtmlReportSinceItem[];
     newFindings: Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.8.0-beta.3",
+  "version": "0.8.0-beta.4",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "MIT",