explorbot 0.5.7 → 0.5.9

package/dist/boat/prima/src/envelope.js

@@ -10,7 +10,7 @@ const EXPECTATION_LABELS = {
     contradiction: 'CONTRADICTION',
 };
 export function renderEnvelope(data) {
-    const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderExpectations(data), renderWarning(data), renderOutcome(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
+    const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderStates(data), renderExpectations(data), renderWarning(data), renderOutcome(data), renderPageIssues(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
     return sections.filter((section) => section).join('\n\n');
 }
 export function writeArtifacts(dir, snapshot) {
@@ -84,7 +84,10 @@ function renderSteps(data) {
             mark = 'ok  ';
         if (step.unconfirmed)
             mark = '??  ';
-        lines.push(`${index + 1}. ${mark} ${step.label}`);
+        let label = step.label;
+        if (step.state)
+            label += `  // state ${step.state}`;
+        lines.push(`${index + 1}. ${mark} ${label}`);
         for (const line of (step.proof || '').split('\n').filter(Boolean))
             lines.push(`      ${line}`);
     });
@@ -92,6 +95,11 @@ function renderSteps(data) {
         lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{${Object.values(STEP_FILES).join(',')}}`);
     return section('Steps', lines.join('\n'));
 }
+function renderStates(data) {
+    if (!data.states?.length)
+        return null;
+    return section('States', data.states.map((state, index) => `${index + 1}. ${state.url}\n   aria: ${state.aria}`).join('\n'));
+}
 function renderExpectations(data) {
     if (!data.expectations?.length)
         return null;
@@ -100,7 +108,7 @@ function renderExpectations(data) {
         lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
         if (expectation.resolution)
             lines.push(`      resolved: ${expectation.resolution}`);
-        if (!expectation.contradicted && !expectation.failed && !expectation.resolution)
+        if (expectation.status === 'passed' && !expectation.resolution)
             return;
         for (const line of (expectation.evidence || '').split('\n').filter(Boolean))
             lines.push(`      ${line}`);
@@ -139,6 +147,11 @@ function renderOutcome(data) {
         lines.push('', 'playwright:', ...proof);
     return section('Assertions', lines.join('\n'));
 }
+function renderPageIssues(data) {
+    if (!data.pageIssues?.length)
+        return null;
+    return section('Page issues', ['Noticed on the page while running, unrelated to the steps or the outcome:', ...data.pageIssues.map((issue) => `- ${issue}`)].join('\n'));
+}
 function renderFailure(data) {
     if (!data.failure)
         return [];

package/dist/boat/prima/src/help.js

@@ -23,15 +23,17 @@ export const checkHelp = dedent `
   --expected  one required outcome, repeatable for several. Without it the
               scenario text is the outcome. Each returns under
               ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
-              "not verified" means never checked, not false.
+              "not verified" means never checked, not false; the line under it names
+              what kept the run from checking it.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
   When screenshot and log disagree, the page structure breaks the tie: the outcome
   becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
   CONTRADICTION remains when it cannot be broken, or when the page holds something
   it does not display; judge the html, aria and screenshot under ### Artifacts yourself.
-  ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
-  reported as such rather than as an app failure.
-  Side issues found on the way go under ### Answer, not as step failures.
+  ok is false when any outcome FAILED or CONTRADICTED, when none was verified, or when
+  the run could not finish, reported as such rather than as an app failure.
+  ### Steps lists only the steps that failed.
+  Side issues found on the way go under ### Page issues, not as step failures.
 `;
 export const doHelp = dedent `
   ### Steps marks each instruction ok, FAIL or ??. ?? means it ran but the run ended
@@ -49,6 +51,14 @@ export const verifyHelp = dedent `
 export const researchHelp = dedent `
   The map is saved per page state and joins later commands there, so one research run pays for all that follow it.
 `;
+export const uxHelp = dedent `
+  Reviews one area, not the page. A named focus is shown first with at most one click,
+  which may open a dialog, tab or section or go to another page; nothing is submitted. The area reviewed is the dialog or region open on the page,
+  else the named focus, else where the session's commands on this page acted, else main.
+  Measures it at the current width, 768px and 375px, then restores the viewport.
+  Findings come under ### Answer by priority; the review reports problems and never
+  proposes wording or visual style. ok stays true whatever it finds.
+`;
 export const statusHelp = dedent `
   Reads recorded files, so it needs no browser and outlives the session.
   The hash is matched across all recorded sites. ### Artifacts lists every kept

package/dist/boat/prima/src/prima.js

@@ -18,7 +18,7 @@ import { ExplorBot } from "../../../src/explorbot.js";
 import { findSiteWith, listSites } from "../../../src/global-config.js";
 import { Reporter } from "../../../src/reporter.js";
 import { Stats } from "../../../src/stats.js";
-import { Task, Test, TestResult } from "../../../src/test-plan.js";
+import { Task, Test } from "../../../src/test-plan.js";
 import { ariaRefSelector, ariaRefSnapshot, describeRef, parseAriaRefs, refIsGone } from "../../../src/utils/aria-ref.js";
 import { compactAriaSnapshot } from "../../../src/utils/aria.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
@@ -34,6 +34,7 @@ const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
+const UX_SESSION_COMMANDS = 8;
 const AI_AGENT_NAME = 'prima';
 const CONNECT_TIMEOUT = 3000;
 const requireLib = createRequire(import.meta.url);
@@ -182,11 +183,14 @@ export class Prima {
                 if (!unreported || nudged)
                     break;
                 nudged = true;
+                let reminder = 'Do not act again on anything you have already carried out.';
+                if (!trace.length)
+                    reminder = 'Nothing has been carried out yet: text in a reply is never executed, only tool calls are. Act with tools.';
                 conversation.addUserText(dedent `
           These instructions are still unreported:
           ${unreported}
 
-          Report each one with completed() or blocked(). Do not act again on anything you have already carried out.
+          Report each one with completed() or blocked(). ${reminder}
         `);
                 continue;
             }
@@ -234,7 +238,9 @@ export class Prima {
             return envelope;
         }
         if (!trace.length && unfinished.length === ledger.length) {
-            const reason = ['No action was performed for these instructions on the current page.', narration].filter(Boolean).join(' ');
+            let reason = 'No action was performed for these instructions on the current page.';
+            if (narration)
+                reason += `\nThe model replied with text instead of calling a tool:\n${narration}`;
             return this.failureEnvelope(command, reason, previousState);
         }
         const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
@@ -353,28 +359,78 @@ export class Prima {
         const guard = await this.aiGuard(command);
         if (guard)
             return guard;
-        const previousState = await this.baselineState();
         const outcomes = expected.length ? expected : [scenario];
+        const preparation = await this.preparationSteps(scenario, outcomes);
+        let prepared = null;
+        if (preparation.length) {
+            prepared = await this.do(preparation, command);
+            if (!prepared.ok) {
+                prepared.failure = { error: `the check never ran, because preparing the page for it failed:\n${prepared.failure?.error || ''}` };
+                return prepared;
+            }
+        }
+        const previousState = await this.baselineState();
         const test = new Test(scenario, 'normal', outcomes, previousState?.url || this.options.url || '');
         const tester = this.bot.agentTester();
-        await tester.test(test, { startOnCurrentPage: true });
+        const states = [];
+        const visited = new Map();
+        const timeline = [];
+        const trackState = (state) => {
+            if (!state?.hash)
+                return;
+            let number = visited.get(state.hash);
+            if (!number) {
+                number = visited.size + 1;
+                visited.set(state.hash, number);
+                const aria = path.join(this.statusDir(), `state-${number}.aria.yml`);
+                mkdirSync(this.statusDir(), { recursive: true });
+                writeFileSync(aria, state.ariaSnapshot || '', 'utf-8');
+                states.push({ url: state.url, aria });
+            }
+            timeline.push({ time: performance.now(), state: number });
+        };
+        trackState(previousState);
+        const stopTracking = this.bot.stateManager().onStateChange((transition) => trackState(transition.toState));
+        await tester.test(test, { startOnCurrentPage: true }).finally(stopTracking);
         const notes = Object.values(test.notes || {});
         const result = await this.capturedResult(this.bot.stateManager().getCurrentState(), { screenshot: this.visionEnabled() });
         const envelope = await this.reportEnvelope(command, result, previousState, {});
-        const recorded = notes.filter((note) => !note.observation && !outcomes.includes(note.message));
-        const failed = recorded.filter((note) => note.status === TestResult.FAILED);
-        envelope.steps = failed.map((note) => ({ label: note.message, ok: false, proof: note.log || '' }));
-        const routine = recorded.length - failed.length;
-        if (routine)
-            envelope.steps.push({ label: `${routine} further ${pluralize(routine, 'step')} ran without failing — prima status ${envelope.status} for the full log`, ok: true, proof: '' });
+        const repeats = new Map();
+        for (const [startedAt, step] of Object.entries(test.steps || {})) {
+            const ok = step.status !== 'failed';
+            const state = timeline.findLast((entry) => entry.time <= Number.parseFloat(startedAt))?.state;
+            const key = `${ok} ${state} ${step.text}`;
+            let proof = '';
+            if (!ok)
+                proof = step.error || '';
+            repeats.set(key, { message: step.text, ok, count: (repeats.get(key)?.count || 0) + 1, proof, state });
+        }
+        const preparedSteps = (prepared?.steps || []).map((step) => ({ ...step, label: `prepare: ${step.label}` }));
+        envelope.steps = [
+            ...preparedSteps,
+            ...[...repeats.values()].map(({ message, ok, count, proof, state }) => {
+                let label = message;
+                if (count > 1)
+                    label += ` (×${count})`;
+                return { label, ok, proof, state };
+            }),
+        ];
+        if (prepared?.stepFiles)
+            envelope.stepFiles = prepared.stepFiles;
+        if (states.length)
+            envelope.states = states;
         envelope.expectations = await this.bot.agentPilot().settleExpectations(test, result);
         if (!result.screenshot || !this.visionEnabled()) {
             envelope.warning = 'These outcomes were settled from the run log alone — no screenshot backed them. Set ai.visionModel, or check anything visual with prima ask.';
         }
         const unreached = envelope.expectations.filter((expectation) => expectation.failed);
         const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
-        envelope.ok = !unreached.length && !contradicted.length;
+        const unverified = envelope.expectations.filter((expectation) => expectation.status === 'unverified');
+        const nothingVerified = unverified.length === envelope.expectations.length;
+        envelope.ok = !unreached.length && !contradicted.length && !nothingVerified;
         const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
+        if (nothingVerified)
+            problems.push(...unverified.map((expectation) => `not verified: ${expectation.text}`));
         if (problems.length)
             envelope.failure = { error: problems.join('\n') };
         if (!test.hasFinished || test.isSkipped) {
@@ -383,7 +439,7 @@ export class Prima {
         }
         const observations = notes.filter((note) => note.observation).map((note) => note.message);
         if (observations.length)
-            envelope.answer = ['Page problems noticed while running, not step failures:', ...observations.map((line) => `- ${line}`)].join('\n');
+            envelope.pageIssues = observations;
         return envelope;
     }
     async ask(question) {
@@ -425,6 +481,31 @@ export class Prima {
         const uiMap = await researcher.research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
         return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
     }
+    async ux(focus) {
+        const command = ['ux', focus].filter(Boolean).join(' ');
+        const guard = await this.aiGuard(command);
+        if (guard)
+            return guard;
+        const previousState = await this.baselineState();
+        let clicked = [];
+        if (focus) {
+            const shown = await this.showFocus(focus, previousState);
+            if (!shown)
+                return this.failureEnvelope(command, `Could not show "${focus}": it is not on this page and no single click from here leads to it, so no review was made.`, previousState);
+            clicked = shown;
+        }
+        const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
+        let auditFocus = focus;
+        if (result.overlay.isOpen && result.overlay.describe() !== previousState?.overlay?.describe())
+            auditFocus = undefined;
+        const answer = await this.bot.agentQuartermaster().auditUx(result, { focus: auditFocus, commands: this.sessionCommandsOn(result.url) });
+        const envelope = await this.reportEnvelope(command, result, previousState, { answer });
+        if (clicked.length)
+            envelope.steps = clicked.map((code) => ({ label: code, ok: true, proof: '' }));
+        if (!this.visionEnabled())
+            envelope.warning = 'No screenshot backed this review, so visual checks were skipped. Set ai.visionModel to include them.';
+        return envelope;
+    }
     async go(target) {
         const command = `go ${target}`;
         const code = `I.amOnPage('${target}')`;
@@ -443,7 +524,7 @@ export class Prima {
         let navigationError = null;
         let arrived = true;
         try {
-            arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
+            arrived = await this.bot.agentNavigator().visit(target, { recover: !this.aiUnavailable() });
         }
         catch (error) {
             navigationError = error;
@@ -455,8 +536,11 @@ export class Prima {
             used.push(code);
         const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
         const envelope = await this.successEnvelope(command, used, result, previousState);
-        if (!arrived)
-            envelope.page.redirectedFrom = target;
+        if (arrived)
+            return envelope;
+        envelope.page.redirectedFrom = target;
+        envelope.ok = false;
+        envelope.failure = { error: `${target} was not reached: the page redirected to ${result.url} and no AI model is available to recover (log in, follow knowledge)` };
         return envelope;
     }
     async browserCheck() {
@@ -473,7 +557,7 @@ export class Prima {
             this.sessionUrl = site.url;
         const config = await this.loadConfig();
         const parser = ConfigParser.getInstance();
-        return ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json });
+        return ConfigCommand.render(config, { configPath: parser.getConfigPath(), siteConfigPath: parser.getSiteConfigPath(), root: parser.getProjectRoot(), json });
     }
     record(envelope, durationMs) {
         if (!this.session)
@@ -817,6 +901,40 @@ export class Prima {
             },
         });
     }
+    async preparationSteps(scenario, outcomes) {
+        const result = await this.capturedResult(await this.baselineState());
+        const page = compactAriaSnapshot(result.ariaSnapshot, true).slice(0, JUDGE_PAGE_CAP);
+        const judge = this.bot.judge?.();
+        if (judge) {
+            const question = 'Before this scenario can start, the current page needs actions the scenario does not perform itself: reaching the page where it starts, or setting up a precondition it relies on.';
+            const needed = await judge.decide(question, null, { scenario, outcomes, url: result.url, page });
+            if (needed.rejected)
+                return [];
+        }
+        const prompt = dedent `
+      <scenario>
+      ${scenario}
+      </scenario>
+
+      <expected_outcomes>
+      ${outcomes.map((outcome) => `- ${outcome}`).join('\n')}
+      </expected_outcomes>
+
+      <page>
+      url: ${result.url}
+      ${page}
+      </page>
+
+      A check of this scenario runs next, starting from the current page. Decide whether the page must be prepared first.
+      Preparation is only what the scenario assumes but does not do: reaching the page where it starts when this is a different one,
+      or setting up a precondition it relies on. Never include the actions the scenario describes — the check performs and judges those.
+      List the preparation as short imperative instructions, in order. Return an empty list when the scenario can start here.
+    `;
+        const schema = z.object({ steps: z.array(z.string()).describe('preparation instructions, in order; empty when none are needed') });
+        const provider = this.bot.getProvider();
+        const response = await provider.generateObject([{ role: 'user', content: prompt }], schema, provider.getAgenticModel?.(AI_AGENT_NAME), { agentName: AI_AGENT_NAME }).catch(() => null);
+        return response?.object?.steps || [];
+    }
     async pageContext(result) {
         const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
         const map = getPreviousResearch(result.baseHash);
@@ -867,13 +985,8 @@ export class Prima {
         const pick = await judge.decide(`Which listed control leads to: ${target}`, [...labels, UNDECIDED], { target });
         if (!pick.value)
             return null;
-        const ref = refs[labels.indexOf(pick.value)].ref;
-        const explorer = this.bot.getExplorer();
-        if (await refIsGone(explorer, ref))
-            return null;
-        const named = await describeRef(explorer, ref);
-        const run = `I.usePlaywrightTo(${JSON.stringify(`go to ${target}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
-        if (!(await explorer.action().attempt(run, `go ${target}`)))
+        const code = await this.clickRef(refs[labels.indexOf(pick.value)].ref, `go to ${target}`);
+        if (!code)
             return null;
         const newState = this.bot.stateManager().getCurrentState();
         if (!newState)
@@ -884,11 +997,62 @@ export class Prima {
         const arrived = await judge.decide(`The page now shows: ${target}`, null, { target, page });
         if (arrived.rejected)
             return null;
-        let code = run;
-        if (named)
-            code = `I.click(${JSON.stringify(named)})`;
         return this.successEnvelope(`go ${target}`, [code], await this.capturedResult(newState), previousState);
     }
+    async showFocus(focus, state) {
+        if (!state)
+            return null;
+        const snapshot = (await this.refAriaSnapshot(ActionResult.fromState(state))) || '';
+        const refs = parseAriaRefs(snapshot).filter((entry) => entry.name);
+        const schema = z.object({
+            shown: z.boolean().describe('whether the page already shows the area'),
+            ref: z.enum(['none', ...refs.map((entry) => entry.ref)]).describe('when it is not shown, the one control whose click leads to it, or none'),
+        });
+        const prompt = dedent `
+      A UX review needs this area on screen: ${focus}
+      Say whether the page already shows it. If not, pick the one control whose single click opens, reveals or navigates to it.
+      Its label may differ from how the area was named: judge by what the control leads to.
+      Answer none when no control plausibly leads there.
+
+      <page_aria>
+      ${snapshot.slice(0, JUDGE_PAGE_CAP)}
+      </page_aria>
+    `;
+        const response = await this.bot
+            .getProvider()
+            .generateObject([{ role: 'user', content: prompt }], schema, undefined, { agentName: AI_AGENT_NAME })
+            .catch(() => null);
+        if (response?.object?.shown)
+            return [];
+        const ref = response?.object?.ref;
+        if (!ref || ref === 'none')
+            return null;
+        const code = await this.clickRef(ref, `show ${focus}`);
+        if (!code)
+            return null;
+        return [code];
+    }
+    async clickRef(ref, purpose) {
+        const explorer = this.bot.getExplorer();
+        if (await refIsGone(explorer, ref))
+            return null;
+        const named = await describeRef(explorer, ref);
+        const run = `I.usePlaywrightTo(${JSON.stringify(purpose)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
+        if (!(await explorer.action().attempt(run, purpose)))
+            return null;
+        if (named)
+            return `I.click(${JSON.stringify(named)})`;
+        return run;
+    }
+    sessionCommandsOn(url) {
+        if (!this.session)
+            return [];
+        const { tests } = readSession(sessionFile(this.session.key));
+        return tests
+            .filter((test) => test.description?.split('\n')[0] === `page: ${url}` && !test.title.startsWith('ux'))
+            .map((test) => test.title)
+            .slice(-UX_SESSION_COMMANDS);
+    }
     executedCodes(code) {
         if (typeof code !== 'string')
             return [];

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/rules/navigator/verification-actions.md

@@ -55,9 +55,11 @@ Checks that page title contains expected text.
 I.seeInSource(<text>)
 
 Checks that page source contains expected text (including hidden elements).
+Pass plain text only — never markup, tags, attributes or class names. The HTML you are shown is rewritten
+and will not match the live source character for character. Use it only for text that no visible element carries.
 
 <example>
-  I.seeInSource('<div class="hidden">');
+  I.seeInSource('Draft saved');
 </example>
 
 ### I.dontSee
@@ -99,10 +101,10 @@ Checks that an input field does NOT contain the specified value.
 
 I.dontSeeInSource(<text>)
 
-Checks that page source does NOT contain expected text.
+Checks that page source does NOT contain expected text. Plain text only, same as I.seeInSource.
 
 <example>
-  I.dontSeeInSource('error-class');
+  I.dontSeeInSource('Session expired');
 </example>
 
 ### Asserting the state of a control

package/dist/rules/planner/ignored-pages.md

@@ -0,0 +1,6 @@
+<ignored_pages>
+Do not plan tests for these pages, return an empty scenarios list:
+- sign in
+- sign up
+- password recovery
+</ignored_pages>

package/dist/rules/quartermaster/ux/accessibility.md

@@ -0,0 +1,8 @@
+<accessibility priority="CRITICAL">
+- Every control has an accessible name; icon-only controls included. Confirm against the ARIA tree, not the picture.
+- Interactive elements are reachable by keyboard in visual order, with a visible focus indicator.
+- Headings form a sequential outline without skipped levels.
+- Meaning never rests on color alone: state, error and status also carry text or an icon.
+- Dialogs and multi-step flows offer a visible way out.
+- Contrast is reported only from axe results, never judged by eye.
+</accessibility>

package/dist/rules/quartermaster/ux/charts.md

@@ -0,0 +1,6 @@
+<charts priority="LOW">
+Apply only when a chart or data visualisation is inside the focus area:
+- Series are identified by a legend or direct labels, not by color alone.
+- Exact values are reachable without hover.
+- An empty or failed dataset shows a message, not a blank frame.
+</charts>

package/dist/rules/quartermaster/ux/copy.md

@@ -0,0 +1,9 @@
+<copy priority="HIGH">
+Judge what a text does for the user, not how it is phrased:
+- Intent: a label or heading must tell what happens or what the area is for; a text that names no outcome fails.
+- Duplication: two texts in the focus area that say the same thing, or a text that repeats the visible label beside it.
+- Relevance: a text that explains nothing the interface does not already show, or concerns something outside the user's task here.
+- Filler: generic, promotional or self-congratulatory text that could sit unchanged on any product.
+- Overload: more text than the task needs, competing with the controls for attention.
+Quote the text and state which check it fails. Never propose replacement wording.
+</copy>

package/dist/rules/quartermaster/ux/forms.md

@@ -0,0 +1,7 @@
+<forms priority="MEDIUM">
+- Each input has a visible label that stays when the user types; a placeholder alone is not a label.
+- Errors appear next to the input they concern and state cause and recovery.
+- Required inputs are marked before submission, not discovered after it.
+- Long or complex forms reveal options progressively instead of all at once.
+- A completed submit confirms its result.
+</forms>

package/dist/rules/quartermaster/ux/interaction.md

@@ -0,0 +1,7 @@
+<interaction priority="CRITICAL">
+- Targets meet the size and spacing limits in measurements: touch limits at touch widths, pointer limits above.
+- Every action is reachable by click or tap; hover may reveal, never be the only way in.
+- An action that waits on the server shows it is working and blocks a second submit.
+- Destructive or irreversible actions ask for confirmation or offer undo.
+- Disabled controls look disabled and say, or make evident, why.
+</interaction>

package/dist/rules/quartermaster/ux/motion.md

@@ -0,0 +1,5 @@
+<motion priority="MEDIUM">
+Judge only what measurements report:
+- Transitions on layout properties, which make content jump while they run.
+- Animations that keep running when the user asks for reduced motion.
+</motion>

package/dist/rules/quartermaster/ux/navigation.md

@@ -0,0 +1,7 @@
+<navigation priority="HIGH">
+- The current location is marked in the navigation that leads to it.
+- Back behaves predictably; a state worth sharing or returning to has its own URL.
+- Navigation offers few top-level choices; grouping beats a long flat list.
+- Destructive or session-ending items are set apart from ordinary destinations.
+- Modals do not carry primary navigation flows.
+</navigation>

package/dist/rules/quartermaster/ux/readability.md

@@ -0,0 +1,6 @@
+<readability priority="MEDIUM">
+Judge only what measurements report:
+- Body text below the minimum size.
+- Multi-line text with cramped line-height.
+- Truncated text that hides meaning and offers no way to read it in full.
+</readability>

package/dist/rules/quartermaster/ux/responsive.md

@@ -0,0 +1,7 @@
+<responsive priority="HIGH">
+- Compare breakpoints: the focus area must stay usable at every width it was measured at.
+- No horizontal scroll; content fits the viewport width. Zoom must never be disabled.
+- When navigation does not fit, it collapses behind one named, reachable control; nothing primary disappears without a way back to it.
+- On narrow screens core content comes first; secondary panels fold, they do not push the task below the fold.
+- Fixed or sticky bars never cover the content or controls beneath them.
+</responsive>

package/dist/src/ai/judge.d.ts

@@ -5,7 +5,8 @@ export declare const JUDGE_PAGE_CAP = 12000;
 export declare class Decision {
     readonly value: string | null;
     readonly confidence: number;
-    constructor(value: string | null, confidence: number);
+    readonly answered: boolean;
+    constructor(value: string | null, confidence: number, answered?: boolean);
     get approved(): boolean;
     get rejected(): boolean;
 }
@@ -23,6 +24,7 @@ export declare class Judge {
     static fromConfig(config: AIConfig['decisionModel']): Judge | null;
     get toolEnabled(): boolean;
     decide(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
+    assert(statement: string, state: unknown): Promise<boolean | null>;
     pick(question: string, options: string[], state: unknown): Promise<number | null>;
     consult(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
     request(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;

package/dist/src/ai/judge.js

@@ -10,9 +10,11 @@ export const JUDGE_PAGE_CAP = 12000;
 export class Decision {
     value;
     confidence;
-    constructor(value, confidence) {
+    answered;
+    constructor(value, confidence, answered = true) {
         this.value = value;
         this.confidence = confidence;
+        this.answered = answered;
     }
     get approved() {
         return this.value !== null;
@@ -43,9 +45,17 @@ export class Judge {
     }
     async decide(question, options, state) {
         if (!this.enabled.direct)
-            return new Decision(null, 0);
+            return new Decision(null, 0, false);
         return this.consult(question, options, state);
     }
+    async assert(statement, state) {
+        const decision = await this.decide(statement, null, state);
+        if (decision.approved)
+            return true;
+        if (decision.answered && decision.confidence < 1 - this.threshold)
+            return false;
+        return null;
+    }
     async pick(question, options, state) {
         if (new Set(options).size < options.length)
             return null;
@@ -75,7 +85,7 @@ export class Judge {
             instructions = `${question} ${UNDECIDED_HINT}`;
         const answer = await this.provider.decide(state, instructions, list).catch((error) => this.recordFailure(error));
         if (!answer)
-            return new Decision(null, 0);
+            return new Decision(null, 0, false);
         Observability.getSpan()?.setAttribute('langfuse.observation.output', JSON.stringify(answer));
         if (answer.probability <= this.threshold)
             return new Decision(null, answer.probability);

package/dist/src/ai/navigator.js

@@ -763,8 +763,9 @@ class Navigator {
             page?.setDefaultTimeout(originalTimeout);
         }
         const totalAttempted = Math.min(codeBlocks.length, this.verifyAttempts);
-        const majorityNeeded = Math.floor(totalAttempted / 2) + 1;
-        let verified = successfulCodes.length >= majorityNeeded;
+        let verified = successfulCodes.length > 0 && !failures;
+        if (successfulCodes.length && failures)
+            verified = await this.provider.oracle(message, { assertions: results.map(({ code, passed, error }) => ({ code, passed, error })) }, { agentName: 'navigator', telemetry: { functionId: 'navigator.verifyState' } });
         if (alreadyVerified)
             verified = true;
         const inexpressible = !alreadyVerified && totalAttempted === 0;

package/dist/src/ai/pilot.js

@@ -553,8 +553,10 @@ export class Pilot {
         const schema = z.object({
             outcomes: z.array(z.object({
                 expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
-                status: z.enum(['passed', 'failed', 'unverified', 'contradiction']).describe('passed = the evidence shows it happened to the thing it names, failed = the evidence shows it did not, unverified = the run never established either way, contradiction = the picture and the run disagree'),
-                evidence: z.string().nullable().describe('What settled it. For a contradiction, what each side shows. Null when there is nothing to add'),
+                status: z
+                    .enum(['passed', 'failed', 'unverified', 'contradiction'])
+                    .describe('passed = the evidence shows it happened to the thing it names, failed = the evidence shows the application did not do it, unverified = the run never established either way, contradiction = the picture and the run disagree'),
+                evidence: z.string().nullable().describe('What settled it. For unverified, what stopped the run from checking it. For a contradiction, what each side shows. Null when there is nothing to add'),
             })),
         });
         let pageEvidence = '';
@@ -593,10 +595,14 @@ export class Pilot {
       The log is written in the tester's own words, so an outcome can be satisfied by a step that describes it
       differently. Judge by what the steps show happened, not by whether the wording matches.
       Wording may differ, the subject may not. An outcome refers to what the scenario names or chooses; it holds
-      only when that same thing appears. A different route or a different thing reaching a similar state is "failed",
-      and so is an outcome about something the run never managed to choose or create.
+      only when that same thing appears. A different route or a different thing reaching a similar state is "failed".
+      An outcome about something the run never managed to choose or create never passes: it is "failed" when the
+      application refused it, "unverified" when the run's own trouble got in the way.
       Choose "unverified" only when the evidence neither shows the outcome happening nor shows it failing —
       that is a statement about the run, not about the application.
+      "failed" is a statement about the application. When the run's own trouble — an earlier step it could not
+      get past, a control it could not reach or operate — left the outcome untested, it is "unverified", and
+      the evidence names that blocker.
     `;
         const settle = (content, model) => this.provider
             .generateObject([{ role: 'user', content }], schema, model, {