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

package/src/resources/extensions/gsd/tests/uok-gitops-turn-action.test.ts

@@ -0,0 +1,85 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { runTurnGitAction } from "../git-service.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+}
+
+function makeRepo(): string {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-uok-gitops-"));
+  run("git init", repo);
+  run('git config user.email "test@example.com"', repo);
+  run('git config user.name "Test User"', repo);
+  writeFileSync(join(repo, "README.md"), "# Test\n", "utf-8");
+  run("git add README.md", repo);
+  run('git commit -m "chore: init"', repo);
+  return repo;
+}
+
+test("uok gitops turn action status-only reports working tree dirtiness", () => {
+  const repo = makeRepo();
+  try {
+    const clean = runTurnGitAction({
+      basePath: repo,
+      action: "status-only",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    assert.equal(clean.status, "ok");
+    assert.equal(clean.dirty, false);
+
+    writeFileSync(join(repo, "README.md"), "# Dirty\n", "utf-8");
+    const dirty = runTurnGitAction({
+      basePath: repo,
+      action: "status-only",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    assert.equal(dirty.status, "ok");
+    assert.equal(dirty.dirty, true);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("uok gitops turn action snapshot writes snapshot refs", () => {
+  const repo = makeRepo();
+  try {
+    const result = runTurnGitAction({
+      basePath: repo,
+      action: "snapshot",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+    assert.equal(result.status, "ok");
+    assert.ok(result.snapshotLabel?.includes("execute-task/M001/S01/T01"));
+    const refs = run("git for-each-ref refs/gsd/snapshots/ --format='%(refname)'", repo);
+    assert.ok(refs.includes("refs/gsd/snapshots/execute-task/M001/S01/T01/"));
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("uok gitops turn action commit creates commit with unit trailer", () => {
+  const repo = makeRepo();
+  try {
+    writeFileSync(join(repo, "feature.ts"), "export const x = 1;\n", "utf-8");
+    const result = runTurnGitAction({
+      basePath: repo,
+      action: "commit",
+      unitType: "execute-task",
+      unitId: "M001/S01/T02",
+    });
+    assert.equal(result.status, "ok");
+    assert.ok(result.commitMessage?.includes("chore: auto-commit after execute-task"));
+    const body = run("git log -1 --pretty=%B", repo);
+    assert.ok(body.includes("GSD-Unit: M001/S01/T02"));
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const gsdDir = join(__dirname, "..");
+
+test("post-unit pre-verification selects turn git action from UOK gitops flags", () => {
+  const source = readFileSync(join(gsdDir, "auto-post-unit.ts"), "utf-8");
+  assert.ok(
+    source.includes("const turnAction: TurnGitActionMode = uokFlags.gitops ? uokFlags.gitopsTurnAction : \"commit\""),
+    "postUnitPreVerification should derive turn action from uok.gitops.turn_action when enabled",
+  );
+});
+
+test("post-unit pre-verification routes git failures through closeout gate", () => {
+  const source = readFileSync(join(gsdDir, "auto-post-unit.ts"), "utf-8");
+  assert.ok(
+    source.includes('id: "closeout-git-action"') &&
+    source.includes('type: "closeout"') &&
+    source.includes('failureClass: "git"'),
+    "git failures should be persisted via a closeout gate with failureClass=git",
+  );
+});
+
+test("auto snapshot opts carry trace/turn IDs for turn closeout records", () => {
+  const source = readFileSync(join(gsdDir, "auto.ts"), "utf-8");
+  assert.ok(
+    source.includes("traceId: s.currentTraceId ?? undefined") &&
+    source.includes("turnId: s.currentTurnId ?? undefined"),
+    "buildSnapshotOpts should pass trace/turn IDs into closeout options",
+  );
+});

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

@@ -0,0 +1,89 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  applyModelPolicyFilter,
+  buildRequirementVector,
+} from "../uok/model-policy.ts";
+import {
+  registerToolCompatibility,
+  resetToolCompatibilityRegistry,
+} from "@gsd/pi-coding-agent";
+
+test.afterEach(() => {
+  resetToolCompatibilityRegistry();
+});
+
+test("uok model policy builds requirement vectors from unit metadata", () => {
+  const requirements = buildRequirementVector("execute-task", {
+    tags: ["docs"],
+    fileCount: 8,
+    estimatedLines: 600,
+  });
+
+  assert.equal(requirements.instruction, 0.9);
+  assert.equal(requirements.coding, 0.3);
+  assert.equal(requirements.speed, 0.7);
+});
+
+test("uok model policy enforces provider/api/tool constraints and emits decision audit events", () => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-model-policy-"));
+  try {
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    registerToolCompatibility("screenshot", { producesImages: true });
+
+    const result = applyModelPolicyFilter(
+      [
+        { id: "openai-image", provider: "openai", api: "openai-responses" },
+        { id: "anthropic-ok", provider: "anthropic", api: "anthropic-messages" },
+        { id: "gemini-api-deny", provider: "google", api: "google-generative-ai" },
+        { id: "blocked-provider", provider: "blocked", api: "anthropic-messages" },
+      ],
+      {
+        basePath,
+        traceId: "trace-model-policy-1",
+        turnId: "turn-model-policy-1",
+        unitType: "execute-task",
+        taskMetadata: { tags: ["docs"] },
+        allowCrossProvider: true,
+        requiredTools: ["screenshot"],
+        allowedApis: ["anthropic-messages", "openai-responses"],
+        deniedProviders: ["blocked"],
+      },
+    );
+
+    assert.deepEqual(
+      result.eligible.map((m) => m.id),
+      ["anthropic-ok"],
+      "only the policy-compliant anthropic model should remain eligible",
+    );
+    assert.equal(result.decisions.length, 4);
+    assert.equal(result.decisions[0]?.allowed, false);
+    assert.match(result.decisions[0]?.reason ?? "", /tool policy denied/);
+    assert.equal(result.decisions[1]?.allowed, true);
+    assert.equal(result.decisions[2]?.allowed, false);
+    assert.match(result.decisions[2]?.reason ?? "", /transport\/api denied by policy/);
+    assert.equal(result.decisions[3]?.allowed, false);
+    assert.match(result.decisions[3]?.reason ?? "", /provider denied by policy/);
+
+    const auditLogPath = join(basePath, ".gsd", "audit", "events.jsonl");
+    const auditLines = readFileSync(auditLogPath, "utf-8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as { type: string; payload?: { reason?: string } });
+    const decisionTypes = auditLines.map((event) => event.type);
+
+    assert.equal(auditLines.length, 4);
+    assert.ok(decisionTypes.includes("model-policy-allow"));
+    assert.ok(decisionTypes.includes("model-policy-deny"));
+    assert.ok(
+      auditLines.some((event) => (event.payload?.reason ?? "").includes("tool policy denied")),
+      "audit stream should include explicit deny reasons",
+    );
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,167 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import {
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
+import type { GSDState, Phase } from "../types.ts";
+import { ensurePlanV2Graph } from "../uok/plan-v2.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const gsdDir = join(__dirname, "..");
+const MILESTONE_ID = "M001";
+const SLICE_ID = "S01";
+const TASK_ID = "T01";
+const tempDirs = new Set<string>();
+
+function createBasePath(): string {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-planv2-"));
+  mkdirSync(join(basePath, ".gsd", "milestones", MILESTONE_ID), { recursive: true });
+  tempDirs.add(basePath);
+  return basePath;
+}
+
+function writeMilestoneFile(basePath: string, suffix: string, content: string): void {
+  const milestoneDir = join(basePath, ".gsd", "milestones", MILESTONE_ID);
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(join(milestoneDir, `${MILESTONE_ID}-${suffix}.md`), `${content}\n`, "utf-8");
+}
+
+function writeSliceFile(basePath: string, suffix: string, content: string): void {
+  const sliceDir = join(basePath, ".gsd", "milestones", MILESTONE_ID, "slices", SLICE_ID);
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, `${SLICE_ID}-${suffix}.md`), `${content}\n`, "utf-8");
+}
+
+function seedGraphRows(): void {
+  insertMilestone({ id: MILESTONE_ID, title: "Milestone", status: "active" });
+  insertSlice({
+    id: SLICE_ID,
+    milestoneId: MILESTONE_ID,
+    title: "Slice",
+    status: "in_progress",
+    sequence: 1,
+  });
+  insertTask({
+    id: TASK_ID,
+    milestoneId: MILESTONE_ID,
+    sliceId: SLICE_ID,
+    title: "Task",
+    status: "pending",
+    keyFiles: ["src/task.ts"],
+    sequence: 1,
+  });
+}
+
+function buildState(phase: Phase): GSDState {
+  return {
+    phase,
+    activeMilestone: { id: MILESTONE_ID, title: "Milestone" },
+    activeSlice: null,
+    activeTask: null,
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "dispatch",
+    registry: [],
+  };
+}
+
+test.beforeEach(() => {
+  closeDatabase();
+  const opened = openDatabase(":memory:");
+  assert.equal(opened, true);
+});
+
+test.afterEach(() => {
+  closeDatabase();
+  for (const path of tempDirs) {
+    rmSync(path, { recursive: true, force: true });
+  }
+  tempDirs.clear();
+});
+
+test("guided flow enforces plan-v2 gate before execution-oriented dispatch", () => {
+  const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
+  assert.ok(
+    source.includes("needsPlanV2Gate") &&
+    source.includes("ensurePlanV2Graph") &&
+    source.includes("Plan gate failed-closed"),
+    "guided flow should fail-closed when plan-v2 graph compilation fails",
+  );
+});
+
+test("plan-v2 gate fails closed for execution phase when finalized context is missing", () => {
+  const basePath = createBasePath();
+  seedGraphRows();
+
+  writeMilestoneFile(basePath, "CONTEXT-DRAFT", "Draft context only.");
+
+  const compiled = ensurePlanV2Graph(basePath, buildState("executing"));
+  assert.equal(compiled.ok, false);
+  assert.match(compiled.reason ?? "", /CONTEXT\.md/i);
+});
+
+test("plan-v2 compiler writes pipeline metadata for clarify/research/draft stages", () => {
+  const basePath = createBasePath();
+  seedGraphRows();
+
+  writeMilestoneFile(basePath, "CONTEXT", "Finalized context.");
+  writeMilestoneFile(basePath, "CONTEXT-DRAFT", "Draft context retained.");
+  writeMilestoneFile(basePath, "RESEARCH", "Milestone research synthesis.");
+  writeSliceFile(basePath, "RESEARCH", "Slice research detail.");
+
+  const compiled = ensurePlanV2Graph(basePath, buildState("executing"));
+  assert.equal(compiled.ok, true);
+  assert.equal(compiled.clarifyRoundLimit, 3);
+  assert.equal(compiled.researchSynthesized, true);
+  assert.equal(compiled.draftContextIncluded, true);
+  assert.equal(compiled.finalizedContextIncluded, true);
+
+  const graphPath = compiled.graphPath ?? "";
+  const graphRaw = readFileSync(graphPath, "utf-8");
+  const graph = JSON.parse(graphRaw) as {
+    pipeline?: Record<string, unknown>;
+    nodes?: unknown[];
+  };
+
+  assert.equal(graph.pipeline?.["clarifyRoundLimit"], 3);
+  assert.equal(graph.pipeline?.["researchSynthesized"], true);
+  assert.equal(graph.pipeline?.["draftContextIncluded"], true);
+  assert.equal(graph.pipeline?.["finalizedContextIncluded"], true);
+  assert.equal(Array.isArray(graph.nodes), true);
+});
+
+test("plan-v2 graph may compile during planning even without finalized context", () => {
+  const basePath = createBasePath();
+  seedGraphRows();
+
+  writeMilestoneFile(basePath, "CONTEXT-DRAFT", "Planning draft context.");
+  const compiled = ensurePlanV2Graph(basePath, buildState("planning"));
+  assert.equal(compiled.ok, true);
+});
+
+test("plan-v2 ensure rejects empty executable graph", () => {
+  const basePath = createBasePath();
+  writeMilestoneFile(basePath, "CONTEXT", "Finalized context.");
+
+  insertMilestone({ id: MILESTONE_ID, title: "Milestone", status: "active" });
+  insertSlice({
+    id: SLICE_ID,
+    milestoneId: MILESTONE_ID,
+    title: "Slice",
+    status: "pending",
+    sequence: 1,
+  });
+
+  const compiled = ensurePlanV2Graph(basePath, buildState("executing"));
+  assert.equal(compiled.ok, false);
+  assert.match(compiled.reason ?? "", /compiled graph is empty/i);
+});

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

@@ -0,0 +1,42 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { validatePreferences } from "../preferences-validation.ts";
+
+test("uok preferences validate nested flags and turn_action", () => {
+  const input = {
+    uok: {
+      enabled: true,
+      legacy_fallback: { enabled: false },
+      gates: { enabled: true },
+      model_policy: { enabled: true },
+      execution_graph: { enabled: false },
+      gitops: {
+        enabled: true,
+        turn_action: "status-only",
+        turn_push: false,
+      },
+      audit_unified: { enabled: true },
+      plan_v2: { enabled: true },
+    },
+  };
+
+  const result = validatePreferences(input as never);
+  assert.equal(result.errors.length, 0);
+  assert.equal(result.preferences.uok?.enabled, true);
+  assert.equal(result.preferences.uok?.legacy_fallback?.enabled, false);
+  assert.equal(result.preferences.uok?.gitops?.turn_action, "status-only");
+  assert.equal(result.preferences.uok?.plan_v2?.enabled, true);
+});
+
+test("uok preferences reject invalid turn_action", () => {
+  const result = validatePreferences({
+    uok: {
+      gitops: {
+        turn_action: "push-everything",
+      },
+    },
+  } as never);
+
+  assert.ok(result.errors.some((e) => e.includes("uok.gitops.turn_action")));
+});

package/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts

@@ -112,4 +112,43 @@ describe("handleValidateMilestone write ordering (#2725)", () => {
     ).get();
     assert.equal(row, undefined, "assessment row should be deleted after disk-write rollback");
   });
+
+  it("persists milestone validation gate_runs rows when UOK gates are enabled", async () => {
+    base = makeTmpBase();
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    const result = await handleValidateMilestone(VALID_PARAMS, base, {
+      uokGatesEnabled: true,
+      traceId: "trace-val-1",
+      turnId: "turn-val-1",
+    });
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+
+    const adapter = _getAdapter()!;
+    const row = adapter.prepare(
+      `SELECT gate_id, outcome, failure_class, trace_id, turn_id
+       FROM gate_runs
+       WHERE gate_id = 'milestone-validation-gates'
+       ORDER BY id DESC
+       LIMIT 1`,
+    ).get() as
+      | {
+          gate_id: string;
+          outcome: string;
+          failure_class: string;
+          trace_id: string;
+          turn_id: string;
+        }
+      | undefined;
+
+    assert.ok(row, "milestone validation gate row should be persisted");
+    assert.equal(row?.gate_id, "milestone-validation-gates");
+    assert.equal(row?.outcome, "pass");
+    assert.equal(row?.failure_class, "none");
+    assert.equal(row?.trace_id, "trace-val-1");
+    assert.equal(row?.turn_id, "turn-val-1");
+  });
 });

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -430,11 +430,18 @@ export async function handleCompleteSlice(
   // eslint-disable-next-line @typescript-eslint/no-floating-promises
   (async () => {
     try {
-      const graphMod = await import("@gsd-build/mcp-server") as {
+      const graphMod = await import("@gsd-build/mcp-server") as unknown as Partial<{
         buildGraph: (dir: string) => Promise<{ nodes: unknown[]; edges: unknown[]; builtAt: string }>;
         writeGraph: (gsdRoot: string, graph: unknown) => Promise<void>;
         resolveGsdRoot: (basePath: string) => string;
-      };
+      }>;
+      if (
+        typeof graphMod.buildGraph !== "function"
+        || typeof graphMod.writeGraph !== "function"
+        || typeof graphMod.resolveGsdRoot !== "function"
+      ) {
+        throw new Error("graph helpers unavailable from @gsd-build/mcp-server");
+      }
       const g = await graphMod.buildGraph(basePath);
       await graphMod.writeGraph(graphMod.resolveGsdRoot(basePath), g);
     } catch (graphErr) {

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -23,6 +23,9 @@ import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 import { insertMilestoneValidationGates } from "../milestone-validation-gates.js";
 import { logWarning } from "../workflow-logger.js";
+import { UokGateRunner } from "../uok/gate-runner.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { resolveUokFlags } from "../uok/flags.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -43,6 +46,12 @@ export interface ValidateMilestoneResult {
   validationPath: string;
 }
 
+export interface ValidateMilestoneOptions {
+  uokGatesEnabled?: boolean;
+  traceId?: string;
+  turnId?: string;
+}
+
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -81,6 +90,7 @@ ${params.verdictRationale}
 export async function handleValidateMilestone(
   params: ValidateMilestoneParams,
   basePath: string,
+  opts?: ValidateMilestoneOptions,
 ): Promise<ValidateMilestoneResult | { error: string }> {
   if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
     return { error: "milestoneId is required and must be a non-empty string" };
@@ -108,6 +118,8 @@ export async function handleValidateMilestone(
   // rendering can regenerate. The inverse (file exists, no DB row) is
   // harder to detect and recover from (#2725).
   const validatedAt = new Date().toISOString();
+  const slices = getMilestoneSlices(params.milestoneId);
+  const gateSliceId = slices.length > 0 ? slices[0].id : "_milestone";
 
   transaction(() => {
     insertAssessment({
@@ -123,11 +135,9 @@ export async function handleValidateMilestone(
     // #2945 Bug 4: persist quality_gates records alongside the assessment.
     // Previously only the assessment was written, leaving M002+ milestones
     // with zero quality_gate records despite passing validation.
-    const slices = getMilestoneSlices(params.milestoneId);
-    const sliceId = slices.length > 0 ? slices[0].id : "_milestone";
     insertMilestoneValidationGates(
       params.milestoneId,
-      sliceId,
+      gateSliceId,
       params.verdict,
       validatedAt,
     );
@@ -147,6 +157,41 @@ export async function handleValidateMilestone(
   clearPathCache();
   clearParseCache();
 
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const gatesEnabled = opts?.uokGatesEnabled ?? resolveUokFlags(prefs).gates;
+  if (gatesEnabled) {
+    try {
+      const gateRunner = new UokGateRunner();
+      const nonPassVerdict = params.verdict !== "pass";
+      gateRunner.register({
+        id: "milestone-validation-gates",
+        type: "verification",
+        execute: async () => ({
+          outcome: nonPassVerdict ? "manual-attention" : "pass",
+          failureClass: nonPassVerdict ? "manual-attention" : "none",
+          rationale: `milestone validation verdict: ${params.verdict}`,
+          findings: nonPassVerdict
+            ? [params.verdictRationale, params.remediationPlan ?? ""].filter(Boolean).join("\n")
+            : "",
+        }),
+      });
+      await gateRunner.run("milestone-validation-gates", {
+        basePath,
+        traceId: opts?.traceId ?? `validate-milestone:${params.milestoneId}`,
+        turnId: opts?.turnId ?? `${params.milestoneId}:validate`,
+        milestoneId: params.milestoneId,
+        sliceId: gateSliceId,
+        unitType: "validate-milestone",
+        unitId: params.milestoneId,
+      });
+    } catch (err) {
+      logWarning(
+        "tool",
+        `validate_milestone — failed to persist UOK gate result: ${(err as Error).message}`,
+      );
+    }
+  }
+
   return {
     milestoneId: params.milestoneId,
     verdict: params.verdict,

package/src/resources/extensions/gsd/types.ts

@@ -253,6 +253,19 @@ export interface GSDState {
   lastCompletedMilestone?: ActiveRef | null;
 }
 
+// ─── GSD Ecosystem Extension API Types ────────────────────────────────────
+// Pure data type — no runtime deps. The GSDExtensionAPI interface itself
+// lives in ecosystem/gsd-extension-api.ts (it imports from pi).
+
+export interface GSDActiveUnit {
+  milestoneId: string;
+  milestoneTitle: string;
+  sliceId: string;
+  sliceTitle: string;
+  taskId: string;
+  taskTitle: string;
+}
+
 // ─── Post-Unit Hook Types ─────────────────────────────────────────────────
 
 export interface PostUnitHookConfig {
@@ -306,7 +319,7 @@ export interface HookDispatchResult {
 
 export type BudgetEnforcementMode = "warn" | "pause" | "halt";
 
-export type TokenProfile = "budget" | "balanced" | "quality";
+export type TokenProfile = "budget" | "balanced" | "quality" | "burn-max";
 
 export type InlineLevel = "full" | "standard" | "minimal";
 

package/src/resources/extensions/gsd/unit-ownership.ts

@@ -46,8 +46,8 @@ let loadAttempted = false;
 
 function suppressSqliteWarning(): void {
   const origEmit = process.emit;
-  // @ts-expect-error overriding process.emit for warning filter
-  process.emit = function (event: string, ...args: unknown[]): boolean {
+  // Override via loose cast: Node's overloaded emit signature is not directly assignable.
+  (process as any).emit = function (event: string, ...args: unknown[]): boolean {
     if (
       event === "warning" &&
       args[0] &&

package/src/resources/extensions/gsd/uok/audit-toggle.ts

@@ -0,0 +1,9 @@
+const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+
+export function setUnifiedAuditEnabled(enabled: boolean): void {
+  process.env[AUDIT_ENV_KEY] = enabled ? "1" : "0";
+}
+
+export function isUnifiedAuditEnabled(): boolean {
+  return process.env[AUDIT_ENV_KEY] === "1";
+}

package/src/resources/extensions/gsd/uok/audit.ts

@@ -0,0 +1,51 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { gsdRoot } from "../paths.js";
+import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
+import type { AuditEventEnvelope } from "./contracts.js";
+
+function auditLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "audit", "events.jsonl");
+}
+
+function ensureAuditDir(basePath: string): void {
+  mkdirSync(join(gsdRoot(basePath), "audit"), { recursive: true });
+}
+
+export function buildAuditEnvelope(args: {
+  traceId: string;
+  turnId?: string;
+  causedBy?: string;
+  category: AuditEventEnvelope["category"];
+  type: string;
+  payload?: Record<string, unknown>;
+}): AuditEventEnvelope {
+  return {
+    eventId: randomUUID(),
+    traceId: args.traceId,
+    turnId: args.turnId,
+    causedBy: args.causedBy,
+    category: args.category,
+    type: args.type,
+    ts: new Date().toISOString(),
+    payload: args.payload ?? {},
+  };
+}
+
+export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
+  try {
+    ensureAuditDir(basePath);
+    appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+  } catch {
+    // Best-effort: audit writes must never break orchestration.
+  }
+
+  if (!isDbAvailable()) return;
+  try {
+    insertAuditEvent(event);
+  } catch {
+    // Projection failures are non-fatal while legacy readers are still active.
+  }
+}