@hover-dev/core 0.22.0 → 0.24.0

package/dist/engine.d.ts

@@ -18,6 +18,14 @@ 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 { appendWikiLog, readWikiLog, wikiLogPath } from './specs/wikiLog.js';
+export type { WikiLogKind, WikiLogEntry } from './specs/wikiLog.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';
@@ -27,7 +35,7 @@ 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;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;AAEjG,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;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,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEpE,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

@@ -17,6 +17,14 @@ 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 P3 log — append-only, machine-parseable run history at .hover/log.md.
+export { appendWikiLog, readWikiLog, wikiLogPath } from './specs/wikiLog.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).
@@ -26,6 +34,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,37 @@
+export type MapNodeKind = 'app' | 'area' | 'line' | 'spec';
+export type CoverageStatus = 'covered' | 'uncovered';
+/** Inter-line relationship kinds recorded in the map's `## Relationships` block
+ *  (LLM-Wiki P2) — the graph edges that aren't the app→area→line→spec hierarchy. */
+export type RelationKind = 'depends-on' | 'shares-state' | 'navigates-to';
+export interface MapNode {
+    id: string;
+    label: string;
+    kind: MapNodeKind;
+    status?: CoverageStatus;
+    route?: string;
+    spec?: string;
+}
+export interface MapEdge {
+    source: string;
+    target: string;
+}
+/** A resolved inter-line edge: source/target are `line:` node ids. */
+export interface MapRelation {
+    source: string;
+    target: string;
+    kind: RelationKind;
+}
+export interface BusinessMapGraph {
+    app: string;
+    nodes: MapNode[];
+    edges: MapEdge[];
+    /** Inter-line relationships from the `## Relationships` block (may be empty). */
+    relations: MapRelation[];
+    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;AACrD;oFACoF;AACpF,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,CAAC;AAE1E,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,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACpB;AACD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,iFAAiF;IACjF,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AA+BD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,SAAQ,GAAG,gBAAgB,CAmFlF"}

package/dist/specs/businessMap.js

@@ -0,0 +1,119 @@
+/*
+ * 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.
+ */
+const RELATION_KINDS = ['depends-on', 'shares-state', 'navigates-to'];
+const RELATION_RE = new RegExp(`^\\s*-\\s+(.+?)\\s+(${RELATION_KINDS.join('|')})\\s+(.+?)\\s*$`);
+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 inRelationships = false;
+    let covered = 0;
+    let lineCount = 0;
+    let areaCount = 0;
+    // name-slug → line node id, so the `## Relationships` block can resolve a line
+    // by its label regardless of which area it sits under. First-defined wins.
+    const lineBySlug = new Map();
+    const rawRelations = [];
+    for (const raw of md.split('\n')) {
+        const line = raw.trimEnd();
+        const areaM = line.match(/^##\s+(.+)$/);
+        if (areaM) {
+            const label = areaM[1].trim();
+            // The Relationships block is metadata, not an area — don't node it; its
+            // items are edges (parsed below), not business lines.
+            if (slug(label) === 'relationships') {
+                inRelationships = true;
+                area = null;
+                continue;
+            }
+            inRelationships = false;
+            const id = `area:${slug(label)}`;
+            area = { id };
+            add({ id, label, kind: 'area' });
+            edges.push({ source: 'app', target: id });
+            areaCount++;
+            continue;
+        }
+        if (inRelationships) {
+            const relM = line.match(RELATION_RE);
+            if (relM)
+                rawRelations.push({ source: relM[1].trim(), kind: relM[2], target: relM[3].trim() });
+            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 });
+            if (!lineBySlug.has(slug(name)))
+                lineBySlug.set(slug(name), lineId);
+            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 });
+            }
+        }
+    }
+    // Resolve relationships against the lines now that all are known; an edge whose
+    // endpoints don't both name a known line is dropped (a stale/typo'd reference).
+    const relations = [];
+    for (const r of rawRelations) {
+        const source = lineBySlug.get(slug(r.source));
+        const target = lineBySlug.get(slug(r.target));
+        if (source && target && source !== target)
+            relations.push({ source, target, kind: r.kind });
+    }
+    return { app, nodes, edges, relations, stats: { lines: lineCount, covered, areas: areaCount } };
+}

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/wikiLog.d.ts

@@ -0,0 +1,14 @@
+export type WikiLogKind = 'crystallize' | 'api' | 'extract' | 'heal' | 'note';
+export interface WikiLogEntry {
+    /** ISO-8601 timestamp. */
+    iso: string;
+    kind: string;
+    summary: string;
+}
+export declare function wikiLogPath(devRoot: string): string;
+/** Append one event line. Best-effort — never throws. */
+export declare function appendWikiLog(devRoot: string, kind: WikiLogKind, summary: string): Promise<void>;
+/** Read the log's most recent entries (oldest→newest), parsed. Total: a missing
+ *  or malformed file yields []. */
+export declare function readWikiLog(devRoot: string, limit?: number): Promise<WikiLogEntry[]>;
+//# sourceMappingURL=wikiLog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wikiLog.d.ts","sourceRoot":"","sources":["../../src/specs/wikiLog.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,yDAAyD;AACzD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBtG;AAED;mCACmC;AACnC,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAYvF"}

package/dist/specs/wikiLog.js

@@ -0,0 +1,58 @@
+/*
+ * LLM-Wiki P3 — `.hover/log.md`: an append-only, machine-parseable run history
+ * for the app's test wiki. One event per line:
+ *
+ *   - <ISO timestamp> · <kind> · <summary>
+ *
+ * Hover writes it deterministically as it MUTATES the wiki (a spec crystallized,
+ * an API spec locked, Page Objects extracted) — no dependence on the agent
+ * remembering to log, and no prompt churn. It powers an auditable timeline (and
+ * a future cockpit history view). Best-effort by contract: a log failure must
+ * NEVER break a crystallize / extract — same rule as the memory + run ledger.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hoverDir } from './sidecar.js';
+const HEADER = '# Hover log\n\n' +
+    "Append-only run history for this app's test wiki. One event per line: " +
+    '`- <ISO> · <kind> · <summary>`.\n\n';
+export function wikiLogPath(devRoot) {
+    return join(hoverDir(devRoot), 'log.md');
+}
+/** Append one event line. Best-effort — never throws. */
+export async function appendWikiLog(devRoot, kind, summary) {
+    try {
+        await mkdir(hoverDir(devRoot), { recursive: true });
+        const path = wikiLogPath(devRoot);
+        let existing = '';
+        try {
+            existing = await readFile(path, 'utf-8');
+        }
+        catch {
+            /* new file → write the header first */
+        }
+        const iso = new Date().toISOString();
+        const line = `- ${iso} · ${kind} · ${summary.replace(/\s+/g, ' ').trim()}\n`;
+        await appendFile(path, `${existing ? '' : HEADER}${line}`, 'utf-8');
+    }
+    catch {
+        /* best-effort: a wiki-log failure must not break the write that triggered it */
+    }
+}
+/** Read the log's most recent entries (oldest→newest), parsed. Total: a missing
+ *  or malformed file yields []. */
+export async function readWikiLog(devRoot, limit = 200) {
+    try {
+        const raw = await readFile(wikiLogPath(devRoot), 'utf-8');
+        const entries = [];
+        for (const l of raw.split('\n')) {
+            const m = l.match(/^-\s+(\S+)\s+·\s+(\w+)\s+·\s+(.+)$/);
+            if (m)
+                entries.push({ iso: m[1], kind: m[2], summary: m[3].trim() });
+        }
+        return entries.slice(-limit);
+    }
+    catch {
+        return [];
+    }
+}

package/package.json

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