gsd-pi 2.79.0 → 2.80.0-dev.4ea7d80e7

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -1,5 +1,10 @@
+// GSD2 UOK Contract Versioning and DB Authority Tests
+
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import type {
   AuditEventEnvelope,
@@ -11,8 +16,17 @@ import type {
   WriteRecord,
   WriterToken,
 } from "../uok/contracts.ts";
-import { buildAuditEnvelope } from "../uok/audit.ts";
+import {
+  CURRENT_UOK_CONTRACT_VERSION,
+  normalizeAuditEvent,
+  validateAuditEvent,
+  validateDispatchEnvelope,
+  validateTurnResult,
+} from "../uok/contracts.ts";
+import { buildAuditEnvelope, emitUokAuditEvent } from "../uok/audit.ts";
 import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
+import { buildTurnTimeline } from "../uok/timeline.ts";
+import { _getAdapter, closeDatabase, openDatabase } from "../gsd-db.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -37,6 +51,7 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
   };
 
   const result: TurnResult = {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     traceId: contract.traceId,
     turnId: contract.turnId,
     iteration: contract.iteration,
@@ -56,8 +71,10 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
 
   const roundTrip = JSON.parse(JSON.stringify(result)) as TurnResult;
   assert.equal(roundTrip.turnId, "turn-1");
+  assert.equal(roundTrip.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(roundTrip.gateResults?.[0]?.gateId, "Q3");
   assert.equal(roundTrip.phaseResults.length, 3);
+  assert.equal(validateTurnResult(roundTrip).ok, true);
 });
 
 test("uok contracts include required DAG node kinds", () => {
@@ -84,9 +101,11 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   });
 
   assert.equal(event.traceId, "trace-xyz");
+  assert.equal(event.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(event.turnId, "turn-xyz");
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
+  assert.equal(validateAuditEvent(event).ok, true);
 });
 
 test("uok dispatch envelope carries scheduler reason and constraints", () => {
@@ -107,9 +126,98 @@ test("uok dispatch envelope carries scheduler reason and constraints", () => {
   });
 
   assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(envelope.reason.reasonCode, "dependency");
   assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
   assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+  assert.equal(validateDispatchEnvelope(envelope).ok, true);
+});
+
+test("uok contracts normalize legacy records without losing payload fields", () => {
+  const legacy = {
+    eventId: "event-legacy",
+    traceId: "trace-legacy",
+    category: "orchestration",
+    type: "turn-result",
+    ts: new Date().toISOString(),
+    payload: { status: "completed", extra: "preserved" },
+  } as AuditEventEnvelope;
+
+  const normalized = normalizeAuditEvent(legacy);
+  assert.equal(normalized.version, "0");
+  assert.equal(normalized.payload.extra, "preserved");
+  assert.equal(validateAuditEvent(legacy).ok, true);
+});
+
+test("uok audit emission writes DB as authoritative before jsonl projection", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-db-audit-"));
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-db",
+      turnId: "turn-db",
+      category: "orchestration",
+      type: "turn-start",
+      payload: { unitType: "execute-task" },
+    }),
+  );
+
+  const row = _getAdapter()!.prepare(
+    "SELECT payload_json FROM audit_events WHERE trace_id = 'trace-db' AND turn_id = 'turn-db'",
+  ).get() as { payload_json: string } | undefined;
+  assert.ok(row, "DB audit row should be written");
+  assert.equal(JSON.parse(row.payload_json).contractVersion, CURRENT_UOK_CONTRACT_VERSION);
+
+  const projection = readFileSync(join(basePath, ".gsd", "audit", "events.jsonl"), "utf-8");
+  assert.ok(projection.includes("trace-db"), "jsonl projection should still be written");
+});
+
+test("uok timeline prefers DB records over jsonl projection when DB is available", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-timeline-"));
+  const auditDir = join(basePath, ".gsd", "audit");
+  mkdirSync(auditDir, { recursive: true });
+  writeFileSync(
+    join(auditDir, "events.jsonl"),
+    `${JSON.stringify({
+      version: CURRENT_UOK_CONTRACT_VERSION,
+      eventId: "jsonl-only",
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "jsonl-projection",
+      ts: "2026-01-01T00:00:00.000Z",
+      payload: {},
+    })}\n`,
+  );
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "db-authoritative",
+      payload: {},
+    }),
+  );
+
+  const timeline = buildTurnTimeline(basePath, { traceId: "trace-timeline", turnId: "turn-timeline" });
+  assert.equal(timeline.authoritative, "db");
+  assert.equal(timeline.degraded, false);
+  assert.ok(timeline.entries.some((entry) => entry.type === "db-authoritative"));
+  assert.equal(timeline.entries.some((entry) => entry.type === "jsonl-projection"), false);
 });
 
 test("uok writer records serialize sequence metadata", () => {

package/src/resources/extensions/gsd/tests/uok-kernel-path.test.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Verifies UOK kernel path selection and legacy fallback telemetry.
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -11,6 +13,7 @@ import type { AutoSession } from "../auto/session.ts";
 import type { LoopDeps } from "../auto/loop-deps.ts";
 import { gsdRoot } from "../paths.ts";
 import type { GSDPreferences } from "../preferences.ts";
+import { getLegacyTelemetry, resetLegacyTelemetry } from "../legacy-telemetry.ts";
 
 function makeBasePath(): string {
   return mkdtempSync(join(tmpdir(), "gsd-uok-kernel-"));
@@ -86,6 +89,7 @@ function readParityEvents(basePath: string): Array<Record<string, unknown>> {
 test("runAutoLoopWithUok uses kernel path by default and records uok-kernel parity", async () => {
   const basePath = makeBasePath();
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -109,7 +113,9 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
     assert.equal(events[1]?.path, "uok-kernel");
     assert.equal(events[1]?.phase, "exit");
     assert.equal(events[1]?.status, "ok");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 0);
   } finally {
+    resetLegacyTelemetry();
     rmSync(basePath, { recursive: true, force: true });
   }
 });
@@ -117,6 +123,7 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
 test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabled", async () => {
   const basePath = makeBasePath();
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -134,7 +141,9 @@ test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabl
     assert.equal(events[0]?.path, "legacy-fallback");
     assert.equal(events[1]?.path, "legacy-fallback");
     assert.equal(events[1]?.status, "ok");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 1);
   } finally {
+    resetLegacyTelemetry();
     rmSync(basePath, { recursive: true, force: true });
   }
 });
@@ -144,6 +153,7 @@ test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async
   const previous = process.env.GSD_UOK_FORCE_LEGACY;
   process.env.GSD_UOK_FORCE_LEGACY = "1";
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -158,7 +168,9 @@ test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async
     assert.equal(events.length, 2);
     assert.equal(events[0]?.path, "legacy-fallback");
     assert.equal(events[1]?.path, "legacy-fallback");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 1);
   } finally {
+    resetLegacyTelemetry();
     if (previous === undefined) delete process.env.GSD_UOK_FORCE_LEGACY;
     else process.env.GSD_UOK_FORCE_LEGACY = previous;
     rmSync(basePath, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/uok-loop-adapter-writer.test.ts

@@ -63,3 +63,101 @@ test("uok turn observer adds writer sequence metadata to audit events", (t) => {
   assert.equal(payloads[1]?.writeSequence, 2);
   assert.equal(typeof payloads[0]?.writerTokenId, "string");
 });
+
+test("uok turn observer releases writer token when validation throws", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-throw-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-throw",
+    turnId: "turn-throw",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), true);
+
+  // Invalid payload (missing required fields like status/finishedAt) should
+  // trigger validateTurnResult to fail and throw.
+  assert.throws(() => {
+    observer.onTurnResult({
+      traceId: "trace-throw",
+      turnId: "turn-throw",
+      // @ts-expect-error intentionally invalid for test
+      iteration: "not-a-number",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      phaseResults: [],
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  }, /Invalid UOK turn result/);
+
+  // Cleanup must run in finally — token released, no leaked state.
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), false);
+});
+
+test("uok turn observer falls back to cached phaseResults when result.phaseResults is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-missing-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-missing",
+    turnId: "turn-missing",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+
+  // Without the Array.isArray guard, accessing result.phaseResults.length on a
+  // payload where phaseResults is undefined would throw TypeError before
+  // validateTurnResult could surface a structured error. The guard must defer
+  // to the cached phaseResults fallback so the turn completes cleanly.
+  assert.doesNotThrow(() => {
+    observer.onTurnResult({
+      traceId: "trace-missing",
+      turnId: "turn-missing",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      // @ts-expect-error intentionally missing for test
+      phaseResults: undefined,
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  });
+
+  assert.equal(hasActiveWriterToken(basePath, "turn-missing"), false);
+});

package/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts

@@ -118,7 +118,7 @@ test("guided flow checks pending deep setup before plan-v2 gate", () => {
   const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
   const showSmartEntryIdx = source.indexOf("export async function showSmartEntry");
   assert.notEqual(showSmartEntryIdx, -1);
-  const deepIdx = source.indexOf("hasPendingDeepStage(prefs, basePath)", showSmartEntryIdx);
+  const deepIdx = source.indexOf("shouldRunDeepProjectSetup(state, prefs, basePath)", showSmartEntryIdx);
   const planIdx = source.indexOf("runPlanV2Gate(ctx, basePath, state)", showSmartEntryIdx);
   assert.ok(
     deepIdx > -1 && planIdx > -1 && deepIdx < planIdx,

package/src/resources/extensions/gsd/tests/workflow-custom-engine-dispatch-outcome.test.ts

@@ -0,0 +1,55 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for custom-engine dispatch outcome side-effect adapter.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { handleCustomEngineDispatchOutcome } from "../auto/workflow-custom-engine-dispatch-outcome.ts";
+
+test("handleCustomEngineDispatchOutcome stops auto on stop decision", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "stop", reason: "done" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "break" });
+  assert.deepEqual(calls, [["stopAuto", "done"]]);
+});
+
+test("handleCustomEngineDispatchOutcome continues on skip decision", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "skip" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "continue" });
+  assert.deepEqual(calls, []);
+});
+
+test("handleCustomEngineDispatchOutcome dispatches without side effects", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "dispatch" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "dispatch" });
+  assert.deepEqual(calls, []);
+});

package/src/resources/extensions/gsd/tests/workflow-custom-engine-iteration.test.ts

@@ -0,0 +1,93 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for auto-mode custom-engine iteration-data adapter.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { GSDState } from "../types.ts";
+import { buildCustomEngineIterationData } from "../auto/workflow-custom-engine-iteration.ts";
+
+test("buildCustomEngineIterationData derives state from canonical project root", async () => {
+  const roots: string[] = [];
+
+  await buildCustomEngineIterationData({
+    step: { unitType: "engine-task", unitId: "E001", prompt: "Run engine task" },
+    basePath: "/worktree",
+    canonicalProjectRoot: "/project",
+    currentMilestoneId: "M001",
+    deriveState: async root => {
+      roots.push(root);
+      return { phase: "executing" } as GSDState;
+    },
+    logPostDerive: () => {},
+  });
+
+  assert.deepEqual(roots, ["/project"]);
+});
+
+test("buildCustomEngineIterationData maps engine step into iteration data", async () => {
+  const state = {
+    phase: "executing",
+    activeMilestone: { id: "M001", title: "Milestone 1" },
+  } as GSDState;
+
+  const iterData = await buildCustomEngineIterationData({
+    step: { unitType: "engine-task", unitId: "E001", prompt: "Run engine task" },
+    basePath: "/worktree",
+    canonicalProjectRoot: "/project",
+    currentMilestoneId: "M001",
+    deriveState: async () => state,
+    logPostDerive: () => {},
+  });
+
+  assert.equal(iterData.unitType, "engine-task");
+  assert.equal(iterData.unitId, "E001");
+  assert.equal(iterData.prompt, "Run engine task");
+  assert.equal(iterData.finalPrompt, "Run engine task");
+  assert.equal(iterData.pauseAfterUatDispatch, false);
+  assert.equal(iterData.state, state);
+  assert.equal(iterData.mid, "M001");
+  assert.equal(iterData.midTitle, "Workflow");
+  assert.equal(iterData.isRetry, false);
+  assert.equal(iterData.previousTier, undefined);
+});
+
+test("buildCustomEngineIterationData defaults milestone id to workflow", async () => {
+  const iterData = await buildCustomEngineIterationData({
+    step: { unitType: "engine-task", unitId: "E001", prompt: "Run engine task" },
+    basePath: "/worktree",
+    canonicalProjectRoot: "/project",
+    currentMilestoneId: null,
+    deriveState: async () => ({ phase: "executing" }) as GSDState,
+    logPostDerive: () => {},
+  });
+
+  assert.equal(iterData.mid, "workflow");
+  assert.equal(iterData.midTitle, "Workflow");
+});
+
+test("buildCustomEngineIterationData logs active unit details", async () => {
+  const logs: unknown[] = [];
+
+  await buildCustomEngineIterationData({
+    step: { unitType: "engine-task", unitId: "E001", prompt: "Run engine task" },
+    basePath: "/worktree",
+    canonicalProjectRoot: "/project",
+    currentMilestoneId: "M001",
+    deriveState: async () => ({
+      phase: "planning",
+      activeMilestone: { id: "M001", title: "Milestone 1" },
+      activeSlice: { id: "S01" },
+      activeTask: { id: "T01" },
+    }) as GSDState,
+    logPostDerive: details => logs.push(details),
+  });
+
+  assert.deepEqual(logs, [{
+    site: "custom-engine-gsd-state",
+    basePath: "/worktree",
+    canonicalProjectRoot: "/project",
+    derivedPhase: "planning",
+    activeUnit: "T01",
+  }]);
+});

package/src/resources/extensions/gsd/tests/workflow-custom-engine-reconcile-outcome.test.ts

@@ -0,0 +1,108 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for custom-engine reconcile outcome side-effect adapter.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  handleCustomEngineReconcileOutcome,
+  type HandleCustomEngineReconcileOutcomeDeps,
+} from "../auto/workflow-custom-engine-reconcile-outcome.ts";
+
+function makeDeps(): {
+  deps: HandleCustomEngineReconcileOutcomeDeps;
+  calls: unknown[];
+} {
+  const calls: unknown[] = [];
+  const deps: HandleCustomEngineReconcileOutcomeDeps = {
+    stopAuto: async reason => {
+      calls.push(["stopAuto", reason]);
+    },
+    pauseAuto: async () => {
+      calls.push(["pauseAuto"]);
+    },
+    report: (action, details) => calls.push(["report", action, details]),
+    finishTurn: (status, failureClass, error) => calls.push(["finishTurn", status, failureClass, error]),
+  };
+  return { deps, calls };
+}
+
+test("handleCustomEngineReconcileOutcome stops completed workflow", async () => {
+  const { deps, calls } = makeDeps();
+
+  const flow = await handleCustomEngineReconcileOutcome({
+    outcome: {
+      decision: { action: "complete-workflow", stopReason: "Workflow complete" },
+    },
+    unitType: "execute-task",
+    unitId: "T01",
+    deps,
+  });
+
+  assert.deepEqual(flow, { action: "break" });
+  assert.deepEqual(calls, [
+    ["stopAuto", "Workflow complete"],
+    ["report", "milestone-complete", { unitType: "execute-task", unitId: "T01" }],
+    ["finishTurn", "completed", undefined, undefined],
+  ]);
+});
+
+test("handleCustomEngineReconcileOutcome pauses for manual attention", async () => {
+  const { deps, calls } = makeDeps();
+
+  const flow = await handleCustomEngineReconcileOutcome({
+    outcome: {
+      decision: { action: "pause" },
+    },
+    unitType: "verify-slice",
+    unitId: "S01",
+    deps,
+  });
+
+  assert.deepEqual(flow, { action: "break" });
+  assert.deepEqual(calls, [
+    ["pauseAuto"],
+    ["report", "pause", { unitType: "verify-slice", unitId: "S01" }],
+    ["finishTurn", "paused", "manual-attention", undefined],
+  ]);
+});
+
+test("handleCustomEngineReconcileOutcome stops with reconcile reason", async () => {
+  const { deps, calls } = makeDeps();
+
+  const flow = await handleCustomEngineReconcileOutcome({
+    outcome: {
+      decision: { action: "stop", reason: "blocked" },
+      reason: "blocked",
+    },
+    unitType: "complete-slice",
+    unitId: "S01",
+    deps,
+  });
+
+  assert.deepEqual(flow, { action: "break" });
+  assert.deepEqual(calls, [
+    ["stopAuto", "blocked"],
+    ["report", "stop", { unitType: "complete-slice", unitId: "S01", reason: "blocked" }],
+    ["finishTurn", "stopped", "manual-attention", "blocked"],
+  ]);
+});
+
+test("handleCustomEngineReconcileOutcome continues after completed unit", async () => {
+  const { deps, calls } = makeDeps();
+
+  const flow = await handleCustomEngineReconcileOutcome({
+    outcome: {
+      decision: { action: "continue" },
+    },
+    unitType: "research-slice",
+    unitId: "S01",
+    deps,
+  });
+
+  assert.deepEqual(flow, { action: "continue" });
+  assert.deepEqual(calls, [
+    ["report", "continue", { unitType: "research-slice", unitId: "S01" }],
+    ["finishTurn", "completed", undefined, undefined],
+  ]);
+});