gsd-pi 2.74.0-dev.b741afb → 2.74.0-dev.ffbcc03

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -26,6 +26,14 @@ import { MAX_FINALIZE_TIMEOUTS } from "../auto/types.ts";
 
 const { assertTrue, assertEq, report } = createTestContext();
 
+function getRunFinalizeBody(phasesSource: string): string {
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
+
+  const nextExportIdx = phasesSource.indexOf("\nexport ", fnIdx + 1);
+  return phasesSource.slice(fnIdx, nextExportIdx > fnIdx ? nextExportIdx : undefined);
+}
+
 // ═══ Test: withTimeout resolves when inner promise resolves promptly ══════════
 
 {
@@ -145,11 +153,7 @@ const { assertTrue, assertEq, report } = createTestContext();
     "utf-8",
   );
 
-  // Find the runFinalize function body
-  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
-  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
-
-  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+  const fnBody = getRunFinalizeBody(phasesSource);
 
   // postUnitPreVerification must be wrapped in withTimeout
   const preTimeoutIdx = fnBody.indexOf("withTimeout(");
@@ -207,8 +211,7 @@ const { assertTrue, assertEq, report } = createTestContext();
     "utf-8",
   );
 
-  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
-  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+  const fnBody = getRunFinalizeBody(phasesSource);
 
   // Both timeout handlers should increment consecutiveFinalizeTimeouts
   const incrementCount = (fnBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;

package/src/resources/extensions/gsd/tests/gsd-db.test.ts

@@ -80,7 +80,7 @@ describe('gsd-db', () => {
     // Check schema_version table
     const adapter = _getAdapter()!;
     const version = adapter.prepare('SELECT MAX(version) as version FROM schema_version').get();
-    assert.deepStrictEqual(version?.['version'], 14, 'schema version should be 14');
+    assert.deepStrictEqual(version?.['version'], 15, 'schema version should be 15');
 
     // Check tables exist by querying them
     const dRows = adapter.prepare('SELECT count(*) as cnt FROM decisions').get();

package/src/resources/extensions/gsd/tests/health-widget.test.ts

@@ -198,7 +198,7 @@ test("session_start bootstraps the health widget alongside notifications", async
     },
   } as any;
 
-  registerHooks(pi);
+  registerHooks(pi, []);
   const sessionStart = handlers.get("session_start");
   assert.ok(sessionStart, "session_start handler is registered");
 

package/src/resources/extensions/gsd/tests/md-importer.test.ts

@@ -363,7 +363,7 @@ test('md-importer: schema v1→v2 migration', () => {
   openDatabase(':memory:');
   const adapter = _getAdapter();
   const version = adapter?.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.v, 14, 'new DB should be at schema version 14');
+  assert.deepStrictEqual(version?.v, 15, 'new DB should be at schema version 15');
 
   // Artifacts table should exist
   const tableCheck = adapter?.prepare("SELECT count(*) as c FROM sqlite_master WHERE type='table' AND name='artifacts'").get();
@@ -413,4 +413,3 @@ test('md-importer: round-trip fidelity', () => {
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
-

package/src/resources/extensions/gsd/tests/memory-store.test.ts

@@ -323,10 +323,9 @@ test('memory-store: schema includes memories table', () => {
   const viewCount = adapter.prepare('SELECT count(*) as cnt FROM active_memories').get();
   assert.deepStrictEqual(viewCount?.['cnt'], 0, 'active_memories view should exist');
 
-  // Verify schema version is 14 (after indexes + slice_dependencies)
+  // Verify schema version is 15 (UOK gate/git/audit projection tables included)
   const version = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.['v'], 14, 'schema version should be 14');
+  assert.deepStrictEqual(version?.['v'], 15, 'schema version should be 15');
 
   closeDatabase();
 });
-

package/src/resources/extensions/gsd/tests/post-exec-retry-bypass.test.ts

@@ -14,7 +14,7 @@ import { join } from "node:path";
 
 import { runPostUnitVerification, type VerificationContext } from "../auto-verification.ts";
 import { AutoSession } from "../auto/session.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, _getAdapter } from "../gsd-db.ts";
 import { invalidateAllCaches } from "../cache.ts";
 import { _clearGsdRootCache } from "../paths.ts";
 
@@ -140,6 +140,43 @@ function createBasicTask(): void {
   });
 }
 
+function createPostExecFailureTask(): void {
+  insertMilestone({ id: "M001" });
+  insertSlice({
+    id: "S01",
+    milestoneId: "M001",
+    title: "Test Slice",
+    risk: "low",
+  });
+
+  const srcDir = join(tempDir, "src");
+  mkdirSync(srcDir, { recursive: true });
+  writeFileSync(
+    join(srcDir, "broken.ts"),
+    "import { missing } from './does-not-exist.js';\nexport const ok = 1;\n",
+    "utf-8",
+  );
+
+  insertTask({
+    id: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    title: "Task with broken import",
+    status: "pending",
+    keyFiles: ["src/broken.ts"],
+    planning: {
+      description: "Task that introduces an unresolved import in key files",
+      estimate: "1h",
+      files: ["src/broken.ts"],
+      verify: "echo pass",
+      inputs: [],
+      expectedOutput: [],
+      observabilityImpact: "",
+    },
+    sequence: 0,
+  });
+}
+
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 describe("Post-execution blocking failure retry bypass", () => {
@@ -249,6 +286,47 @@ describe("Post-execution blocking failure retry bypass", () => {
     // This test mainly confirms the wiring is correct
     assert.equal(result, "continue");
   });
+
+  test("uok gate runner persists post-execution gate failures when enabled", async () => {
+    createPostExecFailureTask();
+    writePreferences({
+      enhanced_verification: true,
+      enhanced_verification_post: true,
+      verification_auto_fix: true,
+      verification_max_retries: 2,
+      uok: {
+        enabled: true,
+        gates: { enabled: true },
+      },
+    });
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" });
+    const vctx: VerificationContext = { s, ctx, pi };
+
+    const result = await runPostUnitVerification(vctx, pauseAutoMock);
+
+    assert.equal(result, "pause");
+    assert.equal(pauseAutoMock.mock.callCount(), 1);
+
+    const adapter = _getAdapter();
+    const row = adapter
+      ?.prepare(
+        `SELECT gate_id, outcome, failure_class
+         FROM gate_runs
+         WHERE gate_id = 'post-execution-checks'
+         ORDER BY id DESC
+         LIMIT 1`,
+      )
+      .get() as { gate_id: string; outcome: string; failure_class: string } | undefined;
+
+    assert.ok(row, "post-execution gate run should be persisted when uok.gates is enabled");
+    assert.equal(row?.gate_id, "post-execution-checks");
+    assert.equal(row?.outcome, "fail");
+    assert.equal(row?.failure_class, "artifact");
+  });
 });
 
 describe("Post-execution retry behavior", () => {

package/src/resources/extensions/gsd/tests/post-unit-state-rebuild.test.ts

@@ -21,7 +21,8 @@ test("postUnitPreVerification rebuilds STATE.md before worktree sync", () => {
   const fnStart = source.indexOf("export async function postUnitPreVerification");
   assert.ok(fnStart > 0, "postUnitPreVerification should exist");
 
-  const section = source.slice(fnStart, fnStart + 8000);
+  const fnEnd = source.indexOf("export async function postUnitPostVerification", fnStart);
+  const section = source.slice(fnStart, fnEnd > fnStart ? fnEnd : undefined);
   const rebuildIdx = section.indexOf('await runSafely("postUnit", "state-rebuild"');
   const syncIdx = section.indexOf('await runSafely("postUnit", "worktree-sync"');
 

package/src/resources/extensions/gsd/tests/pre-execution-pause-wiring.test.ts

@@ -17,7 +17,7 @@ import { join } from "node:path";
 
 import { postUnitPostVerification, type PostUnitContext } from "../auto-post-unit.ts";
 import { AutoSession } from "../auto/session.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, _getAdapter } from "../gsd-db.ts";
 import { invalidateAllCaches } from "../cache.ts";
 import { _clearGsdRootCache } from "../paths.ts";
 
@@ -454,4 +454,43 @@ describe("Pre-execution checks → pauseAuto wiring", () => {
       "postUnitPostVerification should return 'continue' when pre-execution checks are disabled"
     );
   });
+
+  test("uok gate runner persists pre-execution gate outcomes when enabled", async () => {
+    writePreferences({
+      enhanced_verification: true,
+      enhanced_verification_pre: true,
+      enhanced_verification_strict: true,
+      uok: {
+        enabled: true,
+        gates: { enabled: true },
+      },
+    });
+
+    createFailingTasks();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" });
+    const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock);
+
+    const result = await postUnitPostVerification(pctx);
+    assert.equal(result, "stopped");
+
+    const adapter = _getAdapter();
+    const row = adapter
+      ?.prepare(
+        `SELECT gate_id, outcome, failure_class
+         FROM gate_runs
+         WHERE gate_id = 'pre-execution-checks'
+         ORDER BY id DESC
+         LIMIT 1`,
+      )
+      .get() as { gate_id: string; outcome: string; failure_class: string } | undefined;
+
+    assert.ok(row, "pre-execution gate run should be persisted when uok.gates is enabled");
+    assert.equal(row?.gate_id, "pre-execution-checks");
+    assert.equal(row?.outcome, "fail");
+    assert.equal(row?.failure_class, "input");
+  });
 });

package/src/resources/extensions/gsd/tests/register-hooks-depth-verification.test.ts

@@ -41,7 +41,7 @@ test("register-hooks unlocks milestone depth verification from question id witho
     },
   } as any;
 
-  registerHooks(pi);
+  registerHooks(pi, []);
 
   const questionId = "depth_verification_M001_confirm";
   const questions = [

package/src/resources/extensions/gsd/tests/token-profile.test.ts

@@ -34,11 +34,12 @@ const typesSrc = readFileSync(join(__dirname, "..", "types.ts"), "utf-8");
 // Type Definitions
 // ═══════════════════════════════════════════════════════════════════════════
 
-test("types: TokenProfile type exported with budget/balanced/quality", () => {
+test("types: TokenProfile type exported with budget/balanced/quality/burn-max", () => {
   assert.ok(typesSrc.includes("export type TokenProfile"), "TokenProfile should be exported");
   assert.match(typesSrc, /["']budget["']/, "should include budget");
   assert.match(typesSrc, /["']balanced["']/, "should include balanced");
   assert.match(typesSrc, /["']quality["']/, "should include quality");
+  assert.match(typesSrc, /["']burn-max["']/, "should include burn-max");
 });
 
 test("types: InlineLevel type exported with full/standard/minimal", () => {
@@ -91,7 +92,7 @@ test("preferences: KNOWN_PREFERENCE_KEYS includes token_profile and phases", ()
 // Profile Resolution
 // ═══════════════════════════════════════════════════════════════════════════
 
-test("profile: resolveProfileDefaults exists and handles all 3 tiers", () => {
+test("profile: resolveProfileDefaults exists and handles all 4 tiers", () => {
   assert.ok(
     preferencesSrc.includes("export function resolveProfileDefaults"),
     "resolveProfileDefaults should be exported",
@@ -99,8 +100,9 @@ test("profile: resolveProfileDefaults exists and handles all 3 tiers", () => {
   assert.ok(
     preferencesSrc.includes('case "budget"') &&
     preferencesSrc.includes('case "balanced"') &&
-    preferencesSrc.includes('case "quality"'),
-    "resolveProfileDefaults should handle all 3 tiers",
+    preferencesSrc.includes('case "quality"') &&
+    preferencesSrc.includes('case "burn-max"'),
+    "resolveProfileDefaults should handle all 4 tiers",
   );
 });
 
@@ -158,6 +160,7 @@ test("profile: resolveInlineLevel maps profile to inline level", () => {
   assert.ok(preferencesSrc.includes('case "budget": return "minimal"'), "budget → minimal");
   assert.ok(preferencesSrc.includes('case "balanced": return "standard"'), "balanced → standard");
   assert.ok(preferencesSrc.includes('case "quality": return "full"'), "quality → full");
+  assert.ok(preferencesSrc.includes('case "burn-max": return "full"'), "burn-max → full");
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -167,7 +170,7 @@ test("profile: resolveInlineLevel maps profile to inline level", () => {
 test("validate: validatePreferences handles token_profile", () => {
   assert.ok(
     preferencesSrc.includes("preferences.token_profile") &&
-    preferencesSrc.includes("budget, balanced, quality"),
+    preferencesSrc.includes("budget, balanced, quality, burn-max"),
     "validatePreferences should validate token_profile enum values",
   );
 });

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

@@ -0,0 +1,101 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { emitJournalEvent } from "../journal.ts";
+import { saveActivityLog } from "../activity-log.ts";
+import { initMetrics, resetMetrics, snapshotUnitMetrics } from "../metrics.ts";
+import { setLogBasePath, logWarning } from "../workflow-logger.ts";
+import { setUnifiedAuditEnabled } from "../uok/audit-toggle.ts";
+
+function readAuditEvents(basePath: string): Array<Record<string, unknown>> {
+  const file = join(basePath, ".gsd", "audit", "events.jsonl");
+  if (!existsSync(file)) return [];
+  const raw = readFileSync(file, "utf-8");
+  return raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+function makeMockContext(entries: unknown[]): any {
+  return {
+    sessionManager: {
+      getEntries: () => entries,
+    },
+  };
+}
+
+test("unified audit plane bridges journal/activity/metrics/workflow logger into audit envelope log", () => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-audit-"));
+  setUnifiedAuditEnabled(true);
+  try {
+    emitJournalEvent(basePath, {
+      ts: new Date().toISOString(),
+      flowId: "trace-123",
+      seq: 1,
+      eventType: "iteration-start",
+      data: { turnId: "turn-123", unitId: "M001/S01/T01" },
+    });
+
+    const activityCtx = makeMockContext([
+      { type: "message", message: { role: "assistant", content: [{ type: "text", text: "hello" }] } },
+    ]);
+    const activityPath = saveActivityLog(activityCtx, basePath, "execute-task", "M001/S01/T01");
+    assert.ok(activityPath);
+
+    initMetrics(basePath);
+    const metricsCtx = makeMockContext([
+      {
+        type: "message",
+        message: {
+          role: "assistant",
+          usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, totalTokens: 15, cost: 0.01 },
+          content: [],
+        },
+      },
+    ]);
+    const unit = snapshotUnitMetrics(
+      metricsCtx,
+      "execute-task",
+      "M001/S01/T01",
+      Date.now() - 1000,
+      "openai/gpt-5.4",
+      { traceId: "trace-123", turnId: "turn-123" },
+    );
+    assert.ok(unit);
+    resetMetrics();
+
+    setLogBasePath(basePath);
+    logWarning("engine", "audit bridge check", { id: "turn-123" });
+
+    const events = readAuditEvents(basePath);
+    const types = new Set(events.map((event) => String(event.type ?? "")));
+    assert.ok(types.has("journal-iteration-start"));
+    assert.ok(types.has("activity-log-saved"));
+    assert.ok(types.has("unit-metrics-snapshot"));
+    assert.ok(types.has("workflow-log-warn"));
+  } finally {
+    setUnifiedAuditEnabled(false);
+    resetMetrics();
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("unified audit bridge is disabled when toggle is off", () => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-audit-off-"));
+  setUnifiedAuditEnabled(false);
+  try {
+    emitJournalEvent(basePath, {
+      ts: new Date().toISOString(),
+      flowId: "trace-off",
+      seq: 1,
+      eventType: "iteration-start",
+    });
+    const events = readAuditEvents(basePath);
+    assert.equal(events.length, 0);
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,85 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import type {
+  AuditEventEnvelope,
+  GateResult,
+  TurnContract,
+  TurnResult,
+  UokNodeKind,
+} from "../uok/contracts.ts";
+import { buildAuditEnvelope } from "../uok/audit.ts";
+
+test("uok contracts serialize/deserialize turn envelopes", () => {
+  const contract: TurnContract = {
+    traceId: "trace-1",
+    turnId: "turn-1",
+    iteration: 1,
+    basePath: "/tmp/project",
+    unitType: "execute-task",
+    unitId: "M001.S01.T01",
+    startedAt: new Date().toISOString(),
+  };
+
+  const gate: GateResult = {
+    gateId: "Q3",
+    gateType: "policy",
+    outcome: "pass",
+    failureClass: "none",
+    attempt: 1,
+    maxAttempts: 1,
+    retryable: false,
+    evaluatedAt: new Date().toISOString(),
+  };
+
+  const result: TurnResult = {
+    traceId: contract.traceId,
+    turnId: contract.turnId,
+    iteration: contract.iteration,
+    unitType: contract.unitType,
+    unitId: contract.unitId,
+    status: "completed",
+    failureClass: "none",
+    phaseResults: [
+      { phase: "dispatch", action: "next", ts: new Date().toISOString() },
+      { phase: "unit", action: "continue", ts: new Date().toISOString() },
+      { phase: "finalize", action: "next", ts: new Date().toISOString() },
+    ],
+    gateResults: [gate],
+    startedAt: contract.startedAt,
+    finishedAt: new Date().toISOString(),
+  };
+
+  const roundTrip = JSON.parse(JSON.stringify(result)) as TurnResult;
+  assert.equal(roundTrip.turnId, "turn-1");
+  assert.equal(roundTrip.gateResults?.[0]?.gateId, "Q3");
+  assert.equal(roundTrip.phaseResults.length, 3);
+});
+
+test("uok contracts include required DAG node kinds", () => {
+  const required: UokNodeKind[] = [
+    "unit",
+    "hook",
+    "subagent",
+    "team-worker",
+    "verification",
+    "reprocess",
+  ];
+  assert.deepEqual(required.length, 6);
+});
+
+test("uok audit envelope includes trace/turn/causality fields", () => {
+  const event: AuditEventEnvelope = buildAuditEnvelope({
+    traceId: "trace-xyz",
+    turnId: "turn-xyz",
+    causedBy: "turn-start",
+    category: "orchestration",
+    type: "turn-result",
+    payload: { status: "completed" },
+  });
+
+  assert.equal(event.traceId, "trace-xyz");
+  assert.equal(event.turnId, "turn-xyz");
+  assert.equal(event.causedBy, "turn-start");
+  assert.equal(event.payload.status, "completed");
+});

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

@@ -0,0 +1,69 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { SidecarItem } from "../auto/session.ts";
+import {
+  selectConflictFreeBatch,
+  selectReactiveDispatchBatch,
+  buildSidecarQueueNodes,
+  scheduleSidecarQueue,
+} from "../uok/execution-graph.ts";
+
+test("uok execution graph selects deterministic conflict-free IDs", () => {
+  const selected = selectConflictFreeBatch({
+    orderedIds: ["S01", "S02", "S03", "S04"],
+    maxParallel: 4,
+    hasConflict: (candidate, existing) =>
+      (candidate === "S02" && existing === "S01") ||
+      (candidate === "S01" && existing === "S02"),
+  });
+
+  assert.deepEqual(selected, ["S01", "S03", "S04"]);
+});
+
+test("uok execution graph reactive batch honors file conflicts and in-flight writes", () => {
+  const result = selectReactiveDispatchBatch({
+    graph: [
+      { id: "T01", dependsOn: [], outputFiles: ["src/a.ts"] },
+      { id: "T02", dependsOn: [], outputFiles: ["src/a.ts"] },
+      { id: "T03", dependsOn: [], outputFiles: ["src/b.ts"] },
+      { id: "T04", dependsOn: ["T03"], outputFiles: ["src/c.ts"] },
+    ],
+    readyIds: ["T01", "T02", "T03", "T04"],
+    maxParallel: 3,
+    inFlightOutputs: new Set(["src/c.ts"]),
+  });
+
+  assert.deepEqual(result.selected, ["T01", "T03"]);
+  assert.ok(
+    result.conflicts.some((c) => c.nodeA === "T01" && c.nodeB === "T02" && c.file === "src/a.ts"),
+    "conflict list should include overlapping outputs",
+  );
+});
+
+test("uok execution graph sidecar nodes map queue kinds to supported DAG kinds", () => {
+  const queue: SidecarItem[] = [
+    { kind: "hook", unitType: "execute-task", unitId: "M001/S01/T01", prompt: "hook" },
+    { kind: "triage", unitType: "triage", unitId: "M001/S01", prompt: "triage" },
+    { kind: "quick-task", unitType: "quick-task", unitId: "M001/S01/Q01", prompt: "quick" },
+  ];
+
+  const nodes = buildSidecarQueueNodes(queue);
+  assert.equal(nodes[0]?.kind, "hook");
+  assert.equal(nodes[1]?.kind, "verification");
+  assert.equal(nodes[2]?.kind, "team-worker");
+  assert.equal(nodes[1]?.dependsOn.length, 1);
+});
+
+test("uok execution graph sidecar scheduler preserves deterministic queue order", async () => {
+  const queue: SidecarItem[] = [
+    { kind: "quick-task", unitType: "quick-task", unitId: "M001/S01/Q01", prompt: "q1" },
+    { kind: "hook", unitType: "hook", unitId: "M001/S01/H01", prompt: "h1" },
+    { kind: "triage", unitType: "triage", unitId: "M001/S01/TR1", prompt: "t1" },
+  ];
+
+  const scheduled = await scheduleSidecarQueue(queue);
+  assert.deepEqual(
+    scheduled.map((item) => item.unitId),
+    queue.map((item) => item.unitId),
+  );
+});

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

@@ -0,0 +1,39 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { resolveUokFlags } from "../uok/flags.ts";
+
+test("uok flags default to enabled when preference is unset", () => {
+  const flags = resolveUokFlags(undefined);
+  assert.equal(flags.enabled, true);
+  assert.equal(flags.legacyFallback, false);
+});
+
+test("uok legacy fallback preference forces legacy path", () => {
+  const flags = resolveUokFlags({
+    uok: {
+      enabled: true,
+      legacy_fallback: { enabled: true },
+    },
+  });
+  assert.equal(flags.enabled, false);
+  assert.equal(flags.legacyFallback, true);
+});
+
+test("uok legacy fallback env var forces legacy path", () => {
+  const previous = process.env.GSD_UOK_FORCE_LEGACY;
+  process.env.GSD_UOK_FORCE_LEGACY = "1";
+  try {
+    const flags = resolveUokFlags({
+      uok: {
+        enabled: true,
+      },
+    });
+    assert.equal(flags.enabled, false);
+    assert.equal(flags.legacyFallback, true);
+  } finally {
+    if (previous === undefined) delete process.env.GSD_UOK_FORCE_LEGACY;
+    else process.env.GSD_UOK_FORCE_LEGACY = previous;
+  }
+});
+