gsd-pi 2.63.0-dev.026d309 → 2.63.0-dev.786f0ff

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -6,9 +6,10 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
-import { loadPrompt } from "../prompt-loader.js";
+import { loadPrompt, getTemplatesDir } from "../prompt-loader.js";
 import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
+import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
@@ -20,6 +21,31 @@ import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.
 
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
+/**
+ * Bundled skill triggers — resolved dynamically at runtime instead of
+ * hardcoding absolute paths in the system prompt template. Only skills
+ * that actually exist on disk are included in the table. (#3575)
+ */
+const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> = [
+  { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
+  { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
+  { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+];
+
+function buildBundledSkillsTable(): string {
+  const cwd = process.cwd();
+  const rows: string[] = [];
+  for (const { trigger, skill } of BUNDLED_SKILL_TRIGGERS) {
+    const resolution = resolveSkillReference(skill, cwd);
+    if (resolution.method === "unresolved") continue; // skill not installed — omit from prompt
+    rows.push(`| ${trigger} | \`${resolution.resolvedPath}\` |`);
+  }
+  if (rows.length === 0) {
+    return "*No bundled skills found. Install skills to `~/.agents/skills/` or `~/.claude/skills/`.*";
+  }
+  return `| Trigger | Skill to load |\n|---|---|\n${rows.join("\n")}`;
+}
+
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
     join(gsdHome, "agent-instructions.md"),
@@ -43,7 +69,10 @@ export async function buildBeforeAgentStartResult(
   if (!existsSync(join(process.cwd(), ".gsd"))) return undefined;
 
   const stopContextTimer = debugTime("context-inject");
-  const systemContent = loadPrompt("system");
+  const systemContent = loadPrompt("system", {
+    bundledSkillsTable: buildBundledSkillsTable(),
+    templatesDir: getTemplatesDir(),
+  });
   const loadedPreferences = loadEffectiveGSDPreferences();
   if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
     markCmuxPromptShown();

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

@@ -43,21 +43,27 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined,
   );
 }
 
-export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+/** Parse doctor command args into structured flags and positionals (pure, no I/O). */
+export function parseDoctorArgs(args: string) {
   const trimmed = args.trim();
-  // Extract flags before positional parsing
   const jsonMode = trimmed.includes("--json");
   const dryRun = trimmed.includes("--dry-run");
+  const fixFlag = trimmed.includes("--fix");
   const includeBuild = trimmed.includes("--build");
   const includeTests = trimmed.includes("--test");
-  const stripped = trimmed.replace(/--json|--dry-run|--build|--test/g, "").trim();
+  const stripped = trimmed.replace(/--json|--dry-run|--build|--test|--fix/g, "").trim();
   const parts = stripped ? stripped.split(/\s+/) : [];
   const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor";
   const requestedScope = mode === "doctor" ? parts[0] : parts[1];
+  return { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope };
+}
+
+export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
   const report = await runGSDDoctor(projectRoot(), {
-    fix: mode === "fix" || mode === "heal" || dryRun,
+    fix: mode === "fix" || mode === "heal" || dryRun || fixFlag,
     dryRun,
     scope: effectiveScope,
     includeBuild,

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

@@ -19,3 +19,47 @@ export const DIR_CACHE_MAX = 200;
 
 /** Max parse-cache entries before eviction. */
 export const CACHE_MAX = 50;
+
+// ─── Tool Scoping ─────────────────────────────────────────────────────────────
+
+/**
+ * GSD tools allowed during discuss flows (#2949).
+ *
+ * xAI/Grok (and potentially other providers with grammar-based constrained
+ * decoding) return "Grammar is too complex" (HTTP 400) when the combined
+ * tool schemas exceed their internal grammar limit. The full GSD tool set
+ * registers ~33 tools with deeply nested schemas; discuss flows only need
+ * a small subset.
+ *
+ * By scoping tools to this allowlist during discuss dispatches, the grammar
+ * sent to the provider stays well under provider limits.
+ *
+ * Included tools and why:
+ *   - gsd_summary_save: writes CONTEXT.md artifacts (all discuss prompts)
+ *   - gsd_save_summary: alias for above
+ *   - gsd_decision_save: records decisions (discuss.md output phase)
+ *   - gsd_save_decision: alias for above
+ *   - gsd_plan_milestone: writes roadmap (discuss.md single/multi milestone)
+ *   - gsd_milestone_plan: alias for above
+ *   - gsd_milestone_generate_id: generates milestone IDs (discuss.md multi-milestone)
+ *   - gsd_generate_milestone_id: alias for above
+ *   - gsd_requirement_update: updates requirements during discuss
+ *   - gsd_update_requirement: alias for above
+ */
+export const DISCUSS_TOOLS_ALLOWLIST: readonly string[] = [
+  // Context / summary writing
+  "gsd_summary_save",
+  "gsd_save_summary",
+  // Decision recording
+  "gsd_decision_save",
+  "gsd_save_decision",
+  // Milestone planning (needed for discuss.md output phase)
+  "gsd_plan_milestone",
+  "gsd_milestone_plan",
+  // Milestone ID generation (multi-milestone flow)
+  "gsd_milestone_generate_id",
+  "gsd_generate_milestone_id",
+  // Requirement updates
+  "gsd_requirement_update",
+  "gsd_update_requirement",
+];

package/src/resources/extensions/gsd/db-writer.ts

@@ -469,6 +469,23 @@ export async function saveDecisionToDb(
       adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
       throw diskErr;
     }
+    // #2661: When a decision defers a slice, update the slice status in the DB
+    // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are
+    // in split-brain: the decision says "deferred" but the state still says
+    // "active", causing auto-mode to keep dispatching the deferred work.
+    try {
+      const sliceRef = extractDeferredSliceRef(fields);
+      if (sliceRef) {
+        db.updateSliceStatus(sliceRef.milestoneId, sliceRef.sliceId, 'deferred');
+      }
+    } catch (deferErr) {
+      // Non-fatal — log but don't fail the decision save
+      logError('manifest', 'failed to update deferred slice status', {
+        fn: 'saveDecisionToDb',
+        error: String((deferErr as Error).message),
+      });
+    }
+
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
     invalidateStateCache();
@@ -482,6 +499,39 @@ export async function saveDecisionToDb(
   }
 }
 
+/**
+ * Extract a milestone/slice reference from a deferral decision.
+ *
+ * Detects deferrals by checking:
+ *   - scope contains "defer" (e.g., "deferral", "defer")
+ *   - choice or decision contains "defer" + an M###/S## pattern
+ *
+ * Returns { milestoneId, sliceId } if found, null otherwise.
+ */
+export function extractDeferredSliceRef(
+  fields: Pick<SaveDecisionFields, 'scope' | 'decision' | 'choice'>,
+): { milestoneId: string; sliceId: string } | null {
+  const isDeferral =
+    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.scope) ||
+    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.choice) ||
+    /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.decision);
+
+  if (!isDeferral) return null;
+
+  // Look for M###/S## pattern in choice first, then decision
+  const slicePattern = /\b(M\d{3,4})\/(S\d{2,3})\b/;
+  const choiceMatch = fields.choice.match(slicePattern);
+  if (choiceMatch) {
+    return { milestoneId: choiceMatch[1], sliceId: choiceMatch[2] };
+  }
+  const decisionMatch = fields.decision.match(slicePattern);
+  if (decisionMatch) {
+    return { milestoneId: decisionMatch[1], sliceId: decisionMatch[2] };
+  }
+
+  return null;
+}
+
 // ─── Update Requirement in DB + Regenerate Markdown ───────────────────────
 
 /**
@@ -496,11 +546,35 @@ export async function updateRequirementInDb(
   try {
     const db = await import('./gsd-db.js');
 
-    const existing = db.getRequirementById(id);
+    let existing = db.getRequirementById(id);
+
+    // If requirement doesn't exist in DB, seed the entire requirements table
+    // from REQUIREMENTS.md first (#3346). This handles the standard workflow
+    // where requirements are authored in markdown during discussion but never
+    // imported into the database — making gsd_requirement_update always fail
+    // with "not_found" at milestone completion.
+    if (!existing) {
+      const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
+      try {
+        const content = readFileSync(reqFilePath, 'utf-8');
+        const { parseRequirementsSections } = await import('./md-importer.js');
+        const parsed = parseRequirementsSections(content);
+        if (parsed.length > 0) {
+          logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' });
+          for (const req of parsed) {
+            // Only seed if not already in DB (avoid overwriting concurrent inserts)
+            if (!db.getRequirementById(req.id)) {
+              db.upsertRequirement(req);
+            }
+          }
+          // Re-check after seeding
+          existing = db.getRequirementById(id);
+        }
+      } catch {
+        // REQUIREMENTS.md missing or unparseable — fall through to skeleton
+      }
+    }
 
-    // If requirement doesn't exist in DB, create a skeleton and merge updates.
-    // This handles the case where requirements were written to REQUIREMENTS.md
-    // but never imported into the database (see #2919).
     const base: Requirement = existing ?? {
       id,
       class: '',

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

@@ -38,7 +38,7 @@ import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./comm
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
-interface ForensicAnomaly {
+export interface ForensicAnomaly {
   type: "stuck-loop" | "cost-spike" | "timeout" | "missing-artifact" | "crash" | "doctor-issue" | "error-trace" | "journal-stuck" | "journal-guard-block" | "journal-rapid-iterations" | "journal-worktree-failure";
   severity: "info" | "warning" | "error";
   unitType?: string;
@@ -640,13 +640,29 @@ function getDbCompletionCounts(): DbCompletionCounts | null {
 
 // ─── Anomaly Detectors ───────────────────────────────────────────────────────
 
-function detectStuckLoops(units: UnitMetrics[], anomalies: ForensicAnomaly[]): void {
-  const counts = new Map<string, number>();
+/**
+ * Detect units that were dispatched multiple times (stuck in a loop).
+ *
+ * Counts distinct dispatches by grouping on (type, id, startedAt) first to
+ * collapse idle-watchdog duplicate snapshots (#1943), then counts unique
+ * startedAt values per type/id to determine actual dispatch count.
+ *
+ * Exported for testability.
+ */
+export function detectStuckLoops(units: UnitMetrics[], anomalies: ForensicAnomaly[]): void {
+  // First, collect unique startedAt values per type/id key
+  const dispatchMap = new Map<string, Set<number>>();
   for (const u of units) {
     const key = `${u.type}/${u.id}`;
-    counts.set(key, (counts.get(key) ?? 0) + 1);
+    let starts = dispatchMap.get(key);
+    if (!starts) {
+      starts = new Set();
+      dispatchMap.set(key, starts);
+    }
+    starts.add(u.startedAt);
   }
-  for (const [key, count] of counts) {
+  for (const [key, starts] of dispatchMap) {
+    const count = starts.size;
     if (count > 1) {
       const [unitType, ...idParts] = key.split("/");
       anomalies.push({

package/src/resources/extensions/gsd/gsd-db.ts

@@ -1136,11 +1136,12 @@ export function insertMilestone(m: {
   });
 }
 
-export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord>, title?: string): void {
+export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
   currentDb.prepare(
     `UPDATE milestones SET
-      title = COALESCE(:title, title),
+      title = COALESCE(NULLIF(:title, ''), title),
+      status = COALESCE(NULLIF(:status, ''), status),
       vision = COALESCE(:vision, vision),
       success_criteria = COALESCE(:success_criteria, success_criteria),
       key_risks = COALESCE(:key_risks, key_risks),
@@ -1155,7 +1156,8 @@ export function upsertMilestonePlanning(milestoneId: string, planning: Partial<M
      WHERE id = :id`,
   ).run({
     ":id": milestoneId,
-    ":title": title ?? null,
+    ":title": planning.title ?? "",
+    ":status": planning.status ?? "",
     ":vision": planning.vision ?? null,
     ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
     ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
@@ -1183,13 +1185,25 @@ export function insertSlice(s: {
 }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
   currentDb.prepare(
-    `INSERT OR IGNORE INTO slices (
+    `INSERT INTO slices (
       milestone_id, id, title, status, risk, depends, demo, created_at,
       goal, success_criteria, proof_level, integration_closure, observability_impact, sequence
     ) VALUES (
       :milestone_id, :id, :title, :status, :risk, :depends, :demo, :created_at,
       :goal, :success_criteria, :proof_level, :integration_closure, :observability_impact, :sequence
-    )`,
+    )
+    ON CONFLICT (milestone_id, id) DO UPDATE SET
+      title = CASE WHEN :raw_title IS NOT NULL THEN excluded.title ELSE slices.title END,
+      status = CASE WHEN slices.status IN ('complete', 'done') THEN slices.status ELSE excluded.status END,
+      risk = CASE WHEN :raw_risk IS NOT NULL THEN excluded.risk ELSE slices.risk END,
+      depends = excluded.depends,
+      demo = CASE WHEN :raw_demo IS NOT NULL THEN excluded.demo ELSE slices.demo END,
+      goal = CASE WHEN :raw_goal IS NOT NULL THEN excluded.goal ELSE slices.goal END,
+      success_criteria = CASE WHEN :raw_success_criteria IS NOT NULL THEN excluded.success_criteria ELSE slices.success_criteria END,
+      proof_level = CASE WHEN :raw_proof_level IS NOT NULL THEN excluded.proof_level ELSE slices.proof_level END,
+      integration_closure = CASE WHEN :raw_integration_closure IS NOT NULL THEN excluded.integration_closure ELSE slices.integration_closure END,
+      observability_impact = CASE WHEN :raw_observability_impact IS NOT NULL THEN excluded.observability_impact ELSE slices.observability_impact END,
+      sequence = CASE WHEN :raw_sequence IS NOT NULL THEN excluded.sequence ELSE slices.sequence END`,
   ).run({
     ":milestone_id": s.milestoneId,
     ":id": s.id,
@@ -1205,6 +1219,16 @@ export function insertSlice(s: {
     ":integration_closure": s.planning?.integrationClosure ?? "",
     ":observability_impact": s.planning?.observabilityImpact ?? "",
     ":sequence": s.sequence ?? 0,
+    // Raw sentinel params: NULL when caller omitted the field, used in ON CONFLICT guards
+    ":raw_title": s.title ?? null,
+    ":raw_risk": s.risk ?? null,
+    ":raw_demo": s.demo ?? null,
+    ":raw_goal": s.planning?.goal ?? null,
+    ":raw_success_criteria": s.planning?.successCriteria ?? null,
+    ":raw_proof_level": s.planning?.proofLevel ?? null,
+    ":raw_integration_closure": s.planning?.integrationClosure ?? null,
+    ":raw_observability_impact": s.planning?.observabilityImpact ?? null,
+    ":raw_sequence": s.sequence ?? null,
   });
 }
 
@@ -1884,20 +1908,32 @@ export function reconcileWorktreeDb(
           FROM wt.milestones
         `).run());
 
-        // Merge slices — preserve worktree progress (status, summaries, planning)
+        // Merge slices — preserve worktree progress but never downgrade completed status (#2558).
+        // Uses INSERT OR REPLACE with a subquery that picks the best status — if the main DB
+        // already has a completed slice, keep that status even if the worktree copy is stale.
         merged.slices = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO slices (
             milestone_id, id, title, status, risk, depends, demo, created_at, completed_at,
             full_summary_md, full_uat_md, goal, success_criteria, proof_level,
             integration_closure, observability_impact, sequence, replan_triggered_at
           )
-          SELECT milestone_id, id, title, status, risk, depends, demo, created_at, completed_at,
-                 full_summary_md, full_uat_md, goal, success_criteria, proof_level,
-                 integration_closure, observability_impact, sequence, replan_triggered_at
-          FROM wt.slices
+          SELECT w.milestone_id, w.id, w.title,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.status ELSE w.status
+                 END,
+                 w.risk, w.depends, w.demo, w.created_at,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.completed_at ELSE w.completed_at
+                 END,
+                 w.full_summary_md, w.full_uat_md, w.goal, w.success_criteria, w.proof_level,
+                 w.integration_closure, w.observability_impact, w.sequence, w.replan_triggered_at
+          FROM wt.slices w
+          LEFT JOIN slices m ON m.milestone_id = w.milestone_id AND m.id = w.id
         `).run());
 
-        // Merge tasks — preserve execution results, status, summaries
+        // Merge tasks — preserve execution results, never downgrade completed status (#2558)
         merged.tasks = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO tasks (
             milestone_id, slice_id, id, title, status, one_liner, narrative,
@@ -1906,12 +1942,23 @@ export function reconcileWorktreeDb(
             description, estimate, files, verify, inputs, expected_output,
             observability_impact, full_plan_md, sequence
           )
-          SELECT milestone_id, slice_id, id, title, status, one_liner, narrative,
-                 verification_result, duration, completed_at, blocker_discovered,
-                 deviations, known_issues, key_files, key_decisions, full_summary_md,
-                 description, estimate, files, verify, inputs, expected_output,
-                 observability_impact, full_plan_md, sequence
-          FROM wt.tasks
+          SELECT w.milestone_id, w.slice_id, w.id, w.title,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.status ELSE w.status
+                 END,
+                 w.one_liner, w.narrative,
+                 w.verification_result, w.duration,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.completed_at ELSE w.completed_at
+                 END,
+                 w.blocker_discovered,
+                 w.deviations, w.known_issues, w.key_files, w.key_decisions, w.full_summary_md,
+                 w.description, w.estimate, w.files, w.verify, w.inputs, w.expected_output,
+                 w.observability_impact, w.full_plan_md, w.sequence
+          FROM wt.tasks w
+          LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id
         `).run());
 
         // Merge memories — keep worktree-learned insights

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

@@ -39,6 +39,7 @@ import { debugLog } from "./debug-logger.js";
 import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMilestoneIds, clearReservedMilestoneIds } from "./milestone-ids.js";
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
+import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export {
@@ -289,6 +290,27 @@ async function dispatchWorkflow(
     }
   }
 
+  // Scope tools for discuss flows (#2949).
+  // Providers with grammar-based constrained decoding (xAI/Grok) return
+  // "Grammar is too complex" when the combined tool schema is too large.
+  // Discuss flows only need a small subset of GSD tools — strip the heavy
+  // planning/execution/completion tools to keep the grammar within limits.
+  if (unitType?.startsWith("discuss-")) {
+    const currentTools = pi.getActiveTools();
+    // Keep all non-GSD tools (builtins, other extensions) and only the
+    // GSD tools on the discuss allowlist.
+    const scopedTools = currentTools.filter(
+      (t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t),
+    );
+    pi.setActiveTools(scopedTools);
+    debugLog("discuss-tool-scoping", {
+      unitType,
+      before: currentTools.length,
+      after: scopedTools.length,
+      removed: currentTools.length - scopedTools.length,
+    });
+  }
+
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 

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

@@ -567,7 +567,34 @@ export function loadLedgerFromDisk(base: string): MetricsLedger | null {
 }
 
 function loadLedger(base: string): MetricsLedger {
-  return loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger);
+  const raw = loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger);
+  const before = raw.units.length;
+  raw.units = deduplicateUnits(raw.units);
+  if (raw.units.length < before) {
+    // Persist the cleaned ledger so duplicates don't re-accumulate
+    saveLedger(base, raw);
+  }
+  return raw;
+}
+
+/**
+ * Collapse duplicate entries with the same (type, id, startedAt) triple.
+ * Keeps the entry with the highest finishedAt (the most complete snapshot).
+ *
+ * This is a defensive measure against idle-watchdog race conditions that can
+ * produce duplicate entries on disk despite the in-memory idempotency guard
+ * in snapshotUnitMetrics(). See #1943.
+ */
+function deduplicateUnits(units: UnitMetrics[]): UnitMetrics[] {
+  const map = new Map<string, UnitMetrics>();
+  for (const u of units) {
+    const key = `${u.type}\0${u.id}\0${u.startedAt}`;
+    const existing = map.get(key);
+    if (!existing || u.finishedAt > existing.finishedAt) {
+      map.set(key, u);
+    }
+  }
+  return Array.from(map.values());
 }
 
 function saveLedger(base: string, data: MetricsLedger): void {

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -724,10 +724,12 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
       return;
     }
     // When .gsd is a symlink, git rejects `:!.gsd/...` pathspecs with
-    // "beyond a symbolic link". Fall back to plain `git add -A` which
-    // respects .gitignore (where .gsd/ is listed by default).
+    // "beyond a symbolic link". Fall back to `git add -u` which only
+    // stages changes to already-tracked files — O(tracked) not O(filesystem).
+    // Using `git add -A` here would traverse the entire working tree,
+    // hanging indefinitely on repos with large untracked data dirs. (#1977)
     if (stderr.includes("beyond a symbolic link")) {
-      nativeAddAll(basePath);
+      gitFileExec(basePath, ["add", "-u"]);
       return;
     }
     throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);

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

@@ -104,6 +104,8 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "context_management",
   "experimental",
   "codebase",
+  "slice_parallel",
+  "safety_harness",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -288,6 +290,20 @@ export interface GSDPreferences {
   experimental?: ExperimentalPreferences;
   /** Configuration for the codebase map generator (/gsd codebase). */
   codebase?: CodebaseMapPreferences;
+  /** Slice-level parallelism within a milestone. Disabled by default. */
+  slice_parallel?: { enabled?: boolean; max_workers?: number };
+  /** LLM safety harness configuration. Monitors, validates, and constrains LLM behavior during auto-mode. Enabled by default with warn-and-continue policy. */
+  safety_harness?: {
+    enabled?: boolean;
+    evidence_collection?: boolean;
+    file_change_validation?: boolean;
+    evidence_cross_reference?: boolean;
+    destructive_command_warnings?: boolean;
+    content_validation?: boolean;
+    checkpoints?: boolean;
+    auto_rollback?: boolean;
+    timeout_scale_cap?: number;
+  };
 }
 
 export interface LoadedGSDPreferences {

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

@@ -224,9 +224,13 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null
     return parseHeadingListFormat(content);
   }
 
-  if (!_warnedUnrecognizedFormat) {
+  // Warn when a non-empty file exists but lacks frontmatter delimiters (#2036).
+  if (content.trim().length > 0 && !_warnedUnrecognizedFormat) {
     _warnedUnrecognizedFormat = true;
-    console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+    console.warn(
+      "[GSD] Warning: preferences file has unrecognized format — content does not use YAML frontmatter delimiters (---). " +
+      "Wrap your preferences in --- fences. See https://github.com/gsd-build/gsd-2/issues/2036",
+    );
   }
   return null;
 }
@@ -384,6 +388,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
           ].filter(Boolean),
         }
       : undefined,
+    slice_parallel: (base.slice_parallel || override.slice_parallel)
+      ? { ...(base.slice_parallel ?? {}), ...(override.slice_parallel ?? {}) }
+      : undefined,
   };
 }
 

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -51,6 +51,14 @@ const __extensionDir = resolveExtensionDir();
 const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 
+/**
+ * Return the resolved templates directory path for use in prompts.
+ * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575)
+ */
+export function getTemplatesDir(): string {
+  return templatesDir;
+}
+
 // Cache all templates eagerly at module load — a running session uses the
 // template versions that were on disk at startup, immune to later overwrites.
 const templateCache = new Map<string, string>();

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

@@ -24,6 +24,8 @@ Then:
 7. Fill the **Decision Re-evaluation** table in the milestone summary. For each key decision from `.gsd/DECISIONS.md` made during this milestone, evaluate whether it is still valid given what was actually built. Flag decisions that should be revisited next milestone.
 8. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
 
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools — never via direct SQL.
+
 ### Verification Gate — STOP if verification failed
 
 **If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 9.**

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

@@ -35,6 +35,8 @@ Then:
 
 **Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
+**File system safety:** Task summaries are preloaded in the inlined context above. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first — never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
 When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/doctor-heal.md

@@ -9,6 +9,7 @@ Rules:
 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
 5. After each repair cluster, verify the relevant invariant directly from disk.
 6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
 
 ## Doctor Summary
 

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

@@ -116,6 +116,8 @@ A unit dispatched more than once (`type/id` appears multiple times) indicates a
 
 5. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
 
+   **DB inspection:** If you need to check DB state as part of investigation, use `gsd_milestone_status` — never run `sqlite3 .gsd/gsd.db` or `node -e require('better-sqlite3')` directly. The engine holds a WAL write lock; direct access will either fail or return stale data.
+
 6. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
 
 7. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:

package/src/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -63,4 +63,6 @@ If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, up
 
 {{commitInstruction}}
 
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`. Use `gsd_milestone_status` to read current milestone and slice state. All roadmap mutations go through `gsd_reassess_roadmap` — the tool writes to the DB and re-renders ROADMAP.md atomically.
+
 When done, say: "Roadmap reassessed."