@tuan_son.dinh/gsd 2.6.3 → 2.7.0

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

@@ -14,13 +14,14 @@ import type {
   ExtensionAPI,
   ExtensionContext,
   ExtensionCommandContext,
-} from "@mariozechner/pi-coding-agent";
+} from "@gsd/pi-coding-agent";
 
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
+import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { loadPrompt } from "./prompt-loader.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -39,7 +40,7 @@ import {
   readUnitRuntimeRecord,
   writeUnitRuntimeRecord,
 } from "./unit-runtime.js";
-import { resolveAutoSupervisorConfig, resolveModelForUnit, resolveSkillDiscoveryMode, loadEffectiveGSDPreferences, resolveWorkflowConfig } from "./preferences.js";
+import { resolveAutoSupervisorConfig, resolveModelForUnit, resolveModelWithFallbacksForUnit, resolveSkillDiscoveryMode, loadEffectiveGSDPreferences, resolveWorkflowConfig } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
 import {
   validatePlanBoundary,
@@ -68,7 +69,7 @@ import {
 } from "./worktree.ts";
 import { GitServiceImpl } from "./git-service.ts";
 import type { GitPreferences } from "./git-service.ts";
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
 import { showNextAction } from "../shared/next-action-ui.js";
 
@@ -474,6 +475,24 @@ export async function startAuto(
     : "Will loop until milestone complete.";
   ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
+  // Secrets collection gate — collect pending secrets before first dispatch
+  const mid = state.activeMilestone.id;
+  try {
+    const manifestStatus = await getManifestStatus(base, mid);
+    if (manifestStatus && manifestStatus.pending.length > 0) {
+      const result = await collectSecretsFromManifest(base, mid, ctx);
+      ctx.ui.notify(
+        `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
+        "info",
+      );
+    }
+  } catch (err) {
+    ctx.ui.notify(
+      `Secrets collection error: ${err instanceof Error ? err.message : String(err)}`,
+      "warning",
+    );
+  }
+
   // Self-heal: clear stale runtime records where artifacts already exist
   await selfHealRuntimeRecords(base, ctx);
 
@@ -507,14 +526,15 @@ export async function handleAgentEnd(
     }
 
     // Post-hook: fix mechanical bookkeeping the LLM may have skipped.
-    // 1. Doctor handles: checkbox marking, stub summaries/UATs.
+    // 1. Doctor handles: checkbox marking (task-level bookkeeping).
     // 2. STATE.md is always rebuilt from disk state (purely derived, no LLM needed).
-    // This is more reliable than prompt instructions for mechanical tasks.
-    // Scope to slice level (M001/S01) so doctor checks all tasks within the slice.
+    // fixLevel:"task" ensures doctor only fixes task-level issues (e.g. marking
+    // checkboxes). Slice/milestone completion transitions (summary stubs,
+    // roadmap [x] marking) are left for the complete-slice dispatch unit.
     try {
       const scopeParts = currentUnit.id.split("/").slice(0, 2);
       const doctorScope = scopeParts.join("/");
-      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope });
+      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope, fixLevel: "task" });
       if (report.fixesApplied.length > 0) {
         ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
       }
@@ -1023,14 +1043,35 @@ async function dispatchNextUnit(
             midTitle = state.activeMilestone?.title;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+
+            // Safety net: if mergeSliceToMain failed to clean up (or the error
+            // came from switchToMain), ensure the working tree isn't left in a
+            // conflicted/dirty merge state. Without this, state derivation reads
+            // conflict-marker-filled files, produces a corrupt phase, and
+            // dispatch loops forever (see: merge-bug-fix).
+            try {
+              const { runGit } = await import("./git-service.ts");
+              const status = runGit(basePath, ["status", "--porcelain"], { allowFailure: true });
+              if (status && (status.includes("UU ") || status.includes("AA ") || status.includes("UD "))) {
+                runGit(basePath, ["reset", "--hard", "HEAD"], { allowFailure: true });
+                ctx.ui.notify(
+                  `Cleaned up conflicted merge state after failed squash-merge.`,
+                  "warning",
+                );
+              }
+            } catch { /* best-effort cleanup */ }
+
             ctx.ui.notify(
-              `Slice merge failed: ${message}`,
+              `Slice merge failed — stopping auto-mode. Fix conflicts manually and restart.\n${message}`,
               "error",
             );
-            // Re-derive state so dispatch can figure out what to do
-            state = await deriveState(basePath);
-            mid = state.activeMilestone?.id;
-            midTitle = state.activeMilestone?.title;
+            if (currentUnit) {
+              const modelId = ctx.model?.id ?? "unknown";
+              snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+              saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
+            }
+            await stopAuto(ctx, pi);
+            return;
           }
         }
       }
@@ -1327,29 +1368,70 @@ async function dispatchNextUnit(
 
   // On crash recovery, prepend the full recovery briefing
   // On retry (stuck detection), prepend deep diagnostic from last attempt
+  // Cap injected content to prevent unbounded prompt growth → OOM
+  const MAX_RECOVERY_CHARS = 50_000;
   let finalPrompt = prompt;
   if (pendingCrashRecovery) {
-    finalPrompt = `${pendingCrashRecovery}\n\n---\n\n${finalPrompt}`;
+    const capped = pendingCrashRecovery.length > MAX_RECOVERY_CHARS
+      ? pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
+      : pendingCrashRecovery;
+    finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
     pendingCrashRecovery = null;
   } else if ((unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
     const diagnostic = getDeepDiagnostic(basePath);
     if (diagnostic) {
-      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${diagnostic}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
+      const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
+        ? diagnostic.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...diagnostic truncated to prevent memory exhaustion]"
+        : diagnostic;
+      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
     }
   }
 
   // Switch model if preferences specify one for this unit type
-  const preferredModelId = resolveModelForUnit(unitType);
-  if (preferredModelId) {
-    // Try to find the model across all providers
+  // Try primary model, then fallbacks in order if setting fails
+  const modelConfig = resolveModelWithFallbacksForUnit(unitType);
+  if (modelConfig) {
     const allModels = ctx.modelRegistry.getAll();
-    const model = allModels.find(m => m.id === preferredModelId);
-    if (model) {
+    const modelsToTry = [modelConfig.primary, ...modelConfig.fallbacks];
+    let modelSet = false;
+
+    for (const modelId of modelsToTry) {
+      const model = allModels.find(m => m.id === modelId);
+      if (!model) {
+        ctx.ui.notify(`Model ${modelId} not found in registry, trying fallback.`, "warning");
+        continue;
+      }
+
       const ok = await pi.setModel(model, { persist: false });
       if (ok) {
-        ctx.ui.notify(`Model: ${preferredModelId}`, "info");
+        const fallbackNote = modelId === modelConfig.primary
+          ? ""
+          : ` (fallback from ${modelConfig.primary})`;
+        ctx.ui.notify(`Model: ${modelId}${fallbackNote}`, "info");
+        modelSet = true;
+        break;
+      } else {
+        const nextModel = modelsToTry[modelsToTry.indexOf(modelId) + 1];
+        if (nextModel) {
+          ctx.ui.notify(
+            `Failed to set model ${modelId}, trying fallback ${nextModel}...`,
+            "warning",
+          );
+        } else {
+          ctx.ui.notify(
+            `Failed to set model ${modelId} and all fallbacks exhausted. Using default model.`,
+            "warning",
+          );
+        }
       }
     }
+
+    if (!modelSet) {
+      ctx.ui.notify(
+        `Could not set any preferred model for ${unitType}. Continuing with default.`,
+        "warning",
+      );
+    }
   }
 
   // Start progress-aware supervision: a soft warning, an idle watchdog, and
@@ -1628,6 +1710,8 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
   const outputRelPath = relMilestoneFile(base, mid, "ROADMAP");
   const outputAbsPath = resolveMilestoneFile(base, mid, "ROADMAP") ?? join(base, outputRelPath);
 
+  const secretsOutputPath = relMilestoneFile(base, mid, "SECRETS");
+
   const wf = resolveWorkflowConfig();
   const skipObservabilityNote = wf.skip_observability
     ? "\n\n> **Note:** Observability planning is disabled in preferences. Skip observability/diagnostics sections in slice plans."
@@ -1640,6 +1724,7 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
     researchPath: researchRel,
     outputPath: outputRelPath,
     outputAbsPath,
+    secretsOutputPath,
     inlinedContext,
     skipObservabilityNote,
   });

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

@@ -4,7 +4,7 @@
  * One command, one wizard. Routes to smart entry or status.
  */
 
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -201,7 +201,7 @@ async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
 }
 
 export async function fireStatusViaCommand(
-  ctx: import("@mariozechner/pi-coding-agent").ExtensionContext,
+  ctx: import("@gsd/pi-coding-agent").ExtensionContext,
 ): Promise<void> {
   await handleStatus(ctx as ExtensionCommandContext);
 }

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -6,8 +6,8 @@
  * Toggled with Ctrl+Alt+G or opened from /gsd status.
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth, visibleWidth, matchesKey, Key } from "@mariozechner/pi-tui";
+import type { Theme } from "@gsd/pi-coding-agent";
+import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { deriveState } from "./state.js";
 import { loadFile, parseRoadmap, parsePlan } from "./files.js";
 import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -27,7 +27,10 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md
 
 - `custom_instructions`: extra durable instructions related to skill use.
 
-- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `completion`. Values: model IDs (e.g. `claude-sonnet-4-6`, `claude-opus-4-6`). Omit a key to use whatever model is currently active.
+- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `completion`. Values can be:
+  - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks
+  - Object with fallbacks: `{ model: "claude-opus-4-6", fallbacks: ["glm-5", "minimax-m2.5"] }` — tries fallbacks in order if primary fails
+  - Omit a key to use whatever model is currently active. Fallbacks are tried when model switching fails (provider unavailable, rate limited, etc.).
 
 - `skill_discovery`: controls how GSD discovers and applies skills during auto-mode. Valid values:
   - `auto` — skills are found and applied automatically without prompting.
@@ -87,6 +90,47 @@ models:
 
 Opus for planning (where architectural decisions matter most), Sonnet for everything else (faster, cheaper). Omit any key to use the currently selected model.
 
+## Models with Fallbacks Example
+
+```yaml
+---
+version: 1
+models:
+  research:
+    model: openrouter/deepseek/deepseek-r1
+    fallbacks:
+      - openrouter/minimax/minimax-m2.5
+  planning:
+    model: claude-opus-4-6
+    fallbacks:
+      - openrouter/z-ai/glm-5
+      - openrouter/moonshotai/kimi-k2.5
+  execution:
+    model: openrouter/z-ai/glm-5
+    fallbacks:
+      - openrouter/minimax/minimax-m2.5
+  completion: openrouter/minimax/minimax-m2.5
+---
+```
+
+When a model fails to switch (provider unavailable, rate limited, credits exhausted), GSD automatically tries the next model in the `fallbacks` list. This ensures auto-mode continues even when your preferred provider hits limits.
+
+**Cost-optimized example** — use cheap models with expensive ones as fallback for critical phases:
+
+```yaml
+---
+version: 1
+models:
+  research: openrouter/deepseek/deepseek-r1  # $0.28/$0.42 per 1M tokens
+  planning:
+    model: claude-opus-4-6                   # $5/$25 — best for architecture
+    fallbacks:
+      - openrouter/z-ai/glm-5                # $1/$3.20 — strong alternative
+  execution: openrouter/minimax/minimax-m2.5 # $0.30/$1.20 — cheapest quality
+  completion: openrouter/minimax/minimax-m2.5
+---
+```
+
 ---
 
 ## Example Variations

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

@@ -422,10 +422,29 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   }).join("\n");
 }
 
-export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string }): Promise<DoctorReport> {
+export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all" }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
   const fix = options?.fix === true;
+  const fixLevel = options?.fixLevel ?? "all";
+
+  // Issue codes that represent completion state transitions — creating summary
+  // stubs, marking slices/milestones done in the roadmap. These belong to the
+  // dispatch lifecycle (complete-slice, complete-milestone units), not to
+  // mechanical post-hook bookkeeping. When fixLevel is "task", these are
+  // detected and reported but never auto-fixed.
+  const completionTransitionCodes = new Set<DoctorIssueCode>([
+    "all_tasks_done_missing_slice_summary",
+    "all_tasks_done_missing_slice_uat",
+    "all_tasks_done_roadmap_not_checked",
+  ]);
+
+  /** Whether a given issue code should be auto-fixed at the current fixLevel. */
+  const shouldFix = (code: DoctorIssueCode): boolean => {
+    if (!fix) return false;
+    if (fixLevel === "task" && completionTransitionCodes.has(code)) return false;
+    return true;
+  };
 
   const prefs = loadEffectiveGSDPreferences();
   if (prefs) {
@@ -606,7 +625,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relSliceFile(basePath, milestoneId, slice.id, "SUMMARY"),
           fixable: true,
         });
-        if (fix) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
+        if (shouldFix("all_tasks_done_missing_slice_summary")) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
       if (allTasksDone && !hasSliceUat) {
@@ -619,7 +638,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: `${relSlicePath(basePath, milestoneId, slice.id)}/${slice.id}-UAT.md`,
           fixable: true,
         });
-        if (fix) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
+        if (shouldFix("all_tasks_done_missing_slice_uat")) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
       if (allTasksDone && !slice.done) {
@@ -632,7 +651,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
           fixable: true,
         });
-        if (fix && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
+        if (shouldFix("all_tasks_done_roadmap_not_checked") && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
           await markSliceDoneInRoadmap(basePath, milestoneId, slice.id, fixesApplied);
         }
       }

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

@@ -4,7 +4,7 @@
 // Pure functions, zero Pi dependencies — uses only Node built-ins.
 
 import { promises as fs, readdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { milestonesDir, resolveMilestoneFile, relMilestoneFile } from './paths.js';
 
 import type {
@@ -13,8 +13,12 @@ import type {
   Summary, SummaryFrontmatter, SummaryRequires, FileModified,
   Continue, ContinueFrontmatter, ContinueStatus,
   RequirementCounts,
+  SecretsManifest, SecretsManifestEntry, SecretsManifestEntryStatus,
+  ManifestStatus,
 } from './types.ts';
 
+import { checkExistingEnvKeys } from '../get-secrets-from-user.ts';
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 /**
@@ -263,6 +267,75 @@ export function parseRoadmap(content: string): Roadmap {
   return { title, vision, successCriteria, slices, boundaryMap };
 }
 
+// ─── Secrets Manifest Parser ───────────────────────────────────────────────
+
+const VALID_STATUSES = new Set<SecretsManifestEntryStatus>(['pending', 'collected', 'skipped']);
+
+export function parseSecretsManifest(content: string): SecretsManifest {
+  const milestone = extractBoldField(content, 'Milestone') || '';
+  const generatedAt = extractBoldField(content, 'Generated') || '';
+
+  const h3Sections = extractAllSections(content, 3);
+  const entries: SecretsManifestEntry[] = [];
+
+  for (const [heading, sectionContent] of h3Sections) {
+    const key = heading.trim();
+    if (!key) continue;
+
+    const service = extractBoldField(sectionContent, 'Service') || '';
+    const dashboardUrl = extractBoldField(sectionContent, 'Dashboard') || '';
+    const formatHint = extractBoldField(sectionContent, 'Format hint') || '';
+    const rawStatus = (extractBoldField(sectionContent, 'Status') || 'pending').toLowerCase().trim() as SecretsManifestEntryStatus;
+    const status: SecretsManifestEntryStatus = VALID_STATUSES.has(rawStatus) ? rawStatus : 'pending';
+    const destination = extractBoldField(sectionContent, 'Destination') || 'dotenv';
+
+    // Extract numbered guidance list (lines matching "1. ...", "2. ...", etc.)
+    const guidance: string[] = [];
+    for (const line of sectionContent.split('\n')) {
+      const numMatch = line.match(/^\s*\d+\.\s+(.+)/);
+      if (numMatch) {
+        guidance.push(numMatch[1].trim());
+      }
+    }
+
+    entries.push({ key, service, dashboardUrl, guidance, formatHint, status, destination });
+  }
+
+  return { milestone, generatedAt, entries };
+}
+
+// ─── Secrets Manifest Formatter ───────────────────────────────────────────
+
+export function formatSecretsManifest(manifest: SecretsManifest): string {
+  const lines: string[] = [];
+
+  lines.push('# Secrets Manifest');
+  lines.push('');
+  lines.push(`**Milestone:** ${manifest.milestone}`);
+  lines.push(`**Generated:** ${manifest.generatedAt}`);
+
+  for (const entry of manifest.entries) {
+    lines.push('');
+    lines.push(`### ${entry.key}`);
+    lines.push('');
+    lines.push(`**Service:** ${entry.service}`);
+    if (entry.dashboardUrl) {
+      lines.push(`**Dashboard:** ${entry.dashboardUrl}`);
+    }
+    if (entry.formatHint) {
+      lines.push(`**Format hint:** ${entry.formatHint}`);
+    }
+    lines.push(`**Status:** ${entry.status}`);
+    lines.push(`**Destination:** ${entry.destination}`);
+    lines.push('');
+    for (let i = 0; i < entry.guidance.length; i++) {
+      lines.push(`${i + 1}. ${entry.guidance[i]}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
 // ─── Slice Plan Parser ─────────────────────────────────────────────────────
 
 export function parsePlan(content: string): SlicePlan {
@@ -730,3 +803,44 @@ export async function inlinePriorMilestoneSummary(mid: string, base: string): Pr
   if (!content) return null;
   return `### Prior Milestone Summary\nSource: \`${relPath}\`\n\n${content.trim()}`;
 }
+
+// ─── Manifest Status ──────────────────────────────────────────────────────
+
+/**
+ * Read a secrets manifest from disk and cross-reference each entry's status
+ * with the current environment (.env + process.env).
+ *
+ * Returns `null` when no manifest file exists (path resolution failure or
+ * file not on disk) — callers can distinguish "no manifest" from "empty manifest".
+ */
+export async function getManifestStatus(
+  base: string, milestoneId: string,
+): Promise<ManifestStatus | null> {
+  const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
+  if (!resolvedPath) return null;
+
+  const content = await loadFile(resolvedPath);
+  if (!content) return null;
+
+  const manifest = parseSecretsManifest(content);
+  const keys = manifest.entries.map(e => e.key);
+  const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
+  const existingSet = new Set(existingKeys);
+
+  const result: ManifestStatus = {
+    pending: [],
+    collected: [],
+    skipped: [],
+    existing: [],
+  };
+
+  for (const entry of manifest.entries) {
+    if (existingSet.has(entry.key)) {
+      result.existing.push(entry.key);
+    } else {
+      result[entry.status].push(entry.key);
+    }
+  }
+
+  return result;
+}