gsd-pi 2.45.0-dev.fdcf73c → 2.46.0-dev.cc9d310

package/src/resources/extensions/gsd/workflow-events.ts

@@ -0,0 +1,154 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+
+// ─── Session ID ───────────────────────────────────────────────────────────
+
+/**
+ * Engine-generated session ID — stable for the lifetime of this process.
+ * Agents can reference this to correlate all events from one run.
+ */
+const ENGINE_SESSION_ID: string = randomUUID();
+
+export function getSessionId(): string {
+  return ENGINE_SESSION_ID;
+}
+
+// ─── Event Types ─────────────────────────────────────────────────────────
+
+export interface WorkflowEvent {
+  cmd: string;           // e.g. "complete_task"
+  params: Record<string, unknown>;
+  ts: string;            // ISO 8601
+  hash: string;          // content hash (hex, 16 chars)
+  actor: "agent" | "system";
+  actor_name?: string;      // e.g. "executor-agent-01" — caller-provided identity
+  trigger_reason?: string;  // e.g. "plan-phase complete" — caller-provided causation
+  session_id: string;       // engine-generated UUID, stable per process lifetime
+}
+
+// ─── appendEvent ─────────────────────────────────────────────────────────
+
+/**
+ * Append one event to .gsd/event-log.jsonl.
+ * Computes a content hash from cmd+params (deterministic, independent of ts/actor/session).
+ * Creates .gsd directory if needed.
+ */
+export function appendEvent(
+  basePath: string,
+  event: Omit<WorkflowEvent, "hash" | "session_id"> & { actor_name?: string; trigger_reason?: string },
+): void {
+  const hash = createHash("sha256")
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params, ts: event.ts }))
+    .digest("hex")
+    .slice(0, 16);
+
+  const fullEvent: WorkflowEvent = {
+    ...event,
+    hash,
+    session_id: ENGINE_SESSION_ID,
+  };
+  const dir = join(basePath, ".gsd");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+}
+
+// ─── readEvents ──────────────────────────────────────────────────────────
+
+/**
+ * Read all events from a JSONL file.
+ * Returns empty array if file doesn't exist.
+ * Corrupted lines are skipped with stderr warning.
+ */
+export function readEvents(logPath: string): WorkflowEvent[] {
+  if (!existsSync(logPath)) {
+    return [];
+  }
+
+  const content = readFileSync(logPath, "utf-8");
+  const lines = content.split("\n").filter((l) => l.length > 0);
+  const events: WorkflowEvent[] = [];
+
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line) as WorkflowEvent);
+    } catch {
+      process.stderr.write(`workflow-events: skipping corrupted event line: ${line.slice(0, 80)}\n`);
+    }
+  }
+
+  return events;
+}
+
+// ─── findForkPoint ───────────────────────────────────────────────────────
+
+/**
+ * Find the index of the last common event between two logs by comparing hashes.
+ * Returns -1 if the first events differ (completely diverged).
+ * If one log is a prefix of the other, returns length of shorter - 1.
+ */
+export function findForkPoint(
+  logA: WorkflowEvent[],
+  logB: WorkflowEvent[],
+): number {
+  const minLen = Math.min(logA.length, logB.length);
+  let lastCommon = -1;
+
+  for (let i = 0; i < minLen; i++) {
+    if (logA[i]!.hash === logB[i]!.hash) {
+      lastCommon = i;
+    } else {
+      break;
+    }
+  }
+
+  return lastCommon;
+}
+
+// ─── compactMilestoneEvents ─────────────────────────────────────────────────
+
+/**
+ * Archive a milestone's events from the active log to a separate file.
+ * Active log retains only events from other milestones.
+ * Archived file is kept on disk for forensics.
+ *
+ * @param basePath - Project root (parent of .gsd/)
+ * @param milestoneId - The milestone whose events should be archived
+ * @returns { archived: number } — count of events moved to archive
+ */
+export function compactMilestoneEvents(
+  basePath: string,
+  milestoneId: string,
+): { archived: number } {
+  const logPath = join(basePath, ".gsd", "event-log.jsonl");
+  const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+
+  const allEvents = readEvents(logPath);
+  const toArchive = allEvents.filter(
+    (e) => (e.params as { milestoneId?: string }).milestoneId === milestoneId,
+  );
+  const remaining = allEvents.filter(
+    (e) => (e.params as { milestoneId?: string }).milestoneId !== milestoneId,
+  );
+
+  if (toArchive.length === 0) {
+    return { archived: 0 };
+  }
+
+  // Write archived events to .jsonl.archived file (crash-safe)
+  atomicWriteSync(
+    archivePath,
+    toArchive.map((e) => JSON.stringify(e)).join("\n") + "\n",
+  );
+
+  // Truncate active log to remaining events only
+  atomicWriteSync(
+    logPath,
+    remaining.length > 0
+      ? remaining.map((e) => JSON.stringify(e)).join("\n") + "\n"
+      : "",
+  );
+
+  return { archived: toArchive.length };
+}

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -2,6 +2,7 @@
 // Centralized warning/error accumulator for the workflow engine pipeline.
 // Captures structured entries that the auto-loop can drain after each unit
 // to surface root causes for stuck loops, silent degradation, and blocked writes.
+// All entries are also persisted to .gsd/audit-log.jsonl for post-mortem analysis.
 //
 // Stderr policy: every logWarning/logError call writes immediately to stderr
 // for terminal visibility. This is intentional — unlike debug-logger (which is
@@ -13,6 +14,9 @@
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
 
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
 // ─── Types ──────────────────────────────────────────────────────────────
 
 export type LogSeverity = "warn" | "error";
@@ -38,10 +42,20 @@ export interface LogEntry {
   context?: Record<string, string>;
 }
 
-// ─── Buffer ─────────────────────────────────────────────────────────────
+// ─── Buffer & Persistent Audit ──────────────────────────────────────────
 
 const MAX_BUFFER = 100;
 let _buffer: LogEntry[] = [];
+let _auditBasePath: string | null = null;
+
+/**
+ * Set the base path for persistent audit log writes.
+ * Should be called once at engine init with the project root.
+ * Until set, log entries are buffered in-memory only.
+ */
+export function setLogBasePath(basePath: string): void {
+  _auditBasePath = basePath;
+}
 
 // ─── Public API ─────────────────────────────────────────────────────────
 
@@ -156,12 +170,36 @@ export function formatForNotification(entries: readonly LogEntry[]): string {
     .join("\n");
 }
 
+/**
+ * Read all entries from the persistent audit log.
+ * Returns empty array if no basePath is set or the file doesn't exist.
+ */
+export function readAuditLog(basePath?: string): LogEntry[] {
+  const bp = basePath ?? _auditBasePath;
+  if (!bp) return [];
+  const auditPath = join(bp, ".gsd", "audit-log.jsonl");
+  if (!existsSync(auditPath)) return [];
+  try {
+    const content = readFileSync(auditPath, "utf-8");
+    return content
+      .split("\n")
+      .filter((l) => l.length > 0)
+      .map((l) => {
+        try { return JSON.parse(l) as LogEntry; } catch { return null; }
+      })
+      .filter((e): e is LogEntry => e !== null);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Reset buffer. Call at the start of each auto-loop unit to prevent log bleed
  * between units running in the same process. Also used in tests via _resetLogs().
  */
 export function _resetLogs(): void {
   _buffer = [];
+  _auditBasePath = null;
 }
 
 // ─── Internal ───────────────────────────────────────────────────────────
@@ -190,4 +228,16 @@ function _push(
   if (_buffer.length > MAX_BUFFER) {
     _buffer.shift();
   }
+
+  // Persist to .gsd/audit-log.jsonl so entries survive context resets
+  if (_auditBasePath) {
+    try {
+      const auditDir = join(_auditBasePath, ".gsd");
+      mkdirSync(auditDir, { recursive: true });
+      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(entry) + "\n", "utf-8");
+    } catch (auditErr) {
+      // Best-effort — never let audit write failures bubble up
+      process.stderr.write(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);
+    }
+  }
 }

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -0,0 +1,334 @@
+import {
+  _getAdapter,
+  transaction,
+  type MilestoneRow,
+  type SliceRow,
+  type TaskRow,
+} from "./gsd-db.js";
+import type { Decision } from "./types.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Manifest Types ──────────────────────────────────────────────────────
+
+export interface VerificationEvidenceRow {
+  id: number;
+  task_id: string;
+  slice_id: string;
+  milestone_id: string;
+  command: string;
+  exit_code: number | null;
+  verdict: string;
+  duration_ms: number | null;
+  created_at: string;
+}
+
+export interface StateManifest {
+  version: 1;
+  exported_at: string; // ISO 8601
+  milestones: MilestoneRow[];
+  slices: SliceRow[];
+  tasks: TaskRow[];
+  decisions: Decision[];
+  verification_evidence: VerificationEvidenceRow[];
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────
+
+function requireDb() {
+  const db = _getAdapter();
+  if (!db) throw new Error("workflow-manifest: No database open");
+  return db;
+}
+
+// ─── snapshotState ───────────────────────────────────────────────────────
+
+/**
+ * Capture complete DB state as a StateManifest.
+ * Reads all rows from milestones, slices, tasks, decisions, verification_evidence.
+ *
+ * Note: rows returned from raw queries are plain objects with TEXT columns for
+ * JSON arrays. We parse them into typed Row objects using the same logic as
+ * gsd-db helper functions.
+ */
+export function snapshotState(): StateManifest {
+  const db = requireDb();
+
+  // Wrap all reads in a deferred transaction so the snapshot is consistent
+  // (all SELECTs see the same DB state even if a concurrent write lands between them).
+  db.exec("BEGIN DEFERRED");
+
+  try {
+  const rawMilestones = db.prepare("SELECT * FROM milestones ORDER BY id").all() as Record<string, unknown>[];
+  const milestones: MilestoneRow[] = rawMilestones.map((r) => ({
+    id: r["id"] as string,
+    title: r["title"] as string,
+    status: r["status"] as string,
+    depends_on: JSON.parse((r["depends_on"] as string) || "[]"),
+    created_at: r["created_at"] as string,
+    completed_at: (r["completed_at"] as string) ?? null,
+    vision: (r["vision"] as string) ?? "",
+    success_criteria: JSON.parse((r["success_criteria"] as string) || "[]"),
+    key_risks: JSON.parse((r["key_risks"] as string) || "[]"),
+    proof_strategy: JSON.parse((r["proof_strategy"] as string) || "[]"),
+    verification_contract: (r["verification_contract"] as string) ?? "",
+    verification_integration: (r["verification_integration"] as string) ?? "",
+    verification_operational: (r["verification_operational"] as string) ?? "",
+    verification_uat: (r["verification_uat"] as string) ?? "",
+    definition_of_done: JSON.parse((r["definition_of_done"] as string) || "[]"),
+    requirement_coverage: (r["requirement_coverage"] as string) ?? "",
+    boundary_map_markdown: (r["boundary_map_markdown"] as string) ?? "",
+  }));
+
+  const rawSlices = db.prepare("SELECT * FROM slices ORDER BY milestone_id, sequence, id").all() as Record<string, unknown>[];
+  const slices: SliceRow[] = rawSlices.map((r) => ({
+    milestone_id: r["milestone_id"] as string,
+    id: r["id"] as string,
+    title: r["title"] as string,
+    status: r["status"] as string,
+    risk: r["risk"] as string,
+    depends: JSON.parse((r["depends"] as string) || "[]"),
+    demo: (r["demo"] as string) ?? "",
+    created_at: r["created_at"] as string,
+    completed_at: (r["completed_at"] as string) ?? null,
+    full_summary_md: (r["full_summary_md"] as string) ?? "",
+    full_uat_md: (r["full_uat_md"] as string) ?? "",
+    goal: (r["goal"] as string) ?? "",
+    success_criteria: (r["success_criteria"] as string) ?? "",
+    proof_level: (r["proof_level"] as string) ?? "",
+    integration_closure: (r["integration_closure"] as string) ?? "",
+    observability_impact: (r["observability_impact"] as string) ?? "",
+    sequence: (r["sequence"] as number) ?? 0,
+    replan_triggered_at: (r["replan_triggered_at"] as string) ?? null,
+  }));
+
+  const rawTasks = db.prepare("SELECT * FROM tasks ORDER BY milestone_id, slice_id, sequence, id").all() as Record<string, unknown>[];
+  const tasks: TaskRow[] = rawTasks.map((r) => ({
+    milestone_id: r["milestone_id"] as string,
+    slice_id: r["slice_id"] as string,
+    id: r["id"] as string,
+    title: r["title"] as string,
+    status: r["status"] as string,
+    one_liner: (r["one_liner"] as string) ?? "",
+    narrative: (r["narrative"] as string) ?? "",
+    verification_result: (r["verification_result"] as string) ?? "",
+    duration: (r["duration"] as string) ?? "",
+    completed_at: (r["completed_at"] as string) ?? null,
+    blocker_discovered: (r["blocker_discovered"] as number) === 1,
+    deviations: (r["deviations"] as string) ?? "",
+    known_issues: (r["known_issues"] as string) ?? "",
+    key_files: JSON.parse((r["key_files"] as string) || "[]"),
+    key_decisions: JSON.parse((r["key_decisions"] as string) || "[]"),
+    full_summary_md: (r["full_summary_md"] as string) ?? "",
+    description: (r["description"] as string) ?? "",
+    estimate: (r["estimate"] as string) ?? "",
+    files: JSON.parse((r["files"] as string) || "[]"),
+    verify: (r["verify"] as string) ?? "",
+    inputs: JSON.parse((r["inputs"] as string) || "[]"),
+    expected_output: JSON.parse((r["expected_output"] as string) || "[]"),
+    observability_impact: (r["observability_impact"] as string) ?? "",
+    full_plan_md: (r["full_plan_md"] as string) ?? "",
+    sequence: (r["sequence"] as number) ?? 0,
+  }));
+
+  const rawDecisions = db.prepare("SELECT * FROM decisions ORDER BY seq").all() as Record<string, unknown>[];
+  const decisions: Decision[] = rawDecisions.map((r) => ({
+    seq: r["seq"] as number,
+    id: r["id"] as string,
+    when_context: (r["when_context"] as string) ?? "",
+    scope: (r["scope"] as string) ?? "",
+    decision: (r["decision"] as string) ?? "",
+    choice: (r["choice"] as string) ?? "",
+    rationale: (r["rationale"] as string) ?? "",
+    revisable: (r["revisable"] as string) ?? "",
+    made_by: (r["made_by"] as string as Decision["made_by"]) ?? "agent",
+    superseded_by: (r["superseded_by"] as string) ?? null,
+  }));
+
+  const rawEvidence = db.prepare("SELECT * FROM verification_evidence ORDER BY id").all() as Record<string, unknown>[];
+  const verification_evidence: VerificationEvidenceRow[] = rawEvidence.map((r) => ({
+    id: r["id"] as number,
+    task_id: r["task_id"] as string,
+    slice_id: r["slice_id"] as string,
+    milestone_id: r["milestone_id"] as string,
+    command: r["command"] as string,
+    exit_code: (r["exit_code"] as number) ?? null,
+    verdict: (r["verdict"] as string) ?? "",
+    duration_ms: (r["duration_ms"] as number) ?? null,
+    created_at: r["created_at"] as string,
+  }));
+
+  const result: StateManifest = {
+    version: 1,
+    exported_at: new Date().toISOString(),
+    milestones,
+    slices,
+    tasks,
+    decisions,
+    verification_evidence,
+  };
+
+  db.exec("COMMIT");
+  return result;
+  } catch (err) {
+    try { db.exec("ROLLBACK"); } catch { /* ignore rollback failure */ }
+    throw err;
+  }
+}
+
+// ─── restore ─────────────────────────────────────────────────────────────
+
+/**
+ * Atomically replace all workflow state from a manifest.
+ * Runs inside a transaction — if any insert fails, no tables are modified.
+ * Only touches engine tables + decisions. Does NOT modify artifacts or memories.
+ */
+function restore(manifest: StateManifest): void {
+  const db = requireDb();
+
+  transaction(() => {
+    // Clear engine tables (order matters for foreign-key-like consistency)
+    db.exec("DELETE FROM verification_evidence");
+    db.exec("DELETE FROM tasks");
+    db.exec("DELETE FROM slices");
+    db.exec("DELETE FROM milestones");
+    db.exec("DELETE FROM decisions WHERE 1=1");
+
+    // Restore milestones
+    const msStmt = db.prepare(
+      `INSERT INTO milestones (id, title, status, depends_on, created_at, completed_at,
+        vision, success_criteria, key_risks, proof_strategy,
+        verification_contract, verification_integration, verification_operational, verification_uat,
+        definition_of_done, requirement_coverage, boundary_map_markdown)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const m of manifest.milestones) {
+      msStmt.run(
+        m.id, m.title, m.status,
+        JSON.stringify(m.depends_on), m.created_at, m.completed_at,
+        m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks),
+        JSON.stringify(m.proof_strategy),
+        m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat,
+        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown,
+      );
+    }
+
+    // Restore slices
+    const slStmt = db.prepare(
+      `INSERT INTO slices (milestone_id, id, title, status, risk, depends, demo,
+        created_at, completed_at, full_summary_md, full_uat_md,
+        goal, success_criteria, proof_level, integration_closure, observability_impact,
+        sequence, replan_triggered_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const s of manifest.slices) {
+      slStmt.run(
+        s.milestone_id, s.id, s.title, s.status, s.risk,
+        JSON.stringify(s.depends), s.demo,
+        s.created_at, s.completed_at, s.full_summary_md, s.full_uat_md,
+        s.goal, s.success_criteria, s.proof_level, s.integration_closure, s.observability_impact,
+        s.sequence, s.replan_triggered_at,
+      );
+    }
+
+    // Restore tasks
+    const tkStmt = db.prepare(
+      `INSERT INTO tasks (milestone_id, slice_id, id, title, status,
+        one_liner, narrative, verification_result, duration, completed_at,
+        blocker_discovered, deviations, known_issues, key_files, key_decisions,
+        full_summary_md, description, estimate, files, verify,
+        inputs, expected_output, observability_impact, sequence)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const t of manifest.tasks) {
+      tkStmt.run(
+        t.milestone_id, t.slice_id, t.id, t.title, t.status,
+        t.one_liner, t.narrative, t.verification_result, t.duration, t.completed_at,
+        t.blocker_discovered ? 1 : 0, t.deviations, t.known_issues,
+        JSON.stringify(t.key_files), JSON.stringify(t.key_decisions),
+        t.full_summary_md, t.description, t.estimate, JSON.stringify(t.files), t.verify,
+        JSON.stringify(t.inputs), JSON.stringify(t.expected_output),
+        t.observability_impact, t.sequence,
+      );
+    }
+
+    // Restore decisions
+    const dcStmt = db.prepare(
+      `INSERT INTO decisions (seq, id, when_context, scope, decision, choice, rationale, revisable, made_by, superseded_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const d of manifest.decisions) {
+      dcStmt.run(d.seq, d.id, d.when_context, d.scope, d.decision, d.choice, d.rationale, d.revisable, d.made_by, d.superseded_by);
+    }
+
+    // Restore verification evidence
+    const evStmt = db.prepare(
+      `INSERT INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    for (const e of manifest.verification_evidence) {
+      evStmt.run(e.task_id, e.slice_id, e.milestone_id, e.command, e.exit_code, e.verdict, e.duration_ms, e.created_at);
+    }
+  });
+}
+
+// ─── writeManifest ───────────────────────────────────────────────────────
+
+/**
+ * Write current DB state to .gsd/state-manifest.json via atomicWriteSync.
+ * Uses JSON.stringify with 2-space indent for git three-way merge friendliness.
+ */
+export function writeManifest(basePath: string): void {
+  const manifest = snapshotState();
+  const json = JSON.stringify(manifest, null, 2);
+  const dir = join(basePath, ".gsd");
+  mkdirSync(dir, { recursive: true });
+  atomicWriteSync(join(dir, "state-manifest.json"), json);
+}
+
+// ─── readManifest ────────────────────────────────────────────────────────
+
+/**
+ * Read state-manifest.json and return parsed manifest, or null if not found.
+ */
+export function readManifest(basePath: string): StateManifest | null {
+  const manifestPath = join(basePath, ".gsd", "state-manifest.json");
+
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  const raw = readFileSync(manifestPath, "utf-8");
+  const parsed = JSON.parse(raw) as StateManifest;
+
+  if (parsed.version !== 1) {
+    throw new Error(`Unsupported manifest version: ${parsed.version}`);
+  }
+
+  // Validate required fields to avoid cryptic errors during restore
+  if (!Array.isArray(parsed.milestones) || !Array.isArray(parsed.slices) ||
+      !Array.isArray(parsed.tasks) || !Array.isArray(parsed.decisions) ||
+      !Array.isArray(parsed.verification_evidence)) {
+    throw new Error("Malformed manifest: missing or invalid required arrays");
+  }
+
+  return parsed;
+}
+
+// ─── bootstrapFromManifest ──────────────────────────────────────────────
+
+/**
+ * Read state-manifest.json and restore DB state from it.
+ * Returns true if bootstrap succeeded, false if manifest file doesn't exist.
+ */
+export function bootstrapFromManifest(basePath: string): boolean {
+  const manifest = readManifest(basePath);
+
+  if (!manifest) {
+    return false;
+  }
+
+  restore(manifest);
+  return true;
+}