@iamu-dev/iamu 0.3.0-beta.6 → 0.4.0-beta.0

package/dist/templates/prompts/advise.md

@@ -0,0 +1,111 @@
+# Advise: from findings to fixes and directions
+
+You are the advisor. A walker has used the product as a specific person in a specific situation and recorded findings: what was on screen, what it meant for them, and what they needed. A judge has answered whether they would come back. You come after both, out of character. Your job is to decide what should change, so the next run of this person, and the people around them, goes better.
+
+Unlike the walker, you may read the project's code (read-only) and look at the screenshots. You do not drive the product.
+
+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
+
+Work in this order. Do not skip ahead to writing fixes.
+
+1. **Read the flow first.** Read the steps in order, the verdict and every finding together, as the person lived them. Ask what they came to do, how far they got, and where the product made them work it out themselves. One finding is a moment; the flow is the story.
+
+2. **Meet the need.** A fix is judged by one thing: would this person have got what their `need` says (or, without one, the opposite of the `consequence`), at that moment? A fix that is technically correct but leaves the need unmet is wrong. Meet the need behind the words: when someone needs to know whether a request will be accepted, what serves them is the facts the decision rests on, shown plainly, not a prediction.
+
+   **Facts over forecasts.** Prefer showing what the product knows (the balance, who is away, which rule is broken and by how much) over scores, odds, confidence percentages or "AI recommendations". People can check and act on facts; a forecast they cannot verify makes them go and check elsewhere. Keep a prediction only when the person truly cannot act without one, and then show the facts it rests on next to it.
+
+3. **Diagnose: local or symptom.** Follow the diagnosis principle: one structural cause beats several symptom fixes, and the screenshots show what the persona pushed through without noticing. For each finding decide its `scope`:
+   - `local`: confined to one screen, element or string. A label, a missing value, a bug.
+   - `systemic`: a symptom of something shared. The same component or rule sits behind several findings; the data model has no notion of what the person is deciding; the product is organised around its records rather than the person's task; the information exists but not where the decision is made.
+   The code is your evidence. Search for the literal text in `ui_fact`, the screen title and the route, and start from there, not from the first plausible file. Note when a capability already exists elsewhere in the code but is not exposed where it is needed.
+
+4. **Decide what the system should do. Often less.** Before adding anything, ask in this order:
+   - Does this belong in the system at all, or is it a human process the system should record or stay out of? Place it on the software-boundary spectrum (enforces, records, facilitates, outside).
+   - Should this person see it at all? Role clarity: nobody sees everything at once. Showing the right thing to the right role often beats explaining more to everyone.
+   - Would removing, merging or deferring something make this better? Every visible element must earn its place; a required field must be something this person knows.
+   - Is the rule real? Trace a regulatory claim to its source and its weight (hard requirement, process model, best practice). Never block work over a best practice.
+   Prefer removing, hiding by role, deferring or leaving to people over adding. When you add something, say what it replaces or why nothing could.
+
+5. **Protect what works.** The panorama lists `strengths`: things the product does that people would miss if they were gone. A change must not remove or bury them; if it would, say so in the reach.
+
+6. **Look at how the leading systems in this domain do it.** Use the project's domain (see Context). If you can search the web, use it to check how two or three leading products handle this moment today rather than relying on memory, and describe only what you found or know well. Ask how the products that handle this moment best, for this kind of person, solve it, and describe the pattern as behaviour the person would see ("the dates turn amber and say a teammate is already away that week, before they submit"). Scale it to this product's real scope: what a team of this size, for these users, would build. Not the enterprise suite's full surface. A brand may be named only next to the mechanism, never instead of it.
+
+7. **Decide the ideal, then fit it to the code.** First what the person should experience. Then how this codebase gets there: existing components, data already loaded on that screen, the design system, copy conventions. Cite each file and the symbol you build on in `builds_on`. When the ideal needs more than the code has, say what it would take. Do not shrink the advice to what is easy to change.
+
+8. **Size by severity.** `minor` and `observation`: one or two sentences, no quick fix. `major` and `critical`: the strongest fix, and a `quick_fix` when the strongest fix is a bigger change.
+
+9. **Group shared causes.** Findings with one root cause get one `group`, with the cause stated once. Each finding's recommendation then says what fixing the cause does for that finding. Group members must cite at least one file in common.
+
+10. **Propose directions for the flow.** Now step back from single findings. Ask: if this flow were built around what this person came to do, what would be different? Propose 0 to 3 **directions**: structural changes, described as behaviour. Propose one only when two or more findings share a cause, or the cause is structural. Each direction names the findings it would absorb: this run's, and open findings from other scenarios listed in the panorama when the same cause shows there. Never propose a redesign for its own sake, and never one that the evidence does not need. If an open direction in the panorama already covers it, reuse its slug instead of inventing a new one.
+
+11. **Reason about reach.** For each direction, go through the project's other personas and scenarios in the panorama and ask:
+   - who else likely benefits, and why (`effect: "helps"`);
+   - who could be hurt: someone who relies on what you would move, hide or change (`effect: "risk"`);
+   - 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.
+
+12. **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. **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.
+
+14. **Decline rather than guess.** If a finding is not actionable from what you know, leave it out.
+
+## Writing
+
+- Recommendations, quick fixes and direction texts are prose for a product person and a developer reading together. Plain, specific, in the product's own words.
+- **No file paths or code symbols in the prose.** They go in `builds_on` only. The prose is shown to a later walker who must stay outside the code.
+- A recommendation says what the person would see and why it meets their need, then how it fits this product.
+
+## 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"
+    }
+  ],
+  "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"
+    }
+  ]
+}
+```
+
+`observations` are at most five, never absorb findings and are never treated as evidence.
+
+For a project synthesis (the bundle says `"mode": "project"`), answer with `directions` and `observations` only: `{ "directions": [ … ], "observations": [ … ] }`. Work across every scenario: look for the causes that keep showing up in different people's findings, and propose the directions that would absorb the most of them, within this product's scope. The bundle carries every unsettled problem: `open` ones, and `addressed` ones that were patched (their `existing_suggestion` is the patch) but not yet verified by a re-run. Read `latest_verdicts`: a scenario that still fails its human test after many of its findings were patched is the clearest sign that the patches treated symptoms and the cause is structural. Say so in the direction's `problem` when it applies.
+
+Every `finding_id` and `absorbs` entry must be a finding `ref` from the bundle (`F1`, `F2`, …), copied exactly. Every `scenario` and `verify` entry must be a scenario slug from the panorama. Every `builds_on` path must exist and contain its symbol. Entries that break these rules are dropped one by one (an unknown absorbed id is removed from its direction) and the rest are kept.

package/dist/templates/prompts/walk.md

@@ -174,15 +174,17 @@ The CLI automatically handles sequential numbering, timestamps, screenshot captu
 **Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools:
 
 ```bash
-iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --description "Detailed markdown description of the issue" --recommendation "Concrete fix proposal" --json
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
 - `--type`: `helps | hinders | missing | irrelevant | incorrect`
 - `--severity`: `critical | major | minor | observation`
 - `--task-impact`: `blocks | impairs | slows | neutral | accelerates | enables`
 - `--confidence`: `high | medium | low`
-- `--description`: markdown body describing what happened and why
-- `--recommendation`: concrete suggestion for how to improve or fix the issue
+- `--need`: for every finding that is not `helps`, what you needed at that moment, in your own terms as the persona ("I needed to know the code was wrong before I submitted")
+- `--description`: markdown body describing what happened and why it mattered
+
+**Record the need, never the fix.** You are outside the product: you cannot see its code or know what it would take to change. Write what you needed, not how the screen should change, and keep solutions out of the description too ("add inline validation" is a fix; "I needed to know before I pressed Send" is a need). A separate advisor reads the code after the walk and writes the fix from your need.
 
 Leave `triage_status` alone; triage is not the walker's job.
 

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

@@ -61,7 +61,7 @@ Ask whether to pick one up. When the user picks a request:
 
 ### 2. List mode: present open findings grouped by scenario
 
-Read all `.md` files in `iamu/findings/` directory. Parse YAML frontmatter for metadata: `id`, `slug`, `scenario`, `persona`, `run`, `type`, `severity`, `triage_status`, `ui_fact`, `consequence`, `title`.
+Run `iamu findings --open --json`. Each finding carries `slug`, `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
 
 Filter to `triage_status: open`.
 
@@ -73,18 +73,22 @@ Filter to `triage_status: open`.
 
 A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
 
-Group by `scenario` field and render with an executive tally header, followed by a compact, severity-sorted 1-line list per finding (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
+**Directions before findings.** Run `iamu directions --json`. Directions are structural changes the advisor proposed after a walk, each absorbing several findings (sometimes across scenarios), with the people it could hurt and the scenarios to re-run. If any are `proposed` or `accepted`, show them above the tally, one line each: `◆ <title> (<size>, <status>) · absorbs <N> findings in <S> scenarios · could hurt: <scenarios or "none predicted">`. Offer them first: taking a direction fixes its findings together, which beats patching them one by one. For each the user can **take it** (`iamu directions set <slug> --status accepted`, then implement it, or hand it to planning when it is `large`), take **only the local fixes** (leave it `proposed`, triage its findings below), **defer**, or **reject** (`--status rejected`; it is never proposed again). When a taken direction is implemented, mark it `done` and offer `iamu-run` for every scenario in its `verify` list. Reach is a prediction: say "likely" and "could", never "will".
 
-```
-Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
-Awaiting verification: <K> addressed findings pending re-run
+When open findings span three or more scenarios and there are no open directions, or the user asks what to change first, offer a project synthesis: `iamu advise --project --json`, dispatch a thorough-tier subagent with `iamu/.analysis/advise_prompt.md` as its only context, and record its answer with `iamu advise-record --project --data '<json>'`. It proposes directions across every scenario.
 
-▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
-1. [CRITICAL · hinders] Handoff list is cluttered (Step <N>)
-2. [MAJOR · missing] No visible confirmation after shift submit (Step <N>)
-```
+Render it as Markdown, not inside a code fence, so the tables render. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
+
+**<N> open problems** (<C> critical · <M> major · <m> minor) across <S> scenarios · <K> fixes awaiting a re-run
+
+### <persona> · <situation> — **<NO / PARTIAL / YES>**
+<the scenario's latest `summary.verdict.answer`, first sentence or two>
 
-**ANTI-BLOAT DIRECTIVE:** Do NOT dump persona quotes, evidence URLs, or recommendations into the overview tally. Keep it strictly 1 line per finding so the user can scan it in 3 seconds.
+| # | Finding | Severity | Where | What to do |
+|---|---|---|---|---|
+| 1 | <title> | **Critical** | <where> | <first sentence of recommendation, or — > |
+
+Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → observation; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out of the tables. Keep the "What to do" cell to one sentence: the full recommendation belongs in the finding card (step 3).
 
 Ask the user how they would like to triage:
 
@@ -112,6 +116,10 @@ Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter (
 
 Synthesize a scannable triage summary. Do NOT output an undifferentiated wall of bullets or academic schema labels like "UI Fact:". The reviewer must be able to parse **What is broken** and **What to fix** in under 3 seconds.
 
+**Advised findings are shown as they are.** When the frontmatter has `advised_by`, the recommendation was written after the walk by the advisor, from the code and the persona's need; a `**Part of:**` line names the direction it belongs to. Show it as is, and before applying it read `iamu/.runs/<run>/advice.json` and check that each `builds_on` file still exists and contains its symbol; if not, say the advice is stale before editing.
+
+**Raise the recommendation before you show it** (only when there is no `advised_by`: older runs, findings pulled from the cloud, or runs whose advisor stage did not run). The walker wrote it without seeing the code, and it often patches the symptom. Ask what the products that handle this moment best would do for this persona — the established pattern and why it works, not a brand name. Then take a quick look at what this codebase can build that on: existing components, data already on the screen, the design system. Show the strongest fix that fits this project. When it is a bigger change than the walker's proposal, keep a small step that helps now as the quick fix. When the walker's proposal is already the right one, show it as is. Never recommend what the project cannot support without saying what it would take. Your reasoning stays out of the card — it is what "Discuss" is for.
+
 Format the visible finding in chat:
 
 ```markdown
@@ -123,7 +131,8 @@ Format the visible finding in chat:
 <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
 
 **💡 Recommendation:**
-<Concrete fix proposal from finding body>
+<The strongest fix that fits this project, grounded in the finding and the code>
+<Only when the recommendation is a bigger change: *Quick fix:* <small step that helps now>>
 ```
 *(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
 
@@ -236,7 +245,7 @@ If `<N> > 0` findings were queued for fix:
     Proceeding with code edits — say "done" to keep fixes open in iamu/findings/.
 
 - **Executing the queued fixes:**
-  When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+  When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace — the fix shown on its card or agreed in Discuss, not the walker's original text. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
   Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Closed-Loop Regression Verification (1-Click):**

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

@@ -329,10 +329,10 @@ Step files live at `iamu/.runs/<run-id>/steps/<NNN>.json`. The CLI manages monot
 
 **Recording findings:**
 
-Use the CLI to create findings with valid frontmatter, UUID, slug, description, and recommendation in one atomic call:
+Use the CLI to create findings with valid frontmatter, UUID, slug, need and description in one atomic call (the walker records what the persona needed, never the fix; the advisor writes the fix in step C2):
 
 ```bash
-iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --description "Detailed markdown description" --recommendation "Concrete fix proposal" --json
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
 This generates a valid UUID, derives the slug from the title, and writes the complete finding file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`. Never invoke host Edit or Write tools.
@@ -397,7 +397,23 @@ iamu evaluate-record <run-id> --data '<raw_verdicts_json>' --no-prompt --no-push
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
-**D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including verification delta (if a prior run exists). Use this for step 5 presentation.
+**C2. Advise: fixes and directions.** Get the advisor prompt:
+
+```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`:
+
+```bash
+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.
+
+**D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including the verification delta (if a prior run exists) and `analysis.directions` (if the advisor ran). Use this for step 5 presentation.
 
 **E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
 
@@ -415,7 +431,7 @@ It prints the URL only if the run is on the cloud; otherwise it exits 1 and says
 
 In linked-no-credentials or local-only mode, skip E.
 
-Only after A→E are complete, proceed to step 5.
+Only after A→E (with C2) are complete, proceed to step 5.
 
 ### 4a. Walk methodology summary
 
@@ -427,42 +443,68 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 5. Present assessment — stay in the conversation
 
-You MUST output the complete Executive Scorecard to the chat stream FIRST. Output as rich Markdown (do NOT wrap the entire summary in code fences so links render as clickable):
+You MUST output the complete Executive Scorecard to the chat stream FIRST. Build it from `iamu report <scenario-slug> --json`: the first row is this run, and its `summary` holds everything below already assembled (verdict, per-test labels, the since-last-run outcome of each earlier finding, findings with titles, where and recommendations, directions, observations). Do not re-read `canonical.json` or `verdicts.json` yourself. Output rich Markdown, not inside a code fence, so tables render and links are clickable:
+
+### <summary.persona> · <summary.situation>
+<summary.steps> steps · [Open in Iamu Cloud](<summary.cloud>) *(local-only: `[report.md](iamu/.runs/<run-id>/report.md)`)*
 
-### Walkthrough Complete: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
-**Verdict:** <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (<StepCount> steps)
+> **<summary.verdict.question>** **<summary.verdict.label>**
+> <summary.verdict.answer>
 
-> 🎯 **Human Test Checkpoint:**
-> **Question:** "<human_tests[0].question>"
-> **Verdict:** **<NO / PARTIAL / YES>** — <1-2 sentences evaluator reasoning from verdicts.json / report.md>
+If `summary.tests` has more than one test, add one line per test: `**<label>** · <question>`.
 
-> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open <run-id> --print>)
-*(If local-only, render instead: `> **Artifact:** [iamu/.runs/<run-id>/report.md](iamu/.runs/<run-id>/report.md) (Local only)`)*
+If `summary.since` is set, show what happened to every earlier finding this run re-checked (`summary.since.items`), then one line for the new ones:
 
-#### Findings Overview:
-1. **[CRITICAL]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
-2. **[MAJOR]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
-...
-(Helps: • [helps] <short title> (Step <N>))
+**Since the last run** (<date of summary.since.baselineAt>)
 
-(If canonical.json contains a `verification` section, include a 1-line delta: `Since last run: ✓ <N> fixed · ✗ <M> persist · + <K> new`.)
+| Earlier finding | Now |
+|---|---|
+| <title> | ✓ Resolved / ✗ Persists / ○ Not seen / ? Unclear |
 
-Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the scorecard scannable.
+`+ <summary.since.added> new problems this run.` "Not seen" means the walk did not pass that way: never call it fixed.
+
+**Findings** (<N> problems, <K> strengths), worst first:
+
+| # | Finding | Severity | Where | What to do |
+|---|---|---|---|---|
+| 1 | <title> | **Major** | <where> | <first sentence or two of recommendation, or — > |
+
+Mark a finding that persists from the last run with `(persists)` after its title. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
+
+If `summary.directions` is non-empty:
+
+**Directions** (structural changes the advisor proposes)
+
+| Direction | Size | Absorbs | Re-run to check |
+|---|---|---|---|
+| <title> | <size> | <absorbs> findings | <verify> scenarios |
+
+Reach is a prediction until those scenarios run again.
+
+If `summary.observations` is non-empty, end with **Also worth knowing**: one bullet each, `Not walked: <title>` (coverage_gap) or `Risk: <title>` (feature_risk).
+
+Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the scorecard scannable: the tables are the summary.
 
 **Zero-Friction Triage Transition (Eliminate Meta-Prompt Gate):**
 Do NOT prompt the user with a generic "How would you like to proceed?" multiple-choice modal. That intermediate prompt adds cognitive friction, duplicates the triage options, and obscures the assessment scorecard.
 
-- **If `<F> == 0` (Walkthrough Passed):**
-  Output: "✓ Walkthrough passed with zero friction points or blockers. Scenario validated successfully."
+- **If `summary.findings` is empty (no problems):**
+  Output: "No problems found in this run." The verdict above still stands on its own: a run without findings can still answer NO.
   Do not enter triage.
 
-- **If `<F> > 0` (Walkthrough Has Findings):**
+- **If `summary.findings` is not empty:**
   Output the Executive Scorecard above to chat FIRST, and advance IMMEDIATELY to triage on **Finding #1 of <total>** (Step 6 below) in the same turn. The user can choose to queue to fix, queue all remaining fixes (batch accept), dismiss, or discuss directly from Finding #1.
 
 ### 6. Conversational Triage & Guided Review
 
 The conversation is the triage surface. Do NOT eject the user to manual CLI commands or dump them at file paths.
 
+**Directions come first.** When the advisor proposed directions, offer them before going finding by finding, one at a time: what changes for the person, which findings it absorbs (in this and other scenarios), who it could hurt, and the size. The user chooses:
+- **Take it**: `iamu directions set <slug> --status accepted`, then implement it (or hand it to planning when it is large). The findings it absorbs are fixed by the direction, not patched one by one.
+- **Only the local fixes**: leave the direction `proposed` and triage its findings normally below.
+- **Defer** (leave `proposed`) or **reject** (`iamu directions set <slug> --status rejected`; it will not be proposed again).
+After a taken direction lands, mark it `done` and re-run the scenarios in its `verify` list, not only this one.
+
 #### A. Guided One-by-One Review ("walk through them" / "review one by one")
 When the user asks to review findings one by one:
 1. **Present Finding #N in a scannable format (High Visual Hierarchy):**
@@ -608,4 +650,4 @@ Run `iamu validate --all` to verify all entities before reporting done. If older
 - **Validate before done.** Always run `iamu validate --all` after a walkthrough to catch any issues.
 - **Use CLI for scaffolding.** `iamu start-run` for runs, `iamu new-finding` for findings, `iamu complete` for assembly. Never manually create run directories or generate UUIDs.
 - **Step files:** Record steps via the CLI (`iamu browse step` or `iamu step`), which manages step numbering, screenshots, and atomic writes to `steps/001.json`.
-- **Finding bodies:** After `iamu new-finding` scaffolds the file, edit the file to add the description and recommendation below the frontmatter.
+- **Finding bodies:** `iamu new-finding` writes the description; the recommendation is written by `iamu advise-record` (step C2), never by the walker.

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

@@ -0,0 +1,87 @@
+export interface HtmlReportHighlight {
+    targetBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        viewport_width?: number;
+        viewport_height?: number;
+    };
+    label?: string;
+    severity?: string | null;
+    type?: string;
+}
+export interface HtmlReportStep {
+    stepNumber: number;
+    action: string;
+    screenTitle?: string | null;
+    personaReasoning?: string | null;
+    url?: string | null;
+    screenshotUrl?: string | null;
+    targetBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        viewport_width?: number;
+        viewport_height?: number;
+    } | null;
+    highlights?: HtmlReportHighlight[];
+}
+export interface HtmlReportFinding {
+    id: string;
+    title: string;
+    type: string;
+    severity?: string | null;
+    uiFact?: string | null;
+    consequence?: string | null;
+    recommendation?: string | null;
+}
+export interface HtmlReportVerdict {
+    question: string;
+    rating: string;
+    reasoning?: string;
+}
+export interface HtmlReportVerification {
+    resolved: unknown[];
+    persists: unknown[];
+    newFindings: unknown[];
+}
+export interface HtmlReportData {
+    scenarioName: string;
+    scenarioNarrative?: string | null;
+    persona?: {
+        name: string;
+        role?: string | null;
+        context?: string | null;
+    } | null;
+    walkthroughId: string;
+    runNumber?: number | string | null;
+    startedAt?: string | null | Date;
+    completedAt?: string | null | Date;
+    targetUrl?: string | null;
+    steps: HtmlReportStep[];
+    findings: HtmlReportFinding[];
+    verdicts?: HtmlReportVerdict[];
+    verification?: HtmlReportVerification | null;
+    whatWorked?: string[];
+    openQuestions?: string[];
+}
+export declare function generateHtmlReport(data: HtmlReportData): string;
+/**
+ * Builds HtmlReportData by reading a completed run directory and resolving
+ * persona/scenario files and local screenshots into base64 data URIs.
+ */
+export declare function buildReportDataFromRun(projectRoot: string, runId: string): Promise<HtmlReportData>;
+/**
+ * Creates and writes a self-contained local HTML report for a walkthrough run.
+ * Defaults to writing to `iamu/.runs/<runId>/report.html`.
+ */
+export declare function createLocalHtmlReport(projectRoot: string, runId: string, destination?: string): Promise<{
+    filePath: string;
+    html: string;
+}>;

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

@@ -0,0 +1,95 @@
+export type VerdictLabel = "YES" | "PARTIAL" | "NO" | "PENDING" | "BLOCKED";
+export interface RunFindingRow {
+    id: string;
+    /** Finding file slug, for `iamu triage <slug>`; null when the file is gone. */
+    slug: string | null;
+    severity: string | null;
+    type: string;
+    title: string;
+    where: string | null;
+    /** The advisor's recommendation, when the run was advised. */
+    recommendation: string | null;
+    persists: boolean;
+    isNew: boolean;
+}
+export type SinceOutcome = "resolved" | "persists" | "not_seen" | "uncertain";
+export interface RunView {
+    persona: string;
+    situation: string;
+    completedAt: string | null;
+    steps: number;
+    targetUrl: string | null;
+    /** Cloud link, or a note that the run is not synced; null when not linked. */
+    cloud: string | null;
+    verdict: {
+        label: VerdictLabel;
+        question: string | null;
+        answer: string | null;
+    };
+    tests: Array<{
+        question: string;
+        label: VerdictLabel;
+    }>;
+    since: {
+        baselineAt: string | null;
+        resolved: number;
+        persists: number;
+        added: number;
+        notSeen: number;
+        /** Each earlier finding this run re-checked, by title. */
+        items: Array<{
+            title: string;
+            outcome: SinceOutcome;
+        }>;
+    } | null;
+    findings: RunFindingRow[];
+    strengths: string[];
+    directions: Array<{
+        title: string;
+        size: string;
+        absorbs: number;
+        verify: number;
+    }>;
+    observations: Array<{
+        kind: string;
+        title: string;
+    }>;
+}
+export interface OverviewRun {
+    completedAt: string | null;
+    label: VerdictLabel;
+    problems: number;
+    resolved: number;
+    persists: number;
+    added: number;
+}
+export interface OverviewScenario {
+    persona: string;
+    situation: string;
+    slug: string;
+    runs: OverviewRun[];
+    latestAnswer: string | null;
+}
+export interface OverviewView {
+    project: string;
+    scenarios: OverviewScenario[];
+    openProblems: number;
+    directions: Array<{
+        title: string;
+        status: string;
+        size: string;
+        absorbs: number;
+    }>;
+}
+export declare function verdictColor(label: VerdictLabel): (s: string) => string;
+/** "9 Oct 07:54" in local time; the raw value when it does not parse. */
+export declare function shortDate(iso: string | null): string;
+/** Word-wrap plain text to `width`, each line prefixed with `indent`. */
+export declare function wrap(text: string, width: number, indent: string): string[];
+export declare function firstSentence(text: string): string;
+/** Opening sentences of a text, enough to say something (≥ 60 chars). */
+export declare function lead(text: string): string;
+/** The latest run of one scenario, outcome first. */
+export declare function renderRunView(v: RunView, width?: number): string[];
+/** Every scenario and how its runs went, newest scenario first. */
+export declare function renderOverview(v: OverviewView, width?: number): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.3.0-beta.6",
+  "version": "0.4.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,9 +58,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
+    "@iamu-dev/local-store": "0.1.0",
     "@iamu-dev/protocol": "0.1.0",
-    "@iamu/tsconfig": "0.1.0",
-    "@iamu-dev/local-store": "0.1.0"
+    "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",