@opengsd/gsd-pi 1.9.0 → 1.10.0-dev.a5e42e99

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

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

@@ -12,6 +12,12 @@ export interface ModelCostEntry {
   inputPer1k: number;
   /** Approximate cost per 1K output tokens in USD */
   outputPer1k: number;
+  /** Input-token-based long-context pricing tiers, when published */
+  tiers?: Array<{
+    inputTokensAbove: number;
+    inputPer1k: number;
+    outputPer1k: number;
+  }>;
   /** Last updated date */
   updatedAt: string;
 }
@@ -62,6 +68,9 @@ 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" },
+  { id: "gpt-5.6-sol", inputPer1k: 0.005, outputPer1k: 0.03, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.01, outputPer1k: 0.045 }], updatedAt: "2026-07-11" },
+  { id: "gpt-5.6-terra", inputPer1k: 0.0025, outputPer1k: 0.015, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.005, outputPer1k: 0.0225 }], updatedAt: "2026-07-11" },
+  { id: "gpt-5.6-luna", inputPer1k: 0.001, outputPer1k: 0.006, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.002, outputPer1k: 0.009 }], updatedAt: "2026-07-11" },
 
   // Google
   { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },
@@ -78,7 +87,11 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
 export function lookupModelCost(modelId: string): ModelCostEntry | undefined {
   const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
   return BUNDLED_COST_TABLE.find(e => e.id === bareId)
-    ?? BUNDLED_COST_TABLE.find(e => bareId.includes(e.id) || e.id.includes(bareId));
+    ?? BUNDLED_COST_TABLE.find(e =>
+      bareId.startsWith(`${e.id}-`) ||
+      bareId.startsWith(`${e.id}:`) ||
+      bareId.startsWith(`${e.id}@`)
+    );
 }
 
 /**

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

@@ -111,10 +111,14 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "gpt-5.3-codex": "heavy",
   "gpt-5.4": "heavy",
   "gpt-5.5": "heavy",
+  "gpt-5.6-sol": "heavy",
+  "gpt-5.6-terra": "heavy",
+  "gpt-5.6-luna": "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 +153,15 @@ 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-sol": 0.005,
+  "gpt-5.6-terra": 0.0025,
+  "gpt-5.6-luna": 0.001,
   "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 +206,10 @@ 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 profiles are provisional until official eval results are available.
+  "gpt-5.6-sol":                  { coding: 97, debugging: 94, research: 90, reasoning: 96, speed: 42, longContext: 91, instruction: 94 },
+  "gpt-5.6-terra":                { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 48, longContext: 91, instruction: 93 },
+  "gpt-5.6-luna":                 { coding: 92, debugging: 88, research: 84, reasoning: 91, speed: 72, longContext: 91, instruction: 90 },
 
   // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
   "o1":                           { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
@@ -212,6 +224,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

@@ -136,6 +136,14 @@ function cachedReaddir(dirPath: string): string[] {
   return entries;
 }
 
+function isExistingFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Clear the volatile directory listing caches.
  * Call after milestone transitions, file creation in planning directories,
@@ -223,6 +231,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 ─────────────────────────────────────────────────────────────
 
 /**
@@ -264,7 +292,7 @@ export function resolveFile(dir: string, idPrefix: string, suffix: string): stri
   if (!existsSync(dir)) return null;
   const target = `${idPrefix}-${suffix}.md`.toUpperCase();
   try {
-    const entries = cachedReaddir(dir);
+    const entries = cachedReaddirWithTypes(dir).filter(e => e.isFile()).map(e => e.name);
     // Direct match: ID-SUFFIX.md
     const direct = entries.find(e => e.toUpperCase() === target);
     if (direct) return direct;
@@ -284,18 +312,17 @@ 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))
+    return cachedReaddirWithTypes(tasksDir)
+      .filter(e => e.isFile())
+      .map(e => e.name)
+      .filter(f => taskIdFromTaskFileName(f, suffix) !== null)
       .sort();
   } catch {
     return [];
@@ -843,7 +870,7 @@ export function resolveMilestoneFile(
   const prefix = `${String(phaseNum).padStart(2, "0")}`;
   const flatName = `${prefix}-${suffix}.md`;
   const flatPath = join(mDir, flatName);
-  if (existsSync(flatPath)) return flatPath;
+  if (isExistingFile(flatPath)) return flatPath;
   // Legacy fallback: M001-SUFFIX.md
   const file = resolveFile(mDir, milestoneId, suffix);
   return file ? join(mDir, file) : null;
@@ -878,11 +905,11 @@ export function resolveSliceFile(
   const planNum = sliceIdToPlanNum(sliceId);
   const flatName = planFileName(phaseNum, planNum, suffix);
   const flatPath = join(phaseDir, flatName);
-  if (existsSync(flatPath)) return flatPath;
+  if (isExistingFile(flatPath)) return flatPath;
   // Also check plan-number-only format MM-SUFFIX.md (written by buildSliceFileName)
   const planOnlyName = `${String(planNum).padStart(2, "0")}-${suffix}.md`;
   const planOnlyPath = join(phaseDir, planOnlyName);
-  if (existsSync(planOnlyPath)) return planOnlyPath;
+  if (isExistingFile(planOnlyPath)) return planOnlyPath;
   // Try prefix match for the phase+plan number (handles suffix variations)
   const planPrefix = `${String(phaseNum).padStart(2, "0")}-${String(planNum).padStart(2, "0")}-`;
   try {
@@ -931,8 +958,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 (isExistingFile(flatPath)) return flatPath;
+    const legacyFlatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
+    return isExistingFile(legacyFlatPath) ? legacyFlatPath : null;
   }
 
   const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
@@ -1066,6 +1095,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 +1163,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,45 @@
+/**
+ * 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.
+ */
+
+import type { PlanningSubagentRegistryConfig } from "./preferences-types.js";
+
+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),
+);
+
+function configuredPlanningDispatchAgents(registry?: PlanningSubagentRegistryConfig): string[] {
+  return Object.entries(registry ?? {})
+    .filter(([, metadata]) => metadata.read_only_specialist === true)
+    .map(([agentId]) => agentId);
+}
+
+export function isReadOnlyPlanningDispatchAgent(
+  agentId: string,
+  registry?: PlanningSubagentRegistryConfig,
+): boolean {
+  const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
+  return metadata?.readOnlySpecialist === true || registry?.[agentId]?.read_only_specialist === true;
+}
+
+export function allowedPlanningDispatchAgentsList(registry?: PlanningSubagentRegistryConfig): string {
+  return Array.from(new Set([
+    ...ALLOWED_PLANNING_DISPATCH_AGENTS,
+    ...configuredPlanningDispatchAgents(registry),
+  ])).join(", ");
+}