explorbot 0.2.2 → 0.2.4

package/src/ai/task-agent.ts

@@ -1,5 +1,6 @@
 import type { ActionResult } from '../action-result.js';
 import type { ExplorbotConfig } from '../config.ts';
+import { executionController } from '../execution-controller.ts';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import type Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
@@ -12,7 +13,8 @@ import type { Provider } from './provider.js';
 import { Quartermaster } from './quartermaster.js';
 
 export function isInteractive(): boolean {
-  return process.env.INK_RUNNING === 'true';
+  if (process.env.INK_RUNNING === 'true') return true;
+  return executionController.hasInputCallback();
 }
 
 function createNullProxy<T extends object>(): T {
@@ -73,7 +75,7 @@ export abstract class TaskAgent {
   }
 
   protected getKnowledge(actionResult: ActionResult): string {
-    return this.getKnowledgeTracker().renderRelevantKnowledge(actionResult);
+    return this.getKnowledgeTracker().renderRelevantContext(actionResult);
   }
 
   protected getExperience(actionResult: ActionResult): string {

package/src/ai/tester.ts

@@ -11,7 +11,7 @@ import { Observability } from '../observability.ts';
 import type { StateTransition } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
+import { compactAriaSnapshot, detectFocusArea } from '../utils/aria.ts';
 import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
@@ -24,7 +24,7 @@ import { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
-import { createCodeceptJSTools, createIframeTools } from './tools.ts';
+import { createCodeceptJSTools, createIframeTools, withdrawVisionTools } from './tools.ts';
 
 const debugLog = createDebug('explorbot:tester');
 
@@ -117,7 +117,7 @@ export class Tester extends TaskAgent implements Agent {
     const requestStore = this.requestStore;
     requestStore.clear();
     const offFailedRequest = requestStore.onFailedRequest((r) => {
-      task.addNote(`Network error: ${r.method} ${r.path} → ${r.status}`, TestResult.FAILED);
+      task.addObservation(`Network error: ${r.method} ${r.path} → ${r.status}`);
     });
 
     const initialState = ActionResult.fromState(state);
@@ -245,6 +245,7 @@ export class Tester extends TaskAgent implements Agent {
           if (currentState.isInsideIframe) {
             Object.assign(tools, createIframeTools(this.toolDeps));
           }
+          withdrawVisionTools(tools);
 
           debugLog(`Test ${task.scenario} iteration ${iteration}`);
 
@@ -406,6 +407,7 @@ export class Tester extends TaskAgent implements Agent {
       if (extensions >= this.MAX_EXTENSIONS) break;
 
       extensions++;
+      this.stalledIterations = 0;
       tag('info').log(`Pilot extending test (${extensions}/${this.MAX_EXTENSIONS})`);
       conversation.cleanupTag('page_aria', '...trimmed...', 1);
       conversation.cleanupTag('page_html', '...trimmed...', 0);
@@ -464,8 +466,7 @@ export class Tester extends TaskAgent implements Agent {
     this.stalledIterations++;
     if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
 
-    task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
-    task.finish(TestResult.FAILED);
+    task.addNote('No further browser progress on unchanged page; requesting final review');
     return true;
   }
 
@@ -485,7 +486,8 @@ export class Tester extends TaskAgent implements Agent {
     `;
 
     if (task.getPrintableNotes()) {
-      outcomeStatus = dedent`
+      outcomeStatus += dedent`
+
         Your current log:
         <notes>
         ${task.notesToString()}
@@ -514,7 +516,7 @@ export class Tester extends TaskAgent implements Agent {
 
     const focusArea = detectFocusArea(currentState.ariaSnapshot);
 
-    const focusedElement = extractFocusedElement(currentState.ariaSnapshot);
+    const focusedElement = currentState.focusedElement;
     if (focusedElement) {
       const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
       context += dedent`
@@ -596,7 +598,7 @@ export class Tester extends TaskAgent implements Agent {
         </page>
 
         <page_aria>
-        ${currentState.getInteractiveARIA()}
+        ${await this.interactiveAriaWithRefs(currentState)}
         </page_aria>
         ${uiMapSection}
 
@@ -633,25 +635,32 @@ export class Tester extends TaskAgent implements Agent {
       </page>
 
       <page_aria>
-      ${currentState.getInteractiveARIA()}
+      ${await this.interactiveAriaWithRefs(currentState)}
       </page_aria>
     `;
   }
 
+  private async interactiveAriaWithRefs(state: ActionResult): Promise<string> {
+    const withRefs = await Promise.resolve(this.explorer?.withPage?.((page: any) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+    if (!withRefs) return state.getInteractiveARIA();
+    return compactAriaSnapshot(withRefs, false);
+  }
+
   private finishTest(task: Test): void {
-    if (!task.hasFinished) {
-      task.finish(TestResult.FAILED);
+    if (!task.result) {
+      if (task.hasAchievedAll()) task.finish(TestResult.PASSED);
+      else task.finish(TestResult.FAILED);
     }
 
     if (task.isSuccessful) {
       tag('success').log(`Successful test: ${task.scenario}`);
-    } else if (task.isSkipped) {
+      return;
+    }
+    if (task.isSkipped) {
       tag('warning').log(`Skipped test: ${task.scenario}`);
-    } else if (task.hasFailed) {
-      tag('error').log(`Failed test: ${task.scenario}`);
-    } else {
-      tag('warning').log(`Test with no result: ${task.scenario}`);
+      return;
     }
+    tag('error').log(`Failed test: ${task.scenario}`);
   }
 
   private async abortStartedTestOnErrorPage(task: Test, actionResult: ActionResult): Promise<{ success: boolean }> {
@@ -795,6 +804,9 @@ export class Tester extends TaskAgent implements Agent {
       ${task.expected.map((e) => `- ${e}`).join('\n')}
       </expected_results>
 
+      An expected result counts as settled only when you record it back word for word as it is written above.
+      A note in your own wording is a general note and leaves that result unsettled.
+
       Your goal is to perform actions on the web page and verify the expected outcomes.
       Try to achieve as many goals as possible.
       If goal is not achievable, log that and skip to next one.
@@ -1044,6 +1056,9 @@ export class Tester extends TaskAgent implements Agent {
           - You unsuccessfully tried multiple iterations and failed
           - If the expected result was expected to fail, use status="success" instead
 
+          When a note settles one of the expected results, that note must repeat the expected result word
+          for word. Paraphrasing it leaves the expected result unsettled and it is reported as unverified.
+
           Example:
           - record({ notes: ["clicked login button", "login form appeared", "fill credentials"], status: "success" })
         `,
@@ -1128,8 +1143,7 @@ export class Tester extends TaskAgent implements Agent {
     this.stalledIterations++;
     if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
 
-    task.addNote('No browser progress after repeated execution errors', TestResult.FAILED);
-    task.finish(TestResult.FAILED);
+    task.addNote('No browser progress after repeated execution errors; requesting final review');
     return true;
   }
 

package/src/ai/tools.ts

@@ -3,8 +3,9 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
+import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
-import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from '../utils/aria.ts';
+import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -33,6 +34,10 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
       description: dedent`
         Click an element by trying multiple CodeceptJS commands in order until one succeeds.
 
+        Use this only for elements the page context gives you no ref for. When the element shows a ref such as [ref=e14],
+        call clickRef with that ref instead — composing a locator for an element that already has a ref is wasted work,
+        and a locator can match several elements where a ref cannot.
+
         Follow <locator_priority> from system prompt for locator selection.
 
         I.click(locator) - click element matching locator
@@ -51,14 +56,13 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         commands: z.array(z.string()).describe(dedent`
           FALLBACK LOCATORS for ONE element. All commands must click the SAME element.
           Never mix different elements — use separate click() calls instead.
+          REQUIRED: include at least one command WITHOUT a container — a wrong or stale container always fails.
           Order by reliability:
-          1. I.click(text, container) - PREFERRED when container is known - e.g. I.click("Save", ".modal")
+          1. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
-          IMPORTANT: Always include at least one command WITHOUT a container as fallback,
-          in case the element moved to a different section (e.g. I.click("Save") without container).
         `),
         explanation: z.string().describe('Why you are clicking this element'),
       }),
@@ -132,13 +136,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
-        let suggestion = "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
-        const lastError = attempts[attempts.length - 1]?.error || '';
-        if (lastError.includes('was not found') || lastError.includes('not found by text')) {
-          suggestion = 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
-        } else if (lastError.includes('Timeout') || lastError.includes('intercept')) {
-          suggestion = 'Element exists but could not be clicked (possibly covered by overlay or not interactable). Try closing overlapping panels first, or use visualClick().';
-        }
+        const suggestion = clickFailureSuggestion(attempts);
 
         return failedToolResult(
           'click',
@@ -153,6 +151,41 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
       },
     }),
 
+    clickRef: tool({
+      description: dedent`
+        Click an element by the ref the page context gave it, e.g. [ref=e14].
+
+        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
+        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
+        Only pass a ref that appears in the page context you were given. Never invent or guess one.
+        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
+      `,
+      inputSchema: z.object({
+        ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
+        element: z.string().describe('Role and name of the element you are clicking, for the record'),
+      }),
+      execute: async ({ ref, element }) => {
+        const activeNote = task.startNote(`Click ${element}`);
+        const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
+        const action = explorer.action();
+        const named = await describeRef(explorer, ref);
+        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+
+        if (!(await action.attempt(run, `Click ${element}`))) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
+            suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
+          });
+        }
+
+        // a ref belongs to this session only, so the run is reported as the locator a later test can replay
+        const code = named ? `I.click(${JSON.stringify(named)})` : run;
+        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, code);
+        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
+        return successToolResult('clickRef', { ...toolResult, code }, action);
+      },
+    }),
+
     hover: tool({
       description: dedent`
         Move the mouse cursor to an element to reveal hover-only controls.
@@ -299,15 +332,11 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           const focusFreeKeys = new Set(['Escape', 'Esc', 'Tab', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12']);
           const needsFocus = !focusFreeKeys.has(keyToUse) && !modifier;
 
-          if (needsFocus) {
-            const currentAriaState = stateManager.getCurrentState()?.ariaSnapshot;
-            const focused = extractFocusedElement(currentAriaState ?? null);
-            if (!focused) {
-              activeNote.commit(TestResult.FAILED);
-              return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
-                suggestion: 'Click the target element first, then press the key.',
-              });
-            }
+          if (needsFocus && !(await hasFocusedElement(explorer))) {
+            activeNote.commit(TestResult.FAILED);
+            return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
+              suggestion: 'Click the target element first, then press the key.',
+            });
           }
 
           const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
@@ -358,6 +387,8 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         Execute raw CodeceptJS code block with multiple commands.
         USE THIS TOOL for typing text into fields: I.fillField, I.type
 
+        Do not put a click on a ref-bearing element in here — clickRef with its ref is cheaper and cannot mis-target.
+
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
@@ -539,26 +570,25 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }: {
 }
 
 export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any {
-  let visionDisabled = false;
-
   const tools: Record<string, any> = {
     see: tool({
       description: dedent`
-        Check the page contents based on current page state and screenshot.
-        This tool will trigger visual research to check the page contents on request.
-        Use it to verify the actions were performed correctly and the page is in the expected state.
+        Answer a question about the page from a screenshot, for things its structure cannot express:
+        layout and position, what an image or canvas depicts, colour, and whether something is covered or cut off.
+        This runs a second model and is the slowest tool here, so reach for it only when the question is genuinely visual.
+        Do NOT use it to confirm an action landed — every action already reports what changed on the page.
         Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
-        request: "Check current state of the Login form"
-        result: "Login form is visible with username and password fields, username is filled with 'testuser' and password is empty' 
+        request: "Is the save button covered by anything, and does the chart show any plotted data?"
+        result: "The save button is partly behind a cookie banner at the bottom. The chart area is empty apart from its axes."
         </example>
       `,
       inputSchema: z.object({
         request: z.string().describe('LLM-friendly description of the page contents to look for. 1-3 sentences. No more than 100 words.'),
       }),
       execute: async ({ request }) => {
-        if (visionDisabled) {
+        if (Stats.visionDisabled) {
           return failedToolResult('see', 'Vision tools are disabled for this session. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.');
         }
 
@@ -583,8 +613,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         } catch (error) {
           throwIfFatalBrowserError(error);
           const errorMessage = errorText(error);
-          visionDisabled = true;
-          tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
+          disableVision();
           return failedToolResult('see', `See tool failed: ${errorMessage}`, {
             suggestion: 'Vision is now disabled. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.',
           });
@@ -676,6 +705,13 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             );
           }
 
+          if (result.inexpressible) {
+            return failedToolResult('verify', `No assertion could express this claim: ${assertion}`, {
+              inexpressible: true,
+              suggestion: 'This is not evidence the page is wrong — the claim could not be turned into an assertion. Restate it in terms of what is visible or of a control state, or check it with see().',
+            });
+          }
+
           return failedToolResult('verify', `Verification failed: ${assertion}`, {
             suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
           });
@@ -804,7 +840,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         context: z.string().describe('What you already tried and why it failed - helps with accurate identification'),
       }),
       execute: async ({ element, context }) => {
-        if (visionDisabled) {
+        if (Stats.visionDisabled) {
           return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
         }
 
@@ -860,8 +896,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         } catch (error) {
           throwIfFatalBrowserError(error);
           const errorMessage = errorText(error);
-          visionDisabled = true;
-          tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
+          disableVision();
           return failedToolResult('visualClick', `visualClick tool failed: ${errorMessage}`, {
             suggestion: 'Vision is now disabled. Use xpathCheck() to find the element, then click() with the discovered locator.',
           });
@@ -1011,6 +1046,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
     }),
   };
 
+  const disableVision = (): void => {
+    Stats.visionDisabled = true;
+    withdrawVisionTools(tools);
+    tag('warning').log('⚠️ Vision model is not available. Visual tools are disabled for this session.');
+  };
+
   if (withExperience !== false) {
     tools.learnExperience = createLearnExperienceTool({
       getExperienceTracker: () => stateManager.getExperienceTracker(),
@@ -1063,6 +1104,8 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
     });
   }
 
+  withdrawVisionTools(tools);
+
   return tools;
 }
 
@@ -1112,14 +1155,33 @@ function errorText(error: unknown): string {
   return 'Unknown error occurred';
 }
 
-async function commitNote(activeNote: any, result: TestResult, toolResult: any, action: any): Promise<void> {
+export async function commitNote(activeNote: any, result: TestResult, toolResult: any, action: any): Promise<void> {
   if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
     activeNote.screenshot = await action.saveScreenshot();
   }
   activeNote.commit(result);
 }
 
-function successToolResult(action: string, data?: Record<string, any>, source?: { playwrightGroupId?: string | null; assertionSteps?: any[] }) {
+async function describeRef(explorer: any, ref: string): Promise<{ role: string; text: string } | null> {
+  return Promise.resolve(
+    explorer?.withPage?.((page: any) =>
+      page.locator(`aria-ref=${ref}`).evaluate((el: any) => {
+        const tag = el.tagName.toLowerCase();
+        const roles: Record<string, string> = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+        const role = el.getAttribute('role') || roles[tag] || tag;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text) return null;
+        return { role, text };
+      })
+    )
+  ).catch(() => null);
+}
+
+async function hasFocusedElement(explorer: any): Promise<boolean> {
+  return explorer.withPage((page: any) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
+}
+
+export function successToolResult(action: string, data?: Record<string, any>, source?: { playwrightGroupId?: string | null; assertionSteps?: any[] }) {
   const result: Record<string, any> = { success: true, action, ...data };
   if (source?.playwrightGroupId) {
     result.playwrightGroupId = source.playwrightGroupId;
@@ -1155,7 +1217,7 @@ function hasObservablePageChange(data?: Record<string, any>): boolean {
   return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 
-async function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null) {
+export async function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null) {
   const result: Record<string, any> = { success: false, action, message, ...data };
   if (data?.pageDiff) {
     result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
@@ -1192,6 +1254,40 @@ function getMultipleElementsSuggestion(): string {
   `;
 }
 
+export function withdrawVisionTools(tools: Record<string, any>): void {
+  if (!Stats.visionDisabled) return;
+  Reflect.deleteProperty(tools, 'see');
+  Reflect.deleteProperty(tools, 'visualClick');
+}
+
+export function clickFailureSuggestion(attempts: Array<{ error?: string }>): string {
+  const errors = attempts.map((a) => a.error || '');
+
+  if (errors.some((e) => e.includes('not enabled'))) {
+    return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+  }
+
+  if (errors.some((e) => e.includes('intercepts pointer events'))) {
+    return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
+  }
+
+  if (errors.some((e) => e.includes('is not visible'))) {
+    return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+  }
+
+  const notFound = errors.filter((e) => e.includes('was not found'));
+
+  if (notFound.length && notFound.every((e) => e.includes('was not found inside element'))) {
+    return 'Element was not found inside that container — the container is wrong or stale, and the element may exist elsewhere on the page. Retry the same locator WITHOUT a container, or verify the container with xpathCheck().';
+  }
+
+  if (notFound.length) {
+    return 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
+  }
+
+  return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
+}
+
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 

package/src/application-spec-contract.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const APPLICATION_SPEC_FORMAT = 'explorbot-application-spec';
+export const APPLICATION_SPEC_VERSION = 1;
+
+export const APPLICATION_SPEC_PAGE_SCHEMA = z.object({
+  format: z.literal(APPLICATION_SPEC_FORMAT),
+  version: z.literal(APPLICATION_SPEC_VERSION),
+  url: z.string().trim().min(1),
+});

package/src/application-spec.ts

@@ -0,0 +1,87 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { ActionResult } from './action-result.ts';
+import { APPLICATION_SPEC_PAGE_SCHEMA } from './application-spec-contract.ts';
+import { ConfigParser } from './config.ts';
+import { tag } from './utils/logger.ts';
+import { loadMarkdownFiles } from './utils/markdown-files.ts';
+
+export class ApplicationSpec {
+  private pages: ApplicationSpecPage[] = [];
+  readonly sourcePath: string;
+
+  constructor(sourcePath: string) {
+    this.sourcePath = this.resolveSourcePath(sourcePath);
+    this.load();
+  }
+
+  renderFor(state: ActionResult): string {
+    const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+    if (relevant.length === 0) return '';
+
+    tag('operation').log(`Found application specification for ${state.url}`);
+    return dedent`
+      <application_spec>
+      This is previously collected application documentation. Treat User Can and observed state transitions as supporting context, not as a replacement for the current page state. Treat User Might as unverified possibilities that must be confirmed before use.
+
+      ${relevant.map((page) => page.content).join('\n\n')}
+      </application_spec>
+    `;
+  }
+
+  get pageCount(): number {
+    return this.pages.length;
+  }
+
+  private load(): void {
+    if (!existsSync(this.sourcePath)) {
+      throw new Error(`Application spec not found: ${this.sourcePath}`);
+    }
+
+    const isDirectory = statSync(this.sourcePath).isDirectory();
+    if (!isDirectory && path.basename(this.sourcePath).toLowerCase() !== 'index.md') {
+      throw new Error(`Application spec file must be index.md: ${this.sourcePath}`);
+    }
+
+    const bundlePath = isDirectory ? this.sourcePath : path.dirname(this.sourcePath);
+    const indexPath = path.join(bundlePath, 'index.md');
+    if (!existsSync(indexPath)) {
+      throw new Error(`Application spec index not found: ${indexPath}`);
+    }
+
+    const pagesPath = path.join(bundlePath, 'pages');
+    if (!existsSync(pagesPath)) {
+      throw new Error(`Application spec pages directory not found: ${pagesPath}`);
+    }
+
+    for (const file of loadMarkdownFiles(pagesPath, { recursive: true })) {
+      const parsed = APPLICATION_SPEC_PAGE_SCHEMA.safeParse(file.data);
+      if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'format')) {
+        throw new Error(`Invalid application spec format in ${file.filePath}`);
+      }
+      if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'version')) {
+        throw new Error(`Unsupported application spec version in ${file.filePath}: ${String(file.data.version)}`);
+      }
+      if (!parsed.success) {
+        throw new Error(`Application spec page URL is missing in ${file.filePath}`);
+      }
+      this.pages.push({ url: parsed.data.url, content: file.content.trim() });
+    }
+
+    if (this.pages.length === 0) {
+      throw new Error(`Application spec contains no documented pages: ${pagesPath}`);
+    }
+  }
+
+  private resolveSourcePath(sourcePath: string): string {
+    if (path.isAbsolute(sourcePath)) return path.resolve(sourcePath);
+    const configParser = ConfigParser.getInstance();
+    return path.resolve(configParser.resolveProjectDir(sourcePath));
+  }
+}
+
+interface ApplicationSpecPage {
+  url: string;
+  content: string;
+}