gsd-pi 2.82.0-dev.3a3c6509d → 2.82.0-dev.4285182e8

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Main auto-mode execution loop.
 /**
  * auto/loop.ts — Main auto-mode execution loop.
  *
@@ -945,11 +947,18 @@ export async function autoLoop(
         unitId: iterData.unitId,
       });
       const finalizeReason = finalizeResult.action === "break" ? finalizeResult.reason : undefined;
+      const finalizeStatus = finalizeReason === "step-wizard"
+        ? "completed"
+        : finalizeResult.action === "next"
+          ? "completed"
+          : finalizeResult.action === "continue"
+            ? "retry"
+            : "stopped";
       journalReporter.emit("post-unit-finalize-end", {
         iteration,
         unitType: iterData.unitType,
         unitId: iterData.unitId,
-        status: finalizeResult.action === "next" ? "completed" : finalizeResult.action === "continue" ? "retry" : "stopped",
+        status: finalizeStatus,
         action: finalizeResult.action,
         ...(finalizeReason ? { reason: finalizeReason } : {}),
       });
@@ -996,6 +1005,10 @@ export async function autoLoop(
       }) || dispatchSettled;
       completeIteration();
       finishTurn("completed");
+      if (finalizeDecision.action === "complete-and-break") {
+        s.preserveStepSurfaceAfterLoopExit = true;
+        break;
+      }
     } catch (loopErr) {
       // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ──
       const msg = loopErr instanceof Error ? loopErr.message : String(loopErr);

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Mutable auto-mode session state container.
 /**
  * AutoSession — encapsulates all mutable auto-mode state into a single instance.
  *
@@ -89,6 +91,7 @@ export class AutoSession {
   active = false;
   paused = false;
   completionStopInProgress = false;
+  preserveStepSurfaceAfterLoopExit = false;
   stepMode = false;
   verbose = false;
   activeEngineId: string | null = null;
@@ -289,6 +292,7 @@ export class AutoSession {
     this.active = false;
     this.paused = false;
     this.completionStopInProgress = false;
+    this.preserveStepSurfaceAfterLoopExit = false;
     this.stepMode = false;
     this.verbose = false;
     this.activeEngineId = null;

package/src/resources/extensions/gsd/auto/workflow-kernel.ts

@@ -48,7 +48,8 @@ export type FinalizeDecision =
       action: "retry";
       ledgerErrorSummary: "finalize-retry";
     }
-  | { action: "complete" };
+  | { action: "complete" }
+  | { action: "complete-and-break" };
 
 export type EngineReconcileInput =
   | { outcome: "milestone-complete" }
@@ -278,6 +279,9 @@ export function decideEngineDispatch(input: EngineDispatchInput): EngineDispatch
 export function decideFinalizeResult(input: FinalizeInput): FinalizeDecision {
   if (input.action === "break") {
     const reason = input.reason ?? "unknown";
+    if (reason === "step-wizard") {
+      return { action: "complete-and-break" };
+    }
     return {
       action: "stop",
       failureClass: reason === "git-closeout-failure" ? "git" : "closeout",

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

@@ -1340,7 +1340,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           if (verdict !== "pass") {
             return {
               action: "stop",
-              reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or update the verdict manually.`,
+              reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or run \`/gsd verdict pass --rationale "..."\` to override.`,
               level: "warning",
             };
           }

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

@@ -47,7 +47,7 @@ import { regenerateIfMissing } from "./workflow-projections.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { isDbAvailable, getDbPath, refreshOpenDatabaseFromDisk, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { renderPlanCheckboxes } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
@@ -371,7 +371,7 @@ export function detectRogueFileWrites(
 export const MAX_ARTIFACT_VERIFICATION_RETRIES = 3;
 
 export const STEP_COMPLETE_FALLBACK_MESSAGE =
-  "Step complete. Run /clear, then /gsd to continue (or /gsd auto to run continuously).";
+  "Step complete. Run /clear if you want a clean view, then /gsd next to continue one step (or /gsd auto to run continuously).";
 
 export function buildStepCompleteMessage(nextState: import("./types.js").GSDState): string {
   if (nextState.phase === "complete") {
@@ -379,7 +379,7 @@ export function buildStepCompleteMessage(nextState: import("./types.js").GSDStat
   }
   const next = describeNextUnit(nextState);
   return `Step complete. Next: ${next.label}\n`
-    + `Run /clear, then /gsd to continue (or /gsd auto to run continuously).`;
+    + `Run /clear if you want a clean view, then /gsd next to continue one step (or /gsd auto to run continuously).`;
 }
 
 /**
@@ -686,6 +686,14 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
     await new Promise(r => setTimeout(r, 100));
   }
 
+  const dbPath = getDbPath();
+  if (isDbAvailable() && dbPath && dbPath !== ":memory:") {
+    const refreshed = refreshOpenDatabaseFromDisk();
+    if (!refreshed) {
+      logWarning("db", "post-unit database refresh failed; derived state may be stale");
+    }
+  }
+
   // Turn-level git action (commit | snapshot | status-only)
   if (s.currentUnit) {
     const unit = s.currentUnit;
@@ -1731,8 +1739,8 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   }
 
   // Step mode → show wizard instead of dispatch.
-  // Without this notify(), /gsd in step mode finishes a unit and silently
-  // exits the loop, leaving the user with no hint to /clear and /gsd again.
+  // Without this notify(), /gsd next finishes a unit and silently exits the
+  // loop, leaving the user with no next-step command.
   if (s.stepMode) {
     let phaseAfterUnit: string | null = null;
     try {

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

@@ -1029,6 +1029,8 @@ export async function rerootCommandSession(
 }
 
 export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void> {
+  const preserveStepSurface = s.preserveStepSurfaceAfterLoopExit;
+  const preservePausedSurface = s.paused;
   s.currentUnit = null;
   s.active = false;
   deactivateGSD();
@@ -1051,12 +1053,16 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
   // A transient provider-error pause intentionally leaves the paused badge
   // visible so the user still has a resumable auto-mode signal on screen.
   if (!s.paused) {
-    ctx.ui.setStatus("gsd-auto", undefined);
-    ctx.ui.setWidget("gsd-progress", undefined);
-    if (s.completionStopInProgress) {
-      s.completionStopInProgress = false;
+    if (preserveStepSurface) {
+      s.preserveStepSurfaceAfterLoopExit = false;
+    } else {
+      ctx.ui.setStatus("gsd-auto", undefined);
+      ctx.ui.setWidget("gsd-progress", undefined);
+      if (s.completionStopInProgress) {
+        s.completionStopInProgress = false;
+      }
+      initHealthWidget(ctx);
     }
-    initHealthWidget(ctx);
   }
 
   // ADR-016 phase 3 (#5693): the stop-path basePath restore + chdir routes
@@ -1064,7 +1070,7 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
   // `s.basePath` mutation and the paired `process.chdir` for auto-loop
   // transitions. The verb assigns `s.basePath` before any throwable work, so
   // a thrown error still leaves basePath restored.
-  if (s.originalBasePath) {
+  if (s.originalBasePath && !preserveStepSurface && !preservePausedSurface) {
     try {
       buildLifecycle().restoreToProjectRoot();
     } catch (err) {
@@ -1076,7 +1082,7 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
     }
   }
 
-  if (s.originalBasePath && s.cmdCtx) {
+  if (s.originalBasePath && s.cmdCtx && !preserveStepSurface && !preservePausedSurface) {
     const result = await rerootCommandSession(s.cmdCtx, s.originalBasePath);
     if (result.status === "cancelled") {
       logWarning("engine", "post-loop session re-root was cancelled", { file: "auto.ts", basePath: s.originalBasePath });

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -14,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -33,6 +33,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "changelog", desc: "Show categorized release notes" },
   { cmd: "triage", desc: "Manually trigger triage of pending captures" },
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+  { cmd: "verdict", desc: "Override the recorded milestone validation verdict (pass|needs-attention|needs-remediation)" },
   { cmd: "history", desc: "View execution history" },
   { cmd: "undo", desc: "Revert last completed unit" },
   { cmd: "undo-task", desc: "Reset a specific task's completion state (DB + markdown)" },
@@ -248,6 +249,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "uat", desc: "Run user acceptance testing" },
     { cmd: "replan", desc: "Replan the current slice" },
   ],
+  verdict: [
+    { cmd: "pass", desc: "Override the milestone validation verdict to pass" },
+    { cmd: "needs-attention", desc: "Override the verdict to needs-attention (requires --rationale)" },
+    { cmd: "needs-remediation", desc: "Override the verdict to needs-remediation (requires --rationale)" },
+  ],
   rate: [
     { cmd: "over", desc: "Model was overqualified for this task" },
     { cmd: "ok", desc: "Model was appropriate for this task" },

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -71,6 +71,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd new-project    Bootstrap a new project (use --deep for staged project-level discovery)",
     "  /gsd quick          Execute a quick task without full planning overhead",
     "  /gsd dispatch       Dispatch a specific phase directly  [research|plan|execute|complete|uat|replan]",
+    "  /gsd verdict <v>    Override milestone validation verdict  [pass|needs-attention|needs-remediation] [--milestone Mxxx] [--rationale \"...\"]",
     "  /gsd parallel       Parallel milestone orchestration  [start|status|stop|pause|resume|merge|watch]",
     "  /gsd workflow       Custom workflow lifecycle  [new|run|list|validate|pause|resume]",
     "",

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -188,6 +188,11 @@ Examples:
     await dispatchDirectPhase(ctx, pi, phase, projectRoot());
     return true;
   }
+  if (trimmed === "verdict" || trimmed.startsWith("verdict ")) {
+    const { handleVerdict } = await import("../../commands-verdict.js");
+    await handleVerdict(trimmed.replace(/^verdict\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
   if (trimmed === "notifications" || trimmed.startsWith("notifications ")) {
     const { handleNotificationsCommand } = await import("./notifications-handler.js");
     await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi);

package/src/resources/extensions/gsd/commands-verdict.ts

@@ -0,0 +1,202 @@
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { loadFile } from "./files.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { deriveState } from "./state.js";
+import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
+import {
+  VALIDATION_VERDICTS,
+  extractVerdict,
+  isValidMilestoneVerdict,
+  type ValidationVerdict,
+} from "./verdict-parser.js";
+
+const USAGE =
+  'Usage: /gsd verdict <pass|needs-attention|needs-remediation> [--milestone Mxxx] [--rationale "..."]';
+
+interface ParsedArgs {
+  verdict?: ValidationVerdict;
+  milestoneId?: string;
+  rationale?: string;
+}
+
+interface ParsedValidation {
+  verdict: string | undefined;
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verificationClasses?: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+function tokenize(raw: string): string[] {
+  const tokens: string[] = [];
+  const re = /"([^"]*)"|(\S+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(raw)) !== null) {
+    tokens.push(match[1] ?? match[2]);
+  }
+  return tokens;
+}
+
+function parseArgs(raw: string): ParsedArgs | { error: string } {
+  const tokens = tokenize(raw);
+  const out: ParsedArgs = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--milestone") {
+      const next = tokens[++i];
+      if (!next) return { error: "--milestone requires a milestone ID" };
+      out.milestoneId = next;
+    } else if (t === "--rationale") {
+      const next = tokens[++i];
+      if (next == null) return { error: "--rationale requires a value" };
+      out.rationale = next;
+    } else if (!out.verdict) {
+      if (!isValidMilestoneVerdict(t)) {
+        return {
+          error: `Invalid verdict "${t}". Must be one of: ${VALIDATION_VERDICTS.join(", ")}`,
+        };
+      }
+      out.verdict = t;
+    } else {
+      return { error: `Unexpected argument: ${t}` };
+    }
+  }
+  return out;
+}
+
+function extractRemediationRound(content: string): number {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return 0;
+  const m = fm[1].match(/^remediation_round:\s*(\d+)/im);
+  return m ? Number.parseInt(m[1], 10) : 0;
+}
+
+function extractSection(content: string, heading: string): string | undefined {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Match section bodies bounded by the next "## " heading or end-of-string.
+  // Leading "\n" prefix lets a single pattern handle first-line headings too.
+  // No /m flag — we want `$` to mean end-of-string, not end-of-line.
+  const re = new RegExp(`\\n## ${escaped}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = ("\n" + content).match(re);
+  if (!m) return undefined;
+  return m[1].replace(/\s+$/, "");
+}
+
+export function parseValidationFile(content: string): ParsedValidation {
+  return {
+    verdict: extractVerdict(content),
+    remediationRound: extractRemediationRound(content),
+    successCriteriaChecklist: extractSection(content, "Success Criteria Checklist") ?? "",
+    sliceDeliveryAudit: extractSection(content, "Slice Delivery Audit") ?? "",
+    crossSliceIntegration: extractSection(content, "Cross-Slice Integration") ?? "",
+    requirementCoverage: extractSection(content, "Requirement Coverage") ?? "",
+    verificationClasses: extractSection(content, "Verification Class Compliance"),
+    verdictRationale: extractSection(content, "Verdict Rationale") ?? "",
+    remediationPlan: extractSection(content, "Remediation Plan"),
+  };
+}
+
+export async function handleVerdict(
+  rawArgs: string,
+  ctx: ExtensionCommandContext,
+  basePath: string,
+): Promise<void> {
+  if (!rawArgs.trim()) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  const parsed = parseArgs(rawArgs);
+  if ("error" in parsed) {
+    ctx.ui.notify(`${parsed.error}\n${USAGE}`, "warning");
+    return;
+  }
+  if (!parsed.verdict) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  let milestoneId = parsed.milestoneId;
+  if (!milestoneId) {
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone) {
+      ctx.ui.notify(
+        "No active milestone — pass --milestone Mxxx to target a specific milestone.",
+        "warning",
+      );
+      return;
+    }
+    milestoneId = state.activeMilestone.id;
+  }
+
+  const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
+  if (!validationPath) {
+    ctx.ui.notify(
+      `No VALIDATION file found for ${milestoneId}. Run gsd_validate_milestone first to produce one.`,
+      "warning",
+    );
+    return;
+  }
+  const existing = await loadFile(validationPath);
+  if (!existing) {
+    ctx.ui.notify(
+      `Could not read VALIDATION file for ${milestoneId} (${validationPath}).`,
+      "warning",
+    );
+    return;
+  }
+
+  const current = parseValidationFile(existing);
+
+  if (parsed.verdict !== "pass" && !parsed.rationale) {
+    ctx.ui.notify(
+      `--rationale is required when overriding to ${parsed.verdict}.`,
+      "warning",
+    );
+    return;
+  }
+
+  const verdictRationale =
+    parsed.rationale ?? "Manually overridden via /gsd verdict";
+
+  const result = await executeValidateMilestone(
+    {
+      milestoneId,
+      verdict: parsed.verdict,
+      remediationRound: current.remediationRound,
+      successCriteriaChecklist: current.successCriteriaChecklist,
+      sliceDeliveryAudit: current.sliceDeliveryAudit,
+      crossSliceIntegration: current.crossSliceIntegration,
+      requirementCoverage: current.requirementCoverage,
+      verificationClasses: current.verificationClasses,
+      verdictRationale,
+      remediationPlan: current.remediationPlan,
+    },
+    basePath,
+  );
+
+  if (result.isError) {
+    const msg =
+      result.content[0]?.type === "text" ? result.content[0].text : "Unknown error";
+    ctx.ui.notify(msg, "error");
+    return;
+  }
+
+  const prevVerdict = current.verdict ?? "unknown";
+  ctx.ui.notify(
+    `Milestone ${milestoneId} verdict: ${prevVerdict} -> ${parsed.verdict}`,
+    "success",
+  );
+
+  if (parsed.verdict === "needs-remediation") {
+    ctx.ui.notify(
+      "Follow up with gsd_reassess_roadmap to add remediation slices, then re-run /gsd auto.",
+      "info",
+    );
+  }
+}

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -32,7 +32,7 @@ import {
   resolveMilestoneFile,
   resolveSliceFile,
   resolveSlicePath,
-  resolveTasksDir,
+  gsdProjectionRoot,
   gsdRoot,
   buildTaskFileName,
   buildSliceFileName,
@@ -48,7 +48,11 @@ import { clearPathCache } from "./paths.js";
  * E.g. "/project/.gsd/milestones/M001/M001-ROADMAP.md" → "milestones/M001/M001-ROADMAP.md"
  */
 function toArtifactPath(absPath: string, basePath: string): string {
-  const root = gsdRoot(basePath);
+  const projectionRoot = gsdProjectionRoot(basePath);
+  const projectionRel = relative(projectionRoot, absPath);
+  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+    ? projectionRoot
+    : gsdRoot(basePath);
   const rel = relative(root, absPath);
   // Normalize to forward slashes for consistent DB keys
   return rel.replace(/\\/g, "/");
@@ -374,10 +378,9 @@ export async function renderPlanFromDb(
     throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
   }
 
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN")
-    ?? join(slicePath, `${sliceId}-PLAN.md`);
+  const slicePath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId);
+  mkdirSync(slicePath, { recursive: true });
+  const absPath = join(slicePath, `${sliceId}-PLAN.md`);
   const artifactPath = toArtifactPath(absPath, basePath);
   const sliceGates = getGateResults(milestoneId, sliceId, "slice");
   const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
@@ -408,8 +411,7 @@ export async function renderTaskPlanFromDb(
     throw new Error(`task ${milestoneId}/${sliceId}/${taskId} not found`);
   }
 
-  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+  const tasksDir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
   mkdirSync(tasksDir, { recursive: true });
   const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
   const artifactPath = toArtifactPath(absPath, basePath);

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

@@ -357,6 +357,11 @@ export function resolveGsdPathContract(
   };
 }
 
+export function gsdProjectionRoot(basePath: string): string {
+  const contract = resolveGsdPathContract(basePath);
+  return normalizeRealPath(contract.worktreeGsd ?? contract.projectGsd);
+}
+
 /**
  * Invalidate the gsdRoot cache.
  * Use ONLY at session-reset boundaries: workspace switch, process exit, or

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

@@ -591,7 +591,7 @@ async function handleAllSlicesDone(
       recentDecisions: [],
       blockers: [
         `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
-          `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+          `Add remediation slices via gsd_reassess_roadmap, or run \`/gsd verdict pass --rationale "..."\` to override.`,
       ],
       nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
       registry, requirements,
@@ -1314,7 +1314,7 @@ export async function _deriveStateImpl(
         recentDecisions: [],
         blockers: [
           `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
-            `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+            `Add remediation slices via gsd_reassess_roadmap, or run \`/gsd verdict pass --rationale "..."\` to override.`,
         ],
         nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
         registry,

package/src/resources/extensions/gsd/templates/plan.md

@@ -132,6 +132,7 @@
   Verify field rules:
   - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
   - MUST NOT use shell pipes, redirects, semicolons, backticks, command substitution, or output trimming
+  - MUST NOT use inline `node -e` assertions for verification; put assertions in a real test file and run it with `node --test` or a package test script
   - For content/document tasks: verify file existence, section count, YAML validity, or word count
     NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
   - If no command can verify the output, write: "Manual review — file exists and is non-empty"

package/src/resources/extensions/gsd/templates/task-plan.md

@@ -57,6 +57,12 @@ skills_used:
 - {{howToVerifyThisTaskIsActuallyDone}}
 - {{commandToRun_OR_behaviorToCheck}}
 
+## Verify Rules
+
+- Use a real executable check, not prose.
+- If the check needs file-content assertions, write a `node:test` file and run it with `node --test` or a package test script.
+- Do not use inline `node -e` assertions for verification.
+
 ## Observability Impact
 
 <!-- OMIT THIS SECTION ENTIRELY for simple tasks that don't touch runtime boundaries,

package/src/resources/extensions/gsd/tests/auto-paused-ui-cleanup.test.ts

@@ -43,6 +43,52 @@ test("cleanupAfterLoopExit preserves paused auto badge after provider pause", as
   }
 });
 
+test("cleanupAfterLoopExit preserves paused worktree session and visible failure output", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-paused-session-preserve-"));
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const previousCwd = process.cwd();
+  const newSessionWorkspaces: string[] = [];
+  let restoreCalls = 0;
+
+  t.mock.method(WorktreeLifecycle.prototype, "restoreToProjectRoot", function () {
+    restoreCalls += 1;
+  });
+
+  mkdirSync(worktree, { recursive: true });
+  process.chdir(worktree);
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.paused = true;
+  autoSession.basePath = worktree;
+  autoSession.originalBasePath = base;
+  autoSession.cmdCtx = {
+    newSession: async ({ workspaceRoot }: { workspaceRoot: string }) => {
+      newSessionWorkspaces.push(workspaceRoot);
+      return { cancelled: false };
+    },
+  } as any;
+
+  try {
+    await cleanupAfterLoopExit({
+      ui: {
+        setStatus: () => {},
+        setWidget: () => {},
+        notify: () => {},
+      },
+    } as any);
+
+    assert.equal(restoreCalls, 0, "paused cleanup must not restore out of the active worktree");
+    assert.deepEqual(newSessionWorkspaces, [], "paused cleanup must not start a blank rerooted session");
+    assert.equal(autoSession.basePath, worktree);
+    assert.equal(realpathSync(process.cwd()), realpathSync(worktree));
+    assert.equal(autoSession.paused, true);
+  } finally {
+    autoSession.reset();
+    process.chdir(previousCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("cleanupAfterLoopExit clears status and progress widget without replacing outcome surface", async () => {
   const statusCalls: unknown[] = [];
   const widgetCalls: unknown[] = [];
@@ -145,6 +191,70 @@ test("pauseAuto preserves artifact retry counts across pause/resume", async () =
   }
 });
 
+test("cleanupAfterLoopExit preserves step-mode surface and worktree session after completed step", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-step-surface-"));
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const previousCwd = process.cwd();
+  const statusCalls: unknown[] = [];
+  const widgetCalls: unknown[] = [];
+  const newSessionWorkspaces: string[] = [];
+  let restoreCalls = 0;
+
+  t.mock.method(WorktreeLifecycle.prototype, "restoreToProjectRoot", function () {
+    restoreCalls += 1;
+  });
+
+  mkdirSync(worktree, { recursive: true });
+  process.chdir(worktree);
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.paused = false;
+  autoSession.stepMode = true;
+  autoSession.preserveStepSurfaceAfterLoopExit = true;
+  autoSession.basePath = worktree;
+  autoSession.originalBasePath = base;
+  autoSession.cmdCtx = {
+    newSession: async ({ workspaceRoot }: { workspaceRoot: string }) => {
+      newSessionWorkspaces.push(workspaceRoot);
+      return { cancelled: false };
+    },
+  } as any;
+
+  try {
+    await cleanupAfterLoopExit({
+      hasUI: true,
+      ui: {
+        setStatus: (...args: unknown[]) => statusCalls.push(args),
+        setWidget: (...args: unknown[]) => widgetCalls.push(args),
+        setHeader: () => {},
+        notify: () => {},
+      },
+    } as any);
+
+    assert.deepEqual(statusCalls, [], "step-mode cleanup must leave the NEXT badge visible");
+    assert.equal(
+      widgetCalls.some((args) => Array.isArray(args) && args[0] === "gsd-progress" && args[1] === undefined),
+      false,
+      "step-mode cleanup must not clear the completed step progress surface",
+    );
+    assert.equal(
+      widgetCalls.some((args) => Array.isArray(args) && args[0] === "gsd-health"),
+      false,
+      "step-mode cleanup must not replace the progress surface with idle health",
+    );
+    assert.deepEqual(newSessionWorkspaces, [], "step-mode cleanup must not re-root the visible command session");
+    assert.equal(restoreCalls, 0, "step-mode cleanup must not restore out of the active worktree");
+    assert.equal(autoSession.active, false);
+    assert.equal(autoSession.preserveStepSurfaceAfterLoopExit, false);
+    assert.equal(autoSession.basePath, worktree);
+    assert.equal(realpathSync(process.cwd()), realpathSync(worktree));
+  } finally {
+    autoSession.reset();
+    process.chdir(previousCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("cleanupAfterLoopExit restores project root through lifecycle and preserves chdir", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-cleanup-lifecycle-"));
   const worktree = join(base, ".gsd", "worktrees", "M001");