@iamu-dev/iamu 0.2.0-beta.7 → 0.3.0-beta.0

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

@@ -1,16 +1,16 @@
 ---
 name: iamu-run
-description: Execute a scenario walkthrough. Accepts scenario slug / UUID / free-form intent / no-arg. Intent chains into iamu-new first, then runs.
+description: Use when executing a persona walkthrough, running or testing a scenario, driving the browser against the product, verifying fixes, or when the user says "run it", "test it", or "walk through the app".
 generatedBy: __IAMU_VERSION__
 ---
 
 Run a scenario against a running product. The walkthrough executes in your agent session using a driving surface you control — a browser MCP for a web product, or the iOS Simulator for a native app — no separate Iamu runner involved for local flows.
 
-This skill resolves what you want to run from your argument:
+This skill resolves what scenario to run following a clear **Target Scenario Resolution Precedence**:
 
-- Scenario slug or UUID → load + execute.
-- Free-form intent ("checkout abandonment", "returning customer friction") → fuzzy-match against existing scenarios; if nothing fits, chain into `iamu-new` to draft first, then execute.
-- No argument → pickable list of scenarios: scenarios that need a re-run first, then drafts and ready-to-run.
+1. **Explicit argument (`$ARGUMENTS`):** Exact slug / UUID, fuzzy slug match, or free-form intent (which chains into `iamu-new`).
+2. **Active conversational context:** When `$ARGUMENTS` is empty or generic (e.g. "it", "that", "this", "run it", "walk it", "go"), and a scenario was created, modified, staged, or discussed in the active session — immediately resolve to that active scenario without prompting or re-scanning.
+3. **No argument & No active session scenario:** Check unfinished runs, then present a prioritized pickable list (reruns needing proof first, then drafts and ready-to-run).
 
 $ARGUMENTS
 
@@ -18,6 +18,8 @@ $ARGUMENTS
 
 Before starting, check that `iamu/context.yml` exists and has `domain` filled in. If it is missing or empty, run the `iamu-setup` skill first — context grounds every walkthrough. If `iamu/` does not exist at all, run `iamu init` first.
 
+**Fast Preflight Type/Lint Gate:** Run `iamu preflight` before booting dev servers or walkers. If syntax, typecheck, or lint checks fail, halt immediately with the compiler diagnostic and fix them before launching the browser. Never burn minutes on a browser session against code that will not compile.
+
 ## Steps
 
 ### 0. Verify a driving surface
@@ -41,16 +43,22 @@ Tell the user in one line which one you picked and why. If the project's own age
 A native app has no URL, and a browser tool is not a substitute for one. If the product is native, the target is a device plus a build (step 3).
 
 If no surface is available, stop and tell the user:
-
-> A walkthrough needs a driving surface. For a web product, `iamu browse` works wherever Chrome or Chromium is installed (or set `IAMU_BROWSER`); a browser-driving MCP that attaches to Chrome also works — restart your agent session after installing one and re-run `iamu-run`. For a native iOS app, a simulator control tool must be available in this session.
+"A walkthrough needs a driving surface. For a web product, `iamu browse` works wherever Chrome or Chromium is installed (or set `IAMU_BROWSER`); a browser-driving MCP that attaches to Chrome also works — restart your agent session after installing one and re-run `iamu-run`. For a native iOS app, a simulator control tool must be available in this session."
 
 Do NOT proceed to step 1 before a driving surface is confirmed.
 
-**Unfinished runs.** Run `iamu status --json` and look at `runs.incomplete`. A run listed there was started but never reached `iamu complete` — the walker died or the session ended — so its steps and findings exist but it has no report, no verdicts, and no delta. If there are any, tell the user how many and offer, once:
+**Unfinished runs.** Only check and offer when `iamu-run` has no explicit argument AND no active scenario exists in the session context. If an explicit scenario slug or intent was passed, OR if an active scenario is resolved from the conversation context, do NOT block execution with this prompt — log at most a single line (`Note: <N> unfinished run(s) pending — use iamu status to inspect`) and proceed directly to step 1.
+
+When `$ARGUMENTS` is empty and no active scenario exists in context, check `iamu status --json` for `runs.incomplete`. If any exist, offer once:
 
-- **Finish** one that has step files: run the post-walk pipeline (step 4, A→B→C→D) on it as it stands. A partial walk with a report is worth more than a complete one nobody assembled.
-- **Discard** ones with no steps: delete the run directory. Runs are ephemeral; findings already written to `iamu/findings/` are kept.
-- **Leave them** and carry on.
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Found <N> unfinished walkthrough run(s). How would you like to handle them?"
+  - Options:
+    1. "[Recommended] Ignore and continue with new run"
+    2. "Finish run `<run-id>`: Run post-walk assembly on existing steps"
+    3. "Discard empty unfinished runs"
+- Otherwise (in text-only/conversational environments), state that you are proceeding with Option 1 by default:
+  "Note: Found <N> unfinished walkthrough run(s). Proceeding with a new run [1]. (Reply 2 to finish run `<run-id>` or 3 to discard empty runs)."
 
 Do not block the new run on this, and do not ask again in the same session.
 
@@ -60,17 +68,23 @@ Do not block the new run on this, and do not ask again in the same session.
 - **Linked, no credentials** (`cloud_linked` true, `authenticated` false) → say once: "This project is cloud-linked, but this machine has no credentials — the run stays local until `iamu auth login`." Continue.
 - **Local-only** → nothing to do here.
 
-### 1. Resolve the argument
+### 1. Resolve the target scenario
 
-Four paths based on `$ARGUMENTS`:
+Follow this precedence cascade:
 
-**UUID or exact slug match** → Read scenario files from `iamu/scenarios/` directory, or run `iamu list scenarios --json`, and match. Load and skip to step 3.
+#### Path 1: Explicit Argument (`$ARGUMENTS` is provided)
+- **UUID or exact slug match** → Read scenario files from `iamu/scenarios/` directory, or run `iamu list scenarios --json`, and match. Load and skip to step 3.
+- **Slug-like arg with no exact match** → Run fuzzy match against existing scenario slugs (simple substring / levenshtein — the agent should judge similarity). If the best match is obviously close (shared two or more tokens), confirm with the user: "Did you mean `<slug>`?" Accept / correct / treat as free-form intent.
+- **Free-form intent string** (quoted or multi-word, no match) → Chain into `iamu-new` with the intent as seed. After `iamu-new` completes and returns a scenario slug, continue here with that slug.
 
-**Slug-like arg with no exact match** → Run fuzzy match against existing scenario slugs (simple substring / levenshtein — the agent should judge similarity). If the best match is obviously close (shared two or more tokens), confirm with the user: "Did you mean `<slug>`?" Accept / correct / treat as free-form intent.
+#### Path 2: Active Session Context (Conversational Anaphora & Recency)
+When `$ARGUMENTS` is empty, generic (e.g. "it", "that", "this", "run", "go"), or the user says "run it" / "walk through it" / "let's test that" / triggers `iamu-run` right after scenario creation, staging, or discussion:
+- **Immediately bind to the active scenario** created, modified, staged, or discussed in the current conversation turn or session.
+- **Do NOT prompt the user or show a selection menu.** State the binding in one sentence (e.g. `Running active scenario maria-gomez--busy-shift...`) and proceed directly to Step 3 (or Step 2 if unbonded draft).
 
-**Free-form intent string** (quoted or multi-word, no match) → Chain into `iamu-new` with the intent as seed. After `iamu-new` completes and returns a scenario slug, continue here with that slug.
-
-**No arg** → Run `iamu status --json` and `iamu list scenarios --json` (or read `iamu/scenarios/`). `rerun` in the status output lists scenarios holding fixes that no later run has proven yet — a fix counts only once a re-run of its scenario shows it working. Present that group first, most awaiting fixes first, with its `reason`; then drafts and ready-to-run (a scenario in the first group is not repeated below):
+#### Path 3: No Argument & No Active Session Scenario (Global Selection)
+When `$ARGUMENTS` is empty and no specific scenario is active in the conversation:
+- Run `iamu status --json` and `iamu list scenarios --json` (or read `iamu/scenarios/`). `rerun` in the status output lists scenarios holding fixes that no later run has proven yet — a fix counts only once a re-run of its scenario shows it working. Present that group first, most awaiting fixes first, with its `reason`; then drafts and ready-to-run (a scenario in the first group is not repeated below):
 
 ```
 Needs a re-run (fixes awaiting proof):
@@ -84,15 +98,34 @@ Ready to run:
   4. dev-patel--checkout-abandon — Abandoned cart x Dev Patel
 ```
 
-Omit the first group when `rerun` is empty. User picks a number or slug. Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
+Omit the first group when `rerun` is empty. If `requests.open` in the status output is above zero, put one line above the list: `Team requests: <N> waiting — iamu-findings picks them up.` Teammates queued those in Iamu Cloud; a verify or run request names the scenario to walk.
+
+- **Single-Entity Auto-Selection (Zero-Prompt Fast Path):**
+  If only one runnable scenario exists in the project (or only one scenario needs a re-run), do NOT present a selection menu or ask for confirmation. Immediately state: `Using scenario: <slug> (sole scenario in project. Override with iamu-run <other>)` and advance directly to Step 3 (or Step 2 if unbonded draft).
 
-If `requests.open` in the status output is above zero, put one line above the list: `Team requests: <N> waiting — iamu-findings picks them up.` Teammates queued those in Iamu Cloud; a verify or run request names the scenario to walk.
+**Interactive Scenario Selection:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it with the top prioritized candidates as selectable options:
+  - Question: "Which scenario would you like to run?"
+  - Options:
+    1. "[Recommended] <Slug or Title>" (e.g. top rerun needing proof, or primary ready scenario)
+    2. "<Alternative Scenario Slug or Title>"
+    3. "Draft a new scenario..."
+- Otherwise, prompt: "Pick a scenario number (1–N), enter a slug, or type an intent to draft a new one."
+
+Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
 
 ### 2. Bind persona (draft path only)
 
 If the resolved scenario has `persona: null`, prompt to bind before executing:
 
-"This scenario is a draft — no persona bound. Pick one, or draft a new persona."
+**Interactive Persona Binding:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "This scenario is a draft with no persona bound. Which persona should walk it?"
+  - Options:
+    1. "[Recommended] <Existing Persona 1> (<Role>)"
+    2. "<Existing Persona 2> (<Role>)"
+    3. "Draft a new persona candidate"
+- Otherwise, ask: "This scenario is a draft — no persona bound. Pick an existing persona (1–N), or type 'new' to propose candidates."
 
 1. Read `iamu/personas/` directory or run `iamu list personas`; present as pickable list + "new" option.
 2. Picked existing → bind that persona by updating the scenario file's `persona` field.
@@ -113,9 +146,33 @@ After bind + brief, the scenario is ready to execute. Continue to step 3.
 
 ### 3. Target
 
-**Web** — ask for the target URL (live product, staging, or localhost). If the scenario has a default `target_url` in its frontmatter, offer that with a confirm.
-
-Where the walk *starts* is part of the situation, not of the environment: a persona arriving from a video, an email or a search result lands on a specific page, not the home page. If the scenario has `entry_path`, `iamu start-run` resolves it against the target — pass the product's base URL as `--target`. If it has none but the situation clearly begins on a particular page, set `entry_path` in the scenario frontmatter first (a path like `/en/episodes/1`, never a full URL), so this run and every later one start there. A walk started on the wrong page reports the detour as a finding.
+**Web** — determine the target URL:
+1. If the user passed an explicit target or the scenario has `target_url`, use that.
+2. Otherwise, check `iamu/testability.md` for `target_url`.
+3. If still unconfigured, prompt the user for the target URL (live product, staging, or localhost).
+**Dev Server Preflight Check:**
+Verify target reachability before launching the walker with `iamu doctor --target <url>` (or a fast HTTP probe).
+If the target is a local URL (e.g. `http://localhost:*`, `http://127.0.0.1:*`) and is unreachable:
+1. Inspect `iamu/testability.md` for `Command:` under `## Target & Run Instructions` (or check `package.json` for a `dev` or `start` script).
+2. Prompt the user:
+   - If interactive tool available:
+     - Question: "Target URL <url> is unreachable. Boot dev server now?"
+     - Options:
+       1. "[Recommended] Boot dev server in background (`<dev_command>`) and proceed"
+       2. "I will start the dev server manually (wait for port)"
+       3. "Specify a different target URL"
+   - Otherwise (CLI / text-only):
+     Target URL <url> is unreachable. Boot dev server now?
+       1. [Recommended] Boot dev server in background (`<dev_command>`) and proceed
+       2. I will start the dev server manually (wait for port)
+       3. Specify a different target URL
+     Reply '1' to boot dev server [default], select 2-3, or provide target URL:
+3. If Option 1 is chosen:
+   - Launch `<dev_command>` in the background as a managed daemon process.
+   - Poll `<url>` with HTTP requests until it responds (timeout: 30s).
+   - Once reachable, proceed immediately to the walkthrough.
+
+Where the walk *starts* is part of the situation, not of the environment: a persona arriving from a video, an email or a search result lands on a specific page, not the home page. If the scenario has `entry_path`, `iamu start-run` resolves it against the target — pass the product's base URL as `--target`. If it has none but the situation clearly begins on a particular page, set it first with `iamu set scenario <slug> --entry <path>` (a path like `/en/episodes/1`, never a full URL), so this run and every later one start there. A walk started on the wrong page reports the detour as a finding.
 
 **Native iOS** — the target is a device plus a build. Establish three things:
 
@@ -127,30 +184,39 @@ Record it as a target string the run can carry, for example `sim://<device-name>
 
 **Then verify the starting state before spawning anyone.** Launch the app and take ONE screenshot confirming the product is where the scenario assumes it starts. Wait a few seconds after launch first: a screen rendered before its state lands shows the wrong thing, and verifying too early makes the verification itself lie — in the direction of "the harness is broken", which costs a debugging detour or, worse, waves a real seeding bug through.
 
+**Stage the starting state — first run of a scenario.** Drafting a scenario deliberately leaves out the product's code, pages and data, so its first run is where it gets staged. If the scenario has no `state` yet, invoke the `iamu-stage` skill (or stage inline):
+
+1. From the outline, persona and brief, say in plain words what the world must contain for the situation to play out (which records, how old, in what condition, who else is involved) and who the persona must be signed in as.
+2. Check what the project already has to produce that world: seed scripts, fixtures, factories, mock handlers. `iamu/testability.md` lists the known ones; the codebase has the rest.
+3. Show the user each requirement and whether it is met, then agree how to get there: an existing seed, a change to a seed script or mock handler (propose it as a diff for the user to apply), data the user creates by hand, or letting the walker approximate.
+4. Record the outcome on the scenario so later runs do not ask again: `iamu set scenario <slug> --state-description "<the world, in domain words>" --state-approximation "<how the walker picks the closest record when the exact one is missing>"`. When the situation needs no particular data (a visitor reading a public page), record that too: `--state-description "No particular data needed"`. Project-wide facts learned on the way ("the seed needs Docker running") go in the `iamu/testability.md` body.
+
+Staging adds to a scenario and never changes what it is about: do not edit the narrative, tension, human tests or brief; if one looks wrong, tell the user. When the product cannot support the situation, walk it anyway — the persona hitting that wall is the finding. Stop only when the walk itself cannot be set up: the persona's account cannot be reached, the data cannot be produced, or the situation crosses an untestable boundary.
+
 **Expected State & Semantic Squinting — verify environment before walking.** A scenario testing triage, review, or audits requires a populated, realistic system.
 1. **Expected State:** If the scenario defines `state.description`, verify the landing screen matches what the persona expects to see (e.g. populated register, open incidents). If the screen is completely blank and the persona cannot self-seed, stop early and report the run as blocked by missing preconditions rather than logging false product bugs.
 2. **Data Squinting & Approximation:** If the exact record described in the narrative is absent (e.g. no "damaged conveyor belt" hazard), the walker must follow `state.approximation` — "squint" at the real data, pick the closest plausible record (e.g. an active mechanical or safety hazard), and proceed with the evaluation/delegation workflow.
    - **Squinting Guardrail:** Squinting is bounded to semantically related items within the same domain workflow. It does NOT permit drifting to unrelated modules (e.g. switching from risk assessment to user profile settings). If no plausible record exists, declare the run blocked.
 3. **Empty State Fallback:**
    - If the database is empty and the persona role has creation rights (e.g. Manager or Reporter), the persona may create the minimal viable record in-character to proceed with the core test.
-   - If the persona role is read-only or subordinate (cannot self-seed), stop and report the run as blocked by preconditions.
+   - If the persona role is read-only or subordinate (cannot self-seed), stop and report the run as blocked by preconditions (`iamu summary <run-id> --blocked "<what was missing>"`).
 
 **Access — how the walker becomes this persona.** A walk as a forklift driver that runs with an administrator's session reports nothing true about what the driver can see or reach. Access is recorded in two places, and `iamu instructions walk` (step 4) returns both as `access`:
 
-- `access.project` — from `iamu/context.yml` `access`: HOW switching user is done in this product (a dev persona switcher, a storage key, seeded test accounts, a login form). Written once per project.
+- `access.project` — from `iamu/testability.md` `access` (older projects: `iamu/context.yml`): HOW switching user is done in this product (a dev persona switcher, a storage key, seeded test accounts, a login form). Written once per project.
 - `access.persona` — from the persona file's `access`: WHICH user this persona is (an account name, a role, a switcher key).
 
 **Interactive Auth Handshake (for enterprise auth, SSO, 2FA, BankID):**
 If 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).
 2. Prompt the human user:
-   > 👉 **Please log in as `<persona.role>` (`<persona.name>`) in the opened browser window.** Press Enter once you reach the dashboard to hand control to the walker...
+   > 👉 **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.
 
 If automated switching exists:
 1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`) for a documented way to switch user or role.
 2. Map the persona to the closest account or role the product actually has. If nothing fits, say so.
-3. Write what you learned: the mechanism into `iamu/context.yml` as `access:`, the persona's own key into `iamu/personas/<slug>.md` frontmatter as `access:`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
+3. Write what you learned: the mechanism into the `iamu/testability.md` frontmatter as `access:` (it is test setup, so it does not belong in `context.yml`, which holds the domain; if `iamu doctor` finds it there, move it), and the persona's own key with `iamu set persona <slug> --access <key>`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
 
 Carry the result into the walking prompt as the `## Access` section: the exact steps to become the persona, with the instruction to do them BEFORE the first recorded step.
 
@@ -164,13 +230,16 @@ iamu start-run <scenario-slug> --target <target> --json
 
 This creates the run directory, writes `walkthrough.json` with resolved persona/outline slugs and the build under test (git SHA and branch, whether there are uncommitted changes outside `iamu/` with a fingerprint of them, CI run when in CI), and returns:
 ```json
-{ "run_id": "...", "path": "...", "scenario_slug": "...", "target_url": "...", "persona_slug": "...", "outline_slug": "...", "build": { "git_sha": "...", "git_branch": "...", "git_dirty": false }, "environment": "https://staging.example.com" }
+{ "run_id": "...", "path": "...", "scenario_slug": "...", "target_url": "...", "live_viewer_url": "https://app.iamu.dev/projects/.../live/...", "persona_slug": "...", "outline_slug": "...", "build": { "git_sha": "...", "git_branch": "...", "git_dirty": false }, "environment": "https://staging.example.com" }
 ```
 
 Pass `--build <label>` to name the build (a version or release tag) and `--env <name>` to name the environment (`staging`, `production`); without `--env` the environment is the target URL's origin. Neither is needed for a local walk.
 
 Use the returned `run_id` and `path` for all subsequent operations.
 
+**If `live_viewer_url` is returned**, immediately output it to the user so the operator can follow along live in their browser:
+🔴 **Live stream:** `<live_viewer_url>`
+
 **Size the browser for this persona** (`iamu browse` only), every run — also when a browser is already open from an earlier run:
 
 ```bash
@@ -190,11 +259,16 @@ iamu instructions walk --scenario <scenario-slug> --run <run-id> --surface brows
 The result's `walker_prompt` is the walker's entire prompt. 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:
-> "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."
+"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.
 
-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. If the host lets you restrict a subagent's tools, give the walker only the driving surface, file write/edit, and a shell for `iamu` commands.
+A fresh subagent is NOT blind by default. On most hosts it still loads the project's agent instructions and can read files in the repo, so it may know the domain model, the route table, and why a screen was built the way it was — none of which the persona knows. The methodology's "Stay outside the product" rule is what keeps it honest; it is part of `walker_prompt` — never remove or soften it.
+
+**Subagent Capability Fencing (Superpowers Pattern):**
+- **Tool Whitelist:** If the host allows tool restriction, grant the walker ONLY the browser driving tools (`iamu browse` or browser MCP) and read-only inspection.
+- **Tool Blacklist:** Strictly strip file write/edit tools (`write_to_file`, `replace_file_content`, patch/edit tools, and source git commits). The walker is an observer, never a developer.
+- **Child Session Suppression:** The walker must never execute parent workflow routines (`iamu init`, `iamu triage`, `iamu new`). All steps, findings, and summaries are recorded atomically via `iamu browse step`, `iamu new-finding`, and `iamu summary`.
 
 **Model tiering & subagent dispatch:**
 - **Walker (Browser Navigation):** High turn count, mechanical tool-use. Use the **fast** model tier (`flash` or `haiku`) by default to cut walk time by ~60% and conserve session quota.
@@ -221,6 +295,15 @@ The subagent inherits the driving-surface tools and drives the product independe
 
 After the walker returns, continue to the post-walk pipeline below.
 
+**Live progress reporting (terminal monitoring):**
+While the walker subagent executes, maintain visible feedback in the terminal:
+- At start (if cloud-linked): output the live dashboard viewer link: `Live stream: <viewer_url>`
+- As progress occurs (on subagent notifications or milestone steps): output a concise single-line progress update:
+  `step <N> · <action/surface> · <F> finding(s)`
+  This gives the terminal operator immediate real-time visibility into the persona's progress.
+- If the walker stops because the user pressed Stop in the viewer (`The user stopped this run from the live viewer. End the walk now.`), respect the cancellation and proceed to post-walk assembly with existing steps.
+- Once the walker finishes, announce completion and proceed immediately to the post-walk pipeline.
+
 **Recording steps:**
 
 Use atomic CLI commands to drive and record in one step — do NOT manually author JSON files:
@@ -247,15 +330,13 @@ 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, and slug:
+Use the CLI to create findings with valid frontmatter, UUID, slug, description, and recommendation in one atomic call:
 
 ```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" --recommendation "Concrete fix proposal" --json
 ```
 
-This generates a valid UUID, derives the slug from the title, and writes a frontmatter-valid file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`.
-
-After the CLI scaffolds the file, edit the file to add the finding body (description + recommendation) below the frontmatter.
+This generates a valid UUID, derives the slug from the title, and writes the complete finding file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`. Never invoke host Edit or Write tools.
 
 Valid `--type` values: `helps`, `hinders`, `missing`, `irrelevant`, `incorrect`.
 Valid `--severity` values: `critical`, `major`, `minor`, `observation`.
@@ -266,6 +347,12 @@ Findings never name a human test: the walker does not see them. The judge links
 
 **DEPTH GATE:** Both `--ui-fact` and `--consequence` should be provided. If you cannot articulate both, record as a step note instead — do not create a finding file.
 
+**Closing Synthesis:**
+Before finishing the walk, record persona synthesis using `iamu summary`:
+```bash
+iamu summary <run-id> --worked "What worked well 1" --worked "What worked well 2" --question "Open question 1"
+```
+
 **Post-walk pipeline (MANDATORY — do NOT skip any step):**
 
 After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order.
@@ -278,16 +365,19 @@ iamu complete <run-id> --no-prompt --no-push --json
 
 This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, and computes the delta against prior runs.
 
+**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. Match findings to earlier runs.** Get the matcher bundle:
 
 ```bash
 iamu match <run-id> --json
 ```
 
-If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. 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 **thorough** model tier, e.g. `Model="pro"` in Antigravity, to accurately evaluate semantic equivalence). Write its JSON answer to `<matches.json>` and record it:
+If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. 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 **thorough** model tier, e.g. `Model="pro"` in Antigravity, to accurately evaluate semantic equivalence). Record its JSON answer via `--data` (or `--file`):
 
 ```bash
-iamu match-record <run-id> --file <matches.json>
+iamu match-record <run-id> --data '<matches.json>'
+# or: iamu match-record <run-id> --file <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.
@@ -298,10 +388,11 @@ This links recurrences to their earlier canonical finding, marks earlier finding
 iamu evaluate <run-id> --json
 ```
 
-Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to prevent severity inflation). After the evaluator returns verdicts, record them locally with `--no-push`:
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to prevent severity inflation). After the evaluator returns verdicts, record them locally with `--no-push` via `--data` (or `--file`):
 
 ```bash
-iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
+iamu evaluate-record <run-id> --data '<verdicts.json>' --no-prompt --no-push
+# or: iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
 ```
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
@@ -336,72 +427,47 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 5. Present assessment — stay in the conversation
 
-Render results **inline** with a high-contrast executive summary banner, followed by findings enriched with persona voice, evidence citations, and clickable file links.
-
-1. **Executive Summary Banner & Focus Checkpoint**
-
-   Read the outline's `human_tests[0].question` and answer it directly. Use the evaluation verdict if available:
+Render results **inline** as a concise executive scorecard.
 
-   ```
-   Walkthrough: [<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 (Steps: <N>)
-   Focus Checkpoint: "<human_tests[0].question>" → <No / Partial / Yes>: <1-2 sentence direct answer explaining why>
-   ```
-
-2. **Progress since last run** (only when canonical.json contains a `verification` section). Present the delta:
-
-   ```
-   Since this scenario's last run:
-     ✓ 1 fixed, re-checked (handoff note saves — step 6)
-     ✗ 1 persists (timeout warning)
-     ○ 2 not seen this run (handoff list filtering, submit confirmation)
-     + 1 new since that run (date picker locale)
-   ```
-
-   `resolved` means the matcher saw this run's steps do the thing the finding said failed — say which step. `not_observed` means only that this walk did not record the finding again. Never present it as fixed: the walker may have stopped before that screen or taken another route. Say which ones were not seen and, if the walk plainly never reached the screen they live on, say that too.
-
-3. **Findings** — severity-first (CRITICAL → MAJOR → MINOR), grouped by type (hinders and missing first, helps at the bottom). For each finding, include the **persona reaction**, **evidence citation**, and **clickable link**:
-
-   **Hinders / Missing** (act on these):
-
-   1. [CRITICAL · hinders] Submit fails opaquely when required field empty ([file](iamu/findings/<slug>.md))
-      • Persona: <Persona Name>: "<Persona reaction quote or consequence showing real human friction>"
-      • Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
-      • Recommendation: <Concrete recommendation from finding>
+**ANTI-BLOAT DIRECTIVE:** Terminal viewports are small. Never output multi-screen walls of markdown text. The overview exists only to present the top-line score and orient the user for triage. Do NOT dump long quotes, recommendations, full descriptions, or "What Worked" essays here — those belong in the interactive triage step below.
 
-   2. [MAJOR · hinders] Date picker has no "today" shortcut ([file](iamu/findings/<slug>.md))
-      • Persona: <Persona Name>: "<Persona reaction quote or consequence>"
-      • Evidence: Step <N> at <url>
-      • Recommendation: <Concrete recommendation from finding>
+Keep the presentation under 15 lines total:
 
-   **Helps** (preserve these):
-
-   • [helps] Search auto-suggests from recent entries (Step <N>)
+```
+Walkthrough: [<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 (Steps: <N>)
+Focus Checkpoint: "<human_tests[0].question>" → <No / Partial / Yes>: <1-sentence direct answer>
 
-4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
+Findings:
+1. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
+2. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
+...
+(Helps: • [helps] <short title> (Step <N>))
 
-5. **Next-scenario suggestion** — read `iamu/scenarios/` to check coverage, then suggest one of:
-   - Same scenario with a different persona (if other personas exist for this situation)
-   - Adjacent untested scenario in the same capability
-   - Nothing (if coverage is good)
+Cloud: <Shareable report: <url> | Local only>
+```
 
-6. **Cloud** — one line, by mode:
-   - **Linked, run on the cloud** → `Shareable report: <url>` (screenshots and step replay for anyone on the team).
-   - **Linked, run not on the cloud** → the reason from step E and its remedy, e.g. `Cloud: queued — retries on the next iamu sync`.
-   - **Local-only** → on first completed run: `Want a link to share this report? iamu auth login connects to Iamu Cloud — optional, everything keeps working locally.`
+(If canonical.json contains a `verification` section, include a 1-line delta: `Since last run: ✓ <N> fixed · ✗ <M> persist · + <K> new`.)
+Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the entire summary under 15 lines, then immediately present the triage prompt below.
 
-7. **Next actions (Conversational Triage)**:
+7. **Next actions (Interactive Triage Selection)**:
+   When the walkthrough completes and yields findings:
+   - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+     - Question: "Walkthrough complete: <F> findings reported. How would you like to proceed?"
+     - Options:
+       1. "[Recommended] Walk through findings one by one"
+       2. "Apply fixes for all clear findings (batch fix)"
+       3. "Discuss findings and persona friction points"
+       4. "Re-run walkthrough to test changes"
+   - Otherwise (in CLI or text-only environments):
 
-   Conclude your report with clear conversational prompts instead of raw terminal commands:
+   Walkthrough complete: <F> findings reported.
+     1. [Recommended] Walk through findings one by one
+     2. Apply fixes for all clear findings (batch fix)
+     3. Discuss findings and persona friction points
+     4. Re-run walkthrough to test changes
 
-   ```
-   What would you like to do?
-     • "walk through them"    → Review findings one by one with persona context & code location
-     • "fix 1 and 2"          → Have me implement code fixes directly
-     • "discuss 2"            → Ask why the persona hit this friction or explore trade-offs
-     • "skip 3" / "dismiss 3" → Dismiss finding (out of scope, intended, or walker error)
-     • "re-run"               → Re-run walkthrough to verify fixes
-   ```
+   Reply '1' to review findings [default], enter 2-4, or tell me how to proceed:
 
 ### 6. Conversational Triage & Guided Review
 
@@ -409,19 +475,59 @@ The conversation is the triage surface. Do NOT eject the user to manual CLI comm
 
 #### 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 isolation**:
-   - Number, severity, type, and title
-   - Persona consequence quote and why the friction occurred
-   - Relevant source code location (inspect project files to provide file path + line numbers)
-   - Step & screenshot evidence ([view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
-   - Actionable recommendation
-   - Clear options prompt:
-     `Options: [Fix now]  [Skip / Dismiss]  [Discuss / Why]  [Next finding]`
+1. **Present Finding #N in a comprehensive, dashboard-aligned summary:**
+   Do NOT force an artificial single `Location: file:line` (UX friction and user blockers often span entire flows, API errors, or policy). Instead, present:
+   ```
+   Finding <N>/<total>: [<SEVERITY> · <type>] <title>
+   • Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
+   • UI Fact: <What the UI showed or did (ui_fact)>
+   • Consequence: <Impact on the persona completing their task (consequence)>
+   • Agent Insight: <1–2 plain-language sentences synthesizing why this happens and what it means in context>
+   • Recommendation: <Concrete fix proposal from finding body>
+   • Evidence: <iamu/.runs/<run>/screenshots/step-<N>.png> [Dashboard](<url if cloud_linked>)
+   ```
+   If the project is cloud-linked, include the link to the finding in Iamu Cloud (from `iamu open --print`).
+
+   Followed immediately by the decision prompt:
+
+   **CRITICAL: Embed Full Context 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. **You must embed the complete finding summary inside the `question` argument** so the reviewer has full context directly in the dialog without having to close the modal.
+
+   - If interactive tool available (e.g. `ask_question`, `ask_followup_question`), invoke it:
+     - **Question:**
+       """
+       Finding #<N>/<total>: <title>
+
+       • Impact: [<SEVERITY> · <type>]
+       • Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
+       • UI Fact: <ui_fact>
+       • Consequence: <consequence>
+       • Agent Insight: <1–2 sentences explaining why this happens in simple terms>
+       • Recommendation: <concrete recommendation>
+       • Evidence: <screenshot path, local file link, and cloud dashboard link if linked>
+
+       How should we triage this finding?
+       """
+     - **Options:**
+       1. "[Recommended] Queue to fix (mark for fix & continue triage)"
+       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)"
+   - Otherwise (CLI / text-only):
+     Triage Finding #<N>/<total>: '<finding title>'
+       1. [Recommended] Queue to fix (mark for fix & continue triage)
+       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], select 2-5, or describe your decision:
 
 2. **Handle the user's decision**:
-   - **Fix now**:
-     Make the code edit, verify it loads (or check local tests/types), update the finding's frontmatter (`triage_status: addressed`, `triage_note: "<summary of fix>"`).
-     Tell the user the fix is applied and ask: "Ready for finding #<N+1>?".
+   - **Queue to fix [Recommended]**:
+     Add finding to the session's fix queue.
+     Tell the user in 1 line: "✓ Queued for fix. Ready for finding #<N+1>?" and advance immediately.
+     Do NOT edit code or leave triage yet — complete triage across all findings first.
    - **Skip / Dismiss**:
      If reason is not specified, ask or infer the appropriate category:
      - `out_of_scope`: Not relevant to this project/flow scope.
@@ -429,17 +535,74 @@ When the user asks to review findings one by one:
      - `walker_error`: Walker misread the screen or made a navigational error.
      - `duplicate`: Duplicate of another finding.
      Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<why>"`.
-     Tell the user: "Dismissed as `<reason>` — created guidance rule in `iamu/guidance/<slug>.md` so future walkthroughs will not report this."
+     Tell the user in 1 line: "✓ Dismissed as `<reason>` — guidance rule recorded."
      Then advance to finding #<N+1>.
-   - **Discuss / Why**:
-     Analyze why the persona experienced this friction, cite the persona brief and steps/screenshots, evaluate whether competitor tools solve this pattern, and give a direct opinion on whether it's worth fixing.
-   - **Next**:
+   - **Discuss / Why (STRICT CONSTRAINT: maximum 3-4 concise bullets, under 80 words total)**:
+     Never write multi-section essays, markdown headers (`### Trade-off Analysis`, `#### 1. Why it was built this way`, `#### 2. The Operational Failure`), or ASCII/markdown tables. Deliver a direct, surgical 3-bullet answer:
+     • **Root Cause:** 1 sentence on why the UI or workflow behaves this way (and source file if known).
+     • **Persona Friction:** 1 sentence on the practical operational consequence.
+     • **Recommended Fix & Trade-off:** 1-2 sentences with concrete approach and any trade-offs.
+     Immediately re-prompt the triage decision for finding #<N>.
+   - **Fix immediately (leave triage now)**:
+     If the user explicitly chooses to drop out of triage and fix right now:
+     Make the code edit, verify it loads (or check local tests/types), update the finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+     Tell the user in 1 line: "✓ Applied fix. Finding #<N> marked addressed."
+   - **Next finding (keep open / defer)**:
      Leave open (or set `triage_status: deferred` with note) and advance to finding #<N+1>.
 
 3. **Wrap up after all findings are reviewed**:
+   Report the triage recap in 1-2 lines:
+   ```text
+   Triage Complete: <K> queued for fix, <D> dismissed, <O> kept open/deferred.
+   ```
+   If `<K> > 0` (findings are queued for fix):
+   - Prompt the user to execute the batch:
+     - If interactive tool available:
+       - Question: "Triage complete. Apply fixes for the <K> queued findings now?"
+       - Options:
+         1. "[Recommended] Apply fixes for queued findings in workspace now"
+         2. "Re-run walkthrough to verify dismissed items first"
+         3. "Done for now (keep fixes open in iamu/findings/)"
+     - Otherwise (CLI / text-only):
+       Apply fixes for the <K> queued findings now?
+         1. [Recommended] Apply fixes for queued findings in workspace now
+         2. Re-run walkthrough to verify dismissed items first
+         3. Done for now (keep fixes open in iamu/findings/)
+       Reply '1' to apply fixes [default], or select 2-3:
+
+   - **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>"`.
+     Tell the user: "✓ Applied fixes for <K> findings. All marked addressed."
+
    - Run `iamu validate --all`.
-   - In linked mode, run `iamu sync --json` once so teammates see the triage decisions.
-   - Suggest re-running the walkthrough: `iamu-run <scenario-slug>` to verify fixes.
+
+   - **Closed-Loop Regression Verification (1-Click):**
+     Immediately prompt the user to verify the fixes hold in practice:
+     - If interactive tool available:
+       - Question: "Fixes applied and validated. Verify them now with a walkthrough re-run?"
+       - Options:
+         1. "[Recommended] Re-run walkthrough to verify fixes hold"
+         2. "Done for now (leave verification for later)"
+     - Otherwise (CLI / text-only):
+       Verify fixes now?
+         1. [Recommended] Re-run walkthrough 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:
+     1. Start the verification run: `iamu start-run <scenario-slug> --target <target> --json`. Note: `start-run` automatically pulls all awaiting findings into `revisit` places in `walkthrough.json`.
+     2. Walk through the scenario, ensuring the persona visits the revisit places.
+     3. Assemble the run with `iamu complete <run-id> --json`. The canonical assembly compares against the baseline run and outputs `verification` (`resolved`, `persists`, `new_findings`).
+     4. Report the verification verdict:
+        ```text
+        Verification Complete:
+          Scenario: <scenario-slug>
+          Baseline run: <baseline_run_id>
+          Verified fixes: ✓ <N> resolved
+          Regressions: 0 new findings
+        ```
+     5. If any finding persists or a regression occurred, present only the remaining items for follow-up triage.
+     6. In linked mode, run `iamu sync --json` once so teammates see the verified decisions.
 
 #### B. Direct Batch Actions ("fix 1 and 2", "fix all critical")
 Read the finding details from the canonical JSON (already in context), inspect the code, make the edits, and update frontmatter to `triage_status: addressed` with `triage_note`.