@opengsd/gsd-pi 1.9.0 → 1.10.0

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

@@ -1,3 +1,5 @@
+import { GSD_CONTEXT_MESSAGE_SENTINEL } from "./constants.js";
+
 /**
  * Observation masking for GSD auto-mode sessions.
  *
@@ -75,6 +77,26 @@ function findTurnBoundary(messages: MaskableMessage[], keepRecentTurns: number):
   return 0;
 }
 
+function countRealUserTurns(messages: MaskableMessage[]): number {
+  let count = 0;
+  for (const m of messages) {
+    if (m.role === "user" && !isBashResultUserMessage(m)) count++;
+  }
+  return count;
+}
+
+/**
+ * Quantizes how many recent turns stay unmasked so the boundary only moves
+ * forward once per full block of `keepRecentTurns` new turns, instead of
+ * every turn. Keeps the masked prefix byte-stable within a block, which is
+ * what lets the LLM provider's prompt cache survive across turns.
+ */
+function quantizedKeepTurns(totalTurns: number, keepRecentTurns: number): number {
+  if (keepRecentTurns <= 0 || totalTurns < 2 * keepRecentTurns) return totalTurns;
+  const maskedTurns = Math.floor((totalTurns - keepRecentTurns) / keepRecentTurns) * keepRecentTurns;
+  return totalTurns - maskedTurns;
+}
+
 /**
  * Detect user messages that originated from bashExecution.
  * After convertToLlm, these are {role: "user", content: [{type:"text", text:"Ran `cmd`\n..."}]}.
@@ -95,7 +117,8 @@ function isMaskableMessage(m: MaskableMessage): boolean {
 
 export function createObservationMask(keepRecentTurns: number = 8) {
   return (messages: MaskableMessage[]): MaskableMessage[] => {
-    const boundary = findTurnBoundary(messages, keepRecentTurns);
+    const totalTurns = countRealUserTurns(messages);
+    const boundary = findTurnBoundary(messages, quantizedKeepTurns(totalTurns, keepRecentTurns));
     if (boundary === 0) return messages;
 
     return messages.map((m, i) => {
@@ -126,6 +149,14 @@ function findResponsesTurnBoundary(items: ResponsesInputItem[], keepRecentTurns:
   return 0;
 }
 
+function countResponsesRealUserTurns(items: ResponsesInputItem[]): number {
+  let count = 0;
+  for (const item of items) {
+    if (item.role === "user" && !isResponsesBashResultUserItem(item)) count++;
+  }
+  return count;
+}
+
 /**
  * Observation masking for OpenAI/Codex Responses API payloads.
  *
@@ -135,7 +166,8 @@ function findResponsesTurnBoundary(items: ResponsesInputItem[], keepRecentTurns:
  */
 export function createResponsesInputObservationMask(keepRecentTurns: number = 8) {
   return (items: ResponsesInputItem[]): ResponsesInputItem[] => {
-    const boundary = findResponsesTurnBoundary(items, keepRecentTurns);
+    const totalTurns = countResponsesRealUserTurns(items);
+    const boundary = findResponsesTurnBoundary(items, quantizedKeepTurns(totalTurns, keepRecentTurns));
     if (boundary === 0) return items;
 
     return items.map((item, i) => {
@@ -219,3 +251,67 @@ export function truncateResponsesInputResultItems(items: ResponsesInputItem[], m
     return item;
   });
 }
+
+// GSD injects at most one context message per turn (memory/guided/forensics —
+// see buildContextMessage in bootstrap/system-context.ts), marked with
+// GSD_CONTEXT_MESSAGE_SENTINEL. convertToLlm strips the distinguishing
+// customType before the payload reaches this hook, so detection is by content
+// prefix instead. Pre-sentinel session history lacks the sentinel, so we also
+// match the stable *bracketed* GSD block labels those injections begin with,
+// letting resumed sessions dedupe older memory/guided blocks.
+//
+// Only GSD-specific bracketed markers belong here — never generic prose. A
+// message is dropped from the payload when it matches, so a natural-language
+// prefix (e.g. the forensics prompt "Debug GSD itself.") could silently delete
+// a real user message that happens to start the same way. Legacy forensics
+// injections without memory are therefore left un-deduped by design; those
+// with memory still match via the "[GSD Context Metadata]" wrapper.
+const LEGACY_GSD_CONTEXT_INJECTION_PREFIXES = [
+  "[GSD Context Metadata]",
+  "[MEMORY — Critical and prompt-relevant memories from the GSD memory store]",
+  "[GSD Guided Execute Context]",
+] as const;
+
+function isGsdContextInjectionText(text: string | undefined): boolean {
+  if (typeof text !== "string") return false;
+  if (text.startsWith(GSD_CONTEXT_MESSAGE_SENTINEL)) return true;
+  return LEGACY_GSD_CONTEXT_INJECTION_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+function isGsdContextInjectionMessage(m: MaskableMessage): boolean {
+  if (m.role !== "user") return false;
+  return isGsdContextInjectionText(firstTextFromContent(m.content));
+}
+
+/**
+ * Removes every GSD context-injection user message except the latest one.
+ * Each turn re-injects a near-identical memory/guided/forensics block; left
+ * in place they duplicate verbatim across an N-turn session. Removal (not
+ * masking) — an empty placeholder still costs tokens and shifts message
+ * positions, breaking cache byte-stability. Pure function: stored history is
+ * never mutated, only the outgoing payload array.
+ */
+export function filterSupersededContextInjections(messages: MaskableMessage[]): MaskableMessage[] {
+  let lastIndex = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (isGsdContextInjectionMessage(messages[i])) lastIndex = i;
+  }
+  if (lastIndex === -1) return messages;
+  return messages.filter((m, i) => i === lastIndex || !isGsdContextInjectionMessage(m));
+}
+
+function isResponsesGsdContextInjectionItem(item: ResponsesInputItem): boolean {
+  if (item.role !== "user") return false;
+  return isGsdContextInjectionText(firstTextFromContent(item.content));
+}
+
+export function filterSupersededResponsesContextInjections(
+  items: ResponsesInputItem[],
+): ResponsesInputItem[] {
+  let lastIndex = -1;
+  for (let i = 0; i < items.length; i++) {
+    if (isResponsesGsdContextInjectionItem(items[i])) lastIndex = i;
+  }
+  if (lastIndex === -1) return items;
+  return items.filter((item, i) => i === lastIndex || !isResponsesGsdContextInjectionItem(item));
+}

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

@@ -10,7 +10,7 @@
 // writer layer.
 import { createRequire } from "node:module";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "../errors.js";
 import type { GsdWorkspace, MilestoneScope } from "../workspace.js";
 import { logError, logWarning } from "../workflow-logger.js";
@@ -71,7 +71,10 @@ let _gsdRequire: ReturnType<typeof createRequire> | null | undefined;
 function getGsdRequire(): ReturnType<typeof createRequire> | null {
   if (_gsdRequire !== undefined) return _gsdRequire;
   try {
-    _gsdRequire = createRequire(import.meta.url);
+    // Next.js may emit this module into a CommonJS chunk. Avoid ESM-only module
+    // metadata syntax here; it is a hard parse error there.
+    const packageRoot = process.env.GSD_WEB_PACKAGE_ROOT || process.env.GSD_PKG_ROOT || process.cwd();
+    _gsdRequire = createRequire(resolve(packageRoot, "package.json"));
   } catch {
     _gsdRequire = null;
   }

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

@@ -357,6 +357,28 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `planning_subagents`: object — project-local widening for read-only planning subagent dispatch. Supported unit keys are `plan-milestone` and `plan-slice`; each has:
+  - `allowed`: string[] — additional planning-safe agents for that unit.
+
+  Agents must already be classified by GSD as read-only planning specialists: `mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the global read-only registry, and agents not listed for the active unit.
+
+  Example:
+
+  ```yaml
+  planning_subagents:
+    plan-milestone:
+      allowed:
+        - scout
+        - planner
+        - security
+    plan-slice:
+      allowed:
+        - scout
+        - planner
+        - reviewer
+        - security
+  ```
+
   **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
 
 - `experimental`: opt-in experimental features. All features here are **off by default** — you must explicitly set each one to `true` to enable it. Features in this block may change or be removed without a deprecation cycle while in experimental status. Keys:

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -15,13 +15,13 @@ import {
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import {
-  buildTaskFileName,
   gsdProjectionRoot,
   gsdRoot,
   resolveGsdPathContract,
   resolveMilestoneFile,
   resolveMilestonePath,
   resolveSliceFile,
+  resolveTaskFile,
 } from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -95,6 +95,25 @@ function reportCheckboxDbStatusDivergence(
   });
 }
 
+function bareDuplicateMilestoneId(milestoneId: string): string | null {
+  const match = milestoneId.match(/^(M\d{3})-[a-z0-9]{6}$/i);
+  return match?.[1]?.toUpperCase() ?? null;
+}
+
+function checkboxDbStatusMilestoneIds(basePath: string, milestoneIds: string[]): string[] {
+  if (!hasFlatPhaseLayout(basePath)) return milestoneIds;
+
+  // Flat-phase directories are keyed by phase number. A restored
+  // M003-xxxxxx row alongside M003 is a stale duplicate for the same
+  // phases/03-* projection, so checking both can compare DB status against two
+  // competing PLAN files and report a persistent false divergence.
+  const allIds = new Set(milestoneIds.map((id) => id.toUpperCase()));
+  return milestoneIds.filter((milestoneId) => {
+    const bareId = bareDuplicateMilestoneId(milestoneId);
+    return !bareId || !allIds.has(bareId);
+  });
+}
+
 function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
   for (const milestoneId of milestoneIds) {
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
@@ -208,10 +227,8 @@ function resolveFlatPhaseArtifactDiskPath(basePath: string, row: ArtifactRow): s
   if (!artifactType) return null;
 
   if (row.slice_id && row.task_id) {
-    const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
-    if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir)) return null;
-    const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
-    return existsSync(candidate) ? candidate : null;
+    const candidate = resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, artifactType);
+    return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
   }
 
   const candidate = row.slice_id
@@ -436,7 +453,9 @@ function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, a
 
 function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
   const issuePath = artifactPathRelativeToGsd(row.path);
-  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) &&
+    (hasPresentFlatPhaseReplacement(basePath, row, artifactRows) ||
+      hasPresentMilestonesReplacement(basePath, row, artifactRows));
 }
 
 function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
@@ -809,7 +828,11 @@ export async function checkEngineHealth(
   // block doctor.
   try {
     if (isDbAvailable()) {
-      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+      checkProjectionCheckboxDbStatus(
+        basePath,
+        checkboxDbStatusMilestoneIds(basePath, getAllMilestones().map((milestone) => milestone.id)),
+        issues,
+      );
     }
   } catch {
     // Non-fatal: checkbox-vs-DB divergence check must never block doctor

package/src/resources/extensions/gsd/error-classifier.ts

@@ -65,8 +65,12 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528
 const SERVER_RE = /internal(?: server)?[ _-]?error|server[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+// Provider adapters throw this when an upstream stop reason reaches Pi before
+// the adapter knows how to map it. Keep the match scoped so plain "unknown"
+// runtime errors still pause for inspection instead of being retried forever.
+const PROVIDER_STOP_REASON_RE = /unhandled stop reason:\s*(?:abort|unknown)\b/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|\babort\b|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
@@ -103,7 +107,7 @@ const UNSUPPORTED_MODEL_SCOPE_RE = /\b(?:account|plan|tier|subscription)\b/i;
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)
- *  6. Connection (terminated, ECONNREFUSED, EPIPE, other side closed)
+ *  6. Connection (terminated, abort/unknown stop reason, ECONNREFUSED, EPIPE, other side closed)
  *  7. Model error (400 invalid argument / payload rejected for this model)
  *  8. Unknown
  */
@@ -163,6 +167,13 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "rate-limit", retryAfterMs: delayMs };
   }
 
+  // Provider stop-reason adapter gaps are usually request/stream failures from
+  // the current model. Treat the scoped adapter message as fallback-eligible,
+  // but keep generic unknown errors on the indefinite pause path.
+  if (PROVIDER_STOP_REASON_RE.test(errorMsg)) {
+    return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
   // 3. Network errors — same-model retry candidate
   if (NETWORK_RE.test(errorMsg)) {
     // Exclude if also matches permanent signals (already handled above for

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -111,6 +111,7 @@ export const EXEC_DEFAULTS = {
     "LOGNAME",
     "TMPDIR",
     "NODE_OPTIONS",
+    "NODE_PATH",
     "PYTHONPATH",
     "PYTHONIOENCODING",
   ] as const,

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -155,6 +155,19 @@ function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
   return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
 
+function removeFlatProjectionBackup(backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  try {
+    removePathWithRetries(phaseBackupDir);
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${(err as Error).message}`,
+    );
+  }
+}
+
 function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
   const phaseBackupDir = join(backupDir, "__phases");
   if (!existsSync(phaseBackupDir)) return;
@@ -494,4 +507,5 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
     );
   }
+  removeFlatProjectionBackup(backupDir);
 }

package/src/resources/extensions/gsd/git-service.ts

@@ -385,10 +385,16 @@ const runtimeFilesCleanedUpRepos = new Set<string>();
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 
 /**
- * Path to the milestone metadata file that stores the integration branch.
- * Format: .gsd/milestones/<MID>/<MID>-META.json
+ * Path to the milestone integration-branch metadata file.
+ * Format: .gsd/<MID>-META.json  (deliberately OUTSIDE milestones/<MID>/ so it
+ * cannot poison isLegacyMilestonesLayout — see ADR-045).
  */
-function milestoneMetaPath(basePath: string, milestoneId: string): string {
+export function milestoneMetaPath(basePath: string, milestoneId: string): string {
+  return join(gsdRoot(basePath), `${milestoneId}-META.json`);
+}
+
+/** Legacy location (pre-ADR-045). Read-only fallback for existing on-disk trees. */
+function legacyMilestoneMetaPath(basePath: string, milestoneId: string): string {
   return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 
@@ -398,8 +404,12 @@ function milestoneMetaPath(basePath: string, milestoneId: string): string {
  */
 export function readIntegrationBranch(basePath: string, milestoneId: string): string | null {
   try {
-    const metaFile = milestoneMetaPath(basePath, milestoneId);
-    if (!existsSync(metaFile)) return null;
+    let metaFile = milestoneMetaPath(basePath, milestoneId);
+    if (!existsSync(metaFile)) {
+      const legacy = legacyMilestoneMetaPath(basePath, milestoneId);
+      if (!existsSync(legacy)) return null;
+      metaFile = legacy;
+    }
     const data = JSON.parse(readFileSync(metaFile, "utf-8"));
     const branch = data?.integrationBranch;
     if (typeof branch === "string" && branch.trim() !== "" && VALID_BRANCH_NAME.test(branch)) {
@@ -451,7 +461,10 @@ export function writeIntegrationBranch(
   if (existingBranch === branch) return;
 
   const metaFile = milestoneMetaPath(basePath, milestoneId);
-  mkdirSync(join(gsdRoot(basePath), "milestones", milestoneId), { recursive: true });
+  // Ensure the flat .gsd/ root exists (never milestones/<MID>/ — that would
+  // poison layout detection, ADR-045). In production .gsd/ already exists; this
+  // guards fresh trees so the write below can't ENOENT.
+  mkdirSync(gsdRoot(basePath), { recursive: true });
 
   // Merge with existing metadata if present
   let existing: Record<string, unknown> = {};

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

@@ -67,6 +67,13 @@ export type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 
 import { TERMINAL_STATUS_SQL } from "./db/sql-constants.js";
 import { applyStatusTransition } from "./db/writers/status.js";
+import {
+  LAYOUT_SEGMENTS,
+  derivePhaseSlug,
+  milestoneIdToPhaseNum,
+  milestoneIdUniqueSuffix,
+  phaseDirName,
+} from "./layout-policy.js";
 
 export function insertDecision(d: Omit<Decision, "seq">): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -206,6 +213,47 @@ export function insertArtifact(a: {
   });
 }
 
+function canonicalPhaseDirNameForDb(milestoneId: string, title: string): string {
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const slug = derivePhaseSlug(title || milestoneId);
+  const suffix = milestoneIdUniqueSuffix(milestoneId);
+  return phaseDirName(phaseNum, suffix ? `${suffix}-${slug}` : slug);
+}
+
+function reconcileMilestonePhaseArtifactPaths(milestoneId: string, title: string): void {
+  const db = getDbOrNull()!;
+  const phaseNumPrefix = String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0");
+  const canonicalDir = canonicalPhaseDirNameForDb(milestoneId, title);
+  const staleRows = db.prepare(
+    `SELECT path
+       FROM artifacts
+      WHERE milestone_id = :milestone_id
+        AND path LIKE :phase_prefix`,
+  ).all({
+    ":milestone_id": milestoneId,
+    ":phase_prefix": `${LAYOUT_SEGMENTS.level1}/${phaseNumPrefix}-%/%`,
+  }) as Array<{ path: string }>;
+
+  const updatePath = db.prepare("UPDATE artifacts SET path = :new_path WHERE path = :old_path");
+  const deletePath = db.prepare("DELETE FROM artifacts WHERE path = :path");
+  const existingPath = db.prepare("SELECT 1 AS present FROM artifacts WHERE path = :path");
+
+  for (const row of staleRows) {
+    const parts = row.path.split("/");
+    if (parts.length < 3) continue;
+    if (parts[0] !== LAYOUT_SEGMENTS.level1) continue;
+    if (parts[1] === canonicalDir) continue;
+    if (!parts[1]?.startsWith(`${phaseNumPrefix}-`)) continue;
+
+    const newPath = [LAYOUT_SEGMENTS.level1, canonicalDir, ...parts.slice(2)].join("/");
+    if (existingPath.get({ ":path": newPath })) {
+      deletePath.run({ ":path": row.path });
+      continue;
+    }
+    updatePath.run({ ":new_path": newPath, ":old_path": row.path });
+  }
+}
+
 export interface MilestonePlanningRecord {
   vision: string;
   successCriteria: string[];
@@ -287,39 +335,43 @@ export function insertMilestone(m: {
 
 export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string; depends_on?: string[] }): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.prepare(
-    `UPDATE milestones SET
-      title = COALESCE(NULLIF(:title, ''), title),
-      status = COALESCE(NULLIF(:status, ''), status),
-      depends_on = COALESCE(:depends_on, depends_on),
-      vision = COALESCE(:vision, vision),
-      success_criteria = COALESCE(:success_criteria, success_criteria),
-      key_risks = COALESCE(:key_risks, key_risks),
-      proof_strategy = COALESCE(:proof_strategy, proof_strategy),
-      verification_contract = COALESCE(:verification_contract, verification_contract),
-      verification_integration = COALESCE(:verification_integration, verification_integration),
-      verification_operational = COALESCE(:verification_operational, verification_operational),
-      verification_uat = COALESCE(:verification_uat, verification_uat),
-      definition_of_done = COALESCE(:definition_of_done, definition_of_done),
-      requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
-      boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
-     WHERE id = :id`,
-  ).run({
-    ":id": milestoneId,
-    ":title": planning.title ?? "",
-    ":status": planning.status ?? "",
-    ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
-    ":vision": planning.vision ?? null,
-    ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
-    ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
-    ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
-    ":verification_contract": planning.verificationContract ?? null,
-    ":verification_integration": planning.verificationIntegration ?? null,
-    ":verification_operational": planning.verificationOperational ?? null,
-    ":verification_uat": planning.verificationUat ?? null,
-    ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
-    ":requirement_coverage": planning.requirementCoverage ?? null,
-    ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+  transaction(() => {
+    getDbOrNull()!.prepare(
+      `UPDATE milestones SET
+        title = COALESCE(NULLIF(:title, ''), title),
+        status = COALESCE(NULLIF(:status, ''), status),
+        depends_on = COALESCE(:depends_on, depends_on),
+        vision = COALESCE(:vision, vision),
+        success_criteria = COALESCE(:success_criteria, success_criteria),
+        key_risks = COALESCE(:key_risks, key_risks),
+        proof_strategy = COALESCE(:proof_strategy, proof_strategy),
+        verification_contract = COALESCE(:verification_contract, verification_contract),
+        verification_integration = COALESCE(:verification_integration, verification_integration),
+        verification_operational = COALESCE(:verification_operational, verification_operational),
+        verification_uat = COALESCE(:verification_uat, verification_uat),
+        definition_of_done = COALESCE(:definition_of_done, definition_of_done),
+        requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
+        boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
+       WHERE id = :id`,
+    ).run({
+      ":id": milestoneId,
+      ":title": planning.title ?? "",
+      ":status": planning.status ?? "",
+      ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
+      ":vision": planning.vision ?? null,
+      ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
+      ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
+      ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
+      ":verification_contract": planning.verificationContract ?? null,
+      ":verification_integration": planning.verificationIntegration ?? null,
+      ":verification_operational": planning.verificationOperational ?? null,
+      ":verification_uat": planning.verificationUat ?? null,
+      ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
+      ":requirement_coverage": planning.requirementCoverage ?? null,
+      ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+    });
+    const finalTitle = planning.title?.trim();
+    if (finalTitle) reconcileMilestonePhaseArtifactPaths(milestoneId, finalTitle);
   });
 }
 

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

@@ -26,6 +26,7 @@ import {
   buildPlanMilestonePrompt,
   buildPlanSlicePrompt,
   buildSkillActivationBlock,
+  capPreamble,
 } from "./auto-prompts.js";
 import { deriveState, isGhostMilestone } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
@@ -1199,7 +1200,9 @@ function resolveDiscussSliceBasePath(basePath: string, milestoneId: string): str
  * slice summaries so the agent can ask grounded UX/behaviour questions
  * without wasting a turn reading files.
  */
-async function buildDiscussSlicePrompt(
+// Exported for tests (`prompt-budget-enforcement.test.ts`) — verifies the
+// inlined-context cap. Not part of the public flow surface otherwise.
+export async function buildDiscussSlicePrompt(
   mid: string,
   sid: string,
   sTitle: string,
@@ -1262,8 +1265,12 @@ async function buildDiscussSlicePrompt(
     }
   }
 
+  // Cap the inlined block: it grows unbounded with each completed slice's full
+  // SUMMARY. `capPreamble` truncates at `### ` section boundaries — roadmap and
+  // milestone context come first (survive), completed-slice summaries come last
+  // (dropped first) when the executor's window can't hold everything.
   const inlinedContext = inlined.length > 0
-    ? `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`
+    ? capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`)
     : `## Inlined Context\n\n_(no context files found yet — go in blind and ask broad questions)_`;
 
   const sliceDirPath = `.gsd/milestones/${mid}/slices/${sid}`;
@@ -1275,7 +1282,7 @@ async function buildDiscussSlicePrompt(
     : "";
 
   const inlinedTemplates = inlineTemplate("slice-context", "Slice Context");
-  return loadPrompt("guided-discuss-slice", {
+  return prependLanguageDirective(base, loadPrompt("guided-discuss-slice", {
     milestoneId: mid,
     sliceId: sid,
     sliceTitle: sTitle,
@@ -1286,7 +1293,7 @@ async function buildDiscussSlicePrompt(
     inlinedTemplates,
     structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false",
     commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`),
-  });
+  }));
 }
 
 /**

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -12,7 +12,7 @@
 import { readFileSync, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
-import { dirname, join, relative } from "node:path";
+import { dirname, join } from "node:path";
 import {
   getAllMilestones,
   getMilestone,
@@ -40,6 +40,7 @@ import {
   resolveTasksDir,
   targetMilestoneFile,
   targetSliceFile,
+  targetTaskFile,
   gsdProjectionRoot,
   gsdRoot,
   buildTaskFileName,
@@ -49,7 +50,7 @@ import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.j
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, resolveMilestonePath, relSliceFile, canonicalPhaseDirName } from "./paths.js";
-import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./compat/compat-marker.js";
+import { readCompatMarker, writeCompatMarker, computeProjectionSha, deriveCompatProjectionKey } from "./compat/compat-marker.js";
 import type { RiskLevel } from "./types.js";
 import {
   phaseDirName,
@@ -108,13 +109,7 @@ function flushProjectionWritesToMarker(): void {
  */
 function toArtifactPath(absPath: string, basePath: string): string {
   const projectionRoot = gsdProjectionRoot(basePath);
-  const projectionRel = relative(projectionRoot, absPath);
-  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
-    ? projectionRoot
-    : gsdRoot(basePath);
-  const rel = relative(root, absPath);
-  // Normalize to forward slashes for consistent DB keys
-  return rel.replace(/\\/g, "/");
+  return deriveCompatProjectionKey(absPath, [projectionRoot, gsdRoot(basePath)]);
 }
 
 /**
@@ -756,20 +751,7 @@ export async function renderTaskSummary(
     return false; // No summary to render — skip silently
   }
 
-  // Resolve the tasks directory, creating path if needed
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!slicePath) {
-    process.stderr.write(
-      `markdown-renderer: cannot resolve slice path for ${milestoneId}/${sliceId}\n`,
-    );
-    return false;
-  }
-
-  // Use the tasks/ subdir when it exists (legacy layout), otherwise use the
-  // slice path directly (flat-phase: task summaries live alongside plan files).
-  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId) ?? slicePath;
-  const fileName = buildTaskFileName(taskId, "SUMMARY");
-  const absPath = join(tasksDir, fileName);
+  const absPath = targetTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY", getMilestone(milestoneId)?.title);
   const artifactPath = toArtifactPath(absPath, basePath);
 
   await writeAndStore(absPath, artifactPath, task.full_summary_md, {