@iamu-dev/iamu 0.8.0-beta.2 → 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/design-review.md

@@ -13,7 +13,7 @@ You review one surface of the product: a page, its states, and the flows that pa
 
 - **Several people, one surface.** When visitors need different things here (one wants a firm answer, another a fast decision), say who should see what. Role clarity often beats explaining more to everyone.
 - **Evidence, seen or taste, always labelled.** `evidence`: a visitor's walk shows it; cite the refs (`F3`). `seen`: you saw or measured it yourself in the browser (a clipped control, a 3.1:1 contrast); give the screenshot path. `taste`: your judgement against the rules or general craft. All are welcome; never pass one off as another.
-- **Name the rule.** When an issue breaks a rule in the design docs, give the rule's name exactly as the doc writes it (its heading, or the bold words that open it) as `rule`, and the entry it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
+- **Name the rule.** When an issue breaks a rule in the design docs, give the rule's canonical name from that file's `rules` array in `design.files` (or, if none is listed, its heading or the bold words that open it) as `rule`, and the `entry` it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
 - **When a rule hurts a need, say so.** If following a rule is what fails a visitor (the rule keeps a caveat small and grey, and the person missed it), report a `conflict`: the rule and its file, the rule's text copied exactly from the doc as `before`, better wording as `after`, the evidence, and why. Do not silently break the rule or silently follow it. A person decides.
 - **Prefer removing, merging and hiding by role to adding.** Every element must earn its place.
 - **Confirm resolved problems.** When a problem in `problems` or an unverified fix in `fix_history` (`state: "awaiting_rerun"`, carrying a `ref` like `F1`, `F2`, ...) is now visibly fixed on the live surface, list it in `resolved` with its `ref` (`"F1"`) and one sentence (`how`) describing what on the live screen resolves the visitor's need. Never list the same ref in both `issues[].evidence` and `resolved`.

package/dist/templates/prompts/designer.md

@@ -16,10 +16,12 @@ The person already judged what it was like: whether the product fits their role,
 - `findings`: what the person filed on this run, as refs: `F<n>` for problems, `S<n>` for what helped, each with its `step`. A finding's `severity` is the one the person filed.
 - `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. `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.
+- `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.
-- `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, 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.
+- `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 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
@@ -30,7 +32,7 @@ Open only the screenshots the bundle lists and the files `design.files` lists. N
 
 1. **Read the design docs first** (every file in `design.files`), then the persona and the situation.
 2. **Go screen by screen, in walk order.** For each screen, say what it is for this person at this moment, and what on it serves them.
-3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact name as the doc writes it (its heading, or the bold words that open it, without a closing full stop or colon) and the entry it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
+3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact canonical string from that file's `rules` array in `design.files` (or, if none is listed, its heading or the bold words that open it, without a closing full stop or colon) and the `entry` it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
 4. **Judge the craft the person could not see:** consistency across the screens, contrast and accessibility (estimated from the screenshot: say so), copy and formats, interaction and states (what is shown after an action, while loading, when empty, when it fails), and hierarchy and density where they explain a finding or concern what the walk passed by.
 5. **Label every claim.** `evidence`: a finding shows it; cite its refs. `seen`: you see it in a screenshot; cite the steps. `taste`: your judgement against the docs or general craft. All are welcome; never pass one off as another.
 6. **Never restate a finding, except as its design cause.** Before you write an issue, check the findings: if it is about the same problem on the same screen as an `F<n>`, in any words, it is not a new issue. Either give its design cause, citing that `F<n>` in `evidence` and its `step` in `steps` (that is what links your issue to the finding as its cause), or leave it out. Role fit, overload and "this is not for me" are the person's findings; raise them only as such a cause.
@@ -89,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>"] }
   ],
@@ -98,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/prompts/walk.md

@@ -147,6 +147,12 @@ When an environment is unseeded or test records are missing:
 - If your persona role is a creator (e.g. employee or consultant creating an item), click the creation CTA (e.g. "+ Ny reseräkning", "+ New") and proceed with your task.
 - If your persona role is read-only (e.g. an auditor or manager) and cannot create data, do NOT record false "missing data" bugs against the product. Conclude the walk noting that the environment lacks the required preconditions.
 
+## Host product vs. subject payload (Seeded defects & inspected content)
+
+Many products display, inspect, or triage a **subject** — an embedded preview or screenshot of another app, a customer submission, a failing test run, a security alert, an audit log, or a document with errors.
+- **Separate the host UI from the subject payload:** When your persona's job is to review, flag, or act on defects inside an inspected subject (e.g. spotting a squeezed sidebar or wrong notice inside a previewed app screenshot, or triaging a failing check), those defects belong to the **subject** you are inspecting — they are NOT bugs in the **host product** you are using.
+- **Evaluate the host product's tools:** Act on the seeded subject defects using the host product's workflow as the persona would. Only file an `iamu` finding (`hinders`, `missing`, `incorrect`) if the **host product** makes it hard, confusing, or impossible to see, flag, or resolve the subject's defects.
+
 ## Semantic squinting (Adapting to environmental mismatch)
 
 Your prompt may include an approximation strategy (e.g. "If Malmö is missing, choose Göteborg").

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-findings.md

@@ -184,28 +184,20 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **Design change needed** → the change requires design thinking (restructuring a flow, new capability, API contract touch, multiple files). Do NOT fix inline. Use the project's own change process if it has one — check the agent docs and the repo for it (an `openspec/` directory and its change skills, an ADR or RFC folder, an issue tracker the docs name) and start the change there with the finding's persona + scenario context pre-filled. Only if the project has none, draft a short design doc. Then leave the finding `open` until the change ships. Attach the change reference in `triage_note`: `"Design change: <reference>. Re-triage when the change ships."`.
 
-- **Defer** → the finding is real but not urgent. Set `triage_status: deferred` with an explicit `triage_note` naming the condition to revisit: `"Defer: revisit after <trigger, e.g. Q3 mobile release / next round of persona feedback>."`.
+- **Dismiss (`not_relevant` / `walker_error` / `out_of_scope` / `duplicate`)** → the finding is not a problem to fix:
+  - Quick 1-step dismiss (defaults to `not_relevant` and writes `"Don't report: <title>"`): `iamu triage <slug> --status dismissed`.
+  - With custom rationale or rule:
+    - *Not relevant* (by design): `iamu triage <slug> --status dismissed --reason not_relevant [--note "<why>"] [--rule "<rule string>"]`.
+    - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error [--note "<what it misread>"] [--rule "<rule string>"]`.
+    - *Out of scope* (handled outside the system): `iamu triage <slug> --status dismissed --reason out_of_scope [--note "<how it is handled>"] [--rule "<rule string>"]`.
+    - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
+      `iamu triage [slug] --status dismissed [--note "<why>"] --rule "Don't report: <X>" --sweep "<keyword>"`.
+      This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, the matcher, the judge (`evaluate`) and `fix-brief` respect. The designer never reads tester guidance: a swept designer finding is dismissed, and later designer's reviews are told not to raise it again.
+    - *Duplicate* of another finding: `iamu triage <slug> --status dismissed --duplicate-of <other-slug> [--note "<note>"]` (no rule is written).
 
-- **Won't fix (accepted trade-off)** → the problem is real but the team accepts it. `iamu triage <slug> --status wont_fix --note "<the trade-off>"`. It stays out of future walks' dismissed list only as a known issue — no guidance rule is written, unless you pass `--sweep`, which dismisses every matching finding and records a project-wide rule as a dismissal would.
+  `not_relevant`, `walker_error`, and `out_of_scope` write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to `"Don't report: <title>"`; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad, or `--no-guidance` to skip writing a rule. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."**
 
-- **Not relevant / walker got it wrong (Load-Bearing Guidance Learning)** → the finding should never have been reported. **Never infer the reason silently.** Always ask the user:
-  > "To teach future walkthroughs what not to report, why should this be dismissed?
-  > • **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)
-  > What specific rule should future walkers follow?"
-  
-  Once the user provides their rationale:
-  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>" --rule "<rule string>"`.
-  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>" --rule "<rule string>"`.
-  - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
-    `iamu triage [slug] --status dismissed --note "<why>" --rule "Don't report: <X>" --sweep "<keyword>"`.
-    This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, the matcher, the judge (`evaluate`) and `fix-brief` respect. The designer never reads tester guidance: a swept designer finding is dismissed, and later designer's reviews are told not to raise it again.
-  - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
-
-  Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."** One-word notes ("nope") degrade future runs — capture the user's specific rationale.
-
-- **Keep (no decision yet)** → rare. Use only when the reviewer genuinely needs more information. Leave `triage_status: open` and add a `triage_note` noting what you are waiting for: `"Waiting on <thing> before triage."`.
+- **Keep open (no decision yet)** → leave `triage_status: open` and optionally attach a `triage_note`: `iamu triage <slug> --status open --note "Waiting on <thing> before triage."`.
 
 Report back with the action taken:
 
@@ -213,11 +205,8 @@ Report back with the action taken:
 addressed (fix now): <finding-slug>
   Change: made handoff notes optional on /sv/handoff
 
-deferred: <finding-slug>
-  Note: revisit after Q3 mobile release
-
 dismissed (duplicate): <finding-slug>
-  Reason: duplicates frontline-worker--incident-report-overwhelm-a7b2c1
+  Duplicate of: frontline-worker--incident-report-overwhelm-a7b2c1
 
 dismissed (not_relevant): <finding-slug>
   Reason: the beta badge is intentional until launch

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,12 +386,25 @@ 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`, 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).
+> 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>'`.
 
-**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
+**Fast path — prepare all post-walk prompts in one hop:**
+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; 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`):
 
 ```bash
 iamu complete <run-id> --no-prompt --no-push --json
@@ -400,53 +414,64 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 
 **If the result has `blocked`**, the walker could not start the walk as it was set up (`iamu summary --blocked`): it could not become the persona, or the world the situation needs was not there. That is a setup problem, not a product finding. Skip B and C — a blocked run is never compared with earlier runs and never counts as a re-run. Tell the user in one line what was missing (`blocked.reason`), then run the `iamu-stage` skill with that reason as the starting point: fix the scenario's `state`, the persona's access, or the seed, and offer to run the scenario again. Findings the walker recorded before it stopped stay as they are. E still runs in linked mode; the report says the run was blocked.
 
-**B and C run in parallel.** The matcher (B) and the judge (C) answer different questions from different inputs, and the judge never reads the matcher's output. Run `iamu match` and `iamu evaluate` one after the other (both are instant), then dispatch both subagents at the same time. Record their answers one after the other as they arrive (`match-record` and `evaluate-record` both rewrite the report; never run them at the same time). Keep them separate: the judge must not see earlier runs' findings, so its verdict cannot drift toward "it was fixed, so it passes".
+**B and C run in parallel.** The matcher (B) and the judge (C) answer different questions from different inputs, and the judge never reads the matcher's output. Run `iamu post-walk <run-id> --json` (or `iamu match` and `iamu evaluate`), then dispatch the needed subagents at the same time. Record their answers one after the other as they arrive (`match-record` and `evaluate-record` both rewrite the report; never run them at the same time). Keep them separate: the judge must not see earlier runs' findings, so its verdict cannot drift toward "it was fixed, so it passes".
 
 **How to dispatch the matcher and the judge.** Do not paste the prompt into the dispatch; give the absolute path. Their whole prompt is: `Read <absolute path to match_prompt.md / judge_prompt.md> and answer exactly as it says. Everything you need is in that file. Do not open any other file, run any command or search any code. Reply with the JSON only.` Both are pure reading tasks; a subagent that goes looking for context (the repo, the CLI's source, other runs) costs minutes and can see things it must not.
 
-**B. Match findings to earlier runs.** Get the matcher bundle:
+**Avoid zsh quote-escaping failures when recording JSON:** Subagent outputs are 5–15 KB of JSON that frequently contain single quotes (`"Something's off"`) and escaped double quotes (`"\"Hall rules\""`). Prefer piping via a single-quoted heredoc (`--file - <<'EOF'`) or `--file <path>` so the shell never interprets quotes inside the JSON.
+
+**B. Match findings to earlier runs.** Get the matcher bundle (if not already prepared via `iamu post-walk`):
 
 ```bash
 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 `--data` (do NOT create a `matches.json` file yourself; pass the JSON string directly into `--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> --data '<raw_matches_json>'
+iamu match-record <run-id> --file - <<'EOF'
+<raw_matches_json>
+EOF
+# or: iamu match-record <run-id> --data '<raw_matches_json>'
 ```
 
 This links recurrences to their earlier canonical finding, marks earlier findings the run's steps show fixed (only with cited steps), and re-derives the delta and report. If the matcher's output is rejected, show the error to the matcher once and retry; if it fails again, continue without it — the exact-text delta from A stands.
 
-**C. Evaluate human tests.** Get the evaluation prompt:
+**C. Evaluate human tests.** Get the evaluation prompt (if not already prepared via `iamu post-walk`):
 
 ```bash
 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 `--data` (do NOT create a `verdicts.json` file yourself; pass the JSON string directly into `--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> --data '<raw_verdicts_json>'
+iamu evaluate-record <run-id> --file - <<'EOF'
+<raw_verdicts_json>
+EOF
+# or: iamu evaluate-record <run-id> --data '<raw_verdicts_json>'
 ```
 
 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:
+**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 `--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> --data '<raw_advice_json>'
+iamu advise-record <run-id> --file - <<'EOF'
+<raw_advice_json>
+EOF
+# or: iamu advise-record <run-id> --data '<raw_advice_json>'
 ```
 
 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:
 
@@ -454,17 +479,20 @@ 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:
 
 ```bash
-iamu designer-record <run-id> --data '<raw_designer_json>'
+iamu designer-record <run-id> --file - <<'EOF'
+<raw_designer_json>
+EOF
+# or: iamu designer-record <run-id> --data '<raw_designer_json>'
 ```
 
 Record commands run one at a time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` goes between them when its answer arrives (the CLI also holds each run's record lock, so one that starts while another records waits for it). 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.
 
-**Never fabricate a review.** Where the host can dispatch a subagent that looks at images, the review is that subagent's. Only on a host that cannot dispatch one, and only when you can open and look at the screenshots yourself, answer `designer_prompt.md` yourself and record it with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`: the report then says it was written by the orchestrator, which is less independent. If neither is possible, record `iamu designer-record <run-id> --skipped "no subagent can look at images"`. `--no-ux` and `--critic` record their own reasons (see the top of this skill).
+**Never fabricate a review.** Where the host can dispatch a subagent that looks at images, the review is that subagent's. Only on a host that cannot dispatch one, and only when you can open and look at the screenshots yourself, answer `designer_prompt.md` yourself and record it with `iamu designer-record <run-id> --by-orchestrator --file - <<'EOF'` (or `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`): the report then says it was written by the orchestrator, which is less independent. If neither is possible, record `iamu designer-record <run-id> --skipped "no subagent can look at images"`. `--no-ux` and `--critic` record their own reasons (see the top of this skill).
 
 Keep the result's `proposals`, and `offer_template` from `iamu designer`, for step 5.
 
@@ -625,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<{