@opengsd/gsd-pi 1.8.1-dev.897b3c90 → 1.9.0-dev.5c1a3ff2

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/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";
@@ -208,10 +208,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

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/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}`;

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

@@ -40,6 +40,7 @@ import {
   resolveTasksDir,
   targetMilestoneFile,
   targetSliceFile,
+  targetTaskFile,
   gsdProjectionRoot,
   gsdRoot,
   buildTaskFileName,
@@ -756,20 +757,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, {

package/src/resources/extensions/gsd/md-importer.ts

@@ -31,6 +31,7 @@ import {
   legacyMilestonesDir,
   gsdRoot,
   resolveTaskFiles,
+  resolveTaskFile,
   resolveMilestonePath,
 } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
@@ -925,8 +926,7 @@ export function migrateHierarchyToDb(
           legacyTasksDir = isLegacySlice
             ? resolveTasksDir(basePath, milestoneId, sliceEntry.id)
             : null;
-          const summaryDir = legacyTasksDir ?? slicePath;
-          taskSummaryFile = join(summaryDir, `${taskEntry.id}-SUMMARY.md`);
+          taskSummaryFile = resolveTaskFile(basePath, milestoneId, sliceEntry.id, taskEntry.id, 'SUMMARY');
         }
         const hasTaskSummary = taskSummaryFile !== null && existsSync(taskSummaryFile);
 
@@ -950,9 +950,9 @@ export function migrateHierarchyToDb(
         // first execute-task. The surviving SUMMARY wins over a stale checkbox.
         // reopen-task removes the SUMMARY, so this never re-completes an
         // intentionally reopened task.
-        // Flat-phase summaries are phase-scoped (T01-SUMMARY.md); when a milestone
-        // has multiple slices, require the summary parent frontmatter to match so
-        // one slice's completion does not attest a sibling's same-named task.
+        // Flat-phase summaries are phase-scoped; when a milestone has multiple
+        // slices, require the summary parent frontmatter to match so one slice's
+        // completion does not attest a sibling's same-named task.
         let summaryAttestsCompletion = hasTaskSummary;
         if (summaryAttestsCompletion && !isLegacySlice && roadmap.slices.length > 1 && taskSummaryFile) {
           try {

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -62,6 +62,8 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   // GPT-5.5 API list price, also used for live Codex OAuth routing.
   // Source: https://openai.com/api/pricing/
   { id: "gpt-5.5", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-04-23" },
+  // Mirrors gpt-5.5 list pricing until OpenAI publishes official gpt-5.6 pricing.
+  { id: "gpt-5.6", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-07-08" },
 
   // Google
   { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/src/resources/extensions/gsd/model-router.ts

@@ -111,10 +111,12 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "gpt-5.3-codex": "heavy",
   "gpt-5.4": "heavy",
   "gpt-5.5": "heavy",
+  "gpt-5.6": "heavy",
   "o1": "heavy",
   "o3": "heavy",
   "o4-mini": "heavy",
   "o4-mini-deep-research": "heavy",
+  "grok-4.5": "heavy",
 };
 
 // ─── Cost Table (per 1K input tokens, approximate USD) ───────────────────────
@@ -149,11 +151,13 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "gpt-5.3-codex-spark": 0.0003,
   "gpt-5.4": 0.005,
   "gpt-5.5": 0.005,
+  "gpt-5.6": 0.005,
   "o4-mini": 0.005,
   "o4-mini-deep-research": 0.005,
   "gemini-2.0-flash": 0.0001,
   "gemini-2.5-pro": 0.00125,
   "deepseek-chat": 0.00014,
+  "grok-4.5": 0.002,
 };
 
 // ─── Capability Profiles Data Table ──────────────────────────────────────────
@@ -198,6 +202,9 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   // OpenAI's 2026-04-23 published eval deltas across coding, tool use, and long context.
   // Source: https://openai.com/index/introducing-gpt-5-5/
   "gpt-5.5":                      { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 42, longContext: 90, instruction: 93 },
+  // GPT-5.6 profile is provisional: a small uniform step over gpt-5.5, to be
+  // recalibrated once OpenAI publishes official eval results.
+  "gpt-5.6":                      { coding: 97, debugging: 94, research: 90, reasoning: 96, speed: 42, longContext: 91, instruction: 94 },
 
   // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
   "o1":                           { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
@@ -212,6 +219,11 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
 
   // ── DeepSeek ───────────────────────────────────────────────────────────────
   "deepseek-chat":                { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 },
+
+  // ── xAI ────────────────────────────────────────────────────────────────────
+  // Grok 4.5 (2026-07): Opus-class frontier model tuned for coding and agentic
+  // work; notably faster and more token-efficient than peer heavy models.
+  "grok-4.5":                     { coding: 95, debugging: 90, research: 82, reasoning: 93, speed: 55, longContext: 80, instruction: 90 },
 };
 
 // ─── Base Task Requirements Data Table ───────────────────────────────────────

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

@@ -223,6 +223,26 @@ export function buildTaskFileName(taskId: string, suffix: string): string {
   return `${taskId}-${suffix}.md`;
 }
 
+/**
+ * Build a flat-phase task artifact file name.
+ * ("S06", "T03", "SUMMARY") → "S06-T03-SUMMARY.md"
+ */
+export function buildFlatTaskFileName(sliceId: string, taskId: string, suffix: string): string {
+  return `${sliceId}-${taskId}-${suffix}.md`;
+}
+
+/**
+ * Extract the task ID from a task artifact filename.
+ * Supports flat-phase S##-T##-SUFFIX.md plus legacy T##-SUFFIX.md and
+ * T##-DESCRIPTOR-SUFFIX.md names.
+ */
+export function taskIdFromTaskFileName(fileName: string, suffix: string): string | null {
+  const flat = new RegExp(`^S\\d+-(T\\d+)-${suffix}\\.md$`, "i").exec(fileName);
+  if (flat?.[1]) return flat[1].toUpperCase();
+  const legacy = new RegExp(`^(T\\d+)(?:-.*)?-${suffix}\\.md$`, "i").exec(fileName);
+  return legacy?.[1]?.toUpperCase() ?? null;
+}
+
 // ─── Resolvers ─────────────────────────────────────────────────────────────
 
 /**
@@ -284,18 +304,15 @@ export function resolveFile(dir: string, idPrefix: string, suffix: string): stri
 }
 
 /**
- * Find all task files matching a pattern in a tasks directory.
- * Returns sorted file names matching T##-SUFFIX.md or legacy T##-*-SUFFIX.md
+ * Find all task files matching a pattern in a tasks directory or flat phase dir.
+ * Returns sorted file names matching S##-T##-SUFFIX.md, T##-SUFFIX.md,
+ * or legacy T##-*-SUFFIX.md.
  */
 export function resolveTaskFiles(tasksDir: string, suffix: string): string[] {
   if (!existsSync(tasksDir)) return [];
   try {
-    // Current convention: T01-PLAN.md
-    const currentPattern = new RegExp(`^T\\d+-${suffix}\\.md$`, "i");
-    // Legacy convention: T01-INSTALL-PACKAGES-PLAN.md
-    const legacyPattern = new RegExp(`^T\\d+-.*-${suffix}\\.md$`, "i");
     return cachedReaddir(tasksDir)
-      .filter(f => currentPattern.test(f) || legacyPattern.test(f))
+      .filter(f => taskIdFromTaskFileName(f, suffix) !== null)
       .sort();
   } catch {
     return [];
@@ -931,8 +948,10 @@ export function resolveTaskFile(
   const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
 
   if (suffix !== "PLAN" && !isLegacy) {
-    const flatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
-    return existsSync(flatPath) ? flatPath : null;
+    const flatPath = join(phaseDir, buildFlatTaskFileName(sliceId, taskId, suffix));
+    if (existsSync(flatPath)) return flatPath;
+    const legacyFlatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
+    return existsSync(legacyFlatPath) ? legacyFlatPath : null;
   }
 
   const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
@@ -1066,6 +1085,35 @@ export function targetSliceFile(
   return join(dir, fileName);
 }
 
+/**
+ * Build the canonical absolute write target for a task file.
+ * Readers that need legacy flat-phase fallback should call resolveTaskFile.
+ */
+export function targetTaskFile(
+  basePath: string, milestoneId: string, sliceId: string,
+  taskId: string, suffix: string, milestoneTitle?: string
+): string {
+  if (suffix === "PLAN") {
+    return targetSliceFile(basePath, milestoneId, sliceId, "PLAN", milestoneTitle);
+  }
+
+  const mDir = resolveMilestonePath(basePath, milestoneId);
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacy = mDir
+    ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
+    : isLegacyMilestonesLayout(basePath);
+  const milestoneDir = mDir
+    ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestoneTitle));
+
+  if (isLegacy) {
+    const slicesDir = join(milestoneDir, "slices");
+    const sliceDir = join(slicesDir, resolveDir(slicesDir, sliceId) ?? sliceId);
+    return join(sliceDir, "tasks", buildTaskFileName(taskId, suffix));
+  }
+
+  return join(milestoneDir, buildFlatTaskFileName(sliceId, taskId, suffix));
+}
+
 /**
  * Build relative .gsd/ path to a slice file.
  * Preserves an existing compatibility filename when present; otherwise falls
@@ -1105,5 +1153,5 @@ export function relTaskFile(
     return relSliceFile(basePath, milestoneId, sliceId, "PLAN");
   }
   const relS = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
-  return `${relS}/${buildTaskFileName(taskId, suffix)}`;
+  return `${relS}/${buildFlatTaskFileName(sliceId, taskId, suffix)}`;
 }

package/src/resources/extensions/gsd/planning-subagent-policy.ts

@@ -0,0 +1,58 @@
+import { CONFIGURABLE_PLANNING_SUBAGENT_UNITS, type GSDPreferences } from "./preferences-types.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import type { ToolsPolicy } from "./unit-context-manifest.js";
+
+const CONFIGURABLE_UNITS = new Set<string>(CONFIGURABLE_PLANNING_SUBAGENT_UNITS);
+
+function configuredAllowedSubagents(
+  unitType: string,
+  preferences: GSDPreferences | null | undefined,
+): readonly string[] {
+  if (!CONFIGURABLE_UNITS.has(unitType)) return [];
+  return preferences?.planning_subagents?.[
+    unitType as keyof NonNullable<GSDPreferences["planning_subagents"]>
+  ]?.allowed ?? [];
+}
+
+function mergeAllowedSubagents(
+  current: readonly string[],
+  configured: readonly string[],
+): readonly string[] {
+  return Array.from(new Set([...current, ...configured]));
+}
+
+export function applyPlanningSubagentPreferences(
+  unitType: string,
+  policy: ToolsPolicy | null | undefined,
+  preferences: GSDPreferences | null | undefined,
+): ToolsPolicy | null | undefined {
+  if (!policy) return policy;
+  const configured = configuredAllowedSubagents(unitType, preferences);
+  if (configured.length === 0) return policy;
+
+  if (policy.mode === "planning") {
+    return {
+      mode: "planning-dispatch",
+      allowedSubagents: mergeAllowedSubagents([], configured),
+    };
+  }
+
+  if (policy.mode === "planning-dispatch") {
+    return {
+      ...policy,
+      allowedSubagents: mergeAllowedSubagents(policy.allowedSubagents, configured),
+    };
+  }
+
+  return policy;
+}
+
+export function resolveEffectivePlanningToolsPolicy(
+  unitType: string,
+  policy: ToolsPolicy | null | undefined,
+  basePath?: string,
+): ToolsPolicy | null | undefined {
+  if (!basePath) return policy;
+  const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+  return applyPlanningSubagentPreferences(unitType, policy, preferences);
+}

package/src/resources/extensions/gsd/planning-subagent-registry.ts

@@ -0,0 +1,31 @@
+/**
+ * Read-only planning specialists that controlled planning dispatch may use.
+ *
+ * Unit manifests and project preferences still declare per-unit subsets. This
+ * registry is the global safety classification checked by the write gate and
+ * preference validation before any configured planning allowlist takes effect.
+ */
+
+const PLANNING_DISPATCH_AGENT_REGISTRY = {
+  mnemo: { readOnlySpecialist: true },
+  scout: { readOnlySpecialist: true },
+  planner: { readOnlySpecialist: true },
+  reviewer: { readOnlySpecialist: true },
+  security: { readOnlySpecialist: true },
+  tester: { readOnlySpecialist: true },
+} as const satisfies Record<string, { readonly readOnlySpecialist: boolean }>;
+
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
+  Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId),
+);
+
+export function isReadOnlyPlanningDispatchAgent(agentId: string): boolean {
+  const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
+  return metadata?.readOnlySpecialist === true;
+}
+
+export function allowedPlanningDispatchAgentsList(): string {
+  return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}

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

@@ -141,6 +141,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "planning_subagents",
   "dynamic_routing",
   "disabled_model_providers",
   "uok",
@@ -217,6 +218,20 @@ export const KNOWN_UNIT_LABELS = [
 ] as const;
 export type UnitLabel = (typeof KNOWN_UNIT_LABELS)[number];
 
+export const CONFIGURABLE_PLANNING_SUBAGENT_UNITS = [
+  "plan-milestone",
+  "plan-slice",
+] as const;
+export type ConfigurablePlanningSubagentUnit = (typeof CONFIGURABLE_PLANNING_SUBAGENT_UNITS)[number];
+
+export interface PlanningSubagentUnitConfig {
+  allowed?: string[];
+}
+
+export type PlanningSubagentsConfig = Partial<
+  Record<ConfigurablePlanningSubagentUnit, PlanningSubagentUnitConfig>
+>;
+
 
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
@@ -476,6 +491,7 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  planning_subagents?: PlanningSubagentsConfig;
   dynamic_routing?: DynamicRoutingConfig;
   /** Provider IDs to exclude from /model and automatic model routing while leaving tool auth intact. */
   disabled_model_providers?: string[];