@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

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

@@ -15,11 +15,13 @@ import {
   insertGateRun,
   readTransaction,
   saveGateResult,
+  upsertMilestonePlanning,
   upsertQualityGate,
 } from "../gsd-db.js";
+import { extractMilestoneSeq } from "../milestone-ids.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relMilestoneFile, relSliceFile, relSlicePath, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
 import { hostname } from "node:os";
@@ -51,11 +53,13 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
+import { readUnitHarnessAbort, type UnitHarnessAbortRecord } from "../unit-runtime.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { appendNotification } from "../notification-store.js";
 import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
 import {
   claimMilestoneLease,
@@ -114,6 +118,48 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function blockIfHarnessAbortedUnit(operation: string, basePath: string): ToolExecutionResult | null {
+  const snapshot = getAutoRuntimeSnapshot();
+  if (!snapshot.active || !snapshot.currentUnit) return null;
+
+  const abort = readUnitHarnessAbort(
+    snapshot.basePath || basePath,
+    snapshot.currentUnit.type,
+    snapshot.currentUnit.id,
+    snapshot.currentUnit.startedAt,
+  );
+  if (!abort) return null;
+
+  return harnessAbortResult(operation, snapshot.currentUnit.type, snapshot.currentUnit.id, abort);
+}
+
+function harnessAbortResult(
+  operation: string,
+  unitType: string,
+  unitId: string,
+  abort: UnitHarnessAbortRecord,
+): ToolExecutionResult {
+  const toolText = abort.toolName ? ` while calling ${abort.toolName}` : "";
+  const message =
+    `Retryable harness abort: ${unitType} ${unitId} was truncated by ${abort.kind}${toolText}. ` +
+    "This gate result was not saved; leave the gate pending so auto-mode can rerun it.";
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      operation,
+      error: "harness_aborted_needs_retry",
+      retryable: true,
+      unitType,
+      unitId,
+      harnessAbortKind: abort.kind,
+      harnessAbortReason: abort.reason,
+      harnessAbortToolName: abort.toolName,
+      harnessAbortCount: abort.count,
+    },
+    isError: true,
+  };
+}
+
 function milestoneLeaseConflictResult(
   milestoneId: string,
   byWorker: string,
@@ -143,7 +189,34 @@ export interface SummarySaveParams {
 function registerProjectMilestoneSequence(content: string): string[] {
   const parsed = parseProject(content);
   const registered: string[] = [];
+  // Reconcile parsed IDs against existing DB milestones before inserting (#807).
+  // Under unique_milestone_ids the planner mints suffixed IDs (e.g. "M001-b1nole"),
+  // while PROJECT.md's template uses bare sequence IDs (e.g. "M001"). Inserting the
+  // bare ID verbatim mints a phantom milestone row that collides with the planner's
+  // canonical one: the bare row gets its own git worktree, and at dispatch time the
+  // worktree/session scope ("M001") disagrees with ctx.mid ("M001-b1nole"), pausing
+  // auto-mode with "Dispatch milestone mismatch". A project DB holds at most one
+  // milestone per sequence number, so map each parsed line onto the existing row
+  // that shares its sequence number instead of minting a duplicate bare-ID row.
+  const existingBySeq = new Map<number, string>();
+  for (const existing of getAllMilestones()) {
+    const seq = extractMilestoneSeq(existing.id);
+    if (seq > 0 && !existingBySeq.has(seq)) existingBySeq.set(seq, existing.id);
+  }
   for (const milestone of parsed.milestones) {
+    const canonicalId = existingBySeq.get(extractMilestoneSeq(milestone.id));
+    if (canonicalId && canonicalId !== milestone.id) {
+      // An existing milestone already owns this sequence number. Treat the markdown
+      // line as referring to it: refresh the human title, and promote to complete
+      // when the line is checked — but never demote an in-flight milestone back to
+      // "queued" (the planner's row stays the single source of truth).
+      upsertMilestonePlanning(canonicalId, {
+        title: milestone.title,
+        ...(milestone.done ? { status: "complete" } : {}),
+      });
+      registered.push(canonicalId);
+      continue;
+    }
     insertMilestone({
       id: milestone.id,
       title: milestone.title,
@@ -353,11 +426,21 @@ export async function executeSummarySave(
     } else if (params.artifact_type === "REQUIREMENTS-DRAFT") {
       relativePath = "REQUIREMENTS-DRAFT.md";
     } else if (params.task_id && params.slice_id) {
-      relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+      // Layout-aware path for task-scoped artifacts.
+      // Flat-phase: <phaseDir>/TID-TYPE.md  Legacy: milestones/MID/slices/SID/tasks/TID-TYPE.md
+      // relSlicePath returns ".gsd/phases/NN-slug" (flat) or ".gsd/milestones/MID/slices/SID" (legacy).
+      const sRel = relSlicePath(basePath, params.milestone_id!, params.slice_id).replace(/^\.gsd\//, "");
+      relativePath = sRel.startsWith("milestones/")
+        ? `${sRel}/tasks/${params.task_id}-${params.artifact_type}.md`
+        : `${sRel}/${params.task_id}-${params.artifact_type}.md`;
     } else if (params.slice_id) {
-      relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+      // Layout-aware path for slice-scoped artifacts.
+      // relSliceFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+      relativePath = relSliceFile(basePath, params.milestone_id!, params.slice_id, params.artifact_type).replace(/^\.gsd\//, "");
     } else {
-      relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+      // Layout-aware path for milestone-scoped artifacts.
+      // relMilestoneFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+      relativePath = relMilestoneFile(basePath, params.milestone_id!, params.artifact_type).replace(/^\.gsd\//, "");
     }
 
     const activeRequirements = params.artifact_type === "REQUIREMENTS"
@@ -1096,6 +1179,9 @@ export async function executeSaveGateResult(
   params: SaveGateResultParams,
   basePath: string = process.cwd(),
 ): Promise<ToolExecutionResult> {
+  const harnessAbort = blockIfHarnessAbortedUnit("save_gate_result", basePath);
+  if (harnessAbort) return harnessAbort;
+
   const dbAvailable = await ensureDbOpen(basePath);
   if (!dbAvailable) {
     return {
@@ -1167,6 +1253,9 @@ export async function executeUatResultSave(
   const unitGuard = blockIfWrongAutoUnit("run-uat", "save_uat_result");
   if (unitGuard) return unitGuard;
 
+  const harnessAbort = blockIfHarnessAbortedUnit("save_uat_result", basePath);
+  if (harnessAbort) return harnessAbort;
+
   const dbAvailable = await ensureDbOpen(basePath);
   if (!dbAvailable) return errorResult("save_uat_result", "GSD database is not available.", "db_unavailable");
 
@@ -1229,6 +1318,14 @@ export async function executeUatResultSave(
       evaluatedAt: run.evaluatedAt,
     });
     invalidateStateCache();
+    if (run.hasHuman) {
+      appendNotification(
+        `UAT for ${run.params.milestoneId}/${run.params.sliceId} has NEEDS-HUMAN checks awaiting human validation`,
+        "warning",
+        "notify",
+        { kind: "uat-needs-human", scope: `${run.params.milestoneId}/${run.params.sliceId}` },
+      );
+    }
     const savedText = `UAT result saved for ${run.params.milestoneId}/${run.params.sliceId}: ${run.params.verdict}`;
     return {
       content: [{

package/src/resources/extensions/gsd/triage-resolution.ts

@@ -14,7 +14,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { join } from "node:path";
 import { createRequire } from "node:module";
-import { gsdRoot, milestonesDir } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestonePath } from "./paths.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import type { Classification, CaptureEntry } from "./captures.js";
 import {
@@ -185,8 +185,9 @@ export function executeBacktrack(
     // so deriveState() will re-enter it as the active milestone.
     if (targetMilestoneId) {
       try {
-        const targetDir = join(milestonesDir(basePath), targetMilestoneId);
-        if (existsSync(targetDir)) {
+        // Use resolveMilestonePath to locate the dir in either legacy or flat-phase layout.
+        const targetDir = resolveMilestonePath(basePath, targetMilestoneId);
+        if (targetDir && existsSync(targetDir)) {
           // Write a regression marker so the state machine knows this milestone
           // needs re-discussion, not just re-execution
           const regressionPath = join(targetDir, `${targetMilestoneId}-REGRESSION.md`);
@@ -334,8 +335,13 @@ export function ensureDeferMilestoneDir(
 ): boolean {
   if (!MILESTONE_ID_RE.test(targetMilestone)) return false;
 
-  const msDir = join(milestonesDir(basePath), targetMilestone);
-  if (existsSync(msDir)) return true;
+  // Check if the milestone dir already exists in either layout.
+  const existingDir = resolveMilestonePath(basePath, targetMilestone);
+  if (existingDir && existsSync(existingDir)) return true;
+  // Create new dir in the layout-appropriate location.
+  const legacyBase = legacyMilestonesDir(basePath);
+  const msBase = existsSync(legacyBase) ? legacyBase : milestonesDir(basePath);
+  const msDir = join(msBase, targetMilestone);
 
   try {
     mkdirSync(msDir, { recursive: true });
@@ -495,8 +501,9 @@ export function executeTriageResolutions(
       }
     }
     for (const [milestoneId, captures] of byMilestone) {
-      const msDir = join(milestonesDir(basePath), milestoneId);
-      if (!existsSync(msDir)) {
+      // Use resolveMilestonePath to check existence in either layout.
+      const existingMs = resolveMilestonePath(basePath, milestoneId);
+      if (!existingMs || !existsSync(existingMs)) {
         const created = ensureDeferMilestoneDir(basePath, milestoneId, captures);
         if (created) {
           result.deferredMilestones++;

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

@@ -11,10 +11,11 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { parseUnitId } from "./unit-id.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveTaskFile, buildTaskFileName, buildSliceFileName } from "./paths.js";
+import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveSliceFile, resolveTaskFile, buildTaskFileName, buildSliceFileName } from "./paths.js";
 import { sendDesktopNotification } from "./notifications.js";
 import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
+import { UNIT_REGISTRY } from "./unit-registry.js";
 
 /**
  * Undo the last completed unit: revert git commits,
@@ -42,16 +43,20 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
     return;
   }
 
-  // Extract unit type and ID from the most recent activity log filename
-  // Format: <seq>-<unitType>-<unitId>.jsonl
-  const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
-  if (!match) {
+  // Extract unit type and ID from the most recent activity log filename.
+  // Both the unit type and the unit ID may contain hyphens, so anchor on the
+  // known unit-type vocabulary instead of guessing the unit-ID shape: a regex
+  // tuned to milestone-shaped IDs rejects project-level units whose IDs are
+  // symbolic (e.g. discuss-project uses PROJECT, workflow-preferences uses
+  // WORKFLOW-PREFS).
+  const parsed = parseActivityLogFilename(files[0]);
+  if (!parsed) {
     ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
     return;
   }
 
-  const unitType = match[1];
-  const unitId = match[2].replace(/-/g, "/");
+  const unitType = parsed.unitType;
+  const unitId = parsed.unitId.replace(/-/g, "/");
 
   if (!force) {
     ctx.ui.notify(
@@ -100,6 +105,11 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
   if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
     const [mid, sid, tid] = [milestone, slice, task];
     planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+    if (getTask(mid, sid, tid)) {
+      updateTaskStatus(mid, sid, tid, "pending");
+      await renderPlanCheckboxes(basePath, mid, sid);
+      planUpdated = true;
+    }
   }
 
   // 3. Try to revert git commits from activity log
@@ -348,15 +358,14 @@ export async function handleResetSlice(
   }
 
   // Delete slice summary and UAT files
+  // Use resolveSliceFile so the legacy S01-SUMMARY.md filename is found even
+  // when buildSliceFileName now returns the flat-phase 01-SUMMARY.md format.
   let sliceFilesDeleted = 0;
-  const slicePath = resolveSlicePath(basePath, mid, sid);
-  if (slicePath) {
-    for (const suffix of ["SUMMARY", "UAT"]) {
-      const filePath = join(slicePath, buildSliceFileName(sid, suffix));
-      if (existsSync(filePath)) {
-        unlinkSync(filePath);
-        sliceFilesDeleted++;
-      }
+  for (const suffix of ["SUMMARY", "UAT"] as const) {
+    const filePath = resolveSliceFile(basePath, mid, sid, suffix);
+    if (filePath && existsSync(filePath)) {
+      unlinkSync(filePath);
+      sliceFilesDeleted++;
     }
   }
 
@@ -380,6 +389,37 @@ export async function handleResetSlice(
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+// Known unit types sorted longest-first so a more specific type (e.g.
+// "execute-task-simple") matches before a prefix of it ("execute-task") when
+// splitting "<seq>-<unitType>-<unitId>.jsonl".
+const UNIT_TYPES_BY_LENGTH_DESC: readonly string[] = Object.keys(UNIT_REGISTRY).sort(
+  (a, b) => b.length - a.length,
+);
+
+/**
+ * Parse an activity-log filename of the form `<seq>-<unitType>-<unitId>.jsonl`
+ * (the format written by activity-log.ts). Both the unit type and the unit ID
+ * may contain hyphens, so we anchor on the known unit-type vocabulary rather
+ * than guessing the ID shape. This keeps non-milestone IDs (e.g. PROJECT,
+ * WORKFLOW-PREFS) parseable. Returns null when the name has no sequence prefix
+ * or does not start with a recognised unit type.
+ */
+export function parseActivityLogFilename(
+  filename: string,
+): { unitType: string; unitId: string } | null {
+  const seqMatch = filename.match(/^\d+-(.+)\.jsonl$/);
+  if (!seqMatch) return null;
+  const rest = seqMatch[1];
+  for (const unitType of UNIT_TYPES_BY_LENGTH_DESC) {
+    const prefix = `${unitType}-`;
+    if (rest.startsWith(prefix)) {
+      const unitId = rest.slice(prefix.length);
+      if (unitId.length > 0) return { unitType, unitId };
+    }
+  }
+  return null;
+}
+
 export function uncheckTaskInPlan(basePath: string, mid: string, sid: string, tid: string): boolean {
   const slicePath = resolveSlicePath(basePath, mid, sid);
   if (!slicePath) return false;

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

@@ -135,14 +135,38 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">,
     "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
 
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT: Record<string, string> = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "discuss-milestone":
+    "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+  "discuss-slice":
+    "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+  "discuss-project":
+    "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+  "discuss-requirements":
+    "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+  "replan-slice":
+    "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+  "reassess-roadmap":
+    "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
   "run-uat":
     "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+  "research-project":
+    "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+  "gate-evaluate":
+    "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "gate-evaluate":
+    "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 
 /**
@@ -160,7 +184,9 @@ export function composeContextModeInstructions(
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
   const guidance =
-    CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+    ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+    ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
     return `Context Mode (${lane} lane): ${guidance}`;
   }

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

@@ -140,6 +140,10 @@ export type ContextModePolicy =
  *                    restricted to .gsd/**. Subagent dispatch is denied unless
  *                    `allowedSubagents` opts a unit into controlled read-only
  *                    specialist delegation.
+ *   - "workflow-only"
+ *                  — Read tools + GSD workflow tools only. No generic writes
+ *                    and no generic shell; used by lanes whose durable output
+ *                    must be produced by a dedicated DB-backed workflow tool.
  *
  * The allowlist for "docs" is declared per-manifest rather than hardcoded so
  * projects with non-standard doc layouts can extend it without forking the
@@ -152,7 +156,8 @@ export type ToolsPolicy =
   | { readonly mode: "planning" }
   | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
   | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] }
-  | { readonly mode: "verification"; readonly allowedSubagents?: readonly string[] };
+  | { readonly mode: "verification"; readonly allowedSubagents?: readonly string[] }
+  | { readonly mode: "workflow-only"; readonly allowedSubagents?: readonly string[] };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
 
@@ -405,9 +410,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    // Validation may need to run shell verification commands and apply source
-    // fixes before milestone closeout can proceed.
-    tools: TOOLS_ALL,
+    // Validation must persist its durable output through gsd_validate_milestone;
+    // generic write/bash tools can create filesystem artifacts that bypass DB
+    // state and trigger destructive recovery loops.
+    tools: { mode: "workflow-only", allowedSubagents: ["reviewer", "security", "tester"] },
     artifacts: {
       inline: ["roadmap", "requirements", "templates"],
       excerpt: ["slice-summary", "slice-assessment"],
@@ -774,7 +780,7 @@ export function compileSubagentPermissionContract(
     return { allowed: true, allowedSubagents: ["*"], toolsMode: policy.mode };
   }
   if (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray(policy.allowedSubagents)
   ) {
     return {

package/src/resources/extensions/gsd/unit-registry.ts

@@ -98,7 +98,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_summary_save",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
       requiredWorkflowTools: ["gsd_summary_save"],
     },
   },
@@ -111,10 +117,11 @@ export const UNIT_REGISTRY = {
         "gsd_milestone_status",
         "gsd_plan_milestone",
         "gsd_plan_slice",
+        "gsd_plan_task",
         "gsd_decision_save",
         "gsd_requirement_update",
       ],
-      requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+      requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice", "gsd_plan_task"],
     },
   },
   "discuss-milestone": {
@@ -154,7 +161,15 @@ export const UNIT_REGISTRY = {
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
     toolContract: {
-      allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_validate_milestone",
+        "gsd_reassess_roadmap",
+        "subagent",
+      ],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
     },
   },
@@ -165,6 +180,9 @@ export const UNIT_REGISTRY = {
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_requirement_update",
         "gsd_summary_save",
         "gsd_complete_milestone",
@@ -183,7 +201,14 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_summary_save",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
       requiredWorkflowTools: ["gsd_summary_save"],
     },
   },
@@ -192,8 +217,17 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["planning"],
     toolContract: {
-      allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
-      requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_plan_slice",
+        "gsd_plan_task",
+        "gsd_reassess_roadmap",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
+      requiredWorkflowTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_reassess_roadmap"],
     },
   },
   "refine-slice": {
@@ -201,7 +235,14 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["planning"],
     toolContract: {
-      allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_plan_slice",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
       requiredWorkflowTools: ["gsd_plan_slice"],
     },
   },
@@ -220,7 +261,10 @@ export const UNIT_REGISTRY = {
     phaseChain: ["completion"],
     toolContract: {
       allowedGsdTools: [
+        "gsd_milestone_status",
         "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_slice_complete",
         "gsd_task_reopen",
         "gsd_replan_slice",
@@ -231,6 +275,7 @@ export const UNIT_REGISTRY = {
         "subagent",
       ],
       requiredWorkflowTools: [
+        "gsd_milestone_status",
         "gsd_exec",
         "gsd_capture_thought",
         "gsd_slice_complete",
@@ -302,7 +347,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "execute-task",
     phaseChain: ["execution"],
     toolContract: {
-      allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_summary_save",
+        "gsd_decision_save",
+      ],
       requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
     },
   },
@@ -389,12 +440,15 @@ export const UNIT_REGISTRY = {
       requiredWorkflowTools: ["ask_user_questions"],
     },
   },
+  // research-project dispatches 4 parallel scout subagents (Task calls); each scout
+  // writes one file under .gsd/research/ directly. The parent coordinator does not
+  // call gsd_summary_save or gsd_decision_save — the scouts own their own output.
   "research-project": {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [],
       requiredWorkflowTools: [],
     },
   },