gsd-pi 2.79.0 → 2.80.0-dev.b62439b9f

package/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts

@@ -17,8 +17,8 @@
  *
  * This rewrite builds a real git parent repo + local submodule, creates
  * a worktree, dirties a tracked file inside the submodule, then invokes
- * `removeWorktree` and asserts observable behaviour on stderr (where
- * `logWarning` writes) and on the filesystem (the worktree is gone).
+ * `removeWorktree` and asserts observable behaviour through the workflow log
+ * buffer and on the filesystem (the worktree is gone).
  */
 
 import { describe, test, beforeEach, afterEach } from "node:test";
@@ -35,6 +35,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { createWorktree, removeWorktree } from "../worktree-manager.ts";
+import { _resetLogs, peekLogs } from "../workflow-logger.ts";
 
 interface Harness {
   parent: string;
@@ -112,53 +113,38 @@ function makeHarness(): Harness {
   };
 }
 
-/** Capture stderr writes during `fn`. `logWarning` writes to stderr, so
- * this reveals warnings emitted by the worktree-manager. */
-function captureStderr(fn: () => void): string {
-  const streamAny = process.stderr as unknown as {
-    write: (chunk: string | Uint8Array, ...rest: unknown[]) => boolean;
-  };
-  const original = streamAny.write.bind(streamAny);
-  const chunks: string[] = [];
-  streamAny.write = (chunk: string | Uint8Array): boolean => {
-    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"));
-    return true;
-  };
-  try {
-    fn();
-  } finally {
-    streamAny.write = original;
-  }
-  return chunks.join("");
+function workflowLogMessages(): string {
+  return peekLogs().map((entry) => entry.message).join("\n");
 }
 
 describe("removeWorktree preserves submodule uncommitted state (#2337)", () => {
   let h: Harness;
 
   beforeEach(() => {
+    _resetLogs();
     h = makeHarness();
   });
 
   afterEach(() => {
     h.cleanup();
+    _resetLogs();
   });
 
   test("clean submodules: worktree removes without stashing or submodule warnings", () => {
     const wt = createWorktree(h.parent, "cleanwt");
     runGit(wt.path, ["submodule", "update", "--init", "--recursive"]);
 
-    const stderr = captureStderr(() => {
-      removeWorktree(h.parent, "cleanwt");
-    });
+    removeWorktree(h.parent, "cleanwt");
+    const logs = workflowLogMessages();
 
     assert.ok(!existsSync(wt.path), "worktree directory should be gone");
     assert.doesNotMatch(
-      stderr,
+      logs,
       /Saved uncommitted submodule changes to rescue branch/,
       "clean submodule must not trigger rescue-branch creation",
     );
     assert.doesNotMatch(
-      stderr,
+      logs,
       /Submodule rescue branch creation failed/,
       "clean submodule must not trigger rescue-branch failure warning",
     );
@@ -191,21 +177,20 @@ describe("removeWorktree preserves submodule uncommitted state (#2337)", () => {
       `precondition: submodule must be diverged, got: "${subStatus}"`,
     );
 
-    const stderr = captureStderr(() => {
-      removeWorktree(h.parent, "dirtywt");
-    });
+    removeWorktree(h.parent, "dirtywt");
+    const logs = workflowLogMessages();
 
     // Worktree is gone: force fallback succeeded.
     assert.ok(!existsSync(wt.path), "worktree directory should be removed");
 
     // The code path that fires on dirty submodules emits one of these
-    // two warnings. Either indicates the detection ran — the ONLY
+    // warnings. Any of these indicates the detection ran — the ONLY
     // observable that would fail if someone removed the
     // `if (hasSubmoduleChanges)` branch and went straight to force
     // removal. This is the assertion that #4823 demanded in place of
     // the tautological `src.includes("submodule") && src.includes("force")`.
     assert.match(
-      stderr,
+      logs,
       /Saved uncommitted submodule changes to rescue branch|Submodule rescue branch creation failed|Submodule changes detected/,
       "dirty submodule must trigger detection-and-warning path",
     );
@@ -231,12 +216,11 @@ describe("removeWorktree preserves submodule uncommitted state (#2337)", () => {
       renameSync(modPath, hiddenPath);
     }
 
-    const stderr = captureStderr(() => {
-      removeWorktree(h.parent, "no-gitmodules");
-    });
+    removeWorktree(h.parent, "no-gitmodules");
+    const logs = workflowLogMessages();
 
     assert.doesNotMatch(
-      stderr,
+      logs,
       /Saved uncommitted submodule changes to rescue branch/,
       "missing .gitmodules should skip submodule detection entirely",
     );

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

@@ -1,3 +1,4 @@
+// GSD2 complete-milestone tool handler
 /**
  * complete-milestone handler — the core operation behind gsd_complete_milestone.
  *
@@ -57,6 +58,7 @@ export interface CompleteMilestoneResult {
   milestoneId: string;
   summaryPath: string;
   stale?: boolean;
+  alreadyComplete?: boolean;
 }
 
 function renderMilestoneSummaryMarkdown(params: CompleteMilestoneParams): string {
@@ -143,6 +145,7 @@ export async function handleCompleteMilestone(
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
+  let alreadyComplete = false;
 
   transaction(() => {
     // State machine preconditions (inside txn for atomicity)
@@ -152,7 +155,7 @@ export async function handleCompleteMilestone(
       return;
     }
     if (isClosedStatus(milestone.status)) {
-      guardError = `milestone ${params.milestoneId} is already complete`;
+      alreadyComplete = true;
       return;
     }
 
@@ -238,14 +241,16 @@ export async function handleCompleteMilestone(
     logWarning("tool", `complete-milestone manifest warning: ${(mfErr as Error).message}`);
   }
   try {
-    appendEvent(basePath, {
-      cmd: "complete-milestone",
-      params: { milestoneId: params.milestoneId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
+    if (!alreadyComplete) {
+      appendEvent(basePath, {
+        cmd: "complete-milestone",
+        params: { milestoneId: params.milestoneId },
+        ts: new Date().toISOString(),
+        actor: "agent",
+        actor_name: params.actorName,
+        trigger_reason: params.triggerReason,
+      });
+    }
   } catch (eventErr) {
     logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
@@ -254,5 +259,6 @@ export async function handleCompleteMilestone(
     milestoneId: params.milestoneId,
     summaryPath,
     ...(projectionStale ? { stale: true } : {}),
+    ...(alreadyComplete ? { alreadyComplete: true } : {}),
   };
 }

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Complete-task tool handler for GSD workflow state and summaries.
+
 /**
  * complete-task handler — the core operation behind gsd_complete_task.
  *
@@ -55,7 +58,7 @@ export interface CompleteTaskResult {
   stale?: boolean;
 }
 
-import type { TaskRow } from "../gsd-db.js";
+import type { TaskRow } from "../db-task-slice-rows.js";
 
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -3,6 +3,7 @@ import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
 import {
   getActiveRequirements,
+  insertMilestone,
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
@@ -31,6 +32,7 @@ import { handleValidateMilestone } from "./validate-milestone.js";
 import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { parseProject } from "../schemas/parsers.js";
 
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
   "SUMMARY",
@@ -71,6 +73,20 @@ export interface SummarySaveParams {
   content: string;
 }
 
+function registerProjectMilestoneSequence(content: string): string[] {
+  const parsed = parseProject(content);
+  const registered: string[] = [];
+  for (const milestone of parsed.milestones) {
+    insertMilestone({
+      id: milestone.id,
+      title: milestone.title,
+      status: milestone.done ? "complete" : "queued",
+    });
+    registered.push(milestone.id);
+  }
+  return registered;
+}
+
 export async function executeSummarySave(
   params: SummarySaveParams,
   basePath: string = process.cwd(),
@@ -173,6 +189,67 @@ export async function executeSummarySave(
       basePath,
     );
 
+    let registeredMilestones: string[] = [];
+    if (params.artifact_type === "PROJECT") {
+      try {
+        registeredMilestones = registerProjectMilestoneSequence(contentToSave);
+        if (registeredMilestones.length > 0) invalidateStateCache();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logError("tool", `gsd_summary_save: PROJECT artifact persisted but milestone registration threw: ${msg}`, {
+          tool: "gsd_summary_save",
+          error: String(err),
+          stack: err instanceof Error ? err.stack ?? "" : "",
+        });
+        // PROJECT.md was persisted by saveArtifactToDb above; the artifacts row
+        // changed even though no milestones registered. Invalidate so subsequent
+        // /gsd reads see the persisted artifact instead of the pre-save cache.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but milestone registration failed: ${msg}. ` +
+              `The DB has no milestone rows for this project, so /gsd will report "No Active Milestone". ` +
+              `Re-call gsd_summary_save(PROJECT) once the underlying error is resolved — INSERT OR IGNORE makes registration idempotent.`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_threw",
+            registration_error: msg,
+          },
+          isError: true,
+        };
+      }
+      if (registeredMilestones.length === 0) {
+        logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+          tool: "gsd_summary_save",
+        });
+        // PROJECT.md was persisted; invalidate so subsequent reads see the new
+        // artifacts row even though no milestones registered.
+        invalidateStateCache();
+        return {
+          content: [{
+            type: "text",
+            text:
+              `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+              `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+              `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+              `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+          }],
+          details: {
+            operation: "save_summary",
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            error: "milestone_registration_empty_parse",
+          },
+          isError: true,
+        };
+      }
+    }
+
     if (params.artifact_type === "CONTEXT" && !params.task_id) {
       try {
         const draftFile = params.slice_id
@@ -186,7 +263,13 @@ export async function executeSummarySave(
 
     return {
       content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-      details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type, content_source: contentSource },
+      details: {
+        operation: "save_summary",
+        path: relativePath,
+        artifact_type: params.artifact_type,
+        content_source: contentSource,
+        ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
+      },
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -394,12 +477,17 @@ export async function executeCompleteMilestone(
       isError: true,
       };
     }
+    const message = result.alreadyComplete
+      ? `Milestone ${result.milestoneId} is already complete. Summary available at ${result.summaryPath}`
+      : `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}`;
     return {
-      content: [{ type: "text", text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }],
+      content: [{ type: "text", text: message }],
       details: {
         operation: "complete_milestone",
         milestoneId: result.milestoneId,
         summaryPath: result.summaryPath,
+        ...(result.alreadyComplete ? { alreadyComplete: true } : {}),
+        ...(result.stale ? { stale: true } : {}),
       },
     };
   } catch (err) {

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

@@ -42,6 +42,7 @@ import {
   type BaseResolverContext,
   type ComputedArtifactId,
   type ComputedArtifactRegistry,
+  type ContextModePolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
 
@@ -92,6 +93,54 @@ export function manifestBudgetChars(unitType: string): number | null {
   return manifest ? manifest.maxSystemPromptChars : null;
 }
 
+// ─── Context Mode lane guidance ──────────────────────────────────────────
+
+export type ContextModeRenderMode = "standalone" | "nested";
+
+export interface ComposeContextModeInstructionOptions {
+  readonly enabled: boolean;
+  readonly renderMode: ContextModeRenderMode;
+}
+
+const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, string> = {
+  interview: "interview",
+  research: "research",
+  planning: "planning",
+  execution: "execution",
+  verification: "verification",
+  orchestration: "orchestration",
+  docs: "documentation",
+};
+
+const CONTEXT_MODE_GUIDANCE =
+  "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
+
+/**
+ * Render the Context Mode instruction lane for a unit type. Unknown unit
+ * types, disabled config, and explicit `contextMode: "none"` all omit the
+ * block so callers can prefix this safely without extra branching.
+ */
+export function composeContextModeInstructions(
+  unitType: string,
+  opts: ComposeContextModeInstructionOptions,
+): string {
+  if (!opts.enabled) return "";
+  const manifest = resolveManifest(unitType);
+  if (!manifest || manifest.contextMode === "none") return "";
+
+  const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+  if (opts.renderMode === "nested") {
+    return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+  }
+
+  return [
+    "## Context Mode",
+    "",
+    `Lane: **${lane} lane**.`,
+    CONTEXT_MODE_GUIDANCE,
+  ].join("\n");
+}
+
 // ─── v2 surface (#4924) ───────────────────────────────────────────────────
 
 /**

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

@@ -90,6 +90,17 @@ export type MemoryPolicy = "none" | "critical-only" | "prompt-relevant";
 /** Preferences block policy. */
 export type PreferencesPolicy = "none" | "active-only" | "full";
 
+/** Context Mode lane guidance policy for each auto-mode unit. */
+export type ContextModePolicy =
+  | "none"
+  | "interview"
+  | "research"
+  | "planning"
+  | "execution"
+  | "verification"
+  | "orchestration"
+  | "docs";
+
 /**
  * Tool-access policy per unit type (#4934).
  *
@@ -220,6 +231,8 @@ export interface UnitContextManifest {
   readonly codebaseMap: boolean;
   /** Preferences block policy. */
   readonly preferences: PreferencesPolicy;
+  /** Context Mode guidance lane. */
+  readonly contextMode: ContextModePolicy;
   /**
    * Tool-access policy (#4934). Runtime enforcement covers path-scoped write
    * blocking, subagent denial, and bash allowlisting for active auto-mode
@@ -343,6 +356,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "research",
     tools: TOOLS_PLANNING,
     artifacts: {
       // Phase 3 migration (#4782): matches today's actual
@@ -359,6 +373,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "planning",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["project", "requirements", "decisions", "milestone-research", "templates"],
@@ -373,6 +388,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "interview",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["project", "requirements", "decisions", "milestone-context", "templates"],
@@ -387,6 +403,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
+    contextMode: "verification",
     // planning-dispatch: validation is a verification-fan-out unit. It reads
     // the milestone surface and dispatches reviewer/security/tester subagents
     // to report findings without touching user source. Mirrors
@@ -405,6 +422,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
+    contextMode: "verification",
     // planning-dispatch: completion is a high-leverage place to fan out to
     // reviewer / security / tester subagents. They read the diff and report
     // findings; they do not write user source. Write isolation to .gsd/ is
@@ -428,6 +446,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "research",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["roadmap", "milestone-research", "dependency-summaries", "templates"],
@@ -442,6 +461,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "planning",
     // planning-dispatch: allows subagent dispatch so the planner can fan out
     // to scout for codebase recon and to planner/decompose-style specialists
     // for sub-decomposition. Write-isolation to .gsd/ is preserved.
@@ -459,6 +479,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "planning",
     // See plan-slice — same rationale: dispatch to scout/planner-style
     // specialists during refinement is materially better than re-doing recon
     // inline.
@@ -476,6 +497,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "planning",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["slice-plan", "slice-research", "dependency-summaries", "prior-task-summaries", "templates"],
@@ -490,6 +512,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
+    contextMode: "verification",
     // See complete-milestone — same rationale: dispatch to reviewer / security /
     // tester subagents to fan out review work without bloating this unit's
     // context.
@@ -511,6 +534,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "critical-only",
     codebaseMap: false,
     preferences: "none",
+    contextMode: "planning",
     tools: TOOLS_PLANNING,
     artifacts: {
       // Phase 2 pilot (#4782): manifest now matches today's actual
@@ -530,6 +554,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "execution",
     tools: TOOLS_ALL,
     artifacts: {
       inline: ["task-plan", "slice-plan", "prior-task-summaries", "templates"],
@@ -544,6 +569,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "execution",
     tools: TOOLS_ALL,
     artifacts: {
       inline: ["slice-plan", "prior-task-summaries", "templates"],
@@ -560,6 +586,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "critical-only",
     codebaseMap: false,
     preferences: "active-only",
+    contextMode: "verification",
     tools: TOOLS_PLANNING,
     artifacts: {
       // Phase 3 migration (#4782): manifest matches today's actual
@@ -578,6 +605,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "critical-only",
     codebaseMap: false,
     preferences: "active-only",
+    contextMode: "verification",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["slice-plan", "prior-task-summaries"],
@@ -592,6 +620,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "docs",
     tools: TOOLS_DOCS,
     artifacts: {
       inline: ["project", "requirements", "decisions", "templates"],
@@ -611,6 +640,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "none",
     codebaseMap: false,
     preferences: "none",
+    contextMode: "none",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: [],
@@ -628,6 +658,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "interview",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["templates"],
@@ -644,6 +675,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "interview",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: ["project", "templates"],
@@ -660,6 +692,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "none",
     codebaseMap: false,
     preferences: "none",
+    contextMode: "none",
     tools: TOOLS_PLANNING,
     artifacts: {
       inline: [],
@@ -678,6 +711,7 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: true,
     preferences: "active-only",
+    contextMode: "research",
     tools: { mode: "planning-dispatch", allowedSubagents: ["scout"] },
     artifacts: {
       inline: ["project", "requirements", "templates"],

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

@@ -1,3 +1,5 @@
+// GSD2 UOK Audit Events and DB-First Projection Writes
+
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -6,7 +8,7 @@ import { isStaleWrite } from "../auto/turn-epoch.js";
 import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
-import type { AuditEventEnvelope } from "./contracts.js";
+import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent, type AuditEventEnvelope } from "./contracts.js";
 
 function auditLogPath(basePath: string): string {
   return join(gsdRoot(basePath), "audit", "events.jsonl");
@@ -25,6 +27,7 @@ export function buildAuditEnvelope(args: {
   payload?: Record<string, unknown>;
 }): AuditEventEnvelope {
   return {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     eventId: randomUUID(),
     traceId: args.traceId,
     turnId: args.turnId,
@@ -39,6 +42,26 @@ export function buildAuditEnvelope(args: {
 export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
   // Drop writes from a turn superseded by timeout recovery / cancellation.
   if (isStaleWrite("uok-audit")) return;
+  const validation = validateAuditEvent(event);
+  if (!validation.ok) {
+    throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+  }
+  const canonical = validation.value;
+
+  if (isDbAvailable()) {
+    try {
+      insertAuditEvent({
+        ...canonical,
+        payload: {
+          ...canonical.payload,
+          contractVersion: canonical.version ?? CURRENT_UOK_CONTRACT_VERSION,
+        },
+      });
+    } catch (err) {
+      throw new Error(`DB authoritative audit write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   try {
     ensureAuditDir(basePath);
     const path = auditLogPath(basePath);
@@ -52,18 +75,11 @@ export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope):
     withFileLockSync(
       path,
       () => {
-        appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        appendFileSync(path, `${JSON.stringify(canonical)}\n`, "utf-8");
       },
       { onLocked: "skip" },
     );
   } 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.
-  }
 }