@dzhechkov/harness-core 0.3.63 → 0.3.67

package/src/statusline.ts

@@ -14,12 +14,35 @@
  * @packageDocumentation
  */
 
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { listBrain } from './brain.js';
 
+/**
+ * Live learning state for one in-flight `/feature-adr` run — the per-run visibility panel
+ * that surfaces the Pattern memory loop (POOL learned, RECALLED for this run, STORED this run).
+ * Written by the pipeline at Steps 0/8/9 via `writeFeatureAdrState`; read back on the render
+ * path (readonly, best-effort) by `readFeatureAdrState`.
+ */
+export interface FeatureAdrState {
+  /** The feature slug the pipeline is working on (kebab-case). */
+  readonly slug: string;
+  /** Human-readable step label (e.g. "Step 0", "Step 8 QE"). */
+  readonly step: string;
+  /** Total learned-pattern POOL (all patterns available to recall from) at write time. */
+  readonly pool: number;
+  /** How many patterns this run RECALLED / used to inform its work. */
+  readonly recalled: number;
+  /** How many NEW patterns this run STORED back into the pool. */
+  readonly stored: number;
+  /** ISO timestamp of the write — drives the freshness window on the render path. */
+  readonly ts: string;
+  /** Optional run mode (e.g. "reference", "full-qe", "full-qe-extended"). */
+  readonly mode?: string;
+}
+
 /** A snapshot of dz's self-learning state for one project (all fields best-effort). */
 export interface StatuslineData {
   /** Count of learned patterns in the project's unified memory store. */
@@ -28,6 +51,8 @@ export interface StatuslineData {
   readonly brainSources: number;
   /** Hours since the last `dz consolidate` run, if a watermark is present. */
   readonly consolidatedAgeH?: number;
+  /** Live `/feature-adr` learning state — present ONLY when a fresh run is in flight. */
+  readonly featureAdr?: FeatureAdrState;
 }
 
 /** Path of the SQLite pattern store (the Tier-3 backend). */
@@ -40,6 +65,17 @@ function consolidateWatermarkPath(projectRoot: string): string {
   return join(projectRoot, '.dz', 'memory', 'consolidate.json');
 }
 
+/** Path of the live `/feature-adr` learning-state file (per-run panel source). */
+export function featureAdrStatePath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'feature-adr', 'learning-state.json');
+}
+
+/**
+ * Freshness window for the `/feature-adr` panel: a run older than this is considered finished, so
+ * its state must NOT keep showing a stale panel in the status bar. 30 minutes (in ms).
+ */
+const FEATURE_ADR_FRESH_MS = 30 * 60 * 1_000;
+
 interface ReadonlyCountDb {
   pragma: (s: string) => void;
   prepare: (q: string) => { get: (...a: unknown[]) => unknown };
@@ -114,6 +150,94 @@ function consolidatedAgeHours(projectRoot: string, now: number): number | undefi
   }
 }
 
+/**
+ * Read the live `/feature-adr` learning state for one project — the source of the per-run panel.
+ *
+ * RENDER-PATH DISCIPLINE (statusline pattern #1): this runs inside the ~300ms status-bar refresh, so
+ * it is a plain **readonly** file read, **best-effort**, and NEVER throws — an absent, unreadable, or
+ * corrupt state file collapses to `undefined`, not an exception.
+ *
+ * FRESHNESS: a run whose `ts` is older than {@link FEATURE_ADR_FRESH_MS} is treated as finished and
+ * returns `undefined`, so a stale run can never keep a panel pinned in the status bar.
+ *
+ * @param projectRoot Absolute (or cwd-relative) project directory.
+ * @param now Injectable clock (epoch ms) for the freshness check — defaults to `Date.now()`.
+ */
+export function readFeatureAdrState(projectRoot: string, now: number = Date.now()): FeatureAdrState | undefined {
+  const path = featureAdrStatePath(resolve(projectRoot));
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<FeatureAdrState>;
+    if (typeof parsed.slug !== 'string' || parsed.slug.length === 0) return undefined;
+    if (typeof parsed.step !== 'string' || parsed.step.length === 0) return undefined;
+    if (typeof parsed.ts !== 'string') return undefined;
+    const tsMs = Date.parse(parsed.ts);
+    if (Number.isNaN(tsMs)) return undefined;
+    if (now - tsMs > FEATURE_ADR_FRESH_MS) return undefined; // stale run — do not surface a panel
+    const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    const state: FeatureAdrState = {
+      slug: parsed.slug,
+      step: parsed.step,
+      pool: num(parsed.pool),
+      recalled: num(parsed.recalled),
+      stored: num(parsed.stored),
+      ts: parsed.ts,
+      ...(typeof parsed.mode === 'string' && parsed.mode.length > 0 ? { mode: parsed.mode } : {}),
+    };
+    return state;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Fields the `/feature-adr` pipeline supplies when recording its live learning state. */
+export interface WriteFeatureAdrStateInput {
+  readonly slug: string;
+  readonly step: string;
+  readonly recalled: number;
+  readonly stored: number;
+  readonly mode?: string;
+}
+
+/**
+ * Record the live `/feature-adr` learning state — called by the pipeline at Steps 0/8/9. Computes
+ * `pool` as the total learned-pattern count (via the same readonly {@link countLearnedPatterns} the
+ * panel uses) and writes the JSON with a fresh `ts`. Best-effort: returns the written state, or
+ * `undefined` on any I/O error (this must never break the pipeline).
+ *
+ * @param now Injectable clock (epoch ms) for the write timestamp — defaults to `Date.now()`.
+ */
+export function writeFeatureAdrState(
+  projectRoot: string,
+  input: WriteFeatureAdrStateInput,
+  now: number = Date.now(),
+): FeatureAdrState | undefined {
+  const root = resolve(projectRoot);
+  let pool = 0;
+  try {
+    pool = countLearnedPatterns(root);
+  } catch {
+    pool = 0;
+  }
+  const state: FeatureAdrState = {
+    slug: input.slug,
+    step: input.step,
+    pool,
+    recalled: Number.isFinite(input.recalled) ? input.recalled : 0,
+    stored: Number.isFinite(input.stored) ? input.stored : 0,
+    ts: new Date(now).toISOString(),
+    ...(input.mode !== undefined && input.mode.length > 0 ? { mode: input.mode } : {}),
+  };
+  try {
+    const path = featureAdrStatePath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+  } catch {
+    return undefined;
+  }
+  return state;
+}
+
 /**
  * Gather dz's self-learning counts for one project. FAST + best-effort: every read
  * is guarded so a missing/corrupt `.dz`, absent native module, or locked store
@@ -140,5 +264,19 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
   }
 
   const ageH = consolidatedAgeHours(root, now);
-  return ageH !== undefined ? { patterns, brainSources, consolidatedAgeH: ageH } : { patterns, brainSources };
+
+  // Live /feature-adr panel — attached ONLY when a fresh run is in flight (readonly, never throws).
+  let featureAdr: FeatureAdrState | undefined;
+  try {
+    featureAdr = readFeatureAdrState(root, now);
+  } catch {
+    featureAdr = undefined;
+  }
+
+  return {
+    patterns,
+    brainSources,
+    ...(ageH !== undefined ? { consolidatedAgeH: ageH } : {}),
+    ...(featureAdr !== undefined ? { featureAdr } : {}),
+  };
 }