@hover-dev/core 0.16.0 → 0.18.0

package/README.md

@@ -4,7 +4,6 @@ The local Node service. Owns:
 
 - **Agent invocation** (`src/agents/`) — Local CLI Agent First. Spawns `claude` / `codex` / `cursor-agent` / `aider` / `gemini-cli` / `qwen-code` and normalizes their output into a single `InvokeEvent` stream.
 - **Playwright preflight** (`src/playwright/`) — verifies CDP connection to the user's Chrome.
-- **Smoke test** (`src/smoke.ts`) — end-to-end verification of the whole chain.
 
 ## Architecture (agents/)
 
@@ -41,7 +40,7 @@ per-save path** (reproducible by construction):
   runnable around it. `countOptimizableMarkers()` reads the count back; `listSpecs`
   surfaces it as `SpecSummary.optimizableCount`.
 - Alongside the `.spec.ts`, a **sidecar** is written to
-  `.hover/<slug>.json` — the structured `SpecStep[]` + observed signals. This is
+  `.hover/sidecars/<slug>.json` — the structured `SpecStep[]` + observed signals. This is
   the machine-readable behavior record the optimization pass reads (it keeps the
   spec itself clean).
 
@@ -52,33 +51,32 @@ The **service** (never the sandboxed browser agent) can optionally run an LLM
 feedback the session observed. Its input is data the service already holds (the
 draft + sidecar + relevant seeds), not live page content, so it sits outside the
 agent's prompt-injection surface and needs no filesystem access. It writes an
-**optimization candidate** to `.hover/optimized/<slug>.spec.ts.draft` (never
+**optimization candidate** to `.hover/cache/optimized/<slug>.spec.ts.draft` (never
 `*.spec.ts`, so the test runner can't collect an unreviewed candidate). A human
 promotes or discards it via diff — **the deterministic original is always
 preserved**. Off by default.
 
-### Seed library — extending translation (`.hover/rules/`)
+### Seed library — translation patterns (`BUILTIN_SEEDS`)
 
-The optimization pass generalizes from **seeds**: human-written worked examples
-of "captured steps → the Playwright code they should produce." This is how
-coverage of new multi-step patterns grows **without core changes** — you (or the
-community) drop a JSON file; the pass picks it up as few-shot.
+The optimization pass generalizes from **seeds**: worked examples of "captured
+steps → the Playwright code they should produce", fed to the pass as few-shot.
+They ship inlined as the `BUILTIN_SEEDS` constant in
+[`src/specs/seeds.ts`](src/specs/seeds.ts) (`download`, `file-upload`, `dialog`,
+`network-gated-assertion`, `oauth-popup`); a seed is a `signature` (tool names)
++ a concrete `example` (`steps` → `code`):
 
-A seed lives at `<projectRoot>/.hover/rules/<name>.json` and matches
-[`src/specs/seed.schema.json`](src/specs/seed.schema.json):
-
-```json
+```ts
 {
-  "name": "oauth-popup",
-  "signature": ["browser_click", "browser_tabs:select"],
-  "note": "sign in through a provider popup that opens a new tab",
-  "example": {
-    "steps": [
-      { "tool": "browser_click", "element": "Sign in with Google button" },
-      { "tool": "browser_tabs", "action": "select", "idx": 1 }
+  name: 'oauth-popup',
+  signature: ['browser_click', 'browser_tabs:select'],
+  note: 'sign in through a provider popup that opens a new tab',
+  example: {
+    steps: [
+      { tool: 'browser_click', element: 'Sign in with Google button' },
+      { tool: 'browser_tabs', action: 'select', idx: 1 },
     ],
-    "code": "const [popup] = await Promise.all([\n  context.waitForEvent('page'),\n  page.getByRole('button', { name: 'Sign in with Google' }).click(),\n]);\nawait popup.getByLabel('Email').fill('user@example.com');"
-  }
+    code: `const [popup] = await Promise.all([ ... ]);`,
+  },
 }
 ```
 
@@ -87,43 +85,16 @@ A seed lives at `<projectRoot>/.hover/rules/<name>.json` and matches
   in the spec being optimized. It is **not** exact-matched.
 - **`code`** must obey the same rules as generated specs: semantic selectors, no
   XPath, no `waitForTimeout`.
-- **Built-in seeds** ship in `src/specs/seeds.ts` (`BUILTIN_SEEDS`). The bar to
-  be built-in is high — only **highly certain**, app-agnostic, deterministic
-  patterns qualify (currently just `download`). Semantic / judgement-based
-  optimizations (e.g. *which* feedback text to assert) are not seeds — they're
-  standing instructions in the prompt. Popup is hardcoded in `writeSpec.ts`, not
-  a seed. Speculative or project-specific patterns belong in your own
-  `.hover/rules/`, where the bar is your call.
-
-`readSeeds(projectRoot)` returns built-ins + your `.hover/rules/*.json`
-(malformed files are skipped, not fatal).
-
-## Smoke test
-
-```bash
-# Terminal 1: run basic-app — also spawns a debug Chrome (the example sets
-# `autoLaunchChrome: true`) navigated to http://localhost:5173
-pnpm dev:example:basic-app   # from repo root
-
-# Terminal 2: run the smoke test
-pnpm smoke                   # from repo root, defaults to http://localhost:5173
-```
-
-Need the debug Chrome standalone (no example)? `pnpm smoke:chrome` (or `pnpm exec hover-chrome`).
-
-Override the target or prompt:
-
-```bash
-pnpm smoke http://localhost:5173/ "log in then add a todo named 'verify hover'"
-```
+- Adding a pattern = appending a `SeedRule` to `BUILTIN_SEEDS`. There is no
+  user-authored-seed file mechanism: the catalogue is curated and ships with
+  Hover. Semantic / judgement-based optimizations (e.g. *which* feedback text to
+  assert) are not seeds — they're standing instructions in the prompt.
 
-Environment variables:
+## Exercising the engine
 
-- `HOVER_CDP` — CDP URL (default `http://localhost:9222`)
-- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` → `aider` → `gemini-cli` → `qwen-code` today)
-- `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
+There is no standalone CLI smoke loop — the engine is driven by the VS Code extension. Build + sideload it (`pnpm --filter hover-dev package`), open the Hover chat, and drive any dev server. The extension spawns the isolated debug Chrome on demand and connects to the engine over WS (ports 51789+). Env knobs the engine reads: `HOVER_CDP` (CDP URL, default `http://localhost:9222`), `HOVER_AGENT` (agent id; omit to auto-detect), `HOVER_MODEL` (default `sonnet`).
 
-## Sandboxing (what the smoke test enforces)
+## Sandboxing
 
 The `claude -p` invocation is locked down so Claude can only drive the browser:
 

package/dist/agentDirectives.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Agent system-prompt directives — the static prose fragments appended to the
+ * coding agent's system prompt to shape how it drives the browser and writes its
+ * report. Extracted from service.ts (which assembles them per run) so the prompt
+ * engineering lives in one readable place, separate from the run orchestration.
+ *
+ * Which directives apply when:
+ *   - ZH_OUTPUT          — only when the user's prompt contains CJK.
+ *   - REPORTING / NARRATION / ASK_FORMAT / EXPLORATION_CHECKPOINT — all modes.
+ *   - GROUNDED_ACTUATION (directive + DENY list) — modes whose ModeBehavior has
+ *     groundedActuation = true (Flow, QA). See ./modes.ts.
+ */
+/** CJK-presence test — mirrors voice.js's detectLanguage. Any Han character
+ *  in the prompt flips the agent's prose output to Chinese. */
+export declare const CJK_RE: RegExp;
+/** Appended to the agent's system prompt when the user's prompt contains CJK,
+ *  so the human-facing prose (verification summary / ## Findings / step
+ *  narration) comes back in Chinese — matching how Voice mode picks a Chinese
+ *  TTS voice for the same prompt. Deliberately scoped to PROSE only: the agent
+ *  must still use the page's real (often English) accessible names, labels,
+ *  and selectors when driving the browser. */
+export declare const ZH_OUTPUT_DIRECTIVE: string;
+/**
+ * Grounded-actuation deny list. The Playwright MCP interaction tools take a
+ * free-form `element` description that doesn't round-trip to a replayable
+ * selector (it gets crystallized as a confabulated getByText). So in
+ * grounded-actuation modes we DENY them and route every interaction through the
+ * Hover control MCP, whose role+name/testId/text args come straight from the
+ * snapshot and crystallize 1:1. (Plugin modes keep the Playwright tools — they
+ * explore to capture traffic, not to crystallize browser steps.)
+ */
+export declare const GROUNDED_ACTUATION_DENY: string[];
+export declare const REPORTING_DIRECTIVE: string;
+export declare const NARRATION_DIRECTIVE: string;
+export declare const ASK_FORMAT_DIRECTIVE: string;
+export declare const EXPLORATION_CHECKPOINT_DIRECTIVE: string;
+/** State-reset recon (debt-2 reproducible-state-isolation). Appended for grounded
+ *  modes ONLY when the extension explicitly requests it (run payload `reconReset`)
+ *  — recon clears client state, which would wipe a logged-in session, so it never
+ *  runs unsolicited and never on a plain Flow recording. The agent discovers +
+ *  validates the reset recipe ONCE, then reports it via record_reset_recipe for
+ *  the engine to forward to the environment store. */
+export declare const RECON_DIRECTIVE: string;
+/** QA Testing mode — appended on top of the grounded-actuation directive. Turns
+ *  a directed run into autonomous exploratory testing. (Behavioral effect needs
+ *  live verification; the wiring just appends this when mode === 'qa'.) */
+export declare const QA_EXPLORATION_DIRECTIVE: string;
+/** Appended to the FIRST (functional verify) pass when a penetration-testing
+ *  pass is queued to run right after it. Keeps the two passes from both doing
+ *  security work: the verify pass stays functional-only, all security/vuln work
+ *  is deferred to the dedicated pentest pass. (Only added when QA has pentest on
+ *  AND this is the pre-pentest verify phase — see service.ts `splitting`.) */
+export declare const QA_VERIFY_DEFER_SECURITY_DIRECTIVE: string;
+export declare const GROUNDED_ACTUATION_DIRECTIVE: string;
+//# sourceMappingURL=agentDirectives.d.ts.map

package/dist/agentDirectives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentDirectives.d.ts","sourceRoot":"","sources":["../src/agentDirectives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;+DAC+D;AAC/D,eAAO,MAAM,MAAM,QAAU,CAAC;AAE9B;;;;;8CAK8C;AAC9C,eAAO,MAAM,mBAAmB,QAOM,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,UAgBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,QA0BI,CAAC;AAErC,eAAO,MAAM,mBAAmB,QAK2B,CAAC;AAE5D,eAAO,MAAM,oBAAoB,QAc6B,CAAC;AAE/D,eAAO,MAAM,gCAAgC,QAqB8B,CAAC;AAE5E;;;;;sDAKsD;AACtD,eAAO,MAAM,eAAe,QAcL,CAAC;AAExB;;2EAE2E;AAC3E,eAAO,MAAM,wBAAwB,QAoDmB,CAAC;AAEzD;;;;8EAI8E;AAC9E,eAAO,MAAM,kCAAkC,QASD,CAAC;AAE/C,eAAO,MAAM,4BAA4B,QAmE2C,CAAC"}

package/dist/agentDirectives.js

@@ -0,0 +1,276 @@
+/**
+ * Agent system-prompt directives — the static prose fragments appended to the
+ * coding agent's system prompt to shape how it drives the browser and writes its
+ * report. Extracted from service.ts (which assembles them per run) so the prompt
+ * engineering lives in one readable place, separate from the run orchestration.
+ *
+ * Which directives apply when:
+ *   - ZH_OUTPUT          — only when the user's prompt contains CJK.
+ *   - REPORTING / NARRATION / ASK_FORMAT / EXPLORATION_CHECKPOINT — all modes.
+ *   - GROUNDED_ACTUATION (directive + DENY list) — modes whose ModeBehavior has
+ *     groundedActuation = true (Flow, QA). See ./modes.ts.
+ */
+/** CJK-presence test — mirrors voice.js's detectLanguage. Any Han character
+ *  in the prompt flips the agent's prose output to Chinese. */
+export const CJK_RE = /[一-鿿]/;
+/** Appended to the agent's system prompt when the user's prompt contains CJK,
+ *  so the human-facing prose (verification summary / ## Findings / step
+ *  narration) comes back in Chinese — matching how Voice mode picks a Chinese
+ *  TTS voice for the same prompt. Deliberately scoped to PROSE only: the agent
+ *  must still use the page's real (often English) accessible names, labels,
+ *  and selectors when driving the browser. */
+export const ZH_OUTPUT_DIRECTIVE = '用户使用中文下达指令。请用简体中文撰写【所有】面向用户的文字：最终报告的概述、' +
+    '`## Findings` 里的每一条，以及过程中每一步的简短说明。' +
+    '这一点【贯穿整个过程，不分顺利与否】：当你在排查、卡住、改变思路、或自言自语式地推理时' +
+    '（例如“让我先找一下…”“这个按钮点不到，换个方式”），也必须用中文，绝不要中途切回英文。' +
+    '注意：这只影响写给用户看的叙述文字。操作浏览器时仍要使用页面真实的（通常是英文的）' +
+    '角色名、标签、可访问名称和选择器——不要翻译成中文；严重级别标记' +
+    '（high / medium / low / info）也保持英文。';
+/**
+ * Grounded-actuation deny list. The Playwright MCP interaction tools take a
+ * free-form `element` description that doesn't round-trip to a replayable
+ * selector (it gets crystallized as a confabulated getByText). So in
+ * grounded-actuation modes we DENY them and route every interaction through the
+ * Hover control MCP, whose role+name/testId/text args come straight from the
+ * snapshot and crystallize 1:1. (Plugin modes keep the Playwright tools — they
+ * explore to capture traffic, not to crystallize browser steps.)
+ */
+export const GROUNDED_ACTUATION_DENY = [
+    'mcp__playwright__browser_click',
+    'mcp__playwright__browser_type',
+    'mcp__playwright__browser_fill_form',
+    'mcp__playwright__browser_select_option',
+    // Uploads go through mcp__hovercontrol__upload_file (which crystallizes to a
+    // real filechooser + setFiles); Playwright's browser_file_upload would only
+    // leave an untranslatable optimizable marker.
+    'mcp__playwright__browser_file_upload',
+    // Screenshots go through mcp__hovercontrol__take_screenshot (viewport only).
+    // Playwright's browser_take_screenshot does a fullPage capture by RESIZING the
+    // live window, which fires a window 'resize' the app may react to (lost
+    // transient UI state — e.g. a flipped card snapping back), so the agent never
+    // sees the result of its own action. Deny it; the viewport tool has no such
+    // side effect.
+    'mcp__playwright__browser_take_screenshot',
+];
+export const REPORTING_DIRECTIVE = 'YOUR REPORT IS ABOUT THE APP, NOT THE TOOLING. The final summary and any ' +
+    '## Findings are for the developer of the app under test — write them in plain ' +
+    'product terms about what the APP did: which user flows worked, and real ' +
+    'defects only (wrong validation, broken navigation, lost data, a genuinely ' +
+    'confusing UX). NEVER mention how you drove the page or any Hover/Playwright ' +
+    'mechanics: no tool names (click_control, check_control, getByRole, ' +
+    'browser_snapshot, upload_file, …), no selectors, no "strict mode", "grounded", ' +
+    '"display:none", "filechooser", "tab index", and no internal file names. ' +
+    'Trouble OPERATING a control (a hidden input, a label repeated across groups, a ' +
+    'lingering dialog, any tool quirk) is YOUR technique to work out — do it ' +
+    'silently; it is NOT an app bug and must never appear as a finding. NEVER ' +
+    'propose changes to Hover or its tools, and do not narrate your own environment, ' +
+    'capabilities, or memory. Report only what a user of the app would care about.\n\n' +
+    'WRITE YOUR FINAL REPORT AS PLAIN MARKDOWN — NOT JSON, and NOT wrapped in any ' +
+    'fenced code block. Structure it exactly so:\n' +
+    '• ONE short outcome sentence on the first line.\n' +
+    '• Then a blank line, then concise `- ` bullets for the key things you checked ' +
+    '(one per step / area / flow). Never cram it all into one paragraph.\n' +
+    '• ONLY if you found real defects, add a line `## Findings` followed by one ' +
+    '`- ` bullet per defect, each written as `- **severity** — what happened and why ' +
+    'it matters` (severity = high / medium / low / info; name the endpoint + method ' +
+    'inline when the defect is about a specific API call). No real defects → omit ' +
+    'the Findings section entirely.\n' +
+    'Use real line breaks (a literal newline, NEVER the characters backslash-n). ' +
+    'Do not output JSON, a "summary"/"findings" object, or any ```fenced``` wrapper — ' +
+    'just the Markdown report itself.';
+export const NARRATION_DIRECTIVE = 'NARRATION — As you work, keep each interim status to ONE short present-tense ' +
+    'line stating your immediate intent before you act ("Filling the address ' +
+    'fields", "Now testing an underage date of birth"). Do not write paragraphs ' +
+    'between actions and do not restate what just happened — the steps are already ' +
+    'shown. Save the full wrap-up for the final report only.';
+export const ASK_FORMAT_DIRECTIVE = 'OFFERING CHOICES — if the user\'s request is NOT a concrete instruction you ' +
+    'can act on (a concrete instruction looks like "test the login flow", "log ' +
+    'in", "register an account", "complete checkout", "run the X flow", "fill the ' +
+    'form") — i.e. it is vague, conversational, or just asks you to ask (e.g. ' +
+    '"ask me a question", "what can you do", "test this") — do NOT reply with an ' +
+    'open-ended question like "what would you like me to test?". Instead, LOOK at ' +
+    'the current page first, then PROPOSE 2-4 concrete things you could test on ' +
+    'THIS page. Whenever you offer the user a choice, write the question as a ' +
+    'normal sentence, then put ONLY the options in a fenced block tagged ' +
+    'hover-ask, one per line with a leading "- ":\n' +
+    '```hover-ask\n- first concrete option\n- second concrete option\n```\n' +
+    'Each line becomes a clickable button, so keep options short, specific to this ' +
+    'page, and directly actionable. ALWAYS give concrete options this way — never ' +
+    'a bare open question, a numbered list, or inline "A or B".';
+export const EXPLORATION_CHECKPOINT_DIRECTIVE = 'OPEN-ENDED TASKS — CHECK IN BEFORE YOU STOP. When the request is vague or ' +
+    'unscoped (e.g. just "test", "test this", "check the app") YOU chose what to ' +
+    'cover, so you do not actually know when the user considers it done. If you ' +
+    'reach a natural stopping point with MATERIAL scope still untested — whole ' +
+    'sections / flows / steps you noticed but did not exercise — do NOT end the ' +
+    'run on your own. First call mcp__hovercontrol__ask_user: briefly say what ' +
+    'you have covered and what remains, and offer concrete options such as ' +
+    'continuing with a specific untested part, continuing through everything ' +
+    'left, or stopping here. Then act on the answer. Ask at a genuine checkpoint ' +
+    '(a finished chunk), not after every step, and ask once per checkpoint — do ' +
+    'not loop. Skip this entirely when the task was explicit and bounded (you ' +
+    'finished exactly what was asked) or when the user already said to stop / ' +
+    'that it is enough — then just finish and report. ' +
+    'IN-APP LIMITS ARE NOT BLOCKERS. When an EXPLICIT task is stopped by something ' +
+    'you can change inside the app — a daily quota reached, a feature behind a ' +
+    'setting/toggle, a smaller default that a control can raise — do the in-app ' +
+    'workaround yourself (open settings, raise the limit, flip the toggle) and ' +
+    'COMPLETE the task. Do NOT stop to offer a menu of choices. Only a truly ' +
+    'EXTERNAL blocker (missing credentials, a file you cannot obtain) justifies ' +
+    'asking; and if the explicit task is already satisfied, just conclude and ' +
+    'report it — never end an explicit task with a "what next?" option list.';
+/** State-reset recon (debt-2 reproducible-state-isolation). Appended for grounded
+ *  modes ONLY when the extension explicitly requests it (run payload `reconReset`)
+ *  — recon clears client state, which would wipe a logged-in session, so it never
+ *  runs unsolicited and never on a plain Flow recording. The agent discovers +
+ *  validates the reset recipe ONCE, then reports it via record_reset_recipe for
+ *  the engine to forward to the environment store. */
+export const RECON_DIRECTIVE = 'STATE-RESET RECON — do this ONCE, before you start testing. For saved tests to ' +
+    'be reproducible, Hover needs to know how to reset this app to a clean start. ' +
+    '(1) Note which controls/screens reflect the app\'s stored state. (2) Call ' +
+    'mcp__hovercontrol__clear_client_state, then look at the page after it reloads. ' +
+    '(3) Decide: did the app return to its INITIAL state (its state is client-side ' +
+    '— Tier 1) or did your prior progress come BACK (it is re-hydrated from a ' +
+    'backend / your logged-in account — Tier 2)? Prefer a FULL clear (clear ' +
+    'everything) — if that logged you out and the app needs auth, log back in ' +
+    'using the test account credentials provided for this run, then continue. Only ' +
+    'fall back to naming specific storageKeys if a full clear breaks something you ' +
+    'cannot re-establish. (4) Report it with mcp__hovercontrol__record_reset_recipe: ' +
+    'tier 1 (clear-all, the default; or with storageKeys only if you had to scope), ' +
+    'or tier 2 (not client-resettable). Do this recon only once, at the start; ' +
+    'then test normally.';
+/** QA Testing mode — appended on top of the grounded-actuation directive. Turns
+ *  a directed run into autonomous exploratory testing. (Behavioral effect needs
+ *  live verification; the wiring just appends this when mode === 'qa'.) */
+export const QA_EXPLORATION_DIRECTIVE = 'QA TESTING MODE — explore, don\'t just follow. YOU ARE A TESTER: your only job ' +
+    'is to TEST this app. Never merely read out, describe, summarize, or narrate the ' +
+    'page — always EXERCISE the controls (click, fill, submit, toggle, navigate), ' +
+    'try negative / boundary inputs, and verify behavior to find defects; describing ' +
+    'the page is never an acceptable result on its own. A vague or unscoped request ' +
+    '("test the app", "test this") MEANS "explore the whole app" — do NOT open with ' +
+    'an ask_user or a list of choices, just START testing what you can see (even on ' +
+    'a login/landing page: empty submit, bad password, invalid input first). Ask the ' +
+    'user (ask_user) ONLY when EXTERNALLY blocked (credentials / a file you cannot ' +
+    'get) or for a decisive business judgment you cannot resolve — never just to ' +
+    'pick scope. An IN-APP limit you can change yourself (a daily quota, a ' +
+    'setting/toggle, a raisable default) is NOT "blocked": adjust it in the app and ' +
+    'finish the task — do not stop to ask. Go BEYOND any single instruction: ' +
+    'systematically exercise every reachable control and state of the app to find ' +
+    'real defects. Maintain a mental frontier of untried controls; try each; do NOT ' +
+    'repeat a state you have already explored. Do NEGATIVE testing too — empty / ' +
+    'invalid / boundary / special-character inputs on forms — to surface validation ' +
+    'gaps, not just happy paths. Flag what you find as Findings (severity high / ' +
+    'medium / low / info) in your report; DO NOT crystallize a spec unless the user ' +
+    'asks. Treat clearly DESTRUCTIVE / irreversible actions (delete account, submit ' +
+    'payment, send email, bulk delete) carefully: confirm with the user once per ' +
+    'action-type before doing them, otherwise flag-and-skip. Stay on the app under ' +
+    'test (never navigate to external origins). Stop when the frontier is exhausted ' +
+    'or you hit the run budget; then WRITE THE FINDINGS REPORT AND END THE RUN. ' +
+    'Your turn ENDS with that report — do NOT close by asking whether to test more ' +
+    'or offering a menu of further areas (no "shall I also test X?" question, no ' +
+    'ask_user, no closing option list). Anything you did not cover belongs in the ' +
+    'report\'s `## Coverage` → `Not covered:` list, never in a closing question.\n' +
+    'REPORT COVERAGE: end your report with a `## Coverage` section — first a short ' +
+    '`Tested:` list of the main areas / flows / controls you DID exercise, then a ' +
+    '`Not covered:` list of anything you saw but did NOT test (and a few words on ' +
+    'why: out of scope, blocked, ran out of budget, destructive-and-skipped). This ' +
+    'tells the developer exactly what is verified vs still open — be honest about ' +
+    'gaps, do not claim coverage you did not do.\n' +
+    'CAPTURE CLEAN FLOWS: as you exercise the app, whenever you complete a coherent ' +
+    'end-to-end flow worth keeping as a regression test (e.g. "Log in", "Add item ' +
+    'to cart", "Submit the registration form"), call record_candidate with just a ' +
+    'short imperative name — IN ENGLISH (it becomes the spec\'s filename + test ' +
+    'name, even though your report prose is in another language). You do NOT pass ' +
+    'steps: Hover automatically captures the successful click / fill / select / ' +
+    'check / upload actions you did since your last record_candidate, so call it ' +
+    'the MOMENT you finish each distinct flow — before starting the next one or ' +
+    'doing unrelated exploration — so its captured steps are exactly that flow. ' +
+    '(record_candidate only OFFERS the user a one-click "Crystallize" later — it ' +
+    'does not write a spec; you never write one yourself.)\n' +
+    'REMEMBER WHAT YOU LEARN: when you confirm a durable business rule about this ' +
+    'app — an expected behavior, a validation rule, an access policy, or the answer ' +
+    'to a "is this a bug or by-design?" you asked the user — call record_fact to ' +
+    'persist it, so neither you nor a future run re-asks it. State it as a clean ' +
+    'self-contained rule. RULES ONLY — never record secrets, passwords, tokens, or ' +
+    'personal data. (Anything in KNOWN BUSINESS KNOWLEDGE above is already ' +
+    'remembered — treat it as settled, do not re-ask it.)';
+/** Appended to the FIRST (functional verify) pass when a penetration-testing
+ *  pass is queued to run right after it. Keeps the two passes from both doing
+ *  security work: the verify pass stays functional-only, all security/vuln work
+ *  is deferred to the dedicated pentest pass. (Only added when QA has pentest on
+ *  AND this is the pre-pentest verify phase — see service.ts `splitting`.) */
+export const QA_VERIFY_DEFER_SECURITY_DIRECTIVE = 'SECURITY IS A SEPARATE LATER PASS — NOT THIS ONE. A dedicated penetration-' +
+    'testing pass runs right after this one and owns ALL security / vulnerability ' +
+    'work (auth / access control, IDOR, injection, secrets, endpoint abuse, ' +
+    'attacking the backend). In THIS pass do FUNCTIONAL testing ONLY: verify the ' +
+    'app WORKS — flows, forms, navigation, validation, state — and report only ' +
+    'functional defects. Even if the request mentions security, do NOT audit ' +
+    'security, do NOT read source looking for vulnerabilities, and do NOT report ' +
+    'security findings here. Leave every security concern to the pentest pass so ' +
+    'the two passes never duplicate each other.';
+export const GROUNDED_ACTUATION_DIRECTIVE = 'INTERACTING WITH THE PAGE — IMPORTANT: You interact with the page ONLY through ' +
+    'the Hover control tools: mcp__hovercontrol__click_control, fill_control, ' +
+    'select_control, check_control. You ALREADY HAVE FULL PERMISSION to use them — ' +
+    'NEVER ask the user to grant permissions, never stop to request access, never ' +
+    'narrate a permission request. Just call the tools and keep going until the task ' +
+    'is done. Each takes the element\'s accessible role + name exactly as shown in ' +
+    'the latest browser_snapshot (fall back to its testId, then its real visible ' +
+    'text, only when there is no clean role+name). Workflow: browser_snapshot to read ' +
+    'the real roles + names, then call the matching *_control tool for each field / ' +
+    'option / button, snapshotting again after navigation. (The Playwright ' +
+    'interaction tools are disabled — the control tools replace them, so saved ' +
+    'selectors stay grounded.) browser_navigate / browser_snapshot / ' +
+    'browser_wait_for / browser_tabs / browser_press_key remain available.\n\n' +
+    'WHEN A TARGET ISN\'T UNIQUELY ADDRESSABLE — narrow it, don\'t give up. Two ' +
+    'common reasons and the one principle that solves both: (a) its accessible ' +
+    'name/label repeats elsewhere on the page, or (b) its real input is hidden so ' +
+    'it isn\'t in the snapshot as a control and getByRole/check_control would time ' +
+    'out — in which case act on the element you CAN see (its visible label text). ' +
+    'Principle: scope to the smallest container in the snapshot that uniquely ' +
+    'holds your target by passing `within` = that container\'s role + accessible ' +
+    'name, then identify the target inside it (by text when its own name isn\'t ' +
+    'unique). To choose the right container and approach, read the snapshot tree, ' +
+    'take a mcp__hovercontrol__take_screenshot to SEE the real visual layout (the ' +
+    'accessibility tree omits display:none inputs, canvas, and can\'t convey ' +
+    'spatial grouping — the screenshot shows what the user actually sees), and ' +
+    'read the component source if you\'re unsure how it\'s built. take_screenshot ' +
+    'captures the CURRENT VIEWPORT only and never resizes the page — use it, NOT ' +
+    'Playwright\'s browser_take_screenshot (disabled here: its fullPage capture ' +
+    'resizes the live window, which can reset transient app state so you\'d never ' +
+    'see the result of your own action). To see below the fold, scroll first, then ' +
+    'take_screenshot. For FINDING elements, rely on browser_snapshot — its tree ' +
+    'covers the whole page (off-screen included), so a viewport shot never makes ' +
+    'you miss a control. Perceive with the screenshot; ACT through the grounded ' +
+    '*_control tools. This is routine; work it ' +
+    'out and keep going rather than reporting it as a limitation.\n\n' +
+    'WHEN YOU ARE TRULY BLOCKED — ASK VIA THE CARD, DON\'T DEAD-END: only after ' +
+    'you\'ve tried to work it out yourself (re-read the snapshot, scope with ' +
+    '`within`, read the component source), if something genuinely needs the user — ' +
+    'credentials you don\'t have, a file only they can provide, a decision only ' +
+    'they can make — call mcp__hovercontrol__ask_user. Never surface that as a ' +
+    'plain chat question and end your turn: the user can only answer an ask_user ' +
+    'card, so a bare question dead-ends the run. (WHEN to ask vs. keep going on ' +
+    'your own — and how to start and stop — is governed by the mode directive ' +
+    'below; this paragraph only fixes HOW to ask.) Engine helper: ' +
+    'mcp__hovercontrol__upload_file (path or placeholder) sets a file on an upload ' +
+    'control, since you have no filesystem access yourself.\n\n' +
+    'VOLATILE CONTENT — FLAG IT, DON\'T FREEZE IT. Two kinds of text live on a ' +
+    'page: FIXED UI labels the app ships (button / field / menu text like ' +
+    '"Submit", "Email", "Add to cart") and APP DATA the page draws from its ' +
+    'content or state (a word on a card, a product or item title, a person\'s ' +
+    'name, a generated id, an order number, a date, a price, a count). Whenever the ' +
+    'name / text you ground on is APP DATA — NOT a fixed label — you MUST pass ' +
+    'dynamic:true AND anchor on something stable (a testId, the `within` container, ' +
+    'or just the role), never the changing text itself. Quick test before every ' +
+    'click/assert: "would this EXACT text be on the page on a fresh run with ' +
+    'different data?" If no → it is dynamic. (Example: a flashcard heading showing ' +
+    'the current word is APP DATA — click_control({ role: "heading", dynamic: true ' +
+    '}), NOT { name: "bathroom" }.) A frozen data value makes the saved test pass ' +
+    'once and fail every run after.\n\n' +
+    'CAPTURE THE INVARIANT — assert what the flow PROVES, not this run\'s value: ' +
+    'when a flow reaches a state worth verifying, call ' +
+    'mcp__hovercontrol__assert_visible, and capture at least the key one before ' +
+    'record_candidate. Assert the CONTRACT (a result appears, a confirmation shows, ' +
+    'the expected number of items render). When the proof is that some APP DATA ' +
+    'showed up (a word, a row, a result), assert THAT element with dynamic:true + ' +
+    'matcher \'non-empty\' or \'text-contains\' — NOT a fixed button sitting next to ' +
+    'it, and NOT the literal value. Use \'text-exact\' only for genuinely fixed text.';

package/dist/engine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * In-process engine surface for the `@hover-dev/mcp` server (and any other
+ * standalone consumer). The MCP server drives the debug Chrome directly via
+ * `playwright-core` and buffers grounded steps, then crystallizes them with
+ * `writeSpec` — no WebSocket service, no agent spawning. This barrel re-exports
+ * exactly those building blocks.
+ *
+ * (The old staged-engine surface — `runSession`, the WS `service`, the
+ * Playwright-MCP config in `resolveMcpConfig` / `buildGroundedMcpConfig`, and
+ * the `mcp/actuateServer` + `mcp/sourceServer` relays — has been removed. The
+ * MCP-first path doesn't spawn Playwright's MCP; it actuates through
+ * `playwright-core` and `groundedLocate` below, which is what keeps
+ * record == replay.)
+ */
+export { writeSpec } from './specs/writeSpec.js';
+export type { WriteSpecOptions, WriteSpecResult, Redaction } from './specs/writeSpec.js';
+export type { SkillStep } from './specs/specStep.js';
+export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
+export type { ReplayResult, ReplayFailure, ReplayStep, GroundedTarget } from './specs/replayGrounded.js';
+export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';
+export type { LaunchOptions, LaunchResult } from './playwright/launchChrome.js';
+export { GROUNDED_ACTUATION_DENY, GROUNDED_ACTUATION_DIRECTIVE } from './agentDirectives.js';
+export { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+export type { BusinessFact } from './memory/businessMemory.js';
+export { RECON_DIRECTIVE, QA_EXPLORATION_DIRECTIVE } from './agentDirectives.js';
+export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';
+export type { QaIntensity, QaIntensitySpec } from './qa/intensity.js';
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGzG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/engine.js

@@ -0,0 +1,27 @@
+/**
+ * In-process engine surface for the `@hover-dev/mcp` server (and any other
+ * standalone consumer). The MCP server drives the debug Chrome directly via
+ * `playwright-core` and buffers grounded steps, then crystallizes them with
+ * `writeSpec` — no WebSocket service, no agent spawning. This barrel re-exports
+ * exactly those building blocks.
+ *
+ * (The old staged-engine surface — `runSession`, the WS `service`, the
+ * Playwright-MCP config in `resolveMcpConfig` / `buildGroundedMcpConfig`, and
+ * the `mcp/actuateServer` + `mcp/sourceServer` relays — has been removed. The
+ * MCP-first path doesn't spawn Playwright's MCP; it actuates through
+ * `playwright-core` and `groundedLocate` below, which is what keeps
+ * record == replay.)
+ */
+// ── crystallization + grounded replay ────────────────────────────────────────
+export { writeSpec } from './specs/writeSpec.js';
+// Creation-verification: replay a flow's grounded steps over CDP (no playwright test).
+export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
+// ── debug-Chrome lifecycle ───────────────────────────────────────────────────
+export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';
+// ── grounded-actuation knobs (the deny-list + directive the agent runs under) ─
+export { GROUNDED_ACTUATION_DENY, GROUNDED_ACTUATION_DIRECTIVE } from './agentDirectives.js';
+// ── business memory (ask → remember loop) ────────────────────────────────────
+export { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+// ── autonomous-exploration directives + intensity (the test_app workflow) ─────
+export { RECON_DIRECTIVE, QA_EXPLORATION_DIRECTIVE } from './agentDirectives.js';
+export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';

package/dist/memory/businessMemory.d.ts

@@ -0,0 +1,29 @@
+/** A learned business fact about the app under test. */
+export interface BusinessFact {
+    /** kebab-case slug; also the filename stem. */
+    name: string;
+    /** One-line summary used for recall relevance + the index hook. */
+    description: string;
+    /** What kind of knowledge this is. */
+    type: 'business-rule' | 'expected-behavior' | 'validation' | 'access-policy';
+    /** The fact itself (markdown). */
+    body: string;
+}
+export declare function memoryDir(devRoot: string): string;
+/** kebab-case a title into a safe filename stem. */
+export declare function slugify(s: string): string;
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export declare function loadMemory(devRoot: string): Promise<BusinessFact[]>;
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export declare function formatMemoryForPrompt(facts: BusinessFact[]): string;
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export declare function writeFact(devRoot: string, fact: BusinessFact): Promise<{
+    path: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=businessMemory.d.ts.map

package/dist/memory/businessMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"businessMemory.d.ts","sourceRoot":"","sources":["../../src/memory/businessMemory.ts"],"names":[],"mappings":"AAwBA,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,IAAI,EAAE,eAAe,GAAG,mBAAmB,GAAG,YAAY,GAAG,eAAe,CAAC;IAC7E,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzC;AAsBD;6EAC6E;AAC7E,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAkBzE;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAQnE;AAED;;0EAE0E;AAC1E,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAc/C"}