@opengsd/gsd-pi 1.3.0 → 1.4.0

package/dist/resources/extensions/gsd/preferences-models.js

@@ -10,7 +10,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
-import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { getUnitPhaseChain } from "./unit-registry.js";
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
@@ -74,8 +74,10 @@ function resolveWinningPhase(models, chain) {
  * - Legacy: `planning: claude-opus-4-6`
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
  */
-export function resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds) {
-    const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+export function resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds, preferredModelId) {
+    const loadOpts = availableModelIds !== undefined || preferredModelId !== undefined
+        ? { availableModelIds, preferredModelId }
+        : undefined;
     const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
     const chain = phaseChainForUnit(unitType);
     if (!chain)
@@ -159,13 +161,20 @@ export function resolveThinkingLevelForUnit(unitType, basePath, availableModelId
  * `openai-codex/gpt-5.4`).  When a bare ID is found and sessionProvider
  * is available, the session provider is used.  Without sessionProvider,
  * bare IDs are still returned with provider set to the bare ID itself
- * so downstream resolution (resolveModelId) can match it.
+ * so downstream resolution (resolveModelId) can match it. Accepts an optional
+ * `sessionModelId` so token-profile defaults can preserve the selected model
+ * before auto-mode captures its start snapshot.
  *
  * Returns `{ provider, id }` or `undefined` if no model preference is
  * configured.
  */
-export function resolveDefaultSessionModel(sessionProvider, basePath, availableModelIds) {
-    const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+export function resolveDefaultSessionModel(sessionProvider, basePath, availableModelIds, sessionModelId) {
+    const preferredModelId = sessionModelId && sessionProvider
+        ? `${sessionProvider}/${sessionModelId}`
+        : sessionModelId;
+    const loadOpts = availableModelIds !== undefined || preferredModelId !== undefined
+        ? { availableModelIds, preferredModelId }
+        : undefined;
     const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
     const models = prefs?.preferences?.models;
     if (!models)
@@ -353,6 +362,7 @@ export function updatePreferencesModels(models) {
         content = content.trimEnd() + "\n\n" + modelsBlock + "\n";
     }
     writeFileSync(prefsPath, content, "utf-8");
+    clearGSDPreferencesCache();
 }
 /**
  * Resolve the dynamic routing configuration from effective preferences.
@@ -429,22 +439,24 @@ const PROFILE_TIER_MAP = {
  * the best match on the anchor provider (session / auto-start model). Callers
  * scope the available-model list via `modelIdsForProfileResolution` so token
  * profiles do not hop to a cheaper provider (e.g. Gemini Flash) when the user
- * is working on OpenAI or Anthropic. When not known (e.g., early startup),
- * falls back to canonical Anthropic model IDs.
+ * is working on OpenAI or Anthropic. When the selected/session model is known,
+ * it is preferred for tiers it can satisfy. When the registry is unavailable
+ * (e.g., early startup), falls back to canonical Anthropic model IDs.
  *
  * @param profile           The token profile to resolve
  * @param availableModelIds Optional list of available model IDs for cross-provider resolution.
  *                          Undefined means the registry is unavailable.
  * @param routingConfig     Optional routing config for tier model pins.
+ * @param preferredModelId  Optional selected/session model ID to prefer.
  */
-export function resolveProfileDefaults(profile, availableModelIds, routingConfig = defaultRoutingConfig()) {
+export function resolveProfileDefaults(profile, availableModelIds, routingConfig = defaultRoutingConfig(), preferredModelId) {
     // burn-max never writes model defaults — preserve user-selected models.
     // For the other three profiles, derive concrete model IDs from the tier map
     // against the available-model list when the registry is provided. If callers
     // omit the registry entirely, use canonical fallbacks explicitly.
     const tierMap = PROFILE_TIER_MAP[profile];
-    const resolveTierModel = (tier) => Array.isArray(availableModelIds)
-        ? resolveModelForTier(tier, availableModelIds, routingConfig)
+    const resolveTierModel = (tier) => Array.isArray(availableModelIds) || preferredModelId
+        ? resolveModelForTier(tier, availableModelIds ?? [], routingConfig, undefined, preferredModelId)
         : canonicalModelForTier(tier);
     const models = profile === "burn-max"
         ? undefined

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

@@ -9,7 +9,7 @@
  * All symbols are re-exported here so that existing `import { ... } from "./preferences.js"`
  * statements continue to work without modification.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
@@ -124,16 +124,19 @@ export function resolveProfileAnchorProvider(sessionProvider, autoModeStartProvi
  * the user can actually call (from the live registry), not canonical Anthropic
  * fallbacks.
  */
-export function loadEffectiveGSDPreferencesWithRegistry(registry, basePath, anchorProvider) {
+export function loadEffectiveGSDPreferencesWithRegistry(registry, basePath, anchorProvider, preferredModelId) {
+    const preferenceOpts = preferredModelId !== undefined
+        ? { preferredModelId }
+        : undefined;
     if (!registry) {
-        return loadEffectiveGSDPreferences(basePath);
+        return loadEffectiveGSDPreferences(basePath, preferenceOpts);
     }
     const disabledProviders = resolveDisabledModelProvidersFromPreferences();
     const availableModelIds = modelIdsForProfileResolution(registry, anchorProvider, disabledProviders);
     if (!availableModelIds) {
-        return loadEffectiveGSDPreferences(basePath);
+        return loadEffectiveGSDPreferences(basePath, preferenceOpts);
     }
-    return loadEffectiveGSDPreferences(basePath, { availableModelIds });
+    return loadEffectiveGSDPreferences(basePath, { availableModelIds, preferredModelId });
 }
 /**
  * Normalize a value loaded from disk (or passed from another component) into
@@ -165,27 +168,72 @@ export function normalizePreferencesShape(loaded) {
     return { ...candidate };
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
-export function loadGlobalGSDPreferences() {
-    return loadFirstUsablePreferencesFile([
+const EFFECTIVE_PREFERENCES_CACHE_MAX = 64;
+const effectivePreferencesCache = new Map();
+export function clearGSDPreferencesCache() {
+    effectivePreferencesCache.clear();
+}
+function globalPreferencesCandidatePaths() {
+    return [
         globalPreferencesPath(),
         legacyGlobalPreferencesPathLowercase(),
         legacyGlobalPreferencesPath(),
-    ], "global");
+    ];
 }
-export function loadProjectGSDPreferences(basePath) {
-    return loadFirstUsablePreferencesFile([
+function projectPreferencesCandidatePaths(basePath) {
+    return [
         projectPreferencesPath(basePath),
         legacyProjectPreferencesPathLowercase(basePath),
-    ], "project");
+    ];
+}
+function preferencesFileSignature(path) {
+    try {
+        const stats = statSync(path);
+        return `${path}:${stats.size}:${stats.mtimeMs}`;
+    }
+    catch (err) {
+        const code = err.code ?? "unknown";
+        return `${path}:missing:${code}`;
+    }
+}
+function effectivePreferencesCacheKey(basePath, opts) {
+    return JSON.stringify({
+        basePath: basePath ?? null,
+        global: globalPreferencesCandidatePaths().map(preferencesFileSignature),
+        project: projectPreferencesCandidatePaths(basePath).map(preferencesFileSignature),
+        availableModelIds: opts?.availableModelIds ?? null,
+        preferredModelId: opts?.preferredModelId ?? null,
+    });
+}
+function cloneLoadedPreferences(loaded) {
+    return loaded ? structuredClone(loaded) : null;
+}
+function cacheEffectivePreferences(key, loaded) {
+    if (!effectivePreferencesCache.has(key) && effectivePreferencesCache.size >= EFFECTIVE_PREFERENCES_CACHE_MAX) {
+        effectivePreferencesCache.clear();
+    }
+    effectivePreferencesCache.set(key, cloneLoadedPreferences(loaded));
+}
+export function loadGlobalGSDPreferences() {
+    return loadFirstUsablePreferencesFile(globalPreferencesCandidatePaths(), "global");
+}
+export function loadProjectGSDPreferences(basePath) {
+    return loadFirstUsablePreferencesFile(projectPreferencesCandidatePaths(basePath), "project");
 }
 export function loadEffectiveGSDPreferences(basePath, opts) {
+    const cacheKey = effectivePreferencesCacheKey(basePath, opts);
+    if (effectivePreferencesCache.has(cacheKey)) {
+        return cloneLoadedPreferences(effectivePreferencesCache.get(cacheKey));
+    }
     const globalPreferences = loadGlobalGSDPreferences();
     const projectPreferences = loadProjectGSDPreferences(basePath);
     const effectiveGlobalPreferences = globalPreferences?.ignored ? null : globalPreferences;
     const effectiveProjectPreferences = projectPreferences?.ignored ? null : projectPreferences;
     const projectHasPlanningDepth = effectiveProjectPreferences?.preferences.planning_depth !== undefined;
-    if (!effectiveGlobalPreferences && !effectiveProjectPreferences)
+    if (!effectiveGlobalPreferences && !effectiveProjectPreferences) {
+        cacheEffectivePreferences(cacheKey, null);
         return null;
+    }
     let result;
     if (!effectiveGlobalPreferences) {
         result = effectiveProjectPreferences;
@@ -217,7 +265,7 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
         profileForDefaults = DEFAULT_TOKEN_PROFILE;
     }
     if (profileForDefaults) {
-        const profileDefaults = _resolveProfileDefaults(profileForDefaults, opts?.availableModelIds, result.preferences.dynamic_routing);
+        const profileDefaults = _resolveProfileDefaults(profileForDefaults, opts?.availableModelIds, result.preferences.dynamic_routing, opts?.preferredModelId);
         const defaultsToApply = explicitProfile
             ? profileDefaults
             : withoutProfilePhaseDefaults(profileDefaults);
@@ -234,6 +282,7 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
         };
     }
     result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
+    cacheEffectivePreferences(cacheKey, result);
     return result;
 }
 function withoutProfilePhaseDefaults(defaults) {

package/dist/resources/extensions/gsd/prompts/ai-integration-phase.md

@@ -0,0 +1,28 @@
+You are running the GSD **ai-integration-phase** workflow — produce an AI design contract (AI-SPEC) for a milestone/slice that builds an AI system.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice goal and requirements for the AI capability.
+
+2. **Define the AI capability contract:**
+   - **Inputs:** what the model receives (schema, context, examples) and any preprocessing.
+   - **Outputs:** the expected response shape, how it's parsed/validated, and how failures are handled.
+   - **Model & parameters:** which model/provider, temperature, max tokens, fallback chain — never hardcode; reference config.
+   - **Prompt/contract:** the system/user prompt strategy, or tool/function calling schema.
+   - **Evaluation:** how quality is measured (eval set, rubric, human-in-the-loop checkpoints).
+   - **Cost & latency budget:** expected per-call cost and latency, and the ceiling that triggers a redesign.
+
+3. **Risk register.** Hallucination/grounding, prompt injection, data leakage, cost runaway, model deprecation. For each, the mitigation.
+
+4. **Write the AI-SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd plan-phase` or `/gsd spike` for high-uncertainty model behaviors.
+
+## Success criteria
+
+- Inputs/outputs are schema-defined, not prose-only.
+- Evaluation is concrete (eval set + rubric), not "it looks good".
+- Cost/latency has a budget and a ceiling.
+- The risk register covers the standard AI failure modes.

package/dist/resources/extensions/gsd/prompts/audit-fix.md

@@ -0,0 +1,39 @@
+You are running the GSD **audit-fix** workflow — autonomous audit-to-fix pipeline: find issues, classify them, fix the auto-fixable ones, test after each fix, and commit atomically.
+
+## Source
+
+{{source}}
+
+## Severity filter
+
+{{severity}}
+
+## Max fixes
+
+{{maxFixes}}
+
+## Dry run
+
+{{dryRun}}
+
+## Process
+
+1. **Run the audit.** Use the named source audit (default: the most recent audit-uat / scan findings). If no audit exists, run a fresh `/gsd scan --focus concerns` first and use those findings.
+
+2. **Parse and classify findings.** For each finding, decide: `auto-fixable` (deterministic, localized, no public-behavior change) or `manual-only` (ambiguous, risky, or behavior-changing). Apply the severity filter and the `--max` cap.
+
+3. **Fix loop** (skip entirely if `--dry-run`). For each auto-fixable finding, in priority order:
+   - Apply the fix.
+   - Run the project's tests.
+   - If tests pass, stage the change and record the finding id.
+   - If tests fail, revert that fix, mark it manual-only, and continue.
+   Commit atomically, referencing the finding ids in the commit message for traceability.
+
+4. **Report.** List: fixed (with finding ids + commits), deferred to manual (with reasons), and any that were attempted but reverted due to test failure.
+
+## Success criteria
+
+- Every fix is tested before it's kept; failing fixes are reverted, not left half-applied.
+- Commits are atomic and reference finding ids.
+- `--dry-run` shows what would be fixed without changing anything.
+- Manual-only findings are reported, not silently ignored.

package/dist/resources/extensions/gsd/prompts/audit-milestone.md

@@ -0,0 +1,26 @@
+You are running the GSD **audit-milestone** workflow — verify a milestone achieved its definition of done before it is archived.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load the milestone.** Read the milestone's ROADMAP entry, its slices' plans and SUMMARY/ASSESSMENT artifacts, and the requirements/acceptance criteria. If a specific milestone id was given, target it; otherwise target the active or most-recently-completed milestone.
+
+2. **Aggregate per-slice verification.** For each slice, confirm its tasks were completed and its verification strategy was satisfied (tests pass, UAT recorded). Flag slices with incomplete verification.
+
+3. **Check requirements coverage.** Map each requirement/acceptance criterion to the slice(s) and tasks that delivered it. Flag any requirement with no covering evidence.
+
+4. **Check cross-slice integration.** Identify slices that touch shared resources (APIs, data models, state) and confirm their integration points are consistent — no broken handoffs, conflicting schemas, or sequencing gaps.
+
+5. **Aggregate debt and deferred items.** Collect tech debt, deferred tasks, and known gaps into a single list with severity and owner-hint.
+
+6. **Produce the verdict.** Report: `PASS` (done-of-definition met), `NEEDS-ATTENTION` (gaps that need a human call), or `NEEDS-REMEDIATION` (gaps that block archival). Recommend the matching gsd-pi next step (`/gsd verdict`, `/gsd dispatch validate`, or scheduling remediation).
+
+## Success criteria
+
+- Every requirement is mapped to covering evidence or flagged as uncovered.
+- Cross-slice integration risks are explicit, not assumed away.
+- The verdict is one of the three canonical values with supporting evidence.
+- Debt/deferred items are listed, not silently dropped.

package/dist/resources/extensions/gsd/prompts/audit-uat.md

@@ -0,0 +1,24 @@
+You are running the GSD **audit-uat** workflow — cross-milestone audit of all outstanding UAT and verification items.
+
+## Verify mode
+
+{{verifyMode}}
+
+## Process
+
+1. **Find every outstanding verification item.** Scan all milestones and slices for items in a non-passing state: pending, skipped, blocked, human_needed. Read the slice SUMMARY/ASSESSMENT artifacts and any UAT records.
+
+2. **Classify each item.** For each outstanding item, record: milestone/slice id, the item, its current state, and why it's outstanding (skipped intentionally, blocked by a dependency, awaiting a human, stale).
+
+3. **Verify against the codebase** (only when `--verify` is set): for each item, check whether the code now satisfies it — turning stale "pending" items into pass/fail based on current evidence. Do not modify code; only re-evaluate.
+
+4. **Produce a prioritized test plan.** Order the genuinely-outstanding items into a human test plan: blockers first, then high-risk, then the rest. Each entry has a clear test step and expected result.
+
+5. **Summarize.** Report counts by state, the count turned pass/fail by verification, and the prioritized plan.
+
+## Success criteria
+
+- Every outstanding verification item is listed with its milestone/slice and reason.
+- Stale items are detected (and, in verify mode, re-evaluated against the code).
+- The test plan is prioritized by risk, not alphabetical.
+- No item is silently dropped or assumed resolved.

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

@@ -0,0 +1,31 @@
+You are running the GSD **autonomous** workflow — run all remaining work on a milestone/slice continuously: discuss → plan → execute per slice, then validate, with minimal human intervention.
+
+## Scope
+
+{{scope}}
+
+## Flags
+
+- `--interactive` — {{interactiveFlag}} (pause for confirmation at key boundaries)
+- `--converge` — {{convergeFlag}} (re-run review cycles until concerns resolve before advancing)
+
+## Process
+
+This workflow is the gsd-pi equivalent of `/gsd auto` with explicit phase-ceremony. It drives the milestone through its lifecycle:
+
+1. **For each pending slice**, in order: discuss (if not done) → plan (if not done) → execute (all tasks) → complete slice.
+2. **Between slices**, honor the closeout boundary stop rule: stop after a slice closeout and leave the closeout surface visible, unless the user opted out of pause-at-boundary.
+3. **`--converge`:** before advancing, run a plan-review-convergence pass on the slice; only advance when concerns resolve.
+4. **`--interactive`:** confirm before each slice's discuss→plan→execute transitions.
+5. **At milestone completion,** run validation (`/gsd dispatch validate`) rather than auto-closing.
+
+Prefer delegating each lifecycle step to gsd-pi's native dispatch (`/gsd dispatch discuss|plan|execute`, `/gsd next`, `/gsd auto`) rather than reimplementing the unit machinery.
+
+Never barrel past a closeout boundary silently; never mark a milestone complete without validation.
+
+## Success criteria
+
+- The milestone advances through its lifecycle in the correct order.
+- Closeout boundaries are respected (stop and surface, don't barrel).
+- `--converge` actually gates advancement on resolved concerns.
+- Milestone completion goes through validation, not auto-close.

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

@@ -0,0 +1,39 @@
+You are running the GSD **code-review** workflow — review source files changed during recent work for bugs, security issues, and code quality problems.
+
+## Scope
+
+{{scope}}
+
+## Depth
+
+{{depth}}
+
+## Fix mode
+
+{{fixMode}}
+
+## Process
+
+1. **Determine the file set.** Use the explicit `--files` list if provided. Otherwise derive the changed source files from the active slice's recent commits / SUMMARY, or fall back to the git diff against the base branch. Exclude `.gsd/`, lockfiles, generated/vendored code, and docs unless `--files` names them.
+
+2. **Gather diff-first context.** Run `git diff` for the file set (or the relevant commit range) and use that as the primary review evidence. Use `read` only when the diff is insufficient — new/untracked files, truncated hunks, or missing surrounding context needed for a finding. Do **not** read every changed file when the diff already covers the edits. If the Tool Call Loop Guard blocks a tool, stop calling tools for the rest of this turn and continue in text.
+
+3. **Review at the requested depth:**
+   - **quick** — bugs, security, and correctness only.
+   - **standard** (default) — quick + maintainability, error handling, edge cases.
+   - **deep** — standard + performance, concurrency, API design, test coverage gaps.
+
+   Ground every finding in the actual code with file path + line reference. Categorize each by severity (critical / warning / nit) and type (bug, security, quality, performance).
+
+4. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
+
+5. **Present results.** Summarize counts by severity and list the critical findings first.
+
+6. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
+
+## Success criteria
+
+- Every finding cites a concrete file path and line.
+- Findings are categorized by severity and type.
+- The review is written to `.gsd/reviews/`.
+- Fixes only touch safely-auto-fixable findings, and tests run after each batch.

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -6,7 +6,7 @@ You are executing GSD auto-mode.
 
 Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
 
-If any inlined plan, summary, verification command, or prior artifact names an absolute path outside `{{workingDirectory}}`, treat that path as stale context. Convert it to the equivalent relative path under `{{workingDirectory}}` before reading, writing, or executing. If no equivalent path exists under `{{workingDirectory}}`, record a verification failure and stop; do not edit or run commands in another checkout.
+If inlined context names an absolute path outside `{{workingDirectory}}`, treat it as stale. Convert to the relative path under `{{workingDirectory}}` before use. If none exists, record a verification failure and stop; do not edit or run commands in another checkout.
 
 ## Your Role in the Pipeline
 
@@ -14,13 +14,13 @@ You are the closer: verify assembled task work delivers the slice goal, then com
 
 ### Closeout messaging (auto-mode)
 
-You write closeout artifacts; **GSD auto-mode** decides when the slice is actually **done**. Never say "Slice {{sliceId}} complete" in this unit — not even after `gsd_slice_complete` succeeds. GSD announces completion only after post-unit verification passes.
+You write closeout artifacts; **GSD auto-mode** decides when the slice is actually **done**. Never say "Slice {{sliceId}} complete" in this unit. GSD announces completion only after post-unit verification passes.
 
 {{inlinedContext}}
 
 {{gatesToClose}}
 
-Match effort to complexity. Simple slices need brief summary and light verification; multi-subsystem slices need stronger verification and detail.
+Match complexity: simple slices need brief summary/light verification; multi-subsystem slices need stronger verification/detail.
 
 Use `subagent` only when useful: reviewer, security, or tester. Apply findings before completion.
 
@@ -28,29 +28,34 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. See the prepended **Tool Surface** block for unavailable tools.
-4. Complete only when every required check passes. If verification fails or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
+3. Run slice-level verification only through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. Tool availability is in **Tool Surface**.
+4. Complete only after every required check passes. Exactly one terminal workflow tool is required: pass -> `gsd_slice_complete`; task follow-up -> `gsd_task_reopen`; planning follow-up -> `gsd_replan_slice`. A text-only stop, even one mentioning a tool, is invalid. If checks fail or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
 5. If verification fails:
-   - Task-specific regressions: if the failure is in files the task touched and pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with that task and reason.
-   - Inherited/out-of-scope failures, including failures present before the task ran or failures without pre-task evidence: do **not** reopen completed tasks; call `gsd_replan_slice` with adjusted verification scope or follow-up tasks.
-   - Other plan-invalidating failures: call `gsd_replan_slice` with the blocker and updated execution tasks.
-   Then stop with: "Slice {{sliceId}} needs execution follow-up."
+   - Task-specific regression: if pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with task and reason.
+   - Inherited/out-of-scope failure, including failures present before the task ran or no pre-task evidence: do **not** reopen tasks; call `gsd_replan_slice`.
+   - Other plan-invalidating failure: call `gsd_replan_slice` with blocker and updated tasks.
+   After any successful failure-handoff tool call, the unit is done. The `gsd_task_reopen` or `gsd_replan_slice` call is the handoff signal for the orchestrator.
+   - Never call `gsd_replan_slice` after calling `gsd_task_reopen`; reopened tasks are pending.
+   - Do not call `gsd_plan_slice`; that tool belongs to `plan-slice` and is hard-blocked here.
+   - Do not read source code, run `gsd_exec`, invoke subagents, or do implementation/planning work after the first `gsd_task_reopen` or `gsd_replan_slice` handoff call.
+   - Terminal reopen sequence: call `gsd_task_reopen`; after success, final text may only be: "Slice {{sliceId}} needs execution follow-up."
+   - Terminal replan sequence: call `gsd_replan_slice` once; after it succeeds, final text may only be: "Slice {{sliceId}} needs execution follow-up."
 6. Task summaries use a flat file layout under `tasks/` such as `T01-SUMMARY.md`, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. Never use `tasks/*/SUMMARY.md`.
 7. If observability/diagnostics were planned, verify them unless the slice is simple.
 8. Address every Gate to Close. Q8 = **Operational Readiness**: health signal, failure signal, recovery, monitoring gaps. Omit empty sections.
 9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
-10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
-11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare the type as a bullet under a `## UAT Type` heading, exactly like `- UAT mode: browser-executable`.
+10. Prepare `gsd_slice_complete` camelCase fields: `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, `uatContent`.
+11. Draft concrete UAT: preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare type under `## UAT Type` exactly like `- UAT mode: browser-executable`.
     **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
-12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `gsd_capture_thought` (MCP-scoped `mcp__...__gsd_capture_thought`), not bare `capture_thought`; do not append knowledge files.
+12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions/gotchas. Read full `*-SUMMARY.md` only if needed. Capture with MCP-scoped `gsd_capture_thought`, not bare `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
 14. Do not run git commands.
-15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
+15. If project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and full updated project markdown as `content`; omit `milestone_id`. Do not edit `.gsd/PROJECT.md` directly.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 
-**File system safety:** if re-reading task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
+**File system safety:** to re-read task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
 
-**You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
+**You MUST call `gsd_slice_complete` after verification passes. If not, MUST call `gsd_task_reopen` or `gsd_replan_slice`. Never finish this unit with plain text only.**
 
-When done, say: "Slice {{sliceId}} closeout submitted." Do not say the slice is complete. Say this exactly once — if you already said it in a prior message, do not repeat it.
+When done, say exactly once: "Slice {{sliceId}} closeout submitted." Do not say the slice is complete.

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

@@ -0,0 +1,31 @@
+You are running the GSD **discuss-phase** workflow — gather context for upcoming work through adaptive questioning before planning.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--auto` — {{autoFlag}} (when ON, infer answers from existing artifacts without asking)
+- `--text` — {{textFlag}} (when ON, use plain-text questions instead of interactive prompts)
+
+## Process
+
+1. **Load context.** Read the target milestone's ROADMAP entry, CONTEXT, RESEARCH, prior SUMMARYs, and the Decisions Register. This preloaded context is authoritative — do not re-read these files; reference them.
+
+2. **Take a codebase snapshot.** A bounded sample of current code reality (≤5 source files, ≤8KB each) to ground questions. Read a specific file only when a question's answer hinges on it.
+
+3. **Ask grounded questions, one at a time.** Questions must be grounded in the preloaded context + snapshot — never an open-ended survey of the codebase before the first round. Probe: scope boundaries, success criteria, risks, unknowns, integration points.
+
+4. **`--auto` mode:** infer answers from the artifacts rather than asking, and record the inferences as assumptions to be confirmed later.
+
+5. **Record outcomes.** When the discussion settles, capture: decisions (to the Decisions Register via `/gsd knowledge rule` where durable), refined scope (to the milestone CONTEXT), open questions (to RESEARCH or `/gsd dispatch research`), and assumptions. Mark the milestone/slice as "Discussion Complete, Planning Pending".
+
+6. **Route.** Recommend the next step: `/gsd dispatch plan` to plan the milestone/slice, or `/gsd dispatch research` if open questions dominate.
+
+## Success criteria
+
+- Questions are grounded and asked one at a time — no upfront survey.
+- The preloaded context is treated as authoritative (not re-read).
+- Outcomes land in the right gsd-pi artifacts.
+- The recommended next step matches where the milestone now sits.

package/dist/resources/extensions/gsd/prompts/docs-update.md

@@ -0,0 +1,13 @@
+You are running the GSD **docs-update** workflow — generate, update, and verify project documentation against the live codebase.
+
+## Mode
+
+{{mode}}
+
+## Process
+
+{{process}}
+
+## Success criteria
+
+{{successCriteria}}

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

@@ -0,0 +1,33 @@
+You are running the GSD **execute-phase** workflow — execute all tasks in a milestone/slice with wave-based parallelization.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--wave N` — {{waveFlag}} (max parallel tasks per wave)
+- `--gaps-only` — {{gapsOnlyFlag}} (only execute tasks whose verification is incomplete)
+- `--interactive` — {{interactiveFlag}} (confirm each wave)
+- `--tdd` — {{tddFlag}}
+
+## Process
+
+1. **Load the plan.** Read the milestone/slice plan and task list. Determine task dependencies and group independent tasks into waves.
+
+2. **Execute wave-by-wave.** Within a wave, independent tasks can run in parallel (bounded by `--wave`). Each task: implement → run its verification → record outcome. `--gaps-only` restricts to tasks with incomplete verification.
+
+3. **Per-task guarantees.** Each completed task gets an atomic commit and an updated SUMMARY. Failing verification blocks that task's completion (do not mark it done).
+
+4. **Between waves**, confirm if `--interactive`, then proceed to the next wave respecting dependencies.
+
+5. **Honor closeout boundaries.** Stop after the first task/slice/milestone closeout boundary and leave the final closeout surface visible — do not barrel through multiple closeouts.
+
+Prefer delegating single-task execution to gsd-pi's execute machinery (`/gsd next`, `/gsd dispatch execute`) where it fits.
+
+## Success criteria
+
+- Every task attempted is either completed (verified + committed) or left blocked with a clear reason.
+- Wave parallelism respects task dependencies.
+- Closeout boundaries are honored (stop, don't barrel).
+- Atomic commits per task; SUMMARY updated per task.

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

@@ -0,0 +1,58 @@
+You are running the GSD **explore** workflow — Socratic ideation that helps the developer think an idea through before committing to plans or milestones.
+
+## Idea
+
+{{topic}}
+
+## Process
+
+### Step 1 — Open the conversation
+
+If a topic was provided, acknowledge it and begin exploring. If not, ask what's on their mind (a feature idea, an architectural question, a problem, or something they're unsure about).
+
+### Step 2 — Socratic conversation (2–5 exchanges)
+
+- Ask **one question at a time** — never a list.
+- Probe: constraints, tradeoffs, users, scope, dependencies, risks.
+- Listen for "or" / "versus" / "tradeoff" signals — competing priorities worth exploring.
+- Reflect back what you hear to confirm understanding before moving on.
+- Follow the developer's energy — go deeper where they're engaged. Natural, not formulaic.
+
+### Step 3 — Mid-conversation research offer (after 2–3 exchanges)
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns that research could resolve, offer a quick research pass. If the developer accepts, dispatch the project's research tooling. Skip entirely if the topic doesn't warrant it — never force it.
+
+### Step 4 — Crystallize outputs (after 3–6 exchanges)
+
+When the conversation reaches natural conclusions (or the developer signals readiness), analyze what was discussed and propose **up to 4 outputs** from:
+
+| Type | Destination (gsd-pi) | When to suggest |
+|------|----------------------|-----------------|
+| Capture | `.gsd/CAPTURES.md` (append) | Observations, context, decisions worth remembering |
+| Backlog item | `/gsd backlog add` | Forward-looking ideas not ready for a milestone |
+| Knowledge | `/gsd knowledge lesson` | A lesson learned worth persisting |
+| Research | `/gsd dispatch research` | Open questions needing deeper investigation |
+| Requirement | `.gsd/CONTEXT.md` (append under "Domain glossary") | Clear requirements that emerged |
+| New milestone | `/gsd new-milestone` | Scope large enough to warrant its own milestone |
+| Spike | `/gsd spike` | Feasibility uncertainty surfaced ("will this API work?") |
+| Sketch | `/gsd brief diagram` | Design direction unclear ("what should this look like?") |
+
+Present the suggestions and ask the developer to pick, modify, or skip.
+
+**Never write artifacts without explicit user selection.**
+
+### Step 5 — Write selected outputs
+
+For each selected output, use the matching gsd-pi command or write to the destination listed above. Prefer invoking the gsd-pi command (e.g. `/gsd backlog add`, `/gsd knowledge lesson`) so state stays canonical.
+
+### Step 6 — Close
+
+Summarize the topic, list the artifacts created, and suggest next steps (`/gsd explore` again, or `/gsd status` to see where to apply the work).
+
+## Success criteria
+
+- Questions asked one at a time, not in batches.
+- Research offered contextually, not forced.
+- Up to 4 outputs proposed, grounded in the actual conversation.
+- User explicitly selects which outputs to create before anything is written.
+- Artifacts go to the gsd-pi destinations above.