@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.738160b9

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -76,6 +76,8 @@ import { join } from "node:path";
 import { evaluateAllCompleteSettlement } from "../milestone-settlement.js";
 import { hasHeldMilestoneLease, reclaimMissingMilestoneLease } from "./milestone-lease-reclaim.js";
 
+type UokFlags = ReturnType<typeof resolveUokFlags>;
+
 function now(): number {
   return Date.now();
 }
@@ -517,15 +519,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
   // ── UokGateAdapter (folded) ──────────────────────────────────────────────
 
-  private async emitUokGate(input: {
-    gateId: string;
-    gateType: "policy" | "execution";
-    outcome: "pass" | "fail" | "manual-attention";
-    failureClass: "none" | "policy" | "manual-attention";
-    rationale: string;
-    findings?: string;
-    milestoneId?: string;
-  }): Promise<void> {
+  private resolveUokGateContext(): { activeBasePath: string; uokFlags: UokFlags } {
     const activeBasePath = this.getLiveDispatchBasePath();
     const prefs = loadEffectiveGSDPreferencesWithRegistry(
       this.ctx.modelRegistry,
@@ -535,8 +529,22 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         ? `${this.s.autoModeStartModel.provider}/${this.s.autoModeStartModel.id}`
         : undefined,
     )?.preferences;
-    const uokFlags = resolveUokFlags(prefs);
-    if (!uokFlags.gates) return;
+    return { activeBasePath, uokFlags: resolveUokFlags(prefs) };
+  }
+
+  private async emitUokGate(input: {
+    gateId: string;
+    gateType: "policy" | "execution";
+    outcome: "pass" | "fail" | "manual-attention";
+    failureClass: "none" | "policy" | "manual-attention";
+    rationale: string;
+    findings?: string;
+    milestoneId?: string;
+    activeBasePath: string;
+    uokFlags: UokFlags;
+  }): Promise<void> {
+    if (!input.uokFlags.gates) return;
+    const activeBasePath = input.activeBasePath;
     const milestoneId = input.milestoneId ?? this.s.currentMilestoneId ?? undefined;
     try {
       const { UokGateRunner } = await import("../uok/gate-runner.js");
@@ -943,10 +951,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     const stopAdvanceTimer = debugTime("orchestrator-advance");
     try {
       this.ensureLockOwnership();
+      const uokGateContext = this.resolveUokGateContext();
 
       const staleMsg = this.checkResourcesStale();
       if (staleMsg) {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "resource-version-guard",
           gateType: "policy",
           outcome: "fail",
@@ -960,6 +970,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
       await this.emitUokGate({
+        ...uokGateContext,
         gateId: "resource-version-guard",
         gateType: "policy",
         outcome: "pass",
@@ -970,6 +981,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       const gate = await this.preAdvanceGate();
       if (gate.kind === "fail") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -988,6 +1000,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       }
       if (gate.kind === "threw") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -998,6 +1011,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         // intentional fall-through: matches runPreDispatch behaviour
       } else {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "pass",

package/src/resources/extensions/gsd/auto/session.ts

@@ -30,6 +30,7 @@ import { normalizeRealPath } from "../paths.js";
 import type { MilestoneScope } from "../workspace.js";
 import type { RootDirtySnapshot } from "../root-write-leak-guard.js";
 import type { MilestoneSettlementOutcome } from "../milestone-settlement.js";
+import type { ToolSurfaceSnapshot } from "../tool-surface-snapshot.js";
 
 // ─── Exported Types ──────────────────────────────────────────────────────────
 
@@ -55,6 +56,7 @@ export type ThinkingLevelSnapshot = ReturnType<ExtensionAPI["getThinkingLevel"]>
 export interface PendingVerificationRetry {
   unitId: string;
   failureContext: string;
+  signature?: string;
   attempt: number;
 }
 
@@ -160,6 +162,9 @@ export class AutoSession {
   currentMilestoneId: string | null = null;
   readonly sourceObservations = new SourceObservationStore();
 
+  /** Live tool-surface snapshot for dashboard / runtime telemetry while auto is active. */
+  toolSurfaceSnapshot: ToolSurfaceSnapshot | null = null;
+
   // ── Model state ──────────────────────────────────────────────────────────
   autoModeStartModel: StartModel | null = null;
   /** Explicit /gsd model pin captured at bootstrap (session-scoped policy override). */
@@ -207,6 +212,13 @@ export class AutoSession {
    * the issues after MAX_PRE_EXEC_RETRIES re-attempts.
    */
   readonly preExecRetryCount: Map<string, number> = new Map();
+  /**
+   * Tracks how many times each slice unit has been re-dispatched to plan-slice
+   * because task plan files were missing. Keyed by unitId (e.g. "M001/S01").
+   * Separate from preExecRetryCount so pre-exec gate failures do not block or
+   * conflate with missing-task-plan recovery.
+   */
+  readonly missingTaskPlanRetryCount: Map<string, number> = new Map();
 
   // ── Tool invocation errors (#2883) ──────────────────────────────────
   /** Set when a GSD tool execution ends with isError due to malformed/truncated
@@ -367,6 +379,7 @@ export class AutoSession {
 
     // Unit
     this.clearCurrentUnit();
+    this.toolSurfaceSnapshot = null;
     this.currentTraceId = null;
     this.currentTurnId = null;
     this.currentUnitRouting = null;
@@ -407,6 +420,7 @@ export class AutoSession {
     this.consecutiveCompleteBootstraps = 0;
     this.lastPreExecFailure = null;
     this.preExecRetryCount.clear();
+    this.missingTaskPlanRetryCount.clear();
     this.lastToolInvocationError = null;
     this.toolUnavailableRetries = 0;
     this.lastUnitAgentEndMessages = null;

package/src/resources/extensions/gsd/auto/verification-retry-policy.ts

@@ -63,7 +63,9 @@ export function decideVerificationRetry(input: {
   }
 
   const key = verificationRetryKey(unitType, retryInfo.unitId);
-  const failureHash = hashVerificationFailureContext(retryInfo.failureContext);
+  const failureHash = hashVerificationFailureContext(
+    retryInfo.signature ?? retryInfo.failureContext,
+  );
   if (input.previousFailureHash === failureHash) {
     return {
       action: "pause",

package/src/resources/extensions/gsd/auto-artifact-paths.ts

@@ -22,7 +22,8 @@ import {
 } from "./paths.js";
 import { milestoneIdToPhaseNum } from "./layout-policy.js";
 import { parseUnitId } from "./unit-id.js";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
+import { existsSync } from "node:fs";
 
 function resolveMilestoneArtifactPath(
   base: string,
@@ -314,3 +315,48 @@ export function diagnoseExpectedArtifact(
       return null;
   }
 }
+
+export interface SliceResearchLocation {
+  /** Absolute path when research exists; null when missing. */
+  absolutePath: string | null;
+  /** Prompt-friendly relative path when research exists. */
+  relativePath: string | null;
+}
+
+/**
+ * Resolve slice RESEARCH with worktree projection first, then canonical
+ * project-root path. Shared by dispatch rules, execute-task prompts, and
+ * artifact verification.
+ */
+export function resolveSliceResearchLocation(
+  basePath: string,
+  mid: string,
+  sid: string,
+): SliceResearchLocation {
+  const projectedFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
+  if (projectedFile) {
+    return {
+      absolutePath: projectedFile,
+      relativePath: relSliceFile(basePath, mid, sid, "RESEARCH"),
+    };
+  }
+
+  const canonicalPath = resolveExpectedArtifactPath("research-slice", `${mid}/${sid}`, basePath);
+  if (canonicalPath && existsSync(canonicalPath)) {
+    return {
+      absolutePath: canonicalPath,
+      relativePath: relative(basePath, canonicalPath),
+    };
+  }
+
+  return { absolutePath: null, relativePath: null };
+}
+
+/** Returns the absolute RESEARCH path when it exists, otherwise null. */
+export function resolveExistingSliceResearchPath(
+  basePath: string,
+  mid: string,
+  sid: string,
+): string | null {
+  return resolveSliceResearchLocation(basePath, mid, sid).absolutePath;
+}

package/src/resources/extensions/gsd/auto-budget.ts

@@ -79,7 +79,9 @@ export function resolveCompactionThresholdPercent(raw: number | undefined): numb
   return value <= 1 ? value * 100 : value;
 }
 
-export function shouldRerootStepSessionForContext(
+export const HARD_CONTEXT_REROOT_THRESHOLD_PERCENT = 90;
+
+export function shouldWarnStepSessionForContext(
   contextPercent: number | null | undefined,
   compactionThresholdPercent?: number,
 ): boolean {
@@ -88,3 +90,12 @@ export function shouldRerootStepSessionForContext(
     resolveCompactionThresholdPercent(compactionThresholdPercent),
   ) === "pause";
 }
+
+export function shouldRerootStepSessionForContext(
+  contextPercent: number | null | undefined,
+): boolean {
+  return getContextPauseAction(
+    contextPercent,
+    HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
+  ) === "pause";
+}

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -30,6 +30,7 @@ import {
   setSliceSketchFlag,
   transaction,
   getAssessment,
+  getSliceRunUatAssessment,
 } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
@@ -113,7 +114,7 @@ import { detectWorktreeName } from "./worktree.js";
 import { probeGitConflictState } from "./git-conflict-state.js";
 import { runTurnGitAction } from "./git-service.js";
 import { parseUnitId } from "./unit-id.js";
-import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { resolveExpectedArtifactPath, resolveExistingSliceResearchPath } from "./auto-artifact-paths.js";
 import {
   formatCloseoutProofBlock,
   proveMilestoneCloseout,
@@ -322,6 +323,19 @@ export async function readUatGateVerdict(
     }
   }
 
+  // ADR-017 DB fallback: when the ASSESSMENT markdown is missing or orphaned
+  // from its canonical path (e.g. after a milestone artifact-layout migration
+  // moves slice artifacts from `phases/…` to `milestones/…`), consult the
+  // authoritative assessments table by (mid, slice) identity instead of path.
+  // `gsd_uat_result_save` always writes this row, so it is the source of truth.
+  const runUatAssessment = getSliceRunUatAssessment(mid, sliceId);
+  if (runUatAssessment?.status) {
+    return {
+      verdict: runUatAssessment.status,
+      uatType: uatType ?? extractUatType(runUatAssessment.fullContent),
+    };
+  }
+
   return null;
 }
 
@@ -1142,18 +1156,15 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const dbSlices = getMilestoneSliceSummaries(mid);
       if (dbSlices.length === 0) return null;
 
-      // Find slices that need research (no RESEARCH file, dependencies done)
-      const milestoneResearchFile =
-        resolveExistingExpectedArtifact("research-milestone", mid, basePath) ??
-        resolveMilestoneFile(basePath, mid, "RESEARCH");
+      // Find slices that need research (no RESEARCH file, dependencies done).
+      // Milestone research informs slice research; it does not satisfy the
+      // per-slice RESEARCH artifact contract.
       const researchReadySlices: Array<{ id: string; title: string }> = [];
 
       for (const slice of dbSlices) {
         if (slice.done) continue;
-        // Skip S01 when milestone research exists
-        if (milestoneResearchFile && slice.id === "S01") continue;
         // Skip if already has research
-        if (resolveExistingExpectedArtifact("research-slice", `${mid}/${slice.id}`, basePath)) continue;
+        if (resolveExistingSliceResearchPath(basePath, mid, slice.id)) continue;
         // Skip if dependencies aren't done (check for SUMMARY files)
         const depsComplete = slice.depends.every((depId) =>
           !!resolveExistingExpectedArtifact("complete-slice", `${mid}/${depId}`, basePath),
@@ -1190,7 +1201,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     },
   },
   {
-    name: "planning (no research, not S01) → research-slice",
+    name: "planning (no research) → research-slice",
     match: async ({ state, mid, midTitle, basePath, prefs }) => {
       if (state.phase !== "planning") return null;
       // Phase skip: skip research when preference or profile says so
@@ -1201,20 +1212,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
-      const researchFile =
-        resolveExistingExpectedArtifact("research-slice", `${mid}/${sid}`, basePath) ??
-        resolveSliceFile(basePath, mid, sid, "RESEARCH");
-      if (researchFile) return null; // has research, fall through
-      // Skip slice research for S01 when milestone research already exists —
-      // the milestone research already covers the same ground for the first slice.
-      const milestoneResearchFile =
-        resolveExistingExpectedArtifact("research-milestone", mid, basePath) ??
-        resolveMilestoneFile(
-          basePath,
-          mid,
-          "RESEARCH",
-        );
-      if (milestoneResearchFile && sid === "S01") return null; // fall through to plan-slice
+      if (resolveExistingSliceResearchPath(basePath, mid, sid)) return null; // has research, fall through
       return {
         action: "dispatch",
         unitType: "research-slice",
@@ -1525,6 +1523,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
       const tid = state.activeTask.id;
+      const unitId = `${mid}/${sid}`;
       const artifactBasePath = resolveArtifactBasePath(basePath, mid, session);
 
       // Guard: if the slice plan exists but the individual task plan files are
@@ -1564,6 +1563,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
         !existsSync(projectionTaskPlanPath) &&
         !tasksEmbeddedInSlicePlan
       ) {
+        const MAX_MISSING_TASK_PLAN_RETRIES = 2;
+        const retryCount = session?.missingTaskPlanRetryCount?.get(unitId) ?? 0;
+        if (retryCount >= MAX_MISSING_TASK_PLAN_RETRIES) {
+          session?.missingTaskPlanRetryCount?.delete(unitId);
+          return {
+            action: "stop",
+            reason: `Missing task-plan recovery failed ${retryCount} times for ${unitId} - manual intervention required. Task plan ${tid} is still missing after regenerating the slice plan. Fix the task-plan files manually, then run /gsd auto to resume.`,
+            level: "error",
+          };
+        }
+        session?.missingTaskPlanRetryCount?.set(unitId, retryCount + 1);
         if (isDebugEnabled()) {
           const expectedTaskPlanPath = join(artifactBasePath, relTaskFile(artifactBasePath, mid, sid, tid, "PLAN"));
           const originalProjectRoot = session?.originalBasePath || basePath;
@@ -1587,7 +1597,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
         return {
           action: "dispatch",
           unitType: "plan-slice",
-          unitId: `${mid}/${sid}`,
+          unitId,
           prompt: await buildPlanSlicePrompt(
             mid,
             midTitle,
@@ -1600,6 +1610,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
         };
       }
 
+      session?.missingTaskPlanRetryCount?.delete(unitId);
       return null;
     },
   },

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -2212,7 +2212,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
           s.pendingVerificationRetry = {
             unitId: s.currentUnit.id,
-            failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
+            failureContext: failureDetails,
             attempt,
           };
           debugLog("postUnit", { phase: "artifact-verify-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -17,14 +17,14 @@ import {
   resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
   resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relSlicePath, relMilestonePath,
-  resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
+  relTaskFile, resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
 } from "./paths.js";
 import { resolveInlineLevel, loadEffectiveGSDPreferences } from "./preferences.js";
 import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
-import { join, basename } from "node:path";
+import { join, basename, relative } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
 import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
@@ -48,6 +48,7 @@ import {
   type ExcerptResolver,
 } from "./unit-context-composer.js";
 import { resolveManifest, type ArtifactKey } from "./unit-context-manifest.js";
+import { resolveSliceResearchLocation } from "./auto-artifact-paths.js";
 import { compileUnitContextContract, type UnitPromptContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
@@ -323,19 +324,37 @@ function requireComposedArtifactBlock(
   return block.body;
 }
 
+interface ExecuteTaskOnDemandResult {
+  /** Rendered block for the prompt; empty string when not shown. */
+  text: string;
+  /**
+   * Telemetry skip reason when the block was suppressed; null when the block
+   * is included. Callers pass this directly to `trackPromptContext`.
+   */
+  skipReason: string | null;
+}
+
 function renderExecuteTaskOnDemandContext(
   base: string,
   mid: string,
   sid: string,
   artifacts: readonly ArtifactKey[],
-): string {
-  if (!artifacts.includes("slice-research")) return "";
-  const researchPath = relSliceFile(base, mid, sid, "RESEARCH");
-  return [
-    "## On-demand Context",
-    "",
-    `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
-  ].join("\n");
+): ExecuteTaskOnDemandResult {
+  if (!artifacts.includes("slice-research")) {
+    return { text: "", skipReason: "not declared by contract" };
+  }
+  const research = resolveSliceResearchLocation(base, mid, sid);
+  if (!research.absolutePath || !research.relativePath) {
+    return { text: "", skipReason: "missing" };
+  }
+  return {
+    text: [
+      "## On-demand Context",
+      "",
+      `Slice research is available at \`${research.relativePath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
+    ].join("\n"),
+    skipReason: null,
+  };
 }
 
 // ─── Executor Constraints ─────────────────────────────────────────────────────
@@ -1691,7 +1710,13 @@ export async function buildDiscussMilestonePrompt(
   const draftContent = draftPath ? await loadFile(draftPath) : null;
 
   if (includeDraftSeed && draftContent) {
-    return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${draftContent}`;
+    const draftRelPath = relMilestoneFile(base, mid, "CONTEXT-DRAFT");
+    const draftSeed = `### Prior Discussion Draft\nSource: \`${draftRelPath}\`\n\n${draftContent.trim()}`;
+    const cappedDraftSeed = capPreamble(draftSeed);
+    const truncationNote = cappedDraftSeed !== draftSeed
+      ? `\n\n_(Draft seed truncated; read the full draft at \`${draftRelPath}\` if needed.)_`
+      : "";
+    return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${cappedDraftSeed}${truncationNote}`;
   }
 
   return promptWithContextMode;
@@ -2637,7 +2662,7 @@ export async function buildExecuteTaskPrompt(
 
   const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
   const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
-  const taskPlanRelPath = relSlicePath(base, mid, sid) + `/tasks/${tid}-PLAN.md`;
+  const taskPlanRelPath = relTaskFile(base, mid, sid, tid, "PLAN");
   const taskPlanContext = taskPlanContent
     ? [
       "## Inlined Task Plan (authoritative local execution contract)",
@@ -2807,13 +2832,14 @@ export async function buildExecuteTaskPrompt(
   const slicePlanExcerpt = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "slice-plan");
   const contractedCarryForward = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "prior-task-summaries");
   const contractedTemplates = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "templates");
-  const onDemandContext = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  const onDemandResult = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  const onDemandContext = onDemandResult.text;
   trackPromptContext(
     contextTelemetry,
     "slice-research",
     onDemandContext ? "on-demand" : "skipped",
     onDemandContext,
-    onDemandContext ? undefined : "not declared by contract",
+    onDemandContext ? undefined : onDemandResult.skipReason ?? undefined,
   );
 
   const prompt = loadPrompt("execute-task", {
@@ -3875,7 +3901,7 @@ export async function buildReactiveExecutePrompt(
 
     const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
-    const taskPlanRelPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-PLAN.md`;
+    const taskPlanRelPath = relTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanInline = taskPlanContent
       ? [
           "## Inlined Task Plan (authoritative local execution contract)",