@hover-dev/core 0.19.0 → 0.21.0

package/dist/engine.d.ts

@@ -19,12 +19,12 @@ export { writeApiSpec } from './specs/writeApiSpec.js';
 export type { ApiCheck, WriteApiSpecOptions, WriteApiSpecResult } from './specs/writeApiSpec.js';
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
 export type { ReplayResult, ReplayFailure, ReplayStep, GroundedTarget } from './specs/replayGrounded.js';
+export { readSidecar } from './specs/sidecar.js';
+export type { SpecSidecar } from './specs/sidecar.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

@@ -1 +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,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,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"}
+{"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,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,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;AAEzG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,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,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

@@ -16,14 +16,13 @@
 export { writeSpec } from './specs/writeSpec.js';
 // API-layer crystallizer — observed/replayed requests → *.api-test.spec.ts.
 export { writeApiSpec } from './specs/writeApiSpec.js';
-// Creation-verification: replay a flow's grounded steps over CDP (no playwright test).
+// Creation-verification + self-heal: replay a flow's grounded steps over CDP (no playwright test).
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
+// Spec sidecar (recorded grounded steps) — read by self-heal to replay a saved spec.
+export { readSidecar } from './specs/sidecar.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';
+// ── QA intensity (step budget; parked until wired into the workflow) ──────────
 export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';

package/dist/sessions/sessions.d.ts

@@ -81,10 +81,10 @@ export interface SessionRecord {
  * "writes out" the call (a known tool-calling glitch, common at end-of-turn /
  * budget cap) and the parser renders it verbatim into the report + Done card.
  * This keeps user-facing prose about the APP, not Hover's tooling
- * (REPORTING_DIRECTIVE). Defensive + total: any agent can trip this.
+ * (the markdown-report contract). Defensive + total: any agent can trip this.
  */
 export declare function stripToolCallNoise(text: string): string;
-/** Markdown-forced: the agent emits a plain-markdown report (REPORTING_DIRECTIVE)
+/** Markdown-forced: the agent emits a plain-markdown report (the markdown-report contract)
  *  — ONE outcome line, `- ` bullets, and an optional `## Findings` section with
  *  `- **severity** — text` items. Parse the summary + findings from that markdown
  *  only; a stray ```json block (a non-compliant agent) is stripped, never parsed

package/dist/sessions/sessions.js

@@ -19,7 +19,7 @@ function deEsc(s) {
     return s.replace(/\\r\\n/g, '\n').replace(/\\n/g, '\n').replace(/\\t/g, '  ');
 }
 /** Defensive leak-guard, NOT a parse path. The agent is directed to emit a
- *  plain-markdown report (REPORTING_DIRECTIVE) — no JSON. A non-compliant agent
+ *  plain-markdown report (the markdown-report contract) — no JSON. A non-compliant agent
  *  that still wraps its report in a ```json block would otherwise leak raw JSON
  *  to the UI, so strip it: recover the `summary` field as prose when present
  *  (tolerating unescaped quotes by matching up to `","findings"`), else drop the
@@ -41,7 +41,7 @@ function stripJsonArtifact(summary) {
  * "writes out" the call (a known tool-calling glitch, common at end-of-turn /
  * budget cap) and the parser renders it verbatim into the report + Done card.
  * This keeps user-facing prose about the APP, not Hover's tooling
- * (REPORTING_DIRECTIVE). Defensive + total: any agent can trip this.
+ * (the markdown-report contract). Defensive + total: any agent can trip this.
  */
 export function stripToolCallNoise(text) {
     return text
@@ -53,7 +53,7 @@ export function stripToolCallNoise(text) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-/** Markdown-forced: the agent emits a plain-markdown report (REPORTING_DIRECTIVE)
+/** Markdown-forced: the agent emits a plain-markdown report (the markdown-report contract)
  *  — ONE outcome line, `- ` bullets, and an optional `## Findings` section with
  *  `- **severity** — text` items. Parse the summary + findings from that markdown
  *  only; a stray ```json block (a non-compliant agent) is stripped, never parsed

package/dist/specs/humanSteps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwDxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}
+{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAoExE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}

package/dist/specs/humanSteps.js

@@ -40,6 +40,18 @@ export function humanStep(tool, rawInput) {
             const key = String(input.key ?? '');
             return key ? `Press ${key}` : null;
         }
+        // Grounded control tools (MCP-first) — the target is role+name/testId/text
+        // ON the input itself, not an `element` string.
+        case 'click_control':
+            return `Click ${describeGrounded(input)}`;
+        case 'fill_control':
+            return `Fill ${describeGrounded(input)} with ${quote(String(input.value ?? ''))}`;
+        case 'select_control':
+            return `Select ${quote(String(input.value ?? ''))} in ${describeGrounded(input)}`;
+        case 'check_control':
+            return `${input.checked === false ? 'Uncheck' : 'Check'} ${describeGrounded(input)}`;
+        case 'assert_visible':
+            return `Expect ${describeGrounded(input)} to be visible`;
         // Diagnostic / read-only — same skip list as writeSpec.translateStep.
         case 'browser_wait_for':
         case 'browser_tabs':
@@ -91,6 +103,23 @@ function describe(raw) {
     const s = String(raw ?? '').trim();
     return s.length > 0 ? s : 'the target element';
 }
+/** Human phrase for a GROUNDED target ({ role, name, testId, text }) — the shape
+ *  the *_control tools carry, vs the old browser_* tools' `element` string. */
+function describeGrounded(input) {
+    const role = typeof input.role === 'string' ? input.role : '';
+    const name = typeof input.name === 'string' ? input.name : '';
+    const testId = typeof input.testId === 'string' ? input.testId : '';
+    const text = typeof input.text === 'string' ? input.text : '';
+    if (role && name)
+        return `${role} "${name}"`;
+    if (name)
+        return `"${name}"`;
+    if (testId)
+        return `testId "${testId}"`;
+    if (text)
+        return `"${text}"`;
+    return 'the target element';
+}
 /** Wrap in double-quotes for prose; escape internal quotes. A redacted
  *  credential (stored as a `process.env.X …` expression) shows as the masked
  *  `$X` instead — the prose, like the code, never reveals the secret. */

package/dist/specs/writeSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AA+mBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AAonBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}

package/dist/specs/writeSpec.js

@@ -201,13 +201,17 @@ async function writeOneSpec(opts, slug, displayName, rawSteps) {
     const envVars = (opts.redactions ?? []).map(r => r.envVar);
     const detectedPrefix = authPrefixLength(cleanActions, envVars);
     const userConfigName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(opts.devRoot, n)));
+    // A config Hover scaffolded earlier this run (e.g. a non-login spec wrote a
+    // plain one first) is OURS to upgrade — treat it like "no user config", not a
+    // hands-off user file. ensurePlaywrightConfig adds the setup project to it.
+    const ownScaffold = !!userConfigName && readFileSync(join(opts.devRoot, userConfigName), 'utf-8').includes(SCAFFOLD_MARKER);
     // Already opted in: auth.setup.ts exists from a prior approval (and the config
     // already registers it), so engage AUTOMATICALLY — don't re-ask or re-edit.
     const authSetupExists = existsSync(join(dir, 'auth.setup.ts'));
     // Engage the fixture when a login is detected AND we can register the setup
-    // project: we scaffold the config (no user config), the caller approved editing
-    // it (opts.authFixture, Stage 4), or the fixture was already set up earlier.
-    const engage = detectedPrefix > 0 && (!userConfigName || opts.authFixture === true || authSetupExists);
+    // project: we scaffold/own the config, the caller approved editing a user
+    // config (opts.authFixture, Stage 4), or the fixture was already set up earlier.
+    const engage = detectedPrefix > 0 && (!userConfigName || ownScaffold || opts.authFixture === true || authSetupExists);
     const authPrefix = engage ? detectedPrefix : 0;
     const authFile = engage ? AUTH_STATE_FILE : undefined;
     let authFixtureOffer;
@@ -1005,28 +1009,24 @@ async function ensureResetStateHelper(devRoot, keys) {
     ].join('\n');
     await writeFile(join(dir, 'resetState.ts'), source, 'utf-8');
 }
-async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
-    if (PLAYWRIGHT_CONFIG_NAMES.some(n => existsSync(join(devRoot, n))))
-        return;
-    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
-    if (!origin)
-        return;
-    // Auth-as-fixture: register a `setup` project (matches auth.setup.ts) that the
-    // main project depends on, so login runs ONCE before the specs. Only emitted
-    // when scaffolding our own config (we never touch a user's existing one).
+const SCAFFOLD_MARKER = 'Scaffolded by Hover';
+/** The scaffolded config source. When `authFile` is set, a `setup` project runs
+ *  auth.setup.ts ONCE and the main `chromium` project reuses the saved
+ *  storageState — so EVERY spec starts authenticated, not just the login flow. */
+function renderScaffoldConfig(origin, authFile) {
     const projects = authFile
         ? [
             `  projects: [`,
             `    { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },`,
-            `    { name: 'chromium', dependencies: ['setup'] },`,
+            `    { name: 'chromium', dependencies: ['setup'], use: { storageState: ${JSON.stringify(authFile)} } },`,
             `  ],`,
         ]
         : [];
-    const source = [
+    return [
         `import { defineConfig } from '@playwright/test';`,
         ``,
         `/**`,
-        ` * Scaffolded by Hover so crystallized specs (which use relative URLs like`,
+        ` * ${SCAFFOLD_MARKER} so crystallized specs (which use relative URLs like`,
         ` * page.goto("/")) resolve against a base. Override HOVER_BASE_URL in CI to`,
         ` * point the same specs at staging/prod.`,
         ` */`,
@@ -1039,7 +1039,50 @@ async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
         `});`,
         ``,
     ].join('\n');
-    await writeFile(join(devRoot, 'playwright.config.ts'), source, 'utf-8');
+}
+async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
+    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
+    if (!origin)
+        return;
+    const existingName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(devRoot, n)));
+    if (existingName) {
+        // A config already exists. Only ever UPGRADE our OWN scaffold — and only to
+        // add the auth `setup` project when a login was just lifted (authFile) and
+        // it isn't there yet. This makes auth order-independent: whichever spec in
+        // the run triggers auth-fixture upgrades the config, even if a non-login
+        // spec scaffolded a plain config first. A user's own config is never touched
+        // (that's the Stage-4 approval flow via authFixtureOffer).
+        if (!authFile)
+            return;
+        try {
+            const cur = readFileSync(join(devRoot, existingName), 'utf-8');
+            if (!cur.includes(SCAFFOLD_MARKER) || cur.includes(`name: 'setup'`))
+                return;
+            await writeFile(join(devRoot, existingName), renderScaffoldConfig(origin, authFile), 'utf-8');
+        }
+        catch { /* upgrade is best-effort */ }
+        return;
+    }
+    await writeFile(join(devRoot, 'playwright.config.ts'), renderScaffoldConfig(origin, authFile), 'utf-8');
+    await ensurePlaywrightDep(devRoot);
+}
+/** When Hover scaffolds the config it also ensures `@playwright/test` is a
+ *  devDependency — otherwise `npx playwright test` can't run the specs locally.
+ *  Best-effort + idempotent: skips if already present (either dep list) or if
+ *  there's no package.json. Reformats to 2-space JSON (the npm norm). */
+const PLAYWRIGHT_TEST_RANGE = '^1.50.0';
+async function ensurePlaywrightDep(devRoot) {
+    const pkgPath = join(devRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.dependencies?.['@playwright/test'] || pkg.devDependencies?.['@playwright/test'])
+            return;
+        pkg.devDependencies = { ...(pkg.devDependencies ?? {}), '@playwright/test': PLAYWRIGHT_TEST_RANGE };
+        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* best-effort — never break Save */ }
 }
 function stripBaseUrl(url) {
     // http://localhost:5173/checkout → /checkout, http://localhost:5173/ → /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",

package/dist/agentDirectives.d.ts

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,276 +0,0 @@
-/**
- * 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/qa/candidates.d.ts

@@ -1,32 +0,0 @@
-/**
- * QA candidate-flow finalization.
- *
- * During a QA run the agent calls `record_candidate(name)` right after it
- * completes a coherent flow; the hover-control MCP captures the actual grounded
- * actuation steps since the previous marker and sends them along — so a
- * candidate already carries its real, replayable SkillSteps (no fragile
- * step-number citing). This module just validates + de-dupes them before they
- * become one-click "Crystallize" cards.
- *
- * Pure + side-effect-free so it can be unit-tested without a live run.
- */
-import type { SkillStep } from '../specs/specStep.js';
-/** What the agent recorded: a flow name + the real steps Hover captured for it. */
-export interface RecordedCandidate {
-    name: string;
-    description?: string;
-    steps: SkillStep[];
-}
-/** A candidate ready to crystallize. */
-export interface ResolvedCandidate {
-    name: string;
-    description?: string;
-    steps: SkillStep[];
-    stepCount: number;
-}
-/**
- * Validate + de-dupe recorded candidates: drop ones with no name or no steps,
- * collapse identical repeats (same name + same step count), and stamp stepCount.
- */
-export declare function finalizeCandidates(candidates: readonly RecordedCandidate[]): ResolvedCandidate[];
-//# sourceMappingURL=candidates.d.ts.map

package/dist/qa/candidates.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../src/qa/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAahG"}

package/dist/qa/candidates.js

@@ -1,20 +0,0 @@
-/**
- * Validate + de-dupe recorded candidates: drop ones with no name or no steps,
- * collapse identical repeats (same name + same step count), and stamp stepCount.
- */
-export function finalizeCandidates(candidates) {
-    const out = [];
-    const seen = new Set();
-    for (const c of candidates) {
-        const name = c.name?.trim();
-        const steps = Array.isArray(c.steps) ? c.steps.filter((s) => s && s.kind === 'step') : [];
-        if (!name || !steps.length)
-            continue;
-        const key = `${name}|${steps.length}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push({ name, description: c.description?.trim() || undefined, steps, stepCount: steps.length });
-    }
-    return out;
-}

package/dist/qa/qaReport.d.ts

@@ -1,19 +0,0 @@
-import type { SessionFinding } from '../sessions/sessions.js';
-export interface QaReportInput {
-    prompt: string;
-    summary: string;
-    findings: SessionFinding[];
-    endedAt: string;
-    targetUrl?: string;
-}
-/** Render the report Markdown (pure — exported for testing). */
-export declare function renderQaReport(input: QaReportInput): string;
-/** Write the QA report into the run's folder as `report.md`. Each run (incl.
- *  each phase of a two-pass run) has its own folder, so there's no name
- *  collision. NEVER throws; returns the path or an error string. */
-export declare function writeQaReport(runDirPath: string, input: QaReportInput): Promise<{
-    path: string;
-} | {
-    error: string;
-}>;
-//# sourceMappingURL=qaReport.d.ts.map

package/dist/qa/qaReport.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"qaReport.d.ts","sourceRoot":"","sources":["../../src/qa/qaReport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAkB3D;AAED;;oEAEoE;AACpE,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAS/C"}

package/dist/qa/qaReport.js

@@ -1,50 +0,0 @@
-/**
- * QA report artifact — the durable, human-readable output of a QA Testing run.
- *
- * QA is report-first: a run produces findings (rendered live in the chat's
- * Findings card via the normal parseFindings pipeline) AND this persistent
- * Markdown report under `<devRoot>/.hover/qa-reports/<slug>.md`, mirroring
- * pentest's report file. Latest-run-wins per prompt slug (the session ledger
- * keeps the full history; this is the readable artifact).
- *
- * Best-effort by contract: a report-write failure must NEVER break a run or the
- * ledger (same rule as the session ledger + business memory).
- */
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-/** Render the report Markdown (pure — exported for testing). */
-export function renderQaReport(input) {
-    const { prompt, summary, findings, endedAt, targetUrl } = input;
-    const meta = [endedAt, targetUrl, `${findings.length} finding${findings.length === 1 ? '' : 's'}`]
-        .filter(Boolean)
-        .join(' · ');
-    const body = [`# QA report — ${prompt.trim()}`, '', `_${meta}_`];
-    if (summary.trim())
-        body.push('', summary.trim());
-    body.push('', '## Findings');
-    if (findings.length) {
-        for (const f of findings) {
-            const sev = (f.severity || 'note').trim();
-            const head = f.title && f.title !== f.text ? `${f.title} — ` : '';
-            body.push(`- **${sev}** — ${head}${f.text.trim()}`);
-        }
-    }
-    else {
-        body.push('_No issues found._');
-    }
-    return body.join('\n') + '\n';
-}
-/** Write the QA report into the run's folder as `report.md`. Each run (incl.
- *  each phase of a two-pass run) has its own folder, so there's no name
- *  collision. NEVER throws; returns the path or an error string. */
-export async function writeQaReport(runDirPath, input) {
-    try {
-        await mkdir(runDirPath, { recursive: true });
-        const path = join(runDirPath, 'report.md');
-        await writeFile(path, renderQaReport(input), 'utf-8');
-        return { path };
-    }
-    catch (err) {
-        return { error: err instanceof Error ? err.message : String(err) };
-    }
-}