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

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

@@ -77,7 +77,10 @@ No local codebase detected. To seed context, provide one of:
 
 ### 3. Step 1/3: Establish the Safety Fence (`iamu/testability.md`)
 
-Present the detected environment and safety fence. Explain clearly *why* this boundary is required before any autonomous agent runs. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
+Present the detected environment and safety fence. Explain clearly *why* this boundary is required before any autonomous agent runs.
+
+**Dual-Surface Prompting (Sequencing Rule):**
+You MUST output the safety fence card to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the full context embedded in the `question` argument:
 
 ```text
 Step 1/3: Safety Fence & Environment Boundary
@@ -93,12 +96,30 @@ Detected Environment:
 **Interactive Decision Gate:**
 Prompt the user to verify the safety boundary:
 - If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
-  - Question: "Confirm safety fence and dev environment?"
-  - Options:
+  - **Question:**
+    """
+    Step 1/3: Confirm Safety Fence & Dev Environment
+
+    Target URL:    <target_url>
+    Dev Command:   <dev_command>
+    Safe Fixtures: <detected seed scripts or mock handlers>
+
+    DO NOT WALK (Untestable Boundaries):
+    <detected external services, real SMS/email gateways, external submission portals>
+
+    Confirm safety fence and dev environment?
+    """
+  - **Options:**
     1. "[Recommended] Safety boundaries look safe — save fence and proceed"
     2. "Adjust boundaries (add forbidden external URLs, change dev command or port)"
     3. "Skip safety fence for now"
 - Otherwise (text-only/CLI):
+  Step 1/3: Safety Fence & Environment Boundary
+  Target URL:    <target_url>
+  Dev Command:   <dev_command>
+  Safe Fixtures: <detected seed scripts or mock handlers>
+  DO NOT WALK:   <detected external services>
+
   Safety boundaries look safe. I recommend saving fence and proceeding.
   Proceeding to save safety fence — say "adjust" to change boundaries or "skip" to defer.
 
@@ -138,7 +159,10 @@ iamu set testability \
 
 Explain the purpose of project context: traditional tests only assert button clicks; Iamu evaluates user confusion, workflow friction, and whether a real person can succeed under real-world constraints.
 
-Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
+Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys.
+
+**Dual-Surface Prompting (Sequencing Rule):**
+You MUST output the domain context and project description to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the complete substantive project description embedded in the `question` argument so the reviewer can read the full text directly within the dialog modal:
 
 ```text
 Step 2/3: Project Domain & Description
@@ -154,15 +178,38 @@ Project Description:
 <1 cohesive paragraph: what the software fundamentally does, its primary user workflows, and the real-world conditions under which it is used. No marketing buzzwords, no hedging, and no tech stack trivia.>
 ```
 
-**Interactive Decision Gate:**
-Prompt the user to verify the project description:
+**CRITICAL: Embed Full Project Description in Interactive Prompt Modal:**
+Host interactive tools (`ask_question`, `ask_followup_question`) render a modal that obscures the terminal/chat and displays ONLY the tool's `question` argument. Never ask the user to confirm an invisible description. You MUST embed the full drafted project description text inside the `question` argument:
+
 - If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
-  - Question: "Confirm project domain & description?"
-  - Options:
+  - **Question:**
+    """
+    Step 2/3: Confirm Project Domain & Description
+
+    Domain:       <domain name>
+    Industry:     <industry>
+    Jurisdiction: <jurisdiction or omit if standard web app>
+    Governed By:  <statutory regulations or standards, or omit if unregulated>
+
+    PROJECT DESCRIPTION:
+    <1 cohesive paragraph: what the software fundamentally does, its primary user workflows, and the real-world conditions under which it is used>
+
+    Confirm project domain & description?
+    """
+  - **Options:**
     1. "[Recommended] Project description is accurate — proceed to design first test"
     2. "Save project description only (skip scenario creation for now)"
     3. "Adjust domain or description"
 - Otherwise (text-only/CLI):
+  Step 2/3: Project Domain & Description
+  Domain:             <domain name>
+  Industry:           <industry>
+  Jurisdiction:       <jurisdiction>
+  Governed By:        <statutory regulations or standards>
+
+  Project Description:
+  <1 cohesive paragraph>
+
   Project description is accurate. I recommend proceeding to design your first test.
   Proceeding to first test design — say "save only" or describe adjustments to change course.
 
@@ -185,7 +232,10 @@ iamu set context \
 
 Explain the journey model: an Iamu test binds a **Persona** (with habits, pressures, and impatience) to a **Situation** (a realistic high-stakes problem) with an **Evaluation Checkpoint** (a concrete binary question for the AI judge).
 
-Present the proposed test journey, including explicit **Auth Precondition Verification**. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
+Present the proposed test journey, including explicit **Auth Precondition Verification**.
+
+**Dual-Surface Prompting (Sequencing Rule):**
+You MUST output the baseline test proposal to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the full journey spec embedded in the `question` argument:
 
 ```text
 Step 3/3: Co-Design Your First Test Journey
@@ -204,11 +254,26 @@ Baseline Test Proposal (WYSIWGW Spec-Sheet):
   Walker Brief:       "<2–3 sentence first-person test brief that will be written verbatim to disk. States immediate intent and constraints before opening tool. Zero UI terminology.>"
 ```
 
-**Interactive Decision Gate:**
-Prompt the user to verify the scenario and its auth precondition:
+**CRITICAL: Embed Journey Spec in Interactive Prompt Modal:**
 - If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
-  - Question: "Scaffold this baseline journey?"
-  - Options:
+  - **Question:**
+    """
+    Step 3/3: Confirm Baseline Test Journey
+
+    Capability:        <Capability Name> (<What staff can do in this area>)
+    Persona:           <Name> (<Role / Title>) — Friction: <Diagnostic friction trigger>
+    Situation:         <Outline Title>
+    Core Tension:      <Core problem-space tension in X vs Y format>
+    Evaluation Check:  <Concrete binary yes/partial/no question for evaluator>
+    Walk Surface:      Entry: `<entry_path>` | Target: `<target_url>`
+    Auth Precondition: <Detected auth mechanism>
+
+    WALKER BRIEF:
+    "<2–3 sentence first-person test brief>"
+
+    Scaffold this baseline journey?
+    """
+  - **Options:**
     1. "[Recommended] Scaffold journey with <detected auth mechanism>"
     2. "Use interactive human login handshake (pause browser for live login)"
     3. "Switch role / design a different scenario (write-in)"

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

@@ -105,10 +105,25 @@ Now present the **Strategic Fork** to the user. Do not be an unyielding bureaucr
 - State: "This situation reads a public page and requires no pre-existing world state."
 - Mark `--state-description "No particular data needed"`.
 
-**Interactive Decision Gate:**
+**Dual-Surface Staging Gate (Sequencing Rule):**
+You MUST output the staging options to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the staging options and requirements embedded in the `question` argument:
+
 - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
-  - Question: "How should we stage '<scenario-slug>' for walkthrough?"
-  - Options:
+  - **Question:**
+    """
+    Staging Plan for '<scenario-slug>':
+
+    Entry Route: <route>
+    Required World State: <Description of required world in domain words>
+
+    Staging Options:
+    • Option A (Testability): <concrete seed or mock fixture proposal>
+    • Option B (Semantic Squinting): <squinting rule formula>
+    • Option C (Zero Setup): <why flow is public or self-contained>
+
+    How should we stage '<scenario-slug>' for walkthrough?
+    """
+  - **Options:**
     1. "[Recommended] Option A: Build Testability (<brief seed proposal>)"
     2. "Option B: Semantic Squinting (test immediately against current dev database)"
     3. "Option C: Zero Setup Needed (public or self-contained flow)"

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

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

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

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

package/package.json

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