gsd-pi 2.71.0-dev.06b86c6 → 2.71.0-dev.4c35d99

package/src/resources/extensions/gsd/tests/register-shortcuts.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync } from "node:fs";
+import { mkdirSync, realpathSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -37,10 +37,10 @@ test("dashboard shortcut resolves the project root instead of the current worktr
   });
 
   let capturedHandler: ((ctx: any) => Promise<void>) | null = null;
-  const shortcuts: Array<{ description: string; handler: (ctx: any) => Promise<void> }> = [];
+  const shortcuts: Array<{ key: string; description: string; handler: (ctx: any) => Promise<void> }> = [];
   const pi = {
-    registerShortcut: (_key: unknown, shortcut: { description: string; handler: (ctx: any) => Promise<void> }) => {
-      shortcuts.push(shortcut);
+    registerShortcut: (key: unknown, shortcut: { description: string; handler: (ctx: any) => Promise<void> }) => {
+      shortcuts.push({ key: String(key), ...shortcut });
       if (!capturedHandler) {
         capturedHandler = shortcut.handler;
       }
@@ -69,5 +69,63 @@ test("dashboard shortcut resolves the project root instead of the current worktr
 
   assert.ok(customCalls > 0, "shortcut opens the dashboard overlay when project root is resolved");
   assert.equal(notices.length, 0, "shortcut does not fall back to the missing-.gsd warning");
-  assert.equal(shortcuts.length, 3, "all GSD shortcuts are still registered");
+  assert.equal(shortcuts.length, 5, "all GSD shortcuts are still registered");
+  const keys = shortcuts.map((shortcut) => shortcut.key);
+  assert.ok(keys.includes("ctrl+alt+g"), "primary dashboard shortcut is registered");
+  assert.ok(keys.includes("ctrl+shift+g"), "fallback dashboard shortcut is registered");
+  assert.ok(keys.includes("ctrl+alt+n"), "primary notifications shortcut is registered");
+  assert.ok(keys.includes("ctrl+shift+n"), "fallback notifications shortcut is registered");
+  assert.ok(keys.includes("ctrl+alt+p"), "primary parallel shortcut is registered");
+  // No Ctrl+Shift+P fallback — conflicts with cycleModelBackward (shift+ctrl+p)
+  assert.ok(!keys.includes("ctrl+shift+p"), "parallel fallback must not be registered (conflicts with cycleModelBackward)");
+});
+
+test("parallel shortcut passes resolved project root into overlay", async (t) => {
+  const base = makeTempDir("parallel-root");
+  const worktreeRoot = join(base, ".gsd", "worktrees", "M001");
+  mkdirSync(join(base, ".gsd", "parallel"), { recursive: true });
+  mkdirSync(worktreeRoot, { recursive: true });
+
+  const originalCwd = process.cwd();
+  process.chdir(worktreeRoot);
+  t.after(() => {
+    process.chdir(originalCwd);
+    cleanup(base);
+  });
+
+  const shortcuts: Array<{ key: string; description: string; handler: (ctx: any) => Promise<void> }> = [];
+  registerShortcuts({
+    registerShortcut: (key: unknown, shortcut: { description: string; handler: (ctx: any) => Promise<void> }) => {
+      shortcuts.push({ key: String(key), ...shortcut });
+    },
+  } as any);
+
+  const parallelShortcut = shortcuts.find((shortcut) => shortcut.key === "ctrl+alt+p");
+  assert.ok(parallelShortcut, "parallel shortcut is registered");
+
+  let capturedBasePath: string | undefined;
+  await parallelShortcut!.handler({
+    hasUI: true,
+    ui: {
+      custom: async (factory: any) => {
+        const overlay = factory(
+          { requestRender() {} },
+          { fg: (_color: string, text: string) => text, bold: (text: string) => text },
+          null,
+          () => {},
+        );
+        capturedBasePath = (overlay as any).basePath;
+        overlay.dispose?.();
+        return true;
+      },
+      notify: () => {},
+    },
+  });
+
+  assert.ok(capturedBasePath, "parallel shortcut should construct overlay with a basePath");
+  assert.equal(
+    realpathSync(capturedBasePath),
+    realpathSync(base),
+    "parallel overlay should use the resolved project root, not the worktree cwd",
+  );
 });

package/src/resources/extensions/gsd/tests/session-model-override.test.ts

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  clearSessionModelOverride,
+  getSessionModelOverride,
+  setSessionModelOverride,
+} from "../session-model-override.js";
+
+const phasesSource = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
+
+test("setSessionModelOverride stores provider/model for the session", () => {
+  const sessionId = `session-override-${Date.now()}`;
+  setSessionModelOverride(sessionId, { provider: "openai-codex", id: "gpt-5.4" });
+
+  const override = getSessionModelOverride(sessionId);
+  assert.equal(override?.provider, "openai-codex");
+  assert.equal(override?.id, "gpt-5.4");
+});
+
+test("clearSessionModelOverride removes the session override", () => {
+  const sessionId = `session-clear-${Date.now()}`;
+  setSessionModelOverride(sessionId, { provider: "anthropic", id: "claude-sonnet-4-6" });
+  clearSessionModelOverride(sessionId);
+  assert.equal(getSessionModelOverride(sessionId), undefined);
+});
+
+test("auto dispatch threads manual session model override into selectAndApplyModel", () => {
+  assert.ok(
+    phasesSource.includes("s.manualSessionModelOverride"),
+    "auto/phases.ts should pass s.manualSessionModelOverride into selectAndApplyModel",
+  );
+});

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -0,0 +1,90 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const gsdDir = resolve(import.meta.dirname, "..");
+
+function readGsdFile(relativePath: string): string {
+  return readFileSync(resolve(gsdDir, relativePath), "utf-8");
+}
+
+test("command entrypoints use startAutoDetached instead of awaiting startAuto (#3733)", () => {
+  const autoHandlerSrc = readGsdFile("commands/handlers/auto.ts");
+  const workflowHandlerSrc = readGsdFile("commands/handlers/workflow.ts");
+  const guidedFlowSrc = readGsdFile("guided-flow.ts");
+
+  assert.ok(
+    !autoHandlerSrc.includes("await startAuto("),
+    "auto command handler should not await startAuto from the active agent turn",
+  );
+  assert.ok(
+    !workflowHandlerSrc.includes("await startAuto("),
+    "workflow command handler should not await startAuto from the active agent turn",
+  );
+  assert.ok(
+    !guidedFlowSrc.includes("await startAuto("),
+    "guided flow should not await startAuto from the active agent turn",
+  );
+
+  assert.ok(
+    autoHandlerSrc.includes("startAutoDetached("),
+    "auto command handler should launch auto-mode through startAutoDetached",
+  );
+  assert.ok(
+    workflowHandlerSrc.includes("startAutoDetached("),
+    "workflow handler should launch auto-mode through startAutoDetached",
+  );
+  assert.ok(
+    guidedFlowSrc.includes("startAutoDetached("),
+    "guided flow should launch auto-mode through startAutoDetached",
+  );
+});
+
+test("startAutoDetached reports failures asynchronously (#3733)", () => {
+  const autoSrc = readGsdFile("auto.ts");
+
+  assert.ok(
+    autoSrc.includes("export function startAutoDetached"),
+    "auto.ts should export startAutoDetached",
+  );
+  assert.ok(
+    autoSrc.includes("void startAuto(ctx, pi, base, verboseMode, options).catch"),
+    "startAutoDetached should launch startAuto without awaiting it",
+  );
+  assert.ok(
+    autoSrc.includes("ctx.ui.notify(`Auto-start failed: ${message}`, \"error\")"),
+    "startAutoDetached should surface async startup failures to the user",
+  );
+});
+
+test("detached auto-start preserves milestone lock across pause/stop cleanup (#3733)", () => {
+  const autoSrc = readGsdFile("auto.ts");
+  const sessionSrc = readGsdFile("auto/session.ts");
+
+  assert.ok(
+    autoSrc.includes("milestoneLock?: string | null"),
+    "startAuto/startAutoDetached options should carry an explicit milestone lock",
+  );
+  assert.ok(
+    autoSrc.includes("s.sessionMilestoneLock = options.milestoneLock ?? null;"),
+    "startAuto should capture the requested milestone lock before async work begins",
+  );
+  assert.ok(
+    autoSrc.includes("milestoneLock: s.sessionMilestoneLock ?? undefined"),
+    "pause metadata should persist the detached milestone lock for resume",
+  );
+  assert.ok(
+    autoSrc.includes("s.sessionMilestoneLock = meta.milestoneLock ?? null;"),
+    "resume should restore the persisted milestone lock",
+  );
+  assert.ok(
+    autoSrc.includes("restoreMilestoneLockEnv();"),
+    "auto cleanup should restore the previous process milestone-lock env",
+  );
+
+  assert.ok(
+    sessionSrc.includes("sessionMilestoneLock: string | null = null;"),
+    "AutoSession should track the detached milestone lock explicitly",
+  );
+});

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

@@ -21,7 +21,10 @@ import {
   getMilestone,
   updateSliceStatus,
   setSliceSummaryMd,
+  saveGateResult,
+  getPendingGatesForTurn,
 } from "../gsd-db.js";
+import { getGatesForTurn } from "../gate-registry.js";
 import { resolveSliceFile, resolveSlicePath, clearPathCache } from "../paths.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -39,6 +42,23 @@ export interface CompleteSliceResult {
   uatPath: string;
 }
 
+/**
+ * Map a complete-slice-owned gate id to the CompleteSliceParams field
+ * whose presence drives `pass` vs. `omitted`. Keep this in lockstep with
+ * the gates declared in gate-registry.ts under ownerTurn "complete-slice".
+ */
+function sliceGateFieldForId(
+  id: string,
+  params: CompleteSliceParams,
+): string | undefined {
+  switch (id) {
+    case "Q8":
+      return params.operationalReadiness;
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Render slice summary markdown matching the template format.
  * YAML frontmatter uses snake_case keys for parseSummary() compatibility.
@@ -169,6 +189,10 @@ ${reqSurfaced}
 
 ${reqInvalidated}
 
+## Operational Readiness
+
+${params.operationalReadiness?.trim() || "None."}
+
 ## Deviations
 
 ${params.deviations || "None."}
@@ -330,6 +354,45 @@ export async function handleCompleteSlice(
   // Store rendered markdown in DB for D004 recovery
   setSliceSummaryMd(params.milestoneId, params.sliceId, summaryMd, uatMd);
 
+  // ── Close gates owned by complete-slice (Q8) ───────────────────────────
+  // Each owned gate maps to a specific summary section via the registry.
+  // If the caller populated the corresponding field, record `pass`; if the
+  // field is empty, record `omitted`. Without this loop, Q8 would stay
+  // pending forever and block future state derivation (see gate-registry).
+  try {
+    const pendingGates = getPendingGatesForTurn(
+      params.milestoneId,
+      params.sliceId,
+      "complete-slice",
+    );
+    if (pendingGates.length > 0) {
+      const ownedDefs = new Map(getGatesForTurn("complete-slice").map((g) => [g.id, g] as const));
+      for (const row of pendingGates) {
+        const def = ownedDefs.get(row.gate_id);
+        if (!def) continue;
+        // Map gate id → param field it maps to. Keep the map local so
+        // adding a new complete-slice gate is a single place change.
+        const field = sliceGateFieldForId(def.id, params);
+        const hasContent = typeof field === "string" && field.trim().length > 0;
+        saveGateResult({
+          milestoneId: params.milestoneId,
+          sliceId: params.sliceId,
+          gateId: def.id,
+          verdict: hasContent ? "pass" : "omitted",
+          rationale: hasContent
+            ? `${def.promptSection} section populated in slice summary`
+            : `${def.promptSection} section left empty — recorded as omitted`,
+          findings: hasContent ? (field as string).trim() : "",
+        });
+      }
+    }
+  } catch (gateErr) {
+    logWarning(
+      "tool",
+      `complete-slice gate close warning for ${params.milestoneId}/${params.sliceId}: ${(gateErr as Error).message}`,
+    );
+  }
+
   // Invalidate all caches
   invalidateStateCache();
   clearPathCache();

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

@@ -24,7 +24,10 @@ import {
   updateTaskStatus,
   setTaskSummaryMd,
   deleteVerificationEvidence,
+  saveGateResult,
+  getPendingGatesForTurn,
 } from "../gsd-db.js";
+import { getGatesForTurn } from "../gate-registry.js";
 import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -44,6 +47,27 @@ export interface CompleteTaskResult {
 
 import type { TaskRow } from "../gsd-db.js";
 
+/**
+ * Map an execute-task-owned gate id to the CompleteTaskParams field whose
+ * presence drives `pass` vs. `omitted`. Keep in lockstep with the gates
+ * declared in gate-registry.ts under ownerTurn "execute-task".
+ */
+function taskGateFieldForId(
+  id: string,
+  params: CompleteTaskParams,
+): string | undefined {
+  switch (id) {
+    case "Q5":
+      return params.failureModes;
+    case "Q6":
+      return params.loadProfile;
+    case "Q7":
+      return params.negativeTests;
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Normalize a list parameter that may arrive as a string (newline-delimited
  * bullet list from the LLM) into a string array (#3361).
@@ -236,6 +260,45 @@ export async function handleCompleteTask(
   // Store rendered markdown in DB for D004 recovery
   setTaskSummaryMd(params.milestoneId, params.sliceId, params.taskId, summaryMd);
 
+  // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
+  // Each gate id maps to a specific params field via taskGateFieldForId.
+  // When the model populates the field, record `pass`; when it's empty,
+  // record `omitted`. Task-scoped rows are filtered by taskId so a single
+  // task's completion doesn't touch sibling tasks' gate rows.
+  try {
+    const pendingGates = getPendingGatesForTurn(
+      params.milestoneId,
+      params.sliceId,
+      "execute-task",
+      params.taskId,
+    );
+    if (pendingGates.length > 0) {
+      const ownedDefs = new Map(getGatesForTurn("execute-task").map((g) => [g.id, g] as const));
+      for (const row of pendingGates) {
+        const def = ownedDefs.get(row.gate_id);
+        if (!def) continue;
+        const field = taskGateFieldForId(def.id, params);
+        const hasContent = typeof field === "string" && field.trim().length > 0;
+        saveGateResult({
+          milestoneId: params.milestoneId,
+          sliceId: params.sliceId,
+          taskId: params.taskId,
+          gateId: def.id,
+          verdict: hasContent ? "pass" : "omitted",
+          rationale: hasContent
+            ? `${def.promptSection} section populated in task summary`
+            : `${def.promptSection} section left empty — recorded as omitted`,
+          findings: hasContent ? (field as string).trim() : "",
+        });
+      }
+    }
+  } catch (gateErr) {
+    logWarning(
+      "tool",
+      `complete-task gate close warning for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(gateErr as Error).message}`,
+    );
+  }
+
   // Invalidate all caches
   invalidateStateCache();
   clearPathCache();

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

@@ -8,6 +8,7 @@ import {
   _getAdapter,
   saveGateResult,
 } from "../gsd-db.js";
+import { GATE_REGISTRY } from "../gate-registry.js";
 import { saveArtifactToDb } from "../db-writer.js";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -427,7 +428,9 @@ export async function executeSaveGateResult(
       };
   }
 
-  const validGates = ["Q3", "Q4", "Q5", "Q6", "Q7", "Q8"];
+  // Source of truth: gate-registry.ts. Every declared GateId is accepted,
+  // so adding a new gate in one place automatically flows through here.
+  const validGates = Object.keys(GATE_REGISTRY);
   if (!validGates.includes(params.gateId)) {
     return {
       content: [{ type: "text", text: `Error: Invalid gateId "${params.gateId}". Must be one of: ${validGates.join(", ")}` }],

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

@@ -536,6 +536,24 @@ export interface CompleteTaskParams {
     verdict: string;
     durationMs: number;
   }>;
+  /**
+   * Q5 failure-modes section content (what breaks when dependencies fail).
+   * Populated → `pass`; omitted/empty → `omitted`.
+   * @optional
+   */
+  failureModes?: string;
+  /**
+   * Q6 load-profile section content (10x breakpoint + protection).
+   * Populated → `pass`; omitted/empty → `omitted`.
+   * @optional
+   */
+  loadProfile?: string;
+  /**
+   * Q7 negative-tests section content (malformed inputs, error paths,
+   * boundaries). Populated → `pass`; omitted/empty → `omitted`.
+   * @optional
+   */
+  negativeTests?: string;
   /** Optional caller-provided identity for audit trail */
   actorName?: string;
   /** Optional caller-provided reason this action was triggered */
@@ -584,6 +602,14 @@ export interface CompleteSliceParams {
   affects?: string[];
   /** @optional — defaults to [] when omitted */
   drillDownPaths?: string[];
+  /**
+   * Q8 operational readiness section content (health signal, failure signal,
+   * recovery, monitoring gaps). When populated, the complete-slice handler
+   * records Q8 as `pass`; when omitted or empty, Q8 is recorded as `omitted`.
+   * See gate-registry.ts.
+   * @optional
+   */
+  operationalReadiness?: string;
   /** Optional caller-provided identity for audit trail */
   actorName?: string;
   /** Optional caller-provided reason this action was triggered */

package/src/resources/extensions/ollama/index.ts

@@ -57,7 +57,15 @@ async function probeAndRegister(pi: ExtensionAPI): Promise<boolean> {
 	}
 
 	const models = await discoverModels();
-	if (models.length === 0) return true; // Running but no models pulled
+	if (models.length === 0) {
+		// No local models means there's nothing usable to register in GSD.
+		// Keep the footer/status clean instead of advertising Ollama availability.
+		if (providerRegistered) {
+			pi.unregisterProvider("ollama");
+			providerRegistered = false;
+		}
+		return false;
+	}
 
 	const baseUrl = client.getOllamaHost();
 
@@ -115,9 +123,11 @@ export default function ollama(pi: ExtensionAPI) {
 		} else {
 			probeAndRegister(pi)
 				.then((found) => {
-					if (found) ctx.ui.setStatus("ollama", "Ollama");
+					ctx.ui.setStatus("ollama", found ? "Ollama" : undefined);
 				})
-				.catch(() => {});
+				.catch(() => {
+					ctx.ui.setStatus("ollama", undefined);
+				});
 		}
 	});
 

package/src/resources/extensions/ollama/ollama-status-indicator.test.ts

@@ -0,0 +1,28 @@
+/**
+ * Regression test: don't show an Ollama footer status unless Ollama is
+ * actually usable (running with at least one discovered model).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(__dirname, "index.ts"), "utf-8");
+
+test("probeAndRegister returns false when no Ollama models are discovered", () => {
+	assert.match(
+		src,
+		/if \(models\.length === 0\)[\s\S]*return false;/,
+		"running-without-models should not be treated as available",
+	);
+});
+
+test("interactive session clears ollama footer status when unavailable", () => {
+	assert.match(
+		src,
+		/ctx\.ui\.setStatus\("ollama", found \? "Ollama" : undefined\)/,
+		"status should be cleared when probeAndRegister reports unavailable",
+	);
+});

package/src/resources/extensions/shared/gsd-phase-state.ts

@@ -0,0 +1,42 @@
+/**
+ * GSD Phase State — cross-extension coordination
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ *
+ * Lightweight module-level state that GSD auto-mode writes to and the
+ * subagent tool reads from. Both extensions run in the same process so
+ * a module variable is sufficient — no file I/O needed.
+ */
+
+let _active = false;
+let _currentPhase: string | null = null;
+
+/** Mark GSD auto-mode as active. */
+export function activateGSD(): void {
+	_active = true;
+}
+
+/** Mark GSD auto-mode as inactive and clear the current phase. */
+export function deactivateGSD(): void {
+	_active = false;
+	_currentPhase = null;
+}
+
+/** Set the currently dispatched GSD phase (e.g. "plan-milestone"). */
+export function setCurrentPhase(phase: string): void {
+	_currentPhase = phase;
+}
+
+/** Clear the current phase (unit completed or aborted). */
+export function clearCurrentPhase(): void {
+	_currentPhase = null;
+}
+
+/** Returns true if GSD auto-mode is currently active. */
+export function isGSDActive(): boolean {
+	return _active;
+}
+
+/** Returns the current GSD phase, or null if none is active. */
+export function getCurrentPhase(): string | null {
+	return _active ? _currentPhase : null;
+}

package/src/resources/extensions/shared/tests/gsd-phase-state.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+	activateGSD,
+	deactivateGSD,
+	setCurrentPhase,
+	clearCurrentPhase,
+	isGSDActive,
+	getCurrentPhase,
+} from "../gsd-phase-state.js";
+
+describe("gsd-phase-state", () => {
+	beforeEach(() => {
+		deactivateGSD();
+	});
+
+	it("tracks active/inactive state", () => {
+		assert.equal(isGSDActive(), false);
+		activateGSD();
+		assert.equal(isGSDActive(), true);
+		deactivateGSD();
+		assert.equal(isGSDActive(), false);
+	});
+
+	it("tracks the current phase when active", () => {
+		activateGSD();
+		assert.equal(getCurrentPhase(), null);
+		setCurrentPhase("plan-milestone");
+		assert.equal(getCurrentPhase(), "plan-milestone");
+		clearCurrentPhase();
+		assert.equal(getCurrentPhase(), null);
+	});
+
+	it("returns null phase when inactive even if phase was set", () => {
+		activateGSD();
+		setCurrentPhase("plan-milestone");
+		deactivateGSD();
+		assert.equal(getCurrentPhase(), null);
+	});
+
+	it("deactivation clears the current phase", () => {
+		activateGSD();
+		setCurrentPhase("execute-task");
+		deactivateGSD();
+		activateGSD();
+		assert.equal(getCurrentPhase(), null);
+	});
+});

package/src/resources/extensions/subagent/agents.ts

@@ -15,6 +15,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	conflictsWith?: string[];
 	systemPrompt: string;
 	source: "user" | "project";
 	filePath: string;
@@ -30,6 +31,13 @@ interface AgentFrontmatter extends Record<string, unknown> {
 	description?: string;
 	tools?: string | string[];
 	model?: string;
+	conflicts_with?: string;
+}
+
+export function parseConflictsWith(value: string | undefined): string[] | undefined {
+	if (typeof value !== "string") return undefined;
+	const conflicts = value.split(",").map((s) => s.trim()).filter(Boolean);
+	return conflicts.length > 0 ? conflicts : undefined;
 }
 
 function parseAgentTools(value: string | string[] | undefined): string[] | undefined {
@@ -85,12 +93,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 		}
 
 		const tools = parseAgentTools(frontmatter.tools);
+		const conflictsWith = parseConflictsWith(frontmatter.conflicts_with);
 
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: frontmatter.model,
+			conflictsWith,
 			systemPrompt: body,
 			source,
 			filePath,

package/src/resources/extensions/subagent/index.ts

@@ -24,6 +24,7 @@ import { type ExtensionAPI, getMarkdownTheme } from "@gsd/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { formatTokenCount } from "../shared/mod.js";
+import { getCurrentPhase } from "../shared/gsd-phase-state.js";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
 import {
 	type IsolationEnvironment,
@@ -352,6 +353,23 @@ async function runSingleAgent(
 		};
 	}
 
+	// GSD phase guard: block agents that conflict with the active GSD phase
+	if (agent.conflictsWith && agent.conflictsWith.length > 0) {
+		const activePhase = getCurrentPhase();
+		if (activePhase && agent.conflictsWith.includes(activePhase)) {
+			return {
+				agent: agentName,
+				agentSource: agent.source,
+				task,
+				exitCode: 1,
+				messages: [],
+				stderr: `Agent "${agentName}" is blocked: it conflicts with the active GSD phase "${activePhase}". Use the built-in GSD workflow instead.`,
+				usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+				step,
+			};
+		}
+	}
+
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;