@exodus/xqa 1.14.0 → 1.14.2

package/README.md

@@ -14,12 +14,20 @@ The tool manages configuration, project initialization, session state tracking,
 
 Initialize a new xqa project in the current directory.
 
-Creates a `.xqa/` directory with templates and subdirectories for specs, designs, and suites. Installs the `xqa-spec` skill for creating test specs.
+Creates a `.xqa/` directory with `app.md` and `explore.md` templates plus subdirectories for specs, designs, and suites. Installs bundled xqa skills.
 
 ```bash
 xqa init
 ```
 
+### update
+
+Update installed xqa skills to the current CLI version.
+
+```bash
+xqa update
+```
+
 ### explore [prompt]
 
 Run the explorer agent; omit prompt for a full breadth-first sweep.
@@ -31,44 +39,73 @@ xqa explore                          # breadth-first exploration
 xqa explore "test the login flow"    # focused exploration
 xqa explore -v prompt,screen         # verbose output for categories
 xqa explore -v                       # verbose output for all categories
+xqa explore -t 600                   # override explorer timeout (seconds)
+xqa explore --debug                  # log timing and event details to stderr
 ```
 
-Flag: `-v, --verbose [categories]` — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.
+Flags:
+
+- `-v, --verbose [categories]` — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.
+- `-t, --timeout <seconds>` — Explorer timeout in seconds (overrides `QA_EXPLORE_TIMEOUT_SECONDS`).
+- `--debug` — Log timing and event details to stderr.
 
 ### spec [spec-file]
 
 Run the explorer agent against a spec file.
 
-Loads a spec markdown file from `.xqa/specs/` (or an absolute path) and executes the agent against it. Spec files define entry points, steps, and optional timeouts. Omit the argument to pick from available specs interactively.
+Loads a spec markdown file from `.xqa/specs/` (or an absolute path) and executes the agent against it. Omit the argument to pick from available specs interactively.
 
 ```bash
 xqa spec                                      # interactive spec picker
-xqa spec .xqa/specs/authentication.test.md   # explicit spec file
+xqa spec .xqa/specs/authentication.test.md    # explicit spec file
 xqa spec -v tools,memory                      # verbose output
+xqa spec --debug                              # debug logging
 ```
 
-Flag: `-v, --verbose [categories]` — Same as explore.
+Flags:
+
+- `-v, --verbose [categories]` — Same as explore.
+- `--debug` — Log timing and event details to stderr.
 
 Spec file format (YAML frontmatter + markdown):
 
 ```markdown
 ---
 feature: 'Feature Name'
-entry: 'Screen name or navigation path'
 timeout: 300
 ---
 
 # Spec content
 ```
 
+Frontmatter fields: `feature` (required), `timeout` (optional, seconds).
+
+### run
+
+Run a test suite or a set of spec files in parallel across booted simulators.
+
+Exactly one of `--suite` or `--spec` is required.
+
+```bash
+xqa run --suite smoke                         # run .xqa/suites/smoke.suite.json
+xqa run --spec 'specs/**/*.test.md'           # run matching spec files
+xqa run --suite smoke --debug                 # debug logging
+```
+
+Flags:
+
+- `--suite <name>` — Name of the suite (`<name>.suite.json`) under `.xqa/suites/`.
+- `--spec <globs...>` — Glob patterns matching spec files, resolved from the xqa directory.
+- `--debug` — Log timing and event details to stderr.
+
 ### review [findings-path]
 
 Review findings and mark false positives.
 
-Interactive session for triaging findings generated by explore or spec runs. Displays findings with confidence scores, steps, and screenshots. Mark findings as false positives (with optional reason) or undo previous dismissals. Saves dismissals to `.xqa/dismissals.json`. Defaults to the last findings path if omitted.
+Interactive session for triaging findings generated by explore or spec runs. Mark findings as dismissed (with optional reason) or undo previous dismissals. Dismissals are written to `dismissals.json` next to the `.xqa` directory (override with `QA_DISMISSALS_PATH`). Defaults to the last findings path if omitted.
 
 ```bash
-xqa review                                      # use last findings file
+xqa review                                     # use last findings file
 xqa review .xqa/output/findings-abc123.json    # explicit path
 ```
 
@@ -93,26 +130,35 @@ xqa completion bash  # generate bash completions
 xqa completion zsh   # generate zsh completions
 ```
 
-### Suite hooks
+### Suite config
 
-Suite config files may declare a `beforeEach` hook that runs before every work item on every simulator. Use this for project-owned setup (wallet provisioning, cache warming, login seeding).
+Suite files live at `.xqa/suites/<name>.suite.json` and declare the work items plus optional hooks.
 
 ```json
 {
   "specs": ["specs/send.test.md"],
+  "freestyle": [{ "prompt": "explore settings", "timeoutSeconds": 300 }],
   "hooks": {
     "beforeEach": {
       "script": "qa/prepare-sim.mjs",
-      "env": { "APP_PROFILE": "funded" }
+      "env": { "APP_PROFILE": "funded" },
+      "timeoutSeconds": 120
     }
   }
 }
 ```
 
+Fields:
+
+- `specs` (optional) — glob patterns resolved from the xqa directory.
+- `freestyle` (optional) — either a positive integer (N empty entries) or an array of `{ prompt?, timeoutSeconds }` entries.
+- At least one of `specs` or `freestyle` must resolve to a work item.
+- `hooks.beforeEach` (optional) — runs before every work item on every simulator. Use for project-owned setup (wallet provisioning, cache warming, login seeding).
+
 The hook script is invoked as a Node child process. It receives:
 
 - Inherited `process.env`
-- Suite-declared `env` (merged below reserved keys)
+- Suite-declared `env` overlaid with reserved keys (reserved wins)
 - Reserved xqa-owned keys: `XQA_SIM_UDID`, `XQA_ITEM_ID`, `XQA_ITEM_TYPE`, `XQA_ITEM_NAME`, `XQA_SUITE`, and (when item type is `spec`) `XQA_SPEC_PATH`
 
 Suite-declared `env` cannot override reserved keys — the parser rejects such configs.
@@ -121,7 +167,7 @@ Contract:
 
 - Exit 0 → proceed with item.
 - Non-zero exit → item marked failed, `executeItem` skipped, counts toward simulator-unhealthy threshold.
-- 120s timeout (not configurable in v1).
+- Default 120s timeout, overridable via `hooks.beforeEach.timeoutSeconds`.
 - Honors the suite abort signal.
 
 ## Configuration
@@ -133,15 +179,17 @@ Configuration is loaded from environment variables and `.env.local`:
 - `QA_RUN_ID` (optional) — Custom run identifier; defaults to auto-generated
 - `QA_EXPLORE_TIMEOUT_SECONDS` (optional) — Exploration timeout in seconds
 - `QA_BUILD_ENV` (optional) — Build environment: `dev` or `prod` (default: prod)
+- `QA_DISMISSALS_PATH` (optional) — Override the dismissals file path used by `xqa review`
 
 ## Architecture
 
 Key files and directories:
 
 - `src/index.ts` — CLI entry point; wires commander commands and manages graceful shutdown via process locks
-- `src/commands/` — Command implementations (init, explore, spec, review, analyse, completion)
-- `src/core/` — Pure functions: spec parsing, completion generation, verbose option parsing, last-path tracking
-- `src/shell/` — I/O wrappers: file reading, device discovery, app context loading
+- `src/commands/` — Command implementations (init, update, explore, spec, review, analyse, completion)
+- `src/suite/` — Suite runner: config parsing, work-item building, worker pool, hooks
+- `src/core/` — Pure functions: completion generation, verbose/timeout option parsing, last-path tracking
+- `src/shell/` — I/O wrappers: app/explore context reading, debug logging, display factory, preflight, xqa directory discovery
 - `src/config.ts`, `src/config-schema.ts` — Configuration loading and validation with Zod
 - `src/review-session.ts` — Interactive finding review loop with dismissal tracking
 - `src/spec-frontmatter.ts` — Spec markdown frontmatter parsing (YAML)
@@ -157,6 +205,8 @@ Core error discriminated unions:
 - `XqaDirectoryError` — No .xqa directory found (XQA_NOT_INITIALIZED)
 - `SpecFrontmatterError` — Malformed spec markdown (MISSING_FRONTMATTER, MISSING_FIELD, PARSE_ERROR)
 - `LastPathError` — No findings path provided and no prior session (NO_ARG_AND_NO_STATE)
+- `SuiteConfigError` — Suite config JSON malformed or schema-invalid (INVALID_SUITE_CONFIG)
+- `HookError` — Suite hook failure (HOOK_SPAWN_FAILED, HOOK_EXIT_NONZERO, HOOK_TIMEOUT, HOOK_ABORTED)
 
 ## Development
 
@@ -231,20 +281,39 @@ src/
 
   commands/
     init-command.ts           # Project initialization
+    update-command.ts         # Skill updates
+    install-skills.ts         # Bundled skill installer
     explore-command.ts        # Breadth-first exploration
     spec-command.ts           # Spec-based exploration
+    spec-resolver.ts          # Spec file discovery and parsing
     review-command.ts         # Finding triage workflow
     analyse-command.ts        # Video analysis
     completion-command.ts     # Shell completion generation
+    item-events.ts            # Start/complete/fail event emitters
 
   core/
     parse-verbose.ts          # Verbose flag parsing
+    parse-timeout-seconds.ts  # Timeout flag parsing
     completion-generator.ts   # Bash/zsh completion script generation
     last-path.ts              # Last findings path tracking
 
   shell/
     app-context.ts            # Read app.md and explore.md
     xqa-directory.ts          # Locate .xqa directory
+    preflight.ts              # Environment preflight checks
+    ffmpeg-check.ts           # ffmpeg availability probe
+    display-factory.ts        # Solo and suite display factories
+    debug-logger.ts           # Debug event logging
+    debug-agent-events.ts     # Agent event debug formatter
+    debug-suite-events.ts     # Suite event debug formatter
+    debug-logger-core.ts      # Pure logging helpers
+    trigger-abort.ts          # Abort signal plumbing
+
+  suite/
+    types.ts                  # Suite work-item and findings types
+    core/                     # Pure: config parser, item builders, hook env, queue
+    shell/                    # I/O: worker pool, hook runner, findings writer
+    commands/                 # run-command, execute-item, suite-run-context
 
   __tests__/
     *.test.ts                 # Test files co-located with src/

package/dist/xqa.cjs

@@ -52349,25 +52349,15 @@ function createListAppsTool(udid = "booted") {
 }
 var DEFAULT_LONG_PRESS_DURATION_MS = 500;
 var MS_PER_SECOND = 1e3;
+var DEFAULT_SWIPE_DURATION_SECONDS = 0.1;
 var ENTER_KEY_CODE = "0x28";
-var TAP_SCHEMA = { x: external_exports.number(), y: external_exports.number() };
-var LONG_PRESS_SCHEMA = { x: external_exports.number(), y: external_exports.number(), duration: external_exports.number().optional() };
-var SWIPE_SCHEMA = {
-  x_start: external_exports.number(),
-  y_start: external_exports.number(),
-  x_end: external_exports.number(),
-  y_end: external_exports.number()
-};
-var TYPE_TEXT_SCHEMA = { text: external_exports.string(), submit: external_exports.boolean().optional() };
-var PRESS_BUTTON_SCHEMA = {
-  button: external_exports.enum(["HOME", "LOCK", "SIRI", "SIDE_BUTTON", "APPLE_PAY"])
-};
 function errorResult2(error48) {
   return {
     content: [{ type: "text", text: `Error: ${String(error48.cause)}` }],
     isError: true
   };
 }
+var TAP_SCHEMA = { x: external_exports.number(), y: external_exports.number() };
 function buildTapArguments(resolvedUdid, input) {
   return ["ui", "tap", "--udid", resolvedUdid, String(input.x), String(input.y)];
 }
@@ -52402,6 +52392,23 @@ async function handleDoubleTap(input) {
     ]
   };
 }
+function createTapTool(udid = "booted") {
+  return _x(
+    "tap",
+    "Tap on the screen at the given coordinates.",
+    TAP_SCHEMA,
+    async ({ x, y: y6 }) => handleTap({ udid, x, y: y6 })
+  );
+}
+function createDoubleTapTool(udid = "booted") {
+  return _x(
+    "double_tap",
+    "Double-tap on the screen at the given coordinates.",
+    TAP_SCHEMA,
+    async ({ x, y: y6 }) => handleDoubleTap({ udid, x, y: y6 })
+  );
+}
+var LONG_PRESS_SCHEMA = { x: external_exports.number(), y: external_exports.number(), duration: external_exports.number().optional() };
 function buildLongPressArguments(resolvedUdid, input) {
   return [
     "ui",
@@ -52430,8 +52437,39 @@ async function handleLongPress(input) {
     ]
   };
 }
+function createLongPressTool(udid = "booted") {
+  return _x(
+    "long_press",
+    "Long-press on the screen at the given coordinates.",
+    LONG_PRESS_SCHEMA,
+    async ({ x, y: y6, duration: duration3 }) => handleLongPress({ udid, x, y: y6, duration: duration3 ?? DEFAULT_LONG_PRESS_DURATION_MS })
+  );
+}
+var SWIPE_SCHEMA = {
+  x_start: external_exports.number(),
+  y_start: external_exports.number(),
+  x_end: external_exports.number(),
+  y_end: external_exports.number(),
+  duration: external_exports.number().positive().optional().describe(
+    "Seconds for the full gesture. Velocity = distance / duration \u2014 raise duration at fixed distance to slow the gesture and reduce momentum. Default 0.1s (flick) works for short lists; raise to 0.4\u20130.8 for controlled scrolling on long lists where the flick overshoots."
+  ),
+  delta: external_exports.number().positive().optional().describe(
+    "Pixel distance between interpolated touch points along the swipe path. Smaller values (e.g. 5) produce a denser event stream \u2014 smoother motion and more controllable stop-velocity, recommended when combining with a raised duration to tame long-list overshoot. Larger values produce coarser strokes. Omit to use idb defaults."
+  )
+};
+function toSwipeInput(udid, params) {
+  return {
+    udid,
+    xStart: params.x_start,
+    yStart: params.y_start,
+    xEnd: params.x_end,
+    yEnd: params.y_end,
+    duration: params.duration ?? DEFAULT_SWIPE_DURATION_SECONDS,
+    delta: params.delta
+  };
+}
 function buildSwipeArguments(resolvedUdid, input) {
-  return [
+  const arguments_ = [
     "ui",
     "swipe",
     "--udid",
@@ -52439,8 +52477,14 @@ function buildSwipeArguments(resolvedUdid, input) {
     String(input.xStart),
     String(input.yStart),
     String(input.xEnd),
-    String(input.yEnd)
+    String(input.yEnd),
+    "--duration",
+    String(input.duration)
   ];
+  if (input.delta !== void 0) {
+    arguments_.push("--delta", String(input.delta));
+  }
+  return arguments_;
 }
 async function handleSwipe(input) {
   const result = await resolveUdid(input.udid).andThen(
@@ -52458,6 +52502,15 @@ async function handleSwipe(input) {
     ]
   };
 }
+function createSwipeTool(udid = "booted") {
+  return _x(
+    "swipe",
+    "Swipe on the screen from one point to another. Default duration 0.1s produces a flick \u2014 use for scrolling lists, dismissing sheets, triggering paging. Use duration 0.5+ for slow drag (reorder, pan). For long lists where default flick overshoots: shorten swipe distance AND raise duration to 0.4\u20130.8 to lower velocity; optionally lower delta for denser touch events and a more controllable stop. Omitting duration uses the flick default.",
+    SWIPE_SCHEMA,
+    async (params) => handleSwipe(toSwipeInput(udid, params))
+  );
+}
+var TYPE_TEXT_SCHEMA = { text: external_exports.string(), submit: external_exports.boolean().optional() };
 async function handleTypeText({ udid, text, submit }) {
   const result = await resolveUdid(udid).andThen((resolvedUdid) => {
     const typeResult = runCommand("idb", ["ui", "text", "--udid", resolvedUdid, text]);
@@ -52473,6 +52526,17 @@ async function handleTypeText({ udid, text, submit }) {
   }
   return { content: [{ type: "text", text: `Typed: ${text}` }] };
 }
+function createTypeTextTool(udid = "booted") {
+  return _x(
+    "type_text",
+    "Type text into the currently focused element.",
+    TYPE_TEXT_SCHEMA,
+    async ({ text, submit }) => handleTypeText({ udid, text, submit: submit ?? false })
+  );
+}
+var PRESS_BUTTON_SCHEMA = {
+  button: external_exports.enum(["HOME", "LOCK", "SIRI", "SIDE_BUTTON", "APPLE_PAY"])
+};
 async function handlePressButton(udid, button) {
   const result = await resolveUdid(udid).andThen(
     (resolvedUdid) => runCommand("idb", ["ui", "button", "--udid", resolvedUdid, button])
@@ -52482,51 +52546,6 @@ async function handlePressButton(udid, button) {
   }
   return { content: [{ type: "text", text: `Pressed button: ${button}` }] };
 }
-function createTapTool(udid = "booted") {
-  return _x(
-    "tap",
-    "Tap on the screen at the given coordinates.",
-    TAP_SCHEMA,
-    async ({ x, y: y6 }) => handleTap({ udid, x, y: y6 })
-  );
-}
-function createDoubleTapTool(udid = "booted") {
-  return _x(
-    "double_tap",
-    "Double-tap on the screen at the given coordinates.",
-    TAP_SCHEMA,
-    async ({ x, y: y6 }) => handleDoubleTap({ udid, x, y: y6 })
-  );
-}
-function createLongPressTool(udid = "booted") {
-  return _x(
-    "long_press",
-    "Long-press on the screen at the given coordinates.",
-    LONG_PRESS_SCHEMA,
-    async ({ x, y: y6, duration: duration3 }) => handleLongPress({ udid, x, y: y6, duration: duration3 ?? DEFAULT_LONG_PRESS_DURATION_MS })
-  );
-}
-function createSwipeTool(udid = "booted") {
-  return _x(
-    "swipe",
-    "Swipe on the screen from one point to another.",
-    SWIPE_SCHEMA,
-    async ({
-      x_start,
-      y_start,
-      x_end,
-      y_end
-    }) => handleSwipe({ udid, xStart: x_start, yStart: y_start, xEnd: x_end, yEnd: y_end })
-  );
-}
-function createTypeTextTool(udid = "booted") {
-  return _x(
-    "type_text",
-    "Type text into the currently focused element.",
-    TYPE_TEXT_SCHEMA,
-    async ({ text, submit }) => handleTypeText({ udid, text, submit: submit ?? false })
-  );
-}
 function createPressButtonTool(udid = "booted") {
   return _x(
     "press_button",
@@ -62942,15 +62961,17 @@ At every reasoning step, maintain a mental ledger:
 Consult the ledger before every action. Always prefer navigating to a QUEUE screen over a VISITED one.`;
 var SESSION_START_RULE = `Before taking any other action \u2014 including initializing the Working State ledger or emitting findings \u2014 call \`view_ui\` once to observe the starting screen`;
 var BACK_NAV_RULE = `After navigating forward to any new screen: attempt to return to the expected parent in PATH \u2014 consult App Knowledge first for the correct exit gesture on this screen, then try in order: (1) any visible back/close button, (2) OS back gesture, (3) swipe up, (4) swipe down, (5) swipe left, (6) swipe right \u2014 confirm return via \`screenshot\` if the parent is visually unambiguous, \`view_ui\` otherwise \u2014 only after ALL attempts fail emit a \`back-nav-failure\` finding, then navigate forward again to continue`;
-var STUCK_LOOP_RULE = `Stuck loop: emit a \`stuck-loop\` finding when any of these occur: (1) \`view_ui\` returns the same \`<screen_id>\` across 3 or more consecutive \`view_ui\` calls, (2) the same element has been tapped more than twice with no screen change confirmed by \`view_ui\`, (3) PATH shows the same screen at two non-adjacent positions \u2014 before emitting, try one alternative action (scroll, long-press, swipe) to rule out a gesture mismatch \u2014 note: \`screenshot\`-only calls do not update the stuck-loop counter; only \`view_ui\` calls count`;
+var STUCK_LOOP_RULE = `Stuck loop: emit a \`stuck-loop\` finding when any of these signals occur: (1) \`view_ui\` returns the same \`<screen_id>\` across 3 or more consecutive \`view_ui\` calls, (2) the same element has been tapped more than twice with no screen change confirmed by \`view_ui\`, (3) PATH shows the same screen at two non-adjacent positions \u2014 i.e. you visited a screen, left it, and returned. Example: \`Portfolio \u2192 Asset \u2192 Swap \u2192 Asset\` (Asset revisited). Indicates circular navigation. NOT tripped by adjacent repeats like \`Portfolio \u2192 Asset \u2192 Asset\` (normal state refresh), (4) a scrollable list's element positions \u2014 x for horizontal, y for vertical \u2014 are identical across 2 or more consecutive swipe+\`view_ui\` cycles (zero-delta scroll stall) \u2014 before emitting for (1)\u2013(3), try one alternative action (scroll, long-press, swipe) to rule out a gesture mismatch \u2014 before emitting for (4), baseline element positions via \`view_ui\`, then vary one spatial parameter on the next attempt: shift swipe start coord by \u226540% of visible container dimension, OR reverse direction to probe opposite bound, OR extend throw to span \u226580% of viewport dimension \u2014 then \`view_ui\` and compare. Example: if tab bar positions \`Tokens(-31) ETH(65) ... Tron(352)\` are unchanged across 2 swipes starting near x=350, shift start to x=10 or x=395 and extend end past the opposite viewport edge. If delta still zero, emit \`stuck-loop\` with axis, before/after positions, and variation attempted \u2014 note: \`screenshot\`-only calls do not update the stuck-loop counter; only \`view_ui\` calls count. Zero-delta scroll stall is not a separate finding type \u2014 report as \`stuck-loop\`.`;
 var LOADING_STATE_RULE = `Transient loading state: when the screen shows spinners, skeleton screens, progress bars, "Loading..." text, or placeholder content NOT described in spec or app context \u2014 use \`screenshot\` to poll for resolution (up to 3 retries); switch to \`view_ui\` only on the final check or when you need element data to act \u2014 if loading persists after 3 retries, proceed with what is visible; if spec or app context explicitly describes a loading screen as a step, do not retry \u2014 call \`view_ui\` and assert normally`;
 var EXPECTED_CONTENT_MISSING_RULE = `Expected content missing: when \`view_ui\` shows no loading indicator yet omits an element named or strongly implied by spec or app context \u2014 and its absence is not semantically consistent with the current screen \u2014 call \`wait_seconds\` with 2\u20135 seconds and retry \`view_ui\` up to 2 times; if element remains absent, emit a \`missing-content\` finding stating what was expected and what was observed`;
 var CLIPPED_ELEMENT_RULE = `Never tap an element tagged \`[clipped-top]\`, \`[clipped-bottom]\`, \`[clipped-left]\`, or \`[clipped-right]\` \u2014 scroll to fully reveal it first, then re-call \`view_ui\` before tapping`;
-var SCROLL_FOLD_RULE = `Scrollable lists: elements below the visible fold are absent from the a11y tree by design \u2014 scroll to reveal before asserting presence or absence, and never emit a finding solely because list items or rows are missing from the tree on a scrollable screen`;
+var SCROLL_FOLD_RULE = `Scrollable lists: elements outside the visible viewport are absent from the a11y tree by design \u2014 this applies to elements below the fold in vertical lists AND elements clipped off-left or off-right in horizontal lists \u2014 scroll or swipe in the appropriate axis to reveal before asserting presence or absence; never emit a finding solely because list items, rows, or tabs are missing from the tree on a scrollable screen; if swipe attempts yield no position change across 2+ cycles, apply the scroll-stall path in STUCK_LOOP_RULE.`;
 var FINDING_TAXONOMY_SECTION = `## Finding Types
 
 You may emit only these trigger types: \`back-nav-failure\`, \`dead-end\`, \`stuck-modal\`, \`stuck-loop\`, \`missing-a11y-element\`, \`missing-content\`, \`spec-deviation\`, \`destructive-only-exit\`. Do NOT emit \`design-system-violation\`, \`motion-regression\`, \`continuity-regression\`, \`interaction-regression\`, or \`loading-regression\` \u2014 those belong to other agents.`;
 var A11Y_FALLBACK_RULE = `Missing a11y element: if you intend to tap or interact with a UI element and that element is absent from the most recent \`view_ui\` a11y tree \u2014 visible in the screenshot does NOT imply interactable; the a11y tree is authoritative \u2014 do NOT estimate its coordinates from the screenshot, do NOT attempt any pixel-based tap, do NOT retry at different coordinates, do NOT long-press or swipe in the element's visual region as a fallback; a failed pixel tap is never an \`interaction-regression\` \u2014 it is a \`missing-a11y-element\` \u2014 instead, emit a \`missing-a11y-element\` finding that states: (1) your intent (what you were trying to do), (2) the approximate visual region where the element appeared (coords/size from the screenshot), (3) nearby labeled elements from the a11y tree that serve as landmarks \u2014 then continue: in freestyle mode keep exploring other reachable screens; in spec mode advance to the next step`;
+var OUTCOME_LITERAL_RULE = `When verifying a step outcome or assertion, interpret all quantifiers literally and apply them exhaustively: any keyword that imposes a universal or count-bound constraint \u2014 including but not limited to \`only\`, \`all\`, \`every\`, \`each\`, \`both\`, \`no\`, \`none\`, \`neither\`, \`exactly N\`, \`at least N\`, \`fewer than N\`, \`more than N\` \u2014 a single counter-example observed in \`view_ui\` or \`screenshot\` constitutes a failed constraint; this rule applies only when the outcome text contains a universal or count-bound quantifier; positive-existence outcomes (\`X appears\`, \`Y becomes active\`, \`screen is visible\`) are not subject to counter-example scanning and are governed by SPEC_STEP_READING_SECTION; on a scrollable list, scroll through the full list before concluding pass or fail on a universal quantifier \u2014 apply SCROLL_FOLD_RULE to reveal all items, then evaluate across the complete visible set; if the screen shows any loading indicator at the time of observation, apply LOADING_STATE_RULE first and re-verify after resolution before emitting; do NOT soften (\`mostly\`, \`essentially\`, \`largely\`) and do NOT narrow the target class post-hoc to exclude the counter-example; when the counter-evidence is an element absent from the a11y tree, A11Y_FALLBACK_RULE takes precedence and determines the finding type (\`missing-a11y-element\`) \u2014 OUTCOME_LITERAL_RULE governs unwanted-presence violations only; if one item violates the constraint, emit \`spec-deviation\` immediately with: (a) the literal outcome text, (b) the specific element(s) that violate it, (c) the constraint keyword that is broken.`;
+var ANTI_RATIONALIZATION_RULE = `During outcome verification, monitor your own reasoning for reconciliation hypotheses: if you generate any reasoning that re-frames, redefines, or reinterprets the observed counter-example or target class in order to produce agreement with the spec outcome \u2014 regardless of phrasing \u2014 treat that reasoning as a deviation signal, not a resolution; stop, do NOT mark the step complete, and emit \`spec-deviation\` with: (a) the literal outcome text, (b) the specific observation that triggered the hypothesis, (c) the reconciliation reasoning itself verbatim; before marking any quantifier-bearing outcome complete, state explicitly in your reasoning: \`No reconciliation hypothesis generated. Counter-examples found: [list or none].\` If you cannot make that statement honestly, a hypothesis exists \u2014 emit \`spec-deviation\`; when outcome verification is ambiguous and no reconciliation hypothesis is generated, still default to emitting \`spec-deviation\`; silence is not a pass.`;
 var WHAT_TO_TEST_SECTION = `## What to Test
 
 Test navigation elements first, interactions second.
@@ -63043,6 +63064,8 @@ var SPEC_RULES_SECTION = `## Rules
 - ${CLIPPED_ELEMENT_RULE}
 - ${SCROLL_FOLD_RULE}
 - ${A11Y_FALLBACK_RULE}
+- ${OUTCOME_LITERAL_RULE}
+- ${ANTI_RATIONALIZATION_RULE}
 - Each item in \`**Assertions**\` is a mandatory pass/fail check \u2014 verify using \`view_ui\` when the assertion targets an element attribute, label, or presence in the tree; use \`screenshot\` when the assertion is purely visual; if neither can confirm, emit a \`spec-deviation\` finding based on what is observable
 - Flag crash dialogs, unexpected system errors, or navigation failures that occur as a direct result of executing a spec step; if you observe a visibly broken element in passing while navigating, note it without interacting with it`;
 function buildSpecModeBody({
@@ -76151,6 +76174,9 @@ var DEFAULT_FREESTYLE_TIMEOUT_SECONDS2 = 300;
 function buildDeviceInstruction(simulatorUdid) {
   return `You MUST use device "${simulatorUdid}" for ALL mobile tool calls. The simulator UDID is already configured \u2014 use it directly.`;
 }
+function composeAppContext(parts) {
+  return parts.filter((part) => part !== void 0 && part.length > 0).join("\n\n");
+}
 function ensureWorkerCwd(simulatorUdid) {
   const workerDirectory = import_node_path21.default.join(import_node_os4.default.tmpdir(), "xqa-workers", simulatorUdid);
   (0, import_node_fs11.mkdirSync)(workerDirectory, { recursive: true });
@@ -76164,7 +76190,7 @@ function resolveFreestyleTimeout(item, config3) {
 }
 function buildFreestylePipelineConfig(input) {
   const { item, context, signal, simulatorUdid, onEvent } = input;
-  const { config: config3, xqaDirectory, runId, date: date5 } = context;
+  const { config: config3, xqaDirectory, runId, date: date5, appContext } = context;
   return {
     outputDir: import_node_path21.default.join(xqaDirectory, "output", item.id),
     runId,
@@ -76177,9 +76203,11 @@ function buildFreestylePipelineConfig(input) {
       mcpServers: createDefaultMcpServers(simulatorUdid),
       allowedTools: ALLOWED_TOOLS,
       timeoutMs: resolveFreestyleTimeout(item, config3) * MS_PER_SECOND4,
-      appContext: item.prompt ? `${buildDeviceInstruction(simulatorUdid)}
-
-${item.prompt}` : buildDeviceInstruction(simulatorUdid),
+      appContext: composeAppContext([
+        buildDeviceInstruction(simulatorUdid),
+        appContext,
+        item.prompt
+      ]),
       buildEnv: config3.QA_BUILD_ENV,
       cwd: ensureWorkerCwd(simulatorUdid)
     }
@@ -76190,7 +76218,7 @@ function executeFreestyleItem(input) {
 }
 function buildSpecPipelineConfig(input) {
   const { item, context, signal, simulatorUdid, onEvent } = input;
-  const { config: config3, xqaDirectory, runId } = context;
+  const { config: config3, xqaDirectory, runId, appContext } = context;
   return {
     outputDir: import_node_path21.default.join(xqaDirectory, "output", item.id),
     runId,
@@ -76202,7 +76230,7 @@ function buildSpecPipelineConfig(input) {
       specFiles: [item.specPath],
       mcpServers: createDefaultMcpServers(simulatorUdid),
       allowedTools: ALLOWED_TOOLS,
-      appContext: buildDeviceInstruction(simulatorUdid),
+      appContext: composeAppContext([buildDeviceInstruction(simulatorUdid), appContext]),
       buildEnv: config3.QA_BUILD_ENV,
       cwd: ensureWorkerCwd(simulatorUdid)
     }
@@ -76278,17 +76306,30 @@ function deriveSuiteIdFromMode(mode) {
   }
   return deriveSuiteId({ mode: "spec", globs: mode.globs });
 }
+async function loadAppContext(xqaDirectory) {
+  const result = await readAppContext(xqaDirectory);
+  if (result.isErr()) {
+    const cause = result.error.cause instanceof Error ? result.error.cause.message : JSON.stringify(result.error.cause);
+    process.stderr.write(`Failed to read app context: ${result.error.type}
+${cause}
+`);
+    return void 0;
+  }
+  return result.value;
+}
 async function buildSuiteRunContext(input) {
   const suiteId = deriveSuiteIdFromMode(input.mode);
   const date5 = (/* @__PURE__ */ new Date()).toISOString().slice(0, ISO_DATE_LENGTH3);
   const outputDirectory = import_node_path22.default.join(input.xqaDirectory, "output");
   const existingDirectories = await listRunDirectories({ outputDirectory, suiteId, date: date5 });
   const runId = computeNextRunId(existingDirectories);
+  const appContext = await loadAppContext(input.xqaDirectory);
   const context = {
     config: input.config,
     xqaDirectory: input.xqaDirectory,
     runId,
-    date: date5
+    date: date5,
+    appContext
   };
   return { suiteId, date: date5, outputDirectory, runId, context };
 }
@@ -76482,7 +76523,7 @@ function resolveXqaDirectory() {
   return result.value;
 }
 var program2 = new Command();
-program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.14.0"}${false ? ` (dev build +${"7c0bf90"})` : ""}`);
+program2.name("xqa").description("AI-powered QA agent CLI").version(`${"1.14.2"}${false ? ` (dev build +${"5d87cb5"})` : ""}`);
 program2.command("init").description("Initialize a new xqa project in the current directory").action(() => {
   runInitCommand();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/xqa",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -26,9 +26,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.1",
     "zod": "^3.0.0",
-    "@qa-agents/explorer": "0.0.0",
-    "@qa-agents/eslint-config": "0.0.0",
     "@qa-agents/display": "0.0.0",
+    "@qa-agents/eslint-config": "0.0.0",
+    "@qa-agents/explorer": "0.0.0",
     "@qa-agents/mobile-ios": "0.0.0",
     "@qa-agents/pipeline": "0.0.0",
     "@qa-agents/shared": "0.0.0",