gsd-pi 2.79.0-dev.5c910bb05 → 2.79.0-dev.ece5fd8ba

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-dbdfc4ddfea7fdce
+76e1a0d39c0a27d8

package/dist/resources/extensions/gsd/auto/phases.js

@@ -1089,7 +1089,12 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     s.lastGitActionFailure = null;
     s.lastGitActionStatus = null;
     s.lastUnitAgentEndMessages = null;
-    setCurrentPhase(unitType);
+    setCurrentPhase(unitType, {
+        basePath: s.basePath,
+        traceId: ic.flowId,
+        turnId: `iter-${ic.iteration}`,
+        causedBy: "unit-start",
+    });
     s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
     const unitStartSeq = ic.nextSeq();
     deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });

package/dist/resources/extensions/gsd/auto-artifact-paths.js

@@ -128,9 +128,9 @@ export function diagnoseExpectedArtifact(unitType, unitId, base) {
             }
             return `${relSliceFile(base, mid, sid, "RESEARCH")} (slice research)`;
         case "plan-slice":
-            return `${relSliceFile(base, mid, sid, "PLAN")} (slice plan)`;
+            return `${relSliceFile(base, mid, sid, "PLAN")} plus tasks/T##-PLAN.md files (slice plan and task plans)`;
         case "refine-slice":
-            return `${relSliceFile(base, mid, sid, "PLAN")} (refined slice plan from sketch)`;
+            return `${relSliceFile(base, mid, sid, "PLAN")} plus tasks/T##-PLAN.md files (refined slice plan and task plans)`;
         case "execute-task": {
             return `Task ${tid} marked [x] in ${relSliceFile(base, mid, sid, "PLAN")} + summary written`;
         }

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -559,6 +559,8 @@ export const DISPATCH_RULES = [
             const hasContext = !!(contextFile && (await loadFile(contextFile)));
             if (hasContext)
                 return null; // fall through to next rule
+            if (prefs?.planning_depth === "deep")
+                return null;
             // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
             // pre-verify deep planning's user-facing milestone approval gate.
             if (shouldBypassMilestoneDepthGateInAuto(prefs)) {

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -257,7 +257,7 @@ function scanGsdTaggedCommits(basePath, milestoneId, gitArgs) {
             if (!commitMessageHasGsdTrailer(message))
                 continue;
             const commitFiles = getChangedFilesForCommit(basePath, hash);
-            if (!commitMatchesMilestone(message, milestoneId, commitFiles))
+            if (!commitMatchesMilestone(basePath, message, milestoneId, commitFiles))
                 continue;
             matched = true;
             for (const file of commitFiles) {
@@ -278,22 +278,37 @@ function getChangedFilesForCommit(basePath, hash) {
 function commitMessageHasGsdTrailer(message) {
     return /^GSD-(?:Task|Unit):\s*\S+/m.test(message);
 }
-function commitMatchesMilestone(message, milestoneId, files) {
+function commitMatchesMilestone(basePath, message, milestoneId, files) {
     if (commitTrailerStartsWithMilestone(message, milestoneId))
         return true;
     // Meaningful execute-task commits currently store task scope as Sxx/Tyy
     // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone when
     // either the commit touched this milestone's artifacts, or — for projects
     // where .gsd/ is gitignored/external (#5033) — the message explicitly
-    // names the milestone.
+    // names the milestone or local GSD state proves the task belongs here.
     if (/^GSD-Task:\s*S[^/\s]+\/T\S+/m.test(message)) {
         if (files.some((file) => isMilestoneArtifactPath(file, milestoneId)))
             return true;
         if (commitMessageMentionsMilestone(message, milestoneId))
             return true;
+        if (commitTaskTrailerBelongsToMilestone(basePath, message, milestoneId))
+            return true;
     }
     return false;
 }
+function commitTaskTrailerBelongsToMilestone(basePath, message, milestoneId) {
+    const match = message.match(/^GSD-Task:\s*(S[^/\s]+)\/(T[^\s]+)/m);
+    if (!match)
+        return false;
+    const [, sliceId, taskId] = match;
+    if (getTask(milestoneId, sliceId, taskId))
+        return true;
+    const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    if (!tasksDir)
+        return false;
+    return existsSync(join(tasksDir, `${taskId}-PLAN.md`))
+        || existsSync(join(tasksDir, `${taskId}-SUMMARY.md`));
+}
 function commitMessageMentionsMilestone(message, milestoneId) {
     if (!MILESTONE_ID_RE.test(milestoneId))
         return false;

package/dist/resources/extensions/gsd/auto-start.js

@@ -486,8 +486,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             // Clear survivor flag — finalization is done
             hasSurvivorBranch = false;
         }
+        const effectivePrefs = loadEffectiveGSDPreferences(base)?.preferences;
         const deepProjectStagePending = !hasSurvivorBranch
-            ? (await import("./auto-dispatch.js")).hasPendingDeepStage(loadEffectiveGSDPreferences(base)?.preferences, base)
+            ? (await import("./auto-dispatch.js")).hasPendingDeepStage(effectivePrefs, base)
             : false;
         if (deepProjectStagePending) {
             // Deep project-level setup runs before the first milestone exists. Let
@@ -526,7 +527,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 const mid = state.activeMilestone.id;
                 const contextFile = resolveMilestoneFile(base, mid, "CONTEXT");
                 const hasContext = !!(contextFile && (await loadFile(contextFile)));
-                if (!hasContext) {
+                if (!hasContext && effectivePrefs?.planning_depth !== "deep") {
                     const { showSmartEntry } = await import("./guided-flow.js");
                     await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
                     // showSmartEntry dispatches via pi.sendMessage() which is fire-and-forget:

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -166,7 +166,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
         const beforeAgentBasePath = process.cwd();
-        const pendingApprovalGate = getPendingGate();
+        const pendingApprovalGate = getPendingGate(beforeAgentBasePath);
         if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
             markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
             const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
@@ -363,15 +363,15 @@ export function registerHooks(pi, ecosystemHandlers) {
         // ── Discussion gate enforcement: block tool calls while gate is pending ──
         // If ask_user_questions was called with a gate ID but hasn't been confirmed,
         // block all non-read-only tool calls to prevent the model from skipping gates.
-        if (getPendingGate()) {
+        if (getPendingGate(discussionBasePath)) {
             const milestoneId = await getDiscussionMilestoneIdFor(discussionBasePath);
             if (isToolCallEventType("bash", event)) {
-                const bashGuard = shouldBlockPendingGateBash(event.input.command, milestoneId, isQueuePhaseActive());
+                const bashGuard = shouldBlockPendingGateBash(event.input.command, milestoneId, isQueuePhaseActive(discussionBasePath), discussionBasePath);
                 if (bashGuard.block)
                     return bashGuard;
             }
             else {
-                const gateGuard = shouldBlockPendingGate(toolName, milestoneId, isQueuePhaseActive());
+                const gateGuard = shouldBlockPendingGate(toolName, milestoneId, isQueuePhaseActive(discussionBasePath), discussionBasePath);
                 if (gateGuard.block)
                     return gateGuard;
             }
@@ -380,7 +380,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // When /gsd queue is active, the agent should only create milestones,
         // not execute work. Block write/edit to non-.gsd/ paths and bash commands
         // that would modify files.
-        if (isQueuePhaseActive()) {
+        if (isQueuePhaseActive(discussionBasePath)) {
             let queueInput = "";
             if (isToolCallEventType("write", event)) {
                 queueInput = event.input.path;
@@ -445,7 +445,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         if (!isToolCallEventType("write", event))
             return;
-        const result = shouldBlockContextWrite(event.toolName, event.input.path, await getDiscussionMilestoneIdFor(discussionBasePath), isQueuePhaseActive());
+        const result = shouldBlockContextWrite(event.toolName, event.input.path, await getDiscussionMilestoneIdFor(discussionBasePath), isQueuePhaseActive(discussionBasePath), discussionBasePath);
         if (result.block)
             return result;
     });
@@ -500,7 +500,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const basePath = process.cwd();
         const milestoneId = await getDiscussionMilestoneIdFor(basePath);
-        const queueActive = isQueuePhaseActive();
+        const queueActive = isQueuePhaseActive(basePath);
         const details = event.details;
         // ── Discussion gate enforcement: handle gate question responses ──
         // If the result is cancelled or has no response, the pending gate stays active
@@ -508,7 +508,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // If the user responded at all (even "needs adjustment"), clear the pending gate
         // because the user engaged — the prompt handles the re-ask-after-adjustment flow.
         const questions = event.input?.questions ?? [];
-        const currentPendingGate = getPendingGate();
+        const currentPendingGate = getPendingGate(basePath);
         if (currentPendingGate) {
             if (details?.cancelled || !details?.response) {
                 // Gate stays pending. Direct the agent to the most reliable recovery

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -298,8 +298,8 @@ export function getPendingGate(basePath = process.cwd()) {
  * Returns { block: true, reason } if the tool should be blocked.
  * ask_user_questions itself is allowed so the model can re-ask the gate.
  */
-export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive) {
-    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive, basePath = process.cwd()) {
+    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(basePath), toolName, milestoneId, queuePhaseActive);
 }
 export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
@@ -322,8 +322,8 @@ export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneI
  * Check whether a bash command should be blocked because a discussion gate is pending.
  * All bash is blocked while waiting for confirmation so the question stays visible.
  */
-export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive) {
-    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive, basePath = process.cwd()) {
+    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(basePath), command, milestoneId, queuePhaseActive);
 }
 export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
@@ -363,7 +363,7 @@ export function isDepthConfirmationAnswer(selected, options) {
     // Returning false prevents any free-form string from unlocking the gate.
     return false;
 }
-export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive) {
+export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive, basePath = process.cwd()) {
     if (toolName !== "write")
         return { block: false };
     if (!MILESTONE_CONTEXT_RE.test(inputPath))
@@ -379,7 +379,7 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
             ].join(" "),
         };
     }
-    if (isMilestoneDepthVerified(targetMilestoneId))
+    if (isMilestoneDepthVerified(targetMilestoneId, basePath))
         return { block: false };
     return {
         block: true,
@@ -397,8 +397,8 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
  * Slice-level CONTEXT artifacts are allowed; milestone-level CONTEXT writes
  * require the milestone to be depth-verified first.
  */
-export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId) {
-    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId, basePath = process.cwd()) {
+    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(basePath), artifactType, milestoneId, sliceId);
 }
 export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType, milestoneId, sliceId) {
     if (artifactType !== "CONTEXT")

package/dist/resources/extensions/gsd/guided-flow.js

@@ -44,6 +44,7 @@ import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
+import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
@@ -295,6 +296,14 @@ export async function checkDeepProjectSetupAfterTurn(_event, ctx, basePath) {
             return false;
         }
     }
+    // R2: a depth-verification gate is still pending — the LLM emitted the
+    // confirmation question (via ask_user_questions or plain chat) but the user
+    // has not approved yet. Returning false keeps the entry in the
+    // pendingDeepProjectSetupMap so the next user message can resume.
+    const pendingGateId = getPendingGate(entry.basePath);
+    if (pendingGateId) {
+        return false;
+    }
     return dispatchNextDeepProjectSetupStage(entry);
 }
 async function dispatchNextDeepProjectSetupStage(entry) {
@@ -368,6 +377,23 @@ export function checkAutoStartAfterDiscuss() {
     const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
     if (!contextFile && !roadmapFile)
         return false; // neither artifact yet — keep waiting
+    // Gate 1a: a depth-verification gate is still pending for THIS milestone — the
+    // LLM emitted the confirmation question (via ask_user_questions or plain chat)
+    // but the user has not answered yet. Advancing now would skip the gate and
+    // race ahead with unverified context.
+    const basePathForGate = entry.scope.workspace.projectRoot;
+    const pendingGateId = getPendingGate(basePathForGate);
+    if (pendingGateId) {
+        const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
+        // Block advancement if the gate is for THIS milestone, OR if it's a
+        // project/requirements gate (no milestone id encoded) for the deep setup flow.
+        const isProjectGate = pendingGateId === "depth_verification_project_confirm" ||
+            pendingGateId === "depth_verification_requirements_confirm" ||
+            pendingGateId === "depth_verification_research_decision_confirm";
+        if (pendingMilestoneId === milestoneId || isProjectGate) {
+            return false;
+        }
+    }
     // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
     // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
     // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
@@ -489,6 +515,20 @@ export function checkAutoStartAfterDiscuss() {
             logWarning("guided", `manifest unlink failed: ${e.message}`);
         }
     }
+    // R3b: belt-and-suspenders for silent registration failure. The discuss flow
+    // finished and STATE.md exists, but the milestone may never have landed in
+    // the DB. Without this guard, the user sees "Milestone M001 ready." and then
+    // /gsd reports "No Active Milestone".
+    if (isDbAvailable()) {
+        const milestoneRow = getMilestone(milestoneId);
+        if (!milestoneRow) {
+            ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+                `PROJECT.md may have failed to register milestones. ` +
+                `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+                `then re-run /gsd to recover.`, "error");
+            return false;
+        }
+    }
     pendingAutoStartMap.delete(basePath);
     ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
     startAutoDetached(ctx, pi, basePath, false, { step });

package/dist/resources/extensions/gsd/paths.js

@@ -177,8 +177,12 @@ export function resolveDir(parentDir, idPrefix) {
         const exact = entries.find(e => e.isDirectory() && e.name === idPrefix);
         if (exact)
             return exact.name;
+        const idLower = idPrefix.toLowerCase();
+        const exactCaseInsensitive = entries.find(e => e.isDirectory() && e.name.toLowerCase() === idLower);
+        if (exactCaseInsensitive)
+            return exactCaseInsensitive.name;
         // Prefix match for legacy descriptor dirs: M001-SOMETHING
-        const prefixed = entries.find(e => e.isDirectory() && e.name.startsWith(idPrefix + "-"));
+        const prefixed = entries.find(e => e.isDirectory() && e.name.toLowerCase().startsWith(idLower + "-"));
         return prefixed ? prefixed.name : null;
     }
     catch {

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -141,7 +141,6 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
             task_id: isRootArtifact ? undefined : params.task_id,
         }, basePath);
         let registeredMilestones = [];
-        let registrationWarning;
         if (params.artifact_type === "PROJECT") {
             try {
                 registeredMilestones = registerProjectMilestoneSequence(contentToSave);
@@ -150,12 +149,55 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                registrationWarning = `PROJECT artifact saved, but milestone registration failed: ${msg}`;
-                logWarning("tool", registrationWarning, {
+                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) {
@@ -178,7 +220,6 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
                 artifact_type: params.artifact_type,
                 content_source: contentSource,
                 ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
-                ...(registrationWarning ? { warning: registrationWarning } : {}),
             },
         };
     }

package/dist/resources/extensions/gsd/uok/audit.js

@@ -1,3 +1,4 @@
+// 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";
@@ -5,6 +6,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 { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent } from "./contracts.js";
 function auditLogPath(basePath) {
     return join(gsdRoot(basePath), "audit", "events.jsonl");
 }
@@ -13,6 +15,7 @@ function ensureAuditDir(basePath) {
 }
 export function buildAuditEnvelope(args) {
     return {
+        version: CURRENT_UOK_CONTRACT_VERSION,
         eventId: randomUUID(),
         traceId: args.traceId,
         turnId: args.turnId,
@@ -27,6 +30,25 @@ export function emitUokAuditEvent(basePath, event) {
     // 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);
@@ -39,18 +61,10 @@ export function emitUokAuditEvent(basePath, event) {
         // POSIX O_APPEND atomicity still protects small line writes, so skipping
         // the lock rather than stalling orchestration is the correct tradeoff.
         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.
-    }
 }

package/dist/resources/extensions/gsd/uok/contracts.js

@@ -1 +1,69 @@
-export {};
+// GSD2 UOK Contract Types and Versioning
+export const CURRENT_UOK_CONTRACT_VERSION = "1";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeVersion(value) {
+    return value === CURRENT_UOK_CONTRACT_VERSION ? CURRENT_UOK_CONTRACT_VERSION : "0";
+}
+function requireString(value, key, issues) {
+    if (typeof value[key] !== "string" || value[key] === "") {
+        issues.push({ path: key, message: `${key} must be a non-empty string` });
+    }
+}
+function requireRecord(value, key, issues) {
+    if (!isRecord(value[key])) {
+        issues.push({ path: key, message: `${key} must be an object` });
+    }
+}
+export function normalizeTurnResult(value) {
+    return { ...value, version: normalizeVersion(value.version) };
+}
+export function normalizeDispatchEnvelope(value) {
+    return { ...value, version: normalizeVersion(value.version) };
+}
+export function normalizeAuditEvent(value) {
+    return { ...value, version: normalizeVersion(value.version) };
+}
+export function validateTurnResult(value) {
+    const normalized = normalizeTurnResult(value);
+    const record = normalized;
+    const issues = [];
+    requireString(record, "traceId", issues);
+    requireString(record, "turnId", issues);
+    if (!Number.isInteger(record.iteration)) {
+        issues.push({ path: "iteration", message: "iteration must be an integer" });
+    }
+    requireString(record, "status", issues);
+    requireString(record, "failureClass", issues);
+    if (!Array.isArray(record.phaseResults)) {
+        issues.push({ path: "phaseResults", message: "phaseResults must be an array" });
+    }
+    requireString(record, "startedAt", issues);
+    requireString(record, "finishedAt", issues);
+    return { ok: issues.length === 0, value: normalized, issues };
+}
+export function validateDispatchEnvelope(value) {
+    const normalized = normalizeDispatchEnvelope(value);
+    const record = normalized;
+    const issues = [];
+    requireString(record, "action", issues);
+    requireRecord(record, "reason", issues);
+    if (isRecord(record.reason)) {
+        requireString(record.reason, "reasonCode", issues);
+        requireString(record.reason, "summary", issues);
+    }
+    return { ok: issues.length === 0, value: normalized, issues };
+}
+export function validateAuditEvent(value) {
+    const normalized = normalizeAuditEvent(value);
+    const record = normalized;
+    const issues = [];
+    requireString(record, "eventId", issues);
+    requireString(record, "traceId", issues);
+    requireString(record, "category", issues);
+    requireString(record, "type", issues);
+    requireString(record, "ts", issues);
+    requireRecord(record, "payload", issues);
+    return { ok: issues.length === 0, value: normalized, issues };
+}

package/dist/resources/extensions/gsd/uok/dispatch-envelope.js

@@ -1,5 +1,8 @@
+// GSD2 UOK Dispatch Envelope Builder
+import { CURRENT_UOK_CONTRACT_VERSION } from "./contracts.js";
 export function buildDispatchEnvelope(input) {
     return {
+        version: CURRENT_UOK_CONTRACT_VERSION,
         action: input.action,
         nodeKind: input.node?.kind,
         unitType: input.unitType,

package/dist/resources/extensions/gsd/uok/loop-adapter.js

@@ -1,3 +1,5 @@
+// GSD2 UOK Turn Observer and DB-Backed Lifecycle Emission
+import { CURRENT_UOK_CONTRACT_VERSION, validateTurnResult } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
 import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
@@ -115,46 +117,59 @@ export function createTurnObserver(options) {
             }
         },
         onTurnResult(result) {
-            const merged = {
-                ...result,
-                phaseResults: result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+            const cleanup = () => {
+                if (writerToken) {
+                    releaseWriterToken(options.basePath, writerToken);
+                }
+                writerToken = null;
+                current = null;
+                phaseResults.length = 0;
             };
-            if (options.enableAudit) {
-                emitUokAuditEvent(options.basePath, buildAuditEnvelope({
-                    traceId: merged.traceId,
-                    turnId: merged.turnId,
-                    category: "orchestration",
-                    type: "turn-result",
-                    payload: nextSequenceMetadata("audit", "append", {
+            try {
+                const merged = {
+                    ...result,
+                    version: CURRENT_UOK_CONTRACT_VERSION,
+                    phaseResults: Array.isArray(result.phaseResults) && result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+                };
+                const validation = validateTurnResult(merged);
+                if (!validation.ok) {
+                    throw new Error(`Invalid UOK turn result: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+                }
+                if (options.enableAudit) {
+                    emitUokAuditEvent(options.basePath, buildAuditEnvelope({
+                        traceId: validation.value.traceId,
+                        turnId: validation.value.turnId,
+                        category: "orchestration",
+                        type: "turn-result",
+                        payload: nextSequenceMetadata("audit", "append", {
+                            contractVersion: validation.value.version,
+                            unitType: validation.value.unitType,
+                            unitId: validation.value.unitId,
+                            status: validation.value.status,
+                            failureClass: validation.value.failureClass,
+                            error: validation.value.error,
+                            phaseCount: validation.value.phaseResults.length,
+                        }),
+                    }));
+                }
+                if (options.enableGitops) {
+                    const closeout = merged.closeout ?? {
+                        traceId: merged.traceId,
+                        turnId: merged.turnId,
                         unitType: merged.unitType,
                         unitId: merged.unitId,
                         status: merged.status,
                         failureClass: merged.failureClass,
-                        error: merged.error,
-                        phaseCount: merged.phaseResults.length,
-                    }),
-                }));
+                        gitAction: options.gitAction,
+                        gitPushed: options.gitPush,
+                        finishedAt: merged.finishedAt,
+                    };
+                    writeTurnCloseoutGitRecord(options.basePath, closeout, nextSequenceMetadata("gitops", "update", { action: "record" }));
+                }
             }
-            if (options.enableGitops) {
-                const closeout = merged.closeout ?? {
-                    traceId: merged.traceId,
-                    turnId: merged.turnId,
-                    unitType: merged.unitType,
-                    unitId: merged.unitId,
-                    status: merged.status,
-                    failureClass: merged.failureClass,
-                    gitAction: options.gitAction,
-                    gitPushed: options.gitPush,
-                    finishedAt: merged.finishedAt,
-                };
-                writeTurnCloseoutGitRecord(options.basePath, closeout, nextSequenceMetadata("gitops", "update", { action: "record" }));
+            finally {
+                cleanup();
             }
-            if (writerToken) {
-                releaseWriterToken(options.basePath, writerToken);
-            }
-            writerToken = null;
-            current = null;
-            phaseResults.length = 0;
         },
     };
 }