gsd-pi 2.66.0 → 2.66.1-dev.0df32ec

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

@@ -261,7 +261,12 @@ export async function inlineGsdRootFile(
 
 /**
  * Inline decisions with optional milestone scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
+ *
+ * Cascade logic (R005):
+ * 1. Query with { milestoneId, scope } if scope provided
+ * 2. If empty AND scope was provided, retry with { milestoneId } only (drop scope)
+ * 3. If still empty, return null (intentional per D020)
  */
 export async function inlineDecisionsFromDb(
   base: string, milestoneId?: string, scope?: string, level?: InlineLevel,
@@ -271,7 +276,15 @@ export async function inlineDecisionsFromDb(
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryDecisions, formatDecisionsForPrompt } = await import("./context-store.js");
-      const decisions = queryDecisions({ milestoneId, scope });
+
+      // First query: try with both milestoneId and scope (if scope provided)
+      let decisions = queryDecisions({ milestoneId, scope });
+
+      // Cascade: if empty AND scope was provided, retry without scope
+      if (decisions.length === 0 && scope) {
+        decisions = queryDecisions({ milestoneId });
+      }
+
       if (decisions.length > 0) {
         // Use compact format for non-full levels to save ~35% tokens
         const formatted = inlineLevel !== "full"
@@ -279,26 +292,29 @@ export async function inlineDecisionsFromDb(
           : formatDecisionsForPrompt(decisions);
         return `### Decisions\nSource: \`.gsd/DECISIONS.md\`\n\n${formatted}`;
       }
+      // DB available but cascade returned empty — intentional per D020, don't fall back to file
+      return null;
     }
   } catch (err) {
     logWarning("prompt", `inlineDecisionsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
   }
+  // DB unavailable — fall back to filesystem
   return inlineGsdRootFile(base, "decisions.md", "Decisions");
 }
 
 /**
- * Inline requirements with optional slice scoping from the DB.
+ * Inline requirements with optional milestone and slice scoping from the DB.
  * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
  */
 export async function inlineRequirementsFromDb(
-  base: string, sliceId?: string, level?: InlineLevel,
+  base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
 ): Promise<string | null> {
   const inlineLevel = level ?? resolveInlineLevel();
   try {
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ sliceId });
+      const requirements = queryRequirements({ milestoneId, sliceId });
       if (requirements.length > 0) {
         // Use compact format for non-full levels to save ~40% tokens
         const formatted = inlineLevel !== "full"
@@ -335,6 +351,131 @@ export async function inlineProjectFromDb(
   return inlineGsdRootFile(base, "project.md", "Project");
 }
 
+// ─── Stopwords for keyword extraction ─────────────────────────────────────
+const STOPWORDS = new Set(['of', 'the', 'and', 'a', 'for', '+', '-', 'to', 'in', 'on', 'with', 'is', 'as', 'by']);
+
+// Generic words that don't provide meaningful scope differentiation
+const GENERIC_WORDS = new Set([
+  'setup', 'integration', 'implementation', 'testing', 'test', 'tests',
+  'config', 'configuration', 'init', 'initial', 'basic', 'core',
+  'main', 'primary', 'final', 'complete', 'finish', 'end',
+  'start', 'begin', 'first', 'last', 'update', 'updates',
+  'fix', 'fixes', 'add', 'adds', 'remove', 'removes',
+  'create', 'creates', 'build', 'builds', 'deploy', 'deployment',
+  'refactor', 'refactoring', 'cleanup', 'polish', 'review',
+  // Process/activity words that describe what you're doing, not what domain
+  'hardening', 'validation', 'verification', 'optimization',
+  'improvement', 'enhancement', 'infrastructure',
+]);
+
+// Pattern to match slice/milestone/task IDs (e.g., S01, M001, T03)
+const UNIT_ID_PATTERN = /^[smt]\d+$/i;
+
+/**
+ * Derive a scope keyword from slice title and optional description.
+ * Returns the most specific noun (first non-generic keyword) for decision scoping.
+ *
+ * Examples:
+ * - "Auth Middleware & Protected Route" → "auth"
+ * - "Database & User Model Setup" → "database"
+ * - "Integration Testing" → undefined (too generic)
+ * - "API Rate Limiting" → "api"
+ *
+ * @param sliceTitle - The slice title
+ * @param sliceDescription - Optional roadmap description (demo text)
+ * @returns A single lowercase keyword or undefined if no meaningful scope
+ */
+export function deriveSliceScope(sliceTitle: string, sliceDescription?: string): string | undefined {
+  // Combine title and description for keyword extraction
+  const combinedText = sliceDescription
+    ? `${sliceTitle} ${sliceDescription}`
+    : sliceTitle;
+
+  // Extract all words, lowercase, remove punctuation
+  const words = combinedText
+    .split(/[\s&+,;:|/\\()-]+/)
+    .map(w => w.toLowerCase().replace(/[^a-z0-9]/g, ''))
+    .filter(w => w.length >= 2);
+
+  // Find the first word that is:
+  // 1. Not a stopword
+  // 2. Not a generic word
+  // 3. Not a unit ID (S01, M001, T03)
+  // 4. At least 3 characters (meaningful scope)
+  for (const word of words) {
+    if (STOPWORDS.has(word)) continue;
+    if (GENERIC_WORDS.has(word)) continue;
+    if (UNIT_ID_PATTERN.test(word)) continue;
+    if (word.length < 3) continue;
+    return word;
+  }
+
+  return undefined;
+}
+/**
+ * Extract keywords from a slice title for scoped knowledge queries.
+ * Splits on whitespace, filters stopwords, lowercases.
+ * Example: 'KNOWLEDGE scoping + roadmap excerpt' → ['knowledge', 'scoping', 'roadmap', 'excerpt']
+ */
+function extractKeywords(title: string): string[] {
+  return title
+    .split(/\s+/)
+    .map(w => w.toLowerCase().replace(/[^a-z0-9]/g, ''))
+    .filter(w => w.length > 0 && !STOPWORDS.has(w));
+}
+
+/**
+ * Inline scoped KNOWLEDGE.md content based on keywords from slice title.
+ * Reads KNOWLEDGE.md, filters to sections matching keywords, formats with header.
+ * Returns null if no KNOWLEDGE.md exists or no sections match.
+ */
+export async function inlineKnowledgeScoped(
+  base: string,
+  keywords: string[],
+): Promise<string | null> {
+  const knowledgePath = resolveGsdRootFile(base, "KNOWLEDGE");
+  if (!existsSync(knowledgePath)) return null;
+
+  const content = await loadFile(knowledgePath);
+  if (!content) return null;
+
+  // Import queryKnowledge from context-store
+  const { queryKnowledge } = await import("./context-store.js");
+  const scoped = await queryKnowledge(content, keywords);
+
+  // Return null if no sections matched (empty string from queryKnowledge)
+  if (!scoped) return null;
+
+  return `### Project Knowledge (scoped)\nSource: \`${relGsdRootFile("KNOWLEDGE")}\`\n\n${scoped.trim()}`;
+}
+
+/**
+ * Inline a roadmap excerpt for a specific slice.
+ * Reads full roadmap, extracts minimal excerpt with header + predecessor + target row.
+ * Returns null if roadmap doesn't exist or slice not found.
+ */
+export async function inlineRoadmapExcerpt(
+  base: string,
+  mid: string,
+  sid: string,
+): Promise<string | null> {
+  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+  if (!roadmapPath || !existsSync(roadmapPath)) return null;
+
+  const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
+  const content = await loadFile(roadmapPath);
+  if (!content) return null;
+
+  // Import formatRoadmapExcerpt from context-store
+  const { formatRoadmapExcerpt } = await import("./context-store.js");
+  const excerpt = formatRoadmapExcerpt(content, sid, roadmapRel);
+
+  // Return null if slice not found in roadmap
+  if (!excerpt) return null;
+
+  return `### Milestone Roadmap (excerpt)\nSource: \`${roadmapRel}\`\n\n${excerpt}`;
+}
+
 // ─── Skill Activation & Discovery ─────────────────────────────────────────
 
 function normalizeSkillReference(ref: string): string {
@@ -880,7 +1021,7 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string
   inlined.push(await inlineFile(contextPath, contextRel, "Milestone Context"));
   const projectInline = await inlineProjectFromDb(base);
   if (projectInline) inlined.push(projectInline);
-  const requirementsInline = await inlineRequirementsFromDb(base);
+  const requirementsInline = await inlineRequirementsFromDb(base, mid);
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineDecisionsFromDb(base, mid);
   if (decisionsInline) inlined.push(decisionsInline);
@@ -930,7 +1071,7 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   if (inlineLevel !== "minimal") {
     const projectInline = await inlineProjectFromDb(base);
     if (projectInline) inlined.push(projectInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
     const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
     if (decisionsInline) inlined.push(decisionsInline);
@@ -999,19 +1140,35 @@ export async function buildResearchSlicePrompt(
   const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
 
   const inlined: string[] = [];
-  inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+
+  // Use roadmap excerpt instead of full roadmap for context reduction
+  const roadmapExcerptRS = await inlineRoadmapExcerpt(base, mid, sid);
+  if (roadmapExcerptRS) {
+    inlined.push(roadmapExcerptRS);
+  } else {
+    // Fall back to full roadmap if excerpt fails
+    inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  }
+
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
   const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
   if (sliceCtxInline) inlined.push(sliceCtxInline);
   const researchInline = await inlineFileOptional(milestoneResearchPath, milestoneResearchRel, "Milestone Research");
   if (researchInline) inlined.push(researchInline);
-  const decisionsInline = await inlineDecisionsFromDb(base, mid);
+
+  // Derive scope from slice title for decision filtering (R005)
+  const derivedScope = deriveSliceScope(sTitle);
+  const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScope);
   if (decisionsInline) inlined.push(decisionsInline);
-  const requirementsInline = await inlineRequirementsFromDb(base, sid);
+  const requirementsInline = await inlineRequirementsFromDb(base, mid, sid);
   if (requirementsInline) inlined.push(requirementsInline);
-  const knowledgeInlineRS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+
+  // Use scoped knowledge based on slice title keywords
+  const keywords = extractKeywords(sTitle);
+  const knowledgeInlineRS = await inlineKnowledgeScoped(base, keywords);
   if (knowledgeInlineRS) inlined.push(knowledgeInlineRS);
+
   inlined.push(inlineTemplate("research", "Research"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
@@ -1060,19 +1217,33 @@ export async function buildPlanSlicePrompt(
   const researchSliceAnchor = readPhaseAnchor(base, mid, "research-slice");
   if (researchSliceAnchor) inlined.push(formatAnchorForPrompt(researchSliceAnchor));
 
-  inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  // Use roadmap excerpt instead of full roadmap for context reduction
+  const roadmapExcerptPS = await inlineRoadmapExcerpt(base, mid, sid);
+  if (roadmapExcerptPS) {
+    inlined.push(roadmapExcerptPS);
+  } else {
+    // Fall back to full roadmap if excerpt fails
+    inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  }
+
   const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
   if (sliceCtxInline) inlined.push(sliceCtxInline);
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
   if (researchInline) inlined.push(researchInline);
   if (inlineLevel !== "minimal") {
-    const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
+    // Derive scope from slice title for decision filtering (R005)
+    const derivedScopePS = deriveSliceScope(sTitle);
+    const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScopePS, inlineLevel);
     if (decisionsInline) inlined.push(decisionsInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
   }
-  const knowledgeInlinePS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+
+  // Use scoped knowledge based on slice title keywords
+  const keywordsPS = extractKeywords(sTitle);
+  const knowledgeInlinePS = await inlineKnowledgeScoped(base, keywordsPS);
   if (knowledgeInlinePS) inlined.push(knowledgeInlinePS);
+
   inlined.push(inlineTemplate("plan", "Slice Plan"));
   if (inlineLevel === "full") {
     inlined.push(inlineTemplate("task-plan", "Task Plan"));
@@ -1272,7 +1443,7 @@ export async function buildCompleteSlicePrompt(
   if (sliceCtxInline) inlined.push(sliceCtxInline);
   inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Slice Plan"));
   if (inlineLevel !== "minimal") {
-    const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
   }
   const knowledgeInlineCS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
@@ -1355,7 +1526,7 @@ export async function buildCompleteMilestonePrompt(
 
   // Inline root GSD files (skip for minimal — completion can read these if needed)
   if (inlineLevel !== "minimal") {
-    const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
     const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
     if (decisionsInline) inlined.push(decisionsInline);
@@ -1480,7 +1651,7 @@ export async function buildValidateMilestonePrompt(
 
   // Inline root GSD files
   if (inlineLevel !== "minimal") {
-    const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
     const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
     if (decisionsInline) inlined.push(decisionsInline);
@@ -1656,7 +1827,7 @@ export async function buildReassessRoadmapPrompt(
   if (inlineLevel !== "minimal") {
     const projectInline = await inlineProjectFromDb(base);
     if (projectInline) inlined.push(projectInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel);
     if (requirementsInline) inlined.push(requirementsInline);
     const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
     if (decisionsInline) inlined.push(decisionsInline);

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

@@ -1205,7 +1205,18 @@ export async function startAuto(
     s.active = true;
     s.verbose = verboseMode;
     s.stepMode = requestedStepMode;
-    s.cmdCtx = ctx;
+    // Preserve the original cmdCtx (ExtensionCommandContext with newSession)
+    // when resuming from a provider-error pause. The resume callback receives
+    // an ExtensionContext (from the agent_end hook) which lacks newSession —
+    // using it would crash runUnit with "newSession is not a function".
+    // Only override if the new ctx actually has newSession (user-initiated resume).
+    if ("newSession" in ctx && typeof (ctx as any).newSession === "function") {
+      s.cmdCtx = ctx;
+    } else if (!s.cmdCtx) {
+      // No saved cmdCtx — this shouldn't happen, but handle gracefully
+      s.cmdCtx = ctx as ExtensionCommandContext;
+    }
+    // else: keep existing s.cmdCtx which has the real newSession
     s.basePath = base;
     setLogBasePath(base);
     if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now();

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -19,7 +19,17 @@ import {
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
-const MAX_TRANSIENT_AUTO_RESUMES = 3;
+const MAX_TRANSIENT_AUTO_RESUMES = 8;
+
+/**
+ * Reset the module-level retry state so a resumed auto-session starts fresh.
+ * Called by provider-error-resume.ts before startAuto() — without this, the
+ * consecutiveTransientCount accumulates across pause/resume cycles and locks
+ * out auto-resume after MAX_TRANSIENT_AUTO_RESUMES total (not consecutive) errors.
+ */
+export function resetTransientRetryState(): void {
+  resetRetryState(retryState);
+}
 
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
@@ -114,6 +124,29 @@ export async function handleAgentEnd(
     // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
     const cls = classifyError(rawErrorMsg, explicitRetryAfterMs);
 
+    // ── 1b. Defer to Core RetryHandler for transient errors ─────────────
+    // The Core RetryHandler (agent-session.ts) processes retryable errors
+    // AFTER this extension handler, in the same _processAgentEvent() call.
+    // For transient errors (overloaded, rate limit, server), the Core will
+    // retry in-context — same session, same conversation — which is strictly
+    // better than our Layer 2 pause+resume (which creates a new session).
+    //
+    // If we react here AND the Core also retries, we race: pauseAuto tears
+    // down the session while agent.continue() starts a new turn.
+    //
+    // Solution: Do nothing for transient errors. The Core RetryHandler
+    // runs next in _processAgentEvent and will either:
+    //   a) Retry successfully → new agent_end (success) → we see it next time
+    //   b) Exhaust retries → the agent stays idle, autoLoop's unit timeout
+    //      or stuck detection handles it
+    //
+    // We do NOT call resolveAgentEnd here — that would unblock autoLoop
+    // prematurely while the Core is still retrying in the same session.
+    // We do NOT call pauseAuto — that would tear down the session.
+    if (isTransient(cls)) {
+      return;
+    }
+
     // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli)
     // which use per-user quotas with shorter windows (#2922).
     if (cls.kind === "rate-limit") {

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -5,6 +5,7 @@ import type {
 } from "@gsd/pi-coding-agent";
 
 import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js";
+import { resetTransientRetryState } from "./agent-end-recovery.js";
 
 type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMode" | "basePath">;
 
@@ -42,6 +43,11 @@ export async function resumeAutoAfterProviderDelay(
     return "missing-base";
   }
 
+  // Reset the transient retry counter before restarting — without this,
+  // consecutiveTransientCount accumulates across pause/resume cycles and
+  // permanently locks out auto-resume after MAX_TRANSIENT_AUTO_RESUMES errors.
+  resetTransientRetryState();
+
   await deps.startAuto(
     ctx as ExtensionCommandContext,
     pi,

package/src/resources/extensions/gsd/context-store.ts

@@ -15,6 +15,7 @@ export interface DecisionQueryOpts {
 }
 
 export interface RequirementQueryOpts {
+  milestoneId?: string;
   sliceId?: string;
   status?: string;
 }
@@ -67,7 +68,8 @@ export function queryDecisions(opts?: DecisionQueryOpts): Decision[] {
 
 /**
  * Query active (non-superseded) requirements with optional filters.
- * - sliceId: filters where primary_owner LIKE '%sliceId%' OR supporting_slices LIKE '%sliceId%'
+ * - milestoneId: combined with sliceId for precise filtering (e.g. %M005/S01%)
+ * - sliceId: filters where primary_owner LIKE '%pattern%' OR supporting_slices LIKE '%pattern%'
  * - status: filters where status = :status (exact match)
  *
  * Returns [] if DB is not available. Never throws.
@@ -81,9 +83,19 @@ export function queryRequirements(opts?: RequirementQueryOpts): Requirement[] {
     const clauses: string[] = ['superseded_by IS NULL'];
     const params: Record<string, unknown> = {};
 
-    if (opts?.sliceId) {
+    // Combined milestone+slice filtering for precise scoping
+    if (opts?.milestoneId && opts?.sliceId) {
+      // Use combined pattern like %M005/S01% to avoid cross-milestone contamination
+      clauses.push('(primary_owner LIKE :combined_pattern OR supporting_slices LIKE :combined_pattern)');
+      params[':combined_pattern'] = `%${opts.milestoneId}/${opts.sliceId}%`;
+    } else if (opts?.sliceId) {
+      // Slice-only filtering (legacy behavior)
       clauses.push('(primary_owner LIKE :slice_pattern OR supporting_slices LIKE :slice_pattern)');
       params[':slice_pattern'] = `%${opts.sliceId}%`;
+    } else if (opts?.milestoneId) {
+      // Milestone-only filtering
+      clauses.push('(primary_owner LIKE :milestone_pattern OR supporting_slices LIKE :milestone_pattern)');
+      params[':milestone_pattern'] = `%${opts.milestoneId}%`;
     }
 
     if (opts?.status) {
@@ -194,3 +206,156 @@ export function queryArtifact(path: string): string | null {
 export function queryProject(): string | null {
   return queryArtifact('PROJECT.md');
 }
+
+// ─── Knowledge Query ───────────────────────────────────────────────────────
+
+/**
+ * Filter KNOWLEDGE.md sections by keyword matching.
+ * Uses H2 sections, matches keywords case-insensitively against:
+ * 1. Section header text
+ * 2. First paragraph of section content (up to first blank line or next heading)
+ *
+ * Per D020, returns empty string (not null) when no matches found.
+ * This signals "no relevant knowledge" vs "file not found".
+ *
+ * @param content - Full KNOWLEDGE.md content
+ * @param keywords - Keywords to match (case-insensitive)
+ * @returns Concatenated matching sections with H2 headers, or empty string
+ */
+export async function queryKnowledge(content: string, keywords: string[]): Promise<string> {
+  if (!content || keywords.length === 0) return '';
+
+  // Lazy import to avoid circular dependency
+  const { extractAllSections } = await import('./files.js');
+
+  const sections = extractAllSections(content, 2);
+  if (sections.size === 0) return '';
+
+  // Normalize keywords for case-insensitive matching
+  const normalizedKeywords = keywords.map(k => k.toLowerCase());
+
+  const matchingSections: string[] = [];
+
+  for (const [header, body] of sections) {
+    // Extract first paragraph: everything up to first blank line or next heading
+    const firstParagraph = body.split(/\n\s*\n|\n#/)[0] || '';
+
+    // Check if any keyword matches header or first paragraph
+    const headerLower = header.toLowerCase();
+    const paragraphLower = firstParagraph.toLowerCase();
+
+    const matches = normalizedKeywords.some(kw =>
+      headerLower.includes(kw) || paragraphLower.includes(kw)
+    );
+
+    if (matches) {
+      matchingSections.push(`## ${header}\n\n${body}`);
+    }
+  }
+
+  return matchingSections.join('\n\n');
+}
+
+// ─── Roadmap Excerpt Formatter ─────────────────────────────────────────────
+
+/**
+ * Format a minimal roadmap excerpt for prompt injection.
+ * Parses the slice table from roadmap content, extracts:
+ * 1. Header row + separator
+ * 2. Predecessor row (if sliceId depends on one via the Depends column)
+ * 3. Target slice row
+ * 4. Reference directive pointing to full roadmap path
+ *
+ * Per D021, this minimizes injected content while preserving dependency awareness.
+ * Returns empty string if sliceId is not found in the table.
+ * Never throws.
+ *
+ * @param roadmapContent - Full content of the M###-ROADMAP.md file
+ * @param sliceId - Target slice ID (e.g. 'S02')
+ * @param roadmapPath - Optional path for reference directive (defaults to generic)
+ */
+export function formatRoadmapExcerpt(
+  roadmapContent: string,
+  sliceId: string,
+  roadmapPath = 'ROADMAP.md',
+): string {
+  if (!roadmapContent || !sliceId) return '';
+
+  const lines = roadmapContent.split('\n');
+
+  // Find the slice table header: | ID | Slice | ... (case insensitive)
+  let headerIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line && /^\s*\|\s*ID\s*\|\s*Slice\s*\|/i.test(line)) {
+      headerIndex = i;
+      break;
+    }
+  }
+
+  if (headerIndex === -1) return '';
+
+  // The separator should be the next line (|---|---|...)
+  const separatorIndex = headerIndex + 1;
+  if (separatorIndex >= lines.length) return '';
+
+  const headerLine = lines[headerIndex];
+  const separatorLine = lines[separatorIndex];
+
+  // Validate separator line looks like |---|---|... (may include : for alignment)
+  if (!separatorLine || !/^\s*\|[\s:\-|]+\|/.test(separatorLine)) return '';
+
+  // Parse table rows after separator
+  interface SliceRow {
+    line: string;
+    id: string;
+    depends: string;
+  }
+
+  const sliceRows: SliceRow[] = [];
+  for (let i = separatorIndex + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line || !line.trim().startsWith('|')) break; // End of table
+
+    // Parse row: | ID | Slice | Risk | Depends | Done | After this |
+    const cells = line.split('|').map(c => c.trim());
+    // cells[0] is empty (before first |), cells[1] is ID, etc.
+    if (cells.length < 5) continue;
+
+    const id = cells[1] || '';
+    const depends = cells[4] || ''; // Depends column (0-indexed: empty, ID, Slice, Risk, Depends, ...)
+
+    sliceRows.push({ line, id, depends });
+  }
+
+  // Find target slice row
+  const targetRow = sliceRows.find(r => r.id === sliceId);
+  if (!targetRow) return '';
+
+  // Find predecessor if target depends on one
+  // Depends column may contain: '—', 'S01', 'S01, S02', etc.
+  let predecessorRow: SliceRow | undefined;
+  const dependsRaw = targetRow.depends;
+  if (dependsRaw && dependsRaw !== '—' && dependsRaw !== '-') {
+    // Extract first dependency (e.g. 'S01' from 'S01, S02')
+    const depMatch = dependsRaw.match(/S\d+/);
+    if (depMatch) {
+      predecessorRow = sliceRows.find(r => r.id === depMatch[0]);
+    }
+  }
+
+  // Build excerpt
+  const excerptLines: string[] = [headerLine!, separatorLine!];
+
+  if (predecessorRow) {
+    excerptLines.push(predecessorRow.line);
+  }
+
+  excerptLines.push(targetRow.line);
+
+  // Add reference directive
+  excerptLines.push('');
+  excerptLines.push(`> See full roadmap: ${roadmapPath}`);
+
+  return excerptLines.join('\n');
+}

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

@@ -200,11 +200,13 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG
 }
 
 let _warnedUnrecognizedFormat = false;
+let _warnedSectionParse = false;
 
 /** @internal Reset the warn-once flags — exported for testing only. */
 export function _resetParseWarningFlag(): void {
   _warnedUnrecognizedFormat = false;
   _warnedFrontmatterParse = false;
+  _warnedSectionParse = false;
 }
 
 /** @internal Exported for testing only */
@@ -309,7 +311,10 @@ function parseHeadingListFormat(content: string): GSDPreferences {
 
       typed[targetSection] = value;
     } catch (e) {
-      logWarning("guided", `preferences section parse failed: ${(e as Error).message}`);
+      if (!_warnedSectionParse) {
+        _warnedSectionParse = true;
+        logWarning("guided", `preferences section parse failed: ${(e as Error).message}`);
+      }
     }
   }