gsd-pi 2.63.0 → 2.64.0-dev.05b8a94

package/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Key } from "@gsd/pi-tui";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.js";
+import { GSDNotificationOverlay } from "../notification-overlay.js";
 import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js";
 import { shortcutDesc } from "../../shared/mod.js";
 
@@ -31,6 +32,24 @@ export function registerShortcuts(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerShortcut(Key.ctrlAlt("n"), {
+    description: shortcutDesc("Open notification history", "/gsd notifications"),
+    handler: async (ctx) => {
+      await ctx.ui.custom<void>(
+        (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()),
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "80%",
+            minWidth: 60,
+            maxHeight: "88%",
+            anchor: "center",
+          },
+        },
+      );
+    },
+  });
+
   pi.registerShortcut(Key.ctrlAlt("p"), {
     description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"),
     handler: async (ctx) => {

package/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts

@@ -0,0 +1,57 @@
+/**
+ * Input sanitization for gsd_complete_milestone parameters.
+ *
+ * The Claude SDK deserializes tool-call JSON before the handler runs.
+ * When an LLM (especially smaller models like haiku) generates large markdown
+ * parameters, the JSON can arrive with subtly wrong types — numbers where
+ * strings are expected, null where arrays belong, string "true" instead of
+ * boolean true, etc.  This sanitizer normalizes all fields so
+ * handleCompleteMilestone never crashes on type mismatches.
+ *
+ * See: https://github.com/gsd-build/gsd-2/issues/3013
+ */
+
+import type { CompleteMilestoneParams } from "../tools/complete-milestone.js";
+
+/**
+ * Coerce an unknown value to a trimmed string.
+ * Returns "" for null / undefined.
+ */
+function toStr(v: unknown): string {
+  if (v == null) return "";
+  return String(v).trim();
+}
+
+/**
+ * Coerce an unknown value to an array of trimmed, non-empty strings.
+ * - If already an array, filter/trim each element.
+ * - Otherwise return [].
+ */
+function toStrArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v
+    .map((item) => (item == null ? "" : String(item).trim()))
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Sanitize raw params from the tool-call framework into well-typed
+ * CompleteMilestoneParams, tolerating type mismatches from LLM JSON quirks.
+ */
+export function sanitizeCompleteMilestoneParams(raw: Record<string, unknown>): CompleteMilestoneParams {
+  return {
+    milestoneId: toStr(raw.milestoneId),
+    title: toStr(raw.title),
+    oneLiner: toStr(raw.oneLiner),
+    narrative: toStr(raw.narrative),
+    successCriteriaResults: toStr(raw.successCriteriaResults),
+    definitionOfDoneResults: toStr(raw.definitionOfDoneResults),
+    requirementOutcomes: toStr(raw.requirementOutcomes),
+    keyDecisions: toStrArray(raw.keyDecisions),
+    keyFiles: toStrArray(raw.keyFiles),
+    lessonsLearned: toStrArray(raw.lessonsLearned),
+    followUps: toStr(raw.followUps),
+    deviations: toStr(raw.deviations),
+    verificationPassed: raw.verificationPassed === true || raw.verificationPassed === "true",
+  };
+}

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();
@@ -235,6 +264,13 @@ function buildWorktreeContextBlock(): string {
   return "";
 }
 
+/**
+ * Low-entropy resume intent patterns — short phrases a user types to
+ * continue work after a pause, rate limit, or context reset (#3615).
+ * Tested against the trimmed, lowercased prompt with trailing punctuation stripped.
+ */
+const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
+
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
   const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
   if (executeMatch) {
@@ -251,6 +287,27 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
     }
   }
 
+  // Fallback: low-entropy resume prompt (e.g., "continue", "ok", "go ahead")
+  // during an active executing task — inject task context so the agent
+  // doesn't rebuild from scratch (#3615).
+  // Intent-gated: only fire for short, resume-like prompts to avoid hijacking
+  // control/help/diagnostic prompts with unrelated execution context.
+  // Phase-gated: only fire during "executing" to avoid misrouting during
+  // replanning, gate evaluation, or other non-execution phases.
+  const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+  if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+    const state = await deriveState(basePath);
+    if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {
+      return buildTaskExecutionContextInjection(
+        basePath,
+        state.activeMilestone.id,
+        state.activeSlice.id,
+        state.activeTask.id,
+        state.activeTask.title,
+      );
+    }
+  }
+
   return null;
 }
 

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

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -48,6 +48,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
   { cmd: "run-hook", desc: "Manually trigger a specific hook" },
   { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+  { cmd: "notifications", desc: "View, filter, and clear persistent notification history" },
   { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
   { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
   { cmd: "forensics", desc: "Examine execution logs" },
@@ -110,6 +111,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "keys", desc: "Manage API keys" },
     { cmd: "prefs", desc: "Configure global preferences" },
   ],
+  notifications: [
+    { cmd: "clear", desc: "Clear all notifications" },
+    { cmd: "tail", desc: "Show last N notifications (default: 20)" },
+    { cmd: "filter", desc: "Filter by severity (error|warning|info|success)" },
+  ],
   logs: [
     { cmd: "debug", desc: "List or view debug log files" },
     { cmd: "tail", desc: "Show last N activity log summaries" },

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

@@ -29,6 +29,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
+    "  /gsd notifications  View persistent notification history  [clear|tail|filter]  (Ctrl+Alt+N)",
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",

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

@@ -0,0 +1,139 @@
+// GSD Extension — /gsd notifications Command Handler
+// View, filter, and clear the persistent notification history.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import {
+  readNotifications,
+  clearNotifications,
+  getUnreadCount,
+  suppressPersistence,
+  unsuppressPersistence,
+  type NotifySeverity,
+} from "../../notification-store.js";
+import { GSDNotificationOverlay } from "../../notification-overlay.js";
+
+function severityIcon(severity: NotifySeverity): string {
+  switch (severity) {
+    case "error": return "✗";
+    case "warning": return "⚠";
+    case "success": return "✓";
+    case "info":
+    default: return "●";
+  }
+}
+
+function formatTimestamp(ts: string): string {
+  try {
+    const d = new Date(ts);
+    return d.toLocaleString("en-US", { hour12: false, month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return ts.slice(0, 19);
+  }
+}
+
+export async function handleNotificationsCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  // /gsd notifications clear
+  if (args === "clear") {
+    clearNotifications();
+    // Suppress persistence so the confirmation toast doesn't re-populate the store
+    suppressPersistence();
+    try {
+      ctx.ui.notify("All notifications cleared.", "success");
+    } finally {
+      unsuppressPersistence();
+    }
+    return true;
+  }
+
+  // /gsd notifications tail [N]
+  if (args === "tail" || args.startsWith("tail ")) {
+    const countStr = args.replace(/^tail\s*/, "").trim();
+    const count = countStr ? parseInt(countStr, 10) : 20;
+    const n = isNaN(count) || count < 1 ? 20 : Math.min(count, 100);
+    const entries = readNotifications().slice(0, n);
+
+    if (entries.length === 0) {
+      ctx.ui.notify("No notifications.", "info");
+      return true;
+    }
+
+    const lines = entries.map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    ctx.ui.notify(`Last ${entries.length} notification(s):\n${lines.join("\n")}`, "info");
+    return true;
+  }
+
+  // /gsd notifications filter <severity>
+  if (args.startsWith("filter ")) {
+    const severity = args.replace(/^filter\s+/, "").trim().toLowerCase();
+    if (!["error", "warning", "info", "success"].includes(severity)) {
+      ctx.ui.notify("Usage: /gsd notifications filter <error|warning|info|success>", "warning");
+      return true;
+    }
+    const entries = readNotifications().filter((e) => e.severity === severity);
+
+    if (entries.length === 0) {
+      ctx.ui.notify(`No ${severity} notifications.`, "info");
+      return true;
+    }
+
+    const lines = entries.slice(0, 20).map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    const suffix = entries.length > 20 ? `\n... and ${entries.length - 20} more` : "";
+    ctx.ui.notify(`${severity} notifications (${entries.length}):\n${lines.join("\n")}${suffix}`, "info");
+    return true;
+  }
+
+  // /gsd notifications (no args) — open overlay in TUI, or print summary
+  if (args === "" || args === "status") {
+    // Try overlay first (TUI mode)
+    if (ctx.hasUI) {
+      try {
+        await ctx.ui.custom<void>(
+          (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()),
+          {
+            overlay: true,
+            overlayOptions: {
+              width: "80%",
+              minWidth: 60,
+              maxHeight: "88%",
+              anchor: "center",
+            },
+          },
+        );
+        return true;
+      } catch {
+        // Fall through to text output if overlay fails
+      }
+    }
+
+    // Text fallback (RPC/headless mode)
+    const unread = getUnreadCount();
+    const entries = readNotifications().slice(0, 10);
+    if (entries.length === 0) {
+      ctx.ui.notify("No notifications.", "info");
+      return true;
+    }
+
+    const lines = entries.map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    const header = unread > 0 ? `${unread} unread — ` : "";
+    ctx.ui.notify(`${header}Recent notifications:\n${lines.join("\n")}`, "info");
+    return true;
+  }
+
+  // Unknown subcommand
+  ctx.ui.notify(
+    "Usage: /gsd notifications [clear|tail [N]|filter <severity>]",
+    "warning",
+  );
+  return true;
+}

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

@@ -178,6 +178,11 @@ Examples:
     await dispatchDirectPhase(ctx, pi, phase, projectRoot());
     return true;
   }
+  if (trimmed === "notifications" || trimmed.startsWith("notifications ")) {
+    const { handleNotificationsCommand } = await import("./notifications-handler.js");
+    await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "inspect") {
     await handleInspect(ctx);
     return true;

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({