@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

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

@@ -12,6 +12,7 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
 import type { GateId } from "../types.js";
 
 export interface PlanTaskParams {
@@ -26,6 +27,8 @@ export interface PlanTaskParams {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  /** Repository id(s) this task touches (parent workspace); omitted for single-repo projects. */
+  targetRepositories?: string[];
   fullPlanMd?: string;
   /** Optional caller-provided identity for audit trail */
   actorName?: string;
@@ -40,6 +43,63 @@ export interface PlanTaskResult {
   taskPlanPath: string;
 }
 
+function validateRepositoryTargetIds(field: string, value: unknown): string[] {
+  const ids = validateStringArray(value, field);
+  if (ids.length === 0) throw new Error(`${field} must include at least one repository id when provided`);
+  const deduped = Array.from(new Set(ids.map((id) => id.trim()).filter(Boolean)));
+  if (deduped.length === 0) throw new Error(`${field} must include at least one repository id when provided`);
+  return deduped;
+}
+
+function validateReferencedRepositories(
+  targetRepositories: string[] | undefined,
+  registry: RepositoryRegistry,
+): string | null {
+  if (!targetRepositories) return null;
+  const known = new Set(registry.repositories.map((repo) => repo.id));
+  const missing = targetRepositories.filter((id) => !known.has(id));
+  if (missing.length === 0) return null;
+  return `unknown targetRepositories: ${missing.join(", ")}. Declared repositories: ${Array.from(known).join(", ")}`;
+}
+
+function resolveAllowedRootsForPathScope(
+  targetRepositories: string[],
+  registry: RepositoryRegistry,
+): string[] {
+  if (targetRepositories.length === 0) return [registry.projectRoot];
+  const roots = targetRepositories
+    .map((id) => registry.byId.get(id)?.root)
+    .filter((root): root is string => typeof root === "string");
+  return roots.length > 0 ? roots : [registry.projectRoot];
+}
+
+function validatePathScopeForTargetRepositories(
+  params: PlanTaskParams,
+  basePath: string,
+  registry: RepositoryRegistry,
+  targetRepositories: string[],
+): string | null {
+  return validatePlanningPathScope(
+    basePath,
+    [
+      { field: "files", values: params.files },
+      { field: "inputs", values: params.inputs },
+      { field: "expectedOutput", values: params.expectedOutput },
+    ],
+    resolveAllowedRootsForPathScope(targetRepositories, registry),
+  );
+}
+
+function resolveEffectiveTargetRepositories(
+  taskTargetRepositories: string[] | undefined,
+  sliceTargetRepositories: string[] | undefined,
+  defaultTargets: string[],
+): string[] {
+  if (taskTargetRepositories) return taskTargetRepositories;
+  if (sliceTargetRepositories?.length) return sliceTargetRepositories;
+  return defaultTargets;
+}
+
 function validateParams(params: PlanTaskParams): PlanTaskParams {
   if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
   if (!isNonEmptyString(params?.sliceId)) throw new Error("sliceId is required");
@@ -57,6 +117,9 @@ function validateParams(params: PlanTaskParams): PlanTaskParams {
     files: validateStringArray(params.files, "files"),
     inputs: validateStringArray(params.inputs, "inputs"),
     expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
+    ...(params.targetRepositories !== undefined
+      ? { targetRepositories: validateRepositoryTargetIds("targetRepositories", params.targetRepositories) }
+      : {}),
   };
 }
 
@@ -84,23 +147,19 @@ export async function handlePlanTask(
     return { error: `validation failed: ${pathOnlyError}` };
   }
 
-  const pathScopeError = validatePlanningPathScope(basePath, [
-    { field: "files", values: params.files },
-    { field: "inputs", values: params.inputs },
-    { field: "expectedOutput", values: params.expectedOutput },
-  ]);
-  if (pathScopeError) {
-    return { error: `validation failed: ${pathScopeError}` };
-  }
-
   let taskGates: GateId[];
+  let repositoryRegistry: RepositoryRegistry;
   try {
     taskGates = resolveTaskGates(basePath);
+    const loaded = loadEffectiveGSDPreferences(basePath);
+    repositoryRegistry = createRepositoryRegistryFromPreferences(basePath, loaded?.preferences);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { error: `validation failed: ${message}` };
   }
 
+  const defaultTargets = defaultRepositoryTargets(repositoryRegistry);
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
   // change between the read and the write (#2723).
@@ -124,6 +183,44 @@ export async function handlePlanTask(
         return;
       }
 
+      let effectiveTargetRepositories = resolveEffectiveTargetRepositories(
+        params.targetRepositories,
+        parentSlice.target_repositories,
+        defaultTargets,
+      );
+      const repoValidationError = validateReferencedRepositories(effectiveTargetRepositories, repositoryRegistry);
+      if (repoValidationError) {
+        guardError = `validation failed: ${repoValidationError}`;
+        return;
+      }
+
+      let pathScopeError = validatePathScopeForTargetRepositories(
+        params,
+        basePath,
+        repositoryRegistry,
+        effectiveTargetRepositories,
+      );
+      const storedTaskTargets = existingTask?.target_repositories?.length
+        ? existingTask.target_repositories
+        : undefined;
+      // Omitted targetRepositories inherit the current slice default first.
+      // Fall back to the stored task target only when that inherited scope
+      // rejects the replan paths, preserving explicit per-task parent-root work.
+      if (pathScopeError && params.targetRepositories === undefined && storedTaskTargets) {
+        const storedRepoValidationError = validateReferencedRepositories(storedTaskTargets, repositoryRegistry);
+        const storedPathScopeError = storedRepoValidationError
+          ? storedRepoValidationError
+          : validatePathScopeForTargetRepositories(params, basePath, repositoryRegistry, storedTaskTargets);
+        if (!storedPathScopeError) {
+          effectiveTargetRepositories = storedTaskTargets;
+          pathScopeError = null;
+        }
+      }
+      if (pathScopeError) {
+        guardError = `validation failed: ${pathScopeError}`;
+        return;
+      }
+
       if (!existingTask) {
         insertTask({
           id: params.taskId,
@@ -143,6 +240,7 @@ export async function handlePlanTask(
         expectedOutput: params.expectedOutput,
         observabilityImpact: params.observabilityImpact ?? "",
         fullPlanMd: params.fullPlanMd,
+        targetRepositories: effectiveTargetRepositories,
       });
       for (const gid of taskGates) {
         insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: params.taskId });

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

@@ -5,6 +5,11 @@
  * tasks back to "pending". This is intentional — if you're reopening a
  * slice, you're re-doing the work. Partial resets create ambiguous state.
  *
+ * Also recovers a desynced slice (#1205): when a UAT→planning fallback leaves
+ * the slice open (e.g. "pending") but its tasks still "complete", this clears
+ * that state so the planner can re-plan without hitting "already complete"
+ * rejections.
+ *
  * The parent milestone must still be open (not complete).
  */
 

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

@@ -24,8 +24,8 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { resolveTasksDir, clearPathCache } from "../paths.js";
+import { join, basename, dirname } from "node:path";
+import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
 
 export interface ReopenTaskParams {
   milestoneId: string;
@@ -106,10 +106,18 @@ export async function handleReopenTask(
   // ── Clean up stale filesystem artifacts (M12 fix) ────────────────────────
   // Without this, the DB-filesystem reconciler sees the SUMMARY.md and
   // auto-corrects the task back to "complete", making reopen a no-op (#3161).
+  // Legacy layout keeps the summary under a tasks/ subdir; flat-phase writes
+  // TID-SUMMARY.md directly in the phase dir. A tasks/ subdir may still exist
+  // in flat-phase for auxiliary artifacts — its mere existence must NOT redirect
+  // summary cleanup into tasks/ (#1208).
   try {
-    const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-    if (tasksDir) {
-      const summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`);
+    const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    if (slicePath) {
+      const isLegacySlice = basename(dirname(slicePath)) === "slices";
+      const summaryDir = isLegacySlice
+        ? (resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath)
+        : slicePath;
+      const summaryPath = join(summaryDir, `${params.taskId}-SUMMARY.md`);
       if (existsSync(summaryPath)) unlinkSync(summaryPath);
     }
   } catch (cleanupErr) {

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

@@ -53,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,
@@ -116,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,
@@ -1135,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 {
@@ -1206,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");
 
@@ -1268,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/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

@@ -20,8 +20,9 @@
 //
 // Not yet declared here (remaining ADR-033 steps): the manifest data
 // (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
-// against the registry's `UnitType`) and prompt-template association (still
-// implicit in auto-prompts.ts builders).
+// against the registry's `UnitType`). Prompt-template association is declared
+// for direct one-template units and verified conditional template sets;
+// composition logic stays with prompt builders.
 
 import type { CanonicalWorkflowToolName } from "@opengsd/contracts";
 import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
@@ -61,6 +62,17 @@ export interface UnitDescriptor {
    * resolves against session defaults).
    */
   readonly phaseChain: readonly GSDModelPhaseKey[] | null;
+  /**
+   * Prompt template id passed to loadPrompt for units with a direct
+   * one-template builder. Omitted for conditional, composite, or not-yet
+   * verified prompt associations.
+   */
+  readonly promptTemplate?: string;
+  /**
+   * Prompt template ids a conditional or composite builder may choose from.
+   * Omitted unless every listed association is verified against the builder.
+   */
+  readonly promptTemplates?: readonly string[];
   /** `null` = the unit has no scoped gsd-tool contract. */
   readonly toolContract: UnitToolSurfaceContract | null;
 }
@@ -97,6 +109,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_summary_save",
@@ -112,6 +125,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -128,6 +142,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplates: ["discuss", "discuss-headless", "guided-discuss-milestone"],
     toolContract: {
       allowedGsdTools: [
         "gsd_summary_save",
@@ -160,6 +175,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "validate-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -177,6 +193,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["completion"],
+    promptTemplate: "complete-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -200,6 +217,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -216,6 +234,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -234,6 +253,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "refine-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -250,6 +270,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "replan-slice",
     toolContract: {
       allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
       requiredWorkflowTools: ["gsd_replan_slice"],
@@ -259,6 +280,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["completion"],
+    promptTemplate: "complete-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -293,6 +315,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "reassess-roadmap",
     toolContract: {
       allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
@@ -302,6 +325,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "execute-task",
     toolContract: {
       allowedGsdTools: [
         "gsd_task_complete",
@@ -346,6 +370,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "reactive-execute",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -361,6 +386,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["uat", "completion"],
+    promptTemplate: "run-uat",
     toolContract: {
       allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
       requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
@@ -375,6 +401,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "gate-evaluate",
     toolContract: {
       allowedGsdTools: ["gsd_save_gate_result"],
       requiredWorkflowTools: ["gsd_save_gate_result"],
@@ -384,6 +411,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "rewrite-docs",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
       requiredWorkflowTools: [],
@@ -408,6 +436,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-workflow-preferences",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: [],
@@ -417,6 +446,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-project",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
@@ -426,6 +456,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-requirements",
     toolContract: {
       allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
@@ -435,6 +466,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-research-decision",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions"],
@@ -447,6 +479,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "guided-research-project",
     toolContract: {
       allowedGsdTools: [],
       requiredWorkflowTools: [],
@@ -494,3 +527,16 @@ export function getUnitDescriptor(unitType: string): UnitDescriptor | undefined
 export function getUnitPhaseChain(unitType: string): readonly GSDModelPhaseKey[] | null {
   return getUnitDescriptor(unitType)?.phaseChain ?? null;
 }
+
+/** Prompt template id for units with a direct one-template builder. */
+export function getUnitPromptTemplate(unitType: string): string | undefined {
+  return getUnitDescriptor(unitType)?.promptTemplate;
+}
+
+/** Prompt template ids for any verified direct or conditional prompt builder. */
+export function getUnitPromptTemplates(unitType: string): readonly string[] {
+  const descriptor = getUnitDescriptor(unitType);
+  if (!descriptor) return [];
+  if (descriptor.promptTemplates) return descriptor.promptTemplates;
+  return descriptor.promptTemplate ? [descriptor.promptTemplate] : [];
+}

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

@@ -100,6 +100,14 @@ export interface ExecuteTaskRecoveryStatus {
   mustHavesMentionedInSummary: number;
 }
 
+export interface UnitHarnessAbortRecord {
+  kind: "tool-loop-guard" | "tool-error" | "turn-abort";
+  reason: string;
+  toolName?: string;
+  count?: number;
+  recordedAt: number;
+}
+
 export interface AutoUnitRuntimeRecord {
   version: 1;
   unitType: string;
@@ -116,6 +124,7 @@ export interface AutoUnitRuntimeRecord {
   recovery?: ExecuteTaskRecoveryStatus;
   recoveryAttempts?: number;
   lastRecoveryReason?: "idle" | "hard";
+  harnessAbort?: UnitHarnessAbortRecord;
 }
 
 function runtimeDir(basePath: string): string {
@@ -138,6 +147,8 @@ export function writeUnitRuntimeRecord(
   const path = runtimePath(basePath, unitType, unitId);
   return withRecordLock(path, () => {
     const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const sameRun = prev?.startedAt === startedAt;
+    const updatesHarnessAbort = Object.prototype.hasOwnProperty.call(updates, "harnessAbort");
     const next: AutoUnitRuntimeRecord = {
       version: 1,
       unitType,
@@ -154,12 +165,32 @@ export function writeUnitRuntimeRecord(
       recovery: updates.recovery ?? prev?.recovery,
       recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
       lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+      harnessAbort: updatesHarnessAbort
+        ? updates.harnessAbort
+        : (sameRun ? prev?.harnessAbort : undefined),
     };
     atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
     return next;
   });
 }
 
+export function recordUnitHarnessAbort(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  abort: Omit<UnitHarnessAbortRecord, "recordedAt"> & { recordedAt?: number },
+): AutoUnitRuntimeRecord {
+  return writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, {
+    harnessAbort: {
+      ...abort,
+      recordedAt: abort.recordedAt ?? Date.now(),
+    },
+    lastProgressAt: Date.now(),
+    lastProgressKind: `harness-abort:${abort.kind}`,
+  });
+}
+
 export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
   const path = runtimePath(basePath, unitType, unitId);
   if (!existsSync(path)) return null;
@@ -170,6 +201,17 @@ export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId
   }
 }
 
+export function readUnitHarnessAbort(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+): UnitHarnessAbortRecord | null {
+  const record = readUnitRuntimeRecord(basePath, unitType, unitId);
+  if (!record || record.startedAt !== startedAt) return null;
+  return record.harnessAbort ?? null;
+}
+
 export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
   const path = runtimePath(basePath, unitType, unitId);
   if (existsSync(path)) unlinkSync(path);

package/src/resources/extensions/gsd/unmerged-milestone-guard.ts

@@ -9,7 +9,7 @@ import {
   nativeDiffNumstat,
   nativeIsAncestor,
 } from "./native-git-bridge.js";
-import { autoWorktreeBranch } from "./auto-worktree.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";

package/src/resources/extensions/gsd/validation-block-guard.ts

@@ -3,7 +3,8 @@
 
 import { existsSync } from "node:fs";
 
-import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";

package/src/resources/extensions/gsd/workspace-git-preflight.ts

@@ -3,8 +3,8 @@
 
 import { existsSync, realpathSync } from "node:fs";
 
-import { getAutoWorktreePath } from "./auto-worktree.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
   listMergeStateBlockers,