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

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

@@ -65,6 +65,8 @@ import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } fr
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runAutoLoopWithUok } from "./uok/kernel.js";
+import { resolveUokFlags } from "./uok/flags.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 // ─── Session State ─────────────────────────────────────────────────────────
@@ -360,10 +362,22 @@ function clearUnitTimeout() {
 }
 /** Build snapshot metric opts. */
 function buildSnapshotOpts(_unitType, _unitId) {
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const uokFlags = resolveUokFlags(prefs);
     return {
         ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
         promptCharCount: s.lastPromptCharCount,
         baselineCharCount: s.lastBaselineCharCount,
+        traceId: s.currentTraceId ?? undefined,
+        turnId: s.currentTurnId ?? undefined,
+        ...(uokFlags.gitops
+            ? {
+                gitAction: uokFlags.gitopsTurnAction,
+                gitPush: uokFlags.gitopsTurnPush,
+                gitStatus: s.lastGitActionStatus ?? undefined,
+                gitError: s.lastGitActionFailure ?? undefined,
+            }
+            : {}),
         ...(s.currentUnitRouting ?? {}),
     };
 }
@@ -1165,7 +1179,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
         captureProjectRootEnv(s.originalBasePath || s.basePath);
-        await autoLoop(ctx, pi, s, buildLoopDeps());
+        await runAutoLoopWithUok({
+            ctx,
+            pi,
+            s,
+            deps: buildLoopDeps(),
+            runLegacyLoop: autoLoop,
+        });
         cleanupAfterLoopExit(ctx);
         return;
     }
@@ -1189,7 +1209,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
     // Dispatch the first unit
-    await autoLoop(ctx, pi, s, buildLoopDeps());
+    await runAutoLoopWithUok({
+        ctx,
+        pi,
+        s,
+        deps: buildLoopDeps(),
+        runLegacyLoop: autoLoop,
+    });
     cleanupAfterLoopExit(ctx);
 }
 // ─── Agent End Handler ────────────────────────────────────────────────────────

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

@@ -1,6 +1,7 @@
 // GSD2 — Extension registration: wires all GSD tools, commands, and hooks into pi
 import { registerExitCommand } from "../exit-command.js";
 import { registerWorktreeCommand } from "../worktree-command.js";
+import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
@@ -57,6 +58,9 @@ export function registerGsdExtension(pi) {
     registerWorktreeCommand(pi);
     registerExitCommand(pi);
     installEpipeGuard();
+    // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
+    // GSD-owned `before_agent_start` dispatch step (#3338).
+    const ecosystemHandlers = [];
     pi.registerCommand("kill", {
         description: "Exit GSD immediately (no cleanup)",
         handler: async (_args, _ctx) => {
@@ -71,7 +75,12 @@ export function registerGsdExtension(pi) {
         ["journal-tools", () => registerJournalTools(pi)],
         ["query-tools", () => registerQueryTools(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
-        ["hooks", () => registerHooks(pi)],
+        ["hooks", () => registerHooks(pi, ecosystemHandlers)],
+        ["ecosystem", () => {
+                void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {
+                    logWarning("ecosystem", `loader failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }],
     ];
     for (const [name, register] of nonCriticalRegistrations) {
         try {

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

@@ -1,5 +1,7 @@
 import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
+import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
+import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
@@ -29,7 +31,7 @@ async function syncServiceTierStatus(ctx) {
     const { getEffectiveServiceTier, formatServiceTierFooterStatus } = await import("../service-tier.js");
     ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
-export function registerHooks(pi) {
+export function registerHooks(pi, ecosystemHandlers) {
     pi.on("session_start", async (_event, ctx) => {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
@@ -39,8 +41,12 @@ export function registerHooks(pi) {
         resetToolCallLoopGuard();
         resetAskUserQuestionsCache();
         await syncServiceTierStatus(ctx);
-        const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-        prepareWorkflowMcpForProject(ctx, process.cwd());
+        // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
+        const { isInAutoWorktree } = await import("../auto-worktree.js");
+        if (!isInAutoWorktree(process.cwd())) {
+            const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+            prepareWorkflowMcpForProject(ctx, process.cwd());
+        }
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -80,12 +86,56 @@ export function registerHooks(pi) {
         resetAskUserQuestionsCache();
         clearDiscussionFlowState();
         await syncServiceTierStatus(ctx);
-        const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-        prepareWorkflowMcpForProject(ctx, process.cwd());
+        // Skip MCP auto-prep when running inside an auto-worktree. The worktree
+        // already has .mcp.json from createAutoWorktree, and re-running the writer
+        // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
+        // CLI path resolution), dirtying the tree and breaking the milestone merge.
+        const { isInAutoWorktree } = await import("../auto-worktree.js");
+        if (!isInAutoWorktree(process.cwd())) {
+            const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+            prepareWorkflowMcpForProject(ctx, process.cwd());
+        }
         loadToolApiKeys();
     });
     pi.on("before_agent_start", async (event, ctx) => {
-        return buildBeforeAgentStartResult(event, ctx);
+        // Wait for ecosystem loader to finish (no-op after first turn).
+        await getEcosystemReadyPromise();
+        // GSD's own context injection (existing behavior — unchanged).
+        const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+        // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
+        // deriveState has its own ~100ms cache so this is cheap on repeat calls.
+        try {
+            const state = await deriveState(process.cwd());
+            updateSnapshot(state);
+        }
+        catch {
+            updateSnapshot(null);
+        }
+        // Chain ecosystem handlers using pi's runner.ts chaining protocol:
+        // each handler sees the systemPrompt mutated by prior handlers.
+        let currentSystemPrompt = gsdResult?.systemPrompt ?? event.systemPrompt;
+        // `any` because pi's BeforeAgentStartEventResult.message uses an internal
+        // CustomMessage type that's not re-exported (see ecosystem/gsd-extension-api.ts).
+        let lastMessage = gsdResult?.message;
+        for (const handler of ecosystemHandlers) {
+            try {
+                const r = await handler({ ...event, systemPrompt: currentSystemPrompt }, ctx);
+                if (r?.systemPrompt !== undefined)
+                    currentSystemPrompt = r.systemPrompt;
+                if (r?.message)
+                    lastMessage = r.message;
+            }
+            catch (err) {
+                safetyLogWarning("ecosystem", `before_agent_start handler failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Compose result. Return undefined if nothing changed (preserves runner contract).
+        if (currentSystemPrompt === event.systemPrompt && !lastMessage)
+            return undefined;
+        return {
+            systemPrompt: currentSystemPrompt !== event.systemPrompt ? currentSystemPrompt : undefined,
+            message: lastMessage,
+        };
     });
     pi.on("agent_end", async (event, ctx) => {
         resetToolCallLoopGuard();
@@ -116,8 +166,10 @@ export function registerHooks(pi) {
         const state = await deriveState(basePath);
         if (!state.activeMilestone || !state.activeSlice || !state.activeTask)
             return;
-        if (state.phase !== "executing")
-            return;
+        // Write checkpoint for ALL phases, not just "executing" — discuss, research,
+        // and planning also carry in-memory state (user answers, gate verification)
+        // that would be lost on compaction (#4258).
+        // if (state.phase !== "executing") return;
         const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
         if (!sliceDir)
             return;
@@ -240,7 +292,7 @@ export function registerHooks(pi) {
     pi.on("tool_call", async (event, ctx) => {
         if (!isAutoActive())
             return;
-        safetyRecordToolCall(event.toolName, event.input);
+        safetyRecordToolCall(event.toolCallId, event.toolName, event.input);
         // Destructive command classification (warn only, never block)
         if (isToolCallEventType("bash", event)) {
             const classification = classifyCommand(event.input.command);

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

@@ -1,6 +1,6 @@
 // GSD Extension — Unified Cache Invalidation
 //
-// Three module-scoped caches exist across the GSD extension:
+// Three module-scoped read caches exist across the GSD extension:
 //   1. State cache (state.ts)  — memoized deriveState() result
 //   2. Path cache  (paths.ts)  — directory listing results (readdirSync)
 //   3. Parse cache (files.ts)  — parsed markdown file results
@@ -8,20 +8,31 @@
 // After any file write that changes .gsd/ contents, all three must be
 // invalidated together to prevent stale reads. This module provides a
 // single function that clears all three atomically.
+//
+// NOTE: The DB `artifacts` table is NOT included here. Earlier versions
+// called clearArtifacts() as part of this bundle (#793), intending to
+// force deriveState() to re-parse from disk when files were edited
+// out-of-band. But invalidateAllCaches() fires on every post-unit pass,
+// so bundling a DESTRUCTIVE `DELETE FROM artifacts` with routine cache
+// invalidation meant every row written by saveArtifactToDb / writeAndStore
+// was wiped within seconds — leaving the milestone completed on disk but
+// the `artifacts` table empty and the agent looping on "file exists but
+// DB record missing" recovery calls. If a call site genuinely needs the
+// artifact table cleared after an out-of-band file mutation, it should
+// invoke clearArtifacts() from gsd-db.js explicitly — do not add it back
+// here.
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
-import { clearArtifacts } from './gsd-db.js';
 /**
- * Invalidate all GSD runtime caches in one call.
+ * Invalidate all GSD runtime read caches in one call.
  *
  * Call this after file writes, milestone transitions, merge reconciliation,
  * or any operation that changes .gsd/ contents on disk. Forgetting to clear
- * any single cache causes stale reads (see #431, #793).
+ * any single cache causes stale reads (see #431).
  */
 export function invalidateAllCaches() {
     invalidateStateCache();
     clearPathCache();
     clearParseCache();
-    clearArtifacts();
 }

package/dist/resources/extensions/gsd/commands/handlers/ops.js

@@ -233,5 +233,10 @@ Examples:
         await handleAddTests(trimmed.replace(/^add-tests\s*/, "").trim(), ctx, pi);
         return true;
     }
+    if (trimmed === "extract-learnings" || trimmed.startsWith("extract-learnings ")) {
+        const { handleExtractLearnings } = await import("../../commands-extract-learnings.js");
+        await handleExtractLearnings(trimmed.replace(/^extract-learnings\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     return false;
 }

package/dist/resources/extensions/gsd/commands-extract-learnings.js

@@ -0,0 +1,225 @@
+/**
+ * GSD Command — /gsd extract-learnings
+ *
+ * Analyses completed milestone artefacts and dispatches an LLM turn that
+ * extracts structured knowledge into 4 categories:
+ *   Decisions · Lessons · Patterns · Surprises
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+// ─── Pure functions ───────────────────────────────────────────────────────────
+export function parseExtractLearningsArgs(args) {
+    const trimmed = args.trim();
+    return { milestoneId: trimmed || null };
+}
+export function buildLearningsOutputPath(milestoneDir, milestoneId) {
+    return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+export function resolvePhaseArtifacts(milestoneDir, milestoneId) {
+    const missingRequired = [];
+    const planFile = `${milestoneId}-PLAN.md`;
+    const summaryFile = `${milestoneId}-SUMMARY.md`;
+    const verificationFile = `${milestoneId}-VERIFICATION.md`;
+    const uatFile = `${milestoneId}-UAT.md`;
+    const planPath = join(milestoneDir, planFile);
+    const summaryPath = join(milestoneDir, summaryFile);
+    const verificationPath = join(milestoneDir, verificationFile);
+    const uatPath = join(milestoneDir, uatFile);
+    const plan = existsSync(planPath) ? planPath : null;
+    const summary = existsSync(summaryPath) ? summaryPath : null;
+    const verification = existsSync(verificationPath) ? verificationPath : null;
+    const uat = existsSync(uatPath) ? uatPath : null;
+    if (!plan)
+        missingRequired.push(planFile);
+    if (!summary)
+        missingRequired.push(summaryFile);
+    return { plan, summary, verification, uat, missingRequired };
+}
+export function buildExtractLearningsPrompt(ctx) {
+    const optionalSections = [];
+    if (ctx.verificationContent) {
+        optionalSections.push(`## Verification Report\n\n${ctx.verificationContent}`);
+    }
+    if (ctx.uatContent) {
+        optionalSections.push(`## UAT Report\n\n${ctx.uatContent}`);
+    }
+    const missingNote = ctx.missingArtifacts.length > 0
+        ? `\nNote: The following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+        : "";
+    return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+
+Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+
+### Decisions
+Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+
+### Lessons
+What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+
+### Patterns
+Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+
+### Surprises
+Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+
+### Source Attribution (REQUIRED)
+
+Every extracted item MUST include a \`Source:\` line immediately after the item text.
+Format: \`Source: {artifact-filename}/{section}\`
+Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+
+Items without a Source attribution are invalid and must not be included in the output.
+
+---
+
+## Artefacts
+
+### Plan
+
+${ctx.planContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+
+${optionalSections.join("\n\n---\n\n")}
+${missingNote}
+---
+
+## Output Format
+
+Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
+Each section should contain concise, actionable bullet points.
+Every bullet point MUST be followed by a source line, for example:
+
+\`\`\`
+### Decisions
+- Chose PostgreSQL over SQLite for concurrent write support.
+  Source: M001-PLAN.md/Architecture Decisions
+\`\`\`
+
+Items without a \`Source:\` line are invalid.
+
+---
+
+## Optional: Capture Individual Learnings
+
+If the \`capture_thought\` tool is available, call it once for each extracted item with:
+- category: "decision" | "lesson" | "pattern" | "surprise"
+- phase: "${ctx.milestoneId}"
+- content: {the learning text}
+- source: {artifact filename}
+
+If \`capture_thought\` is not available, skip this step silently — do not report an error.
+
+---
+
+## Rebuild Knowledge Graph
+
+After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+
+If the \`gsd_graph\` tool is not available, skip this step silently.
+`;
+}
+export function buildFrontmatter(ctx) {
+    const missingList = ctx.missingArtifacts.length > 0
+        ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
+        : "  []";
+    const missingValue = ctx.missingArtifacts.length > 0
+        ? `\n${missingList}`
+        : " []";
+    return `---
+phase: ${ctx.milestoneId}
+phase_name: ${ctx.milestoneName}
+project: ${ctx.projectName}
+generated: ${ctx.generatedAt}
+counts:
+  decisions: ${ctx.counts.decisions}
+  lessons: ${ctx.counts.lessons}
+  patterns: ${ctx.counts.patterns}
+  surprises: ${ctx.counts.surprises}
+missing_artifacts:${missingValue}
+---`;
+}
+export function extractProjectName(basePath) {
+    const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
+    if (existsSync(projectMdPath)) {
+        try {
+            const content = readFileSync(projectMdPath, "utf-8");
+            const match = content.match(/^name:\s*(.+)$/m);
+            if (match)
+                return match[1].trim();
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    return basename(basePath);
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handleExtractLearnings(args, ctx, pi) {
+    const { milestoneId } = parseExtractLearningsArgs(args);
+    if (!milestoneId) {
+        ctx.ui.notify("Usage: /gsd extract-learnings <milestoneId>  (e.g. M001)", "warning");
+        return;
+    }
+    // projectRoot() throws GSDNoProjectError if no project found — intentional, handled by dispatcher
+    const basePath = projectRoot();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) {
+        ctx.ui.notify(`Milestone not found: ${milestoneId}`, "error");
+        return;
+    }
+    const artifacts = resolvePhaseArtifacts(milestoneDir, milestoneId);
+    if (artifacts.missingRequired.length > 0) {
+        ctx.ui.notify(`Cannot extract learnings — required artefacts missing: ${artifacts.missingRequired.join(", ")}`, "error");
+        return;
+    }
+    // Read required artefacts
+    const planContent = readFileSync(artifacts.plan, "utf-8");
+    const summaryContent = readFileSync(artifacts.summary, "utf-8");
+    // Read optional artefacts
+    const verificationContent = artifacts.verification
+        ? readFileSync(artifacts.verification, "utf-8")
+        : null;
+    const uatContent = artifacts.uat
+        ? readFileSync(artifacts.uat, "utf-8")
+        : null;
+    // Determine missing optional artefacts for context
+    const missingArtifacts = [];
+    if (!artifacts.verification)
+        missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+    if (!artifacts.uat)
+        missingArtifacts.push(`${milestoneId}-UAT.md`);
+    // Extract milestone name from Plan H1 or fall back to milestoneId
+    const h1Match = planContent.match(/^#\s+(.+)$/m);
+    const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+    const projectName = extractProjectName(basePath);
+    const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+    const relativeOutputPath = outputPath.replace(basePath + "/", "");
+    const prompt = buildExtractLearningsPrompt({
+        milestoneId,
+        milestoneName,
+        outputPath,
+        relativeOutputPath,
+        planContent,
+        summaryContent,
+        verificationContent,
+        uatContent,
+        missingArtifacts,
+        projectName,
+    });
+    ctx.ui.notify(`Extracting learnings for ${milestoneId}: "${milestoneName}"...`, "info");
+    pi.sendMessage({ customType: "gsd-extract-learnings", content: prompt, display: false }, { triggerTurn: true });
+}

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -705,7 +705,7 @@ export function serializePreferencesToFrontmatter(prefs) {
         "budget_ceiling", "budget_enforcement", "context_pause_threshold",
         "notifications", "cmux", "remote_questions", "git",
         "post_unit_hooks", "pre_dispatch_hooks",
-        "dynamic_routing", "token_profile", "phases", "parallel",
+        "dynamic_routing", "uok", "token_profile", "phases", "parallel",
         "auto_visualize", "auto_report",
         "verification_commands", "verification_auto_fix", "verification_max_retries",
         "search_provider", "context_selection",

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -153,7 +153,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
 
-- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models. See token-optimization docs.
+- `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
@@ -191,6 +191,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `uok`: Unified Orchestration Kernel controls. Keys:
+  - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
+  - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
+    - Runtime override: set `GSD_UOK_FORCE_LEGACY=1` (or `GSD_UOK_LEGACY_FALLBACK=1`) to force legacy behavior for the current process.
+  - `gates.enabled`: boolean — route checks through the unified gate runner and persist `gate_runs`.
+  - `model_policy.enabled`: boolean — enforce policy filtering before model capability scoring.
+  - `execution_graph.enabled`: boolean — enable DAG scheduler facade/adapters for execution.
+  - `gitops.enabled`: boolean — persist turn-level git transaction records.
+  - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode.
+  - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata.
+  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events.
+  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
+
 - `context_management`: configures context hygiene for auto-mode sessions. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.