@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.9f86580

package/src/resources/extensions/gsd/guided-flow.ts

@@ -98,6 +98,7 @@ import {
   getDiscussionMilestoneId,
   hasPendingAutoStart,
   setPendingAutoStart,
+  type PendingAutoStartEntry,
 } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
 
@@ -320,6 +321,116 @@ export function _roadmapHasParseableSlicesForTest(
   return parseRoadmapSlices(roadmapContent).length > 0;
 }
 
+function hasExecutablePlanForHandoff(milestoneId: string, roadmapFile: string | null): boolean {
+  if (isDbAvailable()) {
+    return getMilestoneSlices(milestoneId).length > 0;
+  }
+  if (!roadmapFile) return false;
+  try {
+    return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length > 0;
+  } catch (e) {
+    logWarning(
+      "guided",
+      `failed to parse roadmap slices for ${milestoneId}: ${(e as Error).message}`,
+    );
+    return false;
+  }
+}
+
+function formatAcceptedDiscussHandoffMessage(
+  milestoneId: string,
+  contextFile: string | null,
+  hasExecutablePlan: boolean,
+): string {
+  if (hasExecutablePlan) return `Milestone ${milestoneId} ready.`;
+  if (contextFile) return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+  return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}
+
+function manifestContainsMilestone(basePath: string, milestoneId: string): boolean {
+  try {
+    const manifest = readManifest(basePath);
+    return (
+      Array.isArray(manifest?.milestones) &&
+      manifest.milestones.some(m => m.id === milestoneId)
+    );
+  } catch (e) {
+    logWarning("guided", `R3b: failed to read state manifest: ${(e as Error).message}`);
+    return false;
+  }
+}
+
+function notifyDbRowRecoveryFailed(entry: PendingAutoStartEntry): void {
+  entry.ctx.ui.notify(
+    `Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`,
+    "error",
+  );
+}
+
+function noteDbRowRecoveryMiss(entry: PendingAutoStartEntry): void {
+  entry.r3bRecoveryCount += 1;
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    notifyDbRowRecoveryFailed(entry);
+  }
+}
+
+function ensureMilestoneRowForAcceptedHandoff(
+  entry: PendingAutoStartEntry,
+  contextFile: string | null,
+): boolean {
+  if (!isDbAvailable()) return true;
+
+  const { basePath, milestoneId } = entry;
+  const milestoneRow = getMilestone(milestoneId);
+  if (milestoneRow) return true;
+
+  if (manifestContainsMilestone(basePath, milestoneId)) {
+    logWarning(
+      "guided",
+      `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`,
+    );
+    return true;
+  }
+
+  if (!contextFile) {
+    entry.ctx.ui.notify(
+      `Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+      `PROJECT.md may have failed to register milestones. ` +
+      `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+      `then re-run /gsd to recover.`,
+      "error",
+    );
+    return false;
+  }
+
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+      `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`,
+    );
+    return false;
+  }
+
+  logWarning(
+    "guided",
+    `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+    `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
+  );
+
+  try {
+    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+  } catch (e) {
+    logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
+  }
+
+  if (getMilestone(milestoneId)) return true;
+
+  noteDbRowRecoveryMiss(entry);
+  return false;
+}
+
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
@@ -344,10 +455,8 @@ interface PendingDeepProjectSetupEntry {
 // phrase before giving up and asking the user to re-run /gsd.
 const MAX_READY_REJECTS = 2;
 
-// H1 (#5012): cap for Gate 1b plan-blocked recovery hints. After this many
-// consecutive recovery attempts the loop is stopped and the user is directed
-// to investigate manually.
-const MAX_PLAN_BLOCKED_RECOVERIES = 3;
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
 
 // #4573: matches the canonical ready phrase the discuss prompt asks the LLM
 // to emit. Accepts any M-prefixed milestone ID (three digits + optional
@@ -613,72 +722,12 @@ export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
     }
   }
 
-  // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
-  // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
-  // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
-  // depth-verification gate.  Emit a recovery hint so the next agent turn can retry
-  // gsd_plan_milestone, then return false (keep blocking auto-start).
-  // If CONTEXT.md does not exist (discuss-incomplete), Gate 1 already blocked above.
-  if (isDbAvailable()) {
-    const dbRow = getMilestone(milestoneId);
-    if (dbRow?.status === "queued" && contextFile) {
-      if (entry.planBlockedRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-        // H1: recovery loop cap reached — stop triggering new turns, escalate to user.
-        logWarning(
-          "guided",
-          `Gate 1b: milestone ${milestoneId} plan-blocked recovery limit reached ` +
-          `(${entry.planBlockedRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`,
-        );
-        ctx.ui.notify(
-          `Milestone ${milestoneId} plan_milestone has been blocked ${entry.planBlockedRecoveryCount} times. ` +
-          `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`,
-          "error",
-        );
-        return false;
-      }
-      logWarning(
-        "guided",
-        `Gate 1b: milestone ${milestoneId} queued with CONTEXT.md present — ` +
-        `plan_milestone was blocked; emitting recovery hint ` +
-        `(attempt ${entry.planBlockedRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`,
-      );
-      ctx.ui.notify(
-        `Milestone ${milestoneId}: context file exists but milestone is still queued. ` +
-        `Retrying gsd_plan_milestone to complete the blocked planning step.`,
-        "warning",
-      );
-      try {
-        pi.sendMessage(
-          {
-            customType: "gsd-plan-milestone-blocked-recovery",
-            content:
-              `Milestone ${milestoneId} has ${contextFile} on disk but its DB row is still ` +
-              `"queued". The gsd_plan_milestone tool was previously blocked by the ` +
-              `depth-verification gate. Call gsd_plan_milestone now to complete the ` +
-              `planning phase.`,
-            display: false,
-          },
-          { triggerTurn: true },
-        );
-        // Increment only after a successful dispatch so transient sendMessage
-        // failures do not consume recovery budget.
-        entry.planBlockedRecoveryCount += 1;
-      } catch (e) {
-        logWarning("guided", `Gate 1b recovery sendMessage failed: ${(e as Error).message}`);
-      }
-      return false;
-    }
-  }
-
-  // Gate 2: STATE.md must exist — written as the last step in the discuss
-  // output phase. This prevents auto-start from firing during Phase 3
-  // (sequential readiness gates for remaining milestones) in multi-milestone
-  // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been
-  // processed yet.
-  const stateFilePath = entry.scope.stateFile();
-  if (!existsSync(stateFilePath)) return false; // discussion not finalized yet
+  // Gate 1b: accept the in-flight discuss handoff. A queued DB row with pinned
+  // CONTEXT.md is Discussion Complete, Planning Pending, not a plan-blocked
+  // failure. If the row is missing, only this pending handoff may repair it.
+  if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile)) return false;
 
-  // Gate 3: Multi-milestone completeness warning
+  // Gate 2: Multi-milestone completeness warning
   // Parse PROJECT.md for milestone sequence, warn if any are missing context.
   // Don't block — milestones can be intentionally queued without context.
   const projectFile = resolveGsdRootFile(basePath, "PROJECT");
@@ -705,7 +754,7 @@ export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
     } catch (e) { logWarning("guided", `PROJECT.md parsing failed: ${(e as Error).message}`); }
   }
 
-  // Gate 4: Discussion manifest process verification (multi-milestone only)
+  // Gate 3: Discussion manifest process verification (multi-milestone only)
   // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
   // When it exists, validate it before auto-starting. Project history alone is
   // not a reliable signal for the current discussion mode.
@@ -747,71 +796,12 @@ export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
     try { unlinkSync(manifestPath); } catch (e) { logWarning("guided", `manifest unlink failed: ${(e as Error).message}`); }
   }
 
-  // R3b: belt-and-suspenders for silent registration failure. The discuss flow
-  // finished and STATE.md exists, but the milestone may never have landed in
-  // the DB. Without this guard, the user sees "Milestone M001 ready." and then
-  // /gsd reports "No Active Milestone".
-  if (isDbAvailable()) {
-    const milestoneRow = getMilestone(milestoneId);
-    if (!milestoneRow) {
-      let manifestHasMilestone = false;
-      try {
-        const manifest = readManifest(basePath);
-        manifestHasMilestone = Array.isArray(manifest?.milestones) && manifest.milestones.some(m => m.id === milestoneId);
-      } catch (e) {
-        logWarning("guided", `R3b: failed to read state manifest: ${(e as Error).message}`);
-      }
-      if (manifestHasMilestone) {
-        logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
-      } else if (contextFile) {
-        // R3b-recovery: CONTEXT.md is on disk but gsd_plan_milestone was never called
-        // (likely blocked by the depth-verification gate re-firing on post-verification
-        // text). Auto-register as "queued" so Gate 1b can pick it up and retry
-        // gsd_plan_milestone on the next checkAutoStartAfterDiscuss call.
-        if (entry.r3bRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-          logWarning(
-            "guided",
-            `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
-            `(${entry.r3bRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`,
-          );
-          ctx.ui.notify(
-            `Milestone ${milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
-            `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`,
-            "error",
-          );
-          return false;
-        }
-        logWarning(
-          "guided",
-          `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
-          `for Gate 1b recovery (attempt ${entry.r3bRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`,
-        );
-        try {
-          insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
-        } catch (e) {
-          logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
-        }
-        entry.r3bRecoveryCount += 1;
-        ctx.ui.notify(
-          `Milestone ${milestoneId}: context file exists but DB row was missing — recovering. Retrying gsd_plan_milestone.`,
-          "warning",
-        );
-        return false;
-      } else {
-        ctx.ui.notify(
-          `Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
-          `PROJECT.md may have failed to register milestones. ` +
-          `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
-          `then re-run /gsd to recover.`,
-          "error",
-        );
-        return false;
-      }
-    }
-  }
-
   deletePendingAutoStart(basePath);
-  ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
+  const hasExecutablePlan = hasExecutablePlanForHandoff(milestoneId, roadmapFile);
+  ctx.ui.notify(
+    formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan),
+    "success",
+  );
   if (entry.startAuto !== false) {
     scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
   }
@@ -1168,7 +1158,10 @@ async function dispatchWorkflow(
             ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
             : undefined,
         baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+        // Guided flow starts the MCP workflow server as part of dispatch, so the
+        // parent session's activeTools doesn't include MCP tools yet. The MCP
+        // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+        // here — not whether MCP tools are pre-registered in the parent session.
       },
     );
     if (compatibilityError) {

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -16,6 +16,7 @@ import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 import type { DispatchAction, DispatchContext } from "./auto-dispatch.js";
 import {
   commitPendingMilestoneCloseoutChanges,
@@ -37,7 +38,8 @@ export async function isMilestoneCloseoutSettled(mid: string, basePath: string):
     if (isDbAvailable()) {
       const milestone = getMilestone(mid);
       if (milestone && isClosedStatus(milestone.status)) {
-        if (verifyExpectedArtifact("complete-milestone", mid, basePath)) {
+        const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+        if (closeoutGate.ok && verifyExpectedArtifact("complete-milestone", mid, basePath)) {
           return true;
         }
       }

package/src/resources/extensions/gsd/pending-auto-start.ts

@@ -14,7 +14,6 @@ export interface PendingAutoStartEntry {
   createdAt: number;
   readyRejectCount?: number;
   scope: MilestoneScope;
-  planBlockedRecoveryCount: number;
   r3bRecoveryCount: number;
 }
 
@@ -51,7 +50,6 @@ export function setPendingAutoStart(basePath: string, entry: PendingAutoStartInp
   const scope = scopeMilestone(ws, entry.milestoneId);
   pendingAutoStartMap.set(basePath, {
     createdAt: Date.now(),
-    planBlockedRecoveryCount: 0,
     r3bRecoveryCount: 0,
     ...entry,
     scope,

package/src/resources/extensions/gsd/planner-handoff.ts

@@ -0,0 +1,149 @@
+// Project/App: gsd-pi
+// File Purpose: Optional gsd-planner handoff after milestone planning.
+
+import { spawn as spawnChild, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdRoot } from "./paths.js";
+
+export const PLANNER_HANDOFF_RULE_NAME = "planning review handoff -> gsd-planner";
+export const GSD_PLANNER_COMMAND = "gsd-planner";
+
+export interface GsdPlannerSpawnPlan {
+  command: string;
+  args: string[];
+  cwd: string;
+}
+
+export interface GsdPlannerLaunchInput {
+  basePath: string;
+  milestoneId?: string | null;
+  extraArgs?: string[];
+}
+
+export type GsdPlannerLaunchResult =
+  | { status: "launched"; plan: GsdPlannerSpawnPlan }
+  | { status: "failed"; plan: GsdPlannerSpawnPlan; error: Error };
+
+type SpawnLike = (
+  command: string,
+  args: readonly string[],
+  options: SpawnOptions,
+) => ChildProcess;
+
+export interface GsdPlannerLaunchDeps {
+  spawn?: SpawnLike;
+}
+
+function handoffDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "planner-handoffs");
+}
+
+function safeMilestoneFileSegment(milestoneId: string): string {
+  return milestoneId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown";
+}
+
+function handoffMarkerPath(basePath: string, milestoneId: string): string {
+  return join(handoffDir(basePath), `${safeMilestoneFileSegment(milestoneId)}.json`);
+}
+
+export function hasPlannerHandoffBeenOffered(basePath: string, milestoneId: string): boolean {
+  return existsSync(handoffMarkerPath(basePath, milestoneId));
+}
+
+export function markPlannerHandoffOffered(
+  basePath: string,
+  milestoneId: string,
+  source: "auto" | "command" = "auto",
+): void {
+  mkdirSync(handoffDir(basePath), { recursive: true });
+  writeFileSync(
+    handoffMarkerPath(basePath, milestoneId),
+    JSON.stringify({
+      milestoneId,
+      source,
+      offeredAt: new Date().toISOString(),
+    }, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+export function buildGsdPlannerSpawnPlan(input: GsdPlannerLaunchInput): GsdPlannerSpawnPlan {
+  const args = ["--project", input.basePath];
+  const milestoneId = input.milestoneId?.trim();
+  if (milestoneId) args.push("--milestone", milestoneId);
+  args.push(...(input.extraArgs ?? []));
+  return {
+    command: GSD_PLANNER_COMMAND,
+    args,
+    cwd: input.basePath,
+  };
+}
+
+function quoteArg(arg: string): string {
+  return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+
+export function formatGsdPlannerCommand(plan: GsdPlannerSpawnPlan): string {
+  return [plan.command, ...plan.args].map(quoteArg).join(" ");
+}
+
+export async function launchGsdPlanner(
+  input: GsdPlannerLaunchInput,
+  deps: GsdPlannerLaunchDeps = {},
+): Promise<GsdPlannerLaunchResult> {
+  const plan = buildGsdPlannerSpawnPlan(input);
+  const spawn = deps.spawn ?? spawnChild;
+
+  let child: ChildProcess;
+  try {
+    child = spawn(plan.command, plan.args, {
+      cwd: plan.cwd,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } catch (err) {
+    return {
+      status: "failed",
+      plan,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (result: GsdPlannerLaunchResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    child.once("error", (err) => {
+      settle({
+        status: "failed",
+        plan,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    });
+    child.once("spawn", () => {
+      child.unref();
+      settle({ status: "launched", plan });
+    });
+  });
+}
+
+export function formatPlannerHandoffPauseReason(milestoneId: string): string {
+  return [
+    `Milestone ${milestoneId} is planned. Review or customize the plan before implementation if needed.`,
+    `Run /gsd planner to launch ${GSD_PLANNER_COMMAND}, or run /gsd auto to continue without planner changes.`,
+  ].join(" ");
+}
+
+export function formatPlannerLaunchUnavailable(plan: GsdPlannerSpawnPlan, error: Error): string {
+  return [
+    `Could not launch ${GSD_PLANNER_COMMAND}: ${error.message}`,
+    `Install ${GSD_PLANNER_COMMAND} or run it manually: ${formatGsdPlannerCommand(plan)}`,
+  ].join("\n");
+}

package/src/resources/extensions/gsd/preferences-models.ts

@@ -372,6 +372,7 @@ export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
     soft_timeout_minutes: configured.soft_timeout_minutes ?? 20,
     idle_timeout_minutes: configured.idle_timeout_minutes ?? 10,
     hard_timeout_minutes: configured.hard_timeout_minutes ?? 30,
+    stalled_tool_timeout_minutes: configured.stalled_tool_timeout_minutes ?? 5,
     ...(configured.model ? { model: configured.model } : {}),
   };
 }

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

@@ -256,6 +256,14 @@ export interface AutoSupervisorConfig {
   soft_timeout_minutes?: number;
   idle_timeout_minutes?: number;
   hard_timeout_minutes?: number;
+  /**
+   * Dedicated budget for a single in-flight tool call before it is treated as
+   * hung. Distinct from `idle_timeout_minutes`: a genuinely stuck tool should
+   * be recovered in minutes rather than waiting out the full idle window. A
+   * long-but-progressing session is not idle, so it must not share the hung-tool
+   * threshold.
+   */
+  stalled_tool_timeout_minutes?: number;
 }
 
 export interface RemoteQuestionsConfig {

package/src/resources/extensions/gsd/prompts/plan-milestone.md

@@ -14,7 +14,7 @@ All relevant context is preloaded below. Start immediately without re-reading th
 
 ## Already Planned? Soft Brake
 
-If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
+If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_milestone_status` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
 
 If only the file or only DB rows exist, the prior write was incomplete; plan normally so the tool reconciles both.
 

package/src/resources/extensions/gsd/prompts/run-uat.md

@@ -27,7 +27,7 @@ You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply a
 ### Automation rules by mode
 
 - `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
-- `browser-executable` — use gsd-browser tools to navigate to the target URL and verify expected behavior. Prefer `mcp__gsd-browser__browser_*` tools when namespaced, or direct `browser_*` tools when surfaced without a namespace. Capture screenshots as evidence. Record pass/fail with specific assertions.
+- `browser-executable` — use browser tools to navigate to the target URL and verify expected behavior. Prefer direct `browser_*` tools when available. Capture screenshots as evidence. Record pass/fail with specific assertions.
 - `runtime-executable` — execute the specified command or script. Capture stdout/stderr as evidence. Record pass/fail based on exit code and output.
 - `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
 - `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
@@ -48,7 +48,7 @@ Choose the lightest tool that proves the check honestly:
 - Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
-- For live/runtime/UI checks, exercise the real flow with gsd-browser when applicable and inspect runtime/network/console state
+- For live/runtime/UI checks, exercise the real flow with browser tools when applicable and inspect runtime/network/console state
 - When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:
@@ -75,24 +75,10 @@ verdict: "PASS" | "FAIL" | "PARTIAL",
 notes: "<one sentence overall verdict rationale>",
 ```
 
-Use this exact `presentation` shape in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one:
+Use this canonical `presentation` object in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one. Keep `toolPresentationPlanId` as `{{toolPresentationPlanId}}`. If browser tools were actually presented for this run, add those concrete browser tool names to `presentedTools`; otherwise reuse this object exactly:
 
-```ts
-presentation: {
-  surface: "mcp",
-  presentedTools: [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-  ],
-  blockedTools: [
-    { name: "gsd_exec", reason: "forbidden during run-uat" },
-    { name: "gsd_summary_save", reason: "forbidden during run-uat" },
-    { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
-  ],
-}
+```json
+{{canonicalPresentation}}
 ```
 
 Pass `checks` with this logical shape:

package/src/resources/extensions/gsd/prompts/system.md

@@ -118,7 +118,7 @@ Templates are in `{{templatesDir}}`.
 
 **Secrets:** Use `secure_env_collect`. Never ask the user to edit `.env` files or paste secrets.
 
-**Browser verification:** Verify frontend work against a running app with gsd-browser by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If tools are MCP-namespaced, prefer `mcp__gsd-browser__browser_*`. Retry only with a new hypothesis.
+**Browser verification:** Verify frontend work against a running app with browser tools by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If browser tools are MCP-namespaced, use that host-provided browser surface. Retry only with a new hypothesis.
 
 **Database:** Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')`; the engine owns a single-writer WAL connection. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools.
 

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -6,7 +6,9 @@ import { ReconciliationFailedError } from "./state-reconciliation.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
+  | "tool-contract"
   | "deterministic-policy"
+  | "lifecycle-progression"
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
@@ -52,6 +54,14 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         exitReason: "tool-schema",
         remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
       };
+    case "tool-contract":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
+        exitReason: "tool-contract",
+        remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+      };
     case "deterministic-policy":
       return {
         failureKind,
@@ -60,6 +70,14 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         exitReason: "deterministic-policy",
         remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
       };
+    case "lifecycle-progression":
+      return {
+        failureKind,
+        action: "stop",
+        reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
+        exitReason: "lifecycle-progression",
+        remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+      };
     case "stale-worker":
       return {
         failureKind,
@@ -118,6 +136,8 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
 }
 
 function inferFailureKind(message: string): RecoveryFailureKind {
+  if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message)) return "tool-contract";
+  if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message)) return "lifecycle-progression";
   if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";
   if (/deterministic policy|policy rejection|write gate|blocked by policy/i.test(message)) return "deterministic-policy";
   if (/stale worker|stale lock|worker.*stale/i.test(message)) return "stale-worker";

package/src/resources/extensions/gsd/skill-manifest.ts

@@ -117,6 +117,18 @@ const UNIT_TYPE_SKILL_MANIFEST: Record<string, string[]> = {
     "review",
     "accessibility",
   ],
+  // Slice closeout — the "closer" role: verify assembled task work, write the
+  // downstream-ready summary + UAT, optionally drive reviewer/security/tester
+  // subagents. Predictable skill set, mirrors `complete-milestone`.
+  "complete-slice": [
+    "verify-before-complete",
+    "test",
+    "review",
+    "security-review",
+    "write-docs",
+    "observability",
+    "handoff",
+  ],
   // `execute-task` intentionally omitted — implementation hot path covers a
   // wide surface of technologies; wildcard fallback preserves today's
   // behavior until per-task skill hints can be derived from task-plan