explorbot 0.5.10 → 0.6.0

package/src/ai/captain/web-mode.ts

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import { pageEvidence } from '../judge.ts';
 import { actionRule, locatorRule, sectionContextRule } from '../rules.ts';
 import { createAgentTools, createCodeceptJSTools } from '../tools.ts';
 import { type Constructor, type ModeContext, debugLog } from './mixin.ts';
@@ -37,6 +38,16 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           },
         }),
 
+        oracle: tool({
+          description: 'Ask a yes/no question about the current page. Much cheaper than see or context.',
+          inputSchema: z.object({ question: z.string() }),
+          execute: async ({ question }) => {
+            const captured = await ctx.explorBot.getExplorer().capture({ screenshot: true });
+            const holds = await ctx.explorBot.getProvider().oracle(question, pageEvidence(captured), { agentName: 'captain', screenshot: captured.screenshot, telemetry: { functionId: 'captain.oracle' } });
+            return { success: holds !== null, question, answer: holds };
+          },
+        }),
+
         browser: tool({
           description: dedent`
             Direct browser access via Playwright. Use for diagnostics and browser management.
@@ -157,6 +168,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         - click() accepts array of commands to try in order — include ARIA, CSS, XPath variants
         - If click() fails with all provided commands, use visualClick() tool as fallback
         - When an action fails or result is unexpected, investigate or inform the user instead of retrying silently
+        - For a quick yes/no question about the page, use oracle instead of see or context
       `;
     }
   };

package/src/ai/captain.ts

@@ -7,6 +7,7 @@ import type { ExplorBot } from '../explorbot.ts';
 import type { WebPageState } from '../state-manager.ts';
 import { Task, Test } from '../test-plan.ts';
 import { formatHeadings } from '../utils/context-formatter.ts';
+import { BlockedError } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { startLogCapture, stopLogCapture, tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
@@ -21,6 +22,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { TaskAgent } from './task-agent.ts';
+import type { SupervisorAction } from './tester.ts';
 import { createLearnExperienceTool, withdrawVisionTools } from './tools.ts';
 
 const MAX_STEPS = 15;
@@ -35,6 +37,9 @@ export class Captain extends CaptainBase implements Agent {
   private hooksRunner: HooksRunner | null = null;
   private commandExecutor: ((cmd: string) => Promise<void>) | null = null;
   private commandDescriptions: { name: string; description: string; options: string }[] = [];
+  private unresolvedBlockers = new Set<string>();
+  private handling = false;
+  private blocker: BlockedError | null = null;
 
   constructor(explorBot: ExplorBot) {
     super();
@@ -123,6 +128,7 @@ export class Captain extends CaptainBase implements Agent {
     - After a successful action, if the pageDiff confirms the goal, call done() immediately — do not verify with see() or context() unless the user explicitly asked for verification
     - Prefer completing in fewer tool calls over thoroughness
     - NEVER run tests unless the user explicitly asks
+    - When an agent reports it is blocked, decide which agent can resolve it and delegate to that agent
     - If you are answering with information rather than completing a browser action, include the actual user-facing answer in done({ details }). Do not only say that it was shown or explained.
     ${mode === 'web' || mode === 'heal' ? this.webModeRules() : ''}
     ${mode === 'test' || mode === 'heal' ? this.testModeRules() : ''}
@@ -304,7 +310,7 @@ export class Captain extends CaptainBase implements Agent {
 
   private async tools(task: Task, onDone: (summary: string) => void) {
     const mode = this.getMode();
-    const ctx: ModeContext = { explorBot: this.explorBot, task };
+    const ctx: ModeContext = { explorBot: this.explorBot, task, blocker: this.blocker };
     const core = this.coreTools(task, onDone);
     const idle = await this.idleModeTools(ctx);
 
@@ -437,6 +443,7 @@ export class Captain extends CaptainBase implements Agent {
 
     conversation.addUserText(initialPrompt);
 
+    this.handling = true;
     await loop(
       async ({ stop, iteration, userInput }) => {
         debugLog(`Captain iteration ${iteration}`);
@@ -510,7 +517,9 @@ export class Captain extends CaptainBase implements Agent {
           stop();
         },
       }
-    );
+    ).finally(() => {
+      this.handling = false;
+    });
 
     const finalUrl = stateManager.getCurrentState()?.url || startUrl;
     await this.getHooksRunner().runAfterHook('captain', finalUrl);
@@ -523,15 +532,24 @@ export class Captain extends CaptainBase implements Agent {
 
     return null;
   }
+
+  async resolveBlocker(error: unknown, resolved: () => boolean | Promise<boolean>): Promise<boolean> {
+    if (!(error instanceof BlockedError) || this.handling) return false;
+    const key = `${error.name} ${error.url} ${error.blocker}`;
+    if (this.unresolvedBlockers.has(key)) return false;
+    tag('info').log(`Captain takes over: ${error.message}`);
+    this.blocker = error;
+    await this.handle(error.request, { reset: true }).finally(() => {
+      this.blocker = null;
+    });
+    if (await resolved()) return true;
+    this.unresolvedBlockers.add(key);
+    return false;
+  }
 }
 
 export default Captain;
 
-interface SupervisorAction {
-  action: 'inject' | 'stop' | 'pass' | 'skip';
-  message: string;
-}
-
 interface ExecutionRecoveryAction {
   action: 'continue' | 'stop';
   message: string;

package/src/ai/driller.ts

@@ -15,7 +15,6 @@ import { eidxInContainer } from '../utils/web-eidx.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import type { Navigator } from './navigator.ts';
-import type { Provider } from './provider.ts';
 import { drillLocatorRule } from './rules.ts';
 import { TaskAgent, isInteractive } from './task-agent.ts';
 import { createCodeceptJSTools, createLearnExperienceTool } from './tools.ts';
@@ -177,7 +176,7 @@ export class Driller extends TaskAgent implements Agent {
     setActivity(`${this.emoji} Capturing annotated page state...`, 'action');
     const action = this.explorer.action();
     try {
-      const annotated = await Promise.race([
+      await Promise.race([
         this.explorer.withPage(annotatePageElements),
         new Promise<never>((_, reject) => {
           setTimeout(() => reject(new Error('annotateElements timeout')), 15000);

package/src/ai/experience-compactor.ts

@@ -1,5 +1,5 @@
 import { unlinkSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, relative } from 'node:path';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { type ExperienceFile, type ExperienceTracker, RECENT_WINDOW_DAYS } from '../experience-tracker.js';
@@ -322,7 +322,7 @@ export class ExperienceCompactor implements Agent {
     };
 
     this.experienceTracker.writeExperienceFile(targetStateHash, combinedContent, newFrontmatter);
-    log(`Merged ${group.files.length} experience files into ${targetFile.filePath}`);
+    log(`Merged ${group.files.length} experience files into ${relative(process.cwd(), targetFile.filePath)}`);
     debugLog('New URL pattern:', group.pattern);
 
     for (const sourceFile of sourceFiles) {

package/src/ai/judge.ts

@@ -1,7 +1,8 @@
 import { clearActivity, setActivity } from '../activity.ts';
+import type { ActionResult } from '../action-result.ts';
 import type { AIConfig } from '../config.ts';
 import { Observability } from '../observability.ts';
-import { createDebug } from '../utils/logger.ts';
+import { createDebug, tag } from '../utils/logger.ts';
 import { JudgeProvider } from './judge-provider.ts';
 
 const debugLog = createDebug('explorbot:judge');
@@ -29,6 +30,8 @@ export class Decision {
 }
 
 export class Judge {
+  private failureReported = false;
+
   constructor(
     private provider: JudgeProvider,
     private enabled: { tool: boolean; direct: boolean },
@@ -93,6 +96,8 @@ export class Judge {
 
   private recordFailure(error: unknown): null {
     debugLog('judge declined: %s', error);
+    if (!this.failureReported) tag('warning').log(`Decision model ${this.provider.model} failed (${error}); continuing without it`);
+    this.failureReported = true;
     const span = Observability.getSpan();
     span?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
     span?.setAttribute('langfuse.observation.level', 'ERROR');
@@ -100,3 +105,7 @@ export class Judge {
     return null;
   }
 }
+
+export function pageEvidence(actionResult: ActionResult) {
+  return { url: actionResult.url, title: actionResult.title, page: actionResult.getCompactARIA().slice(0, JUDGE_PAGE_CAP) };
+}

package/src/ai/navigator.ts

@@ -13,7 +13,7 @@ import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
-import { isLoginPage } from '../utils/error-page.ts';
+import { NavigationBlockedError, isLoginPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -22,7 +22,6 @@ import { normalizeInlineText } from '../utils/strings.ts';
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import type { UrlFilter } from '../utils/url-filter.ts';
 import type { Agent, AgentDeps } from './agent.js';
-import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
@@ -31,6 +30,7 @@ import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from './tools.ts';
 
 const debugLog = createDebug('explorbot:navigator');
+const MAX_TRIED_STEPS = 5;
 
 class Navigator implements Agent {
   emoji = '🧭';
@@ -138,6 +138,10 @@ class Navigator implements Agent {
     return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
+  isOn(url: string): boolean {
+    return this.isOnExpectedPage(url, this.stateManager);
+  }
+
   async visit(url: string, opts: { recover?: boolean } = {}): Promise<boolean> {
     return this.visitOnce(url, opts.recover !== false);
   }
@@ -195,8 +199,9 @@ class Navigator implements Agent {
   }
 
   private navigationError(url: string, fallback: string): Error {
-    if (this.lastFailureReason) return new Error(`Navigation to ${url} failed: ${this.lastFailureReason}`);
-    return new Error(`Navigation to ${url} failed: ${fallback}`);
+    const currentUrl = this.stateManager.getCurrentState()?.url || '';
+    const tried = this.executedSteps.slice(-MAX_TRIED_STEPS).map((step) => step.command);
+    return new NavigationBlockedError(url, currentUrl, this.lastFailureReason || fallback, tried);
   }
 
   private failureReason(stopReason: string | null, knowledge: string, url: string): string | null {
@@ -402,7 +407,7 @@ class Navigator implements Agent {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
-        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it; propose CSS/XPath only once <page_html> is provided.
         Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
@@ -772,7 +777,7 @@ class Navigator implements Agent {
         Do not generate assertions that would pass even if the specific claim is false.
       </task>
 
-      ${RulesLoader.loadRules('navigator', ['verification-actions'], actionResult.url || '')}
+      ${RulesLoader.loadRules('navigator', ['verification-actions', 'verification-output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.verifyAttempts))}
 
       ${experience}
 
@@ -858,7 +863,7 @@ class Navigator implements Agent {
 
     const totalAttempted = Math.min(codeBlocks.length, this.verifyAttempts);
     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 (successfulCodes.length && failures) verified = (await this.provider.oracle(message, { assertions: results.map(({ code, passed, error }) => ({ code, passed, error })) }, { agentName: 'navigator', telemetry: { functionId: 'navigator.verifyState' } })) === true;
     if (alreadyVerified) verified = true;
 
     const inexpressible = !alreadyVerified && totalAttempted === 0;

package/src/ai/planner/subpages.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
-import { tag } from '../../utils/logger.ts';
 import { isSamePageFamily } from '../../utils/url-matcher.ts';
 import type { Provider } from '../provider.ts';
 import type { Constructor } from '../researcher/mixin.ts';
@@ -85,7 +84,7 @@ export function WithSubPages<T extends Constructor>(Base: T) {
     async pickNextSubPage(candidates: SubPageCandidate[]): Promise<{ url: string; reason: string } | null> {
       if (candidates.length === 0) return null;
 
-      const plannedEntries = [...planRegistry.entries()].map(([key, record]) => `- ${record.url} (${record.plan.tests.length} tests${record.feature ? `, feature: ${record.feature}` : ''})`).join('\n');
+      const plannedEntries = [...planRegistry.entries()].map(([, record]) => `- ${record.url} (${record.plan.tests.length} tests${record.feature ? `, feature: ${record.feature}` : ''})`).join('\n');
 
       const candidateList = candidates.map((c) => `- ${c.url} (visits: ${c.visitCount}${c.title ? `, title: "${c.title}"` : ''}${c.h1 ? `, h1: "${c.h1}"` : ''})`).join('\n');
 

package/src/ai/planner.ts

@@ -1,19 +1,19 @@
 import dedent from 'dedent';
-import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { setActivity } from '../activity.ts';
 import { ConfigParser } from '../config.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
-import type Explorer from '../explorer.ts';
 import { Observability } from '../observability.ts';
 import type { StateManager } from '../state-manager.js';
 import { Stats } from '../stats.ts';
 import { Suite } from '../suite.ts';
 import { Plan, Test } from '../test-plan.ts';
+import { PlanningBlockedError } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.js';
+import { loop } from '../utils/loop.ts';
 import { jsonToTable } from '../utils/markdown-parser.ts';
 import { mdq } from '../utils/markdown-query.js';
-import { planToCompactAiContext } from '../utils/test-plan-markdown.ts';
+import { findPlanMarkdownProblems, parsePlansFromMarkdownText, planToCompactAiContext, readPlanMarkdownComment } from '../utils/test-plan-markdown.ts';
 import type { Agent, AgentDeps } from './agent.js';
 import { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
@@ -26,33 +26,16 @@ import { findSimilarStateHash } from './researcher/cache.ts';
 import { hasFocusedSection } from './researcher/focus.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { capabilityGroundingRule, dataProtectionRules, fileUploadRule } from './rules.ts';
-import type { Scout } from './scout.ts';
+import { ScoutQuery, type Scout } from './scout.ts';
 
 const debugLog = createDebug('explorbot:planner');
 
-const TasksSchema = z.object({
-  planName: z.string().describe('Short descriptive name for the test plan (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")'),
-  scenarios: z
-    .array(
-      z.object({
-        scenario: z.string().describe('A single sentence describing the behavior to test.'),
-        priority: z.enum(['critical', 'important', 'high', 'normal', 'low']).describe('Priority of the task based on business importance'),
-        startUrl: z.string().nullable().describe('Start URL for the test if different from plan URL. Use only stable feature/list/detail pages, not transient create/edit/modal URLs unless the scenario specifically starts inside that form.'),
-        steps: z.array(z.string()).describe('List of steps to perform for this scenario. Each step should be a specific action (e.g., "Open the form", "Enter required data", "Submit the form"). Keep steps atomic and actionable.'),
-        expectedOutcomes: z
-          .array(z.string())
-          .describe('List of expected outcomes that can be verified. Each outcome should be simple, specific, and easy to check (e.g., "Success message appears", "URL changes to /dashboard", "Form field shows error"). Keep outcomes atomic - do not combine multiple checks into one.'),
-      })
-    )
-    .describe('List of testing scenarios'),
-  notPlannableReason: z.string().nullish().describe('When scenarios is empty, one sentence saying why this page has nothing to test; otherwise null.'),
-});
+const MAX_FORMAT_ATTEMPTS = 3;
 
 const PlannerBase = WithSessionDedup(WithSubPages(Object as unknown as new (...args: any[]) => object));
 
 export class Planner extends PlannerBase implements Agent {
   emoji = '📋';
-  private explorer: Explorer;
   provider: Provider;
   stateManager: StateManager;
   private experienceTracker: ExperienceTracker;
@@ -60,6 +43,8 @@ export class Planner extends PlannerBase implements Agent {
 
   MIN_TASKS = 3;
   MAX_TASKS = 12;
+  private minTasksOverride?: number;
+  private maxTasksOverride?: number;
   currentPlan: Plan | null = null;
   freshStart = false;
   private lastStyleName = '';
@@ -70,7 +55,6 @@ export class Planner extends PlannerBase implements Agent {
 
   constructor(deps: AgentDeps, researcher: Researcher) {
     super();
-    this.explorer = deps.explorer;
     this.provider = deps.ai;
     this.researcher = researcher;
     this.stateManager = deps.stateManager;
@@ -95,8 +79,23 @@ export class Planner extends PlannerBase implements Agent {
     return Math.max(0, Math.min(100, value));
   }
 
-  private getDefaultStartUrl(state: { url: string; fullUrl?: string }): string {
-    return state.fullUrl || state.url;
+  private get effectiveMinTasks(): number {
+    if (this.minTasksOverride !== undefined) return this.minTasksOverride;
+    return ConfigParser.getInstance().getConfig().ai?.agents?.planner?.minTests ?? this.MIN_TASKS;
+  }
+
+  private get effectiveMaxTasks(): number {
+    if (this.maxTasksOverride !== undefined) return this.maxTasksOverride;
+    return ConfigParser.getInstance().getConfig().ai?.agents?.planner?.maxTests ?? this.MAX_TASKS;
+  }
+
+  setTestCount(opts: { minTests?: number; maxTests?: number }): void {
+    if (opts.minTests !== undefined) this.minTasksOverride = opts.minTests;
+    if (opts.maxTests !== undefined) this.maxTasksOverride = opts.maxTests;
+  }
+
+  private getDefaultStartUrl(state: { url: string }): string {
+    return state.url;
   }
 
   getSystemMessage(feature?: string): string {
@@ -150,7 +149,7 @@ export class Planner extends PlannerBase implements Agent {
     return getRegisteredPlan(url)?.plan || null;
   }
 
-  async plan(feature?: string, style?: string, parentPlan?: Plan, completedPlans?: Plan[]): Promise<Plan> {
+  async plan(feature?: string, style?: string, parentPlan?: Plan): Promise<Plan> {
     Stats.plans++;
     const state = this.stateManager.getCurrentState();
     debugLog('Planning:', state?.url);
@@ -204,22 +203,42 @@ export class Planner extends PlannerBase implements Agent {
         tag('step').log('Focusing on main content of this page');
       }
 
-      debugLog('Sending planning prompt to AI provider with structured output');
-
-      const aiResult = await this.provider.generateObject(conversation.messages, TasksSchema, conversation.model);
+      debugLog('Sending planning prompt to AI provider');
+
+      let markdown = '';
+      await loop(
+        async ({ stop, iteration }) => {
+          const response = await this.provider.chat(conversation.messages, conversation.model, { agentName: 'planner' });
+          markdown = response.text;
+          const problems = findPlanMarkdownProblems(markdown);
+          if (problems.length === 0) stop();
+          if (iteration >= MAX_FORMAT_ATTEMPTS) throw new Error(`Planner output does not match the plan format: ${problems.join('; ')}`);
+          debugLog('Plan format problems: %o', problems);
+          conversation.addAssistantText(markdown);
+          conversation.addUserText(dedent`
+            Your plan does not match the required format:
+            ${problems.map((problem) => `- ${problem}`).join('\n')}
+            Rewrite the whole plan in the format from <output_format>. Keep the same scenarios; fix only the structure.
+          `);
+        },
+        { maxAttempts: MAX_FORMAT_ATTEMPTS, interruptible: false }
+      );
 
-      if (!aiResult?.object?.scenarios) {
-        throw new Error('No tasks were created successfully');
+      const defaultStartUrl = this.getDefaultStartUrl(state);
+      markdown = mdq(markdown).query('h1').first().insertAfter(`### Prerequisite\n\n* URL: ${defaultStartUrl}`).toString();
+      const parsedPlan = parsePlansFromMarkdownText(markdown)[0];
+      const fromPlanning = parsedPlan?.tests || [];
+      const blockedBy = readPlanMarkdownComment(markdown, 'blocked');
+      const prerequisite = readPlanMarkdownComment(markdown, 'prerequisite');
+
+      if (!this.currentPlan && fromPlanning.length === 0 && blockedBy) {
+        tag('warning').log(`Page is not plannable: ${blockedBy}`);
       }
-
-      if (!this.currentPlan && aiResult.object.scenarios.length === 0 && aiResult.object.notPlannableReason) {
-        tag('warning').log(`Page is not plannable: ${aiResult.object.notPlannableReason}`);
+      if (!this.currentPlan && fromPlanning.length === 0 && prerequisite) {
+        throw new PlanningBlockedError(state.url, prerequisite, feature, style);
       }
 
-      const defaultStartUrl = this.getDefaultStartUrl(state);
-      const fromPlanning = aiResult.object.scenarios.map((s: any) => new Test(s.scenario, s.priority, s.expectedOutcomes, s.startUrl || defaultStartUrl, s.steps || []));
-
-      return { tests: fromPlanning, planName: aiResult.object.planName };
+      return { tests: fromPlanning, planName: parsedPlan?.title };
     });
 
     const tests = result.tests;
@@ -345,9 +364,6 @@ export class Planner extends PlannerBase implements Agent {
   private async buildConversation(state: ActionResult, style?: string, parentPlan?: Plan, feature?: string): Promise<Conversation> {
     const model = this.provider.getAgenticModel('planner');
     const conversation = new Conversation([], model);
-    conversation.autoTrimTag('page_research', 20000);
-    conversation.autoTrimTag('tested_scenarios', 10000);
-    conversation.autoTrimTag('docs_context', 8000);
 
     conversation.addUserText(this.getSystemMessage(feature));
 
@@ -380,23 +396,25 @@ export class Planner extends PlannerBase implements Agent {
       If exact wording is unknown, describe the expected result generically, for example "an authentication error is shown" or "the user stays on the login page" instead of guessing the literal text.
       If exact redirect destination is unknown, describe the destination by visible page identity, for example "the dashboard page opens" or "the current workspace home page opens" instead of inventing a URL slug.
       Only propose scenarios whose prerequisites are evident from page research, visited pages, or API data preparation context.
-      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
-      If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
+      If a scenario needs existing records or other target data, propose using api if <api_data_preparation> section is set or reuired record is visible on page or can be created via UI.
+      If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks UI controls skip that page.
       Do not assume hidden data exists just because a control is present.
       Do not put record IDs or unique record names in test plans. Describe which record is needed and let Pilot choose it during execution; name a specific record only when research shows a small, complete list of available records.
       If the list is empty or no concrete item names are visible, do not invent "known" or "existing" items. Prefer empty-state, no-match search, clear-search, or read-only list behavior scenarios.
-      Search, filter, sorting, tab, and list scenarios must start from a stable page where those controls are visible; avoid transient create/edit/new URLs unless the scenario tests that form.
-      For option values and list items, use only visible or previously observed data; do not add create/update/delete setup unless the user explicitly requests that workflow.
-      Detail-view scenarios must target visible data entities from list rows, cards, tree nodes, or detail links; do not use filter tabs, counters, status tabs, breadcrumbs, or navigation controls as detail targets.
-      DO NOT propose "verification-only" tests that merely open a UI element (modal, dropdown, panel) and check it exists.
+
+      <meaningful_tests>
       Every test must complete a meaningful action that changes application state or produces a business outcome.
+      DO NOT propose "verification-only" tests that have only assertions and no real state change
       Opening a modal is NOT a test — performing an action INSIDE the modal IS a test.
       Clicking a dropdown is NOT a test — selecting an option and verifying the result IS a test.
+      </meaningful_tests>
+
       <priority_order>
       Tests that change application data are MORE valuable than tests that only change the UI display.
       Prioritize interactions that create, update, or delete data — these test real application behavior.
       Tests that only switch views, toggle filters, or paginate are LESS valuable — propose them only after data-changing tests are covered.
       If multiple ways to create or modify data exist (different types, different forms), propose a separate test for each.
+      If <docs_content> is provided make sure you incorporate app knowledge into planning
       </priority_order>
       ${capabilityGroundingRule}
       ${dataProtectionRules}
@@ -406,28 +424,8 @@ export class Planner extends PlannerBase implements Agent {
 
     conversation.addUserText(planningPrompt);
     conversation.addUserText(this.getTasksMessage());
-    const currentState = this.stateManager.getCurrentState();
-    const research = await this.researcher.research(currentState || state, {
-      deep: true,
-    });
 
-    let docsPromise: Promise<string> | null = null;
-    if (this.scout && this.docsWeight > 0) {
-      docsPromise = this.scout.collectDocs({ url: state.url, title: state.title, feature, excludeUrls: this.knowledgeTracker.applicationSpecUrls(state) });
-    }
-    let plannerResearch = mdq(research).query('code').replace('').toString();
-    plannerResearch = mdq(plannerResearch)
-      .query('table')
-      .replaceEach((table) => {
-        const rows = table.toJson();
-        if (rows.length === 0 || !rows[0].Element) return table.text();
-        const elementWithType = rows.map((r) => ({
-          Element: r.Element,
-          Type: r.Type || '',
-        }));
-        return jsonToTable(elementWithType, ['Element', 'Type']);
-      })
-      .toString();
+    const [plannerResearch, docs] = await Promise.all([this.collectResearch(state), this.collectDocs(state, feature)]);
 
     const hasFocusedOverlay = hasFocusedSection(plannerResearch);
     const focusNote = hasFocusedOverlay ? "IMPORTANT: One section is marked as **Focused** — this is the user's current focus area. Concentrate testing on the Focused section FIRST — test all interactions inside it before planning tests for the rest of the page." : '';
@@ -448,22 +446,23 @@ export class Planner extends PlannerBase implements Agent {
     const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
     if (applicationContext) {
       conversation.addUserText(applicationContext);
+      const words = applicationContext.split(/\s+/).filter(Boolean).length;
+      tag('info').log(`Added application spec to planning: ${words} words for ${state.url}`);
     }
 
-    if (docsPromise) {
-      const docs = await docsPromise;
-      if (docs) {
-        conversation.addUserText(dedent`
-          <docs_context>
-          Documentation retrieved from the collected corpus by the Scout agent.
-          Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
+    if (docs) {
+      conversation.addUserText(dedent`
+        <docs_context>
+        Documentation retrieved from the collected corpus by the Scout agent.
+        Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
 
-          Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
+        Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
 
-          ${docs}
-          </docs_context>
-        `);
-      }
+        ${docs}
+        </docs_context>
+      `);
+      const words = docs.split(/\s+/).filter(Boolean).length;
+      tag('info').log(`Added spec to planning (${words} words)`);
     }
 
     let activeRegion = '';
@@ -638,20 +637,14 @@ export class Planner extends PlannerBase implements Agent {
   private getTasksMessage(): string {
     return dedent`
     <task>
-      Provide testing scenarios as structured data with the following requirements:
+      Provide testing scenarios with the following requirements:
       1. Create a short, descriptive plan name that summarizes what will be tested (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")
-      2. Assign priorities based on business importance:
-         - CRITICAL: Core business functionality that defines the page purpose
-         - IMPORTANT: Key user flows, primary features, CRUD operations
-         - HIGH: Secondary features, edge cases for critical flows
-         - NORMAL: Supporting actions, settings, configuration
-         - LOW: Cosmetic checks, boundary testing, minor interactions
-      3. Propose tests following research section order: ${this.sectionOrder.join(', ')}
+      2. Propose tests following research section order: ${this.sectionOrder.join(', ')}
          Cover sections in this order — first propose tests for elements from earlier sections, then later ones.
          Extended Research sections come after the main sections.
-      4. Focus on interactive elements of the page. Skip navigation links that lead away from current page.
-      5. Focus on tests you are 100% sure relevant to this page and can be achived from UI.
-      6. For each task, provide BOTH steps and expected outcomes as separate arrays:
+      3. Focus on interactive elements of the page. Skip navigation links that lead away from current page.
+      4. Focus on tests you are 100% sure relevant to this page and can be achived from UI.
+      5. For each task, provide BOTH steps and expected outcomes as separate lists:
 
          STEPS - actionable commands:
          - Each step should be a specific action to perform
@@ -682,8 +675,63 @@ export class Planner extends PlannerBase implements Agent {
          - Do not wrap text in ** or * quotes, ( or ) brackets.
          - Avoid using emojis or special characters.
       7. Only tests that can be tested from web UI should be proposed.
-      8. For a fresh plan propose at least ${this.MIN_TASKS} tests; when expanding an existing plan return ONLY new scenarios not in the tested list, and an empty array if none remain.
+      8. For a fresh plan propose at least ${this.effectiveMinTasks} and at most ${this.effectiveMaxTasks} tests; when expanding an existing plan return ONLY new scenarios not in the tested list, and no scenarios if none remain.
     </task>
+
+    <output_format>
+    Reply with the plan as markdown in exactly this format and nothing else:
+
+    <!-- suite -->
+    # {short plan name summarizing what is tested}
+
+    <!-- test -->
+    # {one sentence describing the behavior to test}
+
+    ## Steps
+    * {first action}
+    * {next action}
+    * {one bullet per action, as many as the workflow needs}
+
+    ## Expected
+    * {first verifiable outcome}
+    * {one bullet per outcome, as many as the scenario verifies}
+
+    Repeat the block from <!-- test to ## Expected for every scenario.
+    Every scenario needs its own <!-- test --> comment, its steps and its expected outcomes.
+    Steps list every action of the workflow in order, one action per bullet, from the starting page to the final action.
+    Expected lists every outcome to verify, one outcome per bullet.
+
+    When there is nothing to test, write no scenarios; after the plan name add one comment instead:
+    <!-- prerequisite: {step that must be done first} --> when the page shows a sign-in form or another required step instead of the content its URL is for
+    <!-- blocked: {one sentence why the page has nothing to test} --> otherwise
+    </output_format>
     `;
   }
+
+  private async collectResearch(state: ActionResult): Promise<string> {
+    const currentState = this.stateManager.getCurrentState();
+    const research = await this.researcher.research(currentState || state, { deep: true });
+    let plannerResearch = mdq(research).query('code').replace('').toString();
+    plannerResearch = mdq(plannerResearch)
+      .query('table')
+      .replaceEach((table) => {
+        const rows = table.toJson();
+        if (rows.length === 0 || !rows[0].Element) return table.text();
+        const elementWithType = rows.map((r) => ({
+          Element: r.Element,
+          Type: r.Type || '',
+        }));
+        return jsonToTable(elementWithType, ['Element', 'Type']);
+      })
+      .toString();
+    return plannerResearch;
+  }
+
+  private async collectDocs(state: ActionResult, feature?: string): Promise<string> {
+    if (!this.scout || this.docsWeight <= 0) return '';
+    const query = ScoutQuery.fromState(state);
+    query.feature = feature;
+    query.exclude = this.knowledgeTracker.applicationSpecUrls(state);
+    return this.scout.collectDocs(query);
+  }
 }