@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/prompts/sketch.md

@@ -0,0 +1,59 @@
+You are running the GSD **sketch** workflow — explore UI/design ideas with throwaway HTML mockups that let the developer feel a design before committing to implementation.
+
+## Design Idea
+
+{{input}}
+
+## Flags
+
+- `--quick` — {{quickFlag}} (when true, skip decomposition and jump straight to a single mockup)
+- `--text` — {{textFlag}} (when true, use plain-text numbered lists instead of interactive prompts)
+- Frontier mode — {{frontierFlag}} (when true, analyze existing sketches and propose what to sketch next instead of a new one)
+
+## Process
+
+### 1. Route the input
+
+- If frontier mode is active (no idea given, or the word "frontier"): go to **Frontier mode**.
+- Otherwise: continue to **Setup**.
+
+### 2. Setup
+
+Create `.gsd/sketches/` if it does not exist and determine the next sketch number by listing existing `.gsd/sketches/[0-9][0-9][0-9]-*` directories.
+
+### 3. Decompose the design (skip if `--quick`)
+
+If the design idea has multiple surfaces (e.g. landing page, dashboard, empty state), break it into focused mockups. Each should explore one surface or one interaction. Order by the most uncertain design direction first.
+
+### 4. Align on direction
+
+Briefly confirm scope and any constraints (brand, target device, accessibility). Keep this short — sketches are cheap and disposable.
+
+### 5. Build
+
+Create `.gsd/sketches/{{sketchId}}/` and build each mockup as a self-contained `index.html` (inline CSS/JS, no build step). Open it in the browser via the project's tooling so the developer can see and react to it.
+
+### 6. Observe and refine
+
+Let the developer react to each mockup. Iterate quickly on the throwaway HTML. Capture the design decisions that emerge (layout, color, motion, copy).
+
+### 7. Document
+
+Write `.gsd/sketches/{{sketchId}}/README.md` with:
+- The design idea and the surfaces explored
+- The mockup files and what each demonstrates
+- Design decisions captured and their rationale
+- Recommendations for the real implementation
+
+Append a one-line summary to `.gsd/CAPTURES.md` linking the README.
+
+### 8. Frontier mode (only when frontier flag is active)
+
+Load the sketch landscape: read `.gsd/sketches/*/README.md`. Analyze for **integration sketches** (sketches that touch the same flow) and **frontier sketches** (unexplored surfaces, alternative directions, empty/loading/error states). Present concrete candidates and let the developer choose which to run.
+
+## Success criteria
+
+- Each mockup is a self-contained `index.html` with no build step.
+- Artifacts live under `.gsd/sketches/{{sketchId}}/`.
+- The README captures design decisions usable by the real implementation.
+- Iteration is fast and the sketches stay disposable.

package/dist/resources/extensions/gsd/prompts/spec-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **spec-phase** workflow — clarify WHAT a milestone/slice delivers, with ambiguity scoring, before discussion or planning.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--auto` — {{autoFlag}}
+- `--text` — {{textFlag}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice's stated goal, requirements, and any discuss/research context.
+
+2. **Draft the SPEC.** State, in plain language: what this delivers, for whom, the inputs/outputs, the success criteria, and explicit non-goals.
+
+3. **Score ambiguity.** For each part of the spec, score ambiguity (low/medium/high) and identify the specific phrase causing it. High-ambiguity items become discussion questions.
+
+4. **Resolve ambiguity.** For each high-ambiguity item: in `--auto`, infer and flag; otherwise ask one targeted question at a time to resolve it. Update the spec with the resolved language.
+
+5. **Write the SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd discuss-phase` (deeper discussion) or `/gsd plan-phase` (the spec is clear enough to plan).
+
+## Success criteria
+
+- The spec states WHAT, not HOW.
+- Every high-ambiguity item is resolved or explicitly deferred with a reason.
+- Non-goals are explicit.
+- The recommended next step reflects remaining ambiguity.

package/dist/resources/extensions/gsd/prompts/spike.md

@@ -0,0 +1,59 @@
+You are running the GSD **spike** workflow — experiential exploration that builds focused experiments to validate feasibility and produce verified knowledge for the real build.
+
+## Spike Input
+
+{{input}}
+
+## Flags
+
+- `--quick` — {{quickFlag}} (when true, skip decomposition/alignment and jump straight to building)
+- `--text` — {{textFlag}} (when true, use plain-text numbered lists instead of interactive prompts)
+- Frontier mode — {{frontierFlag}} (when true, analyze existing spikes and propose integration/frontier spikes instead of a new one)
+
+## Process
+
+### 1. Route the input
+
+- If frontier mode is active (no idea given, or the word "frontier"): go to **Frontier mode**.
+- Otherwise: continue to **Setup**.
+
+### 2. Setup
+
+Create `.gsd/spikes/` if it does not exist and determine the next spike number by listing existing `.gsd/spikes/[0-9][0-9][0-9]-*` directories. Use the project's detected stack (check `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`) to choose technology. Avoid heavy tooling — pick whatever reaches a runnable result fastest.
+
+### 3. Decompose the idea (skip if `--quick`)
+
+Break the idea into 1–3 focused experiments. Each experiment should validate one specific risk or assumption with a clear **Given/When/Then** validation question. Order by highest risk first.
+
+### 4. Research (brief)
+
+For each experiment, do the minimum research needed to start building — library docs, API shape, known gotchas. Use `resolve_library`/docs lookups. Do not over-research.
+
+### 5. Build
+
+Create `.gsd/spikes/{{spikeId}}/` and build each experiment as a small, self-contained, runnable artifact. Prefer throwaway code that proves the point. Hardcode configuration — do not build config systems.
+
+### 6. Verify
+
+For each experiment, run the validation question and record a verdict: `VALIDATED`, `PARTIAL`, or `INVALIDATED`, with the evidence (command output, observed behavior).
+
+### 7. Document
+
+Write `.gsd/spikes/{{spikeId}}/README.md` with:
+- The original idea and the experiments run
+- Per-experiment verdict + evidence
+- Conclusions and recommendations for the real build
+- Any conventions discovered worth recording (stack, patterns)
+
+Append a one-line summary to `.gsd/CAPTURES.md` linking the README so the spike is discoverable.
+
+### 8. Frontier mode (only when frontier flag is active)
+
+Load the spike landscape: read `.gsd/spikes/*/README.md` and any `CONVENTIONS.md`. Analyze for **integration spikes** (validated spikes that share resources, hand off data, or contend) and **frontier spikes** (gaps, discovered dependencies, alternative approaches). Present concrete candidates with Given/When/Then questions and let the developer choose which to run.
+
+## Success criteria
+
+- Each experiment has a clear validation question and a recorded verdict with evidence.
+- Artifacts live under `.gsd/spikes/{{spikeId}}/`.
+- The README captures conclusions usable by the real build.
+- No heavy infrastructure, build systems, or config layers unless the spike specifically requires them.

package/dist/resources/extensions/gsd/prompts/stats.md

@@ -0,0 +1,43 @@
+You are running the GSD **stats** workflow — display comprehensive project statistics.
+
+## Process
+
+Read the canonical gsd-pi state and present a statistics summary. Use gsd-pi's own tooling to gather the data — do not hand-parse files when a command or query exists.
+
+Gather:
+- Active milestone id/title and overall milestone progress (completed/total).
+- Slice and task progress for the active milestone (completed/total per slice where available).
+- Requirements coverage if tracked.
+- Git metrics: total commits, first commit date, last activity date, current branch.
+- Project age in days.
+
+Present the summary in this shape:
+
+```
+# 📊 Project Statistics — {milestone} {title}
+
+## Progress
+[████████░░] X/Y milestones (Z%)
+
+## Slices (active milestone)
+| Slice | Tasks | Completed | Status |
+
+## Requirements
+✅ X/Y requirements complete
+
+## Git
+- Commits: N
+- Started: YYYY-MM-DD
+- Last activity: YYYY-MM-DD
+
+## Timeline
+- Project age: N days
+```
+
+If no `.gsd/` project exists, say so and suggest `/gsd init`.
+
+## Success criteria
+
+- Numbers come from canonical gsd-pi state, not estimates.
+- The summary is readable in a terminal (ASCII progress bar, tables).
+- Missing sections are omitted rather than printed with zeroes.

package/dist/resources/extensions/gsd/prompts/surface.md

@@ -0,0 +1,25 @@
+You are running the GSD **surface** workflow — manage which skills/extensions are surfaced in the active session.
+
+## Action
+
+{{action}}
+
+## Process
+
+Parse the action:
+
+- **list / status** (default): Show every installed skill/extension with its current surfaced state (enabled/disabled) and source (bundled, project, global). Group by cluster where applicable.
+- **profile <name>**: Apply a named surfacing profile — enable a curated cluster of skills and disable the rest. Confirm the change set before applying.
+- **disable <cluster>**: Disable a cluster of skills so they stop loading into context. Record the change so it persists.
+- **enable <cluster>**: Re-enable a previously disabled cluster.
+- **reset**: Restore the default surfacing state.
+
+Use gsd-pi's own extension/skill management (`/gsd extensions`, `/gsd skill-health`) as the backing store for these changes — do not invent a separate state file.
+
+If the action names an unknown cluster or profile, list the valid options rather than failing silently.
+
+## Success criteria
+
+- The current surfaced state is reported accurately from the backing store.
+- Changes persist via gsd-pi's extension/skill management, not a parallel mechanism.
+- Unknown names produce a helpful list of valid options.

package/dist/resources/extensions/gsd/prompts/thread.md

@@ -0,0 +1,24 @@
+You are running the GSD **thread** workflow — manage persistent context threads for cross-session work, backed by the memory store so threads survive across sessions.
+
+## Action
+
+{{action}}
+
+## Process
+
+A thread is a named, resumable context line: a topic, the open question, decisions so far, and the next step. Threads live in the gsd-pi memory store so they persist and are queryable.
+
+Parse the action:
+
+- **list [--open|--resolved]** (default): list threads filtered by state. Each entry: slug, status, last-updated, one-line topic.
+- **close <slug>**: mark a thread resolved (record the resolution as a knowledge lesson if durable).
+- **status <slug>**: show a thread's full context (topic, decisions, open question, next step).
+- **<name> / <description>** (bare text): create or update a thread with the given name/description, stamping the current state and next step.
+
+Use `/gsd memory` as the backing store for thread persistence. When closing a thread whose resolution is a reusable lesson, also record it via `/gsd knowledge lesson`.
+
+## Success criteria
+
+- Threads persist in the memory store, not in a throwaway file.
+- Listing honors the open/resolved filter.
+- Resolved threads with durable lessons feed the knowledge store.

package/dist/resources/extensions/gsd/prompts/ui-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-phase** workflow — produce a UI design contract (UI-SPEC) for a frontend milestone/slice before implementation.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice goal, requirements, and any existing brand/design references.
+
+2. **Inventory the surfaces.** List every screen/state/component the milestone touches: pages, key states (empty, loading, error, success), and shared components.
+
+3. **Define the design contract per surface:**
+   - Layout (structure, responsive behavior)
+   - Key interactions and their feedback states
+   - Content/copy essentials
+   - Accessibility requirements
+   - Entry/exit points to other surfaces
+
+4. **Align on constraints.** Brand, type scale, color tokens, spacing system, component library — use existing design tokens where they exist; flag gaps.
+
+5. **Write the UI-SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd sketch` to prototype high-uncertainty surfaces, or `/gsd plan-phase` to plan implementation.
+
+## Success criteria
+
+- Every surface the milestone touches is inventoried.
+- Each surface's contract is concrete enough to implement against.
+- Existing design tokens are reused; gaps are flagged.
+- The recommended next step reflects design readiness.

package/dist/resources/extensions/gsd/prompts/ui-review.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-review** workflow — retroactive visual audit of implemented frontend code against design intent.
+
+## Target
+
+{{target}}
+
+## Process
+
+Audit the implemented UI across these pillars, grounding each finding in actual code (component files, styles, markup) with file paths:
+
+1. **Layout & spacing** — alignment, grid/flex correctness, responsive behavior, spacing rhythm.
+2. **Color & contrast** — palette consistency, accessible contrast ratios, dark/light coherence.
+3. **Typography** — type scale, hierarchy, line-height, legibility.
+4. **Interaction & feedback** — hover/focus/active states, loading/empty/error states, motion.
+5. **Consistency** — shared components reused, design tokens applied, no one-off magic numbers.
+6. **Accessibility** — semantic markup, keyboard navigation, ARIA correctness, focus management.
+
+For each pillar, give a score (0–5) with bullet findings (location + issue + suggested fix).
+
+## Output
+
+Write `.gsd/reviews/{{reviewId}}-UI-REVIEW.md` with the per-pillar scores, findings, and a prioritized fix list (critical first). Print the overall score and the critical findings.
+
+## Success criteria
+
+- Every finding cites a component/file path.
+- Each pillar has an explicit score, not just prose.
+- Critical findings are surfaced first and are actionable.
+- The review lives under `.gsd/reviews/`.

package/dist/resources/extensions/gsd/prompts/ultraplan-phase.md

@@ -0,0 +1,24 @@
+You are running the GSD **ultraplan-phase** workflow — offload heavy planning of a milestone/slice to an extended-reasoning plan pass, review the result, and import it back. This uses a local extended-reasoning pass (an external cloud service is not available in this runtime).
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Assemble the planning brief.** Gather the milestone/slice goal, CONTEXT, RESEARCH, decisions, requirements, and a codebase snapshot into a single self-contained brief.
+
+2. **Run the extended-reasoning plan pass.** Produce a thorough plan from the brief using high reasoning effort: full task decomposition, dependency graph, verification per task, risks. This is the "ultraplan" — more exhaustive than a standard plan pass.
+
+3. **Review in the open.** Present the plan for review (the human reviews it before it's imported). Flag anything uncertain, risky, or that diverges from the stated goal.
+
+4. **Import.** On approval, write the plan to the milestone/slice plan artifact in `.gsd/` and record durable decisions. Note that this replaces the cloud review-and-import with a local review.
+
+5. **Route.** Recommend `/gsd dispatch execute` or `/gsd plan-review-convergence` for a convergence pass.
+
+## Success criteria
+
+- The plan is more exhaustive than a standard pass (that's the point of the offload).
+- The human reviews before import (no silent overwrite of an existing plan).
+- The brief is self-contained so the reasoning isn't context-starved.
+- Durable decisions are persisted on import.

package/dist/resources/extensions/gsd/prompts/validate-phase.md

@@ -0,0 +1,26 @@
+You are running the GSD **validate-phase** workflow — retroactively audit and fill validation coverage gaps for completed work, using Nyquist-style coverage sampling.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Map the verification surface.** For the target's tasks, list what behaviors/outputs each claims to verify, and the test (or manual check) that verifies it.
+
+2. **Find coverage gaps.** Identify: behaviors with no test, error/edge paths untested, boundaries between slices untested, and claims verified only by happy-path tests. Apply a Nyquist lens — sample at the rate needed to catch the behavior changing, not just once.
+
+3. **Generate the missing tests.** For each gap that is safe to fill deterministically, write the test (matching the project's test framework and conventions). Run the test suite after adding tests. For gaps that need a human (UI, exploratory), record them as UAT items instead of auto-generating.
+
+4. **Update the validation record.** Write/append the slice's VALIDATION note (or `.gsd/` equivalent) with the coverage map before/after, the tests added, and the remaining human-UAT items.
+
+5. **Report.** Summarize: gaps found, tests added (passing), and remaining human-UAT items.
+
+Prefer delegating test generation to `/gsd add-tests` where it fits, rather than hand-writing every test.
+
+## Success criteria
+
+- Every claimed behavior is mapped to a test (or flagged as needing human UAT).
+- Generated tests pass and match the project's conventions.
+- The validation record reflects the new coverage honestly.
+- Human-only gaps are recorded as UAT items, not silently skipped.

package/dist/resources/extensions/gsd/prompts/verify-work.md

@@ -0,0 +1,24 @@
+You are running the GSD **verify-work** workflow — validate built features through conversational UAT.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load what was built.** Read the target slice/milestone plan and SUMMARY to understand what features were delivered and what their acceptance criteria are.
+
+2. **Draft a UAT script.** Turn each acceptance criterion into a concrete, observable test step the human can perform (or that you can perform via tooling where possible). Group by feature; order so earlier steps set up later ones.
+
+3. **Walk through the script conversationally.** Present one step (or a small group) at a time. For each, record the outcome: `pass`, `fail` (with what happened), `blocked` (with the blocker), or `skipped` (intentionally). Do not advance past a fail without acknowledging it.
+
+4. **Where you can self-verify** (deterministic checks: type checks, tests, lint, schema), run them and include the result alongside the human step.
+
+5. **Produce the verdict.** After all steps: `pass` (all criteria met), `needs-attention` (some steps failed but none blocking), or `needs-remediation` (a blocking failure). Record the UAT outcome against the slice via the appropriate gsd-pi mechanism.
+
+## Success criteria
+
+- Every acceptance criterion becomes a concrete, observable step.
+- Outcomes are recorded honestly — fails are not hidden.
+- Deterministic checks are run where possible, not just asked about.
+- The final verdict maps to a canonical gsd-pi outcome.

package/dist/resources/extensions/gsd/prompts/workspace.md

@@ -0,0 +1,22 @@
+You are running the GSD **workspace** workflow — manage isolated workspace environments for parallel or experimental work.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workspace is an isolated environment backed by a git worktree. Map workspace actions onto worktrees:
+
+- **--list / list** (default): show all worktrees with state (current, merged, clean, dirty) — `/gsd worktree list`.
+- **--remove <name>**: remove a worktree — `/gsd worktree remove`.
+- **--merge <name>**: merge a worktree — `/gsd worktree merge`.
+- **--clean / clean**: clean stale worktree records — `/gsd worktree clean`.
+
+Route every structural action to `/gsd worktree` rather than hand-managing git worktrees.
+
+## Success criteria
+
+- Listing reflects canonical worktree state.
+- Structural actions route to `/gsd worktree`, keeping state canonical.
+- Removing a dirty worktree is guarded (confirm first).

package/dist/resources/extensions/gsd/prompts/workstreams.md

@@ -0,0 +1,24 @@
+You are running the GSD **workstreams** workflow — manage parallel workstreams that run multiple milestones concurrently with isolation.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workstream is a parallel worker running its own milestone in its own branch/worktree. Map workstream actions onto parallel workers:
+
+- **list / status** (default): show all parallel workers — milestone, branch/worktree, progress, state (running/paused/done/failed).
+- **create / start**: start parallel workers for all eligible milestones (`/gsd parallel start`). Does not accept a milestone target; use `/gsd parallel start` directly to start all eligible milestones.
+- **switch**: focus the dashboard on the most active worker (`/gsd parallel watch`). Does not accept a milestone target; use `/gsd parallel watch` directly to monitor workers.
+- **progress**: show all workers' progress (`/gsd parallel status`). Does not accept a milestone target; use `/gsd parallel status` directly for worker status.
+- **pause / resume <milestone>**: pause or resume a worker (`/gsd parallel pause|resume`).
+- **complete <milestone>**: complete and merge a worker's milestone (`/gsd parallel merge`).
+
+Route every structural action to `/gsd parallel <subcommand>` rather than reimplementing worktree/merge logic.
+
+## Success criteria
+
+- Status reflects canonical parallel-worker state.
+- Structural actions route to `/gsd parallel`, not duplicates.
+- Unknown milestones list the valid options rather than failing silently.

package/dist/resources/extensions/gsd/queue-order.js

@@ -31,8 +31,9 @@ export function loadQueueOrder(basePath) {
     return data?.order ?? null;
 }
 /**
- * Save a custom queue order. The DB sequence is canonical when a DB
- * connection is open; QUEUE-ORDER.json remains a compatibility projection.
+ * Save a custom queue order. When the DB connection is open, mirror the order
+ * into milestone sequence; QUEUE-ORDER.json remains the durable file contract
+ * for prompt-driven flows such as /gsd rethink.
  */
 export function saveQueueOrder(basePath, order) {
     if (isDbAvailable()) {

package/dist/resources/extensions/gsd/quick.js

@@ -8,8 +8,8 @@
  * Quick tasks live in `.gsd/quick/` and are tracked in STATE.md's
  * "Quick Tasks Completed" table.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -19,6 +19,7 @@ import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat } from ".
 import { nativeHasStagedChanges } from "./native-git-bridge.js";
 import { resolveUokFlags } from "./uok/flags.js";
 let pendingQuickReturn = null;
+const pendingQuickReturnMisses = new Map();
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from a description.
@@ -169,11 +170,36 @@ export function buildQuickCommitInstruction(basePath, root) {
         "   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.",
     ].join("\n");
 }
+function readHeadBranchName(basePath) {
+    try {
+        const gitPath = join(basePath, ".git");
+        if (!existsSync(gitPath))
+            return null;
+        let headPath;
+        if (lstatSync(gitPath).isDirectory()) {
+            headPath = join(gitPath, "HEAD");
+        }
+        else {
+            const gitFile = readFileSync(gitPath, "utf-8").trim();
+            if (!gitFile.startsWith("gitdir: "))
+                return null;
+            headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+        }
+        const head = readFileSync(headPath, "utf-8").trim();
+        if (!head.startsWith("ref: refs/heads/"))
+            return null;
+        return head.slice("ref: refs/heads/".length);
+    }
+    catch {
+        return null;
+    }
+}
 function quickReturnStatePath(basePath) {
     return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 function persistPendingReturn(state) {
     pendingQuickReturn = state;
+    pendingQuickReturnMisses.delete(state.basePath);
     mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
     writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -181,6 +207,13 @@ function readPendingReturn(basePath) {
     if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
         return pendingQuickReturn;
     }
+    if (pendingQuickReturnMisses.has(basePath)) {
+        const statePath = quickReturnStatePath(basePath);
+        if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+            return null;
+        }
+        pendingQuickReturnMisses.delete(basePath);
+    }
     try {
         const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
         const parsed = JSON.parse(raw);
@@ -191,6 +224,7 @@ function readPendingReturn(basePath) {
             && typeof parsed.slug === "string"
             && typeof parsed.description === "string") {
             pendingQuickReturn = parsed;
+            pendingQuickReturnMisses.delete(basePath);
             return pendingQuickReturn;
         }
     }
@@ -200,14 +234,23 @@ function readPendingReturn(basePath) {
     const inferred = inferQuickReturnFromBranch(basePath);
     if (inferred) {
         pendingQuickReturn = inferred;
+        pendingQuickReturnMisses.delete(basePath);
         return inferred;
     }
+    const branchAtMiss = readHeadBranchName(basePath);
+    if (branchAtMiss) {
+        pendingQuickReturnMisses.set(basePath, branchAtMiss);
+    }
     return null;
 }
 function clearPendingReturn(basePath) {
     if (pendingQuickReturn?.basePath === basePath) {
         pendingQuickReturn = null;
     }
+    const branchAtMiss = readHeadBranchName(basePath);
+    if (branchAtMiss) {
+        pendingQuickReturnMisses.set(basePath, branchAtMiss);
+    }
     rmSync(quickReturnStatePath(basePath), { force: true });
 }
 function hasStagedChanges(basePath) {

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -3,6 +3,7 @@
 import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient } from "./error-classifier.js";
 import { recoveryRemediation } from "./guidance.js";
+import { isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
 import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 export function classifyFailure(input) {
@@ -51,6 +52,13 @@ const FAILURE_TAXONOMY = {
     "runtime-unknown": { action: "escalate", label: null },
 };
 function inferFailureKind(message) {
+    // A terminal tool-surface failure (workflow MCP server in failed/needs-auth/
+    // disabled) will not self-heal, so it must escalate rather than retry the
+    // same model into the per-unit cost cap. Checked before the generic
+    // tool-unavailable branch, which matches the same readiness prefix and
+    // would otherwise route it to retry. See #783.
+    if (isTerminalToolSurfaceError(message))
+        return "runtime-unknown";
     if (isToolUnavailableError(message))
         return "tool-unavailable";
     if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -202,7 +202,7 @@ export function parseRoadmapSlices(content) {
     const checkboxItems = slicesSection.split("\n");
     let currentSlice = null;
     for (const line of checkboxItems) {
-        const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+        const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.-]+):\s+(.+?)\*\*\s*(.*)/);
         if (cbMatch) {
             if (currentSlice)
                 slices.push(currentSlice);

package/dist/resources/extensions/gsd/root-write-leak-guard.js

@@ -4,9 +4,15 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { GSD_RUNTIME_PATTERNS } from "./gitignore.js";
 const MAX_SYNC_FINGERPRINT_BYTES = 1_500_000_000;
+const ROOT_RUNTIME_PATH_PREFIXES = Array.from(new Set(GSD_RUNTIME_PATTERNS.map((pattern) => {
+    const path = pattern.replace(/\/+$/, "");
+    const slash = path.indexOf("/");
+    return slash === -1 ? path : path.slice(0, slash);
+})));
 function isRootRuntimePath(path) {
-    return path === ".gsd" || path.startsWith(".gsd/");
+    return ROOT_RUNTIME_PATH_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
 }
 function fileFingerprint(rootPath, relPath) {
     const absPath = join(rootPath, relPath);

package/dist/resources/extensions/gsd/safety/content-validator.js

@@ -29,7 +29,8 @@ export function validateContent(unitType, artifactPath) {
         return [];
     }
 }
-const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+// Matches both legacy "**T01: title**" and flat-phase "**T01**: title" checkbox formats.
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+(?:\*\*)?:|#{2,4}\s+T\d+\b)/gm;
 const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
 const VALIDATORS = {
     "plan-slice": validatePlanSlice,

package/dist/resources/extensions/gsd/safety/destructive-guard.js

@@ -20,14 +20,21 @@ const DESTRUCTIVE_PATTERNS = [
     { pattern: /\baws\s+\w+\s+(delete|create|put|remove|terminate)\b/i, label: "AWS mutation" },
     { pattern: /\bkubectl\s+(delete|apply)\b/i, label: "kubectl mutation" },
 ];
+function stripQuotedAndComments(command) {
+    return command
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+        .replace(/(^|\s)#.*$/g, "$1");
+}
 /**
  * Classify a bash command for destructive operations.
  * Returns the list of matched destructive pattern labels.
  */
 export function classifyCommand(command) {
+    const commandToClassify = stripQuotedAndComments(command);
     const labels = [];
     for (const { pattern, label } of DESTRUCTIVE_PATTERNS) {
-        if (pattern.test(command)) {
+        if (pattern.test(commandToClassify)) {
             // Deduplicate labels (e.g., two force-push patterns)
             if (!labels.includes(label))
                 labels.push(label);