@iamu-dev/iamu 0.2.0-beta.9 → 0.3.0-beta.1

package/dist/sync-mcp/fatal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fatal-error reporting for the sync MCP server entry point.
+ *
+ * stdout is the MCP stdio transport, so a diagnostic printed there would
+ * corrupt the protocol stream. Everything here writes to stderr only.
+ */
+/** Side effects a fatal report needs, injectable so it can be tested. */
+export interface FatalDeps {
+    /** Write a diagnostic line — stderr, never stdout. */
+    writeErr: (text: string) => void;
+    /** Terminate the process with the given exit code. */
+    exit: (code: number) => void;
+}
+/**
+ * Describe a fatal error, with its stack when there is one.
+ *
+ * @example
+ * ```ts
+ * formatFatal("uncaughtException", new Error("boom"));
+ * // "iamu sync-server: fatal uncaughtException: boom\n…stack…\n"
+ * ```
+ */
+export declare function formatFatal(kind: string, err: unknown): string;
+/**
+ * Report a fatal error on stderr and exit non-zero.
+ *
+ * @example
+ * ```ts
+ * handleFatal("uncaughtException", err, deps);
+ * ```
+ */
+export declare function handleFatal(kind: string, err: unknown, deps?: FatalDeps): void;
+/**
+ * Install `uncaughtException` / `unhandledRejection` handlers that log
+ * to stderr before exiting, instead of dying silently with code 1.
+ *
+ * @example
+ * ```ts
+ * installFatalHandlers();
+ * ```
+ */
+export declare function installFatalHandlers(deps?: FatalDeps): void;

package/dist/sync-mcp/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync-mcp/tools.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Build the `iamu-sync` MCP server: push, pull, auth status, and
+ * background change polling over the local `iamu/` project tree.
+ *
+ * @example
+ * ```ts
+ * const server = createSyncServer();
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+export declare function createSyncServer(): McpServer;

package/dist/templates/prompts/walk.md

@@ -26,6 +26,16 @@ The persona has never seen this product's source code, its design docs, its issu
 
 A finding you could only have made by reading code is not a walkthrough finding. Drop it.
 
+## Strict Operational Capability Fence
+
+<CAPABILITY_FENCE>
+You are an observational walker subagent ONLY:
+1. ZERO WRITE ACCESS: You are strictly forbidden from modifying, editing, patching, creating, or deleting project source files, tests, configs, or documents. You have no file editing tools for repository files.
+2. ZERO CODE FIXING: Even if you spot a trivial typo, CSS bug, or broken link in the product, you must NEVER attempt to fix it in the codebase. Your only job is to record it as an iamu finding.
+3. COMMAND WHITELIST: You may only execute `iamu browse ...`, `iamu step ...`, `iamu new-finding ...`, and `iamu summary ...`. Do not run git commits, builds, tests, or file mutations.
+4. CHILD SESSION SUPPRESSION: Do not load parent workflow skills, triage routines, or setup flows. Do not run `iamu triage`, `iamu new`, or `iamu init`. Your sole task is walking the screen and recording steps.
+</CAPABILITY_FENCE>
+
 ## Five observation categories
 
 At every significant screen, observe through all five lenses:
@@ -80,6 +90,20 @@ Follow the persona's motivation. Spend time on what matters to them. When you ha
 
 Browser failures — blank page, stuck spinner, cryptic error, 404 — are signal, not noise. Screenshot the failure state, record it as a finding, move on. Do not retry silently or open developer tools: the persona cannot.
 
+If a step command fails with `The user stopped this run from the live viewer. End the walk now.`, do not retry or continue: stop the walkthrough immediately and proceed to Synthesis with what you observed so far.
+
+## Human intervention (CAPTCHA, 2FA, & blocking walls)
+
+When an anti-bot challenge (Cloudflare Turnstile, Google reCAPTCHA, hCaptcha), SMS/email two-factor authentication (2FA), or interactive security gate appears:
+- **Do NOT record a product bug:** Security challenges and bot mitigation are operational hurdles, not product UX defects.
+- **Request human intervention:** In an interactive session with a human present (visible Chrome window), pause and ask the human in chat to solve the challenge or complete the 2FA prompt in the open browser window.
+- **Wait and verify:** After the human completes the verification, run:
+  ```bash
+  iamu browse step --run <run-id> --action "Waited for human verification" wait 3000
+  ```
+  Take a fresh snapshot to verify the page cleared the gate, and continue walking.
+- **Headless / Unattended environments:** If running headless or in CI where no human is available, do not hang in infinite loops. Record the block in your step notes, finish the run with `--blocked`, and proceed to Synthesis.
+
 ## Tooling limitations vs product bugs
 
 Your browser tooling has limitations that can look like product bugs. Before recording a finding, ask: "Is this a real product issue, or is my tooling failing?"
@@ -87,12 +111,12 @@ Your browser tooling has limitations that can look like product bugs. Before rec
 **Signs of tooling limitation (NOT a product bug):**
 - Navigation to a URL works in a real browser but the tool reports a blank page or redirect loop
 - A click triggers client-side routing but the tool reports "bounced to dashboard" or the URL didn't change
-- A dropdown/select appears empty but evaluating `document.querySelectorAll('[role="option"]')` in the page returns elements
+- A dropdown/select appears empty in accessibility snapshot but rendered controls appear in indexed element inspection
 - Screenshots show content that contradicts what the accessibility snapshot reports
 
 **When you suspect a tooling issue:**
 1. Try the interaction a different way (keyboard instead of click, direct URL instead of navigation)
-2. Use your tool's script-evaluation action to inspect the real DOM state
+2. Inspect interactive elements (e.g. using indexed element inspection) to view rendered controls and available indices
 3. Take a screenshot — if the screenshot shows the UI working but the tool reports failure, it's a tooling issue
 4. If still unclear, record the finding but note in the `consequence` field: "May be a browser tooling limitation — verify in a real browser"
 
@@ -114,7 +138,7 @@ Your prompt may include an approximation strategy (e.g. "If Malmö is missing, c
 
 ## Portal-rendered UI
 
-Radix / Headless UI / Floating UI render dropdowns and listboxes into portals that do not appear in accessibility snapshots. If an expandable combobox looks empty after click, try: press ArrowDown then Enter, or evaluate a script in the page to probe the DOM. Take a fresh screenshot.
+Radix / Headless UI / Floating UI render dropdowns and listboxes into portals that do not appear in accessibility snapshots. If an expandable combobox looks empty after click, try: press ArrowDown then Enter, or re-run an indexed snapshot to inspect rendered portal elements. Take a fresh screenshot.
 
 Progressive disclosure is normal. Before recording a `missing` finding, verify by interacting through at least one round of the form's progressive steps.
 
@@ -129,51 +153,52 @@ Your walking prompt has an `## Access` section saying how to become this persona
 
 ## Recording
 
-**Steps:** Write each step as a separate file using the Write tool:
-
-Path: `iamu/.runs/<run-id>/steps/<NNN>.json` (zero-padded, e.g., `001.json`, `002.json`)
-
-```json
-{
-  "step_number": 1,
-  "timestamp": "2026-04-27T10:00:00Z",
-  "action": "Opened dashboard",
-  "note": "First thing I see is...",
-  "screenshot": "screenshots/step-1.png",
-  "url": "https://app.example.com/dashboard",
-  "surface": "dashboard overview"
-}
-```
+**Steps:** Record each step atomically via the CLI — never hand-craft raw JSON step files with custom scripts or host Write tools:
 
-`url` is the page you are on when the step ends — copy it from your driving surface (`iamu browse` prints it after every action), never reconstruct it. Record it on every step; it is how findings are grouped by page. Only a native app with no URL leaves it out.
+- For `iamu browse`:
+  ```bash
+  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...]
+  ```
+  Commands: `click <role> "<name>"`, `click-text "<text>"`, `click-index <N>`, `fill <role> "<name>" "<text>"`, `fill-index <N> "<text>"`, `select <role> "<name>" "<val>"`, `upload <role> "<name>" "<file-path>"`, `upload-index <N> "<file-path>"`, `press <key>`, `scroll [px]`, `back`, `shot`, `wait [ms]`.
+  When accessibility names are ambiguous, missing, or broken, inspect indexed interactive elements and drive via `click-index <N>`, `fill-index <N> "<text>"`, or `upload-index <N> "<file-path>"`.
+  When a link or button opens a new window/tab (`target="_blank"`), manage tabs via `tabs`, `switch-tab <index>`, and `close-tab [index]`.
+- For other surfaces:
+  ```bash
+  iamu step --run <run-id> --action "<action>" --note "<first-person monologue>" [--shot <screenshot-path>] [--url <url>]
+  ```
 
-`surface` is optional: a short name for the screen in the product's own words (`search results`, `checkout — payment`), not a description of what happened.
+`action` is what you did (e.g. "Clicked Checkout button").
+`note` is your internal first-person persona reaction in character.
+The CLI automatically handles sequential numbering, timestamps, screenshot capture/linking, and live event streaming.
 
-`timestamp` is the real time of the step — you have no clock of your own, so read it with `date -u +%Y-%m-%dT%H:%M:%SZ` rather than inventing one. Made-up times make a run impossible to line up with server logs.
-
-One file per step. No appending. The Write tool creates the file without permission prompts.
-
-**Findings:** Always scaffold with the CLI — never create a finding file by hand, never invent an id:
+**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 --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 --description "Detailed markdown description of the issue" --recommendation "Concrete fix proposal" --json
 ```
 
-`--type` is one of `helps | hinders | missing | irrelevant | incorrect`. `--severity` is one of `critical | major | minor | observation`. They are different axes — a type is never a severity.
+- `--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
 
-Two more axes, both required on every finding:
+Leave `triage_status` alone; triage is not the walker's job.
 
-- `--task-impact` — what this does to the persona's task right now: `blocks` (cannot finish), `impairs` (finishes worse — wrong result, lost trust), `slows` (finishes, with needless effort), `neutral`, `accelerates` (faster than they expected), `enables` (could not have done it otherwise). A `helps` finding is `neutral`, `accelerates` or `enables`; a problem is never `accelerates` or `enables`.
-- `--confidence` — how sure you are this is real for this persona: `high` (you saw it on screen, clearly), `medium` (you saw it, but the persona might read it differently), `low` (it may be your tooling — say so in `consequence`). Then use the Edit tool to add the description and a `## Recommendation` section below the frontmatter. Leave `triage_status` alone; triage is not the walker's job.
+**Screenshots:** Screenshots are captured automatically by `iamu browse step`. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
 
-**Screenshots:** Save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` (pass an absolute path — some browser tools reject relative ones) before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking. A walkthrough with snapshots is better than no walkthrough.
-
-Use the Write tool for step files. Never use bash `cat`, `echo`, or heredocs to write files.
+**Execution rule:** Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.
 
 ## Synthesis
 
-After walking, compile:
-- **What worked** — Things the system did well for this persona. Important to preserve.
-- **Open questions** — Questions that arose that need discussion.
+After walking, record your synthesis using the CLI:
+
+```bash
+iamu summary <run-id> --worked "What worked well 1" --worked "What worked well 2" --question "Open question 1"
+```
+
+- `--worked` — Things the system did well for this persona. Important to preserve.
+- `--question` — Questions that arose that need discussion.
 
-Then return your summary so the orchestrating agent can run `iamu complete` and the evaluation stage.
+Then return your final summary to the orchestrating agent so it can run `iamu complete` and the evaluation stage.

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

@@ -1,6 +1,6 @@
 ---
 name: iamu-findings
-description: Triage findings from past walkthroughs — list open findings, review one in depth, act on them (keep / fix / dismiss / rescope). Terminal-complete; dashboard optional.
+description: Use when triaging, reviewing, listing, or resolving findings, bugs, UX friction, or issues discovered during walkthroughs, or when the user asks "what broke?", "show findings", or "review issues".
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -16,12 +16,18 @@ Before starting, check that `iamu/` exists with findings to review. If `iamu/` d
 
 ## Steps
 
-### 1. Resolve the argument
+### 1. Resolve target and scope
 
-Two paths based on `$ARGUMENTS`:
+Follow this precedence cascade:
 
-- **Finding slug or UUID** → skip to step 3 (direct triage).
-- **No arg** → continue to step 2 (list mode).
+- **Explicit finding slug or UUID** → skip to step 3 (direct triage of this finding).
+- **Active session context (Recent Walkthrough / Active Scenario):**
+  If a walkthrough run just completed in this session, or the user asks to review/triage findings right after running a scenario (e.g. "what did we find?", "triage findings", "show findings"):
+  - Filter list mode to that run or scenario's open findings by default (or if only 1–2 open findings exist from the run, jump directly to step 3).
+  - Note clearly: `(Showing open findings for recently completed run <run-id> / scenario <slug>. Use iamu-findings --all to view all scenarios)`.
+- **No argument & No active session walkthrough** →
+  - **Single-Entity Auto-Selection (Zero-Prompt Fast Path):** If only 1 open finding exists in the project, skip directly to step 3 (direct triage of this finding).
+  - Otherwise, continue to step 2 (global list mode across all scenarios).
 
 **Cloud state** (either path). Run `iamu auth status --json` once:
 
@@ -67,62 +73,113 @@ 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 severity-sorted list per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last), including persona quotes, evidence, and clickable file links:
+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):
 
 ```
 Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
 Awaiting verification: <K> addressed findings pending re-run
 
 ▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
-1. [CRITICAL · hinders] Handoff list is cluttered ([file](iamu/findings/<slug>.md))
-   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
-   • Evidence: Step <N> at <url>
-   • Recommendation: Add status filter chips
-
-2. [MAJOR · missing] No visible confirmation after shift submit ([file](iamu/findings/<slug>.md))
-   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
-   • Evidence: Step <N> at <url>
-   • Recommendation: Show inline success toast
+1. [CRITICAL · hinders] Handoff list is cluttered (Step <N>)
+2. [MAJOR · missing] No visible confirmation after shift submit (Step <N>)
 ```
 
+**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.
+
 Ask the user how they would like to triage:
 
-- **"walk through them"** → iterate through all open findings one-by-one in order with full context, code location, and triage choices (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
+- **"walk through them"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
 - **"all critical"** → iterate through all critical findings in order.
 - **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
 - **Single number or slug** → single finding (skip to step 3).
 - **"fix 1 and 2"** → make code fixes and mark addressed immediately.
 - **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
 
+**Interactive Triage Strategy:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "How would you like to review these <N> open findings?"
+  - Options:
+    1. "[Recommended] Walk through findings one by one"
+    2. "Focus only on Critical findings (<C> items)"
+    3. "Review by scenario group: <Top Scenario>"
+- Otherwise (in CLI or text-only environments):
+
+How would you like to triage these <N> open findings?
+  1. [Recommended] Walk through findings one by one
+  2. Focus only on Critical findings (<C> items)
+  3. Review by scenario group: <Top Scenario>
+
+Reply '1' to walk through all [default], select 2-3, or enter a finding number/slug:
+
 ### 3. Direct triage: review one finding
 
-Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Render full detail with clickable links and evidence:
+Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter (`severity`, `type`, `title`, `ui_fact`, `consequence`, `persona`, `walkthrough_step_id`, `screen_title`, `page_url`, `run`) and markdown body (description and recommendation).
 
-```
-Finding: <title> ([file](iamu/findings/<slug>.md))
-Scenario: [<scenario>](iamu/scenarios/<scenario>.md)
-Severity: <severity> · Type: <type> · Status: <triage_status>
+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.
 
-Persona Quote: "<persona_reaction_or_consequence>"
-UI Fact: <ui_fact>
-Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run>/screenshots/<NNN>.png))
+Format the visible finding in chat:
 
-Description:
-<markdown body above ## Recommendation>
+```markdown
+### Finding #<N>/<total> [<SEVERITY>] — <title>
+> **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
+> **Evidence:** `iamu/.runs/<run>/screenshots/step-<N>.png` [Dashboard](<url if cloud_linked>)
 
-Recommendation:
-<## Recommendation section, or "none">
+**❌ Problem:**
+<What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
 
-Report: [report.md](iamu/.runs/<run>/report.md)
+**💡 Recommendation:**
+<Concrete fix proposal from finding body>
 ```
 
-If the finding references a run directory, mention the report path for context. If the user wants to see the screenshot, read from `iamu/.runs/<run>/screenshots/`.
+If the project is cloud-linked, include the link to the finding in Iamu Cloud (from `iamu open --print`).
+
+Emit this card visibly into the conversation.
 
 ### 4. Prompt for triage action
 
-Ask: "What should happen with this finding?"
+Every finding must land on a decision — never silently skip. Match the user's intent to the closest option.
+
+**CRITICAL: Embed Scannable Finding in Interactive Prompt Modals:**
+Host interactive tools (e.g. `ask_question`, `ask_followup_question`) render a modal that obscures the terminal and displays ONLY the tool's `question` argument. **Embed this exact scannable structure inside the `question` argument** with blank lines separating the sections:
+
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - **Question:**
+    """
+    Finding #<N>/<total> [<SEVERITY>]: <title>
+    Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
+
+    ❌ PROBLEM:
+    <What is broken or awkward on screen and why it hinders the persona in 1–2 direct sentences>
+
+    💡 RECOMMENDATION:
+    <Concrete fix proposal from finding body>
 
-Every finding must land on a decision — never silently skip. The six options below cover the real workflow: two that chain into code changes, one that parks with context, two that close with rationale (an accepted trade-off, or never a problem at all), one that leaves it for later review. Match the user's intent to the closest option; do not shoe-horn.
+    How should we triage this finding?
+    """
+  - **Options:**
+    1. "[Recommended] Queue to fix (<brief 3-5 word fix summary>)"
+    2. "Dismiss / Skip (<brief reason if obvious, e.g. keep current design>)"
+    3. "Discuss / Explore trade-offs"
+    4. "Fix immediately (leave triage now)"
+    5. "Next finding (keep open / defer)"
+- Otherwise (in CLI or text-only environments):
+
+Finding #<N>/<total> [<SEVERITY>]: <title>
+Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
+
+❌ PROBLEM:
+<What went wrong and why it hinders the persona in 1–2 direct sentences>
+
+💡 RECOMMENDATION:
+<Concrete fix proposal>
+
+  1. [Recommended] Queue to fix (<brief 3-5 word fix summary>)
+  2. Dismiss / Skip (not relevant or walker error)
+  3. Discuss / Explore trade-offs
+  4. Fix immediately (leave triage now)
+  5. Next finding (keep open / defer)
+
+Reply '1' to queue fix [default], enter 2-5, or describe your decision:
 
 Record the decision with `iamu triage` — it sets `triage_status` and `triage_note` in `iamu/findings/<slug>.md`, and for a dismissal it also teaches the next walk:
 
@@ -137,7 +194,12 @@ triage_status: addressed
 triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 ```
 
-- **Fix now** → the change is small, one-or-two files, no architectural decision needed (label, field made optional, filter added, typo). Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then update frontmatter: `triage_status: addressed` with a one-line change summary in `triage_note`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
+- **Discuss / Explore trade-offs (Conversational Dialogue Mode — NO MODAL LOOPS)** → when the user chooses "Discuss", asks a question, or wants to explore architectural trade-offs:
+  **DO NOT invoke `ask_question` or present multiple-choice menus.** Stay in natural conversational chat as a senior pair programmer. Answer follow-up questions, inspect code, benchmark against competitors, and discuss options in plain markdown. Converse naturally back and forth until you reach a conclusion together. Only when a consensus or decision is reached ("let's queue it", "dismiss it", "fix it now"), record the decision and proceed. Do NOT trap the user with modal dialogs after each conversational turn.
+
+- **Queue to fix [Recommended in list-mode]** → add to the session's fix queue. Tell the user in 1 line: "✓ Queued for fix. Advancing to next finding..." and loop to the next finding. Complete the triage queue across all findings first.
+
+- **Fix immediately (leave triage now)** → the change is small, one-or-two files, and user explicitly chose to leave triage now. Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then record: `iamu triage <slug> --status addressed --note "<one-line change summary>"`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
 
 - **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."`.
 
@@ -145,12 +207,19 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **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.
 
-- **Not relevant / walker got it wrong** → the finding should never have been reported. Ask which, because they teach different things:
-  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>"`.
-  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>"`.
+- **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>"`.
   - *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 — future walkthroughs are told not to report this"** and name the rule file. One-word notes ("nope") degrade future runs — name the reason specifically.
+  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."`.
 
@@ -173,21 +242,49 @@ dismissed (not_relevant): <finding-slug>
 
 ### 5. Continue or close
 
-If the user is in list-mode iteration (picked "all critical" or a scenario group), loop to step 3 for the next finding in the queue. Otherwise close.
+If the user is in list-mode iteration (picked "walk through them", "all critical", or a scenario group), loop to step 3 for the next finding in the queue.
 
-Summary at the end (list-mode only):
+When all findings in the queue are triaged, present the summary:
 
-```
+```text
 Triage complete.
-  Fixed: <N>
+  Queued for fix: <N>
   Dismissed: <N>
   Rescoped (design change / defer): <N>
   Kept open: <N>
-
-<X> findings remain open. Use iamu-findings to resume later.
 ```
 
-Run `iamu validate --all` to verify all entities before reporting done.
+If `<N> > 0` findings were queued for fix:
+- Prompt the user:
+  - If interactive tool available:
+    - Question: "Triage complete. Apply fixes for the <N> queued findings now?"
+    - Options:
+      1. "[Recommended] Apply queued fixes in workspace now"
+      2. "Done for now (keep fixes open in iamu/findings/)"
+  - Otherwise (CLI / text-only):
+    Apply fixes for the <N> queued findings now?
+      1. [Recommended] Apply queued fixes in workspace now
+      2. Done for now (keep fixes open in iamu/findings/)
+    Reply '1' to apply fixes [default], or select 2:
+
+- **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>"`.
+  Run `iamu validate --all` to verify all entities before reporting done.
+
+- **Closed-Loop Regression Verification (1-Click):**
+  If the addressed findings belong to a known scenario:
+  - If interactive tool available:
+    - Question: "Fixes applied and validated. Verify them now with a walkthrough re-run?"
+    - Options:
+      1. "[Recommended] Re-run walkthrough for <scenario-slug> to verify fixes hold"
+      2. "Done for now (leave verification for later)"
+  - Otherwise (CLI / text-only):
+    Verify fixes now?
+      1. [Recommended] Re-run walkthrough for <scenario-slug> to verify fixes hold
+      2. Done for now (leave verification for later)
+    Reply '1' to re-run [default], or select 2:
+
+  When Option 1 is chosen, hand off to `iamu-run <scenario-slug>` to re-run the walkthrough, visit the revisit places, verify resolutions in `canonical.json`, and report the verified delta.
 
 ### 6. Publish and link (linked mode only)