gsd-pi 2.79.0 → 2.80.0-dev.710c06e97

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -1,12 +1,10 @@
-// tool-naming — Verifies canonical + alias tool registration for GSD DB tools.
-//
-// Each DB tool must register under its canonical gsd_concept_action name
-// AND under a backward-compatible alias name.
-// The alias must share the exact same execute function reference as the canonical tool.
+// Project/App: GSD-2
+// File Purpose: Verifies canonical and alias DB tool registration plus legacy alias telemetry.
 
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { registerDbTools } from '../bootstrap/db-tools.ts';
+import { getLegacyTelemetry, resetLegacyTelemetry } from '../legacy-telemetry.ts';
 
 
 // ─── Mock PI ──────────────────────────────────────────────────────────────────
@@ -66,9 +64,9 @@ for (const { canonical, alias } of RENAME_MAP) {
   assert.ok(aliasTool !== undefined, `Alias tool "${alias}" should be registered`);
 }
 
-// ─── Execute function identity ───────────────────────────────────────────────
+// ─── Execute function wrapping ───────────────────────────────────────────────
 
-console.log('\n── Tool naming: execute function identity (===) ──');
+console.log('\n── Tool naming: alias execute wrapper ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
   const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
@@ -76,12 +74,37 @@ for (const { canonical, alias } of RENAME_MAP) {
 
   if (canonicalTool && aliasTool) {
     assert.ok(
-      canonicalTool.execute === aliasTool.execute,
-      `"${canonical}" and "${alias}" should share the same execute function reference`,
+      canonicalTool.execute !== aliasTool.execute,
+      `"${alias}" should wrap "${canonical}" so alias usage can be counted`,
     );
   }
 }
 
+test("alias execute increments legacy MCP alias telemetry before delegating", async () => {
+  const canonicalTool = pi.tools.find((t: any) => t.name === "gsd_decision_save");
+  const aliasTool = pi.tools.find((t: any) => t.name === "gsd_save_decision");
+  assert.ok(canonicalTool);
+  assert.ok(aliasTool);
+
+  const originalCanonicalExecute = canonicalTool.execute;
+  try {
+    resetLegacyTelemetry();
+    let delegated = false;
+    canonicalTool.execute = async () => {
+      delegated = true;
+      return { content: [{ type: "text", text: "ok" }], details: { ok: true } };
+    };
+
+    await aliasTool.execute("call-1", {}, undefined, undefined, undefined);
+
+    assert.equal(delegated, true);
+    assert.equal(getLegacyTelemetry()["legacy.mcpAliasUsed"], 1);
+  } finally {
+    canonicalTool.execute = originalCanonicalExecute;
+    resetLegacyTelemetry();
+  }
+});
+
 // ─── Alias descriptions include "(alias for ...)" ───────────────────────────
 
 console.log('\n── Tool naming: alias descriptions ──');

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -1,6 +1,5 @@
-// GSD-2 — #4782 phase 2 composer tests. Pure-function tests using mock
-// resolvers plus an integration check that reassess-roadmap's migrated
-// builder produces a prompt matching expectations.
+// Project/App: GSD-2
+// File Purpose: Tests unit context composer rendering, budgets, and reassess-roadmap prompt integration.
 
 import test from "node:test";
 import assert from "node:assert/strict";
@@ -9,6 +8,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  composeContextModeInstructions,
   composeInlinedContext,
   composeUnitContext,
   manifestBudgetChars,
@@ -101,6 +101,44 @@ test("#4782 composer: manifestBudgetChars returns declared budget", () => {
   assert.strictEqual(manifestBudgetChars("never-dispatched"), null);
 });
 
+test("Context Mode composer: disabled, unknown, and none modes return empty string", () => {
+  assert.strictEqual(
+    composeContextModeInstructions("execute-task", { enabled: false, renderMode: "standalone" }),
+    "",
+  );
+  assert.strictEqual(
+    composeContextModeInstructions("never-dispatched", { enabled: true, renderMode: "standalone" }),
+    "",
+  );
+  assert.strictEqual(
+    composeContextModeInstructions("workflow-preferences", { enabled: true, renderMode: "standalone" }),
+    "",
+  );
+});
+
+test("Context Mode composer: standalone output starts with heading and includes required tools", () => {
+  const out = composeContextModeInstructions("execute-task", { enabled: true, renderMode: "standalone" });
+  assert.ok(out.startsWith("## Context Mode"));
+  assert.match(out, /execution lane/i);
+  assert.match(out, /`gsd_exec`/);
+  assert.match(out, /noisy commands/);
+  assert.match(out, /`gsd_exec_search`/);
+  assert.match(out, /before reruns/);
+  assert.match(out, /`gsd_resume`/);
+  assert.match(out, /after compaction or resume/);
+});
+
+test("Context Mode composer: nested output is compact single sentence", () => {
+  const out = composeContextModeInstructions("gate-evaluate", { enabled: true, renderMode: "nested" });
+  assert.ok(!out.startsWith("## Context Mode"));
+  assert.match(out, /^Context Mode \(verification lane\): /);
+  assert.strictEqual(out.split(/\n/).length, 1);
+  assert.match(out, /`gsd_exec`/);
+  assert.match(out, /`gsd_exec_search`/);
+  assert.match(out, /`gsd_resume`/);
+  assert.ok(out.length < 180, `nested guidance should stay compact, got ${out.length} chars`);
+});
+
 // ─── Integration: migrated buildReassessRoadmapPrompt ─────────────────────
 
 function makeFixtureBase(): string {
@@ -186,7 +224,7 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
 
 const fakeBase: BaseResolverContext = {
   unitType: "reassess-roadmap",
-  basePath: "/tmp/fake",
+  basePath: process.env.GSD_TEST_WORKSPACE_ROOT ?? process.cwd(),
   milestoneId: "M001",
   sliceId: "S01",
 };

package/src/resources/extensions/gsd/tests/unit-context-manifest.test.ts

@@ -12,6 +12,7 @@ import {
   UNIT_MANIFESTS,
   resolveManifest,
   type ArtifactKey,
+  type ContextModePolicy,
   type SkillsPolicy,
   type UnitContextManifest,
 } from "../unit-context-manifest.ts";
@@ -105,6 +106,37 @@ test("#4782 phase 1: every manifest has a positive maxSystemPromptChars", () =>
   }
 });
 
+test("Context Mode: every manifest declares the expected contextMode lane", () => {
+  const expected: Record<string, ContextModePolicy> = {
+    "workflow-preferences": "none",
+    "research-decision": "none",
+    "discuss-project": "interview",
+    "discuss-requirements": "interview",
+    "discuss-milestone": "interview",
+    "research-project": "research",
+    "research-milestone": "research",
+    "research-slice": "research",
+    "plan-milestone": "planning",
+    "plan-slice": "planning",
+    "refine-slice": "planning",
+    "replan-slice": "planning",
+    "reassess-roadmap": "planning",
+    "execute-task": "execution",
+    "reactive-execute": "execution",
+    "run-uat": "verification",
+    "gate-evaluate": "verification",
+    "validate-milestone": "verification",
+    "complete-slice": "verification",
+    "complete-milestone": "verification",
+    "rewrite-docs": "docs",
+  };
+
+  assert.deepEqual(Object.keys(expected).sort(), [...KNOWN_UNIT_TYPES].sort());
+  for (const unitType of KNOWN_UNIT_TYPES) {
+    assert.strictEqual(UNIT_MANIFESTS[unitType].contextMode, expected[unitType]);
+  }
+});
+
 test("#4782 phase 1: skills policy shapes are valid discriminated-union members", () => {
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const p = manifest.skills as SkillsPolicy;

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/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",
+  }]);
+});