@hover-dev/core 0.23.0 → 0.25.0

package/dist/engine.d.ts

@@ -18,8 +18,10 @@ 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 { buildOptimizeBrief, saveOptimizedCandidate, promoteOptimizedCandidate, 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';

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;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"}
+{"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,yBAAyB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/H,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

@@ -19,7 +19,9 @@ export { reRenderSpec } from './specs/writeSpec.js';
 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';
+export { buildOptimizeBrief, saveOptimizedCandidate, promoteOptimizedCandidate, 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';

package/dist/specs/businessMap.d.ts

@@ -1,5 +1,8 @@
 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;
@@ -12,10 +15,18 @@ 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;

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

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

@@ -8,6 +8,8 @@
  * 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()
@@ -50,14 +52,27 @@ export function parseBusinessMap(md, fallbackApp = 'app') {
     }
     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' });
@@ -65,6 +80,12 @@ export function parseBusinessMap(md, fallbackApp = 'app') {
             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';
@@ -72,6 +93,8 @@ export function parseBusinessMap(md, fallbackApp = 'app') {
             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')
@@ -83,5 +106,14 @@ export function parseBusinessMap(md, fallbackApp = 'app') {
             }
         }
     }
-    return { app, nodes, edges, stats: { lines: lineCount, covered, areas: areaCount } };
+    // 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/optimizeSpec.d.ts

@@ -54,6 +54,16 @@ export declare function saveOptimizedCandidate(devRoot: string, slug: string, ll
     candidatePath: string;
     code: string;
 }>;
+/**
+ * Promote a reviewed optimization candidate: overwrite the real spec with the
+ * `.hover/cache/optimized/<slug>.spec.ts.draft` and remove the draft. This is the
+ * one place a candidate replaces the original — done ONLY on the user's say-so
+ * (they reviewed the diff), never automatically as part of optimize. Re-validates
+ * the draft (in case it was hand-edited) before applying. Throws if no draft.
+ */
+export declare function promoteOptimizedCandidate(devRoot: string, slug: string): Promise<{
+    path: string;
+}>;
 /**
  * Build the codegen prompt: the current spec + the observed session, plus the
  * same rules the deterministic path enforces (semantic selectors, no XPath, no

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,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"}
+{"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,CA+B/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;AA6BD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBxG;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

@@ -10,7 +10,7 @@
  * The LLM call is injected (`runCodegen`) so callers wire their own agent and
  * tests run deterministically without spawning anything.
  */
-import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, readdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Project } from 'ts-morph';
 import { readSidecar } from './sidecar.js';
@@ -85,8 +85,9 @@ export async function buildOptimizeBrief(devRoot, slug) {
         `.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.`;
+        `back with a ✗ (a rejected check), fix that and call it again. Then show the user the ` +
+        `diff vs __vibe_tests__/${slug}.spec.ts; if they approve, call \`promote_optimized_spec("${slug}")\` ` +
+        `to apply it (it overwrites the spec + removes the draft — no manual mv). They can also promote in the VS Code cockpit.`;
     return { prompt: buildOptimizePrompt(draft, sidecar, seeds, suite, outputInstruction), original: draft };
 }
 /**
@@ -115,6 +116,61 @@ export async function saveOptimizedCandidate(devRoot, slug, llmCode) {
     await writeFile(candidatePath, code.endsWith('\n') ? code : `${code}\n`, 'utf-8');
     return { candidatePath, code };
 }
+/** Find the on-disk spec whose basename is `<slug>.spec.ts` under __vibe_tests__/
+ *  (grouped specs live in subfolders), or the flat default path if none exists. */
+async function findSpecPath(devRoot, slug) {
+    const root = join(devRoot, '__vibe_tests__');
+    const want = `${slug}.spec.ts`;
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return null;
+        }
+        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;
+                const hit = await walk(p);
+                if (hit)
+                    return hit;
+            }
+            else if (e.name === want) {
+                return p;
+            }
+        }
+        return null;
+    };
+    return (await walk(root)) ?? join(root, want);
+}
+/**
+ * Promote a reviewed optimization candidate: overwrite the real spec with the
+ * `.hover/cache/optimized/<slug>.spec.ts.draft` and remove the draft. This is the
+ * one place a candidate replaces the original — done ONLY on the user's say-so
+ * (they reviewed the diff), never automatically as part of optimize. Re-validates
+ * the draft (in case it was hand-edited) before applying. Throws if no draft.
+ */
+export async function promoteOptimizedCandidate(devRoot, slug) {
+    const draftPath = join(devRoot, '.hover', 'cache', 'optimized', `${slug}.spec.ts.draft`);
+    let draft;
+    try {
+        draft = await readFile(draftPath, 'utf-8');
+    }
+    catch {
+        throw new OptimizeError(`no optimization candidate for "${slug}" (looked at ${draftPath}). Run optimize first.`);
+    }
+    const check = validateSpecCode(draft);
+    if (!check.ok) {
+        throw new OptimizeError(`candidate for "${slug}" is invalid — ${check.errors.join('; ')}. Not promoting.`);
+    }
+    const specPath = await findSpecPath(devRoot, slug);
+    await writeFile(specPath, draft.endsWith('\n') ? draft : `${draft}\n`, 'utf-8');
+    await rm(draftPath, { force: true });
+    return { path: specPath };
+}
 /**
  * Build the codegen prompt: the current spec + the observed session, plus the
  * same rules the deterministic path enforces (semantic selectors, no XPath, no

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

@@ -0,0 +1,7 @@
+export { lintWiki, parseRunStatuses } from './specs/lintWiki.js';
+export type { LintResult, LintFinding, LintKind, LintSeverity } from './specs/lintWiki.js';
+export { readWikiLog, wikiLogPath } from './specs/wikiLog.js';
+export type { WikiLogEntry, WikiLogKind } from './specs/wikiLog.js';
+export { parseBusinessMap } from './specs/businessMap.js';
+export type { BusinessMapGraph, MapNode, MapEdge, MapRelation, RelationKind, CoverageStatus } from './specs/businessMap.js';
+//# sourceMappingURL=wiki.d.ts.map

package/dist/wiki.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki.d.ts","sourceRoot":"","sources":["../src/wiki.ts"],"names":[],"mappings":"AAWA,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,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/wiki.js

@@ -0,0 +1,14 @@
+/*
+ * `@hover-dev/core/wiki` — the pure-read entry over `.hover/` (the app's test
+ * wiki): the business-map parser + the Lint health check + the run-history log
+ * reader. Everything here transitively imports ONLY `node:fs` / `node:path`
+ * (and type-only refs) — no playwright, no ts-morph, no engine.
+ *
+ * Why a separate entry from `./engine`: a slim consumer (the VS Code cockpit)
+ * bundles this to render the wiki, and importing the full engine barrel would
+ * drag `playwright-core` + `ts-morph` into its ~220 KB .vsix. This barrel keeps
+ * that consumer's bundle tiny while still sharing one source of truth.
+ */
+export { lintWiki, parseRunStatuses } from './specs/lintWiki.js';
+export { readWikiLog, wikiLogPath } from './specs/wikiLog.js';
+export { parseBusinessMap } from './specs/businessMap.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -30,6 +30,10 @@
     "./engine": {
       "types": "./dist/engine.d.ts",
       "import": "./dist/engine.js"
+    },
+    "./wiki": {
+      "types": "./dist/wiki.d.ts",
+      "import": "./dist/wiki.js"
     }
   },
   "files": [