gsd-pi 2.79.0 → 2.80.0

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

@@ -11,7 +11,9 @@ import {
   _getAdapter,
   insertGateRow,
   upsertRequirement,
+  getAllMilestones,
 } from "../gsd-db.ts";
+import { deriveState, invalidateStateCache } from "../state.ts";
 import { markApprovalGateVerified, markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot, setPendingGate } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
@@ -690,7 +692,18 @@ test("executeSummarySave supports root-level deep planning artifacts", async ()
 
     const project = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "A root project artifact.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n"),
     }, base));
     assert.equal(project.isError, undefined);
     assert.equal(project.details.path, "PROJECT.md");
@@ -737,6 +750,109 @@ test("executeSummarySave supports root-level deep planning artifacts", async ()
   }
 });
 
+test("executeSummarySave registers PROJECT milestone sequence for the next run", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "Deep project setup output.",
+        "",
+        "## Project Shape",
+        "",
+        "**Complexity:** complex",
+        "**Why:** It spans multiple delivery steps.",
+        "",
+        "## Capability Contract",
+        "",
+        "See .gsd/REQUIREMENTS.md.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "- [ ] M002: Polish - Follow-up experience work.",
+        "",
+      ].join("\n"),
+    }, base));
+
+    assert.equal(result.isError, undefined);
+    assert.deepEqual(result.details.registeredMilestones, ["M001", "M002"]);
+
+    const milestones = getAllMilestones();
+    assert.deepEqual(
+      milestones.map((m) => [m.id, m.title, m.status]),
+      [
+        ["M001", "Foundation", "queued"],
+        ["M002", "Polish", "queued"],
+      ],
+    );
+
+    invalidateStateCache();
+    const state = await deriveState(base);
+    assert.equal(state.activeMilestone?.id, "M001");
+    assert.equal(state.phase, "pre-planning");
+    assert.equal(state.registry[0]?.status, "active");
+    assert.equal(state.registry[1]?.status, "pending");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave hard-fails when milestone registration throws so silent No-Active-Milestone is impossible", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const db = _getAdapter();
+    assert.ok(db, "DB should be open");
+    const originalPrepare = db.prepare.bind(db);
+    (db as any).prepare = (sql: string) => {
+      if (sql.includes("INSERT OR IGNORE INTO milestones")) {
+        throw new Error("simulated milestone registration failure");
+      }
+      return originalPrepare(sql);
+    };
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "Deep project setup output.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n"),
+    }, base));
+
+    // The artifact is persisted before registration runs, but registration must
+    // surface as isError so the LLM retries (INSERT OR IGNORE makes it idempotent)
+    // instead of announcing "ready" while the DB has zero milestone rows.
+    assert.equal(result.isError, true);
+    assert.equal(result.details.path, "PROJECT.md");
+    assert.equal(result.details.error, "milestone_registration_threw");
+    assert.match(String(result.details.registration_error), /simulated milestone registration failure/);
+    assert.match(result.content[0].text, /milestone registration failed/);
+    assert.match(result.content[0].text, /idempotent/);
+    assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
+    const artifact = originalPrepare("SELECT path FROM artifacts WHERE path = ?").get("PROJECT.md");
+    assert.equal(artifact?.path, "PROJECT.md");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSummarySave blocks final root artifacts while approval gate is pending", async () => {
   const base = makeTmpBase();
   try {
@@ -772,9 +888,22 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
     writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\nplanning_depth: deep\n---\n");
     openTestDb(base);
 
+    const projectFixture = [
+      "# Project",
+      "",
+      "## What This Is",
+      "",
+      "A root project artifact.",
+      "",
+      "## Milestone Sequence",
+      "",
+      "- [ ] M001: Foundation - Establish the first runnable slice.",
+      "",
+    ].join("\n");
+
     const blocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(blocked.isError, true);
@@ -786,7 +915,7 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
 
     const unblocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
-      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+      content: projectFixture,
     }, base));
 
     assert.equal(unblocked.isError, undefined);

package/src/resources/extensions/gsd/tests/worktree-path-injection.test.ts

@@ -229,6 +229,9 @@ test("worktree-aware prompt builders include the explicit working directory", as
     ),
   ]);
 
+  assert.ok(prompts[0].includes("## Context Mode"), "discuss-milestone should include standalone Context Mode guidance");
+  assert.ok(prompts[0].includes("interview lane"), "discuss-milestone should render the interview lane");
+
   for (const prompt of prompts) {
     assert.match(prompt, /working directory/i);
     assert.ok(prompt.includes(base), "prompt should include the provided working directory");

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);

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 scans, builds, and tests so full output stays out of prompt context; call `gsd_exec_search` before repeating prior runs; call `gsd_resume` after compaction or resume to recover stored execution context.";
+
+/**
+ * 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.
-  }
 }