@hover-dev/core 0.21.0 → 0.23.0

package/dist/engine.d.ts

@@ -15,15 +15,25 @@
 export { writeSpec } from './specs/writeSpec.js';
 export type { WriteSpecOptions, WriteSpecResult, Redaction } from './specs/writeSpec.js';
 export type { SkillStep } from './specs/specStep.js';
+export { reRenderSpec } from './specs/writeSpec.js';
 export { writeApiSpec } from './specs/writeApiSpec.js';
 export type { ApiCheck, WriteApiSpecOptions, WriteApiSpecResult } from './specs/writeApiSpec.js';
+export { buildOptimizeBrief, saveOptimizedCandidate, OptimizeError } from './specs/optimizeSpec.js';
+export type { OptimizeResult } from './specs/optimizeSpec.js';
+export { lintWiki, parseRunStatuses } from './specs/lintWiki.js';
+export type { LintResult, LintFinding, LintKind, LintSeverity } from './specs/lintWiki.js';
+export { parseBusinessMap } from './specs/businessMap.js';
+export type { BusinessMapGraph, MapNode, MapEdge } from './specs/businessMap.js';
+export { extractPageObjects, detectExtractableFlows } from './specs/extractPageObjects.js';
+export type { ExtractResult, ExtractedPage } from './specs/extractPageObjects.js';
+export type { SharedFlow } from './specs/detectSharedFlows.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 { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+export { loadMemory, formatMemoryForPrompt, formatMemoryIndex, recallMemory, readFact, formatFact, writeFact, memoryDir } from './memory/businessMemory.js';
 export type { BusinessFact } from './memory/businessMemory.js';
 export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';
 export type { QaIntensity, QaIntensitySpec } from './qa/intensity.js';

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;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"}
+{"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;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGjG,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACpG,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,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;AAKhF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5J,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

@@ -14,8 +14,17 @@
  */
 // ── crystallization + grounded replay ────────────────────────────────────────
 export { writeSpec } from './specs/writeSpec.js';
+export { reRenderSpec } from './specs/writeSpec.js';
 // API-layer crystallizer — observed/replayed requests → *.api-test.spec.ts.
 export { writeApiSpec } from './specs/writeApiSpec.js';
+// Optimize (F7) — build the improvement brief for the user's own agent, then
+// file its result as a reviewed candidate. No Hover-owned model runs.
+export { buildOptimizeBrief, saveOptimizedCandidate, OptimizeError } from './specs/optimizeSpec.js';
+// LLM-Wiki P1 Lint — deterministic health check over .hover/ (map vs specs vs runs).
+export { lintWiki, parseRunStatuses } from './specs/lintWiki.js';
+export { parseBusinessMap } from './specs/businessMap.js';
+// Page-Object extraction — lift NON-login shared flows into pages/ + fixtures.
+export { extractPageObjects, detectExtractableFlows } from './specs/extractPageObjects.js';
 // 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.
@@ -23,6 +32,8 @@ export { readSidecar } from './specs/sidecar.js';
 // ── debug-Chrome lifecycle ───────────────────────────────────────────────────
 export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';
 // ── business memory (ask → remember loop) ────────────────────────────────────
-export { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+// recallMemory = progressive disclosure (full when small, index when large);
+// readFact = the on-demand single-rule fetch behind recall_fact.
+export { loadMemory, formatMemoryForPrompt, formatMemoryIndex, recallMemory, readFact, formatFact, writeFact, memoryDir } from './memory/businessMemory.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/memory/businessMemory.d.ts

@@ -18,6 +18,26 @@ 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;
+/** Above this many chars of formatted-full memory, recall returns the INDEX
+ *  (title — description per rule) instead of every rule's body, and the agent
+ *  pulls a specific rule with `recall_fact` on demand — Claude-Code-style
+ *  progressive disclosure. Below it, inlining everything is cheaper than making
+ *  the agent round-trip for five rules, so recall stays full. */
+export declare const RECALL_INLINE_BUDGET = 2000;
+/** The INDEX block: one `title — description (type)` line per rule, no bodies.
+ *  This is the always-cheap tier; a rule's body is fetched by `readFact`. */
+export declare function formatMemoryIndex(facts: BusinessFact[]): string;
+/** Recall memory with progressive disclosure: full bodies when the set is small
+ *  (≤ RECALL_INLINE_BUDGET chars formatted), the index alone when it's large.
+ *  '' when there are no facts. This is what `recall_business_knowledge` returns. */
+export declare function recallMemory(devRoot: string): Promise<string>;
+/** Format one fact's FULL text (body verbatim, not whitespace-collapsed) for an
+ *  on-demand `recall_fact`. */
+export declare function formatFact(fact: BusinessFact): string;
+/** Load ONE fact by name/slug for on-demand recall. Match order: exact slug →
+ *  slugified-name equality → prefix → substring. Returns null if nothing matches
+ *  (or the memory dir is empty). Total: never throws. */
+export declare function readFact(devRoot: string, name: string): Promise<BusinessFact | null>;
 /** 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. */

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

@@ -1 +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"}
+{"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;;;;iEAIiE;AACjE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;6EAC6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAY/D;AAED;;oFAEoF;AACpF,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKnE;AAED;+BAC+B;AAC/B,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAErD;AAED;;yDAEyD;AACzD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAW1F;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"}

package/dist/memory/businessMemory.js

@@ -87,6 +87,53 @@ export function formatMemoryForPrompt(facts) {
         'ground truth; do NOT re-ask what these already answer):\n' +
         lines.join('\n'));
 }
+/** Above this many chars of formatted-full memory, recall returns the INDEX
+ *  (title — description per rule) instead of every rule's body, and the agent
+ *  pulls a specific rule with `recall_fact` on demand — Claude-Code-style
+ *  progressive disclosure. Below it, inlining everything is cheaper than making
+ *  the agent round-trip for five rules, so recall stays full. */
+export const RECALL_INLINE_BUDGET = 2000;
+/** The INDEX block: one `title — description (type)` line per rule, no bodies.
+ *  This is the always-cheap tier; a rule's body is fetched by `readFact`. */
+export function formatMemoryIndex(facts) {
+    if (!facts.length)
+        return '';
+    const lines = facts.map((f) => `- ${f.name}${f.description ? ` — ${f.description}` : ''} (${f.type})`);
+    return (`KNOWN BUSINESS KNOWLEDGE FOR THIS APP — ${facts.length} rules learned from earlier ` +
+        `runs (treat as ground truth; do NOT re-ask what these answer). This is the INDEX; ` +
+        `call recall_fact("<name>") to read a rule's full text when it's relevant to what ` +
+        `you're testing:\n` +
+        lines.join('\n'));
+}
+/** Recall memory with progressive disclosure: full bodies when the set is small
+ *  (≤ RECALL_INLINE_BUDGET chars formatted), the index alone when it's large.
+ *  '' when there are no facts. This is what `recall_business_knowledge` returns. */
+export async function recallMemory(devRoot) {
+    const facts = await loadMemory(devRoot);
+    if (!facts.length)
+        return '';
+    const full = formatMemoryForPrompt(facts);
+    return full.length <= RECALL_INLINE_BUDGET ? full : formatMemoryIndex(facts);
+}
+/** Format one fact's FULL text (body verbatim, not whitespace-collapsed) for an
+ *  on-demand `recall_fact`. */
+export function formatFact(fact) {
+    return `${fact.name}${fact.description ? ` — ${fact.description}` : ''} (${fact.type}):\n${fact.body.trim()}`;
+}
+/** Load ONE fact by name/slug for on-demand recall. Match order: exact slug →
+ *  slugified-name equality → prefix → substring. Returns null if nothing matches
+ *  (or the memory dir is empty). Total: never throws. */
+export async function readFact(devRoot, name) {
+    const facts = await loadMemory(devRoot);
+    if (!facts.length)
+        return null;
+    const q = slugify(name);
+    return (facts.find((f) => f.name === q) ??
+        facts.find((f) => slugify(f.name) === q) ??
+        facts.find((f) => f.name.startsWith(q) || slugify(f.name).startsWith(q)) ??
+        facts.find((f) => f.name.includes(q) || slugify(f.name).includes(q)) ??
+        null);
+}
 /** 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. */

package/dist/specs/businessMap.d.ts

@@ -0,0 +1,26 @@
+export type MapNodeKind = 'app' | 'area' | 'line' | 'spec';
+export type CoverageStatus = 'covered' | 'uncovered';
+export interface MapNode {
+    id: string;
+    label: string;
+    kind: MapNodeKind;
+    status?: CoverageStatus;
+    route?: string;
+    spec?: string;
+}
+export interface MapEdge {
+    source: string;
+    target: string;
+}
+export interface BusinessMapGraph {
+    app: string;
+    nodes: MapNode[];
+    edges: MapEdge[];
+    stats: {
+        lines: number;
+        covered: number;
+        areas: number;
+    };
+}
+export declare function parseBusinessMap(md: string, fallbackApp?: string): BusinessMapGraph;
+//# sourceMappingURL=businessMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"businessMap.d.ts","sourceRoot":"","sources":["../../src/specs/businessMap.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAErD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AA4BD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,SAAQ,GAAG,gBAAgB,CAuDlF"}

package/dist/specs/businessMap.js

@@ -0,0 +1,87 @@
+/*
+ * Canonical parser for the `.hover/hover-map.md` business map the agent
+ * maintains — the overview page of the app's living test wiki. Turns the
+ * markdown checklist into a graph model (app → area → business line → spec,
+ * with coverage).
+ *
+ * This is the unit-tested source of truth. The cockpit keeps an in-extension
+ * copy (packages/vscode-ext/src/businessMap.ts) on purpose — a read-only view
+ * must not depend on the engine — so keep the two in sync if the format changes.
+ */
+function slug(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'x');
+}
+const SPEC_RE = /\.spec\.tsx?$/;
+function splitItem(rest) {
+    const parts = rest
+        .split(/\s+[—–-]\s+/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const name = parts.shift() ?? rest.trim();
+    let route;
+    let spec;
+    for (const p of parts) {
+        if (SPEC_RE.test(p))
+            spec = p;
+        else if (p.startsWith('/'))
+            route = p;
+    }
+    return { name, route, spec };
+}
+export function parseBusinessMap(md, fallbackApp = 'app') {
+    const nodes = [];
+    const edges = [];
+    const seen = new Set();
+    const add = (n) => {
+        if (seen.has(n.id))
+            return;
+        seen.add(n.id);
+        nodes.push(n);
+    };
+    let app = fallbackApp;
+    const title = md.match(/^#\s+(.+)$/m);
+    if (title) {
+        const t = title[1].trim();
+        const m = t.match(/business\s*map\s*[—–-]\s*(.+)$/i);
+        app = (m ? m[1] : t).trim() || fallbackApp;
+    }
+    add({ id: 'app', label: app, kind: 'app' });
+    let area = null;
+    let covered = 0;
+    let lineCount = 0;
+    let areaCount = 0;
+    for (const raw of md.split('\n')) {
+        const line = raw.trimEnd();
+        const areaM = line.match(/^##\s+(.+)$/);
+        if (areaM) {
+            const label = areaM[1].trim();
+            const id = `area:${slug(label)}`;
+            area = { id };
+            add({ id, label, kind: 'area' });
+            edges.push({ source: 'app', target: id });
+            areaCount++;
+            continue;
+        }
+        const itemM = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+        if (itemM) {
+            const status = itemM[1].toLowerCase() === 'x' ? 'covered' : 'uncovered';
+            const { name, route, spec } = splitItem(itemM[2]);
+            const parentId = area?.id ?? 'app';
+            const lineId = `line:${slug(area ? area.id.slice(5) : 'top')}/${slug(name)}`;
+            add({ id: lineId, label: name, kind: 'line', status, route, spec });
+            edges.push({ source: parentId, target: lineId });
+            lineCount++;
+            if (status === 'covered')
+                covered++;
+            if (spec) {
+                const specId = `spec:${spec}`;
+                add({ id: specId, label: spec, kind: 'spec', spec });
+                edges.push({ source: lineId, target: specId });
+            }
+        }
+    }
+    return { app, nodes, edges, stats: { lines: lineCount, covered, areas: areaCount } };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgC5E;AAwDD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}
+{"version":3,"file":"detectSharedFlows.d.ts","sourceRoot":"","sources":["../../src/specs/detectSharedFlows.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;2CACuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;wDACoD;IACpD,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B;2EACuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA2C5E;AA+DD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}

package/dist/specs/detectSharedFlows.js

@@ -55,11 +55,28 @@ export function stepSignature(tool, rawInput) {
         }
         case 'browser_press_key':
             return `press:${String(i.key ?? '')}`;
+        // Grounded control tools (MCP-first): the target is role+name/testId/text on
+        // the input. The typed/selected value is data; only the target is structure.
+        case 'click_control':
+            return `click:${normGround(i)}`;
+        case 'fill_control':
+            return `type:${normGround(i)}`;
+        case 'select_control':
+            return `select:${normGround(i)}`;
+        case 'check_control':
+            return `check:${normGround(i)}`;
         default:
-            // Diagnostics / browser_tabs / browser_wait_for — not flow structure.
+            // Diagnostics / assert_visible / browser_tabs / browser_wait_for — not
+            // flow structure (an assertion isn't part of a reusable action prefix).
             return null;
     }
 }
+/** Normalize a GROUNDED target ({ role, name, testId, text }) to a stable
+ *  signature fragment — the *_control sibling of normElement. */
+function normGround(i) {
+    const parts = [i.role, i.name, i.testId, i.text].filter((v) => typeof v === 'string' && v.length > 0);
+    return normElement(parts.join('|'));
+}
 /** Read and parse every sidecar under `.hover/sidecars/`, unioned with any
  *  still in the legacy `__vibe_tests__/.hover/` home (current home wins on a
  *  slug collision). Malformed files are skipped (better to detect across the

package/dist/specs/extractPageObjects.d.ts

@@ -0,0 +1,22 @@
+import { type SharedFlow } from './detectSharedFlows.js';
+export interface ExtractedPage {
+    className: string;
+    methodName: string;
+    fileName: string;
+    path: string;
+    /** Slugs of the specs that share this flow. */
+    specs: string[];
+}
+export interface ExtractResult {
+    pages: ExtractedPage[];
+    fixturesPath: string | null;
+    /** Slugs re-rendered to consume the new Page Objects. */
+    folded: string[];
+}
+/** Detect shared flows worth extracting — NON-login prefixes shared by >= minSpecs
+ *  specs. Read-only: the agent uses this to decide what to ASK the user about. */
+export declare function detectExtractableFlows(devRoot: string, minSpecs?: number): Promise<SharedFlow[]>;
+export declare function extractPageObjects(devRoot: string, opts?: {
+    minSpecs?: number;
+}): Promise<ExtractResult>;
+//# sourceMappingURL=extractPageObjects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractPageObjects.d.ts","sourceRoot":"","sources":["../../src/specs/extractPageObjects.ts"],"names":[],"mappings":"AAeA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAK5E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAcD;kFACkF;AAClF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGjG;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,aAAa,CAAC,CA+CxB"}

package/dist/specs/extractPageObjects.js

@@ -0,0 +1,118 @@
+/**
+ * Page Object extraction (F4) — lift flows shared across saved specs into
+ * `pages/<Name>.ts` + a `fixtures.ts` entry point, then FOLD the specs that use
+ * them (they consume `await xPage.x()` from `./fixtures` instead of repeating
+ * the steps). Fully deterministic — no LLM.
+ *
+ * MCP-first trigger: after `test_app` crystallizes the suite, the agent calls
+ * `detect_shared_flows`, ASKS the user, and on yes calls this. LOGIN prefixes
+ * are EXCLUDED — auth-fixture already lifts login into auth.setup.ts, and
+ * folding it here would double it. So this only extracts NON-login shared
+ * entry flows (the case that scales on large suites).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { detectSharedFlows } from './detectSharedFlows.js';
+import { generatePageObject } from './generatePageObject.js';
+import { writePageObjectManifest } from './pageObjectManifest.js';
+import { reRenderSpec } from './writeSpec.js';
+/** A shared prefix is a LOGIN (auth-fixture's job, not a POM) when it types a
+ *  credential — the sidecar's fill value is a `process.env.<X>` ref. */
+function isLoginPrefix(steps) {
+    return steps.some((s) => {
+        if (s.kind !== 'step')
+            return false;
+        const tool = (s.tool ?? '').replace(/^mcp__[a-z0-9_-]+?__/, '');
+        const input = (s.input ?? {});
+        const v = tool === 'browser_type' ? input.text : tool === 'fill_control' ? input.value : null;
+        return typeof v === 'string' && /process\.env\./.test(v);
+    });
+}
+/** Detect shared flows worth extracting — NON-login prefixes shared by >= minSpecs
+ *  specs. Read-only: the agent uses this to decide what to ASK the user about. */
+export async function detectExtractableFlows(devRoot, minSpecs = 2) {
+    const flows = await detectSharedFlows(devRoot, { minSpecs });
+    return flows.filter((f) => !isLoginPrefix(f.prefixSteps));
+}
+export async function extractPageObjects(devRoot, opts = {}) {
+    const flows = await detectExtractableFlows(devRoot, opts.minSpecs ?? 2);
+    if (flows.length === 0)
+        return { pages: [], fixturesPath: null, folded: [] };
+    const testsDir = join(devRoot, '__vibe_tests__');
+    const pagesDir = join(testsDir, 'pages');
+    await mkdir(pagesDir, { recursive: true });
+    const pages = [];
+    const entries = [];
+    const usedNames = new Set();
+    const affected = new Set();
+    for (const flow of flows) {
+        const probe = generatePageObject(flow.prefixSteps);
+        const className = uniqueName(probe.className, usedNames);
+        const po = className === probe.className ? probe : generatePageObject(flow.prefixSteps, { className });
+        const path = join(pagesDir, po.fileName);
+        await writeFile(path, po.source, 'utf-8');
+        pages.push({ className: po.className, methodName: po.methodName, fileName: po.fileName, path, specs: flow.specs });
+        entries.push({
+            className: po.className,
+            methodName: po.methodName,
+            fixtureName: fixtureName(po.className),
+            fileName: po.fileName,
+            signatures: flow.signatures,
+            specs: flow.specs,
+        });
+        flow.specs.forEach((s) => affected.add(s));
+    }
+    const fixturesPath = join(testsDir, 'fixtures.ts');
+    await writeFile(fixturesPath, renderFixtures(pages), 'utf-8');
+    // The manifest lets writeSpec's matchPageObject fold a matching prefix.
+    await writePageObjectManifest(devRoot, entries);
+    // Fold NOW: faithfully re-render each affected spec so it consumes the Page
+    // Object (via reRenderSpec, which re-applies auth-fixture/base-url from the
+    // sidecar — never regressing them). Non-login prefixes → no auth conflict.
+    const folded = [];
+    for (const slug of affected) {
+        try {
+            if (await reRenderSpec(devRoot, slug))
+                folded.push(slug);
+        }
+        catch {
+            /* a fold is best-effort — the page/fixture still exist for future specs */
+        }
+    }
+    return { pages, fixturesPath, folded };
+}
+function renderFixtures(pages) {
+    const lines = [
+        `import { test as base } from '@playwright/test';`,
+        ...pages.map((p) => `import { ${p.className} } from './pages/${p.className}';`),
+        ``,
+        `/**`,
+        ` * Generated by Hover — Page Object fixtures lifted from flows shared across`,
+        ` * specs. In a spec: \`import { test, expect } from './fixtures';\` then consume`,
+        ` * e.g. \`async ({ page, ${pages[0] ? fixtureName(pages[0].className) : 'somePage'} }) => …\`.`,
+        ` */`,
+        `export const test = base.extend<{ ${pages.map((p) => `${fixtureName(p.className)}: ${p.className}`).join('; ')} }>({`,
+        ...pages.flatMap((p) => [
+            `  ${fixtureName(p.className)}: async ({ page }, use) => {`,
+            `    await use(new ${p.className}(page));`,
+            `  },`,
+        ]),
+        `});`,
+        ``,
+        `export { expect } from '@playwright/test';`,
+        ``,
+    ];
+    return lines.join('\n');
+}
+/** LoginPage -> loginPage. */
+function fixtureName(className) {
+    return className.charAt(0).toLowerCase() + className.slice(1);
+}
+function uniqueName(base, used) {
+    let name = base;
+    let n = 2;
+    while (used.has(name))
+        name = `${base}${n++}`;
+    used.add(name);
+    return name;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAUtD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CAoElB"}
+{"version":3,"file":"generatePageObject.d.ts","sourceRoot":"","sources":["../../src/specs/generatePageObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAWtD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,gBAAgB,CA0FlB"}

package/dist/specs/generatePageObject.js

@@ -1,4 +1,4 @@
-import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, } from './writeSpec.js';
+import { selectorFromDescription, selectorForFormField, emitInteraction, blockScope, groundedSelector, } from './writeSpec.js';
 const PAGE_VAR = 'this.page';
 export function generatePageObject(steps, override = {}) {
     const derived = deriveNames(steps);
@@ -49,8 +49,29 @@ export function generatePageObject(steps, override = {}) {
             case 'browser_press_key':
                 body.push(`await ${PAGE_VAR}.keyboard.press(${JSON.stringify(String(i.key ?? ''))});`);
                 break;
+            // Grounded control tools (MCP-first): target is role+name/testId/text on
+            // the input; the typed/selected value is data → a method parameter (D4).
+            case 'click_control':
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), 'click()')));
+                break;
+            case 'fill_control': {
+                const p = uniqueParam(paramName(groundLabel(i)), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), `fill(${p})`)));
+                break;
+            }
+            case 'select_control': {
+                const withRole = i.role ? i : { ...i, role: i.name ? 'combobox' : undefined };
+                const p = uniqueParam(paramName(groundLabel(i)), used);
+                params.push(p);
+                body.push(...blockScope(emitInteraction(groundedSelector(withRole, PAGE_VAR), `selectOption(${p})`)));
+                break;
+            }
+            case 'check_control':
+                body.push(...blockScope(emitInteraction(groundedSelector(i, PAGE_VAR), i.checked === false ? 'uncheck()' : 'check()')));
+                break;
             default:
-                break; // diagnostics / non-replayable — skipped
+                break; // diagnostics / assert_visible / non-replayable — skipped
         }
     }
     const paramList = params.map(p => `${p}: string`).join(', ');
@@ -127,6 +148,10 @@ function pascal(raw) {
 }
 /** Parameter name derived from a field/element label. */
 const paramName = camel;
+/** A grounded target's label (name → testId → text) for naming its data param. */
+function groundLabel(i) {
+    return String(i.name ?? i.testId ?? i.text ?? 'value');
+}
 function uniqueParam(base, used) {
     const root = base || 'value';
     let name = root;

package/dist/specs/lintWiki.d.ts

@@ -0,0 +1,33 @@
+export type LintSeverity = 'error' | 'warn' | 'info';
+export type LintKind = 'deleted-spec' | 'regressed-coverage' | 'orphan-spec';
+export interface LintFinding {
+    kind: LintKind;
+    severity: LintSeverity;
+    /** One-line human-readable finding. */
+    message: string;
+    /** The business line involved (map label), if any. */
+    line?: string;
+    /** The spec basename involved, if any. */
+    spec?: string;
+    /** A suggested next action for the agent (e.g. heal, map, remove the ref). */
+    fix?: string;
+}
+export interface LintResult {
+    /** No error/warn findings (info-only still counts as ok). */
+    ok: boolean;
+    hasMap: boolean;
+    findings: LintFinding[];
+    summary: {
+        areas: number;
+        lines: number;
+        covered: number;
+        specs: number;
+    };
+}
+type RunStatus = 'pass' | 'fail' | 'flaky';
+/** Parse a Playwright JSON report into { specBasename → worst status }. Mirrors
+ *  the cockpit's parser; an unexpected shape yields no entries. */
+export declare function parseRunStatuses(json: unknown): Record<string, RunStatus>;
+export declare function lintWiki(devRoot: string): Promise<LintResult>;
+export {};
+//# sourceMappingURL=lintWiki.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lintWiki.d.ts","sourceRoot":"","sources":["../../src/specs/lintWiki.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAE7E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAG3C;mEACmE;AACnE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAmBzE;AAgDD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAyEnE"}

package/dist/specs/lintWiki.js

@@ -0,0 +1,163 @@
+/*
+ * LLM-Wiki P1 — Lint: a deterministic health check over `.hover/` (the app's
+ * living test wiki). It cross-checks the business map against the real spec
+ * files and the run ledger and reports drift:
+ *
+ *   - deleted-spec       a covered line points at a *.spec.ts that no longer exists
+ *   - regressed-coverage a covered line's spec last ran fail/flaky (→ candidate for heal)
+ *   - orphan-spec        a *.spec.ts exists but no line references it (a gap in the map)
+ *
+ * These are the CHEAP, mechanical checks — no LLM, no network. The LLM-judged
+ * half (contradictory memory rules, routes in code missing from the map) is the
+ * agent's job, driven by the `/mcp__hover__lint` prompt on top of this result.
+ *
+ * Pure-ish: reads the FS, never writes; a missing map / bad JSON degrades to a
+ * partial (or empty) result, never throws.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseBusinessMap } from './businessMap.js';
+const RUN_RANK = { pass: 0, flaky: 1, fail: 2 };
+/** Parse a Playwright JSON report into { specBasename → worst status }. Mirrors
+ *  the cockpit's parser; an unexpected shape yields no entries. */
+export function parseRunStatuses(json) {
+    const out = {};
+    const worse = (a, b) => !a ? b : RUN_RANK[b] > RUN_RANK[a] ? b : a;
+    const visit = (suite, inherited) => {
+        const file = suite.file ?? inherited;
+        for (const raw of suite.specs ?? []) {
+            const spec = raw;
+            const key = (file ?? spec.file ?? 'unknown').split(/[\\/]/).pop() ?? 'unknown';
+            let status = spec.ok ? 'pass' : 'fail';
+            if (spec.ok && (spec.tests ?? []).some((t) => t.status === 'flaky'))
+                status = 'flaky';
+            out[key] = worse(out[key], status);
+        }
+        for (const child of suite.suites ?? [])
+            visit(child, file);
+    };
+    if (json && typeof json === 'object') {
+        for (const s of json.suites ?? [])
+            visit(s);
+    }
+    return out;
+}
+/** Recursively collect *.spec.ts basenames under __vibe_tests__/. */
+async function collectSpecs(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return; // no __vibe_tests__ yet
+        }
+        for (const e of entries) {
+            const p = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'pages' || e.name === '.hover' || e.name === 'node_modules')
+                    continue;
+                await walk(p);
+            }
+            else if (/\.spec\.tsx?$/.test(e.name)) {
+                out.push(e.name);
+            }
+        }
+    };
+    await walk(dir);
+    return out;
+}
+/** Latest run status per spec basename, merged newest-wins across `.hover/runs/*.json`
+ *  (filename is the ISO stamp → lexical sort is chronological). */
+async function latestRunStatuses(runsDir) {
+    let files;
+    try {
+        files = (await readdir(runsDir)).filter((f) => f.endsWith('.json')).sort();
+    }
+    catch {
+        return {};
+    }
+    const merged = {};
+    for (const f of files) {
+        // later files overwrite earlier → the latest run wins per spec
+        try {
+            const json = JSON.parse(await readFile(join(runsDir, f), 'utf-8'));
+            Object.assign(merged, parseRunStatuses(json));
+        }
+        catch {
+            /* skip a bad run file */
+        }
+    }
+    return merged;
+}
+export async function lintWiki(devRoot) {
+    const hoverDir = join(devRoot, '.hover');
+    const vibeDir = join(devRoot, '__vibe_tests__');
+    let md = '';
+    try {
+        md = await readFile(join(hoverDir, 'hover-map.md'), 'utf-8');
+    }
+    catch {
+        /* no map yet */
+    }
+    const hasMap = md.trim().length > 0;
+    const graph = parseBusinessMap(md);
+    const specFiles = await collectSpecs(vibeDir);
+    const specSet = new Set(specFiles);
+    const runs = await latestRunStatuses(join(hoverDir, 'runs'));
+    const findings = [];
+    const lines = graph.nodes.filter((n) => n.kind === 'line');
+    const referenced = new Set();
+    for (const line of lines) {
+        if (line.spec) {
+            referenced.add(line.spec);
+            // deleted-spec: a line points at a spec file that isn't on disk.
+            if (!specSet.has(line.spec)) {
+                findings.push({
+                    kind: 'deleted-spec',
+                    severity: 'error',
+                    line: line.label,
+                    spec: line.spec,
+                    message: `"${line.label}" points at ${line.spec}, which no longer exists in __vibe_tests__/.`,
+                    fix: `Re-crystallize the flow, or drop the stale spec reference from .hover/hover-map.md.`,
+                });
+                continue; // no point checking its run status
+            }
+            // regressed-coverage: a covered line whose spec last ran fail/flaky.
+            const run = runs[line.spec];
+            if (line.status === 'covered' && (run === 'fail' || run === 'flaky')) {
+                findings.push({
+                    kind: 'regressed-coverage',
+                    severity: 'warn',
+                    line: line.label,
+                    spec: line.spec,
+                    message: `"${line.label}" is marked covered but ${line.spec} last ran ${run}.`,
+                    fix: `Heal it: /mcp__hover__heal ${line.spec.replace(/\.spec\.tsx?$/, '')}`,
+                });
+            }
+        }
+    }
+    // orphan-spec: a UI spec on disk that no business line references (a map gap).
+    // API specs (*.api-test.spec.ts) are siblings of a line, not lines → skip.
+    for (const spec of specFiles) {
+        if (spec.endsWith('.api-test.spec.ts'))
+            continue;
+        if (!referenced.has(spec)) {
+            findings.push({
+                kind: 'orphan-spec',
+                severity: 'info',
+                spec,
+                message: `${spec} exists but no line in the business map references it.`,
+                fix: `Add its business line to .hover/hover-map.md (mark it [x] with the spec).`,
+            });
+        }
+    }
+    const ok = !findings.some((f) => f.severity === 'error' || f.severity === 'warn');
+    return {
+        ok,
+        hasMap,
+        findings,
+        summary: { areas: graph.stats.areas, lines: graph.stats.lines, covered: graph.stats.covered, specs: specFiles.length },
+    };
+}

package/dist/specs/optimizeSpec.d.ts

@@ -29,12 +29,37 @@ export interface OptimizeResult {
     original: string;
 }
 export declare function optimizeSpec(devRoot: string, slug: string, runCodegen: RunCodegen): Promise<OptimizeResult>;
+/**
+ * MCP-first optimize (F7) without a Hover-owned model: build the improvement
+ * brief for a spec, hand it to the USER's own agent (which IS the intelligence),
+ * and let it write the improved file back through `saveOptimizedCandidate`.
+ *
+ * Returns the prompt the agent works from (the same improvement rules the
+ * legacy in-engine `optimizeSpec` used) + the original spec, so a caller can
+ * diff. Throws OptimizeError if the spec doesn't exist. No LLM runs here.
+ */
+export declare function buildOptimizeBrief(devRoot: string, slug: string): Promise<{
+    prompt: string;
+    original: string;
+}>;
+/**
+ * Deterministic finishing + write for an optimized spec the agent produced:
+ * validate the LLM's code against the same guardrails the deterministic path
+ * keeps, soft-batch the trailing independent assertions, and write it as a
+ * CANDIDATE (`.hover/cache/optimized/<slug>.spec.ts.draft`) — never the original.
+ * Throws OptimizeError if the code fails validation (the caller surfaces it so
+ * the agent can retry). No LLM runs here.
+ */
+export declare function saveOptimizedCandidate(devRoot: string, slug: string, llmCode: string): Promise<{
+    candidatePath: string;
+    code: string;
+}>;
 /**
  * Build the codegen prompt: the current spec + the observed session, plus the
  * same rules the deterministic path enforces (semantic selectors, no XPath, no
  * waitForTimeout, keep the test.step shape).
  */
-export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[], suite?: SuiteContext): string;
+export declare function buildOptimizePrompt(draft: string, sidecar: SpecSidecar | null, seeds?: SeedRule[], suite?: SuiteContext, outputInstruction?: string): string;
 /** Strip a ```ts fence if the model wrapped its output in one. */
 export declare function extractCode(raw: string): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAgC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D;;;4DAG4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAOD;0DAC0D;AAC1D,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/E;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CAwCzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,EACtB,KAAK,GAAE,YAA4B,GAClC,MAAM,CAkFR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF"}
+{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAgC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D;;;4DAG4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAOD;0DAC0D;AAC1D,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/E;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CAKzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B/C;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBlD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,EACtB,KAAK,GAAE,YAA4B,EACnC,iBAAiB,SAA+F,GAC/G,MAAM,CAiFR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF"}

package/dist/specs/optimizeSpec.js

@@ -49,6 +49,21 @@ export async function gatherSuiteContext(devRoot) {
     return { conventions, pages };
 }
 export async function optimizeSpec(devRoot, slug, runCodegen) {
+    const { prompt, original } = await buildOptimizeBrief(devRoot, slug);
+    const raw = await runCodegen(prompt);
+    const { candidatePath, code } = await saveOptimizedCandidate(devRoot, slug, extractCode(raw));
+    return { candidatePath, code, original };
+}
+/**
+ * MCP-first optimize (F7) without a Hover-owned model: build the improvement
+ * brief for a spec, hand it to the USER's own agent (which IS the intelligence),
+ * and let it write the improved file back through `saveOptimizedCandidate`.
+ *
+ * Returns the prompt the agent works from (the same improvement rules the
+ * legacy in-engine `optimizeSpec` used) + the original spec, so a caller can
+ * diff. Throws OptimizeError if the spec doesn't exist. No LLM runs here.
+ */
+export async function buildOptimizeBrief(devRoot, slug) {
     const specPath = join(devRoot, '__vibe_tests__', `${slug}.spec.ts`);
     let draft;
     try {
@@ -64,15 +79,31 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
         .map(s => s.tool));
     const seeds = relevantSeeds(BUILTIN_SEEDS, specTools);
     const suite = await gatherSuiteContext(devRoot);
-    const raw = await runCodegen(buildOptimizePrompt(draft, sidecar, seeds, suite));
-    const llmCode = extractCode(raw);
+    // The agent path ends by CALLING a tool (not by emitting raw text), so swap
+    // the legacy "output ONLY the file" footer for a save_optimized_spec directive.
+    const outputInstruction = `When done, call \`save_optimized_spec\` with slug "${slug}" and the COMPLETE improved ` +
+        `.ts file as \`code\`. Hover validates it (semantic selectors, no waitForTimeout/XPath), ` +
+        `soft-batches trailing assertions, and files it as a REVIEW CANDIDATE at ` +
+        `.hover/cache/optimized/${slug}.spec.ts.draft — it does NOT touch your spec. If it comes ` +
+        `back with a ✗ (a rejected check), fix that and call it again. Then tell the user the ` +
+        `candidate path so they can diff it against __vibe_tests__/${slug}.spec.ts and promote it.`;
+    return { prompt: buildOptimizePrompt(draft, sidecar, seeds, suite, outputInstruction), original: draft };
+}
+/**
+ * Deterministic finishing + write for an optimized spec the agent produced:
+ * validate the LLM's code against the same guardrails the deterministic path
+ * keeps, soft-batch the trailing independent assertions, and write it as a
+ * CANDIDATE (`.hover/cache/optimized/<slug>.spec.ts.draft`) — never the original.
+ * Throws OptimizeError if the code fails validation (the caller surfaces it so
+ * the agent can retry). No LLM runs here.
+ */
+export async function saveOptimizedCandidate(devRoot, slug, llmCode) {
     const check = validateSpecCode(llmCode);
     if (!check.ok) {
         throw new OptimizeError(`optimization rejected — ${check.errors.join('; ')}`);
     }
-    // Deterministic finishing step: the LLM decided WHAT to assert; soft-batch
-    // applies the safe mechanical rewrite (trailing run of independent assertions
-    // → expect.soft) surgically on its output. See softBatch.ts for the guard.
+    // Soft-batch applies the safe mechanical rewrite (a trailing run of
+    // independent assertions → expect.soft) surgically. See softBatch.ts.
     const code = softBatch(llmCode).code;
     // Candidates are disposable derived artifacts → `.hover/cache/` (always
     // gitignored). Losing one costs a re-run of the optimization, nothing more.
@@ -82,14 +113,14 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
     // candidate before a human reviews it.
     const candidatePath = join(dir, `${slug}.spec.ts.draft`);
     await writeFile(candidatePath, code.endsWith('\n') ? code : `${code}\n`, 'utf-8');
-    return { candidatePath, code, original: draft };
+    return { candidatePath, code };
 }
 /**
  * Build the codegen prompt: the current spec + the observed session, plus the
  * same rules the deterministic path enforces (semantic selectors, no XPath, no
  * waitForTimeout, keep the test.step shape).
  */
-export function buildOptimizePrompt(draft, sidecar, seeds = [], suite = { pages: [] }) {
+export function buildOptimizePrompt(draft, sidecar, seeds = [], suite = { pages: [] }, outputInstruction = 'Output ONLY the complete .ts file contents — no markdown fences, no prose, no explanation.') {
     const done = sidecar?.steps.find(s => s.kind === 'done');
     const stepsJson = sidecar
         ? JSON.stringify(sidecar.steps.filter(s => s.kind === 'step'), null, 2)
@@ -138,8 +169,7 @@ export function buildOptimizePrompt(draft, sidecar, seeds = [], suite = { pages:
         `    human can find it and so the test breaks loudly once the app is fixed.`,
         `    Never silently lock buggy behavior into a normal-looking assertion.`,
         ``,
-        `Output ONLY the complete .ts file contents — no markdown fences, no prose,`,
-        `no explanation.`,
+        outputInstruction,
         ``,
         `=== CURRENT SPEC ===`,
         draft,

package/dist/specs/sidecar.d.ts

@@ -2,7 +2,7 @@ import type { SkillStep } from '../specs/specStep.js';
 import type { SpecAssertion } from './writeSpec.js';
 /** Current sidecar schema version. Bump when the shape changes so readers
  *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
-export declare const SIDECAR_VERSION = 1;
+export declare const SIDECAR_VERSION = 2;
 export interface SpecSidecar {
     version: number;
     slug: string;
@@ -10,10 +10,24 @@ export interface SpecSidecar {
     /** ISO timestamp the sidecar was written. */
     createdAt: string;
     /** The full captured session, structured and verbatim — never re-derived
-     *  from the generated `.spec.ts`. */
+     *  from the generated `.spec.ts`. Steps are already REDACTED (credentials are
+     *  `process.env.<X>` refs, never literals), so the sidecar carries no secret. */
     steps: SkillStep[];
     /** Alt-click assertions captured alongside the session. */
     assertions: SpecAssertion[];
+    /** The env-var NAMES the run redacted credentials to (e.g. ['HOVER_PASSWORD']).
+     *  Lets a re-render re-detect the login prefix without the literal secret. */
+    redactionEnvVars?: string[];
+    /** The run's target origin — re-render uses it for baseURL / goto synthesis. */
+    startUrl?: string;
+    /** Recon reset recipe (debt-2), so a re-render re-emits the reset beforeEach. */
+    resetRecipe?: {
+        tier: number;
+        storageKeys?: string[];
+        hook?: string;
+    };
+    /** Whether the run had approved editing an existing user config (Stage 4). */
+    authFixture?: boolean;
 }
 /** Project-root `.hover/` directory — the single home for Hover-derived data
  *  (sidecars, runs, rules, conventions). */

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

@@ -1 +1 @@
-{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;6EAC6E;AAC7E,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB;yCACqC;IACrC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;4CAC4C;AAC5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;gCAKgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;oEAEoE;AACpE,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB5F;AAED;;gEAEgE;AAChE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOhF"}
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/specs/sidecar.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;6EAC6E;AAC7E,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB;;qFAEiF;IACjF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,aAAa,EAAE,CAAC;IAI5B;kFAC8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;4CAC4C;AAC5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;gCAKgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE/E;AACD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;2EAC2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;oEAEoE;AACpE,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,WAAW,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoB5F;AAED;;gEAEgE;AAChE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOhF"}

package/dist/specs/sidecar.js

@@ -19,7 +19,7 @@ import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 /** Current sidecar schema version. Bump when the shape changes so readers
  *  (Stage 2 detection, Stage 7 optimization) can migrate or skip cleanly. */
-export const SIDECAR_VERSION = 1;
+export const SIDECAR_VERSION = 2;
 /** Project-root `.hover/` directory — the single home for Hover-derived data
  *  (sidecars, runs, rules, conventions). */
 export function hoverDir(devRoot) {

package/dist/specs/writeSpec.d.ts

@@ -90,6 +90,19 @@ export interface WriteSpecResult {
     };
 }
 export declare function writeSpec(opts: WriteSpecOptions): Promise<WriteSpecResult>;
+/**
+ * Re-crystallize an already-saved spec from its sidecar — FAITHFULLY. Used by
+ * self-heal (re-render the healed flow) and Page-Object extraction (fold a
+ * newly-extracted shared flow into the specs that use it). Reads the v2 sidecar
+ * context so the re-render re-applies the SAME auth-fixture + base URL + reset —
+ * NOT a degraded pass that would drop the login into the spec.
+ *
+ * Credentials never round-trip: the sidecar stores env-var NAMES only and its
+ * steps are already redacted, so we pass `{ value: '', envVar }` placeholders —
+ * enough for authPrefixLength to re-detect the login prefix, with no literal
+ * secret anywhere. Returns null if the spec has no sidecar.
+ */
+export declare function reRenderSpec(devRoot: string, slug: string): Promise<WriteSpecResult | null>;
 /**
  * Emit an interaction (click / dblclick / hover / fill / selectOption) as a
  * visibility-guarded prelude: hoist the locator to `el`, assert it's visible,
@@ -121,6 +134,15 @@ export declare function blockScope(lines: string[]): string[];
  * trailing role keyword is the convention Playwright MCP uses.
  */
 export declare function selectorFromDescription(desc: string, pageVar?: string): string;
+/**
+ * Selector for a Hover control-actuation step (click/fill/select_control). The
+ * agent supplied these fields straight from the snapshot, in the same priority
+ * order the actuation server resolves them — role+name → testId → text — so the
+ * crystallized selector is exactly the one that drove the action at record time
+ * (no free-form description, hence no confabulation). Mirrors
+ * `locate()` in `mcp/actuateServer.ts`.
+ */
+export declare function groundedSelector(input: Record<string, unknown>, pageVar?: string): string;
 /**
  * browser_select_option always targets a native `<select>` — whose ARIA role
  * is `combobox`. The agent's description is usually the label ("marital

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;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"}
+{"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;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAcjG;AA0nBD;;;;;;;;;;;;;;;;;;;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;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,SAAS,GAAG,MAAM,CA+BzF;AAiBD;;;;;;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

@@ -20,7 +20,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { humanSteps, humanStep } from './humanSteps.js';
-import { writeSidecar } from './sidecar.js';
+import { writeSidecar, readSidecar } from './sidecar.js';
 import { readPageObjectManifest, } from './pageObjectManifest.js';
 import { stepSignature } from './detectSharedFlows.js';
 import { slugify, firstSentence } from './text.js';
@@ -162,6 +162,34 @@ export async function writeSpec(opts) {
     // writeSecuritySpec — those are stateless and independently replayable.)
     return writeOneSpec(opts, slugify(opts.name), opts.name, opts.steps);
 }
+/**
+ * Re-crystallize an already-saved spec from its sidecar — FAITHFULLY. Used by
+ * self-heal (re-render the healed flow) and Page-Object extraction (fold a
+ * newly-extracted shared flow into the specs that use it). Reads the v2 sidecar
+ * context so the re-render re-applies the SAME auth-fixture + base URL + reset —
+ * NOT a degraded pass that would drop the login into the spec.
+ *
+ * Credentials never round-trip: the sidecar stores env-var NAMES only and its
+ * steps are already redacted, so we pass `{ value: '', envVar }` placeholders —
+ * enough for authPrefixLength to re-detect the login prefix, with no literal
+ * secret anywhere. Returns null if the spec has no sidecar.
+ */
+export async function reRenderSpec(devRoot, slug) {
+    const sc = await readSidecar(devRoot, slug);
+    if (!sc)
+        return null;
+    return writeSpec({
+        devRoot,
+        name: sc.name,
+        steps: sc.steps,
+        assertions: sc.assertions,
+        startUrl: sc.startUrl,
+        resetRecipe: sc.resetRecipe,
+        authFixture: sc.authFixture,
+        redactions: (sc.redactionEnvVars ?? []).map((envVar) => ({ value: '', envVar })),
+        overwrite: true,
+    });
+}
 /** Write ONE spec file from a (sub)set of steps. The single-file path and each
  *  per-flow file both go through here, so rendering / sidecar / config logic is
  *  identical whether or not the run was split. */
@@ -277,6 +305,12 @@ async function writeOneSpec(opts, slug, displayName, rawSteps) {
         name: displayName,
         steps,
         assertions: opts.assertions ?? [],
+        // v2 context — NAMES only (no literal creds), so a faithful re-render can
+        // re-apply auth-fixture + base URL + reset without re-driving the browser.
+        redactionEnvVars: (opts.redactions ?? []).map(r => r.envVar),
+        startUrl: opts.startUrl,
+        resetRecipe: opts.resetRecipe,
+        authFixture: opts.authFixture,
     });
     // Session-ledger patch, best-effort by contract: markSessionSaved swallows
     // its own failures — it must never break Save-as-spec.
@@ -812,7 +846,7 @@ export function selectorFromDescription(desc, pageVar = 'page') {
  * (no free-form description, hence no confabulation). Mirrors
  * `locate()` in `mcp/actuateServer.ts`.
  */
-function groundedSelector(input, pageVar = 'page') {
+export function groundedSelector(input, pageVar = 'page') {
     const role = typeof input.role === 'string' ? input.role : '';
     const name = typeof input.name === 'string' ? input.name : '';
     const testId = typeof input.testId === 'string' ? input.testId : '';

package/package.json

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