@iamu-dev/iamu 0.4.0-beta.0 → 0.4.0-beta.1

package/dist/templates/prompts/walk.md

@@ -56,7 +56,7 @@ Not every lens produces a finding at every screen. But you must consciously chec
 - **observation** — An enhancement opportunity. Not friction, but a missed chance to help.
 
 Finding type pairing:
-- `helps` → always observation severity. Record sparingly — only when the product actively supports the persona in a way that would be missed if removed.
+- `helps` → always observation severity. Record each one you meet: something the product does that actively supports the persona and would be missed if removed. Not baseline competence ("the button is easy to find"). These tell whoever fixes the problems what to protect.
 - `hinders` → critical, major, or minor.
 - `missing` → critical, major, or minor.
 - `incorrect` → critical or major only.
@@ -197,10 +197,11 @@ Leave `triage_status` alone; triage is not the walker's job.
 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"
+iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --question "Question for the team" --setup-note "Doubt about the test setup"
 ```
 
-- `--worked` — Things the system did well for this persona. Important to preserve.
-- `--question` — Questions that arose that need discussion.
+- `--worked` — What worked for this persona, one point each: the screen or moment and what it did for them ("The confirmation names who is notified, so I knew I was done"). Include the strengths you recorded and anything else that made the task easier. Usually three to six points.
+- `--question` — Questions for the product team: decisions the walk raised that the product does not settle and that you could not settle as the persona ("Should a reporter see the investigator's checklist at all?", "Is the 14-day notice rule enforced or only advised?"). Not doubts about the test itself.
+- `--setup-note` — Doubts about the test setup, not the product: data that seemed missing or unrealistic, an account that could not see what the situation needs, a date the scenario assumes ("No absences are recorded for summer 2027, so 'nobody is away' may only mean no data"). These go to whoever stages the scenario.
 
 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

@@ -125,7 +125,7 @@ Format the visible finding in chat:
 ```markdown
 ### Finding #<N>/<total> [<SEVERITY>] — <title>
 > **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
-> **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+> **Evidence:** <project root>/iamu/.runs/<run>/screenshots/step-<N>.png · Cloud: <full https URL from iamu open <run-id> --print>
 
 **❌ Problem:**
 <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
@@ -223,15 +223,14 @@ dismissed (not_relevant): <finding-slug>
 
 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.
 
-When all findings in the queue are triaged, present the summary:
+When all findings in the queue are triaged, present what was decided, one row per finding, as a Markdown table (not in a code fence). Every finding in the queue gets a row, so none silently disappears:
 
-```text
-Triage complete.
-  Queued for fix: <N>
-  Dismissed: <N>
-  Rescoped (design change / defer): <N>
-  Kept open: <N>
-```
+| # | Finding | Decision | Action |
+|---|---|---|---|
+| 1 | <title> | Fix now | <what will change, or "Done" once applied> |
+| 2 | <title> | Direction | `<direction slug>` |
+| 3 | <title> | Defer | Revisit after the next run |
+| 4 | <title> | Dismissed | <reason>; guidance `<slug>` taught to future walks |
 
 If `<N> > 0` findings were queued for fix:
 - Prompt the user:
@@ -273,12 +272,13 @@ Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `c
 
 Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
 
-> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open --print>)
+> ☁️ **Cloud:** <full https URL from iamu open --print>
 
 In linked-no-credentials mode, end with `Decisions are local only — iamu auth login, then iamu sync, to share them.` Skip this section entirely in local-only mode. The terminal surface is complete.
 
 ## Guidelines
 
+- **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
 - **Terminal-complete.** Everything the user needs to triage fits in chat. Citations, recommendations, linked steps, screenshots (as paths the agent can read if it has image support). Dashboard is nice-to-have, not required.
 - **Group by scenario, not by type.** Findings aggregate around scenarios. When reviewing, the context of "what happened in Maria's shift handoff?" matters before deciding on each finding — not seeing all severity:critical across projects.
 - **Severity-sorted within each group.** Within a scenario group, sort CRITICAL → MAJOR → MINOR → OBS. Within the same severity, show hinders/missing/incorrect before helps.

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

@@ -253,12 +253,12 @@ For drafts (no persona): omit `--persona`, omit `--body`.
 
 ### 7. Summarize
 
-Present the created entities with clickable file links and exact run commands:
+Present the created entities by slug, with the scenario file as an absolute path, and exact run commands:
 
 ```
-Created Scenario: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md)
-• Situation: [<outline-slug>](iamu/outlines/<outline-slug>.md)
-• Persona: [<persona-slug>](iamu/personas/<persona-slug>.md)  (or "draft — no persona bound yet")
+Created Scenario: `<scenario-slug>` (<project root>/iamu/scenarios/<scenario-slug>.md)
+• Situation: `<outline-slug>`
+• Persona: `<persona-slug>`  (or "draft — no persona bound yet")
 • Capability: <primary_capability>
 
 Next step:
@@ -271,6 +271,7 @@ Run `iamu validate --all` to verify all entities before reporting done.
 
 ## Guidelines
 
+- **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
 - **Brainstorm, don't fill forms.** Propose varied seeds. Challenge assumptions. The best scenarios are ones the user hadn't considered.
 - **Problem-space only.** Scenarios describe human situations — never UI, screens, buttons, or features. The walkthrough discovers whether the product supports the situation.
 - **Ground in the domain, not the codebase.** Start from what the persona's week demands. A situation the product cannot support yet is a good scenario: the walk shows the gap with evidence.

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

@@ -69,10 +69,10 @@ Present candidates as scannable numbered cards. Do NOT use multi-column markdown
 
 #### A. When proposing Scenarios:
 
-Lead with existing coverage using clickable links, then render the candidates:
+Lead with existing coverage by slug, then render the candidates:
 
 ```
-Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Uncovered areas: <gaps>.
+Existing coverage: <N> scenarios (`<slug1>`, ...). Uncovered areas: <gaps>.
 
 1. <Short situation name> (<Actor from context>)
    • Capability: <Capability slug, e.g. billing-invoicing>
@@ -116,10 +116,10 @@ You MUST output the proposed candidates to the chat stream FIRST. In the SAME tu
 
 #### B. When proposing Personas:
 
-Lead with existing persona coverage using clickable links and uncovered roles from `context.yml`:
+Lead with existing persona coverage by slug and uncovered roles from `context.yml`:
 
 ```
-Existing personas: [<slug1>](iamu/personas/<slug1>.md), ... Uncovered roles from context.yml: <roles>.
+Existing personas: `<slug1>`, ... Uncovered roles from context.yml: <roles>.
 
 1. <Name> (<Actor role>)
    • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
@@ -179,6 +179,7 @@ Ground rules for generation:
 
 ## Guidelines
 
+- **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
 - **This skill produces seeds, not finished files.** `iamu-new` handles the full scaffolding. This skill handles the harder upstream question: what and who is worth testing?
 - **Context is load-bearing.** Without project context, you produce the same feature-validation scenarios and generic marketing bios that freeform chat produces. The `context.yml` grounding makes the difference.
 - **Don't pad to 5.** If only 2–3 strong candidates exist, propose 2–3. Padding with weak candidates undermines trust.

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

@@ -349,7 +349,7 @@ Findings never name a human test: the walker does not see them. The judge links
 **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"
+iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --question "Question for the team" --setup-note "Doubt about the test setup"
 ```
 
 **Post-walk pipeline (MANDATORY — do NOT skip any step):**
@@ -443,10 +443,12 @@ 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. 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:
+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. Write addresses and file paths out in full so a terminal can open them:
 
 ### <summary.persona> · <summary.situation>
-<summary.steps> steps · [Open in Iamu Cloud](<summary.cloud>) *(local-only: `[report.md](iamu/.runs/<run-id>/report.md)`)*
+<summary.steps> steps · Cloud: <cloud_url, the full https address> *(not on the cloud: the row's `report_path`, the absolute path to report.md)*
+
+If `summary.checks` is set, say first what this run was checking, in one line: `Re-checked <fixes> fixes waiting for a re-check: <fixed> confirmed fixed, <cameBack> came back, the rest not confirmed`, plus the directions that landed. Name the ones that came back.
 
 > **<summary.verdict.question>** **<summary.verdict.label>**
 > <summary.verdict.answer>
@@ -457,9 +459,11 @@ If `summary.since` is set, show what happened to every earlier finding this run
 
 **Since the last run** (<date of summary.since.baselineAt>)
 
-| Earlier finding | Now |
-|---|---|
-| <title> | ✓ Resolved / ✗ Persists / ○ Not seen / ? Unclear |
+| Earlier finding | Now | Notes |
+|---|---|---|
+| <title> | **Resolved** / **Persists** / Not seen / Unclear | <item.note, or — > |
+
+For a persisting finding, put its qualifiers in brackets: the `shift` ("less severe, major → minor") and "the fix did not hold" when `fixedBefore` is true (it was marked fixed before this run).
 
 `+ <summary.since.added> new problems this run.` "Not seen" means the walk did not pass that way: never call it fixed.
 
@@ -483,6 +487,8 @@ 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).
 
+If `summary.setupNotes` is non-empty, add **Test setup** with one bullet each. These are doubts about the test, not the product (missing data, an account that cannot see enough, a date the scenario assumes). Offer the `iamu-stage` skill to fix the setup before the next run; a finding that rests on a setup doubt may not be real.
+
 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):**
@@ -514,7 +520,7 @@ When the user asks to review findings one by one:
    ```markdown
    ### Finding #<N>/<total> [<SEVERITY>] — <title>
    > **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
-   > **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+   > **Evidence:** <run_dir>/screenshots/step-<N>.png · Cloud: <full https URL from iamu open <run-id> --print>
 
    **❌ Problem:**
    <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
@@ -641,6 +647,7 @@ Run `iamu validate --all` to verify all entities before reporting done. If older
 
 ## Guidelines
 
+- **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
 - **Drafts bind in-line, not as a detour.** If the user picks a draft, the persona-bind step should feel like part of running — not a separate invocation.
 - **All generation is local.** All generation — persona suggestions, brief — uses the local LLM directly. No server-side LLM calls.
 - **Scenario vocabulary.** Say "scenario" — never "outline" — when addressing the user.

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

@@ -21,9 +21,9 @@ $ARGUMENTS
 
 Do NOT use `find`, `grep`, or `cat` to dump raw `.md` files in `iamu/`. The CLI outputs clean, validated data.
 
-### 2. Format entity responses with an executive tally and clickable links
+### 2. Format entity responses with an executive tally
 
-When the user asks for project status, lead with an executive tally banner, followed by compact 1-line bullet points with clickable markdown file links.
+When the user asks for project status, lead with an executive tally banner, followed by compact 1-line bullet points that name entities by slug in backticks. Do not link entity files: a relative path opens nowhere in a terminal. Web addresses are written out in full.
 
 **ANTI-BLOAT DIRECTIVE:** Do NOT output multi-column markdown tables (they wrap awkwardly and break borders in terminal viewports). Keep each entity to a single scannable line:
 
@@ -33,17 +33,17 @@ Product Map:    <T> Surfaces (<R> Reached · <U> Unreached) [if explore map exis
 ```
 
 **Personas:**
-• [`elin-dahl`](iamu/personas/elin-dahl.md) — Elin Dahl · Architect & first-time house owner in Falun · active
+• `elin-dahl` — Elin Dahl · Architect & first-time house owner in Falun · active
 
 **Scenarios:**
-• [`replacing-windows`](iamu/scenarios/replacing-windows.md) — [`elin-dahl`](iamu/personas/elin-dahl.md) · outline: [`measure-and-order`](iamu/outlines/measure-and-order.md) · ready
+• `replacing-windows` — `elin-dahl` · outline: `measure-and-order` · ready
 
 **Findings:**
-• `1` [CRITICAL · hinders] Submit fails opaquely on empty field — [`view`](iamu/findings/<slug>.md)
+• `1` [CRITICAL · hinders] Submit fails opaquely on empty field — `<slug>`
 
 **Awaiting Verification (Needs a Re-run):**
 If `iamu status` reports fixes awaiting a re-run:
-• [`<scenario-slug>`](iamu/scenarios/<scenario-slug>.md) — <N> fixes awaiting verification from a re-run (`iamu-run <scenario-slug>`)
+• `<scenario-slug>` — <N> fixes awaiting verification from a re-run (`iamu-run <scenario-slug>`)
 
 **Product Map & Unreached Surfaces:**
 If `iamu status --json` has `explore` data:
@@ -57,7 +57,7 @@ The directory `iamu/.prompts/` contains internal prompt templates (`persona.md`,
 
 For a project-status question, add one line on the cloud from `iamu status --json` (`mode`, `sync`, `requests`) and `iamu auth status --json` (`authenticated`):
 
-- **Linked** → `Cloud: linked — [Open Project in Iamu Cloud](<url from iamu open --print>)`, then only what needs action: unpushed changes (`sync.pending_new` + `sync.pending_updates` + `walkthroughs.pending`, and `sync.local_deletions.count`) → `iamu sync`; `requests.open` above zero → `<N> team requests — iamu-findings`.
+- **Linked** → `Cloud: linked — <full https URL from iamu open --print>`, then only what needs action: unpushed changes (`sync.pending_new` + `sync.pending_updates` + `walkthroughs.pending`, and `sync.local_deletions.count`) → `iamu sync`; `requests.open` above zero → `<N> team requests — iamu-findings`.
 - **Linked, no credentials** → `Cloud: linked, but this machine has no credentials — iamu auth login.`
 - **Local-only** → `Cloud: local-only.` Nothing more; no upgrade pitch.
 

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

@@ -1,3 +1,4 @@
+import { type CheckOutcome, type RunChecks } from "@iamu-dev/local-store";
 export interface HtmlReportHighlight {
     targetBox: {
         x: number;
@@ -40,16 +41,31 @@ export interface HtmlReportFinding {
     uiFact?: string | null;
     consequence?: string | null;
     recommendation?: string | null;
+    /** "/request · step 8" */
+    where?: string | null;
+    isNew?: boolean;
+    persists?: boolean;
 }
 export interface HtmlReportVerdict {
     question: string;
     rating: string;
     reasoning?: string;
 }
+export interface HtmlReportSinceItem {
+    title: string;
+    note?: string;
+    step_ids?: string[];
+    fixed_before?: boolean;
+    severity_before?: string;
+    severity_now?: string;
+}
 export interface HtmlReportVerification {
-    resolved: unknown[];
-    persists: unknown[];
-    newFindings: unknown[];
+    resolved: HtmlReportSinceItem[];
+    persists: HtmlReportSinceItem[];
+    notObserved?: HtmlReportSinceItem[];
+    newFindings: Array<{
+        type?: string;
+    }>;
 }
 export interface HtmlReportData {
     scenarioName: string;
@@ -67,9 +83,25 @@ export interface HtmlReportData {
     steps: HtmlReportStep[];
     findings: HtmlReportFinding[];
     verdicts?: HtmlReportVerdict[];
+    /** The run's answer to "would they come back", with one label for all tests. */
+    overall?: {
+        question: string;
+        label: string;
+        answer: string | null;
+        reasoning: string | null;
+    } | null;
     verification?: HtmlReportVerification | null;
     whatWorked?: string[];
     openQuestions?: string[];
+    /** The walker's doubts about the test setup. */
+    setupNotes?: string[];
+    /** What a re-run was sent to check, with this run's outcome for each fix. */
+    checks?: {
+        fixes: Array<RunChecks["fixes"][number] & {
+            outcome: CheckOutcome;
+        }>;
+        directions: string[];
+    } | null;
 }
 export declare function generateHtmlReport(data: HtmlReportData): string;
 /**

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

@@ -40,6 +40,12 @@ export interface RunView {
         items: Array<{
             title: string;
             outcome: SinceOutcome;
+            /** Why the matcher judged it so. */
+            note: string | null;
+            /** Marked addressed before this run: persisting means the fix did not hold. */
+            fixedBefore: boolean;
+            /** Persists only: "less severe, major → minor" or "worse, …", else "". */
+            shift: string;
         }>;
     } | null;
     findings: RunFindingRow[];
@@ -54,11 +60,26 @@ export interface RunView {
         kind: string;
         title: string;
     }>;
+    /** The fixes this run re-checked: how many, confirmed fixed, and came back. */
+    checks: {
+        fixes: number;
+        fixed: number;
+        cameBack: number;
+        directions: string[];
+    } | null;
+    /** The walker's doubts about the test setup. */
+    setupNotes: string[];
 }
 export interface OverviewRun {
     completedAt: string | null;
     label: VerdictLabel;
     problems: number;
+    /** Problems by severity: critical, major, minor (minor includes observations). */
+    bySeverity: {
+        critical: number;
+        major: number;
+        minor: number;
+    };
     resolved: number;
     persists: number;
     added: number;

package/package.json

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