@iamu-dev/iamu 0.6.0-beta.0 → 0.8.0-beta.0

package/dist/commands/browse.d.ts

@@ -22,6 +22,8 @@ export interface BrowseOptions {
     json?: boolean;
     /** Annotate snapshot with 1-based index numbers [#N] for click-index / fill-index */
     indexed?: boolean;
+    /** `clear-storage`: the origin to clear (default: the run's target URL). */
+    origin?: string;
 }
 interface BrowseState {
     port: number;
@@ -176,6 +178,22 @@ export declare function detectAntiBotChallenge(page: Page, allowEvaluate?: boole
 export declare function withPage(opts: BrowseOptions, driver: BrowserDriver, fn: (page: Page) => Promise<void>, 
 /** What the action looks for, named for the error message. */
 target?: string): Promise<PageResult | null>;
+/** What {@link clearOriginStorage} removed. */
+export interface ClearedStorage {
+    origin: string;
+    local_storage_keys: string[];
+    cookies: string[];
+}
+/**
+ * Leave the page for `about:blank` (so the app cannot write its state
+ * back on unload), then clear cookies, localStorage, IndexedDB and
+ * caches for `origin`. Returns what was there, or an error message.
+ */
+export declare function clearOriginStorage(origin: string, driver?: BrowserDriver, 
+/** Page to open after clearing (the run's start URL); else about:blank. */
+returnTo?: string): Promise<ClearedStorage | {
+    error: string;
+}>;
 /**
  * `iamu browse <command> [args…]` — dispatch one browse subcommand.
  * Failures print to stderr and set exit code 1.

package/dist/commands/design-draft.d.ts

@@ -0,0 +1,11 @@
+import { type DesignOptions } from "./design-output.js";
+/**
+ * Print a design doc draft in iamu's layout, filled in from the code;
+ * with --out also write it there; with --decline record that the offer
+ * was declined instead.
+ */
+export declare function designTemplate(opts: DesignOptions): Promise<void>;
+/** Check a draft: errors and warnings, writing nothing. */
+export declare function designDraftCheck(opts: DesignOptions): Promise<void>;
+/** Write a draft as the project's design doc and record it. */
+export declare function designAdopt(opts: DesignOptions): Promise<void>;

package/dist/commands/design-output.d.ts

@@ -23,6 +23,14 @@ export interface DesignOptions {
      * the designer's earlier notes, so it cannot just confirm them.
      */
     blind?: boolean;
+    /** template, draft-check, adopt: the app the doc is for. */
+    dir?: string;
+    /** template: also write the draft to this file. */
+    out?: string;
+    /** template: record that the offer was declined. */
+    decline?: boolean;
+    /** adopt: where the doc goes (default: <dir>/DESIGN.md). */
+    to?: string;
 }
 /** JSON with --json, else the human output. */
 export declare const out: (opts: DesignOptions, value: unknown, human: () => void) => void;

package/dist/commands/doctor-design.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorCheck } from "./doctor.js";
+/**
+ * The design docs the project recorded: files that are gone, references
+ * inside them to paths, components and tokens that no longer exist, an
+ * unmigrated legacy doc, stale proposals and an outdated agent block.
+ * No recorded docs is not a fault: the designer then reviews by general
+ * craft, so it is reported as ok with a hint.
+ */
+export declare function checkDesignDocs(projectRoot: string): Promise<DoctorCheck[]>;

package/dist/commands/doctor.d.ts

@@ -1,5 +1,5 @@
 export interface DoctorCheck {
-    category: "runtime" | "browser" | "project" | "agent" | "cloud" | "target";
+    category: "runtime" | "browser" | "project" | "design" | "agent" | "cloud" | "target";
     name: string;
     status: "ok" | "warn" | "error";
     message: string;

package/dist/commands/finding-stability.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Spike (fast-critic-loop D6): how stable each finding has been across
+ * its scenario's runs, computed on read from local run history. No new
+ * stored field; the harden phase moves this into the match stage.
+ *
+ * A data point per non-blocked completed run of the scenario, oldest
+ * first, from the finding's first observation on:
+ * - `1` the run recorded it: a finding file of that run carries its
+ *   `canonical_id`, or the run's verification says it persists;
+ * - `0` the run re-checked it and saw it working: `verification.resolved`
+ *   or the matcher's `rechecked_fixed` (step-backed, not absence);
+ * - no point at all when the run said nothing about it (`not_observed`,
+ *   `uncertain`, or it was not part of the comparison). A walk that took
+ *   another path is not evidence of a flicker, the same rule as
+ *   `fix-state.ts` ("never from absence").
+ *
+ * `unstable` when the points since the last fix (a finding with that
+ * canonical id triaged `addressed`/`fixed`) change value two or more
+ * times; `first_seen` when it was observed once; otherwise `stable`.
+ */
+import { type RunEvidence } from "@iamu-dev/local-store";
+/** How far a builder can trust a finding to be real and lasting. */
+export type FindingStability = "stable" | "unstable" | "first_seen";
+/** One run's word on a finding: observed (1) or re-checked fixed (0). */
+export interface StabilityPoint {
+    observed: boolean;
+    /** Run start, epoch ms; null when unknown. */
+    at: number | null;
+}
+/**
+ * The D6 rule on one finding's chronological points.
+ *
+ * @param points - Oldest first; runs with no word on the finding left out.
+ * @param fixedAt - Epoch ms of the latest recorded fix, or null.
+ * @returns `first_seen`, `unstable` or `stable`.
+ *
+ * @example
+ * ```ts
+ * stabilityOf([{ observed: true, at: 1 }, { observed: false, at: 2 }, { observed: true, at: 3 }], null);
+ * // "unstable"
+ * ```
+ */
+export declare function stabilityOf(points: readonly StabilityPoint[], fixedAt: number | null): FindingStability;
+interface HistoryFinding {
+    run?: string;
+    scenario?: string;
+    canonical_id?: string;
+    triage_status?: string;
+    updated_at?: string;
+    created_at?: string;
+    source?: string;
+    lens?: string;
+}
+/** What the stability read needs from disk; load once per report. */
+export interface StabilityHistory {
+    runs: RunEvidence[];
+    findings: HistoryFinding[];
+}
+/** Read the run evidence and finding files once. Never throws. */
+export declare function loadStabilityHistory(projectRoot: string): Promise<StabilityHistory>;
+/**
+ * Stability of every canonical finding of `scenario`, as of `runId`
+ * (later runs are not its past).
+ *
+ * @param history - From {@link loadStabilityHistory}.
+ * @param scenario - Scenario slug.
+ * @param runId - The run being reported; runs after it are ignored.
+ * @returns canonical id → stability.
+ */
+export declare function scenarioStability(history: StabilityHistory, scenario: string, runId: string): Map<string, FindingStability>;
+export {};

package/dist/commands/fix-brief.d.ts

@@ -1,9 +1,13 @@
 import { type DesignerFixBrief, type FixBrief } from "@iamu-dev/local-store";
-export declare function fixBrief(ref: string, opts: {
+export declare function fixBrief(ref: string | undefined, opts: {
+    wave?: boolean;
     json?: boolean;
 }): Promise<void>;
 /**
  * A loop step as a person reads it: each backticked field name becomes
  * the section above that holds it, or its value.
  */
-export declare function readable(step: string, b: Pick<FixBrief | DesignerFixBrief, "rerun" | "closing_check">): string;
+export declare function readable(step: string, b: Pick<FixBrief | DesignerFixBrief, "closing_check"> & {
+    rerun?: string | string[];
+    scenarios_to_rerun?: string[];
+}): string;

package/dist/commands/live-run-client.d.ts

@@ -20,6 +20,7 @@ export interface RegisterLiveRunParams {
     targetUrl: string;
     startedAt?: string;
     lenses?: string[];
+    json?: boolean;
     fetchFn?: typeof fetch;
 }
 export interface RegisterLiveRunResult {

package/dist/commands/report-data.d.ts

@@ -1,5 +1,6 @@
 import type { CanonicalWalkthrough } from "@iamu-dev/protocol";
 import { type OverviewView, type RunView, type VerdictLabel } from "../ui/report-view.js";
+import { type StabilityHistory } from "./finding-stability.js";
 export interface CompletedRun {
     runId: string;
     manifest: Record<string, unknown>;
@@ -12,5 +13,5 @@ export declare function readCompletedRuns(projectRoot: string, runIds: string[],
 export declare function verdictLabel(c: CanonicalWalkthrough | null): VerdictLabel;
 /** "/request · step 8" from a page URL and a step id. */
 export declare function whereOf(pageUrl: unknown, stepId: unknown): string | null;
-export declare function buildRunView(projectRoot: string, run: CompletedRun): Promise<RunView>;
+export declare function buildRunView(projectRoot: string, run: CompletedRun, history?: StabilityHistory): Promise<RunView>;
 export declare function buildOverview(projectRoot: string, runs: CompletedRun[]): Promise<OverviewView>;

package/dist/commands/set-entity.d.ts

@@ -1,3 +1,4 @@
+import { type ContextFrontmatter } from "@iamu-dev/protocol";
 /**
  * Options for `iamu set`. Every field is staging: where a walk starts,
  * what the world holds, which account a persona uses, which routes an
@@ -52,6 +53,12 @@ export interface SetEntityOptions {
     description?: string | false;
     /** Project name (context). */
     name?: string | false;
+    /** Governing documents/standards (context patch). */
+    governedBy?: ContextFrontmatter["governed_by"] | false;
+    /** Domain actors (context patch). */
+    actors?: ContextFrontmatter["actors"] | false;
+    /** Domain glossary (context patch). */
+    glossary?: ContextFrontmatter["glossary"] | false;
     /** Markdown body narrative (testability, context). */
     body?: string;
     /** JSON patch file (or - for stdin) containing staging fields. */

package/dist/commands/timings.d.ts

@@ -0,0 +1,19 @@
+/** A bracket around a pipeline stage: `start` when a command begins, `end` when it has written its output. */
+export type TimingEvent = "start" | "end";
+/**
+ * Spike (fast-critic-loop D0): append one rough timing line to
+ * `<runDir>/timings.jsonl`. Never creates the run directory and never
+ * throws — a timing that cannot be written is simply lost, so a command
+ * never fails because of it. No lock: concurrent appends of one short
+ * line are fine for a rough read.
+ *
+ * @param runDirPath - Absolute path of the run directory (`iamu/.runs/<id>`).
+ * @param stage - The command name, e.g. `match-record`.
+ * @param event - `start` or `end`.
+ *
+ * @example
+ * ```ts
+ * await logTiming(runDirPath, "match", "end");
+ * ```
+ */
+export declare function logTiming(runDirPath: string | null | undefined, stage: string, event: TimingEvent): Promise<void>;

package/dist/commands/triage.d.ts

@@ -10,6 +10,12 @@ export interface TriageOptions {
     scope?: string;
     /** `false` (`--no-guidance`): dismiss without writing a guidance rule. */
     guidance?: boolean;
+    /**
+     * Project-wide sweep ("we never want X"): dismiss all matching open
+     * persona and designer findings across the project and record a
+     * project-wide guidance rule.
+     */
+    sweep?: boolean | string;
     json?: boolean;
 }
 /**