explorbot 0.4.7 → 0.4.9

package/docs/superpowers/specs/2026-09-14-mdq-package-design.md

@@ -0,0 +1,397 @@
+# mdq — Markdown Query & Edit Package
+
+Date: 2026-09-14
+Status: Approved design, pending implementation
+
+## Goal
+
+Extract `src/utils/markdown-query.ts` into `src/utils/mdq/`, designed as a publishable
+standalone package: query markdown *and* update it, with a jq-like CLI planned as a
+second phase.
+
+The name `mdq` is unclaimed on npm (verified 404). Publishing is deferred; this change
+makes the package publish-ready but adds no `package.json` or build script.
+
+## Constraints
+
+- **Zero explorbot imports.** Two dependencies only: `marked` for markdown, `yaml` for
+  frontmatter. Both are already repo deps (`marked` ^16.2.0, `yaml` ^2.8.3).
+- **Two files**, per the module split below.
+- 54 in-repo call sites must keep working; a re-export shim carries them.
+
+## Architecture
+
+```
+src/utils/mdq/
+  query.ts   selector grammar - token index - MarkdownDoc - Selection (reads)
+  edit.ts    pure edits over (source, ranges): splicing - whitespace - renderers
+  README.md  public documentation
+src/utils/markdown-query.ts   re-export shim
+tests/unit/mdq/*.test.ts
+```
+
+`edit.ts` exports pure functions taking source text plus ranges or tokens, and returning
+new source text. It imports types from `query.ts` type-only and never references a class
+value. `query.ts` owns both classes and delegates each write verb to exactly one `edit.ts`
+call. This keeps the split acyclic by construction.
+
+Two types:
+
+- **`MarkdownDoc`** — a whole document. Returned by `mdq()` and by every write.
+- **`Selection`** — a set of matched ranges. Returned by `query()` and the sugar methods.
+
+One rule, stated in the README: **reads narrow, writes return the document.**
+
+## API
+
+### `mdq(source)`
+
+`mdq(source: string | MarkdownDoc): MarkdownDoc`
+
+Accepting a `MarkdownDoc` makes re-wrapping free.
+
+### `MarkdownDoc`
+
+| Method | Returns | Notes |
+|---|---|---|
+| `query(selector, matcher?)` | `Selection` | |
+| `frontmatter()` | `Record<string, unknown>` | `{}` when absent |
+| `setFrontmatter(key, value)` | `MarkdownDoc` | `null` value deletes the key |
+| `append(md)` | `MarkdownDoc` | add a block at end of document |
+| `prepend(md)` | `MarkdownDoc` | add a block at start of body, after frontmatter |
+| `toString()` / `valueOf()` | `string` | full document, frontmatter included |
+
+Plus the shared sugar layer.
+
+`append`/`prepend` exist because "add a section to the end of the document" otherwise has
+no clean path — only the `section().last().insertAfter(...)` workaround. There is a real
+call site: `deep-analysis.ts:131` builds it by hand today as
+`` `${cached.trimEnd()}\n\n# Extended Research\n\n...` ``.
+
+### `Selection` — reads
+
+Narrow or extract; never mutate.
+
+| Method | Returns | Replaces |
+|---|---|---|
+| `query(selector, matcher?)` | `Selection` | sub-query, unchanged |
+| `text()` | `string` | — (`get()` deprecated) |
+| `count()` | `number` | |
+| `exists()` | `boolean` | the `.count() > 0` idiom, 3 in-repo uses |
+| `first()` / `last()` | `Selection` | |
+| `at(n)` | `Selection` | new; sugar-path equivalent of DSL `[n]` |
+| `slice(from?, to?)` | `Selection` | new; sugar-path equivalent of DSL `[a:b]` |
+| `each()` | `Selection[]` | |
+| `nodes()` | `NodeInfo[]` | `meta()` |
+| `rows()` | `Record<string,string>[]` | `toJson()` — it only ever handled tables |
+| `entries()` | `Record<string,string>` | `keyValue()` |
+| `preceding()` / `following()` | `Selection` | `before()` / `after()` |
+
+`before`/`after` are renamed specifically to free those names from colliding with
+`insertBefore`/`insertAfter`.
+
+### `Selection` — writes
+
+Every write returns `MarkdownDoc`, so edits chain in one expression.
+
+| Method | Signature | Notes |
+|---|---|---|
+| `replace(md)` | `(Markdown) => MarkdownDoc` | |
+| `replaceEach(fn)` | `((Selection, number) => Markdown) => MarkdownDoc` | |
+| `remove()` | `() => MarkdownDoc` | node **plus its adjacent `space` token** |
+| `insertBefore(md)` | `(Markdown) => MarkdownDoc` | sibling |
+| `insertAfter(md)` | `(Markdown) => MarkdownDoc` | sibling |
+| `prepend(md)` | `(Markdown) => MarkdownDoc` | inside a section or list; `MdqOperationError` on a leaf node |
+| `append(md)` | `(Markdown) => MarkdownDoc` | inside a section or list; `MdqOperationError` on a leaf node |
+| `addRow(row)` | `(Record<string,string>) => MarkdownDoc` | table only; re-aligns columns |
+| `addItem(text)` | `(string) => MarkdownDoc` | list only; matches marker + indent |
+| `setEntry(key, value)` | `(string, string \| null) => MarkdownDoc` | `null` deletes |
+
+Naming now pairs: `rows()`/`addRow()`, `entries()`/`setEntry()`, `nodes()`.
+
+Every verb that *takes* markdown accepts `Markdown = string | MarkdownDoc`, mirroring
+`mdq()` itself. A `replaceEach` callback may therefore return a `MarkdownDoc` built by a
+nested edit, without a `.toString()` hop.
+
+### Sugar layer
+
+Eleven methods on both classes: `section` `heading` `paragraph` `table` `list` `item`
+`code` `blockquote` `comment` `html` `hr`.
+
+Each is `(matcher?, opts?) => Selection` and is *defined as* `query(sel, matcher)` —
+documented as sugar, not a parallel implementation. Defined once on a shared base that
+implements them in terms of an abstract `query()`, so the two classes do not duplicate it.
+
+Depth is an option rather than 12 near-duplicate methods:
+
+```js
+mdq(src).section('API', { depth: 2 })   // DSL: query('section2("API")')
+mdq(src).heading(/^f/i).at(0)           // DSL: query('heading(/^f/i)[0]')
+mdq(src).comment(/^test/)               // DSL: query('comment(/^test/)')
+```
+
+### Exported types
+
+Declared at the end of their file, per repo convention.
+
+```ts
+type Markdown = string | MarkdownDoc;
+type Matcher  = string | RegExp | ((text: string) => boolean);
+
+interface NodeInfo {
+  type: string;            // 'heading' | 'paragraph' | 'table' | 'comment' | ...
+  depth: number | null;    // heading level, else null
+  text: string;            // unwrapped text; comment bodies without <!-- -->
+}
+
+interface SelectorOptions {
+  depth?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+```
+
+`Matcher` semantics:
+
+- `string` — exact match (mirrors DSL `"x"`)
+- `RegExp` — pattern, honoring its own flags
+- function — predicate; needs no escaping at all
+
+Note the consequence for `comment`: a `string` matcher is **exact**, and this repo's own
+test-plan comments are multi-line (`<!-- test\n  priority=critical\n-->`). So
+`comment('test')` matches only a bare `<!-- test -->`; reaching the multi-line ones needs
+`comment(/^test/)` or a predicate. Exactness is the consistent rule and is kept, but it is
+the one place the sugar is likely to surprise.
+
+This removes an existing wart. Today the repo hand-escapes to build selector strings:
+
+```js
+const escaped = section.name.replace(/"/g, '\\"');   // researcher/focus.ts:77
+mdq(result.text).query(`section2(~"${escaped}")`);
+```
+
+### Deprecated aliases
+
+`get` `toJson` `keyValue` `setKeyValue` `meta` `before` `after` are kept, marked
+`@deprecated`, and omitted from the README so the published surface reads clean.
+
+Aliases cover the read renames completely. They cannot shield the write return-type
+change — see Migration.
+
+## Selector grammar
+
+Unchanged, plus one addition and three fixes.
+
+### `comment` (new)
+
+`html` tokens filtered to those that are comments. Not an alias for `html`: `<div>x</div>`
+lexes as `html` too.
+
+- `comment` matches on the **inner** body, trimmed. `html` matches on raw.
+  This is required for anchored patterns — `/^test/` against `<!-- test id=1 -->` only
+  works if the text is `test id=1`.
+- Multi-line comments are a single token and keep their newlines in the matched text.
+- **Inline comments are out of scope for 1.0.** `para with <!-- x --> comment` lexes the
+  comment inside the paragraph token; it is not reachable as a block. Documented, not faked.
+
+`comment` and `html` together finish the `test-plan-markdown.ts` story: its hand-rolled
+line parser (`src/utils/test-plan-markdown.ts:122+`) exists only because mdq could not
+see `<!-- suite -->` and `<!-- test ... -->`.
+
+### Fixes
+
+1. **Regex flags are honored.** Today flags are parsed then discarded
+   (`markdown-query.ts:90`) and `'i'` is hardcoded (`markdown-query.ts:156`), so `/x/` is
+   case-insensitive while `"x"` and `~"x"` are case-sensitive. After the fix `/x/i` is
+   insensitive and `/x/` is not. One production call site relies on the old behavior:
+   `researcher.ts:316` `section2(/^summary/)` becomes `/^summary/i`. Tests already write
+   flags explicitly.
+2. **Unknown selectors throw.** Today `query('secton("A")')` silently matches nothing
+   (`markdown-query.ts:103-106`, `:356`). Unacceptable for a CLI.
+3. **Table text-match widens to headers plus cells.** Today `getTokenText` returns headers
+   only (`markdown-query.ts:181`), so `table(~"GET")` can never match a cell. No call site
+   uses table text-matching, so this is safe.
+
+## Update semantics
+
+`marked` separators are uneven, and every write rule follows from this:
+
+| Token | `raw` |
+|---|---|
+| `heading` | `"# A\n\n"` — separators baked in |
+| `paragraph` | `"para"` — no trailing newline |
+| `space` | `"\n\n"` — a separate token |
+
+The token index therefore records each node's range **and its adjacent `space` range**.
+
+> **Invariant: mdq never leaves zero blank lines between blocks, and never more than one.**
+
+- `remove()` takes the node plus its trailing `space` — or its leading `space` when it is
+  the last block. Without this, removing a paragraph leaves a four-newline crater. This is
+  the most likely bug in the feature and gets dedicated tests.
+- `insertAfter` / `append` normalize inserted markdown to one trailing `\n` and splice at
+  the boundary, never inside a space token.
+- `append` on a section inserts before the next same-or-shallower heading, reusing the
+  existing `computeSections` end boundary.
+- `addRow` re-renders the whole table so column pipes stay aligned.
+- `addItem` copies the list's existing marker (`-`, `*`, `1.`) and indent.
+
+## Frontmatter
+
+Every `knowledge/` and `experience/` file opens with `---\nurl: /login\n---`, which
+`marked` lexes as a setext h2 titled `url: /login`.
+
+mdq detects leading frontmatter, excludes it from the token index with offsets preserved
+so edits splice correctly, and exposes it as data.
+
+Reading and writing both go through `yaml`'s **Document API** (`YAML.parseDocument`), not
+`parse`/`stringify`. That buys two things a hand-rolled parser cannot: correctness on
+nested maps, lists and block scalars — the Jekyll/Astro/Obsidian files that justify the
+feature — and **comment preservation through a write**, verified:
+
+```yaml
+# a leading comment          <- survives setFrontmatter('wait', 2000)
+url: /login
+wait: 2000
+tags:
+  - auth
+  - smoke
+nested:
+  key: value # trailing note  <- also survives
+```
+
+`gray-matter` is deliberately not used: `knowledge-tracker.ts` keeps it for its own
+purposes, but a published package should not carry it to do what `yaml` already does.
+
+```js
+const doc = mdq(knowledgeFile);
+doc.frontmatter();                  // { url: '/login', wait: 1000, tags: ['auth'] }
+doc.query('h2').count();            // 0 — the --- block is not a heading
+doc.setFrontmatter('wait', 2000).toString();
+```
+
+## Errors
+
+`MdqError` base, with:
+
+- `MdqSelectorError` — malformed or unknown selector, carrying the offending index.
+- `MdqOperationError` — a verb applied to the wrong node type, e.g. `addRow` on a paragraph.
+
+An **empty selection is a safe no-op**: reads return `''` / `[]`, writes return the
+document unchanged. This preserves the existing "returns source unchanged when no matches"
+test.
+
+## CLI (phase 2)
+
+The selector is the program, the file or stdin is the input, markdown is the default output.
+
+A leading `.` is accepted and ignored, so muscle memory from jq (`mdq '.h2'`) works. It is
+sugar in the grammar, not a separate syntax — without it the new "unknown selectors throw"
+rule would reject the most natural thing a jq user types first.
+
+```bash
+mdq 'h2' README.md                           # raw markdown of matches
+cat plan.md | mdq 'section("API") table' -j  # rows() as JSON
+mdq 'comment(~"test")' plan.md --count
+mdq 'section("FAQ")' doc.md --remove -i      # edit in place
+mdq 'table[0]' api.md --add-row '{"Method":"GET","Path":"/users"}' -i
+```
+
+Flags mirror library verbs exactly: `--remove` `--replace` `--insert-before`
+`--insert-after` `--prepend` `--append` `--add-row` `--add-item` `--set k=v`, plus
+`-i/--in-place`, `-j/--json`, `-c/--count`, `-t/--text`, `--frontmatter`.
+
+Built with Commander, per repo convention. Exit codes compose like grep: **0** match,
+**1** no match, **2** usage or selector error.
+
+1.0 reads one file or stdin. Multi-file input is out of scope.
+
+## Testing
+
+Port the existing 801-line suite first — it is the regression net for all 54 call sites.
+Then add coverage for what is new or newly specified:
+
+- whitespace craters on `remove` (the invariant above)
+- chained multi-edits through `MarkdownDoc`
+- `addRow` column alignment; `addItem` marker and indent matching
+- frontmatter round-trip, including a file whose body has its own `---`
+- `comment` inner-text matching, multi-line comments, and `html` versus `comment`
+- `MdqSelectorError` on unknown selectors and malformed input
+- sugar equivalence: every sugar call equals its `query()` form
+
+## Migration
+
+Two steps. Only the second carries risk.
+
+1. `src/utils/markdown-query.ts` becomes a re-export shim. **All 54 call sites keep
+   working untouched.**
+2. A sweep updates imports, then fixes the call sites the return-type change breaks.
+
+Deprecated read aliases mean **no read call site changes**. Writes are not shielded: a
+verb that returned `string` now returns `MarkdownDoc`. That breaks four classes of site,
+at least eleven in total.
+
+**(a) Assignment into a `string`-typed target** — 7 sites, each needs `.toString()`:
+
+| Site | Target |
+|---|---|
+| `experience-tracker.ts:265` | `content` (inferred `string`) |
+| `experience-tracker.ts:289` | `combined` (inferred `string`) |
+| `researcher/deep-analysis.ts:129` | `let updated: string` |
+| `researcher/locators.ts:307` | `result.text` |
+| `researcher/locators.ts:309` | `result.text` |
+| `researcher/pagination.ts:61` | `result.text` |
+| `researcher/research-result.ts:57` | `section.rawMarkdown` |
+| `researcher/research-result.ts:58` | `this.text` |
+
+**(b) A string method called on the result** — 2 sites:
+
+- `planner.ts:304` — `.replace('').trim()`
+- `planner.ts:322` — `const kept = ...replace('')`, then `kept.trimEnd()` on line 324
+
+**(c) Returned from a `replaceEach` callback** — `deep-analysis.ts:542`. **Resolved by
+design**, not by migration: callbacks accept `Markdown`, so returning a `MarkdownDoc` is
+valid. No edit needed.
+
+**(d) Compared against a string — the dangerous one.** `research-result.ts:56`:
+
+```js
+const updated = sectionQuery.query('table').replace(`${newTable.trimEnd()}\n`);
+if (updated === this.text) return;     // MarkdownDoc === string is always false
+```
+
+This does not crash. The guard silently stops firing and the method starts doing work it
+used to skip. `tsc` does flag it — comparing types with no overlap is an error — which is
+precisely why the manual type-check below is not optional. Every `replace`/`setEntry`
+result used in an equality or truthiness test must be audited, not just the ones that fail
+to compile.
+
+Sites that flow the result straight back into `mdq()` — `planner.ts:303`, `planner.ts:405`
+— keep working unchanged, because `mdq()` accepts a `MarkdownDoc`.
+
+`tsc` is the complete detector for these breaks: every one surfaces as a type error. The migration step is therefore *run `tsc` over the changed files and fix
+what it reports*, with the table above as the expected result rather than the whole story.
+
+Also in the sweep: `researcher.ts:316` gains its `i` flag (`section2(/^summary/i)`).
+
+### Hazards
+
+- **`.claude/worktrees/**` holds four stale copies** of `markdown-query.ts` and its
+  consumers. Every grep or sed sweep must exclude that path.
+- **`tsc` runs with `--noCheck` in CI.** The nine breaks above are *exactly* the errors a
+  type-check would raise, and CI raises none of them — a fully green build proves nothing
+  here. Run `tsc` manually over the changed files before considering the sweep done.
+
+## Style compliance
+
+The current file violates several repo rules that the rewrite fixes: types belong at the
+end of the file, ternaries are banned (`markdown-query.ts:30`, `:34`, `:129-130`, `:295`),
+and the `switch` in `matchText` should be early returns.
+
+## Deliberately out of scope
+
+- Publishing: no `package.json`, no build script, no npm release in this change.
+- Frontmatter formats other than YAML (TOML `+++`, JSON) — detected and skipped from the
+  token index, but not parsed.
+- Row-level and item-level *selectors* (`addRow` has no `removeRow` partner). A future
+  `row(...)` selector is the right shape for that; guessing at it now is premature.
+- Inline HTML comments.
+- Multi-file CLI input.

package/package.json

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

package/rules/chief/general.md

@@ -2,6 +2,8 @@
 - Steps should specify exact HTTP methods, paths, and key payload details
 - Expected outcomes should be specific and verifiable (status codes, response fields, error messages)
 - For CRUD operations, each test should handle its own setup and teardown
+- Treat existing records and IDs discovered from the API, knowledge, or sample data as read-only
+- A scenario that updates, patches, deletes, archives, or otherwise mutates a record must create that target inside the same scenario first; omit the scenario if safe setup is impossible
 - Expect standard REST conventions: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, 422 Unprocessable Entity
 - NEVER propose scenarios that test the same thing. "Create a basic suite" and "Successful creation of a simple suite" are DUPLICATES. Each scenario must test a DISTINCT behavior or aspect.
 - Before finalizing, review all scenarios and remove any that overlap in what they actually verify.

package/rules/researcher/pagination.md

@@ -2,5 +2,6 @@
 When a section is a list that continues beyond what is shown, add one line under its `> Container:` line:
 `> Pagination: controls` — it has page numbers (1, 2, 3), prev/next arrows, or a "load more" button.
 `> Pagination: infinite` — it has none of those and loads more as it is scrolled.
+Omit the line when the items already shown are the whole collection.
 Sorting, filtering and switching tabs are not pagination — omit the line then.
 </pagination>

package/src/action.ts

@@ -592,10 +592,11 @@ export const attachStepLogger = (target: ExecutedStep[], assertionsTarget?: Arra
     }
     tag('step').log(step);
   };
-  codeceptjs.event.dispatcher.on(codeceptjs.event.step.passed, listener);
+  const onPassed: StepListener = (step) => listener(step);
+  codeceptjs.event.dispatcher.on(codeceptjs.event.step.passed, onPassed);
   codeceptjs.event.dispatcher.on(codeceptjs.event.step.failed, listener);
   return () => {
-    codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
+    codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, onPassed);
     codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
   };
 };

package/src/ai/fisherman/tools.ts

@@ -221,13 +221,19 @@ export function createAskApiTool(fisherman: Fisherman | null, task: Test) {
   return {
     askApi: tool({
       description: dedent`
-        Ask what data already exists, changing nothing.
-        Ask a question about existing records: which ones are there, what they are called, whether a particular one exists.
-        Use it before precondition() to see whether suitable data is already available, and whenever a step needs the exact name or id of a record that is already there.
+        Read the app's data over the API, changing nothing.
+        Answers questions about records: which ones are there, what they are called, whether a particular one exists.
+
+        Use it to:
+        - check whether suitable data already exists, before precondition() creates any
+        - get the exact name or id of a record a step must act on
+        - find out whether an action was stored, when the app reported success but the page does not show the result
+        - find out whether data exists at all, when a list or dropdown is empty
+
         It never creates, edits or deletes anything — precondition() does that.
       `,
       inputSchema: z.object({
-        question: z.string().describe('What to find out about data that already exists'),
+        question: z.string().describe('What to find out about the data'),
       }),
       execute: async ({ question }) => {
         tag('info').log(`Ask API: ${question}`);

package/src/ai/navigator.ts

@@ -703,7 +703,7 @@ class Navigator implements Agent {
     const cachedVerification = actionResult.getVerification(message);
     if (cachedVerification !== null) {
       tag('operation').log(`Reusing cached verification: ${cachedVerification ? 'PASS' : 'FAIL'}`);
-      return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
+      return { verified: cachedVerification, inexpressible: false, results: [], successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
     }
 
     const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
@@ -832,9 +832,6 @@ class Navigator implements Agent {
           observability: {
             agent: 'navigator',
           },
-          catch: async (error) => {
-            debugLog(error);
-          },
         }
       );
     } finally {

package/src/ai/pilot.ts

@@ -152,14 +152,6 @@ export class Pilot implements Agent {
       ${sessionLog || 'No actions recorded'}
       </session_log>
 
-      Decide and commit. "continue" extends the loop and burns iterations — choose it only when
-      evidence is genuinely insufficient to call pass/fail, not as a safety hedge.
-      - "pass" if final state proves the SCENARIO GOAL is accomplished. Set requestVerification.
-      - "fail" if scenario was attempted but goal not achieved.
-      - "skipped" if scenario is irrelevant/inapplicable, OR systematic infrastructure failures.
-      - "continue" only when a concrete missing piece of evidence (a verify/see) would change your verdict.
-      - Mixed evidence + final state shows success → pass. Mixed + final state unclear → continue with guidance.
-
       When deciding "pass", you MUST also set requestVerification to a one-sentence natural-language
       claim about the current page (e.g., "New item Foo is visible in the items list"). NOT
       code — do not write I.*, expect(), .then(), or any JavaScript. Choose the strongest single
@@ -401,7 +393,7 @@ export class Pilot implements Agent {
   private buildVerdictSystemPrompt(task: Test): string {
     return dedent`
       You are Pilot — final decision maker for test pass/fail. Review the evidence and commit to a
-      verdict; "continue" only when evidence is genuinely insufficient.
+      verdict.
 
       ${capabilityGroundingRule}
 
@@ -415,10 +407,11 @@ export class Pilot implements Agent {
         DOM assertion can't be made.
         Do not pass when Tester achieved only a related navigation/filter/tab/status outcome instead of the
         requested action, workflow, or entity detail goal.
-      - "fail": scenario was attempted but the goal was not achieved.
+      - "fail": goal not achieved and no further step toward it is available on the current page.
       - "skipped": scenario is irrelevant to the app, OR systematic infrastructure failures (LLM errors,
         crashes) prevented testing. NOT for "test failed to interact" — that's "fail" or "continue".
-      - "continue": tester hasn't completed the goal; provide concrete guidance (which tool, what to check).
+      - "continue": goal incomplete but the control for the NEXT step is present on the current page, or a
+        concrete missing check would change your verdict. Guidance must name that step.
         If a verify() asserted a state that was ALREADY TRUE before the test, it proves nothing — reject.
 
       reason field: one short sentence, maximum 120 characters. Do NOT restate the decision
@@ -1023,14 +1016,14 @@ export class Pilot implements Agent {
   private formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string {
     const lines: string[] = [];
     for (const [assertion, passed] of Object.entries(currentState.verifications ?? {})) {
-      if (passed) lines.push(`state verification (passed): ${assertion}`);
+      if (passed) lines.push(`verify: ${assertion}`);
     }
 
     for (const exec of testerConversation.getToolExecutions()) {
       if (!EVIDENCE_TOOLS.includes(exec.toolName) || !exec.wasSuccessful) continue;
       const description = exec.input?.assertion || exec.input?.request || truncateJson(exec.input);
-      const result = exec.output?.message || exec.output?.analysis || exec.output?.result;
-      lines.push(`CHECK ${exec.toolName} (executed successfully): ${description}${result ? ` -> ${result}` : ''}`);
+      const analysis = exec.output?.analysis;
+      lines.push(`${exec.toolName}: ${description}${analysis ? ` -> ${analysis}` : ''}`);
     }
 
     return [...new Set(lines)].join('\n');
@@ -1134,7 +1127,9 @@ export class Pilot implements Agent {
       ${interactive ? '- Use askUser() only as last resort.' : ''}
 
       Diagnostic patterns (use <state>, executed/element/skipped fields, ariaDiff):
-      - Click failed + button in "disabled buttons" → required field missing. Instruct fill first.
+      - Scenario's target control in "disabled buttons" → a precondition is unmet; identify which before acting.
+        Other disabled controls often name the unsatisfied constraint; "active form" marks [required] fields.
+        Aim Tester at the constraint the page names, not the one the scenario assumed — note the difference in PROGRESS.
       - "overlay: none" but Tester targets an overlay → overlay closed; re-trigger.
       - "region:" in <state> → a large area appeared in place without navigation (subview, wizard step, panel). Direct Tester to act inside it; the rest of the page is still usable.
       - Action SUCCESS but ariaDiff empty → may have worked without visible DOM change; check result message.
@@ -1156,14 +1151,20 @@ export class Pilot implements Agent {
       Tester tools: click, pressKey, form, see, verify, interact, context, research, xpathCheck,
       visualClick, back, getVisitedStates, reset, stop, finish, record.
       Use tool names exactly as listed. Do not invent combined names or aliases.
+      Reloading is not a tool: to re-read a page from the server, instruct Tester to run I.reloadPage() through form.
 
       ${capabilityGroundingRule}
 
       YOUR Pilot-only tools, both over the API:
 
-      askApi(question) — ask what data already exists. It changes nothing. Use it to check whether
-      suitable data is already there before creating any, and to get the exact name or id of an existing
-      record a step must act on.
+      askApi(question) — read the app's data over the API. It changes nothing. Use when:
+
+      - Before precondition() — check whether suitable data already exists.
+      - A step needs the exact name or id of an existing record.
+      - The app reported success but the page does not show the result — ask whether it was stored.
+      - A list or dropdown is empty — ask whether the data exists at all.
+
+      The page is not the only witness. A record missing from the page may still exist.
 
       precondition(description) — create FRESH disposable test data. Never request users. Use when:
 

package/src/ai/planner/session-dedup.ts

@@ -1,4 +1,4 @@
-import type { Plan } from '../../test-plan.ts';
+import { type Plan, type Test, TestResult } from '../../test-plan.ts';
 import type { Constructor } from '../researcher/mixin.ts';
 
 const previousPlans: Plan[] = [];
@@ -18,7 +18,7 @@ export function WithSessionDedup<T extends Constructor>(Base: T) {
       for (const plan of previousPlans) {
         if (plan === this.currentPlan) continue;
         for (const test of plan.tests) {
-          lines.push(`${plan.url || '/'} | ${test.style || 'default'} | ${test.scenario}`);
+          lines.push(formatSessionTest(plan, test));
         }
       }
       return lines.join('\n');
@@ -34,6 +34,20 @@ export function WithSessionDedup<T extends Constructor>(Base: T) {
   };
 }
 
+export function formatSessionTest(plan: Plan, test: Test): string {
+  const lastNote = Object.values(test.notes)
+    .filter((note) => note.message)
+    .pop();
+  let outcome: string | null = test.result;
+  if (!outcome) outcome = 'pending';
+  if (!test.result && lastNote) outcome = 'unfinished';
+
+  const line = `${plan.url || '/'} | ${test.style || 'default'} | ${outcome} | ${test.scenario}`;
+  if (!lastNote) return line;
+  if (outcome !== TestResult.FAILED && outcome !== 'unfinished') return line;
+  return `${line} — ${lastNote.message.slice(0, 140)}`;
+}
+
 export function clearSessionDedup(): void {
   previousPlans.length = 0;
 }

package/src/ai/planner.ts

@@ -358,8 +358,10 @@ export class Planner extends PlannerBase implements Agent {
       You can suggest scenarios that can be tested only through web interface.
       You can't test emails, database, SMS, or any external services.
       Suggest scenarios that can be potentially verified by UI.
-      Focus on error or success messages as outcome.
-      Focus on URL page change or data persistency after page reload.
+      Prefer outcomes grounded in observed interface behavior.
+      Every expected outcome must be verifiable through the web interface.
+      If a page or subpage has not been observed, describe the expected visible result generically instead of inventing interface details.
+      Persistency after a reload counts only when the persisted state can be confirmed through the interface.
       If there are subpages (pages with same URL path) plan testing of those subpages as well
       Plan CRUD operations in order: create, read, update, delete.
       Do not invent specific route names, success messages, validation texts, badge counts, or welcome messages unless they are visible in research, visited pages, or prior observed flows.
@@ -370,7 +372,7 @@ export class Planner extends PlannerBase implements Agent {
       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.
       Do not assume hidden data exists just because a control is present.
-      For scenarios that act on existing items or search/filter by existing values, use only item names or values visible in research, visited pages, or prior observed flows.
+      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.
@@ -595,7 +597,9 @@ export class Planner extends PlannerBase implements Agent {
     const sessionTests = this.getSessionTestsSummary();
     if (sessionTests) {
       conversation.addUserText(dedent`
-        Tests already planned in this session across all pages. DO NOT duplicate any of these:
+        Tests already planned in this session across all pages, with how each one ended. DO NOT duplicate any of these.
+        A failed test means the app or the harness could not do what it tried: do not re-propose the same behavior on another page unless you can name what makes it work this time.
+        A failed or unfinished test carries the last thing it observed after the dash — read it before deciding that the behavior is worth trying again.
 
         <session_tests>
         ${sessionTests}