gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

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

@@ -8,7 +8,7 @@
 
 import { loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection, parseTaskPlanFile } from "./files.js";
 import type { Override, UatType } from "./files.js";
-import { hasVerdict, getUatType } from "./verdict-parser.js";
+import { hasVerdict, getUatType, extractVerdict } from "./verdict-parser.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -17,6 +17,7 @@ import {
   resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
 } from "./paths.js";
 import { resolveSkillDiscoveryMode, resolveInlineLevel, loadEffectiveGSDPreferences, resolveAllSkillReferences } from "./preferences.js";
+import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
@@ -33,11 +34,12 @@ import {
 } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeInlinedContext, type ArtifactResolver } from "./unit-context-composer.js";
+import { composeContextModeInstructions, composeInlinedContext, type ArtifactResolver, type ContextModeRenderMode } from "./unit-context-composer.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
 import { resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { classifyProject, type ProjectClassification } from "./detection.js";
 
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 
@@ -79,6 +81,108 @@ function resolveSummaryBudgetChars(): number {
   return resolvePromptBudgets().summaryBudgetChars;
 }
 
+function formatProjectClassificationForPlanning(classification: ProjectClassification): string {
+  const sampleFiles = classification.contentFiles.slice(0, 8);
+  const sample = sampleFiles.length > 0 ? sampleFiles.map((file) => `\`${file}\``).join(", ") : "(none)";
+  const lines = [
+    "### Project Classification",
+    "",
+    `- **Kind:** ${classification.kind}`,
+    `- **Content files:** ${classification.contentFiles.length}`,
+    `- **Sample files:** ${sample}`,
+    `- **Reason:** ${classification.reason}`,
+    "",
+  ];
+
+  if (classification.kind === "untyped-existing") {
+    if (classification.contentFiles.length <= 2) {
+      lines.push(
+        "**Workflow sizing:** This is a tiny existing untyped project. Prefer exactly one slice unless the milestone request clearly spans multiple independent user-visible capabilities.",
+      );
+    } else if (classification.contentFiles.length <= 5) {
+      lines.push(
+        "**Workflow sizing:** This is a small existing untyped project. Prefer 1-2 slices unless the milestone request clearly spans multiple independent user-visible capabilities.",
+      );
+    } else {
+      lines.push(
+        "**Workflow sizing:** Existing untyped project. Use generic file-level workflow guidance and size slices by real capability boundaries, not by missing tooling markers.",
+      );
+    }
+  } else if (classification.kind === "greenfield") {
+    lines.push("**Workflow sizing:** No project content exists yet. Use normal greenfield sizing for the requested scope.");
+  } else if (classification.kind === "typed-existing") {
+    lines.push("**Workflow sizing:** Known project markers exist. Use normal ecosystem-aware planning guidance.");
+  } else {
+    lines.push("**Workflow sizing:** Invalid repository state. Planning should surface this as a blocker rather than inventing project structure.");
+  }
+
+  return lines.join("\n");
+}
+
+function normalizeArtifactRef(value: string): string {
+  return value.trim().replace(/^[-\s]+/, "").replace(/^["'`]+|["'`]+$/g, "").replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function parseCoveredArtifacts(validationContent: string): Set<string> {
+  const covered = new Set<string>();
+  const lines = validationContent.split(/\r?\n/);
+  let inCoveredArtifacts = false;
+  for (const line of lines) {
+    if (/^\s*covered[-_]?artifacts\s*:/i.test(line)) {
+      inCoveredArtifacts = true;
+      const inline = line.split(/covered[-_]?artifacts\s*:/i)[1]?.trim();
+      if (inline && inline !== "[]") {
+        inline.replace(/^\[|\]$/g, "").split(",").map(normalizeArtifactRef).filter(Boolean).forEach((item) => covered.add(item));
+      }
+      continue;
+    }
+    if (!inCoveredArtifacts) continue;
+    if (/^\S/.test(line) && !/^\s*-/.test(line)) break;
+    const item = line.match(/^\s*-\s*(.+)$/)?.[1];
+    if (item) covered.add(normalizeArtifactRef(item));
+  }
+  return covered;
+}
+
+function isValidationFreshOrApplicable(validationContent: string | null, currentArtifacts: string[]): boolean {
+  if (!validationContent) return false;
+  if (!/validation_metadata:/i.test(validationContent)) return false;
+  const coveredArtifacts = parseCoveredArtifacts(validationContent);
+  if (coveredArtifacts.size === 0) return false;
+  return currentArtifacts
+    .map(normalizeArtifactRef)
+    .filter(Boolean)
+    .every((artifact) => coveredArtifacts.has(artifact));
+}
+
+function formatCloseoutReviewInstructions(validationContent: string | null, validationRel: string, currentArtifacts: string[]): string {
+  const verdict = validationContent ? extractVerdict(validationContent) : null;
+  const validationFresh = isValidationFreshOrApplicable(validationContent, currentArtifacts);
+  if (verdict === "pass" && validationFresh) {
+    return [
+      "### Passing Validation Artifact",
+      "",
+      `A passing validation artifact is present at \`${validationRel}\`. Treat it as authoritative for success criteria, requirement coverage, verification classes, and cross-slice integration.`,
+      "",
+      "Do not delegate fresh reviewer/security/tester audits and do not redo the validation evidence review unless the artifact is internally inconsistent with the inlined summaries. Focus this unit on final milestone narrative, learnings, PROJECT/requirements updates, and `gsd_complete_milestone`.",
+    ].join("\n");
+  }
+
+  if (verdict) {
+    return [
+      "### Validation Requires Attention",
+      "",
+      `A validation artifact is present at \`${validationRel}\` with verdict \`${verdict}\`, but it is missing freshness metadata or does not cover current milestone artifacts. Do not treat the milestone as complete unless the issues are resolved and evidence supports completion.`,
+    ].join("\n");
+  }
+
+  return [
+    "### No Passing Validation Artifact",
+    "",
+    `No passing validation artifact was found at \`${validationRel}\`. Use the full closeout review path before completion.`,
+  ].join("\n");
+}
+
 function capPreamble(preamble: string): string {
   // Cap inlined context at min(historical 30K ceiling, scaled inline budget).
   // The ceiling preserves pre-fix behavior for large-window users; the scaled
@@ -89,6 +193,30 @@ function capPreamble(preamble: string): string {
   return truncateAtSectionBoundary(preamble, budget).content;
 }
 
+function renderContextModeForPrompt(
+  unitType: string,
+  base: string,
+  renderMode: ContextModeRenderMode = "standalone",
+): string {
+  const effectivePrefs = loadEffectiveGSDPreferences(base)?.preferences;
+  return composeContextModeInstructions(unitType, {
+    enabled: isContextModeEnabled(effectivePrefs),
+    renderMode,
+  });
+}
+
+function prependContextModeToBlock(
+  unitType: string,
+  base: string,
+  block: string,
+  renderMode: ContextModeRenderMode = "standalone",
+): string {
+  const contextMode = renderContextModeForPrompt(unitType, base, renderMode);
+  if (!contextMode) return block;
+  if (!block.trim()) return contextMode;
+  return `${contextMode}\n\n${block}`;
+}
+
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 
 /**
@@ -250,6 +378,171 @@ export async function inlineFileSmart(
   return `### ${label}\nSource: \`${relPath}\`\n\n${truncated}`;
 }
 
+function inlineCompactTemplate(name: "plan" | "task-summary" | "slice-summary", label: string): string {
+  const compact: Record<typeof name, string> = {
+    plan: [
+      "# {{sliceId}}: {{sliceTitle}}",
+      "",
+      "**Goal:** {{goal}}",
+      "**Demo:** {{demo}}",
+      "",
+      "## Must-Haves",
+      "- {{mustHave}}",
+      "",
+      "## Threat Surface",
+      "- Abuse: {{abuseScenarios}}",
+      "- Data exposure: {{sensitiveDataAccessible}}",
+      "- Input trust: {{untrustedInput}}",
+      "",
+      "## Requirement Impact",
+      "- Requirements touched: {{requirementIds}}",
+      "- Re-verify: {{whatMustBeRetested}}",
+      "- Decisions revisited: {{decisionIds}}",
+      "",
+      "## Proof Level",
+      "- This slice proves: {{contract | integration | operational | final-assembly}}",
+      "- Real runtime required: {{yes/no}}",
+      "- Human/UAT required: {{yes/no}}",
+      "",
+      "## Verification",
+      "- {{testFileOrCommand}}",
+      "",
+      "## Observability / Diagnostics",
+      "- Runtime signals: {{signalOrNone}}",
+      "- Inspection surfaces: {{surfaceOrNone}}",
+      "- Failure visibility: {{failureSignalOrNone}}",
+      "- Redaction constraints: {{secretOrPiiBoundaryOrNone}}",
+      "",
+      "## Integration Closure",
+      "- Upstream surfaces consumed: {{filesModulesContracts}}",
+      "- New wiring introduced: {{entrypointOrNone}}",
+      "- Remaining end-to-end work: {{listOrNothing}}",
+      "",
+      "## Tasks",
+      "- [ ] **T01: {{taskTitle}}** `est:{{estimate}}`",
+      "  - Why: {{whyThisTaskExists}}",
+      "  - Files: `{{filePath}}`",
+      "  - Do: {{specificImplementationStepsAndConstraints}}",
+      "  - Verify: {{testCommandOrRuntimeCheck}}",
+      "  - Done when: {{measurableAcceptanceCondition}}",
+      "",
+      "## Files Likely Touched",
+      "- `{{filePath}}`",
+    ].join("\n"),
+    "task-summary": [
+      "---",
+      "id: {{taskId}}",
+      "parent: {{sliceId}}",
+      "milestone: {{milestoneId}}",
+      "provides: [{{whatThisTaskProvides}}]",
+      "key_files: [{{filePath}}]",
+      "key_decisions: [{{decision}}]",
+      "patterns_established: [{{pattern}}]",
+      "observability_surfaces: [{{diagnosticOrNone}}]",
+      "duration: {{duration}}",
+      "verification_result: passed",
+      "completed_at: {{date}}",
+      "blocker_discovered: false",
+      "---",
+      "",
+      "# {{taskId}}: {{taskTitle}}",
+      "**{{oneLiner}}**",
+      "",
+      "## What Happened",
+      "{{narrative}}",
+      "",
+      "## Verification",
+      "{{whatWasVerifiedAndHow}}",
+      "",
+      "## Verification Evidence",
+      "| # | Command | Exit Code | Verdict | Duration |",
+      "|---|---------|-----------|---------|----------|",
+      "| {{row}} | {{command}} | {{exitCode}} | {{verdict}} | {{duration}} |",
+      "",
+      "## Diagnostics",
+      "{{diagnosticsOrNone}}",
+      "",
+      "## Deviations",
+      "{{deviationsFromPlan_OR_none}}",
+      "",
+      "## Known Issues",
+      "{{issuesDiscoveredButNotFixed_OR_none}}",
+      "",
+      "## Files Created/Modified",
+      "- `{{filePath}}` - {{description}}",
+    ].join("\n"),
+    "slice-summary": [
+      "---",
+      "id: {{sliceId}}",
+      "parent: {{milestoneId}}",
+      "milestone: {{milestoneId}}",
+      "provides: [{{whatThisSliceProvides}}]",
+      "requires: []",
+      "affects: []",
+      "key_files: [{{filePath}}]",
+      "key_decisions: [{{decision}}]",
+      "patterns_established: [{{pattern}}]",
+      "observability_surfaces: [{{diagnosticOrNone}}]",
+      "drill_down_paths: [{{pathToTaskSummary}}]",
+      "duration: {{duration}}",
+      "verification_result: passed",
+      "completed_at: {{date}}",
+      "---",
+      "",
+      "# {{sliceId}}: {{sliceTitle}}",
+      "**{{oneLiner}}**",
+      "",
+      "## What Happened",
+      "{{narrative}}",
+      "",
+      "## Verification",
+      "{{whatWasVerifiedAcrossAllTasks}}",
+      "",
+      "## Requirements Advanced",
+      "- {{requirementId}} - {{howThisSliceAdvancedIt}}",
+      "",
+      "## Requirements Validated",
+      "- {{requirementId}} - {{whatProofNowMakesItValidated}}",
+      "",
+      "## New Requirements Surfaced",
+      "- {{newRequirementOr_none}}",
+      "",
+      "## Requirements Invalidated or Re-scoped",
+      "- {{requirementIdOr_none}} - {{whatChanged}}",
+      "",
+      "## Operational Readiness",
+      "- Health signal: {{healthSignalOrNA}}",
+      "- Failure signal: {{failureSignalOrNA}}",
+      "- Recovery: {{recoveryOrNA}}",
+      "- Monitoring gaps: {{gapsOrNone}}",
+      "",
+      "## Deviations",
+      "{{deviationsFromPlan_OR_none}}",
+      "",
+      "## Known Limitations",
+      "{{whatDoesntWorkYet_OR_whatWasDeferredToLaterSlices}}",
+      "",
+      "## Follow-ups",
+      "{{workDeferredOrDiscoveredDuringExecution_OR_none}}",
+      "",
+      "## Files Created/Modified",
+      "- `{{filePath}}` - {{description}}",
+      "",
+      "## Forward Intelligence",
+      "### What the next slice should know",
+      "- {{insightThatWouldHelpDownstreamWork}}",
+      "### What's fragile",
+      "- {{fragileAreaOrThinImplementation}} - {{whyItMatters}}",
+      "### Authoritative diagnostics",
+      "- {{whereAFutureAgentShouldLookFirst}} - {{whyThisSignalIsTrustworthy}}",
+      "### What assumptions changed",
+      "- {{originalAssumption}} - {{whatActuallyHappened}}",
+    ].join("\n"),
+  };
+
+  return `${compact[name]}\n\n### Output Template: ${label}\nSource: \`templates/${name}.md\``;
+}
+
 /**
  * Compact slice-summary excerpt for milestone-level closers (#4780).
  *
@@ -1266,6 +1559,7 @@ export async function buildDiscussMilestonePrompt(
   structuredQuestionsAvailable = "false",
 ): Promise<string> {
   const discussTemplates = inlineTemplate("context", "Context");
+  const contextModeInstructions = renderContextModeForPrompt("discuss-milestone", base);
 
   const basePrompt = loadPrompt("guided-discuss-milestone", {
     workingDirectory: base,
@@ -1276,16 +1570,17 @@ export async function buildDiscussMilestonePrompt(
     commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
     fastPathInstruction: "",
   });
+  const promptWithContextMode = prependContextModeToBlock("discuss-milestone", base, basePrompt);
 
   // If a CONTEXT-DRAFT.md exists, append it as seed material
   const draftPath = resolveMilestoneFile(base, mid, "CONTEXT-DRAFT");
   const draftContent = draftPath ? await loadFile(draftPath) : null;
 
   if (draftContent) {
-    return `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${draftContent}`;
+    return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${draftContent}`;
   }
 
-  return basePrompt;
+  return contextModeInstructions ? promptWithContextMode : basePrompt;
 }
 
 /**
@@ -1298,10 +1593,10 @@ export async function buildWorkflowPreferencesPrompt(
   base: string,
   structuredQuestionsAvailable = "false",
 ): Promise<string> {
-  return loadPrompt("guided-workflow-preferences", {
+  return prependContextModeToBlock("workflow-preferences", base, loadPrompt("guided-workflow-preferences", {
     workingDirectory: base,
     structuredQuestionsAvailable,
-  });
+  }));
 }
 
 /**
@@ -1315,10 +1610,10 @@ export async function buildResearchProjectPrompt(
   base: string,
   structuredQuestionsAvailable = "false",
 ): Promise<string> {
-  return loadPrompt("guided-research-project", {
+  return prependContextModeToBlock("research-project", base, loadPrompt("guided-research-project", {
     workingDirectory: base,
     structuredQuestionsAvailable,
-  });
+  }));
 }
 
 /**
@@ -1331,10 +1626,10 @@ export async function buildResearchDecisionPrompt(
   base: string,
   structuredQuestionsAvailable = "false",
 ): Promise<string> {
-  return loadPrompt("guided-research-decision", {
+  return prependContextModeToBlock("research-decision", base, loadPrompt("guided-research-decision", {
     workingDirectory: base,
     structuredQuestionsAvailable,
-  });
+  }));
 }
 
 /**
@@ -1349,12 +1644,12 @@ export async function buildDiscussProjectPrompt(
 ): Promise<string> {
   const inlinedTemplates = inlineTemplate("project", "Project");
 
-  return loadPrompt("guided-discuss-project", {
+  return prependContextModeToBlock("discuss-project", base, loadPrompt("guided-discuss-project", {
     workingDirectory: base,
     inlinedTemplates,
     structuredQuestionsAvailable,
     commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
-  });
+  }));
 }
 
 /**
@@ -1369,12 +1664,12 @@ export async function buildDiscussRequirementsPrompt(
 ): Promise<string> {
   const inlinedTemplates = inlineTemplate("requirements", "Requirements");
 
-  return loadPrompt("guided-discuss-requirements", {
+  return prependContextModeToBlock("discuss-requirements", base, loadPrompt("guided-discuss-requirements", {
     workingDirectory: base,
     inlinedTemplates,
     structuredQuestionsAvailable,
     commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
-  });
+  }));
 }
 
 export async function buildResearchMilestonePrompt(mid: string, midTitle: string, base: string): Promise<string> {
@@ -1428,7 +1723,11 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string
     if (knowledgeInlineRM) parts.push(knowledgeInlineRM);
   }
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${parts.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "research-milestone",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${parts.join("\n\n---\n\n")}`),
+  );
 
   const outputRelPath = relMilestoneFile(base, mid, "RESEARCH");
   return loadPrompt("research-milestone", {
@@ -1462,6 +1761,8 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   const researchAnchor = readPhaseAnchor(base, mid, "research-milestone");
   if (researchAnchor) inlined.push(formatAnchorForPrompt(researchAnchor));
 
+  inlined.push(formatProjectClassificationForPlanning(classifyProject(base)));
+
   inlined.push(await inlineFile(contextPath, contextRel, "Milestone Context"));
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Milestone Research");
   if (researchInline) inlined.push(researchInline);
@@ -1501,7 +1802,11 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
     inlined.push(inlineTemplate("task-plan", "Task Plan"));
   }
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "plan-milestone",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+  );
 
   const outputRelPath = relMilestoneFile(base, mid, "ROADMAP");
   const researchOutputPath = join(base, relMilestoneFile(base, mid, "RESEARCH"));
@@ -1530,6 +1835,7 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
 
 export async function buildResearchSlicePrompt(
   mid: string, _midTitle: string, sid: string, sTitle: string, base: string,
+  options?: { contextModeRenderMode?: ContextModeRenderMode },
 ): Promise<string> {
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
@@ -1582,7 +1888,12 @@ export async function buildResearchSlicePrompt(
   const overridesInline = formatOverridesSection(activeOverrides);
   if (overridesInline) inlined.unshift(overridesInline);
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "research-slice",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+    options?.contextModeRenderMode,
+  );
 
   const outputRelPath = relSliceFile(base, mid, sid, "RESEARCH");
   return loadPrompt("research-slice", {
@@ -1629,6 +1940,7 @@ async function renderSlicePrompt(options: {
   sessionContextWindow?: number;
   modelRegistry?: MinimalModelRegistry;
   sessionProvider?: string;
+  contextModeRenderMode?: ContextModeRenderMode;
 }): Promise<string> {
   const {
     mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {},
@@ -1675,7 +1987,7 @@ async function renderSlicePrompt(options: {
   const graphBlock = await inlineGraphSubgraph(base, `${sid} ${sTitle}`, { budget: 3000 });
   if (graphBlock) inlined.push(graphBlock);
 
-  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(level === "minimal" ? inlineCompactTemplate("plan", "Slice Plan") : inlineTemplate("plan", "Slice Plan"));
   if (level === "full") {
     inlined.push(inlineTemplate("task-plan", "Task Plan"));
   }
@@ -1684,7 +1996,12 @@ async function renderSlicePrompt(options: {
   const overridesInline = formatOverridesSection(await loadActiveOverrides(base));
   if (overridesInline) inlined.unshift(overridesInline);
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    promptTemplate,
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+    options.contextModeRenderMode,
+  );
   const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry, sessionProvider);
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
   const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
@@ -1820,6 +2137,8 @@ export interface ExecuteTaskPromptOptions {
   modelRegistry?: MinimalModelRegistry;
   /** Session model provider, used for provider-specific effective context windows. */
   sessionProvider?: string;
+  /** Render compact Context Mode guidance when embedded inside another prompt. */
+  contextModeRenderMode?: ContextModeRenderMode;
 }
 
 export async function buildExecuteTaskPrompt(
@@ -1896,7 +2215,7 @@ export async function buildExecuteTaskPrompt(
   const graphBlockET = await inlineGraphSubgraph(base, `${tid} ${tTitle}`, { budget: 2000 });
 
   const inlinedTemplates = inlineLevel === "minimal"
-    ? inlineTemplate("task-summary", "Task Summary")
+    ? inlineCompactTemplate("task-summary", "Task Summary")
     : [
         inlineTemplate("task-summary", "Task Summary"),
         inlineTemplate("decisions", "Decisions"),
@@ -1962,6 +2281,7 @@ export async function buildExecuteTaskPrompt(
     getGatesForTurn("execute-task"),
     { pending: new Set(etPending.map((g) => g.gate_id)), allowOmit: true },
   );
+  phaseAnchorSection = prependContextModeToBlock("execute-task", base, phaseAnchorSection, opts.contextModeRenderMode);
 
   return loadPrompt("execute-task", {
     overridesSection,
@@ -1990,6 +2310,7 @@ export async function buildExecuteTaskPrompt(
       taskTitle: tTitle,
       taskPlanContent,
       extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+      unitType: "execute-task",
     }),
   });
 }
@@ -2040,7 +2361,9 @@ export async function buildCompleteSlicePrompt(
         return blocks.length > 0 ? blocks.join("\n\n---\n\n") : null;
       }
       case "templates": {
-        const parts = [inlineTemplate("slice-summary", "Slice Summary")];
+        const parts = [inlineLevel === "minimal"
+          ? inlineCompactTemplate("slice-summary", "Slice Summary")
+          : inlineTemplate("slice-summary", "Slice Summary")];
         if (inlineLevel !== "minimal") {
           parts.push(inlineTemplate("uat", "UAT"));
         }
@@ -2088,7 +2411,11 @@ export async function buildCompleteSlicePrompt(
     ? `${completeOverridesInline}\n\n---\n\n${body}`
     : body;
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${finalBody}`);
+  const inlinedContext = prependContextModeToBlock(
+    "complete-slice",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${finalBody}`),
+  );
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
 
   const sliceRel = relSlicePath(base, mid, sid);
@@ -2126,6 +2453,9 @@ export async function buildCompleteMilestonePrompt(
   const inlineLevel = level ?? resolveInlineLevel();
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
+  const validationPath = resolveMilestoneFile(base, mid, "VALIDATION");
+  const validationRel = relMilestoneFile(base, mid, "VALIDATION");
+  const validationContent = validationPath ? await loadFile(validationPath) : null;
 
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
@@ -2167,6 +2497,13 @@ export async function buildCompleteMilestonePrompt(
       `### On-demand Slice Summaries\n\nExcerpted above. Read the full file for any slice when the excerpt's section heads don't carry enough narrative for the milestone summary you're drafting:\n\n${pathList}`,
     );
   }
+  const validationContext = [
+    formatCloseoutReviewInstructions(validationContent, validationRel, [validationRel, roadmapRel, ...summaryRelPaths]),
+  ];
+  if (validationContent) {
+    validationContext.push(`### Milestone Validation\nSource: \`${validationRel}\`\n\n${validationContent.trim()}`);
+  }
+  inlined.unshift(...validationContext);
 
   // Inline root GSD files (skip for minimal — completion can read these if needed)
   if (inlineLevel !== "minimal") {
@@ -2187,7 +2524,11 @@ export async function buildCompleteMilestonePrompt(
   if (contextInline) inlined.push(contextInline);
   inlined.push(inlineTemplate("milestone-summary", "Milestone Summary"));
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "complete-milestone",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+  );
 
   const milestoneSummaryPath = join(base, `${relMilestonePath(base, mid)}/${mid}-SUMMARY.md`);
 
@@ -2324,7 +2665,11 @@ export async function buildValidateMilestonePrompt(
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "validate-milestone",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+  );
 
   const validationOutputPath = join(base, `${relMilestonePath(base, mid)}/${mid}-VALIDATION.md`);
   const roadmapOutputPath = `${relMilestonePath(base, mid)}/${mid}-ROADMAP.md`;
@@ -2400,7 +2745,11 @@ export async function buildReplanSlicePrompt(
   const replanOverridesInline = formatOverridesSection(replanActiveOverrides);
   if (replanOverridesInline) inlined.unshift(replanOverridesInline);
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "replan-slice",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`),
+  );
 
   const replanPath = join(base, `${relSlicePath(base, mid, sid)}/${sid}-REPLAN.md`);
 
@@ -2474,7 +2823,11 @@ export async function buildRunUatPrompt(
   };
 
   const composed = await composeInlinedContext("run-uat", resolveArtifact);
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${composed}`);
+  const inlinedContext = prependContextModeToBlock(
+    "run-uat",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${composed}`),
+  );
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
   const uatType = getUatType(uatContent);
@@ -2548,7 +2901,11 @@ export async function buildReassessRoadmapPrompt(
   const knowledgeInlineRA = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
   if (knowledgeInlineRA) parts.push(knowledgeInlineRA);
 
-  const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${parts.join("\n\n---\n\n")}`);
+  const inlinedContext = prependContextModeToBlock(
+    "reassess-roadmap",
+    base,
+    capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${parts.join("\n\n---\n\n")}`),
+  );
 
   const assessmentPath = join(base, relSliceFile(base, mid, completedSliceId, "ASSESSMENT"));
 
@@ -2641,6 +2998,7 @@ export async function buildReactiveExecutePrompt(
         sessionContextWindow: opts?.sessionContextWindow,
         modelRegistry: opts?.modelRegistry,
         sessionProvider: opts?.sessionProvider,
+        contextModeRenderMode: "nested",
       },
     );
 
@@ -2664,7 +3022,7 @@ export async function buildReactiveExecutePrompt(
     milestoneTitle: midTitle,
     sliceId: sid,
     sliceTitle: sTitle,
-    graphContext,
+    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
     readyTaskCount: String(readyTaskIds.length),
     readyTaskList: readyTaskListLines.join("\n"),
     subagentPrompts: subagentSections.join("\n\n---\n\n"),
@@ -2730,7 +3088,7 @@ export async function buildParallelResearchSlicesPrompt(
   const subagentSections: string[] = [];
   const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
   for (const slice of slices) {
-    const slicePrompt = await buildResearchSlicePrompt(mid, midTitle, slice.id, slice.title, basePath);
+    const slicePrompt = await buildResearchSlicePrompt(mid, midTitle, slice.id, slice.title, basePath, { contextModeRenderMode: "nested" });
     subagentSections.push([
       `### ${slice.id}: ${slice.title}`,
       "",
@@ -2786,6 +3144,8 @@ export async function buildGateEvaluatePrompt(
     gateListLines.push(`- **${def.id}**: ${def.question}`);
 
     const subPrompt = [
+      renderContextModeForPrompt("gate-evaluate", base, "nested"),
+      "",
       `You are evaluating quality gate **${def.id}** for slice ${sid} (${sTitle}).`,
       "",
       `**Working directory:** \`${normalizedBase}\`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT \`cd\` to any other directory.`,
@@ -2828,7 +3188,7 @@ export async function buildGateEvaluatePrompt(
     milestoneTitle: midTitle,
     sliceId: sid,
     sliceTitle: sTitle,
-    slicePlanContent: planContent,
+    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
     gateCount: String(pending.length),
     gateList: gateListLines.join("\n"),
     subagentPrompts: subagentSections.join("\n\n---\n\n"),
@@ -2905,7 +3265,7 @@ export async function buildRewriteDocsPrompt(
 
   const documentList = docList.length > 0 ? docList.join("\n") : "- No active plan documents found.";
 
-  return loadPrompt("rewrite-docs", {
+  return prependContextModeToBlock("rewrite-docs", base, loadPrompt("rewrite-docs", {
     workingDirectory: base,
     milestoneId: mid,
     milestoneTitle: midTitle,
@@ -2914,5 +3274,5 @@ export async function buildRewriteDocsPrompt(
     overrideContent,
     documentList,
     overridesPath: relGsdRootFile("OVERRIDES"),
-  });
+  }));
 }