@iamu-dev/iamu 0.2.0-beta.5 → 0.2.0-beta.7

package/dist/index.js

@@ -199,17 +199,24 @@ function defaultConfig(params) {
     cloud_api_url: null
   };
 }
-var baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
+var modelTierSchema, projectModelsConfigSchema, baseProjectFields, localOnlyConfig, cloudLinkedConfig, projectConfigSchema;
 var init_config = __esm({
   "../../packages/protocol/dist/schemas/frontmatter/config.js"() {
     "use strict";
     init_common();
     init_version();
+    modelTierSchema = z4.string().min(1).max(128).describe("Model role tier ('fast', 'thorough', 'inherit') or a specific model identifier.");
+    projectModelsConfigSchema = z4.object({
+      walker: modelTierSchema.optional(),
+      matcher: modelTierSchema.optional(),
+      judge: modelTierSchema.optional()
+    }).strict();
     baseProjectFields = {
       schema_version: z4.literal(SCHEMA_VERSION),
       id: uuidSchema,
       project_slug: slugSchema,
-      project_name: z4.string().min(1)
+      project_name: z4.string().min(1),
+      models: projectModelsConfigSchema.optional()
     };
     localOnlyConfig = z4.object({
       ...baseProjectFields,
@@ -816,7 +823,14 @@ var init_scenario = __esm({
       reviews: z15.array(z15.string().min(1).max(64)).max(16).default([]),
       baseline_score: z15.number().min(0).max(100).nullish(),
       current_score: z15.number().min(0).max(100).nullish(),
-      target_score: z15.number().min(0).max(100).default(95)
+      target_score: z15.number().min(0).max(100).default(95),
+      /** Environment state preconditions and approximation guidance. */
+      state: z15.object({
+        /** Description of data/records expected to exist in the environment. */
+        description: z15.string().max(2048).nullish(),
+        /** Guidance on how to squint or approximate if exact records are absent. */
+        approximation: z15.string().max(2048).nullish()
+      }).nullish()
     });
   }
 });
@@ -1153,7 +1167,21 @@ var init_walkthrough_bundle = __esm({
           judge_prompt: z19.string().optional(),
           judge_model: z19.string().optional()
         }).optional()
-      }).optional()
+      }).optional(),
+      models: z19.object({
+        walker: z19.string().optional(),
+        matcher: z19.string().optional(),
+        judge: z19.string().optional(),
+        walker_reported: z19.string().optional(),
+        matcher_reported: z19.string().optional(),
+        judge_reported: z19.string().optional(),
+        walker_tier: z19.string().optional(),
+        matcher_tier: z19.string().optional(),
+        judge_tier: z19.string().optional(),
+        execution_mode: z19.enum(["multi_agent", "single_agent"]).optional(),
+        velocity_sec_per_step: z19.number().optional(),
+        total_duration_sec: z19.number().optional()
+      }).optional().describe("AI model configuration and reported runtime provenance for this walkthrough.")
     });
     walkthroughBundleSchema = z19.object({
       manifest: bundleManifestSchema,
@@ -1376,6 +1404,7 @@ var init_walkthrough_canonical = __esm({
       build: buildMetadataSchema.optional(),
       viewport: runViewportSchema.optional(),
       environment: z20.string().optional(),
+      models: z20.record(z20.unknown()).optional(),
       findings: z20.array(canonicalFindingSchema),
       steps: z20.array(canonicalStepSchema),
       human_tests: z20.array(canonicalHumanTestSchema),
@@ -7247,6 +7276,7 @@ async function buildCanonical(projectRoot, manifest, completedAt, inputs) {
     ...manifest.build ? { build: manifest.build } : {},
     ...manifest.viewport ? { viewport: manifest.viewport } : {},
     ...manifest.environment ? { environment: manifest.environment } : {},
+    ...manifest.models ? { models: manifest.models } : {},
     findings: canonicalFindings,
     steps: canonicalSteps,
     human_tests: humanTests,
@@ -7407,6 +7437,20 @@ function renderCanonicalMarkdown(canonical) {
     lines.push(`- Viewport: ${canonical.viewport.device} (${canonical.viewport.width}\xD7${canonical.viewport.height})`);
   }
   lines.push(`- Started: ${canonical.provenance.started_at}`, `- Completed: ${canonical.provenance.completed_at}`, `- Walker prompt: ${canonical.provenance.walker_prompt.id}@${canonical.provenance.walker_prompt.version}`, `- Findings: ${canonical.findings.length}`, `- Steps: ${canonical.steps.length}`);
+  const models = canonical.models;
+  if (models) {
+    const parts = [
+      models.walker ? `Walker: ${models.walker}${models.walker_reported ? ` (${models.walker_reported})` : ""}` : "",
+      models.judge ? `Judge: ${models.judge}${models.judge_reported ? ` (${models.judge_reported})` : ""}` : "",
+      models.matcher ? `Matcher: ${models.matcher}` : ""
+    ].filter(Boolean);
+    if (parts.length > 0) {
+      lines.push(`- Models: ${parts.join(" \xB7 ")}`);
+    }
+    if (typeof models.velocity_sec_per_step === "number") {
+      lines.push(`- Velocity: ~${models.velocity_sec_per_step}s/step (${models.total_duration_sec}s total)`);
+    }
+  }
   const what = canonical.what_worked;
   if (what && what.length > 0) {
     lines.push("", "## What worked");
@@ -7776,6 +7820,7 @@ async function assembleWalkthroughBundle(projectRoot, runId) {
       report_markdown: report3,
       verdict: verdictArray,
       judge_meta: judgeMeta,
+      ...manifest.models ? { models: manifest.models } : {},
       ...buildFields(manifest),
       ...await readCanonicalExtras(projectRoot, runId)
     },
@@ -12266,15 +12311,6 @@ function mcpJson(cmd) {
     2
   );
 }
-function vscodeMcpJson(cmd) {
-  return JSON.stringify(
-    {
-      servers: { iamu: { type: "stdio", command: cmd[0], args: cmd.slice(1) } }
-    },
-    null,
-    2
-  );
-}
 function detectHosts(projectRoot) {
   return HOST_ADAPTERS.filter(
     (host) => host.detectionPaths.some((p) => existsSync3(join3(projectRoot, p)))
@@ -12323,13 +12359,17 @@ var init_registry = __esm({
       {
         name: "GitHub Copilot",
         value: "github-copilot",
-        detectionPaths: [".vscode", ".github/copilot-instructions.md"],
-        supportsSkills: false,
-        getSkillsDir: () => "",
-        getCommandPath: (root, id) => join3(root, ".github", "prompts", `iamu-${id}.prompt.md`),
-        formatCommand: descOnlyFormat,
-        getMcpConfigPath: (root) => join3(root, ".vscode", "mcp.json"),
-        formatMcpConfig: vscodeMcpJson
+        detectionPaths: [
+          ".github/copilot-instructions.md",
+          ".github/skills",
+          ".copilot"
+        ],
+        supportsSkills: true,
+        getSkillsDir: (root) => join3(root, ".github", "skills"),
+        getCommandPath: (root, id) => join3(root, ".github", "skills", `iamu-${id}`, "SKILL.md"),
+        formatCommand: richFormat,
+        getMcpConfigPath: (root) => join3(root, ".mcp.json"),
+        formatMcpConfig: mcpJson
       },
       {
         name: "Cline",
@@ -12511,6 +12551,14 @@ function isCliWrittenSkill(path28) {
     return false;
   }
 }
+function isCliWrittenPrompt(path28) {
+  try {
+    const content = readFileSync3(path28, "utf-8");
+    return content.includes("iamu") || /^generatedBy:/m.test(content);
+  } catch {
+    return false;
+  }
+}
 function planSkillFiles(hosts, projectRoot, version) {
   const skillTemplates = loadSkillTemplates(version);
   const files = [];
@@ -12539,6 +12587,19 @@ function planSkillFiles(hosts, projectRoot, version) {
           }
         }
       }
+      if (host.value === "github-copilot") {
+        for (const cmd of commandsFromSkills(skillTemplates)) {
+          const legacyPrompt = join4(
+            projectRoot,
+            ".github",
+            "prompts",
+            `iamu-${cmd.id}.prompt.md`
+          );
+          if (isCliWrittenPrompt(legacyPrompt)) {
+            files.push({ host, path: legacyPrompt, content: null });
+          }
+        }
+      }
     } else {
       for (const cmd of commandsFromSkills(skillTemplates)) {
         files.push({
@@ -12563,6 +12624,15 @@ function detectInstalledHosts(projectRoot) {
       const skillDir = join4(host.getSkillsDir(projectRoot), "iamu-setup");
       if (existsSync5(skillDir)) return true;
     }
+    if (host.value === "github-copilot") {
+      const legacyPrompt = join4(
+        projectRoot,
+        ".github",
+        "prompts",
+        "iamu-setup.prompt.md"
+      );
+      if (existsSync5(legacyPrompt)) return true;
+    }
     return false;
   });
 }
@@ -14413,6 +14483,18 @@ async function startRun(scenarioSlug, opts) {
   }
   const build = detectBuild({ cwd: projectRoot, label: opts.build });
   const environment = resolveEnvironment(opts.env, start2.url);
+  const cfg = await readConfig(projectRoot).catch(() => null);
+  const walker = opts.walker ?? process.env.IAMU_WALKER_MODEL ?? cfg?.models?.walker ?? "fast";
+  const judge = opts.judge ?? process.env.IAMU_JUDGE_MODEL ?? cfg?.models?.judge ?? "thorough";
+  const matcher = opts.matcher ?? process.env.IAMU_MATCHER_MODEL ?? cfg?.models?.matcher ?? "thorough";
+  const models = {
+    walker,
+    judge,
+    matcher,
+    walker_tier: ["fast", "thorough", "inherit"].includes(walker) ? walker : "custom",
+    judge_tier: ["fast", "thorough", "inherit"].includes(judge) ? judge : "custom",
+    matcher_tier: ["fast", "thorough", "inherit"].includes(matcher) ? matcher : "custom"
+  };
   let revisit = [];
   try {
     revisit = await computeRevisitPlaces(projectRoot, scenarioSlug, start2.url);
@@ -14430,6 +14512,7 @@ async function startRun(scenarioSlug, opts) {
     status: "running",
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
     completed_at: null,
+    models,
     ...build ? { build } : {},
     ...environment ? { environment } : {},
     ...revisit.length > 0 ? { revisit } : {},
@@ -14451,6 +14534,7 @@ async function startRun(scenarioSlug, opts) {
           ...targetWarning ? { target_warning: targetWarning } : {},
           persona_slug: fm.persona,
           outline_slug: fm.outline,
+          models,
           build: build ?? null,
           environment: environment ?? null,
           revisit,
@@ -14469,6 +14553,9 @@ async function startRun(scenarioSlug, opts) {
   console.log(`  ${chalk11.dim("persona:")}  ${fm.persona}`);
   console.log(`  ${chalk11.dim("outline:")}  ${fm.outline}`);
   console.log(`  ${chalk11.dim("target:")}   ${start2.url}`);
+  console.log(
+    `  ${chalk11.dim("models:")}   walker: ${chalk11.cyan(walker)} \xB7 judge: ${chalk11.cyan(judge)} \xB7 matcher: ${chalk11.cyan(matcher)}`
+  );
   if (targetWarning) {
     console.log(`  ${symbols.warning} ${chalk11.yellow(targetWarning)}`);
   }
@@ -16265,7 +16352,10 @@ var init_browse_actions = __esm({
         usage: "goto <url>",
         minArgs: 1,
         run: async (p, args) => {
-          await p.goto(args[0], { waitUntil: "domcontentloaded" });
+          await p.goto(args[0], {
+            waitUntil: "domcontentloaded",
+            timeout: 1e4
+          });
         }
       },
       click: {
@@ -16426,6 +16516,12 @@ var init_browse_driver = __esm({
       commandLine: (pid) => readProcessCommandLine(pid),
       kill(pid) {
         try {
+          if (process.platform !== "win32") {
+            try {
+              process.kill(-pid, "SIGTERM");
+            } catch {
+            }
+          }
           process.kill(pid, "SIGTERM");
         } catch {
         }
@@ -16652,6 +16748,7 @@ __export(browse_exports, {
   readBrowseState: () => readBrowseState,
   shouldDisableSandbox: () => shouldDisableSandbox,
   start: () => start,
+  waitForVisualStability: () => waitForVisualStability,
   withPage: () => withPage
 });
 import { randomUUID as randomUUID7 } from "crypto";
@@ -16801,6 +16898,8 @@ function chromeArgs(opts, port, headless) {
     `--window-size=${opts.width ?? "1280"},${opts.height ?? "900"}`,
     "--no-first-run",
     "--no-default-browser-check",
+    "--password-store=basic",
+    "--use-mock-keychain",
     ...headless ? ["--headless=new", "--disable-dev-shm-usage", "--disable-gpu"] : [],
     ...shouldDisableSandbox() ? ["--no-sandbox"] : [],
     "about:blank"
@@ -16858,6 +16957,45 @@ async function stop(opts, driver) {
   }
   report2(opts, { stopped: true }, [`  ${chalk20.green("\u2713")} Browser stopped`]);
 }
+async function waitForVisualStability(page, maxWaitMs = 300) {
+  let timer;
+  try {
+    const nodeTimeout = new Promise((resolve3) => {
+      timer = setTimeout(resolve3, maxWaitMs + 100);
+    });
+    const browserWait = page.evaluate((maxWait) => {
+      return new Promise((resolve3) => {
+        const timeout = setTimeout(resolve3, maxWait);
+        const done = () => {
+          clearTimeout(timeout);
+          resolve3();
+        };
+        const g = globalThis;
+        if (typeof g.requestAnimationFrame !== "function") {
+          done();
+          return;
+        }
+        g.requestAnimationFrame(() => {
+          g.requestAnimationFrame?.(() => {
+            const animations = g.document?.getAnimations ? g.document.getAnimations().filter((a) => a.playState === "running" && a.finished) : [];
+            if (animations.length === 0) {
+              done();
+              return;
+            }
+            Promise.allSettled(
+              animations.map((a) => a.finished)
+            ).finally(done);
+          });
+        });
+      });
+    }, maxWaitMs).catch(() => {
+    });
+    await Promise.race([browserWait, nodeTimeout]);
+  } catch {
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 async function withPage(opts, driver, fn, target) {
   const state = readBrowseState();
   if (!state) {
@@ -16877,9 +17015,9 @@ async function withPage(opts, driver, fn, target) {
     await fn(page);
     await page.waitForLoadState("domcontentloaded").catch(() => {
     });
-    await page.waitForTimeout(400);
     let screenshot = null;
     if (opts.shot) {
+      await waitForVisualStability(page);
       screenshot = path22.resolve(opts.shot);
       mkdirSync(path22.dirname(screenshot), { recursive: true });
       await page.screenshot({ path: screenshot, fullPage: Boolean(opts.full) });
@@ -18438,13 +18576,21 @@ function defaultFrontmatter(type2, id, slug, name, opts) {
         url: opts.url,
         authority_level: opts.authority ?? "informational"
       };
-    case "scenario":
+    case "scenario": {
+      const stateObj = opts.stateDescription || opts.stateApproximation ? {
+        state: {
+          ...opts.stateDescription ? { description: opts.stateDescription } : {},
+          ...opts.stateApproximation ? { approximation: opts.stateApproximation } : {}
+        }
+      } : {};
       return {
         ...base,
         outline: opts.outline ?? null,
         persona: opts.persona ?? null,
-        ...opts.entry ? { entry_path: opts.entry } : {}
+        ...opts.entry ? { entry_path: opts.entry } : {},
+        ...stateObj
       };
+    }
     default:
       return base;
   }
@@ -18838,6 +18984,17 @@ function composeWalkerPrompt(p) {
     "",
     "## First-person brief",
     p.brief ?? "",
+    ...p.context ? ["", "## Product domain & regulatory context", p.context.trim()] : [],
+    ...p.state?.description || p.state?.approximation ? [
+      "",
+      "## Expected state & semantic squinting",
+      p.state.description ? `Expected state: ${p.state.description}` : "",
+      p.state.approximation ? `Approximation strategy: ${p.state.approximation}` : "",
+      "Squinting Guardrails:",
+      "\u2022 If the exact target record/option is not available, apply the approximation strategy above to pick the closest plausible entity within the domain flow.",
+      "\u2022 Squinting does NOT permit drifting to unrelated settings, account profiles, or off-target pages. Stay strictly within the scenario journey.",
+      "\u2022 If the system is completely empty or unseeded, and your persona role cannot create data, do NOT report false product bugs about the empty state. Note that preconditions are unseeded/blocked."
+    ].filter(Boolean) : [],
     ...revisitSection(p.revisit ?? []),
     "",
     "## Access",
@@ -18866,7 +19023,7 @@ function composeWalkerPrompt(p) {
     `Screenshots to: ${rd}/screenshots/step-N.png \u2014 absolute paths.`,
     `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --json \u2014 then add the body (description + "## Recommendation") below the frontmatter of the file it returns.`,
     "`--step <N>` is the step whose screenshot shows the problem (or strength): it is the evidence people see next to the finding, so record that step and its screenshot first, and pick the screenshot where the thing is actually visible.",
-    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...]} \u2014 one sentence each, in the persona's language.`,
+    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...], "model": "<your model identifier if known, e.g. claude-3-5-haiku, gemini-3.8-flash, or unspecified>"} \u2014 one sentence each, in the persona's language.`,
     "",
     "Do not read the product's source code, other iamu/ entity files, or earlier runs: you know only what the persona knows.",
     "",
@@ -18986,7 +19143,8 @@ async function instructionsWalk(opts) {
   const result = {
     scenario: {
       slug: sfm.slug,
-      brief: scenario.body.trim() || null
+      brief: scenario.body.trim() || null,
+      state: sfm.state ?? null
     },
     persona: {
       slug: sfm.persona,
@@ -19040,7 +19198,9 @@ async function instructionsWalk(opts) {
       runDirPath,
       projectRoot,
       surface: opts.surface ?? "browse",
-      viewport
+      viewport,
+      state: sfm.state ?? null,
+      context: contextYml
     }) : null
   };
   if (opts.json) {
@@ -19052,6 +19212,11 @@ async function instructionsWalk(opts) {
   console.log(`  ${chalk26.dim("scenario:")}  ${sfm.slug}`);
   console.log(`  ${chalk26.dim("persona:")}   ${pfm.name} (${pfm.role})`);
   console.log(`  ${chalk26.dim("outline:")}   ${ofm.title}`);
+  if (sfm.state?.description || sfm.state?.approximation) {
+    console.log(
+      `  ${chalk26.dim("state:")}     ${sfm.state.description ? sfm.state.description : sfm.state.approximation ?? ""}`
+    );
+  }
   if (targetUrl) console.log(`  ${chalk26.dim("target:")}    ${targetUrl}`);
   console.log(
     `  ${chalk26.dim("access:")}    ${projectAccess || personaAccess ? `${projectAccess ? "project" : ""}${projectAccess && personaAccess ? " + " : ""}${personaAccess ? "persona" : ""}` : "not recorded (walker would run as whoever is signed in)"}`
@@ -19688,6 +19853,36 @@ async function complete(runId, opts) {
     return;
   }
   const completedAt = pickCompletedAt(run.manifest);
+  const walkerSummary = await readWalkerSummary(run.runDirPath);
+  let judgeReported;
+  try {
+    const verdictsRaw = await fs26.readFile(
+      path26.join(run.runDirPath, "verdicts.json"),
+      "utf8"
+    );
+    const parsed = JSON.parse(verdictsRaw);
+    if (parsed.provenance?.model) {
+      judgeReported = parsed.provenance.model;
+    }
+  } catch {
+  }
+  const stepCount = provenanceAudit.step_count;
+  const durationSec = provenanceAudit.duration_seconds ?? (run.manifest.created_at && Date.parse(completedAt) > Date.parse(run.manifest.created_at) ? Math.round(
+    (Date.parse(completedAt) - Date.parse(run.manifest.created_at)) / 1e3 * 10
+  ) / 10 : null);
+  const velocitySec = provenanceAudit.avg_step_interval_seconds ?? (durationSec != null && stepCount > 1 ? Math.round(durationSec / (stepCount - 1) * 10) / 10 : null);
+  const existingModels = run.manifest.models ?? {};
+  const updatedModels = {
+    ...existingModels,
+    ...walkerSummary.model ? { walker_reported: walkerSummary.model } : {},
+    ...judgeReported ? { judge_reported: judgeReported } : {},
+    ...durationSec != null ? { total_duration_sec: durationSec } : {},
+    ...velocitySec != null ? { velocity_sec_per_step: velocitySec } : {}
+  };
+  run.manifest = {
+    ...run.manifest,
+    models: updatedModels
+  };
   const assembled = await assembleRun(
     run.projectRoot,
     runId,
@@ -19848,6 +20043,17 @@ function printCompletionSummary(run, completedAt, assembled, extras, provenanceA
   console.log(`  steps      ${count(canonical.steps.length)}`);
   console.log(`  started    ${chalk30.dim(manifest.created_at)}`);
   console.log(`  completed  ${chalk30.dim(completedAt)}`);
+  const models = manifest.models;
+  if (models?.velocity_sec_per_step != null) {
+    console.log(
+      `  velocity   ${chalk30.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk30.dim(`(${models.total_duration_sec}s total)`)}`
+    );
+  }
+  if (models && (models.walker || models.judge || models.matcher)) {
+    const w = models.walker_reported ? `${models.walker} (${models.walker_reported})` : models.walker ?? "fast";
+    const j = models.judge_reported ? `${models.judge} (${models.judge_reported})` : models.judge ?? "thorough";
+    console.log(`  models     ${chalk30.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
+  }
   console.log();
   console.log(
     `  ${chalk30.dim("canonical:")} ${chalk30.dim(path26.relative(projectRoot, assembled.canonicalPath))}`
@@ -19941,9 +20147,11 @@ async function readWalkerSummary(runDirPath) {
       await fs26.readFile(path26.join(runDirPath, "summary.json"), "utf8")
     );
     const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : void 0;
+    const model = typeof data.model === "string" && data.model.trim() !== "" ? data.model.trim() : void 0;
     return {
       what_worked: strings(data.what_worked),
-      open_questions: strings(data.open_questions)
+      open_questions: strings(data.open_questions),
+      model
     };
   } catch {
     return {};
@@ -20684,6 +20892,12 @@ function registerProjectCommands(program) {
   ).option("--outline <slug>", "Outline slug (scenario only)").option("--persona <slug>", "Persona slug (scenario only)").option(
     "--entry <path>",
     "Where the situation starts, as a path on the product, e.g. /en/episodes/1 (scenario only)"
+  ).option(
+    "--state-description <text>",
+    "Assumed environment data/records state (scenario only)"
+  ).option(
+    "--state-approximation <text>",
+    "Guidance on how persona should approximate/squint if records are missing (scenario only)"
   ).option("--url <url>", "Document the source cites (source only, required)").option(
     "--authority <level>",
     "legislation | regulation | standard | company_policy | guideline | informational (source only, default informational)"
@@ -20725,6 +20939,15 @@ function registerWalkthroughCommands(program) {
   ).option(
     "--env <name>",
     "Environment the product runs in (default: the target URL's origin)"
+  ).option(
+    "--walker <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for driving browser navigation (default: fast)"
+  ).option(
+    "--judge <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for human test evaluation (default: thorough)"
+  ).option(
+    "--matcher <tierOrModel>",
+    "Model tier ('fast', 'thorough', 'inherit') or model ID for finding matching (default: thorough)"
   ).option(
     "--check",
     "Enforce target URL reachability (fail fast if server is offline)"

package/dist/templates/prompts/walk.md

@@ -70,11 +70,9 @@ Continuity: steps form ONE ongoing monologue. From step 2 onward, don't restate
 
 ## Pacing
 
-**Aim for 10-20 steps.** Stop when the primary task verdict is clear — either the persona accomplished their goal or they hit friction that blocks them. A focused 12-step walkthrough with sharp findings is worth more than a 40-step exhaustive tour.
+**Aim for 10-20 steps.** When evaluating a form or journey, inspect all relevant sections across the workflow (e.g., travel details, per diem, deductions, expenses). Do not abandon the walkthrough after logging a single defect — continue through the remaining sections to uncover all distinct compliance and usability gaps before completing. A complete walkthrough with sharp findings across all sections gives the team high-value signal.
 
-Do not try to complete every interaction. If a form has 15 fields, the observation is "this persona would give up at field 4" — note the finding and move on.
-
-Do try key interactions that reveal something: click the main CTA, open a dropdown, check what filters exist. These are cheap observations with high signal.
+Do try key interactions that reveal something: click the main CTA, open a dropdown, check what options or deductions exist. These are cheap observations with high signal.
 
 Follow the persona's motivation. Spend time on what matters to them. When you have enough evidence to answer "would this person come back?" — you're done.
 
@@ -100,6 +98,20 @@ Your browser tooling has limitations that can look like product bugs. Before rec
 
 Do NOT silently suppress findings you suspect are tooling issues. Record them with the caveat — the human triaging can verify.
 
+## Expected state vs product bugs (Empty state & unseeded data)
+
+When an environment is unseeded or test records are missing:
+- An empty table or "No records found" screen is NOT automatically a product bug. If your scenario assumes existing data (e.g. reviewing past entries or auditing submitted claims), check whether the environment simply lacks seed data.
+- If your persona role is a creator (e.g. employee or consultant creating an item), click the creation CTA (e.g. "+ Ny reseräkning", "+ New") and proceed with your task.
+- If your persona role is read-only (e.g. an auditor or manager) and cannot create data, do NOT record false "missing data" bugs against the product. Conclude the walk noting that the environment lacks the required preconditions.
+
+## Semantic squinting (Adapting to environmental mismatch)
+
+Your prompt may include an approximation strategy (e.g. "If Malmö is missing, choose Göteborg").
+- **Squint at the closest match:** When the exact target name, category, or record described in your brief isn't available in this environment, pick the closest available alternative that allows testing the workflow.
+- **Stay in the journey:** Approximation is bounded. Never drift to unrelated modules (e.g. settings, profile, admin panels) just because a specific test record was absent.
+- **Log the approximation:** In your step note (`note`), state clearly that you chose the closest alternative according to your instructions.
+
 ## 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.

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

@@ -95,9 +95,13 @@ Human Checkpoint: <Concrete binary yes/partial/no question scored at evaluation>
 Roles with Stakes:
 • <Role 1>: <Stake>
 • <Role 2>: <Stake>
+
+Execution Preconditions (resolved at iamu-run):
+• Assumed State: <What records/data should exist, e.g. "Department with existing risk register containing open hazards">
+• Squint Guidance: <How the walker should approximate if exact records are missing, e.g. "If no packaging hazard exists, select any physical safety hazard and proceed with delegation">
 ```
 
-Ask the user: "Ready to test this draft, or would you like to refine the focus question or circumstances? (Enter to accept, or type adjustments)"
+Ask the user: "Ready to test this draft, or would you like to refine the focus question, preconditions, or circumstances? (Enter to accept, or type adjustments)"
 
 ### 4. Pick or propose personas
 
@@ -164,12 +168,12 @@ The `--role` and `--disposition` flags populate frontmatter directly. If `iamu/c
 
 **4. Scenario** (the binding):
 ```bash
-iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez --json
+iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez [--entry /path/on/the/product] [--state-description "<Assumed state description>"] [--state-approximation "<Squint guidance for walker>"] --body "<First-person brief in persona voice (3–5 sentences)>" --json
 ```
 When the situation begins on a specific page (the persona follows a link from a video, an email, a search result), add `--entry /path/on/the/product` — the run starts there instead of the home page.
-`--outline` is required. `--persona` is optional (omit for drafts). Write the first-person brief as the markdown body — 3–5 sentences in the persona's voice.
+`--outline` is required. `--persona` is optional (omit for drafts). Pass `--state-description` and `--state-approximation` if preconditions were defined in step 3 to populate the scenario's `state:` frontmatter automatically.
 
-For drafts (no persona): omit `--persona`, omit the brief body.
+For drafts (no persona): omit `--persona`, omit `--body`.
 
 ### 7. Summarize
 

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

@@ -39,7 +39,6 @@ Read `iamu/context.yml`. Extract and hold:
 - **Domain + industry** — what world does this product operate in?
 - **Actors** — real roles with real responsibilities. These are scenario and persona seed material.
 - **Governed_by** — regulations and standards (if applicable). These create structural tensions in regulated domains.
-- **Glossary** — domain vocabulary. Scenarios and personas must use these terms, not generic UI words.
 - **Notes body** — extended context, often containing workflow descriptions, pain points, organizational dynamics.
 
 ### 2. Load existing coverage
@@ -116,7 +115,7 @@ Next action:
 Ground rules for generation:
 
 - **Start from the actor's week, not the feature list.** What does this person actually do on a Tuesday? What goes wrong? What requires judgment?
-- **Use domain vocabulary from the glossary.** If the glossary says "skyddsombud" not "safety representative," use "skyddsombud."
+- **Use authentic domain vocabulary.** Speak in the language of the domain and the product UI (e.g., "skyddsombud" rather than generic "safety representative"), avoiding abstract test jargon.
 - **Prefer mundane frequency over dramatic edge cases.** The scenario that happens every week reveals more than the one that happens once a year.
 - **Structural tensions come from the domain, not from product limitations.** A real tension: "the regulation requires immediate reporting but the coordinator handles 3 sites." A fake tension: "the CSV upload has a 50-row limit."
 - **Never mention the product, its UI, its features, or its limitations.** The scenario exists in the domain. The product encounter happens during the walkthrough.